ldapcherry/docs/deploy.rst

Deploy

LdapCherry aims to be as simple as possible to deploy. The Application is constituted of:

• ldapcherryd: the daemon to lauch LdapCherry.
• one ini file (ldapcherry.ini by default): the entry point for the configuration, containing all the "technical" attributes.
• two yaml files (roles.yml and attributes by default): the files containing the roles and attributes definition.

The default configuration directory is /etc/ldapcherry/.

Launch

LdapCherry is launched using the internal cherrypy server:

# ldapcherryd help
$ ldapcherryd -h

# launching ldapcherryd in the foreground
$ ldapcherryd -c /etc/ldapcherry/ldapcherry.ini

# launching ldapcherryd in the foreground in debug mode
$ ldapcherryd -c /etc/ldapcherry/ldapcherry.ini -D

# launching ldapcherryd as a daemon
$ ldapcherryd -c /etc/ldapcherry/ldapcherry.ini -p /var/run/ldapcherry/ldapcherry.pid -d

Roles and Attributes Configuration

Entry point in main configuration

The main configuration file (ldapcherry.ini by default) contains two parameters locating the roles and attributes configuration files:

Parameter	Section	Description	Values
attributes.file	attributes	Attributes configuration file	Path to conf file
roles.file	roles	Roles configuration file	Path to conf file

Attributes Configuration

The attributes configuration is done in a yaml file (attributes.yml by default).

Mandatory parameters

The mandatory parameters for an attribute, and their format are the following:

<attr id>:
    description: <Human readable description of the attribute>                       # (free text)
    display_name: <Display name in LdapCherry forms>                                 # (free text)
    weight: <weight controlling the display order of the attributes, lower is first> # (integer)
    type: <type of the attributes>                                                   # (in ['int', 'string', 'email', 'stringlist', 'fix', 'textfield'])
    backends:                                                                        # (list of backend attributes name)
        - <backend id 1>: <backend 1 attribute name>
        - <backend id 2>: <backend 2 attribute name>

Warning

<attr id> (the attribute id) must be unique, LdapCherry won't start if it's not.

Warning

<backend id> (the backend id) must be defined in main ini configuration file. LdapCherry won't start if it's not.

Type listing

The following type are supported:

• int: an integer (ex: uid)
• string: a string (ex: first name)
• stringlist: a string to choose from a given list of strings (ex: one of /bin/sh, /bin/bash /bin/zsh for a shell)
• textfield: free multiline text (ex: an SSH key)
• email: an email address
• fix: a fix value, only present shown information purposes

Type stringlist values

If type is set to stringlist the parameter values must be filled with the list of possible values:

<attr id>:
    description: <Human readable description of the attribute>
    display_name: <Display name in LdapCherry forms>
    weight: <weight controlling the display order of the attributes)

    type: stringlist
    values:
        - value1
        - value2
        - value3

    backends:
        - <backend id>: <backend attribute name>

Key attribute:

One attribute must be used as a unique key across all backends.

It acts as a reconciliation key.

It also marks which attribute must be used within ldapcherry (ex: querysting parameter in links) to point to one given user.

To set the key attribute, you must set key to True on this attribute.

Example:

uid:
    description: "UID of the user"
    display_name: "UID"
    search_displayed: True
    key: True                       # defining the attribute as "key"
    type: string
    weight: 50
    backends:
        ldap: uid
        ad: sAMAccountName

Authorize self modification

A user can modify some of his attributes (self modification). In such case, the parameter self must set to True:

<attr id>:
    description: <Human readable description of the attribute>
    display_name: <Display name in LdapCherry forms>
    weight: <weight controlling the display order of the attributes)
    type: <type of the attributes>

    self: True

    backends:
        - <backend id 1>: <backend 1 attribute name>
        - <backend id 2>: <backend 2 attribute name>

Autofill

LdapCherry has the possibility to auto-fill fields from other fields, to use this functionnality autofill must be set.

Example:

gidNumber:
    description: "Group ID Number of the user"
    display_name: "GID Number"
    weight: 70
    type: int

    autofill:
        function: lcUidNumber # name of the function to call
        args:                 # list of arguments
            - $first-name     # 
            - $name
            - '10000'
            - '40000'

    backends:
        ldap: gidNumber

Arguments of the autofill function work as follow:

• if argument starts with $, for example $my_field, the value of form input my_field will be passed to the function.
• otherwise, it will be treated as a fixed argument.

Available autofill functions:

• lcUid: generate 8 characters ascii uid from 2 other fields (first letter of the first field, 7 first letters of the second):

autofill: 
    function: lcUid
    args:
        - $first-name
        - $name

• lcDisplayName: concatenate two fields (with a space as separator):

autofill: 
    function: lcDisplayName
    args:
        - $first-name
        - $name

• lcMail: generate an email address from 2 other fields and a domain (<uid>+domain):

autofill: 
    function: lcMail
    args:
        - $first-name
        - $name
        - '@example.com'

• lcUidNumber: generate an uid number from 2 other fields and between a minimum and maximum value:

autofill: 
    function: lcUidNumber
    args:
        - $first-name
        - $name
        - '10000'
        - '40000'

• lcHomeDir: generate an home directory from 2 other fields and a root (<root>+<uid>):

autofill: 
    function: lcHomeDir
    args:
        - $first-name
        - $name
        - /home/

Roles Configuration

The roles configuration is done in a yaml file (roles.yml by default).

Mandatory parameters

Roles are seen as an aggregate of groups:

<role id>:
    display_name: <role display name in LdapCherry>
    description: <human readable role description>  
    backends_groups:                                # list of backends
        <backend id 1>:                             # list of groups in backend
            - <b1 group 1>
            - <b1 group 2>
        <backend id 2>:
            - <b2 group 1>
            - <b2 group 2>

Warning

<role id> must be unique, LdapCherry won't start if it's not

Defining LdapCherry Administrator role

At least one of the declared roles must be tagged to be LdapCherry administrators.

Doing so is done by setting LC_admins to True for the selected role:

<role id>:
    display_name: <Role display name in LdapCherry>
    description: <human readable role description>  

    LC_admins: True

    backends_groups:                                # list of backends
        <backend id 1>:                             # list of groups in backend
            - <b1 group 1>
            - <b1 group 2>
        <backend id 2>:
            - <b2 group 1>
            - <b2 group 2>

Nesting roles

LdapCherry handles roles nesting:

parent_role:
    display_name: Role parent
    description: The parent role
    backends_groups:
        backend_id_1:
            - b1_group_1
            - b1_group_2
        backend_id_2:
            - b2_group_1
            - b2_group_2
    subroles:
        child_role_1:
            display_name: Child role 1
            description: The first Child Role
            backends_groups:
                backend_id_1:
                    - b1_group_3
        child_role_2:
            display_name: Child role 2
            description: The second Child Role
            backends_groups:
                backend_id_1:
                    - b1_group_4

In that case, child_role_1 and child_role_2 will contain all groups of parent_role plus their own specific groups.

Main Configuration

Webserver

LdapCherry uses the embedded http server of CherryPy, however it has some limitations:

• no listening on port 80/443 (unless run as root, which is strongly discourage)
• no https

The simpler way to properly deploy LdapCherry is to run it listening only on localhost with a port above 1024 and put it behind an http server like nginx, apache or lighttpd acting as a reverse http(s) proxy.

Parameter	Section	Description	Values	Comment
server.socket_host	global	Listening IP	IP on which to listen	Use '0.0.0.0' to listen on any interfaces.
server.socket_port	global	Listening Port	TCP Port
server.thread_pool	global	Number of threads created by the CherryPy server	Number of threads threads
tools.staticdir.on	/static	Serve static files through LdapCherry	True, False	These files could be server directly by an HTTP server for better performance.
tools.staticdir.dir	/static	Directory containing LdapCherry static resources (js, css, img...)	Path to static resources

example:

[global]

# listing interface
server.socket_host = '127.0.0.1'
# port
server.socket_port = 8080
# number of threads
server.thread_pool = 8

# enable cherrypy static handling
# to comment if static content are handled otherwise
[/static]
tools.staticdir.on = True
tools.staticdir.dir = '/usr/share/ldapcherry/static/'

Backends

Backends are configure in the backends section, the format is the following:

[backends]

# backend python module path
<backend id>.module = <python.module.path>

# display name of the backend in forms
<backend id>.display_name = <display name of the backend> 

# parameters of the module instance for backend <backend id>.
<backend id>.<param> = <value>

It's possible to instanciate the same module several times.

Authentication and sessions

LdapCherry supports several authentication modes:

Parameter	Section	Description	Values	Comment
auth.mode	auth	Authentication mode	'and' (user must auth on all backends) 'or' (user must auth on one of the backends) 'none' (disable auth) 'custom' (use custom auth module)
auth.module	auth	Custom auth module	python class path to module	only used if auth.mode='custom'
tools.sessions.timeout	global	Session timeout in minutes	Number of minutes

Different session backends can also be configured (see CherryPy documentation for details)

[global]
# session configuration
# activate session
tools.sessions.on = True
# session timeout in minutes
tools.sessions.timeout = 10
# file session storage(to use if multiple processes, 
# default is in RAM and per process)
#tools.sessions.storage_type = "file"
# session 
#tools.sessions.storage_path = "/var/lib/ldapcherry/sessions"

[auth]
# Auth mode
# * and: user must authenticate on all backends
# * or:  user must authenticate on one of the backend
# * none: disable authentification
# * custom: custom authentification module (need auth.module param)
auth.mode = 'or'

# custom auth module to load
#auth.module = 'ldapcherry.auth.modNone'

Logging

LdapCherry has two loggers, one for errors and applicative actions (login, del/add, logout...) and one for access logs.

Each logger can be configured to log to syslog, file, stdout or be disabled.

Logging parameters:

Parameter	Section	Description	Values	Comment
log.access_handler	global	Logger type for access log	'syslog', 'file', 'stdout', 'none'
log.error_handler	global	Logger type for applicative log	'syslog', 'file', 'stdout', 'none'
log.access_file	global	log file for access log	path to log file	only used if log.access_handler='file'
log.error_file	global	log file for applicative log	path to log file	only used if log.error_handler='file'
log.level	global	log level of LdapCherry	'debug', 'info', 'warning', 'error', 'critical'

Example:

[global]

# logger syslog for access log 
log.access_handler = 'syslog'
# logger syslog for error and ldapcherry log 
log.error_handler = 'syslog'
# log level
log.level = 'info'

Warning

'debug' should not be used in production.

It tends to log a lot. More significantly can represent a security issue, as things like passwords will be logged 'clear text'.

Custom javascript

It's possible to add custom javascript to LdapCherry, mainly to add custom autofill functions.

Configuration:

Parameter	Section	Description	Values	Comment
tools.staticdir.on	/custom	Serve custom js files through LdapCherry	True, False	These files could be server directly by an HTTP server for better performance.
tools.staticdir.dir	/custom	Directory containing custom js files	Path to static resources	custom js files must be put at the root if the directory only files ending with ".js" are taken into account

Other LdapCherry parameters

Parameter	Section	Description	Values
template_dir	resources	LdapCherry template directory	path to template dir

# resources parameters
[resources]
# templates directory
template_dir = '/usr/share/ldapcherry/templates/'