Managing Your Network

Your relay is secured and peers are connected. This guide covers daily operations: who can do what, how to manage peers, and what to do when things go wrong.

Roles: admin vs member

Every authorized peer has a role. The first peer to join a fresh relay is automatically promoted to admin.

Auto-promotion: When the relay starts with zero admins in authorized_keys, the first peer to pair is automatically promoted to admin. After that, new peers join as members.

Viewing your peers

From the relay server

# Full peer list with roles, groups, and verification status
shurli relay list-peers

Example output:

1. [admin]  12D3KooWLqK4ab...  home-node
2. [member] 12D3KooWRtP7cd...  laptop    group=family  [UNVERIFIED]
3. [member] 12D3KooWXyZ9ef...  phone     group=family  [verified=2026-03-01]

3 authorized peers (1 admin, 2 members)

From any device

# Uses the local config to find the authorized_keys file
shurli auth list

The output shows:

• Short peer ID (first 16 characters)
• Role badge: [admin] or [member]
• Comment (the name you gave when pairing)
• Group affiliation (if set)
• Verification status: [UNVERIFIED] or [verified=DATE]

Changing roles

Promote a member to admin

shurli auth add 12D3KooWRtP7cd... --role admin

If the peer is already authorized, this updates their role without removing their other attributes.

Demote an admin to member

shurli auth add 12D3KooWRtP7cd... --role member

Caution: Don’t demote yourself unless another admin exists. A relay with zero admins can’t create invites, unseal the vault remotely, or manage peers.

Removing peers

# From a client device
shurli auth remove 12D3KooWXyZ9ef...

# From the relay server
shurli relay deauthorize 12D3KooWXyZ9ef...

What happens when you remove a peer:

1. The peer ID is deleted from authorized_keys
2. Existing connections from this peer continue until they disconnect (TCP keepalive timeout)
3. When the peer tries to reconnect, the connection gater rejects them
4. The peer needs a new invite to rejoin

Relay server note: shurli relay authorize and shurli relay deauthorize apply immediately if the relay is running (live reload via admin socket). If the relay is stopped, changes take effect on next start.

Adding peers manually

Sometimes you have a peer ID but don’t want to go through the invite flow (e.g., adding your own new device):

# On the relay server
shurli relay authorize 12D3KooWNewDevice... my-new-laptop

# On a client device
shurli auth add 12D3KooWNewDevice... --comment "my-new-laptop" --role member

Relay info

See your relay’s identity, addresses, and connection details:

shurli relay info

Example output:

Peer ID: 12D3KooWRelay...
Connection gating: enabled
Authorized peers: 3

Public addresses:
  /ip4/203.0.113.50/tcp/7777/p2p/12D3KooWRelay...
  /ip4/203.0.113.50/udp/7777/quic-v1/p2p/12D3KooWRelay...
  /ip6/2001:db8::1/tcp/7777/p2p/12D3KooWRelay...

Quick setup:
  shurli relay add 203.0.113.50:7777 --peer-id 12D3KooWRelay...

If qrencode is installed, it also displays a QR code for easy mobile setup.

Validating your auth file

Check for syntax errors or malformed peer IDs:

shurli auth validate

Or validate a specific file:

shurli auth validate /etc/shurli/relay_authorized_keys

Output shows the count of valid peer IDs and any errors with line numbers.

Configuration reference

Key configuration fields for network management:

relay-server.yaml (relay side)

shurli.yaml (client side)

Common operations quick reference

Per-peer attributes

Control individual peer behavior with shurli auth set-attr:

# Limit a peer to 1GB per hour
shurli auth set-attr 12D3KooW... bandwidth_budget 1GB

# Remove the limit (use global default)
shurli auth set-attr 12D3KooW... bandwidth_budget ""

The bandwidth budget priority chain: LAN peers (always exempt) > per-peer attribute > config file bandwidth_budget > default (100MB/hr). Config accepts human-readable values like "500MB" or "unlimited".

Remote relay management

All relay admin commands support --remote for management over encrypted P2P:

# Manage vault remotely
shurli relay vault unseal --remote my-relay
shurli relay seal-status --remote my-relay

# Manage peers remotely
shurli relay list-peers --remote my-relay
shurli relay authorize 12D3KooW... home-node --remote my-relay
shurli relay deauthorize 12D3KooW... --remote my-relay

# Manage invites remotely
shurli relay invite list --remote my-relay
shurli relay invite create --caveat "role=member" --remote my-relay

# MOTD and goodbye
shurli relay motd set "Planned maintenance Saturday" --remote my-relay
shurli relay goodbye set "Migrating to new relay" --remote my-relay

Only admin-role peers can use remote management. The connection uses the /shurli/relay-admin/1.0.0 protocol over the same encrypted P2P tunnel as regular traffic.

Operator announcements

MOTD (message of the day)

Set a short message shown to peers when they connect:

shurli relay motd set "Maintenance window: Saturday 2am-4am UTC"
shurli relay motd status    # Show current MOTD and goodbye
shurli relay motd clear     # Remove MOTD

Goodbye (relay decommission)

Notify all peers that the relay is shutting down:

# Set goodbye (pushed to all connected peers immediately)
shurli relay goodbye set "This relay shutting down March 15. Please migrate."

# Changed your mind? Retract it
shurli relay goodbye retract

# Send goodbye and shut down the relay
shurli relay goodbye shutdown "Relay decommissioned."

Goodbyes are persistent: clients cache them and display on reconnect attempts. All messages are signed by the relay’s Ed25519 key and verified by clients.

Security note: MOTD and goodbye messages are sanitized before display. URLs, email addresses, and non-ASCII characters are stripped. This is defense-in-depth against phishing: a compromised relay cannot use announcements to redirect users to malicious sites.

Troubleshooting

Next step: ZKP Privacy Setup - enable zero-knowledge proof authentication so peers can prove authorization without revealing their identity.