This document describes the procedure to be used to install an X-Itools server from CVS sources completely.

The installation is certified for RedHat 7.2 and 7.3 servers.

The installation consist in several parts:

• download the sources in a directory via CVS
• modify httpd.conf file of apache server
• create initial web directory for X-Itools binaries
• compilation of the sources
• installation of the X-Itools database
• restart apache
• initialize root crontab
• test of the X-Itools server

This documentation does not describe how to install softs needed for X-Itools server to run properly: apache, postgresql, sendmail, SSL, LDAP, and/or others...

BEFORE TO START:

On the computer which will be the X-Itools server, create a user called xitools:

#> useradd xitools

His home directory should be something like /home/xitools or whatever.

We will use this unprivileged user to receive the X-Itools CVS tree which will be downloaded below.

DOWNLOAD CVS TREE:

Now that the xitools user has been added, login as him.

#> su - xitools $>

and download the latest X-Itools project CVS tree like written below. Before, for security reasons, don't forget to enable SSH on CVS:

$> export CVS_RSH=ssh

now, download the tree:

$> cvs -z3 -d:pserver:anonymous@cvs.x-itools.sourceforge.net:/cvsroot/x-itools co 20010715_01

If all goes well, you should now have a directory named 20010715_01 in your homedirectory. This directory contains all what is needed to install a X-Itools server from sources.

Here below is the tree you should have in the directory 20010715_01:

20010715_01     +    HISTORY                    // history of each module (not used any more)     +    lib                             // sources of the shared library     +    pixmaps                     // picture files     +    po                             // language files     +    src                            // sources of each module

Note that the name 20010715_01 for the X-Itool directory is not a kind of revision or version name: it just represents the date at which the X-Itools project has been started the first time on sourceforge (http://sourceforge.net).

MODIFY HTTPD.CONF FILE OF APACHE SERVER:

You will need root rights to modify the apache configuration file for X-Itools. Normally, this file sould be located in /etc/httpd/conf directory, but it could depends of you rlinux distribution or installation.

So, as the xitools user, do the following:

$> su root

enter your root password and edit the httpd.conf file with your favorite editor (I'm sure it is vi):

#> vi /etc/httpd/conf/httpd.conf

This configuration file is very well documented. Go at section 3 of the file: this is where we will create and configure virtual hosts.
For this, look for the work NameVirtualHost in the file: it should exist. We have to enable this directive if it is not the case. For that, remove the # if there is one. The NameVirtualHost must contain your ip address: in fact the IP address of your apache server, where will be installed the X-Itools binary files. For example:

NameVirtualHost 10.10.10.1

Now, we have to create a VirtualHost on usual http port 80 specific to the X-Itools server. If you wish, you can modify the default virtualhost for port 443, and in this case the X-Itools server will be accessible through SSL. If your are a company, I am sure you think that security is something important.

So, if you want to enable SSL for X-Itools, modify the <VirtualHost _default_:443> block as follow in the httpd.conf file:

<VirtualHost _default_:443> # General setup for the virtual host DocumentRoot "/var/www/x-itools" #ServerName new.host.name ServerAdmin xitools ErrorLog logs/x-itools.ssl.error_log TransferLog logs/x-itools.sll.access_log # SSL Engine Switch: # Enable/Disable SSL for this virtual host. SSLEngine on # SSL Cipher Suite: # List the ciphers that the client is permitted to negotiate. # See the mod_ssl documentation for a complete list. #SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL # Server Certificate: # Point SSLCertificateFile at a PEM encoded certificate. If # the certificate is encrypted, then you will be prompted for a # pass phrase. Note that a kill -HUP will prompt again. A test # certificate can be generated with `make certificate' under # built time. Keep in mind that if you've both a RSA and a DSA # certificate you can configure both in parallel (to also allow # the use of DSA ciphers, etc.) SSLCertificateFile /etc/httpd/conf/ssl.crt/server.crt #SSLCertificateFile /etc/httpd/conf/ssl.crt/server-dsa.crt # Server Private Key: # If the key is not combined with the certificate, use this # directive to point at the key file. Keep in mind that if # you've both a RSA and a DSA private key you can configure # both in parallel (to also allow the use of DSA ciphers, etc.) SSLCertificateKeyFile /etc/httpd/conf/ssl.key/server.key #SSLCertificateKeyFile /etc/httpd/conf/ssl.key/server-dsa.key # Server Certificate Chain: # Point SSLCertificateChainFile at a file containing the # concatenation of PEM encoded CA certificates which form the # certificate chain for the server certificate. Alternatively # the referenced file can be the same as SSLCertificateFile # when the CA certificates are directly appended to the server # certificate for convinience. #SSLCertificateChainFile /etc/httpd/conf/ssl.crt/ca.crt # Certificate Authority (CA): # Set the CA certificate verification path where to find CA # certificates for client authentication or alternatively one # huge file containing all of them (file must be PEM encoded) # Note: Inside SSLCACertificatePath you need hash symlinks # to point to the certificate files. Use the provided # Makefile to update the hash symlinks after changes. #SSLCACertificatePath /etc/httpd/conf/ssl.crt #SSLCACertificateFile /etc/httpd/conf/ssl.crt/ca-bundle.crt # Certificate Revocation Lists (CRL): # Set the CA revocation path where to find CA CRLs for client # authentication or alternatively one huge file containing all # of them (file must be PEM encoded) # Note: Inside SSLCARevocationPath you need hash symlinks # to point to the certificate files. Use the provided # Makefile to update the hash symlinks after changes. #SSLCARevocationPath /etc/httpd/conf/ssl.crl #SSLCARevocationFile /etc/httpd/conf/ssl.crl/ca-bundle.crl # Client Authentication (Type): # Client certificate verification type and depth. Types are # none, optional, require and optional_no_ca. Depth is a # number which specifies how deeply to verify the certificate # issuer chain before deciding the certificate is not valid. #SSLVerifyClient require #SSLVerifyDepth 10 # Access Control: # With SSLRequire you can do per-directory access control based # on arbitrary complex boolean expressions containing server # variable checks and other lookup directives. The syntax is a # mixture between C and Perl. See the mod_ssl documentation # for more details. #<Location /> #SSLRequire ( %{SSL_CIPHER} !~ m/^(EXP|NULL)/ \ # and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \ # and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} \ # and %{TIME_WDAY} >= 1 and %{TIME_WDAY} <= 5 \ # and %{TIME_HOUR} >= 8 and %{TIME_HOUR} <= 20 ) \ # or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/ #</Location> # SSL Engine Options: # Set various options for the SSL engine. # o FakeBasicAuth: # Translate the client X.509 into a Basic Authorisation. This means that # the standard Auth/DBMAuth methods can be used for access control. The # user name is the `one line' version of the client's X.509 certificate. # Note that no password is obtained from the user. Every entry in the user # file needs this password: `xxj31ZMTZzkVA'. # o ExportCertData: # This exports two additional environment variables: SSL_CLIENT_CERT and # SSL_SERVER_CERT. These contain the PEM-encoded certificates of the # server (always existing) and the client (only existing when client # authentication is used). This can be used to import the certificates # into CGI scripts. # o StdEnvVars: # This exports the standard SSL/TLS related `SSL_*' environment variables. # Per default this exportation is switched off for performance reasons, # because the extraction step is an expensive operation and is usually # useless for serving static content. So one usually enables the # exportation for CGI and SSI requests only. # o CompatEnvVars: # This exports obsolete environment variables for backward compatibility # to Apache-SSL 1.x, mod_ssl 2.0.x, Sioux 1.0 and Stronghold 2.x. Use this # to provide compatibility to existing CGI scripts. # o StrictRequire: # This denies access when "SSLRequireSSL" or "SSLRequire" applied even # under a "Satisfy any" situation, i.e. when it applies access is denied # and no other module can change it. # o OptRenegotiate: # This enables optimized SSL connection renegotiation handling when SSL # directives are used in per-directory context. #SSLOptions +FakeBasicAuth +ExportCertData +CompatEnvVars +StrictRequire <Files ~ "\.(cgi|shtml|phtml|php3?)$"> SSLOptions +StdEnvVars </Files> #<Directory "/var/www/cgi-bin"> # SSLOptions +StdEnvVars #</Directory> <Directory /var/www/x-itools> AddHandler cgi-script .cgi Options +ExecCGI SSLOptions +StdEnvVars </Directory> # SSL Protocol Adjustments: # The safe and default but still SSL/TLS standard compliant shutdown # approach is that mod_ssl sends the close notify alert but doesn't wait for # the close notify alert from client. When you need a different shutdown # approach you can use one of the following variables: # o ssl-unclean-shutdown: # This forces an unclean shutdown when the connection is closed, i.e. no # SSL close notify alert is send or allowed to received. This violates # the SSL/TLS standard but is needed for some brain-dead browsers. Use # this when you receive I/O errors because of the standard approach where # mod_ssl sends the close notify alert. # o ssl-accurate-shutdown: # This forces an accurate shutdown when the connection is closed, i.e. a # SSL close notify alert is send and mod_ssl waits for the close notify # alert of the client. This is 100% SSL/TLS standard compliant, but in # practice often causes hanging connections with brain-dead browsers. Use # this only for browsers where you know that their SSL implementation # works correctly. # Notice: Most problems of broken clients are also related to the HTTP # keep-alive facility, so you usually additionally want to disable # keep-alive for those clients, too. Use variable "nokeepalive" for this. # Similarly, one has to force some clients to use HTTP/1.0 to workaround # their broken HTTP/1.1 implementation. Use variables "downgrade-1.0" and # "force-response-1.0" for this. SetEnvIf User-Agent ".*MSIE.*" \ nokeepalive ssl-unclean-shutdown \ downgrade-1.0 force-response-1.0 # Per-Server Logging: # The home of a custom SSL log file. Use this when you want a # compact non-error SSL logfile on a virtual host basis. CustomLog logs/ssl_request_log \ "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b" </VirtualHost>

As you can see, we have decided that the DocumentRoot for the files of the X-Itools server is /var/www/x-itools, and the ServerAdmin is the user xitools we have created previously. You can change this if you want.

It means that all the files we will compile must be installed in the directory /var/www/x-itools.

Furthemore, don't forget to enable some options for the directory /var/www/x-itools, regarding the execution of the scripts. This is in the sub-section <Directory /var/www/x-itools> of the virtual host.

So, all is done for X-Itools over ssl.
Now, we will create another virtualhost for X-Itools server on usual http port 80.

Add the end of the httpd.conf file, just add this VirtualHost section:

<VirtualHost 62.50.65.20> ServerName x-itools.mydomain.com ServerAdmin xitools ErrorLog logs/x-itools.error_log TransferLog logs/x-itools.access_log DocumentRoot /var/www/x-itools <Directory /var/www/x-itools> AddHandler cgi-script .cgi Options +ExecCGI </Directory> </VirtualHost>

In this case, the X-Itools virtual host can be reached in a browser with the following URL only:

http://x-itools.mydomain.com

As usual, you can change the DocumentRoot directory and the ServerAdmin name. But if you have enabled X-Itools over SSL, the DocumentRoot directory must be exactly the same in the SSL VirtualHost and in the normal VirtualHost.

once you did all of this, you can save the changes in the httpd.conf file and exit vi.

We will not restart the web server now, because before, all the X-Itools binaries must be installed in the correct directory.

CREATE INITIAL WEB SERVER DIRECTORY FOR X-ITOOLS BINARIES:

As root, create the DocumentRoot directory hou've configured in the httpd.conf file:

#> mkdir /var/www/x-itools

That's it !!!

COMPILATION OF THE SOURCES:

Now, we will launch the compilation of the sources. It needs several steps:
- creation of the compile script
- installation of localisation files

The compile script is quite simple. Come back in the xitools user homedirectory:

#> cd /home/xitools/20010715_01

and create the following compile script:

#> vi compile

This script has the following format:

#!/bin/sh HOME=/home/xitools/20010715_01 SERVER=/var/www/x-itools INCLUDE="-I/usr/include/pgsql -I/usr/include/glib-1.2 -I/usr/lib/glib/include -I$HOME/lib " LIBPATH=/usr/lib OPT="-mcpu=i686 -O3 -g -fstrength-reduce -frerun-loop-opt -fexpensive-optimizations -fschedule-insns2 -funroll- loops -fomit-frame-pointer -malign-double -fno-strict-aliasing -malign-loops=2 -malign-functions=2 -DCPU=686 -f fast-math" echo "Compile shared library" #g++ $OPT -shared -Wl,-soname,libX-Itools.so.1 -L$LIBPATH -o/usr/lib/libI-tools.so.1.0 $HOME/lib/XItool_Biblio.C $HOME/lib/XItool_Biblio_AccessControl.C $HOME/lib/XItool_Biblio_LDap.C $HOME/lib/XItool_Biblio_Accounts.C $HOME/lib/XItool_Biblio_Base.C $HOME/lib/XItool_Biblio_CString.C $HOME/lib/XItool_Biblio_CTime.C $HOME/lib/XItool_Biblio_CTimeSpan.C $HOME/lib/XItool_Biblio_Cookie.C $HOME/lib/XItool_Biblio_Params.C $HOME/lib/XItool_Biblio_Profile.C $HOME/lib/XItool_Biblio_Transaction.C $HOME/lib/XItool_Biblio_List.C $HOME/lib/XItool_Biblio_XList.C $HOME/lib/XItool_Biblio_ConfigFile.C $INCLUDE -lpq++ -lglib -lldap #ldconfig -v #(cd /usr/lib; ln -s libX-Itools.so.1 libX-Itools.so) echo "Compile index.cgi" #g++ $OPT -L$LIBPATH -o$SERVER/index.cgi $HOME/src/index.C $INCLUDE -lpq++ -lX-Itools echo "Compile XItool_Actions.cgi" #g++ $OPT -L$LIBPATH -o$SERVER/XItool_Actions.cgi $HOME/src/XItool_Actions.C $HOME/src/XItool_Actions_Actions.C $INCLUDE -lpq++ -lX-Itools echo "Compile XItool_Admin.cgi" #g++ $OPT -L$LIBPATH -o$SERVER/XItool_Admin.cgi $HOME/src/XItool_Admin.C $INCLUDE -lpq++ -lX-Itools echo "Compile XItool_Agenda.cgi" #g++ $OPT -L$LIBPATH -o$SERVER/XItool_Agenda.cgi $HOME/src/XItool_Agenda.C $INCLUDE -lpq++ -lX-Itools echo "Compile XItool_Check.cgi" #g++ $OPT -L$LIBPATH -o$SERVER/XItool_Check.cgi $HOME/src/XItool_Check.C $INCLUDE -lpq++ -lX-Itools echo "Compile XItool_Contacts.cgi" #g++ $OPT -L$LIBPATH -o$SERVER/XItool_Contacts.cgi $HOME/src/XItool_Contacts.C $INCLUDE -lpq++ -lX-Itools echo "Compile XItool_Francs.cgi" #g++ $OPT -L$LIBPATH -o$SERVER/XItool_Francs.cgi $HOME/src/XItool_Francs.C $INCLUDE -lpq++ -lX-Itools echo "Compile XItool_Holidays.cgi" #g++ $OPT -L$LIBPATH -o$SERVER/XItool_Holidays.cgi $HOME/src/XItool_Holidays.C $INCLUDE -lpq++ -lX-Itools echo "Compile XItool_Menu.cgi" #g++ $OPT -L$LIBPATH -o$SERVER/XItool_Menu.cgi $HOME/src/XItool_Menu.C $INCLUDE -lpq++ -lX-Itools echo "Compile XItool_Password.cgi" #g++ $OPT -L$LIBPATH -o$SERVER/XItool_Password.cgi $HOME/src/XItool_Password.C $HOME/src/XItool_Password_PwdStack.C $INCLUDE -lpq++ -lX-Itools echo "Compile XItool_Ping.cgi" #g++ $OPT -L$LIBPATH -o$SERVER/XItool_Ping.cgi $HOME/src/XItool_Ping.C $INCLUDE -lpq++ -lX-Itools echo "Compile XItool_Tel.cgi" #g++ $OPT -L$LIBPATH -o$SERVER/XItool_Tel.cgi $HOME/src/XItool_Tel.C $INCLUDE -lpq++ -lX-Itools echo "Compile XItool_UserInfos.cgi" #g++ $OPT -L$LIBPATH -o$SERVER/XItool_UserInfos.cgi $HOME/src/XItool_UserInfos.C $INCLUDE -lpq++ -lX-Itools echo "Compile XItool_Visites.cgi" #g++ $OPT -L$LIBPATH -o$SERVER/XItool_Visites.cgi $HOME/src/XItool_Visites.C $INCLUDE -lpq++ -lX-Itools chown nobody:nobody $SERVER/*.cgi

Just change the variables at the beginning of the script. SERVER must be the DocumentRoot directory configured in the apache httpd.conf file, and HOME must be the directory where are localised all the sources.

In the rest of the script, you can see that each line is commented (start with #). It allows you to enable only the compilation of some scripts, and not others. But for the first compilation, all must be enabled: so, remove all the # at the beginning of each line, except the comments. To be clear, remove the # which is before each line starting by g++ , and at the beginning of the script only for the first compilation, remove the # of the lines regarding the compilation of the shared library, the ldconfig line, and the creation of the symbolic link on the library.

If you are a programmer, or if you update your CVS tree one day, you will have to recompile all (with shared library) or only the script you have modified. But in all cases, the ldconfig line and the line to create the symbolic link on the library must be done only ONCE.
Never change the end of the script, where we set correct permissions on the binaries.

After your changes, run the compile script to create the X-Itools server binaries in the DocumentRoot directory:

#> ./compile

if you don't have any errors, you should see the scripts in the /var/www/x-itools directory or whatever with the ls command:

#> ls -al /var/www/x-itools

After this, we can install the localisation for french (english is builtin). This is what we do with the command below (do a more msgfmt):

#> msgfmt -o /usr/share/locale/fr/LC_MESSAGES/X-Itools.mo po/fr_FR.po

Of course, if the directory of all your localisations is different on your system, modify the /usr/share/locale/fr path. This command should be OK for RedHat servers.

Last thing to do and only once, is to copy the contents of the WebPics directory of the CVS tree in the DocumentRoot directory:

#> cp /home/xitools/20010715_01/pixmaps/* /var/www/x-itools

This is to have the icons and pictures needed by the X-Itools scripts.

Now, we have to install and initialize the database.

INSTALL AND INITIALISE THE DATABASE:

The only one useable database for now is Postgresql 7.x.

You should have postgresql installed and running on the X-Itools server or on another remote server. Postgresql must be configured to allow connexions on a database named xitools comming from your X-Itools web server, even if the SQL server is the same as the DB server.

You will have to change or update the pg_hba.conf file to authorize such connexions.

copy the Database template of the CVS tree in the postgresql home directory (which is usually /var/lib/pgsql):

#> cp /home/xitools/20010715_01/xitools_template.out /var/lib/pgsql

and but the good rights on the file:

#> chown postgres:postgres /var/lib/pgsql/xitools_template.out

Login as your database user:

#> su - postgres $>

create the xitools database (postgresql must be running):

$> createdb xitools

run pgsql interface to create postgresql xitools users:

$> psql xitools xitools=#

now, create the user xitools:

xitools=# create user xitools with password 'xitools';

and create the user nobody:

xitools=# create user nobody with password 'xitools';

and exit pgsql interface:

xitools=# \q

now, initialize the xitools database:

$> psql -e xitools < xitools_template.out

The xitools database is now ready.

Don't forget to edit the file XItool_Biblio.H of the source tree to update some #define parameters according of the ip address of your database server. For now, such parameters are hard-coded directly in the sources. In the future, such parameters will be moved in the configuration file which will be read by the X-Itools binaries.

Normally, you are now completely ready to test the X-Itools server.

RESTART APACHE:

Before to use the X-Itools server for the first time, apache must be restarted. As root on a RedHat:

#> /etc/rc.d/init.d/httpd restart

You can check that all virtual hosts are correcly configured and recognised by Apache by typing:

#> httpd -S

it should give you the list of all configured VirtualHosts. X-Itools VirtualHosts should be in this list.

Now, you can open your browser and go on the X-Itools URL you have defined in the httpd.conf file, which should be something like: http://x-itools.mydomain.com

Don't forget to update your DNS or your hosts file with the X-Itools FQDN (x-itools.mydomain.com here).

INITIALIZE ROOT CRONTAB:

In order for the X-Itools server to perform automatic real-time tasks, like sending notifications, displaying E-post-its, monitoring machines, perform holiday calculations ans so on, the script XItool_Check.cgi must be run each 5 minutes by the root user. For this, just initialize the root crontab by adding the content of the file crontab.root to the already existing root crontab.

If there isn't anything in your root crontab (crontab -l doesn't display anything), then you can do like this:

#> crontab crontab.root

Otherwise, edit the crontab by typing the command crontab -e and add the content of the crontab.root file.

TEST THE X-ITOOLS SERVER:

if all goes well, the X-Itools login page is loaded into your browser. But because it is the first time you use it, no users exist in the X-Itools database, except one: the xitools system user.

So, login with user xitools, and password xitools.

If your login is successfull (should be), you have now the X-Itools menu bar on your screen, in a separate window. You can go in the Administrator module to add and manage X-Itools users and X-Itools server.

At first, we strongly recommand you to add another X-Itools administrator to avoid the use of the X-Itools system account you used above.

Refer to user documentation for further details
Enjoy ;-)