ldapcherry/docs/deploy.rst

Deploy

LdapCherry aims at being 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

Launch

LdapCherry is launched using the internal cherrypy server:

# ldapcherryd help
$ ldapcherryd -h

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

# 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	Comment
attributes.file	attributes	Attributes configuration file	Path to conf file
roles.file	roles	Roles configuration file	Path to conf file

Attributes Configuration

Roles Configuration

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

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 or be desactivated.

Logging parameters:

Parameter	Section	Description	Values	Comment
log.access_handler	global	Logger type for access log	'syslog', 'file', 'none'
log.error_handler	global	Logger type for applicative log	'syslog', 'file', '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'

Other LdapCherry parameters

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

LdapCherry full configuration file

../conf/ldapcherry.ini

Init Script

Sample init script for Debian:

../goodies/init-debian

This init script is available in goodies/init-debian.