Skip to content

cli.md

Latest commit

 

History

History
357 lines (246 loc) · 10.3 KB

cli.md

File metadata and controls

357 lines (246 loc) · 10.3 KB
Raw

CLI Commands

meshguard keygen

Generate a new Ed25519 identity keypair.

meshguard keygen [--force]
Flag Description
--force Overwrite existing keys (destructive)

Output files (in $MESHGUARD_CONFIG_DIR, or the platform default config directory):

  • identity.key — secret key (permissions 0600)
  • identity.pub — public key

Safety: Refuses to overwrite existing keys unless --force is passed.

meshguard export

Print your public key to stdout.

meshguard export > my-node.pub

meshguard trust

Add a peer's public key to your authorized keys.

meshguard trust <key-or-path> [--name <name>]
Argument Description
<key-or-path> Base64 public key string or path to a .pub file
--name Human-readable name (default: auto-generated from key)

Validation:

  • Base64 decode check
  • Ed25519 point-on-curve check
  • Key collision check (same key, different name)
  • Name collision check (same name, different key)

meshguard revoke

Remove a peer from your authorized keys.

meshguard revoke <name>

Deletes $MESHGUARD_CONFIG_DIR/authorized_keys/<name>.pub.

meshguard up

Start the meshguard daemon.

meshguard up [options]
Flag Default Description
--seed (none) Seed peer ip:port. Can be repeated.
--dns (none) Discover seeds via DNS TXT records
--mdns false Discover seeds via mDNS on LAN
--announce (auto) Manually specify public IP for announcement
--encrypt-workers 0 Number of encryption threads (0 = serial)
--kernel false Use kernel WireGuard instead of userspace
--gossip-only false Run discovery/rendezvous only, no TUN/WG
--no-tun false Alias for --gossip-only
--open false Accept all peers (skip trust enforcement)

Startup sequence:

  1. Load identity from config directory
  2. Derive mesh IP from public key
  3. Create mg0 interface unless running --gossip-only
  4. Assign mesh IPv4/IPv6 and set MTU (1420)
  5. Run STUN to discover public endpoint
  6. Connect to seed peers
  7. Enter SWIM gossip plus WireGuard event loop, or gossip-only loop

meshguard down

Stop the daemon.

meshguard down

When a userspace daemon is running, this sends a graceful stop request through the control socket (/run/meshguard/meshguard.sock, the per-user config socket fallback, or \\.\pipe\meshguard on Windows). On Linux, if no control socket answers, meshguard down falls back to RTNETLINK teardown for the kernel mg0 interface.

meshguard status

Display the current mesh state.

meshguard status

When a userspace daemon is running, this queries the control socket and reports the node public key, mesh IP, and membership counts. On Linux, if no control socket answers, meshguard status falls back to RTNETLINK and kernel WireGuard Genetlink for mg0 where available.

meshguard version

Print the version.

meshguard version

meshguard config show

Display the current node configuration.

meshguard config show

meshguard service

Manage service access control policies (port-level allow/deny rules).

meshguard service <command> [options]

Subcommands

Subcommand Description
list List all service policies
allow <proto> <port> Add an allow rule
deny <proto> <port> Add a deny rule
default <allow|deny> Set default action (when no rule matches)
show [peer-name] Show effective policy for a peer (or global summary)
reset Remove all service policies

Options

Flag Description
--peer <name> Target a specific peer (by alias or pubkey)
--org <name> Target an organization
(no flag) Target the global policy

Protocol and Port

  • Proto: tcp, udp, or all
  • Port: single port (22), range (8000-9000), or all

Examples

# Global: allow SSH and HTTPS, deny everything else
meshguard service allow tcp 22
meshguard service allow tcp 443
meshguard service deny all

# Set default-deny mode (when no services/ directory exists, default is allow)
meshguard service default deny

# Peer-specific: allow Postgres for node-1
meshguard service allow --peer node-1 tcp 5432

# Org-specific: allow HTTP for all eosrio members
meshguard service allow --org eosrio tcp 80

# List all policies
meshguard service list

# Show effective policy for a peer
meshguard service show node-1

# Clear all policies
meshguard service reset

Evaluation Order

Rules are evaluated in this order (first match wins):

  1. Peer-specific policy (by pubkey or alias)
  2. Org-specific policy (by org name)
  3. Global policy (global.policy)
  4. Default action (services/default file, defaults to allow)

meshguard connect

Direct peer connection via token exchange — no seed server needed. Uses STUN-based coordinated hole punching.

# Generate a connection token (share with your peer)
meshguard connect --generate

# Generate a token that expires in 30 minutes
meshguard connect --generate --in 30

# Join using a token from another peer
meshguard connect --join mg://...
Flag Description
--generate Generate a connection token for a peer to join with
--join Join using a mg:// token from another peer
--in Token expiry in minutes (used with --generate)

Flow:

  1. Peer A runs meshguard connect --generate → prints an mg:// token
  2. Peer A shares the token with Peer B
  3. Peer B runs meshguard connect --join mg://...
  4. Both peers perform STUN discovery, exchange endpoints, and establish a direct WireGuard tunnel
  5. Seeds are saved to config for future meshguard up reconnection

Environment Variables

Variable Description
MESHGUARD_CONFIG_DIR Override config directory (default: ~/.config/meshguard)

Default config directories are %APPDATA%\meshguard\ on Windows, /etc/meshguard when running as root on POSIX systems, otherwise $XDG_CONFIG_HOME/meshguard or ~/.config/meshguard.

meshguard org-keygen

Generate a new Ed25519 organization keypair.

meshguard org-keygen

Output files (in $MESHGUARD_CONFIG_DIR/org/):

  • org/org.key — secret key (permissions 0600)
  • org/org.pub — public key

meshguard org-sign

Sign a node's public key with the organization key.

meshguard org-sign <node-key-or-path> [--name <label>] [--expires <unix-timestamp>] [--wg-pubkey <key-or-path>]
Argument Description
<node-key-or-path> Base64 public key string or path to a .pub file
--name Human-readable name for the node
--expires Unix timestamp when the signature expires (default: 0, never expires)
--wg-pubkey Base64 WireGuard public key string or path to a file. When set, emits a v2 certificate that binds node identity to this WireGuard key.

Without --wg-pubkey, org-sign emits a legacy v1 certificate for mixed-version meshes. With --wg-pubkey, it emits a v2 certificate. Upgrade trust-enforcing peers before relying on v2-only certificates.

meshguard org-vouch

Vouch for an external node. This action auto-propagates to organization members.

meshguard org-vouch <node-key-or-path>
Argument Description
<node-key-or-path> Base64 public key string or path to a .pub file

meshguard org-revoke

Sign an organization certificate revocation for a node key.

meshguard org-revoke <node-key-or-path> [--reason <reason>]
Argument Description
<node-key-or-path> Base64 public key string or path to a .pub file
--reason unspecified, key-compromised, or admin-removed (default)

The command loads $MESHGUARD_CONFIG_DIR/org/org.key, writes a signed OrgCertRevoke wire message to $MESHGUARD_CONFIG_DIR/revoked/*.revoke, and queues that revocation for broadcast the next time meshguard up runs. Revocations are scoped to the issuing org: they invalidate that org's certificate or vouch for the node, not certificates or vouches from other trusted orgs.

meshguard upgrade

Upgrade meshguard to the latest release from GitHub.

Platform: Linux (amd64) only. This command downloads the meshguard-linux-amd64 asset from the latest GitHub release. It is not supported on other operating systems or architectures.

Privileges: Requires write access to /usr/local/bin/meshguard. Run with sudo if the current user does not have sufficient permissions.

Service management: Uses systemctl to stop the meshguard service before installing the new binary and restart it afterwards. Ensure systemd is available on your system.

meshguard upgrade
# or, if elevated privileges are required:
sudo meshguard upgrade

The command:

  1. Queries the GitHub Releases API for the latest tag.
  2. Downloads meshguard-linux-amd64 from that release.
  3. Stops the meshguard systemd service.
  4. Installs the new binary to /usr/local/bin/meshguard.
  5. Restarts the meshguard systemd service.