WEB2CS INSTALLATION GUIDE

Transcription

1 WEB2CS INSTALLATION GUIDE FOR CPANEL / WHM XandMail 32, rue de Cambrai PARIS - FRANCE Tel : +33 (0)

2 TABLE OF CONTENTS 1. INSTALLING WEB2CS ADDING XANDMAIL AS A VENDOR CONNECT TO YOUR SERVER S ADMINISTRATION INTERFACE OPEN THE CPANEL MENU AND DISPLAY THE INSTALL CPADDONS PAGE INPUT XANDMAIL S VENDOR URL AND CLICK UPDATE VENDORS INSTALLING THE WEB2CS PACKAGE ON THE SERVER CHECK THE INSTALLED CHECKBOX CORRESPONDING TO THE WEB2CS APPLICATION AND CLICK ON THE UPDATE ADDON CONFIG BUTTON YOUR SERVER CONNECTS TO THE XANDMAIL SYNC SERVER AND RETRIEVES THE WEB2CS PACKAGE CLICK ON BACK TO DISPLAY THE CPADDONS LIST INSTALLING THE WEB2CS APPLICATION IN A DOMAIN CONNECT TO YOUR DOMAIN S ADMINISTRATION INTERFACE CLICK ON SUBDOMAINS IN THE DOMAINS SECTION CREATE AN XMAIL SUBDOMAIN OF YOUR DOMAIN CLICK ON HOME THEN ON SITE SOFTWARE IN THE SOFTWARE/SERVICES SECTION XANDMAIL S APPLICATIONS ARE LISTED IN THE CPADDON SCRIPTS CLICK ON WEB2CS SELECT THE SUBDOMAIN IN WHICH TO INSTALL WEB2CS CLICK INSTALL CREATING THE POSTMASTER@DOMAIN ACCOUNT IF IT DOES NOT YET EXIST ADDING SECURITY TO THE INSTALLATION AND SETTING UP MULTIPLE DOMAIN MANAGEMENT GET THE INSTRUCTIONS FROM THE INSTALLATION.LOG FILE RESTART APACHE CHECKING THE POSTMASTER WEBMAIL ACCOUNT DISPLAY THE LOGIN PAGE DISPLAY THE ADMINISTRATION INTERFACE HIDE THE INSTRUCTIONS ON THE LOGIN PAGE MANAGING MULTIPLE DOMAINS ON THE SAME INSTALLATION PRESENTATION ONE INSTALLATION FOR SEVERAL DOMAINS, EACH WITH ITS OWN LEVEL OF FEATURES ONE INSTALLATION FOR SEVERAL DOMAINS, ALL WITH THE SAME LEVEL OF FEATURES ADD A NEW DOMAIN FOR ANOTHER CUSTOMER LINK AN XMAIL SUBDOMAIN OF THIS NEW DOMAIN TO THE WEB2CS INSTALLATION 28 2

3 2.4. RESTART THE APACHE SERVER CREATE THE ACCOUNT ACCESS THE WEB2CS LOGIN PAGE FOR DOMAIN1.NET LOGIN TO XMAIL.DOMAIN1.NET AS POSTMASTER REMOVING A DOMAIN ALIAS FROM THE INSTALLATION MAKING A BACKUP OF THE DOMAIN SPECIFIC DATA USING THE WEB2CS APPLICATION ACCESS THE MAIN INTERFACE DISPLAY THE LOGIN PAGE CHANGE THE APPLICATION COLORS AND LOGO Upload a logo Change the background color Is the customization valid for all domains? APPLICATION CAPABILITIES: LIMITED OR NOT? INSTALL AN UPGRADE LICENSE Is the license valid for all domains? CHANGE THE RSS FEED Is the RSS feed valid for all domains? TROUBLESHOOTING UPGRADING XANDMAILWEB2CS LOGIN DOES NOT WORK ON A 64 BITS SERVER UNINSTALLING WEB2CS UNINSTALLING WEB2CS FROM A DOMAIN REMOVING WEB2CS FROM THE SERVER 50 3

4 1. INSTALLING WEB2CS The Web2cs application has been packaged for installation on servers managed with cpanel s Web Host Manager ADDING XANDMAIL AS A VENDOR The first step to execute is to add XandMail as a vendor on your server CONNECT TO YOUR SERVER S ADMINISTRATION INTERFACE The connection is normally done in HTTPS, using the port

5 OPEN THE CPANEL MENU AND DISPLAY THE INSTALL CPADDONS PAGE 5

6 INPUT XANDMAIL S VENDOR URL AND CLICK UPDATE VENDORS XandMail s Vendor information URL is: 6

7 XandMail is now listed as a Vendor in the same page, with in the Webmail category the Web2cs product: 7

8 1.2. INSTALLING THE WEB2CS PACKAGE ON THE SERVER CHECK THE INSTALLED CHECKBOX CORRESPONDING TO THE WEB2CS APPLICATION AND CLICK ON THE UPDATE ADDON CONFIG BUTTON 8

9 YOUR SERVER CONNECTS TO THE XANDMAIL SYNC SERVER AND RETRIEVES THE WEB2CS PACKAGE 9

10 CLICK ON BACK TO DISPLAY THE CPADDONS LIST Now XandMail s Web2cs application is checked, indicating that it is available for installation on a domain. 10

11 1.3. INSTALLING THE WEB2CS APPLICATION IN A DOMAIN CONNECT TO YOUR DOMAIN S ADMINISTRATION INTERFACE The connection is normally done in HTTPS, using the port

12 CLICK ON SUBDOMAINS IN THE DOMAINS SECTION 12

13 CREATE AN XMAIL SUBDOMAIN OF YOUR DOMAIN Web2cs should be installed in a separate location. In order to avoid blocking a whole domain name, and also to keep a consistent way of calling the Webmail in all domains, it should be installed in a subdomain and not in a subdirectory of a domain. So each domain will call Web2cs using the following URL: name] 13

14 The subdomain is now created. 14

15 CLICK ON HOME THEN ON SITE SOFTWARE IN THE SOFTWARE/SERVICES SECTION 15

16 XANDMAIL S APPLICATIONS ARE LISTED IN THE CPADDON SCRIPTS Please take note of the information available in the product description: It runs only on Linux platforms. An installation log file called installation.log (or upgrade.log in case of upgrade) is created during installation at the root of the installed site. Please consult it after installation, as it contains instructions on how to make your installation secure. 16

17 CLICK ON WEB2CS 17

18 SELECT THE SUBDOMAIN IN WHICH TO INSTALL WEB2CS Make sure to select the name] subdomain that was previously created. Leave the Installation URL input field empty. Check the other installation parameters for correctness: Input the IMAP server name and port. If your mailboxes already have specific system folder names for Draft, Sent, Trash and Spam folders, input them so that Web2cs will use them instead of creating different ones. Keep postmaster as the administrator account name, unless you wish to use another mailbox name (in this case, you will need to create the mailbox accordingly in the next step). Note: If you will be hosting and managing in a single installation several domains (see the domain management section below), remember that you will have to create a mailbox with this administrator address for each managed domain. Input the SMTP server name and port. Choose the default language and timezone. 18

19 CLICK INSTALL After installation, the access URL is indicated and you can use the application, BUT the installation is not complete yet You need to add some configuration rules to the Apache server in order to prevent users from accessing and breaking your server, as well as to enable the use of multiple domains in this installation. 19

20 1.4. CREATING THE ACCOUNT IF IT DOES NOT YET EXIST Click on Home, then on Accounts in the Mail section. Create the account. 20

21 1.5. ADDING SECURITY TO THE INSTALLATION AND SETTING UP MULTIPLE DOMAIN MANAGEMENT GET THE INSTRUCTIONS FROM THE INSTALLATION.LOG FILE Connect to your server using SSH. Go to the xmail subdirectory which hosts the installed Web2cs application. Read the installation.log file. The instructions indicated in the file are: In order to make your installation work and be secure, you must manually add the following line: Include /home/[% username %]/public_html/xmail/vhost.conf in a /usr/local/apache/conf/userdata/std/2/[% username %]/vhost.conf file which will be included in your Apache configuration. After that, call the command: /scripts/ensure_vhost_includes --all-users Follow these instructions RESTART APACHE The previous call to the ensure_vhost_includes command should normally restart the Apache server. If, however, it did not do so and did not display any error which would explain why Apache was not restarted, then restart Apache now. 21

22 1.6. CHECKING THE POSTMASTER WEBMAIL ACCOUNT DISPLAY THE LOGIN PAGE Type the installation URL in your favorite browser. Type the postmaster address and password that was previously created and click on Login to use the application. The application should start. 22

23 The domain] (unless you changed postmaster for another value in the installation parameters) address is configured to be the Web2cs administrator and has access to the administration menu. Logout 23

24 DISPLAY THE ADMINISTRATION INTERFACE The application administrator defined during the installation process ( postmaster by default) has access to the administration interface, using his login and password. The URL of that administration interface is indicated in the installation instructions page, but will no longer be available in the user interface once the installation instructions page is hidden (which is the next step). If you forget it, however, it will still be indicated in the installation.log file located in the root directory of the installed application. The URL is [application installation URL]/admin/index.html. 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 license The pages available in the administration interface are also accessible to the administrator in the Web2cs main interface. 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. 24

25 HIDE THE INSTRUCTIONS ON THE LOGIN PAGE Click on the Web2.0 communication Solution link to get back to the login page. Now that the login works and you have added the security configuration parameters to the vhost.conf file, you can hide the installation instructions page by clicking on the When the login works correctly, click here to hide these instructions. link. Hiding the installations instructions page will display in its place the normal login page. 25

26 2. MANAGING MULTIPLE DOMAINS ON THE SAME INSTALLATION 2.1. PRESENTATION ONE INSTALLATION FOR SEVERAL DOMAINS, EACH WITH ITS OWN LEVEL OF FEATURES It is possible to use a single installation to manage several domains. In this type of installation, you install the application only once, for the first domain. Each subsequent domain can be added / removed through the configure-domain.sh script available in the root directory of the installed Web2cs application (/home/[account name]/public_html/xmail). Each domain needs its own license to enable the features required for that domain, but disk space is used sparingly as only the domain specific files are separated for each domain: 26

27 ONE INSTALLATION FOR SEVERAL DOMAINS, ALL WITH THE SAME LEVEL OF FEATURES It is possible to use a single installation to manage several domains. In this type of installation, you install the application only once, for the first domain. Each subsequent domain can be added / removed through the configure-domain.sh script available in the root directory of the installed Web2cs application (/home/[account name]/public_html/xmail). A global license is installed to enable a set of features which will be available to all the domains managed by that installation. Only the domain specific files are separated for each domain: 27

28 2.2. ADD A NEW DOMAIN FOR ANOTHER CUSTOMER The installation of the Web2CS application is made on the primary domain. This can be a valid domain managed by one of your customers, or it can be restricted to your own use as the server administrator. We recommend this second solution, as it will prevent your customer from putting in peril (voluntarily or by mistake) the Web2CS application used by other domains than his own. In order for each domain to have his private access to Web2CS, you will have to create a domain alias pointing to the primary Web2CS domain for each of the customer domains. For example, you have installed on xmail.domain.com. Your first customer purchases domain1.net from you. You will create the domain called domain1.net to host his website and a subdomain called xmail.domain1.net (or any other name that you fancy) to be the web2cs entry point. You will provide this xmail.domain1.net subdomain to the Web2CS service as a domain alias LINK AN XMAIL SUBDOMAIN OF THIS NEW DOMAIN TO THE WEB2CS INSTALLATION Connect to your server using SSH, using the account which owns the Web2cs installation. Go to the xmail subdirectory which hosts the installed Web2cs application. The configure-domain.sh script manages the installation and removal of the domain aliases: Usage:./configure-domain.sh (install remove) domain_alias Execute the script to link the xmail.domain1.net alias:./configure-domain.sh install xmail.domain1.net 28

29 2.4. RESTART THE APACHE SERVER You need to restart the Apache server for the new domain alias to be known through HTTP requests. In the WebHost Manager, expand the Restart Services menu and Click on HTTP Server (Apache). Confirm the restart request. 29

30 2.1. CREATE THE ACCOUNT Connect to your server using SSH, using the account which owns the new domain domain1.net. Click on Accounts in the Mail section. Create the account. Create in the same way mailboxes for all the users of that domain. 30

31 2.2. ACCESS THE WEB2CS LOGIN PAGE FOR DOMAIN1.NET Try the URL of the new domain alias : The Web2cs login page should be displayed. 31

32 2.3. LOGIN TO XMAIL.DOMAIN1.NET AS POSTMASTER Input as the login name. Input the password. Choose your preferred language. Click Login. If the login works fine, send a message to yourself to check that the messaging operations are also working. The message should appear in your Inbox. 32

33 2.4. REMOVING A DOMAIN ALIAS FROM THE INSTALLATION Removing a domain alias from the installation will delete the entire user data associated to that domain alias. Connect to your server using SSH, using the account which owns the Web2cs installation. Go to the xmail subdirectory which hosts the installed Web2cs application. The configure-domain.sh script manages the installation and removal of the domain aliases: Usage:./configure-domain.sh (install remove) domain_alias Execute the script to link the xmail.domain1.net alias:./configure-domain.sh remove xmail.domain1.net 2.5. MAKING A BACKUP OF THE DOMAIN SPECIFIC DATA To backup all the domain specific data of your web2cs installation, simply backup the domains directory. 33

34 3. USING THE WEB2CS APPLICATION 3.1. ACCESS THE MAIN INTERFACE DISPLAY THE LOGIN PAGE Type the installation URL in your favorite browser. Type an address and password that exist on your domain and click on Login to use the application. 34

35 CHANGE THE APPLICATION COLORS AND LOGO In order to change the application colors and logo, you must login either to the Web2cs or its administrator interface using the administrator account ( domain name] by default). In the application menu (located on the left), click on Administration. You will see the access points to the three administration pages: License Management Customization Manage RSS feed 35

36 Click on Customization You can in this page: Upload a logo Change the background color of the interface 36

37 UPLOAD A LOGO The format of the image for the logo must be in png format (.png extension) and not exceed the size of 100 KB. You can replace the logo for: the Web login page the Web interface (Web2cs and HTML) Mobile interface You have to respect the following rules: The name for the Web login page logo must be "logo_big.png" The name for the Web interface logo must be "logo_small.png" and the dimension should be less than 80x250 pixels The name for the mobile interface logo must be "logo_mobile.png" and the dimension should be less than 46x150 pixels Start by uploading the logo for the Web interface (logo_small.png) as it will immediately appear at the top of the page. 37

38 If the new logo does not immediately appear, finish uploading the other logo files, then logout, empty the cache of your browser and re-login. In the same way, upload then the Web login page logo and the Mobile interface logo. To see the Web login page s new logo, you will need to logout, empty your browser cache and reload the login page. To see the Mobile interface logo, you will need to connect with a Mobile phone. 38

39 CHANGE THE BACKGROUND COLOR In the customization administration page, you can also change the background color of the application to better match your company colors. You can either clear on the pre-defined colored squares (pink, yellow, green, blue, grey) or you can specify your own color using the standard hexadecimal color format: #RRGGBB (RR = red, GG = green, BB = blue each of the 3 colors can take hexadecimal values between 00 and FF). If you specify your own color, click on the Preview link to see the result: Once you are happy with the chosen color, do not forget to click on the Save button 39

40 IS THE CUSTOMIZATION VALID FOR ALL DOMAINS? Each account has access to the customization menu and can change the logos and background colors of his own domain. Here is an example: 40

41 APPLICATION CAPABILITIES: LIMITED OR NOT? The free basic version of the application is limited to using the messaging functions together with the address book. But the Web2cs application is capable of much more which, as service administrator, you might think about providing to your users. Thus the administrator account can see the full set of modules and options in the menus. Each of these modules or options can be enabled with a specific license, without having to reinstall the application. When you browse through a disabled module in the menu, a popup will indicate it and provide at the same time links to more information and pricing on that module. 41

42 Of course, a regular (non-administrator) user will not see those modules in the menu as long as they are disabled. So the application capabilities are limited in the free basic pack, but can easily be augmented by purchasing an upgrade license. 42

43 INSTALL AN UPGRADE LICENSE In order to install an upgrade license, you must login either to the Web2cs or its administrator interface using the administrator account ( postmaster by default). In the application menu (located on the left), click on Administration. You will see the access points to the three administration pages: License Management Customization Manage RSS feed Click on License Management. In this page, you can see which type of license you have purchased (Free basic license by default), the numbers of users available, which products are being used and when the license will expire. 43

44 When you receive an upgrade license, simply come to this page, click on the Upload a license file button and choose the part00.dat file you received after your purchase. A popup will list the content of the new license, waiting for your confirmation to apply the new license file. Once you click on the Apply license file button, the new license is installed. Logout and login again to have the application use the new license. 44

45 IS THE LICENSE VALID FOR ALL DOMAINS? The license is by default only valid for one domain. That domain is indicated in the popup showing the content of the new license and, after it is installed, in the license management page. To purchase a single license valid for all the domains of a single installation, you will have to provide an installation ID which can be found in the license management page: 45

46 CHANGE THE RSS FEED In order to change the RSS feed, you must login either to the Web2cs or its administrator interface using the administrator account ( postmaster by default). In the application menu (located on the left), click on Administration. You will see the access points to the three administration pages: License Management Customization Manage RSS feed Click on Manage RSS feed. Provide a new RSS feed URL. Click Save. The RSS feed is updated. Go to the Desktop page to see the new RSS feed. 46

47 IS THE RSS FEED VALID FOR ALL DOMAINS? No. The RSS feed is valid for one domain only. 47

48 3.2. TROUBLESHOOTING UPGRADING XANDMAILWEB2CS If you have a previously installed XandMailWeb2cs version, your users already have address book data and will want to keep their contacts in the new XandMailWeb2cs V4 for POA version. Follow these steps to upgrade your installation: 1. Backup the user data from the existing installation The user data is located in subfolders of the domains directory. Make a copy or a compressed file of the content of the domains directory. Make sure to announce to your users that their address book data will be copied at that time, so that they will not add or modify them afterwards 2. Install the new version of XandMailWeb2cs V4 for POA You should install in a new directory if you do not want to interrupt the service. This way, your users can keep working with the previous version while you prepare the new version. If you wish to install in the same directory, the service will be interrupted during the time it will take to make the installation. You must first uninstall the previous version (after making a backup of the domains directory) before installing the new version in the same location. 3. Copy the user data on the new installation Copy the content of the domains directory, taken from the previous installation, into the domains directory of the new installation. Make sure to keep the directory and file permissions as they were in the previous installation. 4. Update the Apache configuration includes on the new installation Include all the vhost_domain.conf filesfound under the domains subdirectories in the vhost.conf of the new installation 48

49 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. 49

50 4. 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 4.1. UNINSTALLING WEB2CS FROM A DOMAIN 1) Connect to your server using SSH 2) Remove the /usr/local/apache/conf/userdata/std/2/[% username %]/vhost.conf file 3) Call the command: /scripts/ensure_vhost_includes --all-users to synchronize the Apache configuration 4) Connect to your domain s administration interface 5) Click on site software in the Software/Services section 6) Click on Web2cs 7) At the bottom of the page, choose the installation to remove and click on Uninstall 8) Confirm the request to uninstall the application 4.2. REMOVING WEB2CS FROM THE SERVER 1) Connect to your server s administration interface 2) Open the cpanel menu and display the Install cpaddons page 3) Uncheck the XandMail Webmail Web2cs application 4) Click on the Update Addon Config button 5) Click Back The Web2cs application is now no longer available for installation. If you have uninstalled all instances of the Web2cs application, you can also: 6) Click on the Completely Remove link presented beside the Web2cs application name The Web2cs application is now no longer present on the server. 50