You're looking at an older version of Totara Learn.

Please see Totara 13 help for the latest version.

All pages



New requirements in Totara Learn 2.9:

  • PHP version 5.4.4 now required, 7.0 and higher is not supported (was 5.3.3 in Totara Learn 2.6).
  • PHP zlib and OPcache modules now recommended.
  • MSSQL only: Database user requires additional permissions: 'ALTER SETTINGS(SERVER)'.
  • MSSQL 2008 now required (was 2005 in Totara Learn 2.6).
  • Postgres 9.1 now required (was 8.3 in Totara Learn 2.6).
  • MySQL 5.5.31 now required (was 5.1.33 in Totara Learn 2.6).
  • MariaDB 5.5.31 now required (was 5.3.5 in Totara Learn 2.6).

To upgrade to Totara Learn 2.9 you must be on Totara Learn 2.2.13 or later. If your version is earlier than 2.2.13 the upgrade will not run. Versions of Totara Learn prior to 2.2 must first upgrade to 2.2 via Totara Learn 1.1.17+, then to at least 2.2.13, before upgrading to 2.9.

Upgrade process

  1. Log in as an administrator.
  2. Check the live logs to check if any users are currently using the site. The site will be offline while the upgrades are performed (Site administration > Reports > Live Logs).
  3. Enable maintenance mode in Totara Learn (Site administration > Server > Maintenance Mode).
  4. Log out.
  5. Back up the Totara Learn database.
  6. Back up the sitedata directory.
  7. Back up the Totara Learn source code directory.
  8. Make a copy of your config.php and any plugins you have installed.
  9. Remove the old source code - delete everything!
  10. Extract the new source code into the source code directory.

    Do not copy the new code on top of the existing code folder.

  11. Copy your config.php and any third party plugins back into the source code directory.
  12. Run the following command in your terminal, replacing www-data with your web users username.

    sudo -u www-data php admin/cli/upgrade.php

  13. Review the information provided and confirm you want to continue.
  14. Carefully check the output in the terminal and ensure no errors were encountered.

    If you have encountered an error the site will need to be rolled back, the issue fixed, and then the upgrade attempted again.

  15. Log in as an administrator.
  16. Review and save changes to new settings (if any).
  17. Disable server maintenance mode.
  18. Congratulations, your site is now upgraded. Read CHANGELOG.php for details on what is new.

Considerations for upgrading

When upgrading there are many things to consider both from a technical and training perspective. It is important to ensure all elements of your system are technically compatible, including your theme and any customisations. You will also want to make sure any training materials, and indeed any trainers, are up-to-date with new features and improvements. 


It is important to review the changelogs and make sure you understand what is changing. New features and improvements are likely to bring changes to interfaces, behaviour, and workflows. Our changelogs will help you identify which areas have changed, so you can then find information on new behaviours and workflows on this help site. This is important so that any internal training material you have can be updated and staff trainers can learn about what has changed.

You should also review any new administration settings, as new controls get added with every major release. These added controls may facilitate new functionality, improve security, or allow further customisation. Each setting should be reviewed so that you can check your Totara Learn site configuration is current and understood.

System requirements may also change and although these will have no impact for those using the site, you will need review them to ensure they are met during deployment of the new release. 


User experience (UX) changes will mean that you will need to review your theme. It is likely there will be new places that need to be styled to make them look a part of your site. This is because HTML structure, CSS classes, and Javascript changes have been made. New features also bring new interfaces.


Our APIs can change significantly between major releases. We have a deprecation policy that ensures that all changes where possible are backwards compatible, and that customisations will continue to function in the short term. When backwards compatibility is being used developer debugging information will be printed out to inform you that customisations and plugins will need to be updated. It is important these changes are made as backwards compatibility is only maintained for a limited time (typically one major release).

Incompatible API changes are rare, but they do occur. If you have customisations using API that no longer functions you will be presented with a debugging notice and you'll find that your customisations don't function as they should.

Password salting & module security

Totara Learn automatically generates and adds a different salt for each user. A site-wide variable for the salt is no longer required for new installations of 2.5 or greater.

Backward compatibility for site upgrades

If you are upgrading a site from 2.4 or below and you are already using a site-wide salt in your configuration file, you need to keep using it to ensure your existing users can still log in.

Each time a user logs in their password hash will be converted to the new scheme, but it may take a long time before all your users have logged in. Alternatively, if you would like to force all your users to use the new scheme you could force reset all passwords using bulk user actions.

Sites running PHP version below 5.3.7

The new password hashing mechanism relies on bcrypt support from PHP which is only normally available in PHP version is 5.3.7 or greater (see note below). If you are using a version of PHP which doesn't properly support bcrypt, Totara Learn will fall back to the old password hashing scheme, so we recommend that you continue to use a site-wide salt until you are able to upgrade PHP.

Note: While an important fix to PHP's hashing algorithm was added in 5.3.7, some distributions of Linux have backported the fix to bcrypt to earlier versions of PHP. This means that some earlier versions of PHP may still work.

Course completion 

Prior to Totara Learn 2.9 if you configured a course to require activity completion and that activity had a passing grade defined in the gradebook, then the course would only consider the activity complete if the user had also achieved a passing grade despite the activity being marked complete for the user. 

Totara Learn 2.9.0 introduced a new course completion behaviour where activity completions marked as complete but failed are now considered complete when aggregating course completion. This lead to an unexpected change in behaviour for some sites when upgrading to Totara Learn 2.9.

By adding the setting $CFG→completionexcludefailures to config.php that change of behaviour can be reverted. Please note that in order to prevent completion changes this setting must be added to config.php before upgrade from Totara Learn 2.7 or right after a new installation.

This setting should not be changed if you have already upgraded your site to Totara Learn 2.9.0 through to 2.9.11, because there are new settings in activities that can be used to get similar behaviour and the already changed completions cannot be reverted.

Totara registration

You may be prompted to register your Totara Learn site, you can find more information on the Totara registration page.

On this page

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