web2ldap - Installing
Author: Michael Ströder <michael@stroeder.com>
Description: web2ldap: A brief description on how to install it
Keywords: LDAP LDAPv2 LDAPv3 subschema gateway Python python-ldap Directory userCertificate PKI LDIF DSML

Note that this installation description is always for the released version you can download here. It likely won't apply to older releases.

See also separate install receipts for specific platforms:

- Windows 32
- Debian Squeeze
- openSUSE Linux 11.4 or 12.1

## Run modes

web2ldap is running persistent as a multi-threaded server process under Win32 and Unix platforms:

Run mode | Start script | Web server
--- | --- | ---
stand-alone | `sbin/web2ldap.py` | Python standard lib
CGI-BIN | `cgi-bin/web2ldap.fcgi` | Any web server with CGI support and cgi-fcgi wrapper from FastCGI dev kit installed
FastCGI server | `fcgi/web2ldap.py` | Any web server with FastCGI support

## Prerequisites

For running web2ldap you need several modules. You can check them with script `sbin/checkinst.py`.

Package | Required | Description
--- | --- | ---
Python 2.6+ (2.7.3+ recommended, Python 3.x not supported!) | mandatory | The programming language needed to run.
PyWebLib 1.3.8+ | mandatory | Module package for web application programming.
python-ldap 2.4.0+ (2.4.10+ recommended) | mandatory | A wrapper module for accessing the OpenLDAP libs from Python and other LDAP-related modules.
OpenLDAP 2.4.11+ client libs (2.4.30+ recommended) | mandatory | Required to build python-ldap.
pyasn1 and pyasn1-modules | mandatory | Two separate module packages for processing ASN.1 data directly.
netaddr or ipaddr-py | mandatory | Module package for processing IP addresses (netaddr preferred)
fcgi.py | optional | For running as FastCGI server process
PyDNS (2.3.5+ recommended) | optional | If you want to make use of SRV RR's to automatically locate your LDAP server for a given dc-style DN you have to install this DNS module.
M2Crypto | optional | For displaying short overview of X.509 certificates.
Python Imaging Library (PIL) | optional | For automatically converting image data to required format (e.g. JPEGImage syntax).
pyExcelerator | optional | For Excel data export.

## Installing

1. Install all required software on your system.
2. Extract content of archive web2ldap-*.tar.gz to e.g. /opt. Regarding directory names under several Unix flavours: Your mileage may vary. ;-)
3. Rename /opt/web2ldap-<version> to /opt/web2ldap.
4. Edit configuration modules under [web2ldapdir]/etc/web2ldap/web2ldapcnf/ which contain comments about every configuration parameter. See also the documentation.
5. Optional step to speed start-up time when starting web2ldap as user which does not have write access to web2ldap directory:
   Change current directory to the directory where you extracted web2ldap and invoke `python [web2ldapdir]/sbin/compile.py` or `python -O [web2ldapdir]/sbin/compile.py` for compiling all Python sources.
6. Optional step when running under Unix-like systems:
   Choose the right start script for your run mode and adjust the path to the Python interpreter executable in the first line of the start script (see also python -h for usage of option -O and -OO for running with optimized bytecode generation).
7. Configure and run WWW server:
   stand-alone
     Unix/Linux:
       `[web2ldapdir]/sbin/web2ldap.py`
       For a quick start as stand-alone web gateway simply invoke the script at the command-line which outputs the start URL before detaching from console.
     Windows:
       Simply double-click the file `[web2ldapdir]/sbin/web2ldap.py`.
   Any HTTP server with CGI-FCGI wrapper
     Install `cgi-bin/web2ldap.fcgi` to CGI-BIN directory of web server.
   Apache with mod_fastcgi
     See configuration directives in file `etc/httpd/sample-mod_fastcgi.conf`.
   Apache with mod_fcgid
     See configuration directives in file `etc/httpd/sample-mod_fcgid.conf`.