Codendi Installation Guide

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.

Preamble
The 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 Installation
Codendi 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
Content
Directory

/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/lib/mysql contains the Codendi database, and /var/lib/codendi is Codendi main data
/var 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 Settings
Specific user accounts and groups that must be created prior to any manual software installation

User name user group Full Name home dir shell Remarks
id id

codendiadm 104 104 Owner of /home/codend /bin/b Set a password
Codendi iadm ash
directories

dummy 103 103 Dummy Codendi /var/lib/coden /bin/b Set same
user di/dumps ash password as

codendiadm

mailman 106 106 Owner of /usr/lib/mailm /bin/b - shell login not
Mailman an ash allowed
directories - Set same
password as
codendiadm

ftpadmin 96 96 FTP /var/lib/coden - shell login not
Administrator di/ftp allowed

ftp 14 50 FTP User /var/lib/coden - shell login not
di/ftp 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 mysql
shadow: files mysql
group: 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 Settings
Directory 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 Ownership permission Remarks
path

Codendi Users and Projects Directories

/home/users codendiadm.codendiadm drwxrwxr-x

/home/group codendiadm.codendiadm drwxrwxr-x
s

Temporary Codendi database dumps

/home/dum dummy.dummy drwx------
my

/var/lib/code dummy.dummy drwxr-xr-x
ndi/dumps

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

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

central server

/var/lib/code ftpadmin.ftpadmin d--x--x--x
ndi/ftp/bin
/var/lib/code
ndi/ftp/etc

/var/lib/code ftpadmin.ftpadmin drwxr-xr-x
ndi/ftp/lib

/var/lib/code root.root drwxr-xr-x
ndi/ftp/code
ndi

/var/lib/code ftpadmin.ftpadmin drwxr-xr-x
ndi/ftp/pub

/var/lib/code ftpadmin.ftpadmin drwxrwsrwt
ndi/ftp/inco
ming

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)

Temporary storage space for the
/var/run/log
root.root drwxrwxrwt cvs tracking script that feed the
_accum
Codendi database

/var/lib/code codendiadm.codendiadm drwxr-xr-x Where all CVS repo reside.
ndi/cvsroot

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

Subversion directory

/var/lib/code codendiadm.codendiadm drwxr-xr-x Where all Subversion repositories
ndi/svnroot reside.

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

Log files (http/cvs/ftp traffic archive)

/var/log/cod codendiadm.codendiadm drwxr-xr-x
endi/

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

Cache for generated HTML

/var/tmp/cod codendiadm.codendiadm drwxr-xr-x
endi_cache

MySQL directories

/var/lib/mys mysql.mysql drwxr-xr-x In case you have not enough
ql 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 /hom
e/var/lib; ln
-s /home/var/lib/mysql
NOTE: the mysql user will only
be available once the MySQL
packages are installed (see
section RPM Packages)

User Directory Startup files

/etc/skel_co root.root drwxr-xr-x All the files that you place in this
dendi 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 Support
Codendi 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 Items to Install
Specific
Packages

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

codendi- Install the Codendi SaloméTMF package. This RPM is needed if you
salome 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.

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

Install the subversion, mod_dav-svn, subversion-tools, subversion-perl
subversion
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.

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

Install the customized Mailman package. It is configured specifically
Mailman
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 Items to Install
Component

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.z
docbook-xsl -> docbook-xsl-x.y.z
fop -> fop-x.y.z
jimi -> 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 Configuration
Codendi 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.116
atlas IN A 13.0.33.116 ;
production server
atlas2 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 atlas
xww IN CNAME atlas
cvs IN CNAME atlas
cvs1 IN CNAME atlas
svn IN CNAME atlas
svn1 IN CNAME atlas
download IN CNAME atlas
shell IN CNAME atlas
shell1 IN CNAME atlas
users IN CNAME atlas
cxdocs IN CNAME atlas
lists 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 Software
As 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 File Value Remarks
name (MBytes)

sys_max_size /etc/codend N
_upload i/conf/local
.inc

upload_max_ /etc/httpd/c N
file_size onf.d/php.c
onf

post_max_siz /etc/httpd/c N+1
e onf.d/php.c
onf

memory_limi /etc/httpd/c 4*N We have to multiply by 4 because of the
t onf.d/php.c (legacy) document manager which stores the
onf 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 /etc/my.cnf 2*N+1 Escaping the file data can double the size of the
_packet data, plus 1 Mbyte for the other fields of the
SQL query.

Installing the Codendi Database
As 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 DB
mysql -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-bin
set-variable = max_allowed_packet=128M

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

Mail Configuration
Codendi 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 be
executed 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.com
lists.codendi.xerox.com
users.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.com
service 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 Configuration
Codendi 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 Utilities
There 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.rpm
ln -s /lib/libcrypto.so.0.9.8e /lib/libcrypto.so.4
ln -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 cvslockd
service 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 Account
Unless 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 -p
mysql> 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 -p
mysql> 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/ParametersDefa
ult.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 Querying
NOTE: 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 Scripts
Most 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 Jobs
Codendi 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 am
30 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 1am
0 1 * * Mon (cd /usr/share/codendi/src/utils/underworld-
root; ./db_project_weekly_metric.pl)
# daily incremental backup of subversion repositories
45 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 basis
00 03 * * * /usr/share/codendi/src/utils/generate_doc.sh
30 03 * *
* /usr/share/codendi/src/utils/generate_programmer_doc.sh
45 03 * * * /usr/share/codendi/src/utils/generate_cli_package.sh

Log Files Rotation
In 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
# 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
endscript
}

/var/log/httpd/error_log {
missingok
# LJ
daily
rotate 4

postrotate
endscript
}

/var/log/httpd/referer_log {
missingok
# LJ
daily
rotate 4
postrotate
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 phpMyAdmin
phpMyAdmin 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 plugin
Codendi 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 plugin
Codendi 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 Messaging
Codendi 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

Codendi Installation Guide

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Codendi Installation Guide

Similar to Codendi Installation Guide (20)

More from Codendi

More from Codendi (12)

Recently uploaded

Recently uploaded (20)

Codendi Installation Guide