Web server

FAQ › EUZOS Server › Web server · Nederlands

What is it?

Web server (web) is a server package of EUZOS Server: it serves static websites and works as a reverse proxy to internal servers, on TCP 80 (HTTP) and 443 (HTTPS, TLS 1.3). Certificates come automatically from Let's Encrypt with EUZOS's own ACME client, or are uploaded by the admin. Everything is managed with Server Admin from an EUZOS PC; the design is in docs/PACKAGE-WEBSERVER.md.

Remote management goes through the admin protocol of Workplace management (port 8446), so a web server is installed together with that package.

How do I…?

How do I install and turn on the web server?

Choose Web server in the installer (off by default): it writes \EOS\FW\WEB.TXT with role=web. After the first boot, turn it on in Server Admin:

serveradmin <server> package-on web

Turning it on opens allow tcp 80 anywhere and allow tcp 443 anywhere in the firewall. package-off web confirm stops serving and closes 80 and 443.

For an internal site, choose the LAN first, then nothing is ever open from outside the own subnet:

serveradmin <server> web settings access=lan
serveradmin <server> package-on web

Turning it on then opens allow tcp 80 lan and allow tcp 443 lan. On a server installed without Web server, web settings sets the package up (still off). Let's Encrypt cannot reach a LAN-only server: use cert=local or cert=upload.

How do I put an internal site on the server in one go?

serveradmin <server> web lan-site-from intranet.example usb:site.zip

One command, the first time and for every update. usb: reads the zip directly from a stick; without it, the path is in My files. It sets access=lan, adds the site, turns the package on, makes sure 80 and 443 are open for the LAN only (and stops otherwise), makes a certificate on the server (cert=local), uploads and publishes. The site also answers on the private address of the server, so no DNS record is needed. It is refused while other sites are on access=anywhere.

To avoid the browser warning, open http://<server address>/lan-ca.crt once on a device and trust it, after comparing the SHA-256 in the reply. That CA can only vouch for this site and for private addresses.

How do I add a site?

serveradmin <server> web site-add example.com aliases=www.example.com
serveradmin <server> web site-add intranet.example cert=none redirect=no hsts=no

Options: cert=acme (default, Let's Encrypt), cert=upload, cert=local (made by this server) or cert=none (HTTP only); address=yes (also on the private address of the server, only with access=lan); redirect=yes|no (HTTP → HTTPS, default yes); hsts=yes|no (default yes, only sent with a real certificate); aliases= (up to 8 more names). Change with web site-set <domain> key=value, remove with web site-remove <domain> confirm (also deletes its files and certificate).

How do I put the files of a site on the server?

Put the site in My files on the EUZOS PC (a folder, or a .zip), then:

serveradmin <server> web upload-from example.com Documenten/mysite
serveradmin <server> web upload-from example.com Documenten/mysite.zip

The PC sends the files one by one (each as a signed command, at most 16 MiB per file), and the server publishes them at once at the end. A single top folder in a zip is stripped. Files whose names start with a dot (except .well-known) are skipped. A directory serves its index.html. Put a style.css.gz next to style.css to have it sent compressed.

How do I make a new website?

Server Admin → the server → Web server: a second column lists the websites. Press New website, choose LAN only or Public, type a name or domain, and press Add. It gets a public_html with a simple first page. A public website is reachable from the internet once the access of the whole web server is Anywhere (top of the column); that does not change by itself. Click a website for its tabs: Files, Git version, SSL certificate and Others. In a narrow window the column becomes a row of buttons above the content.

How do I manage the files of a site?

Server Admin → the server → Web server → a website → Files. public_html is what visitors get; repo shows the working files of its repositories, read only. In public_html: Open a folder, New folder, Rename, Remove (asks first), Download (Save as, to your own folders) and Upload (Open, from your own folders). At most 16 MiB per file through these dialogs, in pieces, with progress and Stop. An existing file is not replaced: delete or rename it first.

A site from before this keeps working: its files are simply its public_html.

How do I deploy a site from Git?

Web server → a website → Git version. Add a repository with its https:// URL. For a private repository press Set token; the field shows no text and the token cannot be shown again. Choose a branch, press Update from remote (it goes on when you close the window), check the commit, and press Deploy HEAD. The site switches in one step; Roll back returns to the previous version.

No firewall rule is needed: outgoing HTTPS passes and nothing opens inbound. Symbolic links in a repository are not followed or written, and submodules are ignored; both are shown next to the commit. Dotfiles are not deployed, because the server never serves them.

How do I get a certificate?

With cert=acme the server asks Let's Encrypt itself, soon after the site is added and then every 12 hours if needed (renewal 30 days before expiry). Requirements: the name points to the server's public address and port 80 is reachable from the internet (http-01 challenge). Ask now with web cert-renew <domain>; look with web cert <domain>. Use web settings acme=staging to test first (a test build uses staging by default).

To upload your own certificate (P-256 key; RSA is not supported):

serveradmin <server> web cert-from example.com certs/chain.pem certs/key.pem

How do I set up a reverse proxy?

serveradmin <server> web proxy-add example.com /app/ http://<lan-address>:8080/ strip=yes
serveradmin <server> web proxy-add example.com /api/ https://<lan-address>:8443/ pin=<64 hex>

The backend must be a private IPv4 address (10/8, 172.16/12, 192.168/16): no open proxy. pin= is the SHA-256 of the backend's public key (for a self-signed internal server). Remove with web proxy-remove <domain> <prefix>.

How do I see the state and the log?

web (or web status): package, ACME settings, sites with files and certificate state, proxy rules, traffic. web log [n]: the last lines of the access log. On the server console: webserver.

Details

• Limits: 64 connections, 8 per address; the header within 10 s (slowloris), 16 KiB of header, max-body (default 1 MiB) for request bodies; 5 s idle between keep-alive requests.
• Streaming: a request body for a reverse-proxy route goes to the backend while it arrives (at most 256 KiB per request in memory; a chunked body is passed on re-framed); a site file uploaded with Server Admin goes to the store in 64 KiB pieces after the admin's signature is checked, and is only put in place when exactly the signed size and SHA-256 arrived.
• Access log (GDPR): time, address, host, method, path without query, status, bytes, duration. Addresses are truncated (last octet 0) after ip-days (default 7; 0 = never stored), files are deleted after log-days (default 30). Set with web settings.
• Storage: sites, certificates, the ACME account and the log are on partition 2 in an encrypted area of their own (key WEBKEY.TXT).
• Not yet: HTTP/2, WebSocket through the proxy, files over 16 MiB per upload, wildcard certificates (DNS-01), IPv6.

Reference

Console commands

Server Admin: web sub-commands

Config files

API endpoints

See also

• docs/PACKAGE-WEBSERVER.md
• docs/EXCEPTIONS.md (U-21, Let's Encrypt)
• Packages, Server Admin, Network and firewall