Installing Sugar on IBM i

    Overview

    This KB article discusses installation, configuration, and tuning of SugarCRM on the IBM i platform, formerly known as i5/OS or OS/400.

    Prerequisites

    SugarCRM on the IBM i OS requires the installation of Zend Server for IBM i. For more information on Zend Server, visit the Zend Server web page. For instructions on the installation of Zend Server, see Zend Server documentation.

    Install the Zend Server and apply appropriate FastCGI Program Temporary Fixes (PTFs) on your IBM i system.

    V6R1
    SI43224 – HTTPSVR – FastCGI Dynamic setting fix
    SI43243 – OSP-PASE Update FastCGI server support for PASE for i

    V7R1
    SI43222 – HTTPSVR – FastCGI Dynamic setting fix
    SI43244 – OSP-PASE Update FastCGI server support for PASE for i

    SugarCRM prerequisites for IBM i system are automatically met (Apache, PHP, FastCGI, MySQL, Zend Server) once the Zend Server and the PTFs are successfully installed.

    Installing Sugar

    Access the PASE environment where the Zend Server is installed and copy files to it to install SugarCRM on the IBM i. You need to thoroughly understand how to access and use the PASE environment within the IBM i to successfully install and configure SugarCRM. Refer to the IBM i Infocenter and search for PASE.
    Follow the steps listed below to install SugarCRM:

    1. Access the PASE environment by one of the following methods:
      • SSH Connection (requires the SSHD TCPIP server running on the IBM i OS)
      • IBM System i Navigator
      • IBM i command CALL QP2TERM
    2. Copy files to the IBM i IFS (Integrated File System) directory where the PASE environment can access them, by one of the following methods:
      • Windows Drive Mapping – map the IFS directory that has been shared through IBM System i Navigator to an MS Windows drive
      • SSH Copy (SCP)
    3. Copy and unarchive the downloaded Sugar-XXX.zip to the directory:
      /www/zendsvr/htdocs/SUGARCRM_DIRECTORY
      Note: Third-party utilities provide zip/unzip functionality within the IBM i PASE environment. Unarchive the SugarCRM zip file on a MS Windows machine and copy the files from Windows to the IBM i machine if the zip utility is not installed on the IBM i. Due to the large number of files within the SugarCRM zip file, this can be a time-intensive process. Installing the zip utility on the IBM i machine is highly recommended. Download is available at: http://www.easy400.net/zip/html/page1.htm
    4. Confirm that the SUGARCRM_DIRECTORY is owned by the HTTP server user – qtmhhttp from the IBM i PASE environment.
    5. Use chown –R qtmhhttp SUGARCRM_DIRECTORY to change ownership, if required.
    6. Ensure that you have configured MySQL and Zend Server/Apache/PHP with minimal recommended settings, before continuing with the SugarCRM install.
    7. Use the GO ZENDSVR/ZSMENU command in the Zend Server Menu to restart Apache/Zend Server and MySQL.

    Zend Server and PHP Configuration

    1. Increase PHP file upload size limit and PHP memory allocation for SugarCRM installation via the Zend Server Web UI (http://<yourIBMiServer>:10088/ZendServer).
      Select the Directives tab within the Server Setup tab and perform the following:
      • memory_limit – set to 40M or above
      • upload_max_filesize – set to 6M or above
    2. Configure the Zend Optimizer+ for SugarCRM usage via the Zend Server Web UI (http://<yourIBMiServer>:10088/ZendServer).After restart, Zend Optimizer+ within Zend Server checks PHP file changes every 10 minutes. Note: Set this value to 10 minutes for optimal SugarCRM performance on the IBM i.
      1. Verify that the Zend Optimizer+ component is set to On in the Server Setup tab.
      2. Click the Configure link in the Directives column to display the list of Optimizer+ directives.
      3. Set the value of zend_optimizerplus.revalidate_freq to 600 (seconds).
    3. Turn off Zend Optimizer+ for the custom working files used by Module Builder.After Zend Server restart, the Sugar Module Builder working directory is now ignored by Optimizer+. Note: This Zend Server configuration is necessary to prevent errors when using Sugar Module Builder.
      Any future SugarCRM configuration changes made in Studio or Module Builder will require clearing the SugarCRM cache for Zend Optimizer+ to recognize the new SugarCRM configuration files. To do this, navigate within the SugarCRM Admin interface to the Repair screen and click Quick Repair and Rebuild.
      1. Create a blacklist.txt file using a text editor. For example, /www/zendsvr/etc/blacklist.txt
      2. Write the full pathname to the following directory and files into this blacklist file (ignored by the Optimizer+). Each entry must be on a new line in the file.
        • config.php- For example, the path name would be
          /www/zendsvr/htdocs/SUGARCRM_DIRECTORY/config.php
        • config_override.php- For example, the path name would be
          /www/zendsvr/htdocs/SUGARCRM_DIRECTORY/config_override.php
        • custom/modulebuilder – For example, the directory path would be
          /www/zendsvr/htdocs/SUGARCRM_DIRECTORY/custom/modulebuilder/
      3. Verify that the Zend Optimizer+ component is set to On in the Server Setup tab.
      4. Click the Configure link in the Directives column to display the list of Optimizer+ directives.
      5. Locate the directive zend_optimizerplus.blacklist_filename.
      6. Specify the full path to the blacklist.txt file location. For example:
        zend_optimizerplus.blacklist_filename =/www/zendsvr/etc/blacklist.txt

    After Zend Server restart, the Sugar Module Builder working directory is now ignored by Optimizer+. Note: This Zend Server configuration is necessary to prevent errors when using Sugar Module Builder.
    Any future SugarCRM configuration changes made in Studio or Module Builder will require clearing the SugarCRM cache for Zend Optimizer+ to recognize the new SugarCRM configuration files. To do this, navigate within the SugarCRM Admin interface to the Repair screen and click Quick Repair and Rebuild.

    MySQL Configuration

    Follow the steps listed below to configure MySQL:

    Note: Other MySQL storage engines are not supported for SugarCRM on the IBM i. Also, if the Zend Server Menu is used to start/stop MySQL, the my.cnf folder should be owned by the mysql user and its permissions should be set to 664 (not world-writable).

    1. Set the default MySQL storage engine to InnoDB for optimum performance. The MySQL configuration file is located in /usr/local/mysql/bin/my.cnf
    2. Add the default-storage-engine=innodb parameter to the [mysqld] section of my.cnf.
    3. Restart MySQL.

    Apache and FastCGI Configuration

    Default Apache configuration is sufficient for SugarCRM installation on IBM i. Tuning of the Apache web server is necessary for production use.

    1. Increase memory available to the process by adding the following to the end of fastcgi.conf file in FastCGI.conf located in /var/zendsvr/conf/fastcgi.conf:
      SetEnv=”LDR_CNTRL=MAXDATA=0×40000000″The complete file will look similar to this:
      ; Static PHP servers for default user
      Server type=”application/x-httpd-php”
      CommandLine=”/usr/local/ZendSvr/bin/php-cgi.bin” StartProcesses=”1″
      SetEnv=”LIBPATH=/usr/local/ZendSvr/lib” SetEnv=”PHPRC=/usr/local/ZendSvr/etc/” SetEnv=”PHP_FCGI_CHILDREN=300″
      SetEnv=”PHP_FCGI_MAX_REQUESTS=10000″ ConnectionTimeout=”600″ RequestTimeout=”600″ SetEnv=”CCSID=819″ SetEnv=”LANG=en_US” SetEnv=”INSTALLATION_UID=20110406044848981813″ SetEnv=”LDR_CNTRL=MAXDATA=0×40000000″
    2. Complete the prerequisites.
    3. Go to the SugarCRM URL. By default, it is http://servername:10088/ SUGARCRM_DIRECTORY.
    4. Start the normal Sugar installation.

    Scheduler

    SugarCRM scheduler requires execution of the cron.php file at 1 minute intervals. In a Unix environment, this is accomplished via the cron system utility. For the IBM i, the Zend Server Job Queue is used. A new recurring job must be created with a 1 minute interval and the URL to the SugarCRM cron.php file in the Zend Server UI. By default, the URL is: http://servername:10088/SUGARCRM_DIRECTORY/cron.php

    Performance Monitoring and Tuning

    SugarCRM on IBM i tuning requires adjusting several key parameters in IBMi, Apache, FastCGI, and MySQL to match workloads.

    IBMi WRKSYSSTS

    Maximize the available Memory and Max Active threads to improve SugarCRM performance. Use the wrksyssts command to monitor and tune these parameters.

    The following values are important for optimal SugarCRM performance:

    • Sys Pool – System Pool the Zend Server is in. By default, Zend Server is in Pool 2, Base Pool.

    Note: Other memory pools can be adjusted to increase the size of Memory Pool 2, o. For example, changing pool 4 from 1024MB to 500MB increases pool 2 automatically. Whatever memory is not allocated to an individual pool will be given to the base pool 2.

    • Pool Size – Memory available to the pool. Add memory must to the pool if Non-DB Pages and Faults increase, or report above zero consistently.
    • Max Active – This controls max active threads, and should be increased until the Wait to Ineligible (state transition) column is zero.

    The system needs more memory if you notice high paging and page fault values. SugarCRM performance is not optimal if the system is paging and no more memory is available.

    If the partition is dedicated to SugarCRM:

    • Memory auto-tuning can be disabled via wrksysval qpfradj
    • Paging algorithm set to calc (and not fixed as per default)

    IBMi WRKSYSACT

    Wrksysact command is similar to Top in Unix systems or Task Manager in Windows. Applications consuming the CPU can be monitored and traced from here.

    Set the to auto-refresh on 1 second interval to see what consumes your CPU during system activity. If you notice 100% CPU utilization, you need to dedicate more CPUs to this partition.

    IBMi WRKACTJOB SBS

    Wrkactjob SBS enables you to check detailed information about a specific subsystem and the processes it has spawned. For example, wrkactjob sbs(qhttpsvr) displays all HTTP Server processes. Use the F11key to review different information screens.

    MySQL

    Use the phpMyAdmin included with the Zend Server web UI to get an overall status of your MySQL performance.

    1. Click on the phpMyAdmin link on the Zend Server main screen.
      The phpMyAdmin Status tab displays mySql performance triggers. phpMyAdmin highlights suggested tuning parameters.
    2. Adjust MySQL max connections for the maximum number of concurrent users in your system. In my.cnf [mysqld] section set:
      max_connections = xxx
    3. Increase buffer sizes and table caches if you are running a high-load system with a large data set, to improve performance.
      See below for a sample my.cnf file tuned for a system with a large amount of RAM (notice innodb_buffer pool_size is set to 8GB of ram)
    [mysqld]
     datadir = /usr/local/mysqldata
     default-storage-engine=INNODB
     innodb_buffer_pool_size = 8048M
     innodb_flush_log_at_trx_commit=0
     key_buffer_size = 2024M
     max_connections = 500
     max_heap_table_size = 1024M
     myisam_sort_buffer_size = 50M
     net_read_timeout = 60
     query_cache_size = 1024M
     skip-locking
     slow_query_log = 0
     sort_buffer_size = 4024K
     table_open_cache = 10024
     thread_cache_size = 16
     tmp_table_size = 1536M
     user = MYSQL

    Apache

    1. Configure IBM i Apache by one of the following methods:
      • Accessing the IBM i http server gui located at: http://servername:2001/HTTPAdmin
      • Editing the httpd.conf in /www/zendsvr/conf
    2. Restart the apache server via the Zend Menu or HTTPD server console.
    3. Adjust the ThreadsPerChild settings to reflect the maximum number of concurrent users for the system, plus 10% overhead.

    Zend Server and FastCGI

    Zend Server (Out of the box) is configured for good overall performance. FastCGI.conf controls the number of concurrent requests that the Zend Server can process. Set this number to reflect the maximum concurrent users for the system. It is recommended to set the StartProcesses=”1″ and vary SetEnv=”PHP_FCGI_CHILDREN=XXX” to match maximum concurrent users.

    See below for a sample fastcgi.conf for a large number of concurrent users. Note the increase in Timeout values to prevent php processes being stopped in case of slow execution under load spikes.

    ; Static PHP servers for default user
     Server type="application/x-httpd-php"
     CommandLine="/usr/local/ZendSvr/bin/php-cgi.bin"
     StartProcesses="1″
     SetEnv="LIBPATH=/usr/local/ZendSvr/lib"
     SetEnv="PHPRC=/usr/local/ZendSvr/etc/"
     SetEnv="PHP_FCGI_CHILDREN=500″
     SetEnv="PHP_FCGI_MAX_REQUESTS=10000″ ConnectionTimeout="300″
     RequestTimeout="600″
     SetEnv="CCSID=819″
     SetEnv="LANG=en_US"
     SetEnv="INSTALLATION_UID=20110420110611139606″
     SetEnv="LDR_CNTRL=MAXDATA=0×40000000″
     ; Where to place socket files
     IpcDir /www/zendsvr/logs

    Capacity Planning

    The following tables can be used as guidelines to approximate resources required for deploying SugarCRM. Performance will vary depending on end-user activities and data sizes.

    Note: A typical SugarCRM system sees 20% concurrency. That means a 100 named user system (i.e. 100 users with login credentials) will typically see on average 20 users accessing the system concurrently at peak load times.

    Power 550 Express

    Maximum Named Users
    (Power6, 550 Express)
    Maximum Concurrent Users (Power6, 550 Express) Cores RAM
    1,000 100 2 8 GB
    1,500 300 6 16 GB

    Power 740 Express

    Maximum Nammed Users Maximum Concurrent Users Cores RAM
    50 10 1 2 GB
    250 50 1 4 GB
    850 170 2 8 GB
    1,250 250 4 16 GB

    It is highly recommended that you use the IBM Performance Capacity and Workload Sizing tool, IBM Systems Workload Estimator, if other applications run in the same partition and additional resources required for SugarCRM need to be evaluated and estimated. Performance data can be collected in the existing environments and fed directly into the WLE tool for further extrapolations. The WLE tool and more information about workload sizing are available at:
    http://www-912.ibm.com/wle/EstimatorServlet?

    Additional Resources

    IBMi performance tuning
    http://publib.boulder.ibm.com/infocenter/iseries/v6r1m0/topic/rzahx/rzahx.pdf

    IBMi HTTP server documentation
    http://www.redbooks.ibm.com/abstracts/sg246716.html

    IBMi MySQL documentation
    http://www.redbooks.ibm.com/redbooks/SG247398/wwhelp/wwhimpl/js/html/wwhelp.htm

    http://publib.boulder.ibm.com/infocenter/tpfhelp/current/index.jsp?topic=/com.ibm.ztpf-ztpfdf.doc_put.cur/gtpm7/m7enablelogs.html

    Zend Server for iSeries documentation
    http://files.zend.com/help/Zend-Server-IBMi/zend-server.htm

    in Installation and Upgrade

    Reach out to us for help