Advanced Configuration Options

Overview

Sugar comes with many different ways to configure your system to best meet your needs. Many configuration options are available throughout the application; though, some advanced options are not available through the interface, but can still be configured.

In the root directory of Sugar, there are two configuration files: config.php and config_override.php. These files hold many configuration options within your instance of Sugar. The config_override.php file is available for you to modify Sugar's configuration. For more information on which options are available to change, please refer to the Developer Guide.

Note: Instances running on Sugar's cloud service do not have access to modify the config_override.php file.

Maintenance Mode

On rare occasions, you may need to restrict users from logging in to Sugar. This is particularly useful when upgrading Sugar or making significant changes to the application (e.g., changing config values, making code-level changes, or deploying changes via Studio, Module Builder, or Module Loader). For these situations, we recommend enabling maintenance mode, which is disabled by default. With maintenance mode enabled, only administrators will be able to log in, and regular users will receive an alert on the login screen letting them know that the system is temporarily unavailable. All incoming API calls will also encounter an error message until maintenance mode has been disabled. When possible, it is best practice to notify affected users in advance of a maintenance period.

To enable maintenance mode for your instance, add the following line to the config_override.php file:

  $sugar_config['maintenanceMode'] = true;

System Configuration

Changing values in the config files can change functionality and behaviors in Sugar. We always recommend testing your changes on a development or test system before changing values in a production system. After changing the config_override.php file, you should perform a Quick Repair and Rebuild from the Admin > Repair menu. For more information, please refer to the Repair documentation.

Configuring File Permissions

Many features in Sugar require the web server to have the proper file permission settings to be able to read and write files. At a minimum, the following files and directories need to be writable from your web server:

./config.php
./config_override.php
./sugarcrm.log
./cache/ and all subdirectories and files
./custom/ and all subdirectories and files
./data/ and all subdirectories and files
./modules/ and all subdirectories and files

Sugar running on Windows with IIS will need the IIS user (IUSR_[computerName]) to have access to these files.

Sugar running on Linux expects the listed files and directories to be owned by the same user running the web server and to also be in the same group. Sugar would then require the following permissions:

2770 for the directories listed above
660 for the config.php file and all files in the directories listed above
770 for bin/sugarcrm

When running on Linux, the config.php file in your Sugar instance's root directory contains a setting called default_permissions. This setting controls the ownership and accessibility to all files and folders created by Sugar. The following is an example of setting Read, Write, and Execute permissions for the Apache user and the Apache group on CentOS operating system:

   default_permissions' => array(
   'dir_mode' => 1528,
   'file_mode' => 432,
   'user' => 'apache',
   'group' => 'apache',
),

The values for dir_mode and file_mode are decimal equivalent values for the standard octal values entered for permissions. The value 1528 is the decimal equivalent of the octal value 02770 and a value of 432 which is the decimal equivalent of octal value 0660. These are the recommended directory and file permissions for Linux systems.

Note: If the octal values are entered, they will be interpreted as decimal and will not provide the expected file permission settings.

The 'user' and 'group' values determine the ownership of the files created. When empty, your Apache settings will take precedence to determine file and directory ownership. These values should be set explicitly to the Apache user and group on your server and these values will vary depending on the Apache setup and/or Linux OS you are running. To update these values, please edit the config_override.php file in the root directory of your installation and add the following lines:

  $sugar_config['default_permissions']['user'] = '<your Apache user>';
$sugar_config['default_permissions']['group'] = '<your Apache group>';

Note: These values will take effect for only newly created files, not existing files. If you need to change the file permissions or ownership for existing files, you must execute the changes through the file system.

Allowing POP Email Accounts

Inbound email accounts are set up to work with IMAP protocols by default. If your email provider required POP3 access instead of IMAP, you can add the following line to the config_override.php file:

  $sugar_config['allow_pop_inbound'] = true;

This will allow new inbound email accounts to be configured with POP3 or IMAP.

Note: POP3 access is not supported and can cause unintended consequences. IMAP is the recommended protocol to use for inbound email accounts.

Security Options

By default, all administrators have access to administrative tools in Sugar like the Upgrade Wizard, Module Builder, and Module Loader. The following sections will show a few different ways to disable these options.

Locking Down Admin Control

If you are managing multiple instances of the Sugar application, you can maintain complete control over the Sugar instances by preventing users with administrative privileges from making any changes. To do this, you can lock down the Upgrade Wizard and Module Builder with a single command in the config_override.php file:

  $sugar_config['admin_access_control'] = true;

Locking Down Module Loader

To ensure that users with administrative privileges do not load sub-standard modules into Sugar, you can restrict the Module Loader to a specific directory on the web server that you control. This allows you to check modules before they are loaded into Sugar. To restrict the module loader, simply add the following lines to the config_override.php file:

  $sugar_config['use_common_ml_dir'] = true;
$sugar_config['common_ml_dir'] = '/Applications/MAMP/htdocs/sugarcrm/screenedModules';

This will prevent any admin users from loading a module from any directory other than the specified directory. Once a module is approved through the necessary channels, the module can be placed in the specified directory for any admin to install when necessary.

Another method for locking down the module loader is to enable the package scanner. The package scanner is enabled by default for instances hosted on SugarCloud. If you are running Sugar on-site, you can enable the package scanner by adding the following command in the config_override.php file:

  $sugar_config['moduleInstaller']['packageScan'] = true;

When the package scanner is enabled, the module loader will check the files being loaded for various functions that could be damaging to the server or instance of Sugar. For more information on which functions are denylisted and how to configure the package scanner, please refer to the Developer Guide.

Note: Sugar Sell Essentials customers do not have the ability to upload custom file packages to Sugar using Module Loader.

Enabling Sites as Referers

To prevent Cross-Site Request Forgery (XSRF) attacks, Sugar has a list of acceptable sites that are allowed as a referer to Sugar. If you receive a "Possible Cross Site Request Forgery (XSRF) Attack Detected" message from an approved site trying to access Sugar, you can add that approved site's URL to the list of valid referers by adding the following line to the config_override.php file:

  $sugar_config['http_referer']['list'][] = 'my.site.com';

This line will add the specified site to the list of approved sites. If you have multiple sites to add, repeat this line for each site required.

Performance

If the performance of your Sugar instance begins to degrade, there are some configuration options you can enable to lighten the load on your system. The following options may cause Sugar's performance to increase, but some performance gains will come with a loss of functionality.

Recommended Server Settings

Sugar recommends a PHP memory limit of at least 1GB. This value may need to be increased depending on how your users utilize Sugar. For example, operations such as mass update and imports may require additional memory depending on your instance size and configuration. To change this limit, edit the setting within php.ini:

  memory_limit = 1G

In addition, display_errors should always be set to "off". Enabling this option can result in adverse behavior for your users. To turn this setting off, edit the option within php.ini:

  display_errors = off

When making changes to either of these settings or any other settings within php.ini, you must restart the web server before the settings will take effect.

Limiting System Resources

Sugar allows non-admin users to be restricted to how many queries they can run per action. By default, the limit for all modules is set to 1000 queries. This prevents user-initiated processes from taking up too many system resources. If an operation is performed by a user that attempts too many queries they will see a message returned saying: "Error: Query limit of 1000 reached for Leads module." To change this limit for all modules, add the following line to the config_override.php file:

  $sugar_config['resource_management']['default_limit'] = 5000; // default is 1000

Note: Setting the default_limit value to 0 will remove the query limit altogether for all modules.

In addition to setting the default for all modules, you can specify certain modules to have a different value. To remove the limit for specific modules only you need to specify the modules and the limit for those modules by adding the following lines to the config_override.php file:

  $sugar_config['resource_management']['special_query_modules'][] = 'Accounts';
$sugar_config['resource_management']['special_query_modules'][] = 'Contacts';
$sugar_config['resource_management']['special_query_limit'] = 0; // default is 50000

In this example, the Accounts module, Contacts module, and any other module in the special_query_modules array will no longer be limited. All other modules will adhere to the default limit.

Note: Setting this limit too low can severely restrict users from performing basic actions. Alternatively, removing the limits altogether may let users inadvertently perform operations that significantly impact overall performance.

Configuring a Secondary Database

Sugar allows you to configure your instance to pull reports or list view data from a secondary database instead of your live database. Reports and list views can create a heavy load on the database, so separating out the reports or list view data on a different database or server can help alleviate some performance issues.

To configure a secondary database, set the appropriate array in the config_override.php file:

Reports: $sugar_config['db']['reports']
Dashlets, Subpanels, and List Views: $sugar_config['db']['listviews']

Set the following values in the array to configure Sugar to use a secondary database:

Key	Value
db_host_name	The host name of the server running the secondary database.
db_user_name	The user name to connect to the secondary database.
db_password	The password to connect to the secondary database.
db_name	The name of the secondary database.
db_type	The type of database running the secondary (DB2, mysql, mssql, oracle).

For example:

  $sugar_config['db']['reports'] =
   array(
      'db_host_name' => 'sugar_secondary',
      'db_user_name' => 'ro_user',
      'db_password' => 'ro_user_password',
      'db_name' => 'sugarcrm_reports',
      'db_type' => 'mysql',
   );

Note: You must create the secondary database and the sync mechanism to keep the secondary up to date with the live database. The Sugar application will not sync data from the live database to the secondary.

Changing the Upload Directory

Sugar stores content, such as images, documents, and installable modules, uploaded by users in the upload directory. Some of these documents may be large in size and can cause performance issues. Administrators can move the upload directory to a different location to ensure that enough space is available for uploads without affecting the system. You can change the location of the uploads to a different folder within the sugar directory or use an absolute path to place the folder anywhere in the file system. You can change this location by adding the following line to the config_override.php file:

  $sugar_config['upload_dir'] = 'd:\upload\';

Note: Remember to copy files from the old upload directory into the new upload directory for accessibility. The upload directory should be writable by the user running the web server.

Changing the Cache Directory

Sugar uses a cache directory to store files (such as compiled templates, aggregated variable definitions, remote mailbox data, various cache files) produced by the system to optimize functionality and enhance system performance. These files can take considerable space, especially in larger systems. You can change the location of the cache to a different folder within the sugar directory or use an absolute path to place the folder anywhere in the file system. You can change this location by adding the following line to the config_override.php file:

  $sugar_config['cache_dir'] = 'd:\cache\';

Some of the cache files can be accessed by direct URLs. So if you move the cache directory, you should also ensure that the URL /cache/ (relative to the main Sugar site URL) on your web server is configured to refer to the new cache location. For more information on how to configure mappings between URLs and file system directories, refer to your web server documentation.

Note: The cache directory needs to be created first, or you may receive an internal server error. The cache directory should be writable by the user running the web server.

Configuring Count Queries

By default, list views and subpanels in Sugar return record counts. This can be convenient to know how many records were found for a specific search, but in order to retrieve the record count; Sugar needs to perform additional queries on the database. When there are large amounts of data, these queries can cause performance issues. You can disable these count queries in Sugar by adding the following line to the config_override.php file:

  $sugar_config['disable_count_query'] = true;

Instead of seeing the total record count, you will see the current known record count with a plus sign next to it.

Disabling Related Calculation Fields

When a calculated field in Sugar uses the related function in the Sugar Logic, this will cause the calculated field to be executed when the related module is updated. This can cause a cascading effect through the system to update related calculated fields. When this happens you may receive a 502 Gateway Error. You can disable the related calculation field updates by adding the following line to the config_override.php file:

  $sugar_config['disable_related_calc_fields'] = true;

Note: This is a global setting that will affect all modules. If you have a calculated field in Accounts that sums up all Opportunities for the account, setting this value to true will no longer update the opportunity account sum in Accounts until the account record itself is modified. However, if this setting is left disabled, the sum would update any time a related opportunity or the account is modified.

Disabling Automatic Searches

By default, list views in Sugar remember the last search performed by the current user in each module. While this can be convenient, it is sometimes unnecessary. If the last search performed in a module was an extensive search, the next time the user navigates to that module will inadvertently perform the search again. This can have a negative impact on performance in Sugar.

Set one of the following values for $sugar_config['save_query'] in the config_override.php file to configure different options for saving list view queries:

Value	Description
all	Populates the last search and executes it. Note: This is the default behavior in Sugar.
no	Discards the previous search and executes a search with no criteria.
populate_only	Populates the last search but does not execute it.

For example:

  $sugar_config['save_query'] = 'populate_only';

Note: The $sugar_config['save_query'] setting is not supported for Sidecar modules and only applies to Legacy modules.

Using a Custom Page For Campaign Trackers

When sending campaigns through Sugar, tracker URLs are used for images, links, and the opt-out link in the campaign. When the recipient of the campaign clicks one of these links they are by default taken to the Sugar instance that sent the campaign. Many organizations may want to use a custom page to send recipients to instead of using Sugar, or when running Sugar onsite it may be behind a firewall and not accessible to the recipients of the campaign. Use the following steps to create a custom landing page to use for tracker URLs while still properly recording the activity in Sugar.

Create an index.php page on the desired web server that is open to the Internet.
Add the following code to the custom index.php page to ensure all campaign activities are properly recorded in Sugar.
Note: Replace all occurrences of "http://sugar_url" in the code below with the actual Site URL of your Sugar instance.

<?php
  if ($_REQUEST['entryPoint'] == 'removeme' || $_REQUEST['entryPoint'] == 'campaign_trackerv2' || $_REQUEST['entryPoint'] == 'image') {
    if (strlen($_REQUEST['identifier']) == 36) {
      $ch = curl_init();
      if (strlen($_REQUEST['track']) > 0) {
        curl_setopt($ch, CURLOPT_URL, \"http://sugar_url/index.php?entryPoint=\" . $_REQUEST['entryPoint'] . \"&identifier=\" . $_REQUEST['identifier'] . \"&track=\" . $_REQUEST['track']);
                curl_setopt($ch, CURLOPT_HEADER, 1);
                curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
                curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 0);
                curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                curl_setopt($ch, CURLOPT_USERAGENT, $_SERVER['HTTP_USER_AGENT']);
                $headers = curl_exec($ch);
                $headerArray = explode(\"\n\",$headers);
                foreach ($headerArray as $value) {
                    if (substr(strtolower($value),0,8) == \"location\") {
                        header($value);
                    }
                }
            } else {
                curl_setopt($ch, CURLOPT_URL, \"http://sugar_url/index.php?entryPoint=\" . $_REQUEST['entryPoint'] . \"&identifier=\" . $_REQUEST['identifier']);
                curl_setopt($ch, CURLOPT_HEADER, 0);
                curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
                curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
                curl_setopt($ch, CURLOPT_USERAGENT, $_SERVER['HTTP_USER_AGENT']);
                curl_exec($ch);
            }
            curl_close($ch);
            unset($ch);
        }
    }
?>

Finally, specify the external server URL in the Admin > Campaign Email Settings > Location of campaign tracking files option in order for the tracking links to be correctly generated in the campaign emails. For more information on setting this value, please refer to the Email documentation.

Configuring Cron for Schedulers

Sugar's scheduler jobs are executed by the cron utility which runs on your server. There are several configuration options available to ensure that long-running or failed scheduler jobs do not impede your other scheduler jobs from running in a timely manner.

First, max_cron_runtime determines how long a single job should be allowed to run. If a single job exceeds this limit, cron.php is aborted with the long-running job marked as in progress in the job queue. The next time cron runs, it will skip the job that overran the limit and start on the next job in the queue. Additionally, if the total running time of a single cron run across all current jobs exceeds max_cron_runtime, then cron will complete whatever job it is currently executing, then stop. The next time cron runs, it will pick up with the next queued job. The max_cron_runtime uses seconds as its units and defaults to 1800 (30 minutes). You may wish to adjust this number based on the typical time requirements of scheduler jobs in your instance.

By default, max_cron_runtime is not enforced on your instance. In order to enforce this limit, set enforce_runtime to true.

  $sugar_config['cron']['enforce_runtime'] = true; // default is false
$sugar_config['cron']['max_cron_runtime'] = 1800; // seconds, default is 1800

The timeout configuration controls how long cron will wait before re-starting a job that previously failed to complete. Once a job has been marked as in progress for longer than the timeout setting, the next cron run will mark the job as failed, making it eligible in the queue to be executed by the following cron run. The timeout uses seconds as its units and defaults to 3600 (1 hour). You may wish to adjust this number based on how quickly you wish a failed or long-running job to be reattempted. Please note that should enforce_runtime be set to false or your max_cron_runtime be longer than the timeout, a job which is running normally may be set to "failed" upon reaching this timeout limit.

  $sugar_config['jobs']['timeout'] = 3600; // seconds, default is 3600