Skip to content
Files and paths

Files and paths

The Broker keeps its configuration, identity, peer table, directory and audit log in fixed locations. The locations are chosen by the deployment form: a user Broker serves one account, and a system Broker runs as root and serves every permitted account on the host.

User Broker

PathContents
~/.peers/config.yamlConfiguration, mode 0600. Generated by peers service install if it does not exist.
~/.peers/identity.keyThe Broker’s private key, mode 0600.
~/.peers/identity.crtThe self-signed certificate that matches the key, mode 0600.
~/.peers/peers.jsonPaired peers, mode 0600.
~/.peers/directory.jsonBroker cards and public-topic declarations this Broker knows.
~/.peers/name-owners.jsonThe name-owner table: the account that owns each name and when each name was last held, mode 0600.
~/.peers/audit.logAudit log, mode 0600.
/tmp/peers-<uid>/broker.sockLocal socket, mode 0600.
/tmp/peers-<uid>/broker.lockAccount lock that allows one Broker per account.

<uid> is the numeric account ID. The runtime directory is mode 0700. The identity files are created at the Broker’s first start; peers.json and directory.json appear when the Broker first has something to store. When a user Broker runs as root (for example one that root started with peers service run --user in a terminal), the runtime directory is /run/peers on Linux or /var/run/peers on macOS, the same directory the system Broker uses. Running the Broker directly without service install does not generate the configuration file; when the file does not exist, every key takes its default value.

The runtime directory is normally /tmp/peers-<uid>. When another account has taken that path (it is a symbolic link, it is not a directory or it is a directory owned by another account), the Broker uses a fallback directory: /run/user/<uid>/peers/ on Linux, or peers/ under the per-user temporary directory that getconf DARWIN_USER_TEMP_DIR reports on macOS. The socket and the lock file keep their names inside it. The Broker, sessions and the terminal commands look in both places. The fallback’s parent directory must belong to the account, be a directory rather than a symbolic link and give no access to group or others; when neither location is usable, the Broker refuses to start and names the occupant. The runtime directory for root does not change.

Every minute, the Broker sets the account lock, the runtime directory and the local socket to the same timestamp, without following symbolic links, so a /tmp cleanup rule that deletes old files does not remove them.

System Broker

PathContents
/etc/peers/config.yamlConfiguration, with every key listed, owned by root with the default group peers and mode 0660. Generated by peers service install --system if it does not exist.
/var/lib/peers/identity.keyThe Broker’s private key, mode 0600.
/var/lib/peers/identity.crtThe matching self-signed certificate, mode 0600.
/var/lib/peers/peers.jsonPaired peers, mode 0600.
/var/lib/peers/directory.jsonBroker cards and public-topic declarations this Broker knows.
/var/lib/peers/name-owners.jsonThe name-owner table: the account that owns each name and when each name was last held, mode 0600.
/var/lib/peers/admin-groupThe name of the admin group this installation created, if it created one, mode 0600.
/var/log/peers/audit.logAudit log, mode 0600.
/run/peers/broker.sockLocal socket, on Linux.
/var/run/peers/broker.sockLocal socket, on macOS.
/run/peers/broker.lock or /var/run/peers/broker.lockAccount lock, in the same directory as the socket.

The runtime directory is mode 0755. The socket’s group and mode come from broker.local_socket_group and broker.local_socket_mode; the mode defaults to 0666, which lets every local account connect, and the file permission on the configuration then decides what each account may do.

Service definitions

peers service install writes one service definition:

PlatformFormPath
Linuxuser~/.config/systemd/user/peers.service, or $XDG_CONFIG_HOME/systemd/user/peers.service when XDG_CONFIG_HOME is set to an absolute path
Linuxsystem/etc/systemd/system/peers.service
macOSuser~/Library/LaunchAgents/io.github.wangzw.peers.plist
macOSsystem/Library/LaunchDaemons/io.github.wangzw.peers.plist

Shell completions and man pages

The install script writes the shell completions, and the system installation also writes the man pages:

LevelPathContents
User~/.local/share/bash-completion/completions/peersBash completion.
User~/.config/fish/completions/peers.fishFish completion, written only when fish is installed.
System/usr/local/share/bash-completion/completions/peersBash completion.
System/usr/local/share/zsh/site-functions/_peersZsh completion.
System/usr/local/share/fish/vendor_completions.d/peers.fishFish completion, written only when fish is installed.
System/usr/local/share/man/man1/peers.1 and peers-*.1The man page for peers, plus one page for each command in the help.

The user installation does not install a zsh completion; install.sh prints the command that enables one by hand.

The system installation checks the directories it writes the shell completions and man pages into before writing them. Starting from /usr/local, a component that is a symbolic link, is not owned by root or the account that ran sudo or is writable by group or others makes the install skip that file: it prints a warning with the command to install the file by hand, and the rest of the installation still completes. A completion is skipped with

install.sh: warning: skipped the <shell> completion: <reason>; install it with: <prefix>/peers completion <shell> > <path>

and a man page with

install.sh: warning: skipped the man page <page>: <reason>; install it with: install -m 0644 <src> <dir>/

A user installation writes into its own directories without this check.

The binary’s own directory is checked separately. Every directory from the binary’s directory up to / must be owned by root, not writable by group or others and searchable by others; a directory that fails stops the install with exit code 1, for example with install.sh: system install: <dir> is not owned by root; pass --prefix with a root-owned directory such as /usr/local/bin.

Logs

The Broker writes its run log to standard error and the audit log to the audit file above.

  • A Linux service logs to the systemd journal: journalctl --user -u peers.service for the user service, or journalctl -u peers.service for the system service.
  • The macOS user service writes to ~/Library/Logs/peers/broker.log; the system daemon writes to /var/log/peers/broker.log.
  • A Broker started in a terminal writes its run log to that terminal.

Permissions

A user Broker runs as its account. The Broker creates the data directory with mode 0700 when it does not exist, creates its files with mode 0600 and binds the local socket with mode 0600, so only that account can reach them.

A system Broker runs as root. The configuration file’s permissions decide what other accounts may do with the management tools and the terminal commands: read access allows reading the configuration, the full status and the audit log; write access allows changing the configuration and managing pairings. The system installation already makes the default peers group own a new configuration file and gives the group write access; for an existing file, chgrp and chmod assign it to the group, as Manage a Broker by file permission describes. When the file does not exist and the system Broker creates it through set_config or peers config set, it writes the file as root with mode 0600 instead: the Broker does not know the admin group, and 0600 keeps pairing.static_key away from other accounts. A file created that way has no group write access until an administrator assigns it to the group with the commands in that section. Do not assign the file to the group when broker.listen uses a port below 1024; Configuration keys gives the rule and the fix. The Broker checks the caller’s access to the actual file, so the tools and the terminal commands never let an account do more than editing the file directly would.

The socket and its mode are described under Configuration keys. The project configuration file is described separately under Project configuration file, and Guides covers installing the service.