Codendi Installation Guide

Copyright © Xerox Corporation, Codendi 2007-2009.This file is licensed under the GNU General Public License version 2. See the file COPYING.

PreambleThe Codendi Installation Guide covers the various steps that one has to go through to install and configure the Codendi software. After or while you are reading the installation guide we also recommend that you read the Codendi Administration Guide which focuses on the various tasks to perform to properly administrate a Codendi site on a daily basis.

The Installation procedure is documented so that Codendi adminstrators learn about the interns of the Codendi software. However the Codendi installation script provided by Xerox as part of the Codendi software takes care of most of the installation process described below. After completion the installation script will inform you of the remaining configuration that must be done manually.

Linux OS InstallationCodendi is designed to run on on a PC server (Intel x86 CPU or compatible) running Linux RedHat Linux Enterprise Server 5 (RHEL5) wether ES or AS version. This Linux version is only available with paid-for support. If you don't need a fully supported server (e.g. a test server or development server), you may use a free RHEL clone distribution. While those distributions are supposed to be fully binary compatible with RHEL, they are not tested, nor supported by Xerox.

OS Installation options

You are free to choose a full, partial, or minimum installation. The Codendi server does not need an X server, KDE, Gnome, etc. But you might find it useful if you intend to use the graphical administration tools. The Codendi installation script will ask for missing RPMs.

Codendi fully supports the SELinux targeted policy implemented in RHEL5. Feel free to enable it ("enforcing") during the installation.

If you choose to install a firewall on the server, make sure that all needed ports are open. This includes:

• Apache ports: 80 (HTTP) and 443 (HTTPS) • CVS pserver port: 2401 • FTP: port 21 • SSH: port 22

• SMTP: port 25 • JDBC: port 3306 (for SaloméTMF JDBC-mode support) • OpenFire (instant messaging server):

• 9090 -> administration of OpenFire • 9091 -> same in SSL • 5222 -> XMPP port • 5223 -> same in SSL • 7777 -> proxy file transfer • 8080 and 8483 for http bindings (not used in Codendi 3.6).

Disk Partitioning

Before choosing a partitioning scheme, it is important to know where Codendi data will be located. The following table shows the main directories used by Codendi:

Top Directory

Content

/usr Codendi source code is installed in /usr/share/codendi. Size around 300 MB. Total size for the whole /usr directory: up to 8 GB for a full RHEL4 installation.

/home Contains Codendi users home directories, and project directories (including project web sites). Size depends on Codendi usage (login shell allowed, web site usage).

/var/var/lib/mysql contains the Codendi database, and /var/lib/codendi is Codendi main data directory. It contains CVS and Subversion repositories, file releases, backups . Size: as much as the projects need. This directory should be located in the biggest disk or disk partition.

Whatever the partitioning scheme chosen, it is always possible to move directories from a partition to another, and create links from their original location. Be warned, though, of potential issues with SELinux: you might need to change security contexts.

User Accounts and Group SettingsSpecific user accounts and groups that must be created prior to any manual software installation

User name user id

group id

Full Name home dir shell Remarks

codendiadm 104 104 Owner of Codendi directories

/home/codendiadm

/bin/bash

Set a password

dummy 103 103 Dummy Codendi user

/var/lib/codendi/dumps

/bin/bash

Set same password as

codendiadm

mailman 106 106 Owner of Mailman directories

/usr/lib/mailman

/bin/bash

- shell login not allowed- Set same password as codendiadm

ftpadmin 96 96 FTP Administrator

/var/lib/codendi/ftp

- shell login not allowed

ftp 14 50 FTP User /var/lib/codendi/ftp

- shell login not allowed

Group name group id Group members Remarks

codendiadm 104 -

dummy 103 -

mailman 106 -

ftpadmin 96 ftpadmin, codendiadm

Authentication with libnNSS-MySQL

Starting with Codendi 4.0, Codendi users are now directly authenticated against the MySQL database. There is no longer need to edit /etc/passwd, /etc/shadow and /etc/group. Only the system users listed above still need to exist in those files (codendiadm, mailman, ftp, etc.).

Configuration files

LibNSS-MySQL needs two configuration files: /etc/libnss-mysql.cfg and /etc/libnss-mysql-root.cfg. Those files contain the queries that map system calls to SQL syntax. We provide sample files (.dist) for codendi in /usr/share/codendi/src/etc.

nsswitch.conf

In order to use libnss-mysql, one need to update /etc/nsswitch.conf to inform the system that it can use mysql for name service requests. Here is an extract from a sample nsswitch.conf (it is automatically updated by the

Codendi installation script):

passwd: files mysqlshadow: files mysqlgroup: files mysql

This means that if a user or group is not found in the corresponding file (/etc/passwd or /etc/group), the system will look into the MySQL DB.

NSCD

Using MySQL for system calls is slower that using the dedicated files. For this reason, we decided to deploy nscd (Name Service Caching Daemon) by default with Codendi. This daemon stores successfull name service requests into a cache for faster performance. Please note, however, that each time a user or a project is created, or a new member is added to a project, we need to clear the nscd cache. This is done automatically by the Codendi backend.

File System SettingsDirectory that must be created on the filesystem prior to software installation. For a description of the content of each directory see the Codendi Administration Guide.

Directory path

Ownership permission Remarks

Codendi Users and Projects Directories

/home/users codendiadm.codendiadm drwxrwxr-x

/home/groups

codendiadm.codendiadm drwxrwxr-x

Temporary Codendi database dumps

/home/dummy

dummy.dummy drwx------

/var/lib/codendi/dumps

dummy.dummy drwxr-xr-x

FTP storage spaces (incoming, anonymous and file release space)

/var/lib/codendi/ftp

root.ftp drwxr-xr-x Create a welcome.msg file in this directory with instructions for people uploading/downloading code (see example on Codendi

central server

/var/lib/codendi/ftp/bin/var/lib/codendi/ftp/etc

ftpadmin.ftpadmin d--x--x--x

/var/lib/codendi/ftp/lib

ftpadmin.ftpadmin drwxr-xr-x

/var/lib/codendi/ftp/codendi

root.root drwxr-xr-x

/var/lib/codendi/ftp/pub

ftpadmin.ftpadmin drwxr-xr-x

/var/lib/codendi/ftp/incoming

ftpadmin.ftpadmin drwxrwsrwt

CVS directories

/var/tmp root.root drwxrwxrwt Temporary storage space for cvs commit (needs a lot of space so we can not keep the default /tmp location)

/var/run/log_accum

root.root drwxrwxrwtTemporary storage space for the cvs tracking script that feed the Codendi database

/var/lib/codendi/cvsroot

codendiadm.codendiadm drwxr-xr-x Where all CVS repo reside.

/cvsroot root.root lrwxrwxrwx Link to /var/lib/codendi/cvsroot.

Subversion directory

/var/lib/codendi/svnroot

codendiadm.codendiadm drwxr-xr-x Where all Subversion repositories reside.

/svnroot root.root lrwxrwxrwx Link to /var/lib/codendi/svnroot.

Log files (http/cvs/ftp traffic archive)

/var/log/codendi/

codendiadm.codendiadm drwxr-xr-x

/var/log/codendi/cvslogs

codendiadm.codendiadm drwxrwxr-x Daily generated log files of all CVS repo hosted on Codendi (used for stattistics purposes)

Cache for generated HTML

/var/tmp/codendi_cache

codendiadm.codendiadm drwxr-xr-x

MySQL directories

/var/lib/mysql

mysql.mysql drwxr-xr-x In case you have not enough space in /var you can move the /var/lib/mysql directory to /home/var/lib/mysql and create a symbolic link in /var/lib:$ cd /var/lib/ ; mv /var/lib/mysql /home/var/lib; ln -s /home/var/lib/mysqlNOTE: the mysql user will only be available once the MySQL packages are installed (see section RPM Packages)

User Directory Startup files

/etc/skel_codendi

root.root drwxr-xr-x All the files that you place in this directory will be copied in the user's home directory when created. This would typically contain startup files (e.g. hidden files like .bash_profile, .bash_logout...) that you want to run when a user logs in with its telnet/shell account.

SELinux SupportCodendi is compatible with the SELinux targeted policy defined in RedHat Enterprise Linux 5. SELinux enforcement is not required by Codendi, but it is recommended for servers accessible from the internet.

In order to run Codendi when SELinux is in 'enforcing' state, it is required to make some specific adjustements to both directory contexts and SELinux policy.

SELinux directory contexts

The 'httpd' daemon needs to access paths that are not defined in the standard RHEL5 SELinux installation: Codendi installation directory, custom directory, data directory (for file packages, documents) , codendiadm subversion directory (for server update plugin), project directories (for project web sites) and source code repositories (for ViewVC). You can execute the 'fix_selinux_contexts.pl' Perl script located in /usr/share/codendi/src/utils to setup SELinux directory contexts automatically.

New SELinux modules

Codendi also needs specific rules that must be added to the RedHat default targeted policy.

SELinux rules for Codendi are provided in /usr/share/codendi/codendi_tools/selinux, in both textual and binary format. In order to load a binary module, simply type:

semodule -i modulename.pp

You can load all Codendi-provided modules by running the 'fix_selinux_contexts.pl' Perl script located in /usr/share/codendi/src/utils.

Compiling SELinux modules

Please read the RedHat official SELinux documentation for a detailed explanation of SELinux customization.

Building (or updating) an SELinux module is done in several steps:

1. Generate a source file from audit messages. SELinux modules can be built from access denial messages: RedHat provides tools to analyse those messages and create rules to enable access. For instance, to read all denial messages produced by the 'cvs' command, you can type:

ausearch -m AVC --comm cvs

And to build a SELinux module from these messages:

ausearch -m AVC --comm cvs | audit2allow -M cvs

This will create a file "cvs.te" containing the SELinux rules to suppress the denial messages, as well as a file "cvs.pp", which is the compiled, ready-to-use module.

2. You can edit the module source file by hand (e.g. to combine modules) (e.g. edit "cvs.te"). 3. Compile the module:

checkmodule -M -m cvs.te -o cvs.mod

4. Package the module:

semodule_package -o cvs.pp -m cvs.mod

5. And then, the module is ready for installation. You can install (or uninstall) it with the "semodule" command:

semodule -i cvs.pp

Specific Software Packages

RPM Packages

Codendi requires a number of specific packages to operate properly. These packages are provided either through the RedHat Linux Enterprise Server distribution or by Xerox as part of your support contract. It is the responsibility of the Codendi Administrators to make sure that they keep RPMs up-to-date with latest versions provided by RedHat or by Xerox for the Codendi specific RPMs.

Codendi Specific Packages

Items to Install

codendi-eclipse

Install the Codendi Eclipse software. This RPM is needed if you activate the Eclipse plugin.

codendi-salome

Install the Codendi SaloméTMF package. This RPM is needed if you activate the SaloméTMF plugin.

cvs or cvsnt Install the cvs or cvsnt package. If you use CVS, make sure you use a package provided with Codendi: it is a patched version.

cvsgraphInstall the cvsgraph package (used by viewvc to build a graphical view of CVS branches)

subversionInstall the subversion, mod_dav-svn, subversion-tools, subversion-perl and subversion-python packages

jre The Java Runtime environment is required to generate the HTML and PDF version of the Codendi User Guide. Install the jre rpm.

The package normally installs in /usr/java. Once installed make sure you create a symbolic link in /usr/java from 'jre' pointing to 'jre_xxxx' where xxxx is the version number. This is required by the DocBook

processing chain to generate the Codendi User Guide.

viewvc Install the viewvc package.

enscript Install the enscript package, used by viewVC for syntax highlighting.

highlight Install the highlight package, used by phpWiki for syntax highlighting.

HTML PurifierInstall the htmlpurifier PHP package. It is used by Codendi to filter HTML input.

MailmanInstall the customized Mailman package. It is configured specifically for Codendi (with the proper group IDs defined at compile time)

openfire Install the OpenFire package. OpenFire is a Jabber/XMPP server. This RPM is needed if you activate the Instant Messaging plugin.

Stock RedHat Codendi needs a number of RedHat packages that may not be installed by default (e.g. php-soap, apr, bind, etc.). The /usr/share/codendi/codendi_install.sh installation script contain the list of required RPMs. During installation, this script will complain if packages are missing.

Non RPM packages

Codendi also requires a number of specific packages that are not delivered in the form of RPM files. These packages are also compiled and installed automatically when Codendi is first installed.

Software Component

Items to Install

docbook In this directory you'll find all the programs required to generate the PDF and HTMl version of the Codendi Documentation (Codendi User Guide). All the packages (delivered in tar gzip'ed format must be installed in /usr/local:

• docbook-dtd-x.y.z.tgz: the DocBook Schema itself. • docbook-xsl-x.y.z.tgz: DocBook XSL stylesheets. • fop-x.y.z.tgz: the Apche FOP PDF generator. • Jimi-x.y.tgz: a java image processing software needed by FOP • saxon-x.y.z.tgz: XSLT engine to process the DocBook XML

documents

Each of these packages must be dearchived in /usr/local and for each directory make sure your create a generic symbolic link (with no

version number in it) to the top level directory. Like this:

docbook-dtd -> docbook-dtd-x.y.zdocbook-xsl -> docbook-xsl-x.y.zfop -> fop-x.y.zjimi -> Jimi-x.y.z (Caution!! symbolic link uses lower case only)etc...

utilities A series of small utilities that are needed by the PHP scripts and the Codendi backend to operate properly. See the Miscellaneous Utilities section below for more information

DNS ConfigurationCodendi has its own domain name and the name server for the Codendi domain is hosted on the central Codendi server.

DNS Zone file

Your DNS zone (called codendi.zone) definition file must be placed in /var/named/chroot/var/named. As an example here is how the codendi.zone file looks like on the Codendi central site of the Xerox Corporation. Adapt the file to your own needs:

$TTL 3600@ IN SOA atlas.codendi.xerox.com. dns_support\.cinops.xerox.com. ( 2002101805 ; Serial 3600 ; Refresh 1 hour 900 ; Retry 15 minutes 604800 ; Expire in 7 days 3600 ) ; Minimum TTL 1 hours IN NS atlas.codendi.xerox.com. IN NS athena.xerox.com. IN NS beta.xerox.com. IN NS carme.xerox.com.localhost IN A 127.0.0.1;----------------------------------------------------------------------

codendi.xerox.com. IN A 13.0.33.116atlas IN A 13.0.33.116 ; production serveratlas2 IN A 13.0.33.45 ; backup server

codendi.xerox.com. IN MX 0 atlas.codendi.xerox.com.codendi.xerox.com. IN MX 10 mailer-east.xerox.com.;www IN CNAME atlasxww IN CNAME atlascvs IN CNAME atlascvs1 IN CNAME atlassvn IN CNAME atlassvn1 IN CNAME atlasdownload IN CNAME atlasshell IN CNAME atlasshell1 IN CNAME atlasusers IN CNAME atlascxdocs IN CNAME atlaslists IN A 13.0.33.116 IN MX 0 lists.codendi.xerox.com. IN MX 10 mailer-east.xerox.com.

;; Wildcard DNS entry, to match all possible hosts: projnamme.*, cvs.projname.*, svn.projname.*, etc.;* IN CNAME atlas

As you can see the Codendi central hosts all the Codendi services on a single physical server. Hence the alias to the atlas machine name for all other logical servers (CVS, SVN, mail, download, shell account,etc...). The reason for defining those aliases is that at the site grows you are given the flexibility to export specific services to a separate server and all you'll have to do is to redefine the alias name to point to the IP address of the new server. Note that all servers must remain in the Codendi domain.

Named.conf file

/var/named/chroot/etc/named.conf is the master DNS configuration file. As an example, here is a sample file:

//// named.caching-nameserver.conf//// Provided by Red Hat caching-nameserver package to configure the// ISC BIND named(8) DNS server as a caching only nameserver

// (as a localhost DNS resolver only).//// See /usr/share/doc/bind*/sample/ for example named configuration files.////options {// listen-on port 53 { 127.0.0.1; }; listen-on-v6 port 53 { ::1; }; directory "/var/named"; dump-file "/var/named/data/cache_dump.db"; statistics-file "/var/named/data/named_stats.txt"; memstatistics-file "/var/named/data/named_mem_stats.txt"; query-source port *; query-source-v6 port *; allow-query { any; };

forwarders { 13.202.220.10; // Put your own DNS forwarders list here!!! };};logging { channel default_debug { file "data/named.run"; severity dynamic; };};

include "/etc/named.rfc1912.zones";

zone "codendi.xerox.com" { type master; file "codendi.zone";};

Apache Configuration• A sample Apache configuration file is available in the Codendi code in /usr/share/codendi/src/etc/http.conf.dist. Edit this file to reflect your site settings and place it in /etc/httpd/conf/httpd.conf.

• Modules configuration must be placed in /etc/httpd/conf.d/ . Codendi comes with a number of Apache modules configuration files that must be copied from /usr/share/codendi/src/etc/ to /etc/httpd/conf.d/ (e.g. php.conf, ssl.conf,etc.).

• Please not that, by default, all configuration files (ending with .conf) located in /etc/httpd/conf.d/ are included in both httpd.conf and ssl.conf. For this reason, you may want to remove or delete useless configuration files (e.g. perl.conf, python.conf, etc).

• Directory aliases (e.g. '/documentation', or '/phpMyAdmin') used to be defined in httpd.conf top level. This caused potential issues with virtual hosts defined for Codendi. For instance, the URL http://guineapig.codendi.xerox.com/documentation did not point to a "documentation" directory located in the Guinea Pig htroot directory, but to the main Codendi documentation tree. For this reason, Codendi aliases are defined per virtualhost. This is why configuration files are loaded in both the main virtual host, and the secure (HTTPS) virtual host.

• For the same reason, the ssl.conf file is moved from 'conf.d' to 'conf' (so that it does not include itself). • Start or restart the Apache web server (from the root account type the command: 'service httpd

restart')

Secure Apache (https)

Before you activate SSL in Apache make sure the standard RedHat openssl package is installed. Then you must either generate your own test certificate or you must get one from a certified company and install it in the right place. The RedHat Manual has excellent instructions on how to do generate a self-signed certificate. See the section called Apache HTTP Secure Server Configuration

You will also find a script that will automate these tasks for you (/usr/share/codendi/src/utils/generate_ssl_certificate.sh)

Note: although RedHat recommends that you generate a password protected key for your certificate it has some serious implications. The most noticeable is that a system administrator must be physically present while rebooting the Codendi system to type the password when the Apache server is started. This prevents from doing an unattended reboot.

To activate SSL on your Codendi server simply copy the sample /usr/share/codendi/src/etc/ssl.conf.dist file to /etc/httpd/conf/. It contains all the necessary Apache directives to enable secured HTTP. Then do the following:

• Edit /etc/httpd/conf/ssl.conf and replace the %sys_ip_address% and %sys_default_domain% patterns with the appropriate values for your site.

• For the changes to take effect you must restart the Apache server. • Then edit the /etc/codendi/conf/local.inc file and edit the $sys_https_host variable (in most cases this

will be the same name as the $sys_default_domain variable. If the port number you use for https is not the regular one (443) then you must specify the port number explicitely in the host name.

• In the same /etc/codendi/conf/local.inc file, you can also tune the $sys_force_ssl variable to determine how HTTPS is going to be used/enforced on your site.

Note: If you want to use the Eclipse plugin or the SaloméTMF client with an HTTPS-only server, you will need a valid certificate from a certified authority. Java is very touchy about certificates, and Eclipse and Salomé won't run with an HTTPS server presenting a self-signed certificate, or with a name different from the one specified in the certificate.

Installing the Codendi Software• Before you install the Codendi software make sure you have a user account on the Partners or central

Codendi server. You'll need this user account to update the source code from the Codendi Subversion repository.

• Ask us to add you to the codendi-svnevents mailing list to automatically receive all the commit made to the Central repository of Codendi so you know what modifications are being made and what to do to upgrade.

• If you want to develop a new feature, PLEASE get in touch with the Codendi Team to talk about it first. By doing so we can mutualize our development resources and make your effort beneficial to the entire Xerox community. Plus we can provide you with useful guidelines and tips. In addition remember that the Codendi code is subject to the GNU GPL license.

Configuring the Codendi SoftwareAs user root:

• copy /usr/share/codendi/src/etc/local.inc.dist in /etc/codendi/conf/local.inc and /usr/share/codendi/src/etc/database.inc.dist in /etc/codendi/conf/database.inc

• change local.inc and database.inc ownership (e.g. chown codendiadm.codendiadm /etc/codendi/conf/local.inc)

• change permission (e.g. chmod 640 /etc/codendi/conf/local.inc) **HIGHLY CRITICAL**

A couple of remarks on the some the variables in local.inc:

• Machine names: The local.inc and database.inc files are included by all Codendi PHP scripts and contains global variables that are used throughout the site. These files are also read by the backend Perl scripts and Python scripts (see below). You'll see that Codendi allows you to give distinct machine names that will be in charge of the various Codendi services (Web front end, CVS, Shell account, list manager,etc.). Even if you run all those services on the same machine we strongly encourage you to give different names for the various services and setup your DNS server so that all these are actually aliases to the same physical server. The reason is that it gives you the freedom, later in the life of the site, to delocalize a given service on a distinct machine without having to mess up with the Codendi database. The simple fact of assigining a new IP adress to what used to be a simple alias will automagically redirect all the traffic for this service to the right machine.

• Database parameters ($sys_dbxxx) : you'll have to provide the password for the MySQL codendiadm user here so make sure you have set the file permission of database.inc correctly (see above)

• Codendi News group ($sys_news_group): this is a reserved Codendi group_id. Leave this value unchanged.

• Site language ($sys_lang): right now, Codendi supports two languages: English (en_US) and French (fr_FR).

• HTTPS host ($sys_https_host): if your Apache server is SSL enabled (HTTPS protocol) set this variable with name/port number of the host to talk to. In general it is the same name as $sys_default_domain. Set it to an empty string ($sys_https_host = "") if your site is not SSL enabled.

PHP configuration

Most PHP configuration is now defined in /etc/httpd/conf.d/php.conf instead of /etc/php.ini.

• Codendi still needs the register_globals parameter to be set. It is 'off' by default starting with PHP5, so add this line to php.conf:

php_value register_globals on

php_flag magic_quotes_gpc on

• Update the include_path variable to the following value:

php_value include_path "/usr/share/codendi/src/www/include:/usr/share/codendi/src:."

• Also set/tune some additional variable for upload size:

php_value memory_limit 30M php_value post_max_size 20M php_value upload_max_file_size 20M php_value upload_tmp_dir /var/tmp

• Use /var/tmp as temporary directory to store uploaded file:

php_admin_value upload_tmp_dir /var/tmp

• phpWiki also needs thess parameters:

php_value allow_call_time_pass_reference on

php_flag register_long_arrays on

Modifying maximum size of uploaded files

By default, the maximum size of an artifact attachment is 16 MB, and the maximum size of a project document is 64 MB. Still, it is possible to modify these default values by modifying two parameters in local.inc:

• sys_max_size_attachment: this is the maximum size of an attachment, either for a bug, a task or any artifact.

• sys_max_size_upload: this is the maximum size of a document, a patch, a code snippet or a quick file release.

If you wish to go over the existing limit you might also have to modify the following files:

• /etc/httpd/conf.d/php.conf as described above • /etc/my.cnf i.e. the MySQL configuration file. Specify a max_allowed_packet value above the

maximum size you chose.

As a rule of thumb, if the $sys_max_size_upload is equal to N Mbytes then the other parameters should have the following values:

Parameter name

File Value (MBytes)

Remarks

sys_max_size_upload

/etc/codendi/conf/local.inc

N

upload_max_file_size

/etc/httpd/conf.d/php.conf

N

post_max_size

/etc/httpd/conf.d/php.conf

N+1

memory_limit

/etc/httpd/conf.d/php.conf

4*N We have to multiply by 4 because of the (legacy) document manager which stores the document in the database. We first have to escape the file data before building the SQL query. This in the worst case can double the size. And then we have to build the SQL query, which doubles the amount of memory again.

max_allowed_packet

/etc/my.cnf 2*N+1 Escaping the file data can double the size of the data, plus 1 Mbyte for the other fields of the SQL query.

Installing the Codendi DatabaseAs user root go through the following steps:

Move the mysql data directoy

• Make sure the official MySQL RPMs are installed (see above) • Make sure the mysql engine is started (command is 'service mysql start')

Create Codendi database

As root, run in a shell

mysql -e "create database codendi"

Define access permission

• Choose distinct passwords for the MySQL 'codendiadm' account and 'root' account. We recommend that you use the same passwords as those you chose for the codendiadm Unix account and root Unix account created earlier.

• Then run mysql on the mysql database:

# mysql mysql mysql> GRANT ALL PRIVILEGES on *.* to codendiadm@localhost identified by 'password'; mysql> GRANT ALL PRIVILEGES on *.* to root@localhost identified by 'password'; mysql> Flush Privileges; mysql> quit

From now onwards if you want to use the mysql shell to interact with the Codendi database (think twice before doing any change by hand in the database !!!) you'll have to run the following command and type the codendiadm password when prompted:

# mysql -u codendiadm codendi -p

Populate the database

To create the tables in the Codendi database and populate the database with the initial values one needs to type a few commands:

cd /usr/share/codendi/src/db/mysql/mysql -u codendiadm codendi -p < database_structure.sql # create the DBmysql -u codendiadm codendi -p < database_initvalues.sql # populate with init values.If you make a mistake in the creation process and want to restart from scratch run the following command:

mysql -e "drop database codendi"

MySQL configuration file

The /etc/my.cnf configuration file is here to specify a number of configuration items that are going to be used by the MySQL engine at run time. Right now the configuration file looks like this

# The MySQL server[mysqld]log-bin=codendi-binset-variable = max_allowed_packet=128M

[safe_mysqld]err-log=/var/log/mysqld.log

Mail ConfigurationCodendi uses sendmail as Mail transfer agent but it is possible to use any other MTA like Postfix, Exim or other. You need to setup

Sendmail settings

In /etc/mail/sendmail.cf:

• Set Cw to codendi.xerox.com (or change the domain name to your own). If you get errors like "config error: mail loops back to me (MX problem?)" when sending emails to lists.codendi.xerox.com, you may need to add this domain in the CW. Then the line looks like:

Cwcodendi.xerox.com lists.codendi.xerox.com

• Set DM to codendi.xerox.com (this is what we masquerade as):

DMcodendi.xerox.com

• To modify sendmail to accept remote connections in the sendmail.cf file, comment out (or delete) the following line:

O DaemonPortOptions=Port=smtp,Addr=127.0.0.1, Name=MTA

The commented out version of this line would then look like so:

#O DaemonPortOptions=Port=smtp,Addr=127.0.0.1, Name=MTA

• Aliases files should have been automatically set up. They are:

O AliasFile=/etc/aliases,/etc/aliases.codendi

• If you have errors when using mailman like this one:

Group mismatch error. Mailman expected the mail wrapper script to beexecuted as one of the following groups:[mail, postfix, mailman, nobody, daemon],but the system's mail server executed the mail script as group: "mailnull".

This seems to be related to a sendmail bug. Then you should add this line in sendmail.cf:

O DefaultUser=root:mailman

In /etc/mail/local-host-names:

• Say that you are serving the various codendi sub-domains as follows:

# local-host-names - include all aliases for your machine here.codendi.xerox.comlists.codendi.xerox.comusers.codendi.xerox.com

To check your configuration, you can try to send an email from the root account to an external email address. If the message comes back with this error:

(reason: 553 5.1.8 ... Domain of sender address root@localhost.localdomain does not exist)

It probably means that the machine host name is not properly configured. Try:

hostname atlas.codendi.xerox.comservice sendmail restart

Or edit /etc/sysconfig/network and enter the machine fully qualified name as HOSTNAME. OR edit /etc/hosts and add codendi.xerox.com in the first line. E.g.

127.0.0.1 codendi.xerox.com atlas localhost.localdomain localhost

Aliases

/etc/aliases

This is where you must insert system level aliases by hand (e.g. aliases for postmaster, root, etc.).

/etc/aliases.codendi

aliases.codendi is generated automatically bo the Codendi cron job (see below) and contains the aliases for all the mailing lists in the @lists.codendi.xerox.com domain and the email aliases for users. **Never edit this file by hand**

/usr/share/codendi/src/utils/underworld-dummy/aliases.zone

This is where you can define Codendi level aliases like codendi-contact, codendi-admin, etc. This file is currently under version control so if you are managing your own site it might be a better idea to add these aliases in /etc/aliases to avoid conflict when merging new code from Codendi source repository

Sendmail shell wrappers

In the Codendi Configuration, sendmail uses a number of shell wrappers used in pipe commands in the aliases file. These shell wrappers must be explicitely delcared in the /etc/smrsh directory in order to execute properly. You should create the following links:

# cd /etc/smrsh # ln -sf /usr/local/bin/gotohell # ln -sf /usr/lib/mailman/mail/mailman

Mailman Installation and ConfigurationCodendi now uses a modified version of RedHat mailman RPMs. Only the RPM SPEC file and mailman configuration files have been changed. You need to setup a mailman admin password once the installation is done (we recommend that you use the same password as the codendiadm account). To this end use the 'mmsitepass' script in /usr/lib/mailman/bin.

You must also configure the Apache configuration httpd.conf to instruct Apache on how to access the Web based mailing manager and archiver. A sample configuration file is provided with the RPM.

Create a "site-wide" mailing list. This is the one that password reminders will appear to come from.

% bin/newlist mailman % bin/config_list -i data/sitelist.cfg mailman

Be sure to subscribe yourself to the site list

% echo "your.email@address.com" | bin/add_members -r - mailman

Update /etc/aliases as precised, and remove existing mailman aliases if any. Then run 'newaliases'. You must also override some Mailman variable settings, most notably set the DEFAULT_EMAIL_HOST and DEFAULT_URL_HOST to lists.codendi.xerox.com. Look at their original definition in /usr/lib/mailman/Mailman/Defaults.py and redefine them in /usr/lib/mailman/Mailman/mm_cfg.py. When you change either variable in your mm_cfg.py, then be sure to also include the following:

add_virtualhost(DEFAULT_URL_HOST, DEFAULT_EMAIL_HOST)

If you wish to run Mailman with HTTPS (secure server), you need to add two more lines to /usr/lib/mailman/Mailman/mm_cfg.py.:

DEFAULT_URL_PATTERN = 'https://%s/mailman/'PUBLIC_ARCHIVE_URL = 'https://%(hostname)s/pipermail/%(listname)s'

See also Mailman FAQ on this topic.

Then recompile with python -O mm_cfg.py.

Miscellaneous UtilitiesThere are a few utilities that must be either compiled and/or installed in /usr/local/bin. A precompiled version of all these scripts is provided at http://codendi.partners.xrce.xerox.com/packages/nonRPMS_Codendi/utilities

fileforge

This is a small utility which is called by the Apache server to move files from the incoming ftp directory to the project file release space

Go to /usr/share/codendi/src/utils. In fileforge.c, modify the following lines if need be

char * src_dir = "/var/lib/codendi/ftp/incoming/"; /* the ftp incoming directory */ char * dest_dir = "/var/lib/codendi/ftp/codendi/"; /* the file release space for Codendi projects */

The trailing slashes are mandatory. Compile it with gcc -O2 -o fileforge fileforge.c. Then copy fileforge to /usr/local/bin and run:

# cd /usr/local/bin # chown root.codendiadm fileforge # chmod 4750 fileforge # sets the uid bit

Alternatively, use the compile_fileforge.sh script located in src/utils: it will perform all those steps for you.

gotohell

A simple shell script to discard all the messages sent to the noreply@codendi.xerox.com messages. The file

must contain:

#!/bin/sh

cat - >/dev/null

Ownership and permission must be:

-rwxr-xr-x 1 root root 27 Dec 11 2001 /usr/lib/codendi/bin/gotohell

Subversion Configuration• First make sure the Codendi specific RPMs for Subversion are installed on your Codendi server (see

the section on RPM Packages) • Create the /var/lib/codendi/svnroot directory and the /svnroot link as follows:

# mkdir /var/lib/codendi/svnroot# chown codendiadm.codendiadm /var/lib/codendi/svnroot# chmod 775 /svnroot# ln -s /var/lib/codendi/svnroot /svnroot

Subversion offers several remote access methods either via the native svnserve protocol or via the HTTP WebDAV subversion protocol. For many reasons Codendi has opted for the HTTP WebDAV access through Apache 2.0. The Apache virtual subversion servers are created automatically by the Codendi cron job. If you have activated secure HTTP on your server then you can also protect the HTTP authentication process by accessing your Subversion repository via an HTTPS URL.

CVS Configuration• First, make sure the Codendi specific RPMs for CVS are installed on your Codendi server (see the

section on RPM Packages) • Create the /etc/cvs_root_allow file as follows:

# touch /etc/cvs_root_allow# chown codendiadm.codendiadm /etc/cvs_root_allow# chmod 644 /etc/cvs_root_allow

Then you have to decide what type of CVS access you want to offer to your users: either through the standard pserver protocol,through SSH (secure shell), or, if you installed CVSNT instead of CVS, you may use the sserver protocol (SSL encrypted pserver). If your site is inside your corporate network the pserver method is a good choice. If your site is on the Internet we recommend that you use the SSH or sserver approach to make sure that confidential information like passwords or source code travels encrypted.

The pserver approach

• Configure xinetd to start the cvs server when needed. The /etc/xinetd.d/cvs file must look like this: service cvspserver{ disable = no socket_type = stream protocol = tcp wait = no user = root server = /usr/bin/cvs server_args = -f -z3 -T/var/tmp --allow-root-file=/etc/cvs_root_allow pserver}

The benefit of using the pserver approach is that you can define who has read and write permission on the CVS repository through the CVSROOT/readers and CVSROOT/writers file of your CVS repository. In the current implementation all project members are granted read and write access to the CVS repository of the projects they belong to. You can always add users' name in the CVSROOT/readers file to give them read-only access.

The sserver approach: CVSNT

• First, you need to make sure that you use cvsnt and not cvs. Type 'cvs -v' to verify this. If not, install CVSNT from Codendi CD like this:

rpm -ivh --nodeps cvsnt-2.5.04.3236-1.i386.rpm cvsnt-protocol-sserver-2.5.04.3236-1.i386.rpmln -s /lib/libcrypto.so.0.9.8e /lib/libcrypto.so.4ln -s /lib/libssl.so.0.9.8e /lib/libssl.so.4

The RPM provided by CVSNT relies on older libraries. This is why we need to 'force' the RPM installation without checking dependencies.

• You also need to verify that the sserver protocol is installed. Type 'cvs info'. this command should return a line like this one:

sserver sserver 2.5.04 (Zen) Build 3236 ()

• Configure xinetd to start the cvs server when needed. The /etc/xinetd.d/cvsnt file must look like this:

service cvspserver{ disable = no socket_type = stream wait = no user = root group = root log_type = FILE /var/log/cvspserver server = /usr/bin/cvsnt server_args = -f -z3 -T/var/tmp authserver groups = yes log_on_failure += USERID mdns = no # Lockserver handles mdns broadcast}

You will need to restart xinetd:

service xinetd restart

• Make sure that there is no /etc/xinetd.d/cvs file that might interfere with this one. Don't rename the file, but move it somewhere else, or delete it.

• add the cvslockd service:

chkconfig --add cvslockdservice cvslockd start

• Copy '/usr/share/codendi/src/etc/PServer.dist' file to /etc/cvsnt/PServer.Note that the sserver protocol uses the same SSL certificates as the https protocol. If your Codendi server is not yet configured for HTTPS, you need to generate a certificate.

• You may need to migrate existing CVSROOTs if they were created with CVS (and not CVSNT) with a script. Use /usr/share/codendi/src/utils/cvs1/cvs2cvsnt.pl.

The SSH approach

The idea behind the SSH approach is that a client ssh to the remote server and the cvs command is actually executed on the remote server. Note that this is different from another approach which consist of using the port forwarding capability of SSH to encrypt all trafic on the TCP port 2401 used by the pserver.

There is no much to do to allow this method. The simple fact of having the sshd daemon running will allow users to use this method. Things to pay attention to:

• If you want to disable the pserver access, make sure you edit /etc/xinetd.d/cvs, change the 'disable' parameter to 'yes' and restart xinetd (service xinetd restart)

• On the client side, users must set the environment variable CVS_RSH to 'ssh' • You must also copy the site-content/en_US/cvs/intro.txt in site-content/custom/en_US/cvs/intro.txt

and edit it to reflect the new CVS access method.

See also the section on restricted shells.

The CVS Tracking Database

Codendi offers the ability for each project to build a database of all CVS events (commit, add, delete) happening on their CVS repository. This feature is activated in the CVS Web interface of the Codendi Web frontend under CVS -> Admin. For this feature to work properly symbolic links must be created from the /usr/local/bin directory as follows:

# cd /usr/share/codendi/src/utils/cvs1 # cp log_accum /usr/lib/codendi/bin # cp commit_prep /usr/lib/codendi/bin

The log_accum script requires the codendiadm group ownership to execute properly. **HIGHLY CRITICAL**

# cd /usr/lib/codendi/bin # chown codendiadm.codendiadm log_accum commit_prep

# chmod 755 log_accum commit_prep # chmod u+s log_accum # sets the uid bit (-rwsr-xr-x)

Be careful that you must set the uid bit again whenever the log_accum script is updated from CVS and copied again into the /usr/lib/codendi/bin directory.

Browsing the CVS Trees

The ViewVC package is delivered as part of the Codendi software and allows Codendi users to browse both CVS and Subversion repositories from their Web browser. After installing the ViewVC RPM package (see #Installing_the_Codendi_Software ), a cgi-bin directory is created with the viewvc.cgi script in it. The ViewVC configuration file is at /etc/codendi/conf/viewvc.conf.

FTP Configuration• Codendi FTP service is based on vsftpd, the FTP server distributed with Red Hat Enterprise Linux. • Make sure the ftp service is enabled:chkconfig vsftpd on

• The /etc/vsftpd/vsftpd.conf on the Codendi site must be edited to allow anonymous upload:anon_upload_enable=YES

• You may also customize the welcome banner.ftpd_banner=Welcome to Codendi FTP service.

• Last, you may also set welcome messages in various directories: /var/lib/codendi/ftp/.message for the main welcome message, and /var/lib/codendi/ftp/incoming/.message for the incoming directory. Make sure both files are owned by ftpadmin.

Shell AccountUnless otherwise instructed the Codendi system will create a shell account for all users who have a Web account. The login and password are the same. Users can access their shell account either through SSH or telnet. We will see how to restrict the use of a shell account below. It is also possible to suspend or delete a user account (both Web and Unix) but be aware that disabling the Linux account will prevent users from using all the peripheral services like CVS, FTP,...

SSH Configuration

Simply check that the ssh daemon is started (command is 'service ssh start'). Also make sure that it is started at boot time (command is 'chkconfig sshd on').

Telnet Configuration

Telnet access should only be enabled when your Codendi site is on a safe network. If you are on the Internet

we *strongly* recommend that you disable it. To enable/disable the telnet access on your Codendi server, edit the /etc/xinetd.d/telnet file and change the 'disable' parameter accordingly. Then restart xinetd.

Restricted Shell Capabilities

It is sometimes desirable to allow the creation of a Shell Account for Codendi users while limiting the thing they can do with it. For instance you may want to limit the capabilities of certain users to use only CVS and may be sftp if you decide to use the secure ftp server but you don't want them to log into the system with a real shell like bash. Doing so is just a matter of changing the shell account associated with a given user.

By default the user table of the Codendi database has '/bin/bash' configured as the default shell. When the user account is created by the cron job s/he will have /bin/bash as a shell and therefore s/he will be given full shell capabilities. You can later decide to change the shell of a given user through the user admin interface of the Codendi Web site and use a restricted shell like the ones Codendi provide in src/utils/cvs1/:

• cvssh: This is a little script that simply check the command that are remotely executed through ssh by the user (it can be cvs, sftp, rsync,...) and decide to accept or reject the command.

• cvssh-restricted: works as cvssh, but prevents CVS access to projects the user is not member of. This is the default shell for Codendi restricted users (status 'R')

To activate these pseudo shells:

• copy the file cvssh (or cvssh-restricted) in /usr/lib/codendi/bin, make sure it is executable and also add the file to the list of authorized shells in /etc/shells. Adding cvssh to /etc/shells will make it appear in the list of possible shells in the Codendi user admin interface. Note: This is already done for you on Codendi versions after 2.4

• If you want the restricted shell to be the default for all users then change the default value of the shell column in the user table with the following mysql command:

$ mysql -u codendiadm codendi -pmysql> ALTER TABLE user ALTER COLUMN shell SET DEFAULT'/usr/lib/codendi/bin/cvssh' ;

No Shell Access

It is also possible to disable the shell access to all user by default. The procedure is as follows:

• Add '/bin/false' to the list of allowed shells in /etc/shells. • If you want to deactivate shell access for all users by default then change the default value of the shell

column in the user table with the following mysql command:

$ mysql -u codendiadm codendi -pmysql> ALTER TABLE user ALTER COLUMN shell SET DEFAULT'/bin/false' ;

Note: if you do this then you must use the pserver or sserver protocols to access the cvs repository as the access through ssh requires a shell account to be activated.

Codendi Site Customization

Codendi admin user

**HIGHLY CRITICAL**When you'll be initializing the Codendi database (see next step below), the user table of the Codendi database is initialized with a Codendi user called 'admin' who has full admin rights on all the Codendi hosted projects and also has access to Web based administration modules like user and project settings, project approval, software map configuration,etc.

The default password for the admin user is 'siteadmin' , we strongly encourage you to change this password as soon as the site is up and running. Here is how to do it:

• login on the Web front end with user 'admin', password 'siteadmin' • click on the 'Account Maintenance' link in the left hand side menu pane • click on change email address and update it either with your own email address if you are the only

administrator or first create a distribution list with all the codendi admin email adresses and use this mailing list address

• go back and change the password • logout and login again to make sure that the new password was taken into account

System configuration file (local.inc)

The PHP scripts take many values from a configuration file located in /etc/codendi/conf/local.inc. This file must be initially copied from the src/etc/local.inc.dist file and the values must be changed accordingly for your site. Make sure that you read this file where the role of each variable is well documented.

UI Themes

The Codendi Web pages look and feel are defined through Cascading Style Sheets (CSS). Therefore Codendi UI is customizable to large extent. The Graphical user interface elements of Codendi come in the following directory:

src/www/themes/ Each sub-directory in this place contains a given theme which name is the sub-directory name. By default Codendi comes with the 'Codendi', 'CodendiTab' and 'savannah' themes. Each theme directory contains a css directory and a images directory. Each style directory contains 3 CSS files named 'themename_fontsize.css' where fontsize is one of 'large', 'normal' or 'small'. Files differ only by the size of the default font used in the Web pages. All 3 must be present because Codendi users can choose a prefered font size in her Account Maintenance page. Each images directory contains all the logos and images needed by the Codendi Web pages.The theme must contain also a class named themename_Theme.class which is responsible for the construction of the layout.

To have more information about themes, or about creation of new themes, please see the corresponding section in The Codendi Programmer's Guide.

Organization Logo

At the top of the left hand side Codendi menu pane (just above the Logged In section) is an empty area where you can dock the logo of your organization. This can be achieved by first creating your own theme directory as explained in the previous section and then changing the image named 'organization_logo.png'. By default this is a transparent image of size 52x52 pixels. We recommend that your logo do not exceed 60x140 pixels to preserve the nice looking layout of the menu bar.

Site content

Several PHP scripts in the Codendi source code contain pieces of text or code that are generally here to give instructions to the Codendi users, or to provide site-specific information. Typical examples are: the introductory text at the top of the Codendi Home Page, instructions on how to connect to the CVS repository, instructions and guidelines in the project registration process, LDAP repository information, etc.

These pieces of text or code are isolated from the PHP scripts themselves and they are all placed under the top directory 'site-content'. The file path to the content of a given script (or part of a script) follows the following pattern:

site-content/LANG_COUNTRY/src_path/whattext.txt

where:

• LANG_COUNTRY is the standard ISO naming for language and countries: Currently Codendi supports two languages: en_US (American English) and fr_FR (French).

• src_path is the name of the directory under src which contains the script the text belongs to. • whattext.txt is a file name that contains the piece of text itself

By default the site-content directory should be stored in the same place as the src directory (PHP scripts). Make sure you update the $sys_incdir variable in /etc/codendi/conf/local.inc to reflect the path to the site-content directory (default is /usr/share/codendi/site-content).

To customize the content of a given script for your site go through the following steps:

1. Under /etc/codendi create the site-content directory if it doesn't exist. 2. For each piece of text that you want to customize copy the original whattext.txt file under the /etc/codendi/site-content/ with the exact same path. For instance if you want to customize the introductory text of the Codendi home page, copy /usr/share/codendi/site-content/en_US/homepage/welcome_intro.txt into and /etc/site-content/en_US/homepage/welcome_intro.txt edit it as you like.

Be careful that some of these files contain PHP scripting that you probably want to preserve in your customized version. Deleting the PHP scripting could break the entire PHP scripts. Ask the Codendi Team if you are unsure of what you are doing.

Read also Localization below for additional information on how to customize interface messages.

Localization

Codendi source code is localized, so the interface is displayed in the user-selected language. Currently, Codendi supports the English and French languages.

Messages are stored in the Site content directory: there is one message file per service, with the same name as the service, ending with '.tab'. E.g. 'site-content/en_US/tracker/tracker.tab' contains all tracker messages in English. The format of the message files is very simple: one line per message, with the following format:

key1[tab]key2[tab]your message here

As with other site-content files, you may customize the language files, so that you can change a few specific messages:

1. Copy the language file you need to customize from the /usr/share/codendi/site-content subdirectory to the corresponding subdirectory in /etc/codendi/site-content (see Site content above)

2. Remove all lines that you don't need to change, and only keep the lines you will modify. 3. Change the messages 4. Repeat the operation for all the languages you need to support on your Codendi server.

Codendi themes may also use additional messages that are not part of the main Codendi source code. These messages are directly stored in the theme directory, and they may be customized for local themes in /etc/codendi/themes/messages/theme_name/

When looking for a message to display, Codendi will look successively in the following directories, stopping as soon as the message is found:

1. Theme-specific message file 2. /etc/codendi/site-content/user_lang directory 3. /usr/share/codendi/site-content/user_lang directory 4. /usr/share/codendi/site-content/en_US directory (if the message file does not exist in the selected

language)

Site Documentation

Codendi has an entry called 'Site Documentation' in the left hand side menu. This menu entry actually points to the Document Manager of the Codendi project ('Admin Project'). This project is automatically defined when the Codendi database is initialized. It comes with group_id 1 (ONE) and you can acces it at http://your.codendi_site.url/projects/codendi.

All documents stored in the document manager of the 'Admin Project' will automatically appear under 'Site Documentation' (except those with restricted access. See the Codendi User Guide for more details on the Document Manager service.

User Guide and On-line Help

'On-line Help' is also a menu entry appearing in the left hand side menu of Codendi. It actually points to the HTML version of the Codendi User Guide (CUG). The CUG has been written in XML with the DocBook DTD and is stored under the top level 'documentation' directory in the Codendi source repository. To activate the on-line help simply check out the documentation directory at the same place as the src and site-content directories.

**IMPORTANT REMARK**The User Guide contain references to the company name, server name running Codendi,etc. These pieces of information vary from one site to another. Therefore a specific file has been introduced at /usr/share/codendi/documentation/user_guide/xml/ParametersLocal.dtd that you can use to customize the content of the Codendi User Guide. To do so:

• Copy /usr/share/codendi/documentation/user_guide/xml/ParametersLocal.dtd to /etc/codendi/documentation/user_guide/xml/ParametersLocal.dtd

• Edit the file you just copied and redefine the XML entities that govern the site specific information. For a list of the available XML entities that you can redefine see the /usr/share/codendi/documentation/user_guide/xml/en_US/ParametersDefault.dtd .

• Regenerate the documentation by running the script /usr/share/codendi/src/utils/generate_doc.sh

Also notice that the HTML and PDF versions of the CUG are not stored in the source repository. They are generated from the XML files using the script /usr/share/codendi/src/utils/generate_doc.sh. You can run this script by hand from the codendiadm Linux account and our advice is also to include it in the codendiadm crontab so that it runs once a day and automatically regenerate the documentation when needed.

For the script to work properly you must have the JRE (Java Runtime Environment) and the DocBook processing chain installed properly. See the section about specific software packages to install.

Project Web Site

When a project is registered on Codendi a new web site is created for that project. A default home page is installed for that project from the /usr/share/codendi/site-content/en_US/others/default_page.php file. You may want to create your own custom file for your own Codendi site. To do so, copy the /usr/share/codendi/site-content/en_US/others/default_page.php file in the /etc/codendi/site-content/en_US/others/ directory if not already there. Then, edit the custom file and customize it to your liking

LDAP Authentication and QueryingNOTE: LDAP settings have changed in Codendi 2.8. This documentation is only valid for Codendi 2.6.

LDAP information from the company directory

While visiting a user information page on Codendi, you have the ability to query the LDAP directory of your company to get more information about this user. The following variables in the local.inc configuration file (see above) allow you to customize the LDAP search:

• $sys_ldap_server: the full name of the LDAP server to query (ask your system administrator if you don't know of any around you). You may specify multiple directories or mirrors by using a comma separated list of servers.

• $sys_ldap_dn: the distinguished name (DN) to use in the LDAP query (Remark: the LDAP query in Codendi uses the user email address as the search key)

• $sys_ldap_filter: the search filter to use when a query is sent to the LDAP server. This is the filter argument used in the ldap_search call. Any pattern of the form %name% in the search filter will be replaced with the corresponding value from the user table before ldap_search is called. As an example %email% will be replaced by the user email, %user_name% means the user login name,etc...

• $sys_ldap_bind_dn and $sys_ldap_bind_passwd need only to be defined if the LDAP server does not allow anonymous binding. In such a case, please specify an LDAP distinguished name (DN) and password to use when querying or searching the directory.

It is also possible to customize the HTML output of the LDAP search when one accesses the information about a user on Codendi. You must edit the script site-content/LANG_COUNTRY/include/user_home.txt to customize the HTML output and save it in the corresponding custom directory (see Site Content section above).

LDAP Authentication

Codendi also supports LDAP authentication: passwords are no longer Codendi specific, but are managed in an external LDAP directory (e.g. the company directory).

Please note: as of Codendi 2.4, LDAP authentication is still experimental. Use with caution.

Specifications

Codendi now supports LDAP authentication. In order to use this authentication scheme, set $sys_auth_type to 'ldap' and define the other variables in local.inc as specified below.

The LDAP login and the Codendi login might not be the same. The reason for this is that the LDAP logins might not be compatible with UNIX logins (e.g. they might contain spaces, accentuated characters, etc.). In this case, the users will have two logins.

• The web authentication login is the LDAP login: it is used to access the web-based user interface of Codendi.

• Some services need a unix-based authentication, namely: CVS (with pserver, sserver or SSH), Subversion, FTP and shell access, and thus rely on the Codendi login.

Note that both logins use the same password, i.e. the LDAP password.

Registration

The registration phase is made up of two phases:

• On the first screen, simply type your LDAP login and password. • If the information was correct, the second screen displays the final registration form. Most fields are

already defined, based on the LDAP directory information: email address, real name, unix login (currently based on email address).

Fill the remaining blank fields and press the submit button. Your account is created! Note that if account creation needs approval, the account is not immediately available.

Login

When logging on the Codendi web interface, simply enter your LDAP name and password. The system will dynamically check your password against the LDAP server.

If the LDAP password is different from the current Codendi password (used for Unix services: CVS, etc.), then the Codendi password is updated with the LDAP password. This is to ensure that the two logins always use the same password.

LDAP authentication setup

In order to activate Codendi LDAP authentication, one only has to modify the local.inc configuration file (see above).

• $sys_ldap_server is the full name of the LDAP server(s). You may specify multiple directories or mirrors by using a comma separated list of servers. To specify secure LDAP servers, use 'ldaps://servername'. This variable is already defined above for querying LDAP information from the company directory.

• $sys_ldap_bind_dn and $sys_ldap_bind_passwd may also be necessary depending on your LDAP setup (see above).

• $sys_auth_type defines the authentication scheme to use. Its default value is 'codendi' for Codendi specific login/passwords. In order to use LDAP authentication, set this variable to 'ldap'.

• $sys_ldap_auth_dn is the distinguished name (DN) used for checking the user LDAP name and password.

• If you already know the correct DN to use for your LDAP repository, please use '%ldap_name%' wherever the user LDAP login should appear in this DN. It will automatically be replaced by the login name entered by the user. In order to test the user credentials, the system will perform an LDAP bind with this DN and the user entered password. Example: $sys_ldap_auth_dn = 'dc=xerox, dc=com, cn=%ldap_name%'.

• If you don't know the DN to use, you probably need a two-step authentication: an initial LDAP query with the first DN defined here and the filter defined below ($sys_ldap_auth_filter) will return the actual DN to use for authentication. Then a bind with the correct DN will be performed to test the credentials of the user. In this latter case, the string '%ldap_name%' should not appear in this variable, and you should probably have: $sys_ldap_auth_dn == $sys_ldap_dn. Example: $sys_ldap_auth_dn = 'o=XEROX, c=US'.

• $sys_ldap_auth_filter defines the query filter to use for authentication-related LDAP

queries. This variable must contain the '%ldap_name%' string, that will be replaced automatically by the user LDAP login. Example: $sys_ldap_auth_filter = 'uid=%ldap_name%'. It is used in two places:

• First, when a new user registers in Codendi, she needs to enter her LDAP login name. The system will then query the LDAP directory for additional information about this person (email address, real name, etc.). $sys_ldap_auth_filter is the filter used in this query.

• When a two-step LDAP authentication is in place (see above), this filter is used in the initial LDAP query run to extract the user DN needed for the authentication.

Backend ScriptsMost of the backend scripts used by the Codendi system are writen in Perl and are located in /usr/share/codendi/src/utils. Many of these script use the include.pl file and, in case you did not follow the standard installation process explained in this document, you may have to customize the content of this include file to match your site configuration.

Cron JobsCodendi runs a number of cron job in the background. The most important one is run once every 2hours on the Codendi site to map the Codendi user/project permission to the Linux user/group permission mechanism. it also create all the user and project related directories automatically.

Other cron jobs run daily and weekly statistics.

Root crontab

Find below a copy of the root crontab file. we highly recommend that you keep the same time and frequency to run the jobs.

# Once a minute, process Codendi system events* * * * * (cd /usr/share/codendi/src/utils; ./php-launcher.sh ./process_system_events.php)## Regularly launch a system_check event (e.g. every half-hour) 0,30 * * * * (cd /usr/share/codendi/src/utils; ./php-launcher.sh ./launch_system_check.php)## run the daily statistics script just a little bit after# midnight so that it computes stats for the day before# Run at 0:30 am30 0 * * * /usr/share/codendi/src/utils/compute_all_daily_stats.sh#

# run the weekly stats for projects. Run it on Monday morning so that# it computes the stats for the week before# Run on Monday at 1am0 1 * * Mon (cd /usr/share/codendi/src/utils/underworld-root; ./db_project_weekly_metric.pl)# daily incremental backup of subversion repositories45 23 * * 1-6 /usr/lib/codendi/bin/backup_subversion.sh -i## weekly full backup of subversion repositories (0:15 on Sunday)15 0 * * Sun /usr/lib/codendi/bin/backup_subversion.sh## weekly backup preparation (mysql shutdown, file dump and restart)45 0 * * Sun /usr/lib/codendi/bin/backup_job## Delete all files in FTP incoming that are older than 2 weeks (336 hours)#0 3 * * * /usr/sbin/tmpwatch -m -f 336 /var/lib/codendi/ftp/incoming#

Please note that your own root crontab should probably contain some additional jobs like may be stopping the mysql engine before starting your backup procedure or something similar.

Codendiadm crontab

# Daily Codendi PHP cron (obsolete documents...)10 0 * * * /usr/share/codendi/src/utils/php-launcher.sh /usr/share/codendi/src/utils/codendi_daily.php# Re-generate the Codendi User Guides on a daily basis00 03 * * * /usr/share/codendi/src/utils/generate_doc.sh30 03 * * * /usr/share/codendi/src/utils/generate_programmer_doc.sh45 03 * * * /usr/share/codendi/src/utils/generate_cli_package.sh

Log Files RotationIn order to maintain statistics on http and ftp traffic the Codendi server must be instructed to rotate the apache and ftp log files on a daily basis.

Apache Log File Rotation

/etc/logrotate.d/apache looks like this:

/var/log/httpd/access_log { missingok # LJ daily rotate 4 postrotate /usr/bin/killall -HUP httpd 2> /dev/null || true # LJ Added for Codendi archiving year=`date +%Y` month=`date +%m` day=`date +%d` destdir="/var/log/codendi/$year/$month" destfile="http_combined_$year$month$day.log" mkdir -p $destdir cp /var/log/httpd/access_log.1 $destdir/$destfile endscript} /var/log/httpd/vhosts-access_log { missingok # LJ daily rotate 4 postrotate /usr/bin/killall -HUP httpd 2> /dev/null || true # LJ Added for Codendi archiving year=`date +%Y` month=`date +%m` day=`date +%d` server=`hostname` destdir="/var/log/codendi/$server/$year/$month" destfile="vhosts-access_$year$month$day.log" mkdir -p $destdir cp /var/log/httpd/vhosts-access_log.1 $destdir/$destfile endscript} /var/log/httpd/agent_log { missingok # LJ daily rotate 4 postrotate /usr/bin/killall -HUP httpd 2> /dev/null || true endscript} /var/log/httpd/error_log { missingok # LJ daily rotate 4

postrotate /usr/bin/killall -HUP httpd 2> /dev/null || true endscript}

/var/log/httpd/referer_log { missingok # LJ daily rotate 4 postrotate /usr/bin/killall -HUP httpd 2> /dev/null || true endscript}

FTP log file rotation

/etc/logrotate.d/ftpd looks like this:

/var/log/xferlog { # ftpd doesn't handle SIGHUP properly nocompress # LJ Modified for codendi daily postrotate year=`date +%Y` month=`date +%m` day=`date +%d` destdir="/var/log/codendi/$year/$month" destfile="ftp_xferlog_$year$month$day.log" mkdir -p $destdir cp /var/log/xferlog.1 $destdir/$destfile endscript}

Installing phpMyAdminphpMyAdmin is a Web based GUI to manage MySQL database. Although installing phpMyAdmin is not mandatory it is a very convenient for a Codendi site adminstrator.phpMyAdmin is now provided with Codendi as a customized RPM package. When you access the phpMyAdmin GUI at http://your.codendi.domain/phpMyAdmin you'll be prompted for a user name and password. Use the MySQL 'codendiadm' login and password.

Eclipse pluginCodendi provides a plugin for Eclipse to allow access to Codendi trackers directly from the IDE interface. This plugin is provided as a rpm (named codendi-eclipse), that needs to be installed on the Codendi server. You also need to activate the plugin from the Codendi plugin administration interface. Please read the Codendi User Guide for more information on how to setup the Eclipse plugin.

SaloméTMF pluginCodendi provides a test plan manager called SaloméTMF. This is a Java application that must be downloaded by the end user with Java Web Start. In order to provide this service, you need to install a dedicated RPM (codendi-salome). You also need to activate the plugin from the Codendi plugin administration interface, and activate the service for each project that would like to use the service.

Please read the Codendi User Guide for more information on how to run Salomé from Codendi.

Please note that Salomé uses its own database (called 'salome'), with its own administrator (salomeadm).

The current implementation of Salomé needs a direct JDBC access from the client machine (the Java application) to the server database. Make sure that your firewalls do not forbid access to the JDBC port (3306).

Instant MessagingCodendi hosts an Instant Messaging server based on the Jabber/XMPP protocol to provide instant messaging. This server is the java-based OpenFire server. Please note that OpenFire uses its own database (openfire), with its own administrator ('openfireadm'). The openfireadm MySQL user also needs read access to the user, group and user_group tables of the main database ('codendi'). You can access the detailed installation guide: JabbeXInstallGuide.odt (OpenOffice odt format).

First Things To Do to run the site• Access the Codendi server and login as admin with default password siteadmin. Then change the

password immediately. We suggest that you use the same as the root password on the Linux side • Logout and create your own account on the Codendi site: click on 'New User' and fill out the form.

Wait for the email notification to arrive and confirm the registration. If the mail doesn't work yet then login as 'admin' again and force User registration approval in 'Main Page' of the Site Administration menu.

• Login again as user 'admin' and make your own account a project member of the Admin Project

(group_id=1) so that you are considered as a super user on the entire site. Set permissions for this new account.

• Create the trackers you need (bug and support requests most likely) • From your own account create a new project 'Guinea Pig' (shortname: gpig) that you will use as a test

project for anybody who wants to experiment with the site. Setup the project completely, approve it and then set up the CVS or SVN repository with some sample code, create a release, download it,etc...

• Under the 'Codendi Project' create a piece of news to announce the launch of the Codendi site and promote the news to the front page.

End of Document