Skip to content
CodonicOarbank docs

The coordinator service

From Oarbank 2.9 the coordinator is a system service on every operating system. It starts when the computer starts, before anyone logs in, keeps running when you log out or someone else uses the computer, and runs under an account of its own. The menu bar or tray app, Oarbank Coordinator, only shows it: quitting or hiding the app never stops the coordinator.

Where it runs

Section titled “Where it runs”

There are two services, dev.codonic.oarbank.oarbankd (the coordinator) and dev.codonic.oarbank.console (the web console), on every OS.

macOS Linux Windows
Services launchd daemons in /Library/LaunchDaemons systemd system units in /etc/systemd/system Windows services, delayed automatic start, restarted after a crash
Account _oarbankd (hidden, no login shell) oarbankd (a system account) a virtual account per service
Owners’ group _oarbankadmin oarbank-admin administrators (an elevated prompt)
State /Library/Application Support/Oarbank/coordinator (only _oarbankd may enter) /var/lib/oarbank/coordinator (only oarbankd) C:\ProgramData\Oarbank\coordinator (SYSTEM, administrators and the two services)
Logs logs/ in the state directory (read with sudo) logs/ in the state directory (read with sudo); systemctl status dev.codonic.oarbank.oarbankd logs\ in the state directory
Programs /Applications/Oarbank Coordinator.app /opt/oarbank/coordinator C:\Program Files\Oarbank\Coordinator\package
Your owner signing keys ~/Library/Application Support/Oarbank/keys ${XDG_CONFIG_HOME:-~/.config}/oarbank/keys %APPDATA%\Oarbank\keys of the account that set it up

The coordinator’s account is not the node agent’s (_oarbank on macOS, oarbank on Linux): on a computer that is both coordinator and node, a compromised agent cannot reach the coordinator’s database or keys. The programs belong to root, so the service cannot change what it runs. Your owner signing keys stay with you, in your own home: the service never reads them, so a compromised coordinator cannot sign releases or moves as you.

The coordinator’s own secrets (its audit key, the module secrets key) are files only the service account can read, on macOS too (before 2.9 they were in the owner’s login Keychain, which stays locked until that person logs in).

Who may use the CLI

Section titled “Who may use the CLI”

The oarbank command reaches the coordinator through a local admin channel. Whoever is in the owners’ group is an owner and needs no token; anyone else on the computer cannot even see the channel. The person who sets up the coordinator is added to the group. To add another owner:

Terminal window
sudo dseditgroup -o edit -a <user> -t user _oarbankadmin
dscl . -read /Groups/_oarbankadmin GroupMembership     # who is in it

The new member can use oarbank at once.

Anywhere else (another account, another computer), sign in with oarbank console login or use a personal access token from oarbank token create.

The oarbank command on the PATH

Section titled “The oarbank command on the PATH”

From 2.9 the coordinator packages put oarbank on the PATH. Open a new terminal after installing.

oarbank oarbank-setup
macOS /usr/local/bin/oarbank, a link into /Applications/Oarbank Coordinator.app/Contents/Resources/coordinator/bin/oarbank (an existing oarbank there that is not a link is left alone) /usr/local/bin/oarbank-setup
Linux /usr/bin/oarbank, a link to /opt/oarbank/coordinator/bin/oarbank /usr/bin/oarbank-setup
Windows C:\Program Files\Oarbank\Coordinator\package\cli is on the system PATH; its oarbank.cmd runs the build the services use C:\Program Files\Oarbank\Coordinator\package\oarbank-setup.ps1

The full paths keep working and behave the same.

The menu bar and tray app

Section titled “The menu bar and tray app”

Oarbank Coordinator shows the coordinator’s status and opens the web console (Open web app). It runs as you and never holds account credentials or keys.

The app has one setting, Show Oarbank Coordinator in the menu bar (in its Settings…). It is on after the app’s first launch: the item is shown and the app opens when you log in. Hide from Menu Bar (⌘Q) turns it off and quits the app; the coordinator keeps running. Open the app from Applications to get its window back.

The window says how the coordinator runs: “Runs as a system service — starts with the Mac, before anyone logs in, as _oarbankd, and keeps running when this app quits.” The coordinator’s glyph is the logo’s three oars; the node’s is one oar.

When the node package is installed on the same Mac, the coordinator’s menu also shows This Mac’s Node (its state, Join this Mac… while it has not joined, Oarbank Node… for the node’s window), and Oarbank Node keeps out of the menu bar, so each Mac has one Oarbank item.

In System Settings, General → Login Items → Allow in the Background lists the coordinator’s two services under Oarbank Coordinator. Switching that entry off stops them from starting; the app then offers Open Login Items… to switch it back on.

The node’s own app, Oarbank Node, follows the same model, with a managed policy key that hides it: Adding machines.

Open the console from another device

Section titled “Open the console from another device”

The web console and its module frames listen on http://127.0.0.1:7400 (frames on 7402) only, until you choose more in Settings → Access (or with the CLI). The choice is a setting, so a system-service install needs no edited service file: the console picks up a change within seconds, on macOS, Linux and Windows alike, and the desktop app’s Open web app keeps using localhost.

  • Console listen addresses (console_listen): localhost is always included. Add tailscale to listen on this machine’s Tailscale addresses (followed when they change), or an IP address of this machine:

    Terminal window
    oarbank settings set console_listen localhost,tailscale

    Then open http://<this machine's Tailscale address>:7400 from another device of your tailnet. all listens on every interface, so anyone who can reach the machine reaches the sign-in page; saving it asks you to type console_listen. Prefer tailscale.

  • Console over https (Tailscale) (console_https): passkeys need a host name in a secure context, so they never work at an IP address. Set it to tailscale and the console is served at https://<this machine's MagicDNS name>/ through tailscale serve (tailnet only, never Funnel); module frames use port 8443. Turn on MagicDNS and HTTPS certificates in your tailnet first. On Linux the console’s account may not change Tailscale’s configuration: the Settings page then shows two commands to run once as root (or make that account Tailscale’s operator).

    Terminal window
    oarbank settings set console_https tailscale

  • Console host names (console_hosts): another name in front of the console, such as your own reverse proxy.

Every address asks for a sign-in. oarbank console login prints a one-time link for each address the console listens on; open the one your browser can reach. The Listening now card under Settings → Access shows where the console listens, and why an address is not bound yet.

Setting up

Section titled “Setting up”

The package installs the software only (on macOS and Linux it also creates the service account, the owners’ group and the state directory). The first-run wizard asks for the address nodes reach, your administrator name and password (at least 12 characters), checks your authenticator app and creates your primary and backup owner signing keys. Its one privileged step starts the system services: the system’s administrator prompt on macOS, polkit on Linux, UAC on Windows. Run the wizard as the ordinary user who will own the coordinator; everything after the services start goes through the admin channel, which you reach as a member of the owners’ group. Get started walks through it.

Choose an agent address that exists before anyone logs in: a LAN address, or a tailnet address from a VPN client that connects at boot (for Tailscale on macOS, the tailscaled variant, such as Homebrew’s tailscale service; the App Store and Standalone apps connect only after a login). Until the address exists, the coordinator retries every 10 seconds.

FileVault. A Mac with FileVault that lost power waits at the disk unlock screen until someone types a password; nothing on the disk runs before that, the coordinator included. Restarts that unlock the disk for you (macOS updates that do so, sudo fdesetup authrestart) bring the coordinator back with nobody logged in.

Local Network privacy (macOS). macOS lets launchd daemons use the local network without asking, so the coordinator announces itself for discovery with nobody at the Mac.

Check and restart it

Section titled “Check and restart it”
Terminal window
oarbank coordinator status      # includes "form  system service — runs from boot, as _oarbankd"

The console’s Coordinator page shows the same. A coordinator still running in the 2.8 per-user form shows a warning there and in a banner across the console (“runs only while … is logged in; move it to a system service”).

If the services stopped, run oarbank-setup (on the PATH on macOS and Linux; on Windows C:\Program Files\Oarbank\Coordinator\package\oarbank-setup.ps1). It asks for an administrator and starts them again on the existing installation; it never creates a new fleet. Installing a newer package restarts the services by itself, from the record of how they were set up (/Library/Application Support/Oarbank/coordinator-service.json on macOS, /etc/oarbank/coordinator-service.json on Linux).

To look at the services directly:

Terminal window
sudo launchctl print system/dev.codonic.oarbank.oarbankd
sudo ls "/Library/Application Support/Oarbank/coordinator/logs"

Known limitations in 2.9.0

Section titled “Known limitations in 2.9.0”

These parts of the system service were built and tested on virtual machines and containers but not yet on every real setup:

  • On macOS, Allow in the Background names Oarbank Coordinator only for Developer ID signed builds; ad hoc test builds are listed as an unknown developer.
  • The FileVault unlock path, the administrator prompt shown from the wizard and the app, and Intel Macs have not been verified.
  • On Linux, the polkit prompt and the .deb and .rpm packages themselves (as opposed to their install scripts) have not been verified on a real install.
  • On macOS, whether a person added to the owners’ group can use an already-running wizard without restarting it has not been verified.

Report what you see on roeehrl/oarbank.