Repository navigation
Installation (v4)
These are the instructions for installing V4 of RWSOLS, the current version. For the previous version, see Installation (v3). Already running v3? See Upgrading from v3 at the bottom of this page.
Ready to get the Remote Wake/Sleep-on-LAN Server (RWSOLS) installed? OK! You should read the terminology page first, so you know what we're talking about. Done? Cool.
Before you start, decide how you want to reach RWSOLS when you're away from home. The setup script asks a few short questions, one at a time, that lead to one of three remote access modes, and you can re-run it later to switch:
- None (LAN only). RWSOLS is only reachable from inside your home network. This is the default for a new install. If that's all you want, skip the router and dynamic DNS sections below.
- Port forwarding (the original, legacy method). Static DHCP leases, router port forwards for 80/443, and dynamic DNS, with an optional Let's Encrypt certificate. This is what the rest of this page documents in detail, and it is the default when the script finds an existing install. It is also the mode to use with a free dynamic DNS name from a provider, or with a domain whose DNS is not on Cloudflare.
- Cloudflare Tunnel. No router changes, no open ports, and no dynamic DNS needed (you can still run dynamic DNS for other services). A small service on the Pi connects out to Cloudflare. You need a domain whose DNS is managed by Cloudflare (it does not matter how its IP is kept up to date; the script checks this and only offers the option when it applies, see Is my domain on Cloudflare?), and a Pi that isn't an ARMv6 model (Pi Zero or Pi 1). You can optionally put a Cloudflare Access login in front. Skip the router and dynamic DNS sections below and see Remote Access with Cloudflare Tunnel and Adding Cloudflare Access (optional).
Whichever you pick, the script can also enable a hostname allowlist, which protects against DNS rebinding. See Security for what each mode exposes. All of the settings are described on the Configuration Reference page.
If you are upgrading an existing install, remote access stays as it is unless you opt in. Re-running python3 setup.py shows the checklist with your install recorded as done (remote access as port forwarding, the previous behavior). Nothing is asked unless you choose a section, apart from the one-time automatic security updates question. Two security changes apply to everyone after upgrading: login throttling (5 wrong passphrases lock an address out for 15 minutes) and stricter permissions on the served config.php. Both are described on the Security page.
You'll need to get your remote machine(s) set up to support WOL Magic packets. If you're using a Windows remote machine, and you want to be able to put it to sleep Remotely, too, you need to set that up.
- Ensure that the remote computer(s) supports Wake-On-Lan (WOL) functionality. You may need to boot into the BIOS and permit the computer to be woken up via the network interface. This will look different on nearly every BIOS. You also need to configure the network interface from within the OS to not go into power save mode, and to support Wake events from magic packets. HowToGeek has a good tutorial showing how to enable WOL functionality.
- If the remote computer is Windows 8/10/11, you might need to change some settings to make it reply to ping requests (or else you won't know when it has woken up, and the webapp won't be able to ascertain its state). Follow these instructions to make it reply.
- If you want to be able to put your computer to sleep remotely, in addition to being able to wake it up, you need to install and run the Sleep-on-LAN application server. Download the Sleep on LAN software (v1.1 download link) and run it on your windows computer. Set it to launch at boot so that it will always be ready to go.
- If the Remote computer is Windows 10/11, its Sleep settings may prevent it from supporting Wake-On-LAN. You can fix this by disabling "Fast Boot". You can find instructions how to disable Fast Boot, here.
This section (and the next one) is only needed for the legacy Port forwarding mode. Skip it if you chose None or Cloudflare Tunnel.
If you want to wake/sleep your machines from outside your network, you'll need to setup static DHCP leases, port forwarding, NAT Loopback, and a dynamic DNS service.
- Log into your Router’s administration panel (in most scenarios you can do this by visiting your Gateway IP from your browser). Find the status page and locate the listing of attached clients. Identify your Raspberry Pi and your computer by their hostnames, and copy down their MAC addresses, and IP addresses. In the screenshot below you can see the computer I want to control and the Pi, whose hostname is, appropriately, “raspberrypi.” This will vary by router, but the listing will look something like this (Note: I blurred out some of my personal info):
- Now, find the “DHCP Reservation” or “Static Leases” list in your router’s administration panel. You’ll configure your router to always assign your remote computer and the raspberry pi the same IP address every time they connect to the network. This ensures that you’ll be able to reliably forward data to them through the router. It will look something like this. You can use the currently assigned IP addresses, just make sure that you reserve them for those MAC addresses:
- Next, find the port forwarding configuration screen in your router’s administration panel. You’ll want to route the HTTP port (TCP 80) and HTTPS port (TCP 443) to the Raspberry Pi's IP. These ports will be used to send data to the Raspberry Pi. You’ll also need to forward any remote service ports that you want to use to access the remote computer. If your ISP blocks incoming traffic on port 80 and/or 443, you can route an arbitrary external port to the internal port 80 or 443 on your Raspberry Pi. If you do this, when you eventually access the WOL server, you’ll need to specify the port, like this: wol.example.com:5000. NOTE that if you do this, automatic encryption setup will NOT be possible, so I strongly recommend that you route external port 80 to your Pi if you can. Route the appropriate port for whatever services you want to access on the remote computer. In the screenshot below, I’ve routed port 32400 for Plex Media Server on my Desktop computer that the Pi will will wake up. If you wanted to access an SSH server or SFTP server running on the remote computer, you could additionally route port 22. You can find a listing of ports used by various services on wikipedia. Note that you can always use an arbitrary external port and route it to appropriate internal port. For example, if you wanted to externally access the SSH interface on your desktop, you might consider forwarding external port 5022 to internal port 22 of that computer, since bad actors like to scan the web for open SSH ports and try brute-force attacks on them.
- Ensure that NAT Loopback is enabled on your router. This is necessary for the automatic cert script setup. Most modern routers support this, but you might have to turn it on if it isn't enabled by default.
Legacy Port forwarding mode only. Cloudflare Tunnel does not use dynamic DNS.
Your home network is connected to the internet via your router. The WAN port of your router connects to your ISP via a modem, and is assigned a public-facing IP address. If this IP address is static (unchanging) then you can simply point a domain name that you own at this IP address, and you'll be able to access it using that URL. However, most residential ISPs will not assign you a static IP unless you pay extra for the privilege. Instead, your home's public-facing IP is "dynamic" - it is likely to change whenever your modem power-cycles, or at any other interval the ISP deems fit. If your public-facing IP address is constantly changing, then how can we point a URL at this IP? The answer is to use a "Dynamic DNS Service". These services use a small application within your home network to periodically query for your public-facing IP and automatically update your domain name's DNS record to point at your new IP when it changes. This ensures that when you navigate to your URL (like wol.example.com), it will be pointing at your home network's public facing IP.
Before you decide on your preferred approach for updating your DNS entry, decide what kind of URL you want to use. You can either use a free service like no-ip.com (described below) to get a URL like yoursite.no-ip.org, or you can use your own domain/subdomain. For instance, if you already own a domain like johnsmith.com, you might as well just create a subdomain like myhome.johnsmith.com. You're paying for the domain anyways (subdomains won't cost you any extra), and it will be easy for you to remember. Or, you could also just buy a dedicated domain to point at your home, like johns-home.com. Domains have become very affordable in recent years, with .com domains costing only about $10/year. Note that if you plan to enable encryption for your WOL server, and your ISP blocks port 80 traffic, then you must use a domain provider that allows you add DNS TXT records to authenticate a signed certificate. I don't think that the free no-ip.com allows you to do this. If using your own domain name, I suggest transferring your registration to a registrar that natively supports synthetic DDNS records. I personally use Cloudflare as my registrar and DNS provider, which does support API-based Dynamic DNS changes.
You have two options for how to configure a Dynamic DNS updater client:
- Run ddclient on the Raspberry PI that is hosting your WOL server.
- Use a dynamic DNS updating service that is built into your router, if available.
Option 1 is nice because it keeps all the related functions of the RWSOLS on your Pi. Option 2 is nice because it will continue to work even if you stop needing a WOL Pi server. Option 2 is also more likely to "just work", but it limits the providers that you can use. Instructions for both are provided below.
If you decide to have your Pi update your DDNS entry, just make sure you've selected a domain name provider that is compatible with ddclient: https://sourceforge.net/p/ddclient/wiki/protocols. There are other methods for updating other providers from linux, but they aren't covered in these instructions. You'll follow instructions during the Pi software setup below to setup your ddclient config file.
Sign up for a dynamic DNS updating service that your router supports. Different routers support different services. In the screenshot below, I'm using DynDNS. Unfortunately, DynDNS no longer offers its free services, but NoIP.com does, and is supported by many routers. Another free option is Dynu. Sign up for a free account, and get a URL that looks something like this: yoursite.no-ip.org. Once you’ve got your dynamic DNS account, find the Dynamic DNS (DDNS) updating screen in your router’s administration panel, and enter your account info. Now, you’ll always be able to access your home network, without knowing the IP addresses, and the router will handle automatically updating where the URL directs when your dynamic IP changes!

You're done setting up the network. Time to move on to setting up your actual Raspberry Pi Server!
Now that your router is all set to handle everything, it’s time to get the Raspberry Pi setup. Please note, as of October 2026, RWSOLS is tested and confirmed to work on the "Bookworm" release of Raspberry Pi OS Lite, with Apache 2.4.68 and PHP 8.2.35. It likely will not work correctly on pre 2.4.x versions of Apache, as Apache made several non-backwards-compatible changes to config file formats. I suggest you start with a fresh Pi (any model should work - I've tested this on Pi 3, 4, and 5) running Raspberry Pi OS Bookworm Lite. It should also work on the previous OS version (Bullseye). The correct software versions will be installed automatically by the setup script.
The previous version, 3.x, is documented on the Installation (v3) page. If you need to use older software for some reason, Version 2.x of RWSOLS was tested on Raspbian Jessie and used PHP5/7.0/7.3.
- Setup your Raspberry Pi with Raspberry Pi OS Lite if you haven’t already, and get it connected to your network. I highly recommend using the official Raspberry Pi Imager application to install the LITE version of the Raspberry Pi OS. When you run the imaging tool, do choose to apply OS customizations. Set your desired username and password, and configure Wi-Fi credentials if you will be using it over Wi-Fi. Since you are likely going to be using it headless, enable the SSH server. Write the image to your SD card.
- SSH into your pi using the credentials you configured during boot media creation, as its reserved DHCP local IP address.
- Update your Pi, and install Git:
sudo apt update && sudo apt upgrade -y && sudo apt install git -y - Reboot your Pi! This ensures that any new kernels that were installed during the upgrade process are applied:
sudo reboot - SSH back into the pi after it reboots, and ensure you are in the home directory:
cd $HOME - Clone this Repository to your home directory and then enter it:
git clone https://github.com/sciguy14/Remote-Wake-Sleep-On-LAN-Server.git && cd Remote-Wake-Sleep-On-LAN-Server - Run the setup script, which will perform the necessary package installation, configure permissions, and make adjustments to improve security. As with all scripts from the internet, I suggest you read it and understand it before blindly executing it!
python3 setup.py

- The script shows a checklist of seven sections and what is done or left for each, then goes through them in order. You can stop with Ctrl+C at any time; the next run continues with what is left.
- Base install. Packages, permissions, PHP hardening and the web files. No questions.
- Remote access. The questions come one decision at a time. First: only at home, or also from outside your home? Home only ends the section there. Second, for outside access: what address you will use, a domain of your own or a free dynamic DNS name from a provider. Third, only for a domain of your own: the script looks up who hosts its DNS and shows the result. If that is Cloudflare, it explains Cloudflare Tunnel and port forwarding side by side and asks which you want. In every other case (a free dynamic DNS name, or a domain whose DNS is elsewhere) only port forwarding is possible, so the script explains it instead of asking, and says what it takes to use Cloudflare Tunnel later. A failed lookup never hides the tunnel. If you choose Cloudflare Tunnel, the tunnel and optional Access questions follow here; see the Cloudflare Tunnel page.
- Dynamic DNS (optional). With port forwarding this is required: the script walks you through ddclient (or you tell it your router handles it) and checks that your name resolves to your public IP. If the Remote access section already found that your domain's DNS is on Cloudflare, the script does not ask you to choose a DDNS protocol or type the zone again: it asks "Use Cloudflare to keep example.com up to date?" (default Yes) and goes straight to the API token. Answer No to pick another provider or domain from the full list. With None or Cloudflare Tunnel it is optional and the default is "No dynamic DNS"; set it up only if you want a domain to keep following your home IP for something else. If ddclient is already set up on the Pi, the default is to keep it.
-
HTTPS on your LAN. With port forwarding, the script checks that ports 80/443 reach the Pi and sets up an automatically-renewing signed certificate when the Pi can be reached on port 80 (or offers a self-signed certificate, or no encryption). With None or Cloudflare Tunnel it asks for the name you use to reach the Pi on your LAN (it suggests your Pi's hostname followed by
.local) and how to serve RWSOLS there: keep the existing settings, a self-signed certificate, no encryption, or a trusted certificate for a LAN name in a Cloudflare domain. See Certificates with a tunnel. -
Hostname allowlist. Optional; see Security before enabling it. If you enable it, you tick the names to allow from a single list that shows a reason next to each one (your Pi's
.localname and your router's local DNS name are ticked, the LAN IP is an unticked option, andaadds your own). - Security updates. Asks whether to install security updates automatically (default yes), and then whether the Pi may restart itself at 04:00 when an update needs it (default no). See Security for what this changes and how to undo it.
- Passphrase and computers. You provide the passphrase that will authenticate you. The script then asks for the computers you wish to wake/sleep, one at a time: a name (the label in the drop down), the MAC address and the IP address. After each one it asks whether there are more. It checks what you type (a mistyped MAC or IP address is asked again) and writes the config file for you. On a later run it shows the list you already have, and you can keep it, add a computer, remove one or start over. The sleep command, sleep port and ping timing have sensible defaults and are only asked about if you say you want to change them. At the end the script offers to open the config file in a text editor (nano) so you can double-check it; you can say no.
- The script uses
python3-richfor its prompts when it can install it, and falls back to plain text otherwise. Withpython3-rich, lists are driven with the arrow keys (Up/Down to move, Space to tick, Enter to accept); in plain text mode you type the numbers.
You can now access your web site at the dynamic DNS URL that you specified (port forwarding), at your Cloudflare Tunnel hostname (tunnel), or at your Pi's LAN name (none)! Enjoy Waking and Sleeping remotely.
Run python3 setup.py again. It shows the checklist with the current state of each section, for example:
1. Base install done
2. Remote access Cloudflare Tunnel
3. Dynamic DNS (optional) this Pi updates example.com
4. HTTPS on your LAN self-signed certificate
5. Hostname allowlist on (3 names)
6. Security updates on
7. Passphrase and computers passphrase set
Choose "Run one section again" and pick the section. Only that section's questions are asked. If you change the remote access mode, the script puts the HTTPS section (and Dynamic DNS, when you switch to port forwarding without it) back on the "left to do" list, because their choices depend on the mode.
Starting over. The menu also has "Start over: reset all settings to the defaults and set everything up again" (or run python3 setup.py --reset). It asks first (the default is No). It puts config.php back to the defaults (passphrase, computers, allowed hosts and remote access settings are cleared, so nobody can log in until setup is finished again), clears the record of finished sections, and removes the Cloudflare Tunnel service and the Apache settings the script added. Your old config.php is saved in the setup folder as a hidden file whose name starts with .config.php.before-reset-. Installed software, certificates, automatic updates and dynamic DNS are kept (it offers to remove the dynamic DNS configuration as a separate question). Nothing in your Cloudflare account is deleted; use --remove-tunnel first if you want that.
These options skip the checklist:
-
python3 setup.py --resetstarts over (the same as "Start over" in the menu, described above). -
python3 setup.py --remote-accessasks the mode, Tunnel, Access and allowlist questions in one go. Use it after editing the remote access settings inconfig.phpby hand (so the copy in/var/www/htmland the generated Apache configuration are updated). -
python3 setup.py --remove-tunnelremoves the Cloudflare Tunnel setup that the script created. -
python3 setup.py --auto-updatesasks only the automatic security updates question. - Add
--dry-runto either to print what would be done without changing anything. Add--forceto--remote-accessto replace a conflicting DNS record for the tunnel hostname.
Running python3 setup.py with no options shows the checklist, as above.
Your install keeps working the way it does now. Remote access stays on port forwarding unless you choose something else, and no allowlist, tunnel or Access login is turned on for you.
- SSH into your Pi and enter the folder you cloned:
cd $HOME/Remote-Wake-Sleep-On-LAN-Server - Get the new version:
git pull - Run the setup script:
python3 setup.py - The script shows the checklist with every section recorded as done, and asks nothing unless you choose a section. The one exception is the "Security updates" section, which is listed as left to do until you answer it once (the default is yes; answer no to leave the system as it is).
- To switch to a Cloudflare Tunnel, choose "Run one section again" and pick "Remote access". See the Cloudflare Tunnel page.
Two security changes apply to every install after the upgrade:
-
Login throttling. Five wrong passphrases from one address lock that address out for 15 minutes, even with the right passphrase. Add
$LOGIN_MAX_ATTEMPTS = 0;toconfig.phpfor the old behavior. -
Stricter file permissions. The setup script makes
/var/www/html/config.phpreadable only by root and the web server (root:www-data, mode 640), and the/var/www/html_backup_*folders readable only by root. Usesudoto read them.
The full list of changes is in the changelog.
(C) 2021 Jeremy Blum, Blum Idea Labs, LLC. This software is licensed under GPL v3