Kallithea currently only hosts repositories using http and https. (The addition

of ssh hosting is a planned future feature.) However you can easily use ssh in

parallel with Kallithea. (Repository access via ssh is a standard "out of

the box" feature of Mercurial_ and you can use this to access any of the

repositories that Kallithea is hosting. See PublishingRepositories_)

Kallithea repository structures are kept in directories with the same name

as the project. When using repository groups, each group is a subdirectory.

This allows you to easily use ssh for accessing repositories.

In order to use ssh you need to make sure that your web server and the users'

login accounts have the correct permissions set on the appropriate directories.

.. note:: These permissions are independent of any permissions you

          have set up using the Kallithea web interface.

If your main directory (the same as set in Kallithea settings) is for

example set to ``/srv/repos`` and the repository you are using is

named ``kallithea``, then to clone via ssh you should run::

    hg clone ssh://user@kallithea.example.com/srv/repos/kallithea

Using other external tools such as mercurial-server_ or using ssh key-based

authentication is fully supported.

.. note:: In an advanced setup, in order for your ssh access to use

          the same permissions as set up via the Kallithea web

          interface, you can create an authentication hook to connect

          to the Kallithea db and run check functions for permissions

          against that.

Setting up Whoosh full text search

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

Kallithea provides full text search of repositories using `Whoosh`__.

.. __: https://pythonhosted.org/Whoosh/

For an incremental index build, run::

    paster make-index my.ini

For a full index rebuild, run::

    paster make-index my.ini -f

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

 Port                 = 389

 Account              = <account>

 Password             = <password>

 Connection Security  = LDAPS connection

 Certificate Checks   = DEMAND

    """

    if not whitelist:

        from kallithea import CONFIG

        whitelist = aslist(CONFIG.get('api_access_controllers_whitelist'),

                           sep=',')

        log.debug('whitelist of API access is: %s', whitelist)

    api_access_valid = controller_name in whitelist

    if api_access_valid:

        log.debug('controller:%s is in API whitelist', controller_name)

    else:

        msg = 'controller: %s is *NOT* in API whitelist' % (controller_name)

        if api_key:

            #if we use API key and don't have access it's a warning

            log.warning(msg)

        else:

            log.debug(msg)

    return api_access_valid

class AuthUser(object):

    """

    Represents a Kallithea user, including various authentication and

    authorization information. Typically used to store the current user,

    but is also used as a generic user information data structure in

    parts of the code, e.g. user management.

    Constructed from a database `User` object, a user ID or cookie dict,

    it looks up the user (if needed) and copies all attributes to itself,

    adding various non-persistent data. If lookup fails but anonymous

    access to Kallithea is enabled, the default user is loaded instead.

    `AuthUser` does not by itself authenticate users and the constructor

    sets the `is_authenticated` field to False. It's up to other parts

    of the code to check e.g. if a supplied password is correct, and if

    so, set `is_authenticated` to True.

    However, `AuthUser` does refuse to load a user that is not `active`.

    """

    def __init__(self, user_id=None, dbuser=None,

            is_external_auth=False):

        self.is_authenticated = False

        self.is_external_auth = is_external_auth

        user_model = UserModel()

        self.anonymous_user = User.get_default_user(cache=True)

        # requested user cannot be found and the default anonymous user is

        # not enabled.

        self.user_id = None

        self.username = None

        self.api_key = None

        self.name = ''

        self.lastname = ''

        self.email = ''

        self.admin = False

        self.inherit_default_permissions = False

        # Look up database user, if necessary.

        if user_id is not None:

            log.debug('Auth User lookup by USER ID %s', user_id)

            dbuser = user_model.get(user_id)

        else:

            # Note: dbuser is allowed to be None.

            log.debug('Auth User lookup by database user %s', dbuser)

        is_user_loaded = self._fill_data(dbuser)

        # If user cannot be found, try falling back to anonymous.

        if not is_user_loaded:

            is_user_loaded =  self._fill_data(self.anonymous_user)

        self.is_default_user = (self.user_id == self.anonymous_user.user_id)

        if not self.username:

            self.username = 'None'

        log.debug('Auth User is now %s', self)

    def _fill_data(self, dbuser):

        """

        Copies database fields from a `db.User` to this `AuthUser`. Does

        not copy `api_keys` and `permissions` attributes.

        Checks that `dbuser` is `active` (and not None) before copying;

        returns True on success.

        """

        if dbuser is not None and dbuser.active:

            log.debug('filling %s data', dbuser)

            for k, v in dbuser.get_dict().iteritems():

                assert k not in ['api_keys', 'permissions']

                setattr(self, k, v)

            return True

        return False

                                             'password': 'test12',

                                             'password_confirmation': 'test12',

                                             'email': 'goodmailm',

                                             'firstname': 'test',

                                             'lastname': 'test'})

        response.mustcontain('An email address must contain a single @')

        msg = validators.ValidUsername()._messages['username_exists']

        msg = h.html_escape(msg % {'username': usr})

        response.mustcontain(msg)

    def test_register_special_chars(self):

        response = self.app.post(url(controller='login', action='register'),

                                        {'username': 'xxxaxn',

                                         'password': 'ąćźżąśśśś',

                                         'password_confirmation': 'ąćźżąśśśś',

                                         'email': 'goodmailm@test.plx',

                                         'firstname': 'test',

                                         'lastname': 'test'})

        msg = validators.ValidPassword()._messages['invalid_password']

        response.mustcontain(msg)

    def test_register_password_mismatch(self):

        response = self.app.post(url(controller='login', action='register'),

                                            {'username': 'xs',

                                             'password': '123qwe',

                                             'password_confirmation': 'qwe123',

                                             'email': 'goodmailm@test.plxa',

                                             'firstname': 'test',

                                             'lastname': 'test'})

        msg = validators.ValidPasswordsMatch('password', 'password_confirmation')._messages['password_mismatch']

        response.mustcontain(msg)

    def test_register_ok(self):

        username = 'test_regular4'

        password = 'qweqwe'

        email = 'user4@example.com'

        name = 'testname'

        lastname = 'testlastname'

        response = self.app.post(url(controller='login', action='register'),

                                            {'username': username,

                                             'password': password,

                                             'password_confirmation': password,

                                             'email': email,

                                             'firstname': name,

                                             'lastname': lastname,

        self.assertEqual(response.status, '302 Found')

        self.checkSessionFlash(response, 'You have successfully registered into Kallithea')

        ret = Session().query(User).filter(User.username == 'test_regular4').one()

        self.assertEqual(ret.username, username)

        self.assertEqual(check_password(password, ret.password), True)

        self.assertEqual(ret.email, email)

        self.assertEqual(ret.name, name)

        self.assertEqual(ret.lastname, lastname)

        self.assertNotEqual(ret.api_key, None)

        self.assertEqual(ret.admin, False)

    #==========================================================================

    # PASSWORD RESET

    #==========================================================================

    def test_forgot_password_wrong_mail(self):

        bad_email = 'username%wrongmail.org'

        response = self.app.post(

                        url(controller='login', action='password_reset'),

                            {'email': bad_email, }

        )

        response.mustcontain('An email address must contain a single @')

    def test_forgot_password(self):

        response = self.app.get(url(controller='login',

                                    action='password_reset'))

        self.assertEqual(response.status, '200 OK')

        username = 'test_password_reset_1'

        password = 'qweqwe'

        email = 'username@example.com'

        name = u'passwd'

        lastname = u'reset'

        timestamp = int(time.time())

        new = User()

        new.username = username

        new.password = password

        new.email = email

        new.name = name

        new.lastname = lastname

        new.api_key = generate_api_key()

        Session().add(new)

        Session().commit()

        response = self.app.post(url(controller='login',