Skip to main content
emisar

WireGuard VPN

v0.1.12

WireGuard state — interfaces, peers, transfer counts, last handshakes — plus operator actions: bring iface up/down via wg-quick, remove a peer from a live iface. Use to debug connectivity or evict a compromised peer.

5 allowed by default 3 need approval by default
Pack ID
wireguard
Vendor
emisar
OS
linux
Actions
8
Required binaries. Install these on the host before relying on the pack — an action that calls a missing one fails at run time.
wg wg-quick

Install

emisar pack install fetches this pack, re-validates it, and verifies its content hash against the --hash below — the exact bytes this page was rendered against, so a tampered copy is rejected — before copying it into the runner's packs dir. The command reloads a running daemon itself; no manual restart.

on the runner host 
sudo emisar pack install wireguard --hash sha256:8417e4fddf095858bb90e4f0f2991a83c8a2abaf7da3953ba2c0d48b5fd70d30

Setup

Reads and manages WireGuard interfaces on the local runner host — no credentials needed.

Host access

Run these commands yourself on the runner host. Emisar shows and copies setup recipes; it never runs them.

Read or change WireGuard interface state with CAP_NET_ADMIN.

wg.showwg.show_transferwg.show_latest_handshakeswg.show_endpointswg.showconfwg.set_peer_remove

Grant CAP_NET_ADMIN to the Emisar service

Grant access 
sudo install -d -m 0755 /etc/systemd/system/emisar.service.d
printf '%s\n' '[Service]' 'AmbientCapabilities=CAP_NET_ADMIN' | sudo tee /etc/systemd/system/emisar.service.d/10-wireguard-host-access.conf >/dev/null
sudo systemctl daemon-reload
sudo systemctl restart emisar
Verify access 
systemctl show emisar --property=AmbientCapabilities --value | grep -Fwi cap_net_admin

Impact: Every Emisar action on this runner inherits CAP_NET_ADMIN and can change network interfaces, routes, firewall rules, and WireGuard peers outside this pack.

Run wg-quick, including its host networking and configured hook commands, as root.

wg.quick_upwg.quick_down

Run the Emisar service as root

Grant access 
sudo install -d -m 0755 /etc/systemd/system/emisar.service.d
printf '%s\n' '[Service]' 'User=root' 'Group=root' | sudo tee /etc/systemd/system/emisar.service.d/10-wireguard-root.conf >/dev/null
sudo systemctl daemon-reload
sudo systemctl restart emisar
Verify access 
test "$(systemctl show emisar --property=User --value)" = root

Impact: Every Emisar action on this runner executes as root. wg-quick also executes every PreUp, PostUp, PreDown, and PostDown command authored in the interface configuration.

Notes

  • showconf's PrivateKey/PresharedKey lines are masked at the source before output leaves the host.

Verify it works

Runs wg.show, a low-risk read that confirms the pack can reach its target. Run it on the host once the pack is installed; pack install runs it for you.

on the runner host 
sudo emisar pack verify wireguard

Install and configure a pack walks through the whole sequence on a host.

Actions 8 total

View on GitHub
  • wg.quick_down exec high High — service-affecting

    wg-quick down <iface>

    Tear down a WireGuard interface. All active sessions through it drop. PostDown rules run (typically cleaning up routes/firewall).

    View source on GitHub
  • wg.quick_up exec high High — service-affecting

    wg-quick up <iface>

    Bring up a WireGuard interface defined in /etc/wireguard/<iface>.conf. Applies the address, peers, and PostUp rules.

    View source on GitHub
  • wg.set_peer_remove exec high High — service-affecting

    wg set <iface> peer <pubkey> remove

    Remove one peer from a running WireGuard interface. Its tunnel sessions drop. The peer can no longer connect until added back (or the config file is reloaded).

    View source on GitHub
  • wg.show exec low Low — read-only or trivially reversible

    wg show

    List all interfaces with peers + endpoints + last-handshake.

    View source on GitHub
  • wg.show_endpoints exec low Low — read-only or trivially reversible

    wg show all endpoints

    Show per-peer remote endpoint (last known).

    View source on GitHub
  • wg.show_latest_handshakes exec low Low — read-only or trivially reversible

    wg show all latest-handshakes

    Show per-peer epoch of last handshake. 0 means never seen.

    View source on GitHub
  • wg.show_transfer exec low Low — read-only or trivially reversible

    wg show all transfer

    Show per-peer cumulative bytes rx/tx. Use to confirm "is the tunnel actually carrying traffic?".

    View source on GitHub
  • wg.showconf exec medium Medium — changes state, easily reversible

    wg showconf <iface>

    Show the effective config for one WireGuard interface (`[Interface]`/`[Peer]` sections, peer pubkeys, allowed-ips, endpoints). WireGuard owns this key space, so its secret-bearing directives are enumerable rather than guessed at: `wg showconf` writes exactly `PrivateKey` and `PresharedKey`, and both are masked at the source. Rated medium — not low — because that mask, and not the absence of secrets, is what makes the output safe to return.

    View source on GitHub
← Back to registry
Pack reference  Publish your own