ELX-VNetwork server
===================

This package is the server and its web panel. The machines themselves run the
client, package elx-vnetwork; both can be installed on the same machine.

What the package puts where
---------------------------

  /opt/elxvnet/elxvnet-server       the program
  /etc/elxvnet/config.json          configuration (created on first install)
  /var/lib/elxvnet/                 database, keys, files offered for download
  elxvnet-server.service            systemd unit, enabled and started

After the first install
-----------------------

The panel listens on port 9191 on every interface, over HTTPS with a
certificate the server makes for itself (the browser warns about it once):

  https://<server-address>:9191/        the dashboard
  https://<server-address>:9191/admin   the server administrator's pages

Sign in to /admin as admin / admin: the pages ask for a new password at once
and do nothing else until it is set. Accounts for the dashboard are created
there, under Users — there is no signing up. From the command line:

  sudo /opt/elxvnet/elxvnet-server -config /etc/elxvnet/config.json -set-password NEW
  sudo systemctl restart elxvnet-server

If a firewall is on, port 9191 has to be opened for this first look
(ufw allow 9191/tcp) — and closed again once nginx is in front.

Machines will not join with the self-signed address, and should not: they
need the real domain and certificate described below.

Before real machines connect: HTTPS
-----------------------------------

The self-signed HTTPS on port 9191 is for trying the server out. In use it
belongs behind nginx on port 443 with a real certificate: the machines check
the certificate, and their traffic must look like an ordinary visit to a
website. You need a domain name pointing at this machine.

1. Make the server listen on the loopback interface only, in plain HTTP —
   nginx does the TLS from now on. In /etc/elxvnet/config.json set

     "addr": "127.0.0.1:9191",
     "tlsAddr": ""

   and run: sudo systemctl restart elxvnet-server

2. Install nginx and certbot, get a certificate:

     sudo apt install nginx certbot
     sudo certbot certonly --webroot -w /var/www/html -d vnet.example.com

3. Take the example site, replace vnet.example.com with your domain, enable it:

     sudo cp /usr/share/doc/elx-vnetwork-server/nginx-example.conf \
             /etc/nginx/sites-available/vnet.example.com
     sudo ln -s /etc/nginx/sites-available/vnet.example.com /etc/nginx/sites-enabled/
     sudo nginx -t && sudo systemctl reload nginx

   Keep the WebSocket headers, the long timeouts and "proxy_buffering off" —
   without them the network either does not come up or drops every minute.

4. Set the server address for links in letters: /admin, page "Mail", field
   "Server address" = https://vnet.example.com (or "publicUrl" in
   config.json). Until it is set, "Forgotten your password?" letters are not
   sent — an address taken from the request could be forged.

Clients then join with:

  sudo elxvnet join -server https://vnet.example.com -invite ELX-XXXX-XXXX-XXXX

No domain, only an IP address
-----------------------------

The server can do TLS itself with any certificate you give it, in
/etc/elxvnet/config.json:

  "web": { "addr": "", "tlsAddr": ":443" },
  "tls": { "cert": "/etc/elxvnet/tls/fullchain.pem",
           "key":  "/etc/elxvnet/tls/privkey.pem", "selfSigned": false },
  "publicUrl": "https://203.0.113.10"

then: sudo systemctl restart elxvnet-server (also after every renewal — the
files are read at start). The files must be readable by the user elxvnet.

The certificate has to be issued for that IP address by a trusted authority;
the self-signed one is fine for the pages in a browser, but machines refuse
it. The easiest way without buying a domain: a name such as
203-0-113-10.sslip.io points at 203.0.113.10 by itself, and certbot issues an
ordinary certificate for it — then follow the nginx steps above.

Mail
----

Mail is needed for "Forgotten your password?" letters and for mail
notifications: /admin, page "Mail" — SMTP server, account, and the server
address that goes into links. Without it the server works; those letters do
not go out.

Updating and removing
---------------------

  sudo apt upgrade            the configuration and the database are kept
  sudo apt remove ...         stops the server, keeps everything
  sudo apt purge ...          also deletes /etc/elxvnet

The database in /var/lib/elxvnet is never deleted by the package: it holds
every account, segment and machine. Remove it by hand if you mean to.

Moving to another machine: /admin, page "Transfer", exports everything into
one file. Copy /var/lib/elxvnet/secrets.key across as well — without it the
saved machine passwords cannot be decrypted.

Supported systems
-----------------

Debian 11 or newer, Ubuntu 20.04 or newer; amd64 and arm64. The program is a
single static binary; what sets the floor is systemd 235, needed by the unit.
