File Descriptor Socket Passing¶
SWS provides the ability to accept a socket listener as a file descriptor for use in sandboxing and on-demand applications via systemd (Linux), launchd (Macos) or similar.
Tip
The Socket Activation model is an alternative to TCP port binding.
Socket activation is supported by the -f, --fd option or the equivalent SERVER_LISTEN_FD env.
If you are using inetd, its "wait" option should be used in conjunction with static-web-server's --fd 0 option.
Systemd¶
If you're using systemd on Linux, there is a fully working example in the SWS Git repository under the ./systemd directory.
Service example¶
Below is a systemd service example. Follow the steps to create an SWS service using HTTP2 (static-web-server.service). The service will bind SWS to a TCP 443 privileged port without running the server as root.
If you want to change the server port used by the service, edit the value of ListenStream in the static-web-server.socket file.
The template files can be found in ./systemd directory.
# 1. Copy environment file template
# Use an environment variable file, add/modify the values if necessary and
# assign the proper owner/permissions to the environment variable file.
# TIP: you could skip this step and use a config file if you prefer.
cp systemd/etc_default_static-web-server /etc/default/static-web-server
# TIP: For example, you could create a `nologin` user with specific privileges.
# 2. Copy service file templates
cp systemd/static-web-server.s* /etc/systemd/system/
# 3. Make sure that the `EnvironmentFile` and `ExecStart` values
# of the service match to the corresponding file paths in the `static-web-server.service` file.
# TIP: Use absolute paths.
# EnvironmentFile=/etc/default/static-web-server
# ExecStart=/usr/local/bin/static-web-server --fd 0
# 4. Make sure to change this value with an existing user editing the `static-web-server.service` file.
# SupplementaryGroups=www-data
# 5. Create/reuse a directory for placing the certificate and private key.
# TIP: this is an example, you can create/reuse your own dirs.
sudo mkdir /etc/static-web-server
# 6. For example purposes, copy the testing cert/key files.
# TIP: Use your own cert/key files instead.
sudo cp tests/tls/local.dev_cert.ecc.pem /etc/static-web-server/
sudo cp tests/tls/local.dev_key.ecc.pem /etc/static-web-server/
# 7. Create/reuse a root directory (example only)
sudo mkdir -p /var/www/html
sudo sh -c 'echo "<h1>Static Web Server is running!</h1>" > /var/www/html/index.html'
# 8. Reload systemd manager configuration
sudo systemctl daemon-reload
# 9. Start the SWS service
sudo systemctl start static-web-server.service
# 10. Show the status of the SWS service running
sudo systemctl status static-web-server.service
# 11. Enable the service to start automatically at boot (optional)
sudo systemctl enable static-web-server.service
# 12. Analyze and debug the SWS service security
sudo systemd-analyze security static-web-server.service
# If the service was successfully created then you should get something like:
# → Overall exposure level for static-web-server.service: 0.6 SAFE 😀
Testing¶
Alternatively, the lightweight systemfd utility may be useful, especially for testing purposes.
For example, using systemfd utility as follows:
sudo systemfd --no-pid -s http::8091 -- path/to/static-web-server --fd 0
Or if you want to test using an environment variables file then you could use Enve.
sudo enve -f /path/to/environment.env systemfd --no-pid -s http::443 -- path/to/static-web-server --fd 0