Looking for up-to-date Help documentation? Documentation for the latest releases of Totara is now available at totara.help!

Visit the new Help site

All pages

The Server section of the Site administration settings lets you control various aspects of your site's setup. 

System Paths

The system paths page includes the following options:

  • GD version: GD is a graphics library that manipulates graphics. It’s used to create thumbnail images from uploaded files and other graphics on the fly. If you don’t know what version is installed, leave this on the original setting.
  • Path to zip and unzip: If you are running Totara on a Unix or Unix-like server (Linux, Solaris, BSD, Mac OS X), you may need to specify where the zip program is located. Zip and unzip are used to compress and decompress ZIP archives such as the backup folder.
  • Path to aspell: To use spell checking within the HTML editor, you must have aspell 0.50 or later (http://aspell.net/) installed on your server, and you must specify the correct path to accesstheaspell binary.

PDF production and wkhtmltopdf

There are several areas in Totara that produce PDF documents, including exporting report builder reports and exporting appraisals. By default Totara uses an internal library DOMPDF to produce these PDF documents. DOMPDF is known to perform poorly with large documents, problems which unfortunately can not be avoided in PHP.

Totara however ships with the ability to use wkhtmltopdf an external library that can be installed on the server and then utilised to produce these PDF documents. This format (wkhtmltopdf) is know to perform better and produce a more consistent result.

To configure wkhtmltopdf:

  1. Install the full version of wkhtmltopdf.

    Some Linux distributions include wkhtmltopdf in their repositories. If you intend on using a repository version please check that it is a full version. We are aware of some Ubuntu distributions that include only a simple version of wkhtmltopdf and Totara requires the full version.

  2. Add the following to your config.php (if it is not already defined), this allows you to use executables such as wkhtmltopdf.
    $CFG->preventexecpath = 0;
  3. Log in as a system admin and browse to Site administration > Server > System path.

  4. Set Path to wkhtmltopdf to the correct system path for wkhtmltopdf.

Support contact

An administrator can specify a support name, email, and/or support page in Settings > Site administration > Server > Support contact for including in the account confirmation email.

When a user changes the email address in their profile a confirmation email is sent from the primary administrator of the site, rather than from the support email.

Session handling

The session handling page includes the following options:

  • Timeout: Once someone logs in to your Totara server, the server starts a session. The session data allows the server to track users as they access different pages. If users don’t load a new page during the amount of time set here, Totara will end their sessions and log them out. Be sure this time frame is long enough to cover the longest test your trainers may offer. If learners are logged out while they are taking a test, their responses to the test questions may be lost.
  • Cookie prefix: Most of the time, you can leave this blank, unless you are running more than one Totara site on the same server. In this case, you will want to customise the name of the cookie each Totara site uses to track the session. This enables you to be logged in to more than one Totara site at the same time. If you change the cookie prefix you will need to log in again, as the change takes effect immediately.


If you enable site statistics, Totara will gather statistics about each course and for the whole site and produce graphs displaying them.

To enable statistics:

  1. Select Server > Statistics from the Site Administration block.
  2. Click the Enable statistics check box.
  3. As stats processing is quite resource-intensive, you should set the stats processing to start in the early morning.
  4. Set the stats processing to start an hour before your automated course backups are scheduled to start, then set the maximum run- time to one hour. This ensures that stats are not being processed at the same time as course backups are being made.
  5. Click the Save changes button.


The HTTP page contains the following options:

  • Frame name: If you’ve developed a web wrapper for Totara and you want to include Totara in a larger frame, set the name for the Totara frame here.
  • Use slash arguments: You will need to change this setting only if you are having trouble viewing files or images. Most of the time,Totara will display files and pictures with no problem using the slash arguments. If you get errors when you try to view pictures or files from within Totara, your PHP server doesn’t allow the slash argument method and you will need to use the file argument method instead.
  • Proxyhost, proxyport, and reverse proxy: Your Totara server may need to access the Internet through a proxy server, depending on your network configuration. If you’re not sure about whether you need a proxy server, contact your network administrator or ISP.

Maintenance Mode

Maintenance mode is for preventing any users other than administrators from using the site while maintenance is taking place.

When users attempt to access a course while your site is in maintenance mode, they receive a message informing them that the site is in maintenance mode. If you wish, you can create a customised maintenance mode message, perhaps stating when the site will be available again or giving the reason for doing maintenance.

The front page of your site will appear as normal when your site is in maintenance mode. Users will only see the maintenance mode message when they attempt to access a course.

To put your site in maintenance mode:

  1. Click Site administration > Server > Maintenance mode in the Administration block.
  2. Click the Enable button.

An alternative way of putting your site in maintenance mode if you’re unable to access the web interface is to create a file called maintenance.html and save it in the folder called 1 in your totaradata folder. A customised maintenance mode message can be entered in the maintenance.html file.


The cleanup page contains the following options:

  • Unsubscribe users from courses after: To help keep lists of participants up-to-date, you can tell Totara to unenrol any learner who hasn’t logged in for a certain amount of time. Be sure to keep this time long enough so learners aren’t unenrolled accidentally while they still need access to the course.
  • Delete unconfirmed users after: If you’re using email-based self-registration, users must confirm their account within a certain time frame. Once the time set here has passed, any account that hasn’t been confirmed will be deleted. Seven days is a good setting.
  • Keep logs for: Totara keeps extensive logs of user activity. Eventually, however, the logs will become so large that they begin to clog your server. Limiting the length of time logs are kept for will reduce database table size. Generally, a year is enough time to keep logs for.
  • Disable grade history: This can be disabled to help speed up the server.
  • Grade history lifetime: Select the number of days to keep a history of changes to tables, only change this if you have limited database space or having tried other solutions to help performance.


The environment page enables you to check that your server meets all system requirements for your current and future versions of Totara Learn.

Check that the status is okay for all of the server requirements.


Totara Learn uses the Unicode character encryption system. The UTF-8 encoding form is used to support multiple languages, as well as special characters used in science and mathematics. You can read more about Unicode on the Unicode consortium's website.

PHP Information

The PHP info page provides information on the version of PHP your server is running, including PHP compilation options and extensions, server information, and the PHP environment and OS version information.

Incoming mail configuration

General configuration

The checkbox Enable incoming mail processing (messageinbound_enabled) must be ticked for this feature to work.

Mailbox configuration

It is important to have a dedicated email address here. Don't use one you normally use for your personal emails. You do not need to add the @ sign. 

Incoming mail server settings

As an example, if you are using gmail you would use IMAP.gmail.com in the Incoming mail server (messageinbound_host) field. (If using gmail you also need to make sure that you've enabled IMAP for your gmail account. See https://support.google.com/mail/troubleshooter/1668960?hl=en ).

Incoming Mail Server: The address of the server that Totara should check mail against. To specify a non-default port, you can use the [server]:[port], for example mail.example.com:587 format. If you leave this field blank, Totara will use the default port for the type of mail server you specify.

Use SSL: This is an extra level of security. Select the version of SSL that your server uses.

The SMTP server hosting the mailbox you've configured above must support plus addressing i.e. any email sent to [email protected] is still delivered to [email protected]

The username and password here must relate to the settings you entered earlier in Mailbox configuration. So if your address was [email protected] and your username is 'partner', then enter your username in this section along with the password you use to get into this email account.

You may also need to make sure that your host does not block outbound connections to the IMAP ports (some do by default).

If using gmail, you may find that IMAP does not work with Google's higher security setting. If IMAP is not working with gmail, check out https://support.google.com/accounts/answer/6010255?hl=en-GB.

Message handlers

Accessed from Site administration > Server > Incoming mail configuration > Message handlers, this page allows you to turn on or off the following settings. Note that you must first have completed the fields in Site administration > Server > Incoming mail configuration > Mail settings.

Invalid recipient handler: If a valid message is received but the sender cannot be authenticated, the message is stored on the email server and the user is contacted using the email address in their user profile. The user is given the chance to reply to confirm the authenticity of the original message.This handler processes those replies. It is not possible to disable sender verification of this handler because the user may reply from an incorrect email address if their email client configuration is incorrect.

Email to Private files: If you enable this, then users will be able to send attachments via email directly to their private files. Each user will be provided with an address in their Private files to which they send the email and attached files. You can set the default expiry period for this address here. Checking the Validate sender address box will mean that if an email is sent to a user's private files from a different account from that registered with user in Totara, then Totara will check first before allowing the file to be stored in the user's Private files.

Reply to forum posts: If you enable this, then users will be able to reply to forum posts directly from their email inbox. See the section on Reply to posts via email in Using Forum for details of how the feature works. You must set Site administration > Plugins > Message outputs > Email to Always send email from the No reply address; otherwise users will see the email of the forum poster instead. Each user will be provided with reply-to address when they click to reply to a forum post via email. You can set the default expiry period for this address here.


The Totara cron process is a PHP script (part of the standard Totara installation) that must be run regularly in the background. The Totara cron script runs different tasks at differently scheduled intervals.

Do not skip setting up the cron process on your server for your Totara. Your site will not work properly without it.

A special program is used to run the Totara cron script at a regular interval. The Totara cron script runs tasks include sending mail, updating Totara reports, RSS feeds, activity completions, posting forum messages, and other tasks. Since different tasks have different schedules, not every task will run in Totara when the cron script is triggered.

The cron program (that runs the Totara script) is a core part of Unix based systems (including Linux and OSX) being used to run all manner of time-dependent services. On Windows the simplest solution is to create a task in the Windows Task Scheduler and set it to run at regular intervals. On shared hosting, you should find the documentation (or ask support) how cron is configured.

Essentially, the task involves adding a single command to the list of cron activities on your system. On Unix based systems this list is a file called a crontab which all users have.

The Totara cron command

Totara has two different ways to deploy cron which uses different scripts within the Totara install. These are as follows:

  • The CLI (command line interpreter) script: This will be at the path /path/to/Totara/admin/cli/cron.php. If in doubt, this is the correct script to use. This needs to be run by a PHP CLI program on your computer. So the final command may look something like /usr/bin/php /path/to/Totara/admin/cli/cron.php. You can (and should) try this on your command line to see if it works.
  • The web based script: This needs to be run from a web browser and will be accessed via a web URL something like http://your.totara.site/admin/cron.php. You can find command line based web browser (e.g. wget) so the final command may look like /usr/bin/wget http://your.totara.site/admin/cron.php. This has the advantage that it can be run from anywhere. If you can't get cron to work on your machine it can be run somewhere else.

Finding the right place to put the command

This really does depend on the system you are using and you should find and read the documentation for your platform or hosting. In most cases getting the Totara cron to run consists of establishing the correct command (above) and then adding it, and the time to run the command, to some sort of file. This might be either through a specific user interface or by editing the file directly.

If using the CLI version you also need to make sure that the cron process is run as the correct user. This is not an issue with the web version.

Example: Installing cron on Ubuntu/Debian Linux. Assuming logged in as root:

Use the crontab command to open a crontab editor window for the www-data user. This is the user that Apache (the web server) runs as on Debian based systems.

$ crontab -u www-data -e

This will open an editor window. To run the cli cron script every 15 minutes, add the line:

*/15 * * * * /usr/bin/php  /path/to/Totara/admin/cli/cron.php >/dev/null

Note that the final ">/dev/null" sends all the output to the 'bin' and stops you getting an email every 15 minutes.


The Performance page (under Site administration > Server > Performance) contains a variety of settings that can be used to optimise the performance of your site.

  • Extra PHP memory limit: Some scripts like search, backup/restore, or cron require more memory, therefore, it is recommended to set higher values for large sites.
  • Maximum time limit: This setting is used to restrict the maximum PHP execution time that Totara will allow without any output. To use the default restrictions enter 0. If you have a front-end server with its own time limit, set this value lower to receive PHP errors in logs. Does not apply to CLI scripts.
  • cURL cache TTL: Time-to-live for cURL cache, in seconds.
  • Bitrate to use when calculating cURL timeouts (Kbps): This setting is used to calculate an appropriate timeout during large cURL requests. As part of this calculation, an HTTP HEAD request is made to determine the size of the content. Setting this to 0 disables this request from being made.
  • Cache main menu: Higher values improve performance but some changes in menu structure may be delayed.
On this page

Related pages

Provide feedback about this page using the link in the bottom right of this page. 

Still have questions? Why not post them in the forums of the Totara Community?

  • No labels