paster make-index my.ini -f

The ``--repo-location`` option allows the location of the repositories to be overridden;

usually, the location is retrieved from the Kallithea database.

The ``--index-only`` option can be used to limit the indexed repositories to a comma-separated list::

    paster make-index my.ini --index-only=vcs,kallithea

To keep your index up-to-date it is necessary to do periodic index builds;

for this, it is recommended to use a crontab entry. Example::

    0  3  *  *  *  /path/to/virtualenv/bin/paster make-index /path/to/kallithea/my.ini

When using incremental mode (the default), Whoosh will check the last

modification date of each file and add it to be reindexed if a newer file is

available. The indexing daemon checks for any removed files and removes them

from index.

If you want to rebuild the index from scratch, you can use the ``-f`` flag as above,

or in the admin panel you can check the "build from scratch" checkbox.

.. _ldap-setup:

Setting up LDAP support

-----------------------

Kallithea supports LDAP authentication. In order

to use LDAP, you have to install the python-ldap_ package. This package is

available via PyPI, so you can install it by running::

    pip install python-ldap

.. note:: ``python-ldap`` requires some libraries to be installed on

          your system, so before installing it check that you have at

          least the ``openldap`` and ``sasl`` libraries.

Choose *Admin > Authentication*, click the ``kallithea.lib.auth_modules.auth_ldap`` button

and then *Save*, to enable the LDAP plugin and configure its settings.

Here's a typical LDAP setup::

 Connection settings

 Enable LDAP          = checked

 Host                 = host.example.com

 Account              = <account>

 Password             = <password>

 Certificate Checks   = DEMAND

 Search settings

 Base DN              = CN=users,DC=host,DC=example,DC=org

 LDAP Filter          = (&(objectClass=user)(!(objectClass=computer)))

 LDAP Search Scope    = SUBTREE

 Attribute mappings

 Login Attribute      = uid

 First Name Attribute = firstName

 Last Name Attribute  = lastName

 Email Attribute      = mail

If your user groups are placed in an Organisation Unit (OU) structure, the Search Settings configuration differs::

 Search settings

 Base DN              = DC=host,DC=example,DC=org

 LDAP Filter          = (&(memberOf=CN=your user group,OU=subunit,OU=unit,DC=host,DC=example,DC=org)(objectClass=user))

 LDAP Search Scope    = SUBTREE

.. _enable_ldap:

Enable LDAP : required

    Whether to use LDAP for authenticating users.

.. _ldap_host:

Host : required

    LDAP server hostname or IP address. Can be also a comma separated

    list of servers to support LDAP fail-over.

.. _Port:

Port : optional

    Defaults to 389 for PLAIN un-encrypted LDAP and START_TLS.

    Defaults to 636 for LDAPS.

.. _ldap_account:

Account : optional

    Only required if the LDAP server does not allow anonymous browsing of

    records.  This should be a special account for record browsing.  This

    will require `LDAP Password`_ below.

.. _LDAP Password:

Password : optional

    Only required if the LDAP server does not allow anonymous browsing of

      AuthType Basic

      AuthName "Kallithea authentication"

      AuthUserFile /srv/kallithea/.htpasswd

      Require valid-user

      RequestHeader unset X-Forwarded-User

      RewriteEngine On

      RewriteCond %{LA-U:REMOTE_USER} (.+)

      RewriteRule .* - [E=RU:%1]

      RequestHeader set X-Forwarded-User %{RU}e

    </Location>

Setting metadata in container/reverse-proxy

"""""""""""""""""""""""""""""""""""""""""""

When a new user account is created on the first login, Kallithea has no information about

the user's email and full name. So you can set some additional request headers like in the

example below. In this example the user is authenticated via Kerberos and an Apache

mod_python fixup handler is used to get the user information from a LDAP server. But you

could set the request headers however you want.

.. code-block:: apache

    <Location /someprefix>

      ProxyPass http://127.0.0.1:5000/someprefix

      ProxyPassReverse http://127.0.0.1:5000/someprefix

      SetEnvIf X-Url-Scheme https HTTPS=1

      AuthName "Kerberos Login"

      AuthType Kerberos

      Krb5Keytab /etc/apache2/http.keytab

      KrbMethodK5Passwd off

      KrbVerifyKDC on

      Require valid-user

      PythonFixupHandler ldapmetadata

      RequestHeader set X_REMOTE_USER %{X_REMOTE_USER}e

      RequestHeader set X_REMOTE_EMAIL %{X_REMOTE_EMAIL}e

      RequestHeader set X_REMOTE_FIRSTNAME %{X_REMOTE_FIRSTNAME}e

      RequestHeader set X_REMOTE_LASTNAME %{X_REMOTE_LASTNAME}e

    </Location>

.. code-block:: python

    from mod_python import apache

    import ldap

    LDAP_USER = ""

    LDAP_PASS = ""

    LDAP_ROOT = "dc=mydomain,dc=com"

    LDAP_FILTER = "sAMAccountName=%s"

    LDAP_ATTR_LIST = ['sAMAccountName','givenname','sn','mail']

    def fixuphandler(req):

        if req.user is None:

            # no user to search for

            return apache.OK

        else:

            try:

                if('\\' in req.user):

                    username = req.user.split('\\')[1]

                elif('@' in req.user):

                    username = req.user.split('@')[0]

                else:

                    username = req.user

                l = ldap.initialize(LDAP_SERVER)

                l.simple_bind_s(LDAP_USER, LDAP_PASS)

                r = l.search_s(LDAP_ROOT, ldap.SCOPE_SUBTREE, LDAP_FILTER % username, attrlist=LDAP_ATTR_LIST)

                req.subprocess_env['X_REMOTE_USER'] = username

                req.subprocess_env['X_REMOTE_EMAIL'] = r[0][1]['mail'][0].lower()

                req.subprocess_env['X_REMOTE_FIRSTNAME'] = "%s" % r[0][1]['givenname'][0]

                req.subprocess_env['X_REMOTE_LASTNAME'] = "%s" % r[0][1]['sn'][0]

            except Exception, e:

                apache.log_error("error getting data from ldap %s" % str(e), apache.APLOG_ERR)

            return apache.OK

.. note::

   If you enable proxy pass-through authentication, make sure your server is

   only accessible through the proxy. Otherwise, any client would be able to

   forge the authentication header and could effectively become authenticated

   using any account of their liking.

Integration with issue trackers

-------------------------------

Kallithea provides a simple integration with issue trackers. It's possible

to define a regular expression that will match an issue ID in commit messages,

and have that replaced with a URL to the issue. To enable this simply

uncomment the following variables in the ini file::

    issue_pat = (?:^#|\s#)(\w+)

    issue_server_link = https://issues.example.com/{repo}/issue/{id}

[default]

api_url = http://kallithea.example.com/_admin/api

api_user = admin

api_key = XXXXXXXXXXXX

ldap_user = cn=kallithea,dc=example,dc=com

ldap_key = XXXXXXXXX

base_dn = dc=example,dc=com

sync_users = True

# (at your option) any later version.

#

# This program is distributed in the hope that it will be useful,

# but WITHOUT ANY WARRANTY; without even the implied warranty of

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

# GNU General Public License for more details.

#

# You should have received a copy of the GNU General Public License

# along with this program.  If not, see <http://www.gnu.org/licenses/>.

"""

kallithea.lib.auth_modules.auth_ldap

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Kallithea authentication plugin for LDAP

This file was forked by the Kallithea project in July 2014.

Original author and date, and relevant copyright and licensing information is below:

:created_on: Created on Nov 17, 2010

:author: marcink

:copyright: (c) 2013 RhodeCode GmbH, and others.

:license: GPLv3, see LICENSE.md for more details.

"""

import logging

import traceback

from kallithea.lib import auth_modules

from kallithea.lib.compat import hybrid_property

from kallithea.lib.utils2 import safe_unicode, safe_str

from kallithea.lib.exceptions import (

    LdapConnectionError, LdapUsernameError, LdapPasswordError, LdapImportError

)

from kallithea.model.db import User

log = logging.getLogger(__name__)

try:

    import ldap

    import ldap.filter

except ImportError:

    # means that python-ldap is not installed

    ldap = None

class AuthLdap(object):

    def __init__(self, server, base_dn, port=None, bind_dn='', bind_pass='',

                 ldap_filter='(&(objectClass=user)(!(objectClass=computer)))',

                 search_scope='SUBTREE', attr_login='uid'):

        if ldap is None:

            raise LdapImportError

        self.ldap_version = ldap_version

        self.TLS_KIND = tls_kind

        OPT_X_TLS_DEMAND = 2

        self.TLS_REQCERT = getattr(ldap, 'OPT_X_TLS_%s' % tls_reqcert,

                                   OPT_X_TLS_DEMAND)

        self.cacertdir = cacertdir

        protocol = 'ldaps' if self.TLS_KIND == 'LDAPS' else 'ldap'

        if not port:

            port = 636 if self.TLS_KIND == 'LDAPS' else 389

        self.LDAP_SERVER = str(', '.join(

            "%s://%s:%s" % (protocol,

                            host.strip(),

                            port)

            for host in server.split(',')))

        self.LDAP_BIND_DN = safe_str(bind_dn)

        self.LDAP_BIND_PASS = safe_str(bind_pass)

        self.BASE_DN = safe_str(base_dn)

        self.LDAP_FILTER = safe_str(ldap_filter)

        self.SEARCH_SCOPE = getattr(ldap, 'SCOPE_%s' % search_scope)

        self.attr_login = attr_login

    def authenticate_ldap(self, username, password):

        """

        Authenticate a user via LDAP and return his/her LDAP properties.

        Raises AuthenticationError if the credentials are rejected, or

        EnvironmentError if the LDAP server can't be reached.

        :param username: username

        :param password: password

        """

        if not password:

            log.debug("Attempt to authenticate LDAP user "

                      "with blank password rejected.")

            raise LdapPasswordError()

        if "," in username:

            raise LdapUsernameError("invalid character in username: ,")

        try:

class KallitheaAuthPlugin(auth_modules.KallitheaExternalAuthPlugin):

    def __init__(self):

        self._logger = logging.getLogger(__name__)

        self._tls_kind_values = ["PLAIN", "LDAPS", "START_TLS"]

        self._tls_reqcert_values = ["NEVER", "ALLOW", "TRY", "DEMAND", "HARD"]

        self._search_scopes = ["BASE", "ONELEVEL", "SUBTREE"]

    @hybrid_property

    def name(self):

        return "ldap"

    def settings(self):

        settings = [

            {

                "name": "host",

                "validator": self.validators.UnicodeString(strip=True),

                "type": "string",

                "description": "Host of the LDAP Server",

                "formname": "LDAP Host"

            },

            {

                "name": "port",

                "validator": self.validators.Number(strip=True),

                "type": "string",

                "description": "Port that the LDAP server is listening on. Defaults to 389 for PLAIN/START_TLS and 636 for LDAPS.",

                "default": "",

                "formname": "Custom LDAP Port"

            },

            {

                "name": "dn_user",

                "validator": self.validators.UnicodeString(strip=True),

                "type": "string",

                "description": "User to connect to LDAP",

                "formname": "Account"

            },

            {

                "name": "dn_pass",

                "validator": self.validators.UnicodeString(strip=True),

                "type": "password",

                "description": "Password to connect to LDAP",

                "formname": "Password"

            },

            {

                "name": "tls_kind",

                "validator": self.validators.OneOf(self._tls_kind_values),

                "type": "select",

                "values": self._tls_kind_values,

                "description": "TLS Type",

                "formname": "Connection Security"

            },

            {

                "name": "tls_reqcert",

                "validator": self.validators.OneOf(self._tls_reqcert_values),

                "type": "select",

                "values": self._tls_reqcert_values,

                "description": "Require Cert over TLS?",

                "formname": "Certificate Checks"

            },

            {

                "name": "cacertdir",

                "validator": self.validators.UnicodeString(strip=True),

                "type": "string",

                "description": "Optional: Custom CA certificate directory for validating LDAPS",

                "formname": "Custom CA Certificates"

            },

            {

                "name": "base_dn",

                "validator": self.validators.UnicodeString(strip=True),

                "type": "string",

                "description": "Base DN to search (e.g., dc=mydomain,dc=com)",

                "formname": "Base DN"

            },

            {

                "name": "filter",

                "validator": self.validators.UnicodeString(strip=True),

                "type": "string",

                "description": "Filter to narrow results (e.g., ou=Users, etc)",

                "formname": "LDAP Search Filter"

            },

            {

                "name": "search_scope",

                "validator": self.validators.OneOf(self._search_scopes),

                "type": "select",

                "values": self._search_scopes,

                "description": "How deep to search LDAP",

                "formname": "LDAP Search Scope"

            },

            {

                "name": "attr_login",

                "validator": self.validators.AttrLoginValidator(not_empty=True, strip=True),

                "type": "string",

                "description": "LDAP Attribute to map to user name",

                "formname": "Login Attribute"

            },

            {

                "name": "attr_firstname",