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: After running shurli relay authorize or shurli relay deauthorize, restart the relay to apply changes: sudo systemctl restart shurli-relay

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

Troubleshooting

Next step: Monitoring - set up Prometheus and Grafana to see everything your relay is doing in real time.