Docs / Obsidian Remote / Administrators

Installing the server

The Obsidian Remote server gives your PCs their IDs, introduces them to each other, relays sessions between networks, and carries the admin console and the web viewer. It is a single program on one HTTPS port (21114 unless you change it), with its own small database. There is no separate database server or relay to install.

Choose how to install it

The ISO, the VHDX and the OVA make an appliance: a server that runs only Obsidian Remote and is managed from its own screen. See The appliance. The package and the appliance update from Integrators Resource's signed repository; the tarball is updated by installing the next tarball.

What you need

• A 64-bit (x86-64) machine. The appliance: 2 CPU cores, 2 GB of memory and a 32 GB disk (what the VM images start with); give relayed sessions more CPU and bandwidth as they grow. The package or the tarball: about 250 MB of disk space on top of the system, plus room for the database and its audit log.
• One inbound TCP port that your PCs and technicians can reach: 21114, or 443 if you put the server behind a reverse proxy.
• A DNS name for it, for example remote.example.com, is recommended.

The server's only outbound connection of its own is the monthly country list for country blocking, from download.db-ip.com over HTTPS (geoip.enabled: false turns it off); the appliance also fetches its updates. Relayed sessions pass through it, so give it the bandwidth your remote sessions need.

Checking a download

The server downloads come with SHA256SUMS and SHA256SUMS.gpg, signed by the Obsidian Remote archive key (the key the servers' updates are signed with). Its fingerprint is 1B44 9C8F C3CF B330 37AC 0544 19B0 86D4 01A0 B765. Download obsidian-remote-archive-keyring.gpg from the same folder, then on any Linux machine:

gpg --show-keys obsidian-remote-archive-keyring.gpg      # must show the fingerprint above
gpgv --keyring ./obsidian-remote-archive-keyring.gpg SHA256SUMS.gpg SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS

gpgv must print "Good signature" and sha256sum OK for every file you downloaded; stop if either does not. On Windows, compare Get-FileHash <file> with the line in SHA256SUMS.

The appliance

1. Start the machine from the ISO (choose Install Obsidian Remote, pick the disk and the network; it restarts when done), or create the VM from the VHDX (New-ObsidianRemoteVM.ps1 -Vhdx <file> -SwitchName <switch>) or the OVA.
2. The machine's screen shows where to finish the setup in a web browser: https://<its address>:21114/setup, and a one-time setup code (for example K7QM-4XWD). Open that address from a PC on the same network. The browser warns about the certificate: the server made it itself, so continue to the site. Type the setup code.
   • No address on the screen? The network has no DHCP: press N there and give the server a static address.
   • Rather answer on the machine's own screen? Press T there for the text setup: the same questions as dialogs. It closes the web setup.
3. The wizard asks for:
   • the server's host name, for example remote.example.com,
   • the network: keep it as it is, DHCP (use a reservation) or a static address,
   • the address clients use (normally the host name; from the internet, a DNS name for your public address with the router forwarding TCP 21114; leave it empty and each PC uses the address it reached the server at),
   • the time zone,
   • the password of the remoteadmin account (the machine's screen and SSH; it has sudo), and optionally an SSH public key for it (SSH then takes that key only),
   • whether to turn on the firewall (it opens only TCP 21114, and SSH from the local network, anywhere or nobody),
   • the web console's first administrator (user name and password), so you don't need the setup token.

   Nothing changes until you press Set up the server on the review page. Then the page shows the progress. At the end the server restarts with a new certificate made for its real name, so the browser warns once more: open the link the page shows in a new tab, continue past the warning there, and come back. If you gave the server a new static address, continue at that address instead.

4. The last page shows the web console's address and the client config string to give your PCs (also on the console's dashboard and under Server settings). The machine's screen shows them too.

The setup code is shown only on the machine's screen (and its serial port, for headless VMs); five wrong codes from one address lock that address out for 15 minutes. The web setup is open only until the server is set up.

Afterwards, sign in as remoteadmin on the machine's screen (or sudo obsidian-remote-console over SSH) for the server menu: status and the client config string, the address clients use, network, host name, certificate (use your own PEM files), updates, restarting the server, its log, a backup of configuration and data, firewall, passwords, console users (reset a lost two-factor phone or a forgotten password), time zone, reboot and power off. sudo obsidian-remote-setup runs the whole setup again (as text dialogs on the screen).

Updates: Updates in the server menu checks for and installs them (the Obsidian Remote update only, or everything including Ubuntu's). Ubuntu's automatic security updates stay on, but nothing restarts the server by itself: the menu lists what still needs a restart.

Install the package on your own Ubuntu server

Copy obsidian-remote-server_<version>_amd64.deb to an Ubuntu Server 24.04 machine and run:

sudo apt install ./obsidian-remote-server_<version>_amd64.deb
sudo obsidian-remote-setup

The package installs the server to /usr/lib/obsidian-remote/app, starts the obsidian-remote service and adds the signed update repository, so later versions arrive with sudo apt update && sudo apt upgrade. obsidian-remote-setup is the appliance's text setup (the questions above, as dialogs); skip the steps you manage yourself. The web setup with a setup code is only for the appliance. A server installed earlier from the tarball keeps its configuration and data: the package moves the old service file aside, and /opt/obsidian-remote can then be deleted.

Install it from the tarball

Copy the server tarball, obsidian-remote-server-0.1.0-linux-x64.tar.gz, to the Linux machine and run:

tar xzf obsidian-remote-server-0.1.0-linux-x64.tar.gz
sudo obsidian-remote-server-0.1.0-linux-x64/deploy/install.sh obsidian-remote-server-0.1.0-linux-x64/server
sudo ufw allow 21114/tcp

The last line opens the port in Ubuntu's firewall; use the equivalent if you use another firewall.

The installer:

• creates a system user, obsidian-remote, for the server to run as,
• installs the program to /opt/obsidian-remote,
• writes the configuration, /etc/obsidian-remote/server.json, from an example (only if there isn't one already),
• creates the data folder, /var/lib/obsidian-remote,
• installs and starts the obsidian-remote service, locked down so it can only write to its data folder,
• prints the setup token for the first administrator.

Create the first administrator

The appliance's setup does this for you. Otherwise:

1. Open https://remote.example.com:21114/setup in a browser (use your server's name or address).
2. The server uses its own certificate at first, so the browser warns you; continue to the page. (See Certificates to avoid the warning.)
3. Enter the setup token the installer printed. If you lost it: sudo cat /var/lib/obsidian-remote/setup-token.
4. Choose the administrator's user name and a password of at least 8 characters.

The setup token stops working as soon as the first user exists. Then sign in at https://remote.example.com:21114/ and, first of all, turn on two-factor sign-in for your account under My account (see The admin console).

The client config string

Every PC finds your server with one line, the client config string, for example:

host=remote.example.com:21114;key=AbCdEfGhIjKlMnOpQrStUvWxYz0123456789-_AbCd

You find it in the admin console under Server settings > Client configuration, with a copy button (the dashboard has Copy client config too). Give it to people for the app's Settings > Network, or put it in the installer for a rollout (see Rolling out to PCs).

The key part is the fingerprint of the server's own certificate. The PCs check it on every connection, so nobody can pretend to be your server even though the certificate isn't from a certificate authority.

If the host name in the string isn't the one your PCs should use (for example because you opened the console by IP address), set publicHost in server.json (see below).

Certificates

The server can protect its connections in two ways:

Its own certificate is fine for a start. Two things to know:

• Back up cert.pem and key.pem in the data folder (see Upgrades, backups and logs). A new certificate means a new key, and then every installed PC must be given the new config string.
• The web viewer needs a certificate the browser trusts to work smoothly, so for browser use a certificate from a certificate authority is the better choice.

To use a certificate from a certificate authority (Let's Encrypt or another), set certPath and keyPath in server.json to the PEM certificate chain and its private key, and restart the service. Renewals need no restart: the server notices the new files within 30 seconds and new connections get the new certificate.

Behind nginx

To serve it on port 443 behind nginx with a Let's Encrypt certificate, use deploy/nginx.conf.example from the package: a complete server block with the WebSocket upgrade, no buffering and long timeouts for sessions. In server.json set:

"behindProxy": true,
"port": 21114,
"publicHost": "remote.example.com"

The server then listens only on 127.0.0.1:21114, without TLS, and trusts the forwarded headers from nginx. PCs use host=remote.example.com:443 with no key. Keep the server listening on the loopback address (or an address only the proxy can reach), because in this mode it believes what the proxy tells it.

server.json

The configuration is /etc/obsidian-remote/server.json. Every setting is optional, and // comments are allowed. Restart the service after a change: sudo systemctl restart obsidian-remote.

Running it on Windows

The server also runs as a Windows service. Its package is not on the download page yet: ask us for it. Unzip obsidian-remote-server-<v>-windows-x64.zip, open PowerShell as administrator and run:

powershell -ExecutionPolicy Bypass -File obsidian-remote-server-<v>-windows-x64\deploy\install-windows.ps1

It installs the server to C:\Program Files\Obsidian Remote Server, keeps its settings and data in C:\ProgramData\ObsidianRemoteServer (back that folder up), adds the service Obsidian Remote Server (starts with Windows, restarts if it fails) and a firewall rule for its port, starts it and shows the setup token for the first administrator. Its log is in Event Viewer, under Windows Logs > Application, source ObsidianRemoteServer. Run the same command with a newer package to upgrade; -Uninstall removes it and keeps the data, -Uninstall -RemoveData removes that too. For account recovery, run "C:\Program Files\Obsidian Remote Server\ObsidianRemote.Server.exe" admin reset-2fa NAME (or set-password NAME, users) in PowerShell as administrator.