Agent Configuration

The installed agent reads its settings from one YAML file. woho-client install writes it, and the systemd unit’s ExecStart is just -config /etc/woho/woho-client.yaml — so the connection key never appears in systemctl cat, systemctl show or /proc/<pid>/cmdline.

flag typed on the command line  >  config file  >  built-in default

A flag’s default never overrides the file. There is no built-in server: -server, or server: in the file, is required.

---

Configuration File

Running as	Default path	If missing
root (the installed service)	/etc/woho/woho-client.yaml	Runs on flags and defaults
another user	~/.config/woho/woho-client.yaml	Same
anyone, with -config <path>	the given path	Error

Windows

The Windows service keeps its settings on the service command line; there is no config file on Windows.

Schema

# WoHo server tunnel endpoint. Required.
server: 'woho.example.com:9000'

# Name shown in the panel. Empty means the hostname.
name: 'web-prod-01'

# Connection key. A credential — keep this file root-only.
auth_key: 'XXXX-XXXX-XXXX'

# SPKI pins, for a server certificate the system root store does not trust.
spki_pins: []

# Disable TLS. Only for a server with tunnel_insecure.
insecure: false

# Confine file operations from the panel to this directory. Empty: unconfined.
files_root: ''

# Tell the machine's logged-in users when an admin connects or leaves.
notify_console: false

Field	Flag	Rules
server	-server	host:port, port 1–65535. Use the hostname the server’s certificate covers; by IP you usually need a pin
name	-name	Free text. Empty means the hostname
auth_key	-key	A key from Connection keys
spki_pins	-pin	Each sha256//<base64> or bare base64 of a SHA-256. Empty means the system root store
insecure	-insecure	true disables TLS; the agent warns on every connection. Cannot be combined with pins
files_root	-files-root	Absolute path. In the Files tab ~ becomes this root; nothing outside it is reachable, symlinks resolved. Terminals are not confined
notify_console	file only	true writes a line to every logged-in user via wall when an admin connects or leaves — WoHo: support engineer alice connected, with - this session is recorded when the server records terminals. Linux only; a missing wall is logged and changes nothing else

The file is read once at startup and validated strictly. YAML that does not parse, an unknown field (reported with the known ones), a wrong type, server without a valid port, a pin that is not a SHA-256, insecure: true with pins, or a relative files_root stops the agent with an error naming the field.

Permissions

auth_key is a credential: whoever reads it can register as this machine. The installer creates /etc/woho with mode 0700, writes the file 0600 owned by root, atomically, and never prints the key. If you write the file yourself, keep it 0600; the agent warns when a file with a key is readable by others.

Sharing a host with the server

/etc/woho at 0700 means a WoHo server running as a non-root user on the same host cannot read anything in it. Keep the server’s files elsewhere — see Server Configuration.

Applying a change

vi /etc/woho/woho-client.yaml
systemctl restart woho-client

Or rerun install with just the flag — it keeps every other setting:

To change	Run
Server	woho-client install -server support.example.com:9000
Name	woho-client install -name web-prod-01
Key	woho-client install -key XXXX-XXXX-XXXX
TLS pin	woho-client install -pin sha256//…
Drop the pin	woho-client install -pin ""
Plaintext (test only)	woho-client install -insecure -pin ""
Back to TLS	woho-client install -insecure=false
File root	woho-client install -files-root /srv/exchange
Unconfine	woho-client install -files-root ""

Then restart. install does not restart a running service.

---

Flags

Flag	Default	Description
-config	the default path when it exists	YAML config file. A path given explicitly must exist
-server	none — required	host:port
-name	hostname	Name in the panel
-key	from the file	Connection key. With a config file, -key applies to that run and is not saved
-pin	from the file	SPKI pin(s), comma-separated
-insecure	false	Connect without TLS
-files-root	unconfined	Confine panel-driven file operations to this directory
-v		Verbose logging: stream, terminal, file and reconnect detail
-version		Print version and exit

There is no automatic fallback to plaintext. If the server cannot be verified, the agent refuses to connect and retries the same way.

# Run by hand with a trusted certificate
woho-client -server woho.example.com:9000 -key XXXX-XXXX-XXXX

# Pinned
woho-client -server 10.0.0.5:9000 -key XXXX-XXXX-XXXX -pin sha256//zCpPIQlFlembt2NvzEfpM3FKvYno8QhKwxQPe74gR6k=

# On the installed service's settings, verbose
woho-client -config /etc/woho/woho-client.yaml -v

---

Service Commands

Command	Does
install	Copy the binary to /usr/local/bin/woho-client, write the config file, create and enable the systemd unit, create /var/lib/woho. Rerunning changes only the flags you pass
uninstall	Stop the service; remove the unit, the binary, the config file and legacy auth_key / spki_pin files. Keeps /etc/woho/client_id
start, stop, status	The service

The unit it writes:

[Unit]
Description=WoHo Remote Support Client
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/woho-client -config '/etc/woho/woho-client.yaml'
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=woho-client
WorkingDirectory=/var/lib/woho
TasksMax=512

[Install]
WantedBy=multi-user.target

Do not add flags to ExecStart: a flag there overrides the file and makes it misleading.

An install from before the config file existed keeps working after a binary upgrade. Running install once migrates it: the old unit’s flags and the auth_key / spki_pin files are imported into the YAML file, the unit is rewritten to -config, and only then are the old files removed.

Logs

journalctl -u woho-client -f

Normal logs cover connection state, admin connections and file operations; -v adds stream, terminal and reconnect detail. Transport is named on every connection: TLS 1.3, system root store, TLS 1.3, pinned (1 pin(s)), or PLAINTEXT (insecure).

Log line	Cause	Fix
certificate signed by unknown authority	Not publicly trusted, no pin	A trusted certificate, or -pin
does not match any configured SPKI pin	Wrong pin, or the server’s key changed	Compare with the server’s startup log
certificate is valid for X, not Y	-server names a host the certificate does not cover	Use the covered hostname, or a pin
read server handshake: EOF after an INSECURE MODE warning	-insecure against a TLS server	Remove -insecure
AUTH_REQUIRED / AUTH_FAILED	Key missing, revoked, or bound to another machine	Connection keys
The service restarts every 10 s	A refused registration — usually a revoked key	Same

---

Connection Behaviour

Reconnect backoff: 1, 2, 5, 10, 30 s, then 60 s, reset after a successful connection. Heartbeats every 30 s; the server drops a connection silent for 120 s. Stats are reported every 10 s.

The client ID is stable across reconnects; the server session is not. When the tunnel drops, running terminals end, and the panel offers Reconnect once the machine is back. Why a session ended is on the machine’s timeline: agent closed, read timeout, replaced by a new connection, key revoked, closed by admin, server shutdown.

Client Identity

Each agent generates a UUID on first run and keeps it in client_id in its config directory: /etc/woho/ as root, ~/.config/woho/ as another user, %AppData%\woho\ on Windows. The server tracks the machine by it, and the connection key is bound to it. uninstall keeps the file, so a reinstall is the same machine. After an OS reinstall the UUID is new: Reset the machine’s key in the panel.