Repository navigation
Configuration Reference
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.
| 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. |
| 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.
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. |
- Each entry is an exact host name or IP address. There are no wildcards or suffix matching: an entry like
*.example.comnever 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
.localname 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_HOSTSor$ALLOW_LOCALHOSTby hand, re-runpython3 setup.py --remote-access. - If you lock yourself out, see the recovery steps on the Security page.
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.
(C) 2021 Jeremy Blum, Blum Idea Labs, LLC. This software is licensed under GPL v3