Administration via command line
Note: You are currently viewing documentation for Moodle 3.4. Up-to-date documentation for the latest stable version of Moodle is likely available here: Administration via command line.
- 1 Running CLI scripts
- 2 Upgrading
- 3 Installation
- 4 Maintenance mode
- 5 Offline mode
- 6 Custom site defaults
- 7 Reset user password
- 8 MySQL storage engine conversion
- 9 Converting InnoDB tables to Barracuda
- 10 Converting to the new character set and collation
- 11 Running cron via command line
- 12 Scheduled tasks
- 13 Database transfer
- 14 Purge caches
- 15 Kill all sessions
- 16 Fix course / module sequences
- 17 Fix orphaned question categories
- 18 Search and replace text
- 19 Build theme CSS cache
- 20 See also
Running CLI scriptsIf you have shell access to your web server, you may find various CLI (command line interface) scripts useful during Moodle administration. Core admin CLI tools are located in the
admin/cli/*folder. Other plugins provide their CLI functionality via scripts in their own cli folder. For example, the enrol_db sync script is located in
To avoid problems with access control, you should run them as the owner of the web server process. It is especially important for CLI installation and upgrade as they create new files in moodledata directory and the web server has to have write access to them. In Linux distributions, the user that runs the web server is usually apache or wwrun or httpd or something similar. As a root, you will probably want to execute Moodle CLI scripts like this:
$ cd /path/to/your/moodle/dir $ sudo -u apache /usr/bin/php admin/cli/somescript.php --params
Most of the scripts accept common --help (or -h) parameter to display the full usage information, for example:
$ sudo -u apache /usr/bin/php admin/cli/install.php --help
|Note: These scripts are supposed to be run under the identity of the web server user. Examples on this page use the apache user for illustration. The particular value depends on your OS distribution and local set-up. Typical values may be apache, www-data or httpd.|
Moodle can be upgraded from the command line. As with the installation script, there is either interactive or non-interactive mode of the upgrade. The script itself does not put the site into the maintenance mode, you have to do it on your own. Also, the script does not backup any data (if you read this page, you probably have some own scripts to backup your moodledata and the database, right?)
$ sudo -u apache /usr/bin/php admin/cli/upgrade.php
Upgrading via command line is a very comfortable way of Moodle upgrade if you use Git checkout of the Moodle source code (see Git for Administrators). See the following procedure how to upgrade your site within several seconds to the most recent version while preserving your eventual local customizations tracked in git repository:
$ cd /var/www/sites/moodle/htdocs/ $ sudo -u apache /usr/bin/php admin/cli/maintenance.php --enable $ git pull $ sudo -u apache /usr/bin/php admin/cli/upgrade.php $ sudo -u apache /usr/bin/php admin/cli/maintenance.php --disable
There are two modes of installing Moodle from the command line. In interactive mode, the install script asks you for all data needed to properly set up new Moodle site. In non-interactive mode, you must provide all required data as the script parameters and then the new site is installed silently. The parameters can be passed in the interactive mode, too. The provided values are then used as the default values during the interactive session.
$ sudo -u apache /usr/bin/php admin/cli/install.php --lang=cs
If required, the database install may be skipped, with just config.php populated.
$ sudo -u apache /usr/bin/php admin/cli/install.php --skip-database
To switch your site into the maintenance mode via CLI, you can use
$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --enable
To turn maintenance mode off, just execute the same script with the --disable parameter.
This script will also create and remove the climaintenance.html file for "Offline" mode.
Offline modeIn some situations, you may want to switch your Moodle site into offline mode so that it is not accessible via the web but you can not stop the web server completely (typically because there are other web pages and applications running there). If a file called
climaintenance.htmlexists in the root folder of moodledata directory, Moodle will automatically display the contents of that file instead of any other page.
$ cd /var/www/sites/moodle/moodledata/ $ echo '<h1>Sorry, maintenance in progress</h1>' > climaintenance.htmlYou can prepare a nice formatted HTML page to inform your users about the server being down and keep in the moodledata directory under a name like
climaintenance.offand rename it to the
Custom site defaultsDuring the install and upgrade via CLI, Moodle sets the administration variables to the default values. You can use different defaults. See MDL-17850 for details. Shortly, all you need to do is to add a file
local/defaults.phpinto your Moodle installation. The format of the file is like
<?php $defaults['pluginname']['settingname'] = 'settingvalue'; // for plugins $defaults['moodle']['settingname'] = 'settingvalue'; // for core settings
These defaults are used during install, upgrade and are also displayed as defaults on Site administration pages.
Reset user password
If you happen to forget your admin password (or you want to set a password for any other user on the site), you can use reset_password.php script. The script sets the correctly salted password for the given user.
$ sudo -u apache /usr/bin/php admin/cli/reset_password.php
MySQL storage engine conversion
If you run your Moodle site with MySQL database backend and use the default MyISAM as the storage engine for your tables, you may want to convert them to use some more reliable engine like InnoDB (actually, you should want to switch to PostgreSQL ;-) anyway).
$ sudo -u apache /usr/bin/php admin/cli/mysql_engine.php --engine=InnoDB
Converting InnoDB tables to Barracuda
Sites using MySQL with database tables using Antelope as the file format are recommended to convert the tables to the Barracuda file format.
This is because tables using Antelope as the file format cannot handle more than 10 text columns. This file formats only supports compact and redundant row formats for backward compatibility reasons. This may cause a problem on larger sites when restoring a course, in which case the following error will be displayed:
Row size too large (>8126). Changing some columns to TEXT or BLOB or using ROW_FORMAT=DYNAMIC or ROW_FORMAT=COMPRESSED may help.
Barracuda is the newest innoDB file format. In addition to supporting compact and redundant row formats, Barracuda also supports compressed and dynamic row formats.
However, converting tables to Barracuda is only recommended, and not required, since not all MySQL users are affected. (It may only be a problem for larger sites.)
Tool for converting tables
A command line tool is included in Moodle for converting tables to Barracuda.
To view tables requiring conversion, use the list option:
$ php admin/cli/mysql_compressed_rows.php --list
Here is an example output:
mdl_data Compact (needs fixing) mdl_data_fields Compact (needs fixing) mdl_enrol_paypal Compact (needs fixing)
To proceed with the conversion, run the command using the fix option:
$ php admin/cli/mysql_compressed_rows.php --fix
Successful table conversion will be reported in the output, for example:
mdl_data ... Compressed mdl_data_fields ... Compressed mdl_enrol_paypal ... Compressed
Please note that the commands must be executed on your moodle directory. Once tables are fixed, the warning message will no longer be displayed.
If you get errors due to having insufficient privileges to run these commands (this is quite likely) then the easiest solution is to generate the required SQL commands using,
$ php admin/cli/mysql_compressed_rows.php --showsql
You can then copy the generated SQL into your mysql client running as the 'root' user.
Converting to the new character set and collation
$ php admin/cli/mysql_collation.php --collation=utf8mb4_unicode_ci
Running cron via command line
In versions 1.x, you could execute admin/cron.php either from command line or via the web. Since Moodle 2.0, only admin/cli/cron.php script can be run via command line.
Scheduled tasks are automatically run by the cron script, but the specific tasks which run on each cron iteration are determined by the scheduled tasks configuration. It is possible to override the scheduled tasks configuration and run a single scheduled task immediately using the admin/tool/task/cli/schedule_task.php script.
This script accepts the following arguments:
--list - list all the known scheduled tasks. The tasks are listed by the class name used to run the task. This class name is required as the argument to the next option in order to run a specific task immediately.
--execute=<task> - Runs a single scheduled task immediately - regardless of scheduling settings. This will even run disabled tasks. Tasks will still use locking to prevent concurrent execution of the same task - even on clusters. The format of the <task> argument must be the same as returned by the --list option above.
--showsql - Shows sql queries before they are execute
--showdebugging - Shows developer debugging info
Note: You must escape the "\" with an extra \ when using the --execute command. Take the following for example:
php schedule_task.php --list
will return something like:
== List of scheduled tasks (http://yourserver.com/moodle) == \enrol_imsenterprise\task\cron_task 10 * * * * * ASAP \logstore_legacy\task\cleanup_task * 5 * * * * ASAP \logstore_standard\task\cleanup_task * 4 * * * * Wednesday, November 12, 2014, 4:35 AM \mod_forum\task\cron_task * * * * * * ASAP \core\task\automated_backup_task 50 * * * * * ASAP ...
To run the first task in that list, you would execute
php schedule_task.php --execute='\enrol_imsenterprise\task\cron_task'
Be aware of the single quotes. Without them, you would need to use double backlashes to avoid escaping by the shell.
A command line script for Database transfer may be found in admin/tool/dbtransfer/cli/migrate.php.
You can purge caches using this script:
Kill all sessions
If needed for administrative reasons, you can kill all user sessions using this script:
As a result, all users will be logged out from Moodle.
Fix course / module sequences
In rare cases (such as after upgrading from a very old version of Moodle), the course / section / module sequence data can be out of sync. This can cause various problems for affected courses, such as sections not appearing, backups failing, pages not displaying etc. There is a specific check to check for errors caused by this problem, and to fix the data in the database if they are found. To run this script please use the command below:
php admin/cli/fix_course_sequence.php -c=* --fix
This will check every course in Moodle and report which ones had errors and were fixed.
Fix orphaned question categories
When a quiz is created, a new question category for the quiz is automatically created. In versions of Moodle prior to 2.9.1, if the quiz is deleted, the question category and any questions in the category remain in database. These orphaned question categories may be fixed by running the admin/cli/fix_orphaned_question_categories.php script with the --fix option.
Search and replace text
This script can be used to search and replace text throughout the whole database. Use carefully and backup first always. More info in Search and replace tool.
php admin/tool/replace/cli/replace.php --search=//oldsitehost --replace=//newsitehost
Build theme CSS cache
If Moodle is not running in theme designer mode it will keep a copy of the compiled CSS on local disk and serve that to the browser when it requests a page. If there isn't a copy on local disk then a copy will be built the first time a page within Moodle is requested.
With this script you can pre-compile the cached CSS files for themes within Moodle to avoid having a user wait for the theme to compile during the first page request.
php admin/cli/build_theme_css.php -- themes boost