Demo mode for hosts #

This page is for the system administrators of a host that runs a public demonstration site of Exponential, one whose administrator sign-in is published. Demo mode is switched on by the environment variable EXP_DEMO_MODE=1. While it is on, nobody can change or reset the password of an administrator (so the next visitor can still sign in), the installers accept the published demo password, and the administration shows a Demo mode banner.

Contents #

1. The rules of the variable
2. Setting it for each server
3. Installing a demo
4. Checking it
5. Keeping it away from production
6. Risks to tell the demo's owner
7. Related pages

The rules of the variable #

• Environment only. No INI setting, no request parameter and no administration page can switch it on, so a settings file or a database copied from a demo does not carry it to another site.
• Only the exact value 1. 0, true, yes, on and an empty value leave it off.
• Per process. PHP reads it with getenv() first, then $_SERVER, on every call. Every process that serves or maintains the demo needs it: the web server's PHP, Exponential Velocity if it serves the site, cron jobs and console commands. A process without it runs with demo mode off.

Setting it for each server #

Velocity restarts. With export EXP_DEMO_MODE=1 in the demo's site envvars, /etc/vc/sites-available/<site>.envvars, exp:velocity restart and exp:velocity deploy keep demo mode whichever shell runs them: exp:velocity start reads the file at every start of that installation's server, and ./console exp:velocity layout lists it under site envvars. The file is read, never run, and refuses PATH, LD_*, DYLD_*, MALLOC_*, HTTP_*, PHPRC, PHP_INI_SCAN_DIR, HOME, USER and the other loader and shell variables (on-disk layout).

Never in the shared /etc/vc/envvars. The Velocity server of every installation on the host reads it, so demo mode there would reach your customers' production sites. Since 6.0.15 a Velocity worker refuses demo mode from a shared envvars file, keeps it off and logs demo/refused ... came from an envvars file other installations share in var/log/security.log; ./console exp:info shows refused (shared envvars). A demo set up there by an earlier release loses demo mode at the upgrade's restart: move the line to its site envvars first (demo mode).

Installing a demo #

Set the variable for the installation too. The installers (setup wizard, kickstarter, exp:install) then accept the published administrator password even though it is a well-known word and shorter than MinPasswordLength, instead of replacing it with a random one:

EXP_DEMO_MODE=1 ./console exp:install --apply --db=sqlite --password='<the published demo password>' ...

Any non-empty password works, so both publish (seven characters) and publishing do; an empty one is still refused. Only the administrator password of the new installation is relaxed: every other account keeps [UserSettings] MinPasswordLength (10 as shipped) and the well-known list. Do not reset the password after the installation with exp:resetuserpassword: in demo mode that is refused, and it is no longer needed.

A demo that is rebuilt on a schedule (every few hours, from the current code) does this in its build script: install with the variable, swap the new site in, keep the variable in the running site's PHP environment and crontab. The script must not write the variable into config.php, settings/ or anything that is copied to other sites.

Checking it #

• The administration shows the Demo mode banner on every page.
• grep 'demo/mode' var/log/security.log lists every process that started with it (one line per process, with its pid and SAPI); Setup > Log files groups them as demo/mode.
• The audit has a system.demo.mode event per process (always recorded).
• A console command prints Demo mode is on (EXP_DEMO_MODE=1) ... on standard error.

Keeping it away from production #

• Never set it server-wide (/etc/environment, a global SetEnv, the default pool, a base image) or in a provisioning template.
• Alert on it: a demo/mode line in the security.log of a production site, or a system.demo.mode audit event, means the variable reached a process it should not have.
• Add it to the security review: grep -r EXP_DEMO_MODE over the PHP-FPM pools, the virtual hosts, the service units and the crontabs of production machines must find nothing.

Risks to tell the demo's owner #

• Demo mode only protects administrator passwords. A visitor signed in as an administrator can still create accounts, change roles and settings, install packages and upload files: rebuild the demo on a schedule.
• Keep real data, real mail addresses and secrets out of the demo, and send its mail to a file or a sink.
• Other published sign-ins (an editor, a member) are not protected.
• If the variable is lost (a restart from a shell without it), demo mode is off without a sign other than the missing banner.

Related pages #

• Demo mode (for administrators), Demo mode FAQ
• Recipe: run a public demo on LiteSpeed and Plesk, Demo mode problems, Demo mode examples
• Demo mode: the upgrade note
• First sign-in and default passwords
• Hardening for hosts, Security for hosts: overview
• Setting up a demo installation
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.