better documentation
This commit is contained in:
kakwa
parent
3043310f83
commit
49b268dd3d
|
|
@ -6,6 +6,7 @@ Nice and simple application to manage user and groups in multiple directory serv
|
|||
|
||||
----
|
||||
|
||||
:Doc: `ldapcherry documentation on ReadTheDoc <http://ldapcherry.readthedocs.org/en/latest/>`_
|
||||
:Dev: `ldapcherry code on GitHub <https://github.com/kakwa/ldapcherry>`_
|
||||
:PyPI: `ldapcherry package on Pypi <http://pypi.python.org/pypi/ldapcherry>`_
|
||||
:License: MIT
|
||||
|
|
|
|||
198
docs/deploy.rst
198
docs/deploy.rst
|
|
@ -1,51 +1,50 @@
|
|||
Deploy
|
||||
======
|
||||
|
||||
Launching LdapCherry
|
||||
-------------------
|
||||
Launch
|
||||
------
|
||||
|
||||
ldapCherry can be launch using cherrypy internal webserver:
|
||||
LdapCherry is launched using the internal cherrypy server:
|
||||
|
||||
|
||||
.. sourcecode:: bash
|
||||
|
||||
# ldapcherryd help
|
||||
$ ldapcherryd -h
|
||||
Usage: ldapcherryd [options]
|
||||
|
||||
Options:
|
||||
-h, --help show this help message and exit
|
||||
-c CONFIG, --config=CONFIG
|
||||
specify config file
|
||||
-d run the server as a daemon
|
||||
-e ENVIRONMENT, --environment=ENVIRONMENT
|
||||
apply the given config environment
|
||||
-f start a fastcgi server instead of the default HTTP
|
||||
server
|
||||
-s start a scgi server instead of the default HTTP server
|
||||
-x start a cgi server instead of the default HTTP server
|
||||
-p PIDFILE, --pidfile=PIDFILE
|
||||
store the process id in the given file
|
||||
-P PATH, --Path=PATH add the given paths to sys.path
|
||||
|
||||
# launching ldapcherryd
|
||||
# launching ldapcherryd in the forground
|
||||
$ ldapcherryd -c /etc/ldapcherry/ldapcherry.ini
|
||||
|
||||
ldap Configuration
|
||||
-----------------
|
||||
# launching ldapcherryd as a daemon
|
||||
$ ldapcherryd -c /etc/ldapcherry/ldapcherry.ini -p /var/run/ldapcherry/ldapcherry.pid -d
|
||||
|
||||
General Configuration
|
||||
---------------------
|
||||
|
||||
Logs
|
||||
----
|
||||
Logging
|
||||
~~~~~~~
|
||||
|
||||
ldapCherry has two loggers, one for errors and actions (login, del/add, logout...) and one for access logs.
|
||||
Each logger can be configured to log to syslog, file or be unactivated.
|
||||
LdapCherry has two loggers, one for errors and applicative actions (login, del/add, logout...) and one for access logs.
|
||||
|
||||
.. warning::
|
||||
Each logger can be configured to log to syslog, file or be desactivated.
|
||||
|
||||
you can't set a logger to log both in file and syslog
|
||||
Syslog parameters:
|
||||
|
||||
Syslog configuration:
|
||||
+--------------------+---------+---------------------------------+-------------------------------------------------+----------------------------------------+
|
||||
| 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:
|
||||
|
||||
.. sourcecode:: ini
|
||||
|
||||
|
|
@ -55,44 +54,62 @@ Syslog configuration:
|
|||
log.access_handler = 'syslog'
|
||||
# logger syslog for error and ldapcherry log
|
||||
log.error_handler = 'syslog'
|
||||
|
||||
File configuration:
|
||||
|
||||
.. sourcecode:: ini
|
||||
|
||||
[global]
|
||||
|
||||
# logger syslog for access log
|
||||
log.access_handler = 'file'
|
||||
# logger syslog for error and ldapcherry log
|
||||
log.error_handler = 'file'
|
||||
# access log file
|
||||
log.access_file = '/tmp/ldapcherry_access.log'
|
||||
# error and ldapcherry log file
|
||||
log.error_file = '/tmp/ldapcherry_error.log'
|
||||
|
||||
Disable logs:
|
||||
|
||||
.. sourcecode:: ini
|
||||
|
||||
[global]
|
||||
|
||||
# logger syslog for access log
|
||||
log.access_handler = 'none'
|
||||
# logger syslog for error and ldapcherry log
|
||||
log.error_handler = 'none'
|
||||
|
||||
Set log level:
|
||||
|
||||
.. sourcecode:: ini
|
||||
|
||||
[global]
|
||||
|
||||
# log level
|
||||
log.level = 'info'
|
||||
|
||||
Other ldapCherry parameters
|
||||
--------------------------
|
||||
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 | Number of | |
|
||||
| | | by the CherryPy server | threads | |
|
||||
+---------------------+---------+------------------------------------+--------------------------+----------------------------------------------+
|
||||
| tools.staticdir.on | /static | Serve static files through | True, False | These files could be server directly by an |
|
||||
| | | LdapCherry | | http server for better performance. |
|
||||
+---------------------+---------+------------------------------------+--------------------------+----------------------------------------------+
|
||||
| tools.staticdir.dir | /static | Directory containing LdapCherry | Path to static resources | |
|
||||
| | | static resources (js, css, img...) | | |
|
||||
+---------------------+---------+------------------------------------+--------------------------+----------------------------------------------+
|
||||
|
||||
example:
|
||||
|
||||
.. sourcecode:: ini
|
||||
|
||||
[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/'
|
||||
|
||||
Authentication and sessions
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Other LdapCherry parameters
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. sourcecode:: ini
|
||||
|
||||
|
|
@ -130,52 +147,12 @@ Other ldapCherry parameters
|
|||
tools.staticdir.on = True
|
||||
tools.staticdir.dir = '/usr/share/ldapcherry/static/'
|
||||
|
||||
WebServer
|
||||
---------
|
||||
LdapCherry full configuration file
|
||||
----------------------------------
|
||||
|
||||
Idealy, LdapCherry must be deployed behind a proper http server like nginx or apache.
|
||||
.. literalinclude:: ../conf/ldapcherry.ini
|
||||
:language: ini
|
||||
|
||||
The webserver must be configured to act as a reverse (ssl) proxy to a ldapCherry instance listening on localhost (127.0.0.1).
|
||||
|
||||
Cherrypy
|
||||
~~~~~~~~
|
||||
|
||||
Cherrypy has an embeded web sever which can be used for testing.
|
||||
|
||||
It has some severe limitations:
|
||||
|
||||
* no SSL/TLS (which is recommanded)
|
||||
* no listening on the standard http port 80
|
||||
|
||||
To make ldapCherry listens on every IP:
|
||||
|
||||
.. sourcecode:: ini
|
||||
|
||||
[global]
|
||||
|
||||
# listing interface
|
||||
server.socket_host = '0.0.0.0'
|
||||
# port
|
||||
server.socket_port = 8080
|
||||
|
||||
Nginx
|
||||
~~~~~
|
||||
|
||||
.. literalinclude:: ../goodies/nginx.conf
|
||||
:language: none
|
||||
|
||||
|
||||
Apache
|
||||
~~~~~~
|
||||
|
||||
.. literalinclude:: ../goodies/apache.conf
|
||||
:language: none
|
||||
|
||||
Lighttpd
|
||||
~~~~~~~~
|
||||
|
||||
.. literalinclude:: ../goodies/lighttpd.conf
|
||||
:language: none
|
||||
|
||||
Init Script
|
||||
-----------
|
||||
|
|
@ -187,9 +164,4 @@ Sample init script for Debian:
|
|||
|
||||
This init script is available in **goodies/init-debian**.
|
||||
|
||||
ldapCherry configuration file
|
||||
----------------------------
|
||||
|
||||
.. literalinclude:: ../conf/ldapcherry.ini
|
||||
:language: ini
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,6 @@
|
|||
.. include:: ../README.rst
|
||||
|
||||
*************
|
||||
Site Menu
|
||||
*************
|
||||
********************
|
||||
Table of Content
|
||||
********************
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
|
@ -11,3 +9,5 @@
|
|||
deploy
|
||||
changelog
|
||||
|
||||
|
||||
.. include:: ../README.rst
|
||||
|
|
|
|||
Loading…
Reference in New Issue