System configuration

Web Server

Allow to pass OQL queries as parameters

In iTop, lots of pages are sending OQL queries as parameters. This is risk-free as queries are interpreted and customized by iTop before being transformed in a single Select only SQL query and sent to the DB server.

In other words for any query iTop will :

check syntax and classes validity
add appropriate filters according to user rights
protects against injections

As OQL syntax is close to SQL, this may be blocked by a security system like mod_security. You must allow those in order to use iTop. For example with mod_security :

SecRule REQUEST_URI "@beginsWith /pages/UI.php" \
"id:'000013', \
phase:1, \
t:none, \
nolog, \
pass, \
ctl:ruleRemoveById=942190, \
ctl:ruleRemoveById=942360"

Write permission on temp directory

iTop needs write access to the temp dir (this path is retrieved using the PHP function sys_get_temp_dir()). Check rights and also the openbase_dir PHP parameter !

APCu

We strongly recommend to enable APCu ! For more details, read Tuning iTop Performance

However, if you are using APCu on mutiple instances, after a Move To Production, the cache must be cleared on all instances. As we have no tools for doing this, practically speaking this means:

either restart all web servers
or do not use APCu

PHP

Required Extensions

ctype
dom
iconv
json
mbstring
mysqli
soap

All mandatory PHP extensions are checked on setup landing page

Other PHP extentions

curl is required to export in PDF the impacted CIs
php-gd is required to be able to add images with CKEditor and resize automatically images within HTML fields
PHP LDAP module is required to support LDAP or Active Directory identification
Encrypted data : check Encrypted data to know what to install in order to be able to use EncryptedString attributes

php.ini settings

Recommended values in php.ini summary :

php.ini

memory_limit = 256M ; could be increased if needed
max_input_vars = 5000
 
; upload_tmp_dir : should point to a directory with write access
 
; also check those options for attachments (se dedicated chapter below)
; adapt values depending of your preferences!
; - upload_max_filesize
; - max_file_uploads
; - post_max_size
; - max_input_time

If you're using CLI tools like cron.php, check also the PHP instance used for CLI !

max_input_vars

On various use cases iTop send large amount of data to the server. Especially some XHR queries sends a description of the current object structure : list of attributes and all corresponding properties. If your datamodel adds lots of attributes on an object, you can get wrong behavior on one of those screens :

when editing objects with many relations (iTop creates one big form containing all the relations)
in a object list :
- when ordering the list by clicking on a column header
- after checking lots of attributes in the “configure this list” dialog

Such behavior can be caused by the webserver : the parameter max_input_vars in php.ini defines the maximum size of data sent to the server. Its default value is 1000, which might not be sufficient for such customized objects with many fields. If you get such behavior, you can update max_input_vars value from 1000 to 3000 or 5000 depending on the volume needed to be transferred.

This very same behavior may happen when Suhosin is installed. Refer to iTop and Suhosin for more information

Attachments upload

iTop is capable of uploading and storing documents (i.e files) as attachments to various objects (Tickets, CIs…). These documents are stored as binary blobs in the iTop database. In order to to safely upload and store documents, several settings must be adjusted consistently across PHP and MySQL.

In PHP, several variables govern the upload of files:

file_uploads	Set to 1 to allow file upload, to zero to prevent all file uploads.
upload_tmp_dir	The temporary location (on the server) were the uploaded files will be stored. Make sure that this parameter points to a location that is accessible (and writable) by the process running the web server (or by the end users in case of IIS with the Windows built-in authentication) and that there is enough space left.
upload_max_filesize	The maximum size allowed for an uploaded file. The value is expressed in bytes. You can use units like K for kilobytes (=1024 bytes), M for megabytes and G for gigabytes. Example: 4M stands for 4 megabytes.
max_file_uploads	The maximum number of files that can be uploaded simultaneously in a single web page. iTop should normally upload only one file at a time. You can safely use the default value, which is 20.
post_max_size	The maximum amount of data that can be sent to the server via a POST request. This value MUST BE bigger than upload_max_filesize, since the same request will contain some more information (the title of the document, an operation code…). So it’s better to put a bigger value here. For example, if upload_max_filesize is 4M, then put 5M for post_max_size.
memory_limit	After being uploaded on the server, the file will be read in memory before being stored in the database. Therefore make sure that memory_limit (if enabled) is at least 5 times bigger than `upload_max_filesize`.
max_input_time	This value defines the maximum time allowed for the server to read its input. This includes the time spent uploading the files. The default of 60 seconds may be exceeded for uploading big files over slow connections.

It is good practice to have the following relation between the various settings:

upload_max_filesize	<	post_max_size	<	max_allowed_packet	<	memory_limit
php.ini		php.ini		my.cnf		php.ini

DB server

DB server user

Starting with MySQL 5.7, the root user has no explicit password in MySQL, so you will have to create a user account with a password for installing iTop. The commands below create a user iTop with all privileges. This is useful for testing but is not the best configuration for use in production (because security matters):

  sudo mysql

Once logged in MySQL, execute the following commands:

  GRANT ALL PRIVILEGES ON *.* TO 'iTop'@'%' IDENTIFIED BY 'some_password';
  FLUSH PRIVILEGES;

Provide a MySQL account with enough privileges:

SELECT, INSERT, UPDATE, DELETE for daily use of iTop
CREATE (table), ALTER, CREATE VIEW for Setup and datamodel modification
CREATE (database) if you ask the Setup to create you database and for the ITSM Designer for Test database creation (DROP in this case is needed also)
SHOW VIEW, LOCK TABLES are used for backups
DROP and TRIGGER are used by DataSynchro
SUPER required for DataSynchro, only if MySQL is running with binary logging but without the –log-bin-trust-function-creators option (see MySQL Bugs: #39489: Cannot create or drop triggers without SUPER privilege)

Settings

my.cnf

innodb_buffer_pool_size = 512M
query_cache_size = 32M
query_cache_limit = 1M
 
innodb_default_row_format = DYNAMIC
innodb_large_prefix = true
 
; max_allowed_packet : should be set to a value bigger than upload_max_filesize in php.ini

innodb_log_file_size must be at least 10 times bigger than max_allowed_packet
[ERROR] InnoDB: The total blob data length (35174918) is greater than 10% of the total redo log size (268435456). Please increase total redo log size.

If you ever have an issue linked with mysqldump, there is another parameter max_allowed_packet you can act on, in the same file my.cnf but under [mysqldump] section

i18n

As of iTop 2.5, the charset used is utf8mb4 with utf8mb4_general_ci collation. To allow iTop to correctly handle strings, the following requirements must be met :

MySQL version 5.5.3 or newer
innodb_default_row_format variable set to DYNAMIC (default value) or COMPRESSED
innodb_large_prefix set to true

Attachments

The uploaded files are stored into the MySQL database, each file in one query. Therefore the maximum size allowed for a query MUST BE BIGGER than the maximum size of the uploaded file. This is configured via the variable max_allowed_packet in the my.cnf configuration file (on the MySQL server).

MySQLDump

The mysqldump utility must be executable on your web server for the database backup to be possible.

Sidebar