WEB2CS INSTALLATION GUIDE FOR XANDMAIL XandMail 32, rue de Cambrai 75019 PARIS - FRANCE Tel : +33 (0)1 40 388 700 - http://www.xandmail.com
TABLE OF CONTENTS 1. INSTALLING WEB2CS 3 1.1. RETRIEVING THE WEB2CS APPLICATION PACKAGE FROM THE XANDMAIL DOWNLOAD SITE 3 1.1.1. RETRIEVE THE LATEST INSTALLATION PACKAGE FROM THE XANDMAIL DOWNLOAD SITE 3 1.2. UNCOMPRESSING THE WEB2CS PACKAGE ON THE SERVER 3 1.2.1. CONNECT TO THE SERVER IN SSH AND CREATE AN EMPTY DIRECTORY IN WHICH THE APPLICATION WILL BE INSTALLED 3 1.2.2. UNCOMPRESS THE WEB2CS PACKAGE IN THIS NEW DIRECTORY 4 1.3. INSTALLING THE WEB2CS PACKAGE USING THE GRAPHICAL USER INTERFACE 5 1.3.1. DISPLAY THE INSTALLATION UI IN YOUR BROWSER 5 1.3.2. ACCEPT THE CONDITIONS OF USE AND CLICK NEXT STEP 5 1.3.3. DEFINE THE INSTALLATION PATHS AND CLICK NEXT STEP 6 1.3.4. DEFINE THE MESSAGING DOMAIN, THE IMAP4 AND SMTP SERVERS, AND THE ADMINISTRATOR S NAME AND CLICK NEXT STEP 7 1.3.5. INSTALLATION PROCEEDS 8 1.3.6. READ THE INSTRUCTIONS GIVEN IN THE LAST PAGE 9 1.4. INSTALLING THE WEB2CS PACKAGE IN COMMAND LINE MODE 10 1.4.1. CONNECT TO THE SERVER IN SSH AND GO TO THE DIRECTORY IN WHICH THE PACKAGE WAS UNCOMPRESSED 10 1.4.2. RUN THE INSTALL.SH INSTALLATION SCRIPT 10 1.4.3. PROVIDE THE HTTP SERVER NAME OR IP ADDRESS 10 1.4.4. PROVIDE THE ADMINISTRATOR S NAME 11 1.4.5. PROVIDE THE MESSAGING DOMAIN 11 1.4.6. PROVIDE THE IMAP4 SERVER S ADDRESS 11 1.4.7. PROVIDE THE IMAP4 SERVER S PORT NUMBER 11 1.4.8. INDICATE WHETHER THE IMAP4 SERVER REQUIRES A LONG LOGIN 12 1.4.9. PROVIDE THE SMTP SERVER S ADDRESS 12 1.4.10. INSTALLATION PROCEEDS 12 1.5. CONFIGURING THE APACHE SERVER FOR THE APPLICATION 13 1.6. USING THE WEB2CS APPLICATION 14 1.6.1. DISPLAY THE LOGIN PAGE 14 1.6.2. DISPLAY THE ADMINISTRATION INTERFACE 15 1.7. TROUBLESHOOTING 16 1.7.1. LOGIN DOES NOT WORK ON A 64 BITS SERVER 16 2. UNINSTALLING WEB2CS 17 2.1. UNINSTALLING WEB2CS FROM A DOMAIN 17 2
1. INSTALLING WEB2CS The Web2cs application has been packaged for installation on unix servers. 1.1. RETRIEVING THE WEB2CS APPLICATION PACKAGE FROM THE XANDMAIL DOWNLOAD SITE 1.1.1. RETRIEVE THE LATEST INSTALLATION PACKAGE FROM THE XANDMAIL DOWNLOAD SITE Type the following URL in your favorite browser: http://download.estore.xandmail.com/ Click on the «Free download» link of the «Product available for download» you want to download. If you come for the first time to the download site, you will be prompted to create your personal space. Otherwise, you will be asked to login to your personal space if you have not yet done so. When asked to open or save the free download, save the package in a temporary directory of your disk, for example /tmp. 1.2. UNCOMPRESSING THE WEB2CS PACKAGE ON THE SERVER 1.2.1. CONNECT TO THE SERVER IN SSH AND CREATE AN EMPTY DIRECTORY IN WHICH THE APPLICATION WILL BE INSTALLED Connect to your server in SSH. Go to the root directory of your website. cd [root path of your website] Make sure you are logged in with the user/group that is used by the Apache server. If not, do not forget to come back here after the installation and to do a global chown on the whole installation. Create a new (empty) directory that will receive the Web2cs application. mkdir [installation directory] In the screenshots, you will see this new directory as: development/eh/v4/xamupload 3
1.2.2. UNCOMPRESS THE WEB2CS PACKAGE IN THIS NEW DIRECTORY Uncompress the package in the empty directory cd [installation directory] tar xvzf /tmp/latest_installation_package.tar.gz 4
1.3. INSTALLING THE WEB2CS PACKAGE USING THE GRAPHICAL USER INTERFACE 1.3.1. DISPLAY THE INSTALLATION UI IN YOUR BROWSER Type the following URL in your browser: http://[root path of your website]/[installation directory]/install/ui/index.php 1.3.2. ACCEPT THE CONDITIONS OF USE AND CLICK NEXT STEP You must accept the conditions of use if you wish to use our application. 5
1.3.3. DEFINE THE INSTALLATION PATHS AND CLICK NEXT STEP The installation path, the user preferences folder path and the URL are already filled in using the installation directory information. You should not need to change them. 6
1.3.4. DEFINE THE MESSAGING DOMAIN, THE IMAP4 AND SMTP SERVERS, AND THE ADMINISTRATOR S NAME AND CLICK NEXT STEP The messaging domain is the email s right part, after the @ character (name@domain). The IMAP4 server will be used to retrieve messages from your mailbox and display those messages in the Web2cs user interface. You must provide the name or IP of the server, as well as the port in use. You must also indicate whether the IMAP4 server requires a login with a complete email address (name@domain) or accepts a login with a short email address (name). The SMTP server will be used to send messages from the Web2cs user interface. You must provide the name or IP of the server, as well as the port in use. The Administration account name is the email s left part, before the @ character (name@domain) of the account which will have administration permissions on the installed application. 7
1.3.5. INSTALLATION PROCEEDS The progress bas will show you the installation progress. Once it is finished, click Next Step. 8
1.3.6. READ THE INSTRUCTIONS GIVEN IN THE LAST PAGE The graphical part of the installation is finished. Read the instructions carefully and modify the Apache configuration to make your application work and be secure. See 1.5 Configuring the Apache server for the application for the instructions on how to modify the Apache configuration. 9
1.4. INSTALLING THE WEB2CS PACKAGE IN COMMAND LINE MODE 1.4.1. CONNECT TO THE SERVER IN SSH AND GO TO THE DIRECTORY IN WHICH THE PACKAGE WAS UNCOMPRESSED Connect to your server in SSH. Go to the root directory of the application. cd [root path of your website]/[installation directory] Go to the install sub-directory. cd install Make sure you are logged in with the user/group that is used by the Apache server. If not, do not forget to come back here after the installation and to do a global chown on the whole installation. 1.4.2. RUN THE INSTALL.SH INSTALLATION SCRIPT Run the installation script:./install.sh The script starts preparing the installation: * Copying binaries... * Building symlinks... * Creating user directories * Generate help pages... Done Launching configure script... 1.4.3. PROVIDE THE HTTP SERVER NAME OR IP ADDRESS * Please enter your HTTP server name or IP address linux23.xandmail.com/development/eh/v4/xamupload The HTTP server name corresponds to the URL you will type in the browser to access the login page of the application. 10
1.4.4. PROVIDE THE ADMINISTRATOR S NAME * Please enter the administrator's name (default: postmaster) If you do not want to change it, simply press Enter. The Administrator s account name is the email s left part, before the @ character (name@domain) of the account which will have administration permissions on the installed application. 1.4.5. PROVIDE THE MESSAGING DOMAIN * Please enter the email domain linux23.xandmail.com The messaging domain is the email s right part, after the @ character (name@domain). 1.4.6. PROVIDE THE IMAP4 SERVER S ADDRESS * Please enter your incoming mail server address (default: linux23.xandmail.com) If you do not want to change it, simply press Enter. The IMAP4 server will be used to retrieve messages from your mailbox and display those messages in the Web2cs user interface. You must provide the name or IP of the server. 1.4.7. PROVIDE THE IMAP4 SERVER S PORT NUMBER * Please enter the server's port number (default: 143) If you do not want to change it, simply press Enter. The IMAP4 server will be used to retrieve messages from your mailbox and display those messages in the Web2cs user interface. You must provide the port number of the server. 11
1.4.8. INDICATE WHETHER THE IMAP4 SERVER REQUIRES A LONG LOGIN * Does your IMAP4 server use a long login? (y/n) (long: user@linux23.xandmail.com, short: user) Answer y or n to indicate whether the IMAP4 server requires a login with a complete email address (name@domain) or accepts a login with a short email address (name). 1.4.9. PROVIDE THE SMTP SERVER S ADDRESS * Please enter your outgoing server address (default: linux23.xandmail.com) If you do not want to change it, simply press Enter. The SMTP server will be used to send messages from the Web2cs user interface. You must provide the name or IP of the server. 1.4.10. INSTALLATION PROCEEDS The installation script will now configure the application according to the information provided, try to start the reminder daemon and provide you with the instructions required for the daily cleanup of application temporary directories. 12
1.5. CONFIGURING THE APACHE SERVER FOR THE APPLICATION In order to make your installation work, you must modify the Apache configuration to declare the application and indicate that CGI binaries should be executed in its cgi-bin directory. Without this step, you will not be able to login to the application: <Directory "[root path of your website]/[installation directory]"> AllowOverride None Order Allow,Deny Allow from all DirectoryIndex index.php Options -Indexes </Directory> <Directory "[root path of your website]/[installation directory]/cgi-bin"> <IfModule mod_cgi.c> Options +execcgi <Files *> SetHandler cgi-script </Files> </IfModule> </Directory> In addition, you should add other instructions in order to make your installation secure, protecting several of the application s directories. All the necessary instructions for those 2 Apache configuration steps can be found in the content of the [root path of your website]/[installation directory]/vhost.conf file. You can copy its content into the Apache server s configuration file (httpd.conf), or you can more simply include this file in the Apache server s configuration file (use the Include [root path of your website]/[installation directory]/vhost.conf instruction). You will need to restart the Apache server once those configuration modifications are made. 13
1.6. USING THE WEB2CS APPLICATION 1.6.1. DISPLAY THE LOGIN PAGE Type the installation URL in your favorite browser. Type an email address and password that exist on your server and click on Login to use the application. The postmaster@[your domain] email address is configured to be the Web2cs administrator and has access to the administration interface. 14
1.6.2. DISPLAY THE ADMINISTRATION INTERFACE Type the installation URL, followed by /admin/index.html in your favorite browser. The postmaster@[your domain] email address is configured to be the Web2cs administrator and has access to the administration interface. In this administration interface, you will be able to: Replace the XandMail logo with your own logo Change the background color of the application Change the newsfeed URL to provide your own information to your users Manage the application s licence When you are through with your administrator configuration, clicking on the Web2.0 Communication Solution link on the login page will get you directly to the Web2cs login page. 15
1.7. TROUBLESHOOTING 1.7.1. LOGIN DOES NOT WORK ON A 64 BITS SERVER 32 bits application binaries cannot execute on 64 bits servers if they are not recognized as executable files. So on 64 bits servers, it is necessary to install some system libraries used by 32 bits applications, so that they will execute correctly. You can check whether the application will work or not by going to the cgi-bin directory and asking for the binaries version. Type:./webmail -id It should display the version and copyright notices. If that succeeds, there is nothing to do. If you get an error /lib/ld-linux.so.2: bad ELF interpreter, you need to install the libgcc, glibc, and maybe also the libstdc++ and libncurses libraries. The command to see which library is missing is: ldd webmail The command to find out in which package to find the missing library is: yum whatprovides [the library name] The command to install the missing package is: yum install [the package name] After you have installed all missing packages and ldd finds all the dynamically linked libraries, ask once again for the binaries version. If that succeeds, try to login again from the login page in your browser. 16
2. UNINSTALLING WEB2CS We really do hope that you will not need to uninstall our application, except maybe to replace it with a more recent version of our products 2.1. UNINSTALLING WEB2CS FROM A DOMAIN 1) Connect to your server 2) Stop the reminder process, if it runs 3) Remove the include instruction for the vhost.conf file from your Apache server configuration and restart it 4) Remove all the application files and directories The Web2cs application is now no longer present on the server. 17