Skip to main content

Paths, logs and the installer

Everything the Obacht agent puts on a Raspberry Pi or Linux PC, where to find the logs, and a step-by-step account of what the generated install command and install.sh change. For the Mac, the equivalent folder is ~/Library/Application Support/dev.obacht.macapp/.

Paths​

WhatWhere
Agent binary and helpers/opt/obacht-agent/, CLI symlinked to /usr/local/bin/obachtctl
SQLite database (source of truth: device token, app secrets, desired state)/var/lib/obacht/agent-v2.db plus -wal and -shm
Config/etc/obacht/agent-v2.yml (mode 0600)
Unix socket/run/obacht/agent-v2.sock
Caddy state and certificates/var/lib/obacht/caddy/
App data/var/lib/obacht/<template>/<instance>/
Compose projects of bundle apps/var/lib/obacht/compose/<instanceID>/
Pinned user signing key/var/lib/obacht/user-keys.d/default.pub
Audit log/var/log/obacht/audit.log
WireGuard config/etc/wireguard/wg0.conf
Helpers/usr/local/sbin/obacht-power-toggle, /usr/local/sbin/obacht-self-update
systemd unitobacht-agent.service, runs as User=obacht

The database is the one file that defines the device's identity. Copying it to another machine makes that machine show up as this device.

Logs​

# the agent itself
sudo journalctl -u obacht-agent -f

# since the last boot, no follow
sudo journalctl -u obacht-agent -b

# audit log of changes applied on this device
sudo tail -f /var/log/obacht/audit.log

# logs of one app
obachtctl logs <instance-id>

# the tunnel
sudo wg show wg0
sudo systemctl status wg-quick@wg0

The line to look for after a fresh install is ws connected. Until it appears, the dashboard checklist stays at "Install command ran".

What the install command does​

You never run install.sh directly. The dashboard generates a one-time command of the form curl -fsSL https://<api-host>/i/<alias> | sudo bash, valid for 7 days. That script, in order:

  1. Requires root.
  2. Preflight: apt-based OS only (Debian, Ubuntu Server, Raspberry Pi OS); architecture x86_64, aarch64 or armv7l. Refuses if Docker was installed as a snap, with the hint sudo snap remove docker, then re-run.
  3. Grows the root filesystem if less than 4 GB are free.
  4. Installs curl, tar, coreutils, jq and wireguard-tools.
  5. Creates a WireGuard keypair, registers the public key with Obacht, writes /etc/wireguard/wg0.conf with AllowedIPs = 10.137.0.0/16, and enables wg-quick@wg0.
  6. Creates the obacht login user with your default SSH public key in authorized_keys.
  7. Installs Docker via get.docker.com if missing.
  8. Downloads install.sh from the GitHub release and runs it with your signing key pinned.
  9. If you turned on "Make the obacht user an admin", writes /etc/sudoers.d/010_obacht-nopasswd with obacht ALL=(ALL) NOPASSWD:ALL.

armv7l passes preflight for the agent, but apps are published for linux/arm64 and linux/amd64 only, so a 32-bit OS gets an agent that cannot install anything. Use the 64-bit image.

What install.sh does​

  1. Picks the tarball for the OS and architecture and checks its sha256.
  2. Unpacks to /opt/obacht-agent/, symlinks /usr/local/bin/obachtctl.
  3. Installs the helpers /usr/local/sbin/obacht-power-toggle, /usr/local/sbin/obacht-self-update and the kiosk session script.
  4. Creates the system user obacht with groups docker and systemd-journal.
  5. Writes /etc/docker/daemon.json with max-concurrent-downloads: 2 (on a fresh Docker only).
  6. Writes /etc/obacht/agent-v2.yml with the install token.
  7. Pins your signing key to /var/lib/obacht/user-keys.d/default.pub.
  8. Installs and starts obacht-agent.service, then waits up to 120 s for ws connected.
  9. Removes the legacy v1 sudoers files /etc/sudoers.d/obacht and obacht-power if present.

sudoers rules​

Two files can exist.

/etc/sudoers.d/obacht-bootstrap is always written. It lets the obacht user run exactly two things without a password:

/usr/local/sbin/obacht-power-toggle enable|disable
/usr/local/sbin/obacht-self-update <tag>

That is what the "Unlock Power Mode" and "Update agent" buttons in the dashboard use. Nothing else gets root through it.

/etc/sudoers.d/010_obacht-nopasswd exists only if you turned on Make the obacht user an admin when creating the install command. It grants obacht ALL=(ALL) NOPASSWD:ALL, so anything in the web terminal can sudo without a password. Leave it off and admin jobs go through your own account on the device. There is no toggle after install. Remove the file by hand to revoke it.

warning

With the admin rule on, your device key is root on that device. Anyone with your passphrase has the whole machine.

Self-update​

Update agent in the device Overview runs sudo /usr/local/sbin/obacht-self-update <tag|latest> on the device. The helper downloads the release and checks its .minisig signature against the key embedded in the agent, obacht-agent-release-1 (key id 2E7980BE136B606D). A release without a valid signature is not installed. The systemd unit restarts, containers keep running, and the version tile refreshes on the next heartbeat.

A fresh curl | sudo bash install has no key to check against yet. It relies on TLS to the API and the sha256 check inside install.sh.

Reinstalling on used hardware​

On start, the agent prefers a device token already in /var/lib/obacht/agent-v2.db over the install token in /etc/obacht/agent-v2.yml. Running a new device's command on a box that still has an old database connects as the old device, or fails. Delete or move the database first, or use Reset Setup & Generate New Token in the device's Settings tab for the same device. Running the same device's command again is a safe upgrade in place. See Reuse a device or start over.

Next: obachtctl reference.