Skip to content

Configuration Reference

Jeremy Blum edited this page Nov 14, 2026 · 4 revisions

Every setting lives in config.php. The repo has a commented template, www/html/config_sample.php; the setup script copies it to www/html/config.php the first time it runs, and copies that into Apache's webroot, /var/www/html/config.php. Apache serves the copy in /var/www/html. If you edit the repo copy by hand, run python3 setup.py (or python3 setup.py --remote-access if you only changed the remote access settings) to copy it over and regenerate the Apache configuration. Existing settings are replaced in place; settings missing from your file are added in a block at the end, headed "Remote access settings (managed by setup.py; safe to edit by hand)".

Settings are PHP assignments, so strings need quotes, and each line ends in a semicolon.

Set by the setup script

Setting Type Default Meaning
$USE_HTTPS bool false Whether RWSOLS is served over HTTPS. When true, plain HTTP requests are redirected to HTTPS and an HSTS header is sent. Set by the setup script based on your encryption choice. Requests that come in through the Cloudflare Tunnel listener are not redirected (Cloudflare handles HTTPS there).
$APPROVED_HASH string or NULL NULL The hash of your passphrase, created by the setup script. Not the passphrase itself. If it is NULL, nobody can log in.

Computers and timing

Setting Type Default Meaning
$MAX_PINGS int 15 How many times RWSOLS pings the target computer to see if it woke up (or went to sleep).
$SLEEP_TIME int (seconds) 5 How long to wait between those pings. Waking from shutdown is slower than waking from sleep, so adjust to suit.
$COMPUTER_NAME array of strings array("computer1","computer2") The names that appear in the drop down.
$COMPUTER_MAC array of strings array("00:00:00:00:00:00","00:00:00:00:00:00") The MAC address of each computer's network interface, in the same order as $COMPUTER_NAME.
$COMPUTER_LOCAL_IP array of strings array("192.168.0.1","192.168.0.2") The local IP address of each computer, in the same order. Reserve these in your router so they don't change.
$COMPUTER_SLEEP_CMD_PORT int 7760 The port the Windows Sleep on LAN utility listens on.
$COMPUTER_SLEEP_CMD string "suspend" The command sent to Sleep on LAN: suspend, hibernate, logoff, poweroff, forcepoweroff, lock or reboot.
$BOOTSTRAP_LOCATION_PREFIX string "" Where the bootstrap folder is, relative to the index and config files. "" means the same folder. Use "../" if it is one directory up, and so on. Only needed if RWSOLS is part of a bigger web project.

The setup script fills in the settings in this table for you (section "Passphrase and computers"): it asks for each computer's name, MAC address and IP address, and keeps the three lists in step. Editing them by hand works too.

The three $COMPUTER_* arrays must have the same number of entries, and the first entry is computer 0 (the ?computer=0 in the URL).

There's one more setting that isn't in the sample file: if you add $DEBUG = true;, index.php prints the submitted form data (which includes the passphrase you typed) and whether it was accepted at the top of the page. Don't leave it on.

Remote access and security (all optional)

If none of these are present in your file, RWSOLS behaves exactly as it did before they existed.

Setting Type Default Meaning
$ALLOWED_HOSTS array of strings array() The exact host names RWSOLS answers to, for example array("wol.example.com", "raspberrypi.local", "192.168.1.10"). Anything else gets an empty HTTP 421. An empty array turns Host checking off. See the rules below.
$ALLOW_LOCALHOST bool false When $ALLOWED_HOSTS is in use, also accept localhost, 127.0.0.1 and [::1].
$LOG_HOST_REJECTIONS bool false Write a rate-limited line to syslog (tag rwsols) for each request rejected by $ALLOWED_HOSTS. View with journalctl -t rwsols.
$TUNNEL_HOSTNAME string or NULL NULL The public hostname served through Cloudflare Tunnel, for example "wol.example.com". Set by the wizard. Requests for this name are treated as tunnel requests (this matters for Access). Should also be in $ALLOWED_HOSTS if you use the allowlist.
$TUNNEL_ORIGIN_BIND string "127.0.0.1" The loopback address of the Apache listener that cloudflared forwards to. Only used by the setup script when it writes the Apache virtual host.
$TUNNEL_ORIGIN_PORT int 8080 The port of that listener. Also only used by the setup script. Changing it by hand does nothing until you re-run python3 setup.py --remote-access.
$ACCESS_TEAM_DOMAIN string or NULL NULL Your Cloudflare Access team domain, without https://, for example "example.cloudflareaccess.com".
$ACCESS_AUD string or NULL NULL The Application Audience (AUD) tag of your Access application: 64 hexadecimal characters.
$LOGIN_MAX_ATTEMPTS int 5 How many wrong passphrases one client address may send within $LOGIN_LOCKOUT_SECONDS before it is locked out. 0 turns throttling off. Applies even when the line is missing from config.php.
$LOGIN_LOCKOUT_SECONDS int 900 How long a lockout lasts, in seconds. Wrong passphrases are counted over the same period.

How $ALLOWED_HOSTS matching works

  • Each entry is an exact host name or IP address. There are no wildcards or suffix matching: an entry like *.example.com never matches anything.
  • Matching is case-insensitive. The port in the request (wol.example.com:8443) and one trailing dot (wol.example.com.) are ignored.
  • A request whose Host is a bare IP address is rejected unless that exact IP is in the list. So to browse by IP on your LAN, list the Pi's LAN IP, or just use its .local name and list that. IPv6 addresses are written in brackets, like [::1].
  • A request with no Host header is rejected.
  • It is enforced twice: by Apache, using a generated file (/etc/apache2/conf-available/rwsols-allowed-hosts.conf) that covers every virtual host, including the one certbot creates, and again by PHP. Apache's copy is generated from config.php by the setup script, so after editing $ALLOWED_HOSTS or $ALLOW_LOCALHOST by hand, re-run python3 setup.py --remote-access.
  • If you lock yourself out, see the recovery steps on the Security page.

Using Access

Cloudflare Access is on only when both $ACCESS_TEAM_DOMAIN and $ACCESS_AUD are set, and applies only to tunnel requests. Setting just one of them denies all tunnel requests. See Adding Cloudflare Access.

Clone this wiki locally