Start the relay automatically

oar start runs the relay in the background until you stop it or the machine restarts. To have the relay come back by itself, install the autostart: oar service install Added in 0.9.9 sets it up on Linux and Windows. Added in 0.9.15 oar autostart picks either Windows mode, at sign-in or at boot, and oar setup asks for it on Windows. After that you do not need an open terminal, and on a headless host you do not need to log in.

The service runs the same relay as oar start: the same config, the same data folder and the same log folder. Nothing about your conversations changes. Added in 0.9.14 On Windows that holds for both autostart modes too; before 0.9.14 they kept the data inside the installed package (see Data folder of the Windows entries).

The commands #

oar service install
oar service status
oar service remove

oar service status is the default when you give no word. The commands are for global installs; in a git checkout they say so and do nothing. oar alone opens a menu with an entry for the same thing (Install or remove the service). oar setup --start and the macOS and Linux installer install the Linux service for you where a systemd user session exists.

oar service install needs a config: run oar setup first.

Added in 0.9.15 oar autostart names the mode instead of a service:

oar autostart signin    # Windows: at sign-in
oar autostart boot      # Windows: at boot, before anyone signs in
oar autostart off
oar autostart status    # the default when you give no word

On Windows it is the command for both modes, with the same rules as the Autostart (Windows) control in Settings. On Linux it is oar service: signin and boot both run oar service install, off runs oar service remove, and status runs oar service status. On macOS it says Autostart is not supported on macOS yet. Start the relay with: oar start. In a git checkout it says it is for global installs. signin and boot need a config; off and status do not.

Linux: the systemd user service #

Added in 0.9.8

The service is called oar. oar service install writes its unit file to ~/.config/systemd/user/oar.service, enables it and starts it. It also runs loginctl enable-linger for your user. Lingering keeps your user services up while nobody is logged in, so the relay is back after a reboot and keeps running after you log out. Nothing here needs sudo. If lingering cannot be enabled, the command says so and gives the line to run yourself, because without it the relay stops when you log out:

loginctl enable-linger "$USER"

The unit starts the relay with the Node.js that ran the command and restarts it after a crash (Restart=on-failure, after 5 seconds). Added in 0.9.14 It does not restart a relay that stopped with exit code 78 (RestartPreventExitStatus=78): the relay uses that code when it cannot run on its data, for example when another relay holds its lock (see If it does not work). A unit written by an earlier version lacks the line until you run oar service install again. It carries the PATH of the shell that ran oar service install, plus ~/.local/bin and the folder of that Node.js, because a systemd user service otherwise starts with a bare PATH. The relay's sessions find the provider CLIs and node through it. After your PATH has changed, run oar service install again and then oar restart: install rewrites the unit but does not restart a service that is already running.

If a relay that you started by hand is running, install stops it first so the service can take the port. If that relay is busy and does not stop at once, the service is installed and takes over at the next login, or when you run oar start once the relay has stopped.

start, stop and restart #

With the service installed, oar start, oar stop and oar restart go through systemd.

Status and logs #

systemctl --user status oar

shows whether the service runs. The unit does not redirect the relay's output, so systemd keeps it in the journal: journalctl --user -u oar reads it.

The unit also sets the relay's log folder to the logs folder of OAR's state folder (~/.oar/logs by default). The relay keeps a copy of its console there in relay-console.log, and each session worker writes a worker-<session>.log. oar doctor prints the state folder they sit under.

Windows #

Added in 0.9.2

Windows has two autostart modes. Both run the same relay with the same config.

The control is in ⚙️ Settings → General, labeled Autostart (Windows). It shows only on a Windows relay and has three choices:

Off
At sign-in — visible terminal after you log on
At system startup — headless, no logon needed

Added in 0.9.15 In a terminal on Windows, oar setup asks for the mode as its last question, with the mode in force as the default:

Autostart: 1 = at sign-in, 2 = at boot, before anyone signs in (one administrator prompt), 3 = off [3]:

Enter keeps the mode as it is. oar setup --autostart signin|boot|off sets it without the question. If the boot task cannot be read, setup does not ask. When the switch does not go through, setup still writes the config, says The config is written; the autostart step did not go through (see above). and exits 1.

Each switch takes out the other mode's entry, but only one that OAR generated (see Entries OAR did not make).

At sign-in #

Choose At sign-in, or run oar autostart signin or oar service install. They all write the same entry, oar-web-relay.cmd in your Startup folder, so the commands and the control agree. oar autostart off, oar service remove or Off deletes it. None of them starts the relay right away: the relay starts at your next sign-in, or now with oar start. Switching from boot mode to sign-in needs the admin confirmation that removes the boot task.

At system startup #

Choose At system startup, or run oar autostart boot. Registering a boot task needs administrator rights, and the relay runs without them, so Windows asks for one admin confirmation; the elevated part is only the schtasks call. The prompt appears on the PC's own desktop only. oar autostart prints Confirm the administrator prompt to register the boot task … and waits. From a browser on another device, Settings shows Confirm the admin prompt on the PC…. Both wait up to two minutes; a prompt nobody answered by then counts as failed. The task runs as your user without a stored password. Local files and the tunnel work as usual; the task has no credentials for network shares.

Switching back to Off or At sign-in (oar autostart off, oar autostart signin) needs the same confirmation to remove the task. Added in 0.9.15 The control switches the sign-in entry on only after that prompt was confirmed and the task is gone.

Added in 0.9.15 A declined prompt changes nothing: Nothing changed: the administrator prompt was declined. The earlier mode stays as it was, and no file is left behind. If the switch itself fails after the prompt, it puts back the tasks it deleted from their copies (<task>.task.xml.bak in the OAR folder, %APPDATA%\oar), keeps the copies and reports the failure. If the prompt was confirmed but the task cannot be read back afterwards, OAR says so, names the copies, and undoes nothing. In the web UI a failure shows the problem and a command to run from an elevated PowerShell instead.

Added in 0.9.15 Boot mode switches on and off with a space, an apostrophe or non-ASCII characters in your profile path, for example C:\Users\Jürgen. Earlier versions failed there, or took OAR's own task for a hand-made one.

The boot task starts a launcher script that OAR generates, oar-web-relay-launcher.cmd in the OAR folder. Added in 0.9.11 The launcher adds Node.js's folder at the end of PATH. The relay starts its workers on its own Node.js by full path, so they start even though the task's PATH has no node (The agent process).

When a generated launcher is missing or comes from an earlier version, Settings names the difference instead of reporting a failure, and choosing At system startup again (or oar autostart boot) regenerates it. When a change of the setting fails, Settings shows the relay's reason. If a sign-in entry exists beside the boot task, the setting warns that it can start the relay twice; choose At system startup again to clean it up.

oar service only reports this mode. While the boot task is in place, oar service install and oar service remove refuse and point you to oar autostart signin|off or Settings; oar service status prints on, at boot (scheduled task).

Status Added in 0.9.15 #

oar autostart status prints the mode, then each entry there is, and whether OAR generated it:

[oar] Autostart: at boot, before anyone signs in (scheduled task)
[oar]   scheduled task \oar-relay (generated by OAR)
[oar]   C:\Users\dev\AppData\Roaming\oar\oar-web-relay-launcher.cmd (generated by OAR)

The mode is at sign-in (Startup folder), at boot, before anyone signs in (scheduled task), off, or unknown, the boot task could not be read (<reason>). A hand-made entry reads <path> (hand-made), and one left by another OAR install <path> (hand-made: it starts the OAR install in <folder>). When there is one, a last line says how to replace it.

Entries OAR did not make Added in 0.9.15 #

OAR changes only autostart entries that are exactly as an OAR version generated them for this install, in the web UI as in oar autostart. Any other entry is hand-made and is never deleted or written over:

• a Startup entry you edited, or one of another OAR install or config;
• the boot task when it differs from the one OAR registers in the account, the run level, its one action, its one boot trigger or its settings;
• a launcher you edited;
• a task named oar-relay that someone else made, and the pre-rebrand boot task.

While a hand-made entry would stay beside the new mode, or be replaced by it, a switch changes nothing and names the entry:

[oar] Nothing changed: OAR does not delete or overwrite an autostart entry it did not make. Remove it yourself, or replace it keeping a copy: oar autostart boot --replace.
[oar] Left as it is: C:\Users\dev\AppData\Roaming\oar\oar-web-relay-launcher.cmd (hand-made).

The web UI shows the same message. A hand-made entry of the mode you pick serves that mode and stays (Left as it is: …). To replace hand-made entries with OAR's own, run the switch with --replace:

oar autostart boot --replace

It keeps a copy of each entry first, as <name>.bak in the OAR folder (%APPDATA%\oar): the launcher's beside it, a task's exported XML as <task>.task.xml.bak, which schtasks /create /xml takes back, and a Startup entry's there too, because Windows would open a copy left in the Startup folder at sign-in. An earlier copy is never written over: the next one is .bak-2. Nothing but --replace replaces a hand-made entry.

A boot task OAR cannot read, for example one that stores another account's password and answers Access is denied, is never taken as missing. Status says unknown, the boot task could not be read (<reason>), and every switch, --replace included, stops with Nothing changed: the boot task could not be read (<reason>).

Waiting for TEMP and the data drive Added in 0.9.14 #

Both modes wait before they start the relay: up to 5 minutes in all for the %TEMP% folder and for the drive of the data folder, for example a RAM disk or a drive that a startup script mounts later. Before 0.9.14 the system-startup launcher waited 2 minutes for %TEMP% only, and the sign-in entry not at all. A data folder on a network share is not waited for. A TEMP or TMP set with quotes ("D:\My Temp"), or one naming a folder that does not exist, is fixed for the relay: the quotes come off, or it uses your own temp folder.

When the wait runs out, one line names what is still missing and the relay starts anyway:

[<date> <time>] Still missing after 300 s: data drive "R:\"; starting the relay anyway.

The line goes to oar-web-relay-launcher.log beside the system-startup launcher, or to oar-web-relay.log in the OAR folder (%APPDATA%\oar) for the sign-in entry. A relay whose data folder still cannot be created then stops with one line naming the folder, and exit code 78, instead of an error trace.

Data folder of the Windows entries Added in 0.9.14 #

Both entries start the relay on the config, data folder and log folder that oar start uses: %APPDATA%\oar\config.json, %APPDATA%\oar\data and %APPDATA%\oar\logs on a global install. Before 0.9.14 they set only the config file, so a relay they started kept its database, uploads and logs in server\data, server\uploads and server\logs inside the installed package: other conversations than with oar start, and gone with the next update. Update from those versions as the upgrade note says.

The relay brings an entry or a launcher that OAR generated (0.9.0 on, also the pre-rebrand copilot-remote-web-relay.cmd) up to date by itself at its first start after the update, without an admin confirmation. An entry you edited, one that points at another config file, and one of a relay started on data folders of its own are left alone. Added in 0.9.15 They count as hand-made: oar autostart <mode> --replace replaces them, keeping a copy (see Entries OAR did not make). Rewriting a launcher while the relay it started still runs is safe. The launchers switch the console to UTF-8, so a user folder with non-ASCII characters in its name keeps its paths intact.

macOS #

The service is not available on macOS yet. oar service says so and names oar start. After a reboot, run oar start to start the relay again. The installer starts it in the background.

WSL #

The Linux service needs a systemd user session. A WSL distro has one only when systemd is switched on. If it is not, oar service install stops with a hint: set systemd=true under [boot] in /etc/wsl.conf, then restart the distro from Windows with wsl --terminate <distro>. Until then use oar start. The same holds for a container or any Linux without a systemd user session.

Updates #

oar update asks the running relay to restart itself, and it does so once its queue is idle. That also holds with the Linux service: the update does not go through systemd, so it does not cut turns off. See Restarts and resuming. The service and the autostart entries start the installed package, so they run the new version after that restart. Updating the package never touches the config or the data. Added in 0.9.14 The one exception is the update to 0.9.14 from a Windows autostart relay, whose data was inside the package: see the upgrade note.

By platform #

If it does not work #

More startup problems are covered in First run. To install OAR in the first place, see Install.