.. include:: /shortcuts.rstext .. index:: pair: Administration; config.php Config.php variables ------------------------- Some site options cannot be set in the administration area but need to be updated directly on the server in the ``config.php`` file. In this section, you see the settings that are possible and why you might want to include them in your ``config.php`` file for your site. The ``config.php`` file sits in the ``/htdocs`` directory of your site. If you want to view all possible variables and their default values, you can find them in ``/htdocs/lib/config-defaults.php``. You can overwrite any default values by placing the variable in your ``config.php`` file. Anatomy of a config variable ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A configuration variable needs to be written in the correct syntax in order to function. In Mahara, this is done the following way: ``$cfg->variable = value;``. .. figure:: /images/administration/config_variable.* :alt: A typical configuration variable A typical configuration variable #. **$cfg->**: Stands for "configuration" and indicates that what follows is a configuration variable. #. **variable =**: Here you see the variable that is to be set. Generally, it consists of one word, or words are joined together with underscores. The variable cannot contain any spaces. #. **value;**: The value that the variable takes is displayed. The values can be different things, for example: * "true" or "false" * text * numbers * file path .. note:: If you want to change the default behaviour of a variable in your instance of Mahara, copy it from the ``config-defaults.php`` file into your ``config.php`` file so it won't get overwritten when you update the codebase. The ``config.php`` file is never changed by an update or upgrade of Mahara. .. index:: single: config.php; Developer mode single: config.php variables; developermode .. _config_variable_developermode: developermode: Enable or disable developer mode ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``$cfg->developermode = true;`` or ``$cfg->developermode = false;`` When you enable developer mode, the following two changes are made automatically for your site: * ``debug.css`` will be included on each page. You can edit this file to add debugging CSS at your discretion. * The unpacked version of MochiKit will be used. .. note:: ``developermode=true`` is less powerful than the :ref:`productionmode=false `. .. index:: single: config.php; Open Badges displayer sources single: config.php variables; openbadgedisplayer_source .. _config_variable_openbadgedisplayer_source: openbadgedisplayer_source: Open Badges displayer sources ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``$cfg->openbadgedisplayer_source = '{"shortname":"url","shortname":"url"}';`` In order to display Open Badges in the :ref:`"Open Badges" block `, the sites that host the badges need to be configured. Per default, the `Mozilla Backpack `_ and the `Open Badge Passport `_ can be connected to. If you have other sources, you would need to add them to the allowed sources. .. index:: single: config.php; Set a site-wide password salt (passwordsaltmain) single: config.php variables; passwordsaltmain .. _config_variable_passwordsaltmain: passwordsaltmain: Set a site-wide password salt ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``$cfg->passwordsaltmain = 'your secret phrase here';`` A password salt helps "hash" passwords more securely in the database to make hacking them more difficult. Using a phrase is a good start. Passwords are already not displayed in plain text in the database, they are hashed. The salt helps randomise that even more. If you don't have a password salt set, you see a warning on the :ref:`"Admin home" ` page. .. index:: single: config.php; Path to ClamAV (pathtoclam) single: config.php variables; pathtoclam .. _config_variable_pathtoclam: pathtoclam: Path to virus scanner ClamAV ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``$cfg->pathtoclam = '/path/to/your/clamscan';`` If you are running the antivirus engine `ClamAV `_ on your server and don't scan for viruses on the system level, you can let Mahara know where to find it so files that are uploaded are scanned. For security reasons, the path to ClamAV on your server needs to be provided in the ``config.php`` file. You can see the path that has been set in the :ref:`"Security settings" `. .. index:: single: config.php; Give users probation status (probationenabled) single: config.php variables; probationenabled single: config.php variables; probationstartingpoints .. _config_variable_probationenabled: probationenabled: Give users probation status ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``$cfg->probationenabled = true;`` or ``$cfg->probationenabled = false;`` If ``$cfg->probationenabled = true;``, you should set ``$cfg->probationstartingpoints = 2;`` as well. You can set a :ref:`spam probation level ` for your users to prevent self-registered users from posting spam especially on a public site. Use the following two variables to do that: * ``$cfg->probationenabled = true;``: This setting decides whether users can be put on probation. * ``$cfg->probationstartingpoints = 2;``: This setting determines how many probation points a newly self-registered user has per default. In this example, users would get two probation points that they need to get rid off before all functionality is available to them. You can change the probation points individually on the :ref:`user's account settings page ` in the *Administration*. When you enable probation, people who leave comments on a page or artefact and are not logged in, cannot post URLs either. .. index:: single: config.php; Disable production mode single: config.php variables; productionmode .. _config_variable_productionmode: productionmode: Enable or disable production mode ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``$cfg->productionmode = true;`` or ``$cfg->productionmode = false;`` If production mode is disabled, a message is displayed at the top of the screen alerting to that effect. .. figure:: ../images/administration/config_productionmode.* :alt: Info message when site is not in prodution mode Info message when site is not in prodution mode A number of parameters are overridden with sensible defaults for a testing or development site. For the current list of parameters, please see ``init.php``. These settings include: * Print debug, information and warning messages as well as environment targets to the screen and the error log. This helps to see error messages quickly as they appear directly on the screen. * Turn on :ref:`developer mode `. * Disable cache. .. note:: Paradoxically, you will need to set ``productionmode=true`` if you want to fine-tune your settings on a test / development site because ``productionmode=false`` overrides a lot of settings with sensible developer mode defaults. .. index:: single: config.php; Remote avatar server URL (remoteavatarbaseurl) single: config.php variables; remoteavatarbaseurl .. _config_variable_remoteavatarbaseurl: remoteavatarbaseurl: Remote avatar server URL ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``$cfg->remoteavatarbaseurl = 'http://example.com/avatar/';`` Profile pictures of your users can be pulled from an avatar service such as Gravatar. If you run your own service. e.g. `Libravatar `_, you can point Mahara directly to it with this configuration variable. You decide in the :ref:`"User settings" ` whether remote avatars can be displayed or not. .. index:: single: config.php; Rename copied pages and collections (renamecopies) single: config.php variables; renamecopies .. _config_variable_renamecopies: renamecopies: Rename copied pages and collections ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``$cfg->renamecopies = true;`` or ``$cfg->renamecopies = false;`` The site administrator can decide to add "Copy of..." for copied pages and collections. If ``$cfg->renamecopies = true;``, copies of new pages and collections will have "Copy of" prepended to their titles. The default setting is ``$cfg->renamecopies = false;``. .. index:: single: config.php; Hide login sideblock (showloginsideblock) single: config.php variables; showloginsideblock .. _config_variable_showloginsideblock: showloginsideblock: Show or hide the login sideblock ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``$cfg->showloginsideblock = true;`` or ``$cfg->showloginsideblock = false;`` You can hide the login form by adding the value ``$cfg->showloginsideblock = false;`` to your ``config.php`` file. Once you have done that, only a link to the login form is displayed for an administrator or other users with internal Mahara accounts to log into the site. .. figure:: ../images/login_link.* :alt: Link to the login form Link to the login form This is useful if you have single sign-on set up and automatically log in to Mahara via another site. Per default, the value is set to "true" so that the login sideblock is displayed. .. index:: single: config.php; Skins (skins) single: config.php variables; skins .. _config_variable_sitethemeprefs: sitethemeprefs: Choose your browse theme from any theme ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``$cfg->sitethemeprefs = true;`` or ``$cfg->sitethemeprefs = false;`` If the site administrator allowed it, you can choose any theme that is available to you as your browse theme on your :ref:`"Account settings" ` page. In that case, you are not restricted to only use your institution theme or if you are a member of multiple institutions choose between them. .. index:: single: config.php; Skins (skins) single: config.php variables; skins .. _config_variable_skins: skins: Skins ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``$cfg->skins = true;`` or ``$cfg->skins = false;`` You can allow your users to personalise their portfolio pages beyond choosing a theme. This is done via :ref:`skins ` in Mahara. Skins can be created on the :ref:`site level ` or by individuals. Institutions can :ref:`allow or deny the use of skins ` for their users. .. index:: single: config.php; Run the cron or upgrade only when you are authorised (urlsecret) single: config.php variables; urlsecret urlsecret: Run the cron or upgrade only when you are authorised ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``$cfg->urlsecret = 'somesecret';`` Without this configuration variable, anybody can run the cron job (scheduled tasks) on your site or an upgrade potentially causing problems. Place this variable into your ``config.php`` file to overwrite the default value. Choose your own secret phrase (enclose it with single quotation marks) that only select few people know who are allowed to run the cron or an upgrade. Whenever you want to run the cron or perform an upgrade, you need to add your secret word at the end of the URL. The URLs for the cron and the upgrade look like this then (replace "somesecret" with your own secret word): * **cron**: /lib/cron.php?urlsecret=somesecret * **upgrade**: /admin/upgrade.php?urlsecret=somesecret .. note:: When you have a developer instance or a test server that is behind a firewall, you may not want to add the urlsecret every time, especially when you are the only one who has access to those sites. You could put ``$cfg->urlsecret = null;`` into the ``config.php`` files for these sites and circumvent the requirement of entering a secret phrase. However, you should not use that on a production site or any other site that is accessible to many people. .. index:: single: config.php; Internal username counts instead of remote one (usersuniquebyusername) single: config.php variables; usersuniquebyusername .. _config_variable_usersuniquebyusername: usersuniquebyusername: The internal Mahara username prevails when connecting external authentication methods ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``$cfg->usersuniquebyusername = true;`` or ``$cfg->usersuniquebyusername = false;`` This is an :ref:`experimental feature `. When turned on, this setting means that it does not matter which other application the user SSOs from, they will be given the same account in Mahara as the internal username is matched and the remote username ignored.