Skip to main content
Display the WireGuard network configuration and peer information for a machine in the cluster.

​
Usage

uc wg show [OPTIONS]

​
Options

​
--machine, -m
string
Name or ID of the machine to show configuration for. If not specified, shows configuration for the currently connected machine

​
Description

The wg show command displays detailed WireGuard network information for a machine, including:
  • Interface configuration (public key, listen port, addresses)
  • Connected peers (other machines in the cluster)
  • Peer connection details (endpoints, allowed IPs, handshake times, data transfer)
This command is useful for:
  • Debugging network connectivity issues
  • Verifying WireGuard tunnel status
  • Monitoring data transfer between machines
  • Checking peer handshake times
This command shows low-level WireGuard details. For general cluster status, use uc machine ls instead.

​
Examples

​
Show WireGuard config for current machine

uc wg show
Output: 
interface: uncloud0
  public key: ABC123xyz789...
  private key: (hidden)
  listening port: 51820
  addresses: 10.210.0.1/24, fd00:uncloud::1/64

peer: DEF456uvw012...
  endpoint: 5.223.45.199:51820
  allowed ips: 10.210.1.0/24, fd00:uncloud:1::/64
  latest handshake: 45 seconds ago
  transfer: 12.5 MiB received, 8.3 MiB sent
  persistent keepalive: every 25 seconds

peer: GHI789rst345...
  endpoint: 203.0.113.42:51820
  allowed ips: 10.210.2.0/24, fd00:uncloud:2::/64
  latest handshake: 2 minutes ago
  transfer: 856 KiB received, 1.2 MiB sent
  persistent keepalive: every 25 seconds

​
Check specific machine

View WireGuard status on a specific machine: 
uc wg show --machine hetzner-server

​
Monitor peer connectivity

Check when peers last communicated: 
uc wg show | grep "latest handshake"
Output: 
  latest handshake: 45 seconds ago
  latest handshake: 2 minutes ago
  latest handshake: 15 seconds ago
Handshakes should occur at least every 2-3 minutes. If a peer shows “never” or a very old timestamp, there may be a connectivity issue.

​
Check data transfer

See how much data has been transferred between machines: 
uc wg show | grep "transfer"
Output: 
  transfer: 12.5 MiB received, 8.3 MiB sent
  transfer: 856 KiB received, 1.2 MiB sent
  transfer: 2.1 GiB received, 1.8 GiB sent

​
Output Fields

​
Interface Section

  • public key: Machine’s WireGuard public key (used by peers to connect)
  • private key: Hidden for security
  • listening port: UDP port for incoming WireGuard connections (default: 51820)
  • addresses: IP addresses assigned to the WireGuard interface

​
Peer Sections (one per connected machine)

  • public key: Peer’s WireGuard public key
  • endpoint: Peer’s public IP:port where it’s reachable
  • allowed ips: Subnets routed through this peer
  • latest handshake: Time since last WireGuard handshake (connection check)
  • transfer: Data sent/received through this tunnel
  • persistent keepalive: Interval for NAT traversal keepalive packets

​
Troubleshooting Network Issues

​
Peer shows “never” for handshake

If a peer has never completed a handshake:
  1. Check if machines can reach each other on UDP port 51820
  2. Verify firewall rules allow UDP/51820
  3. Check if endpoints are correct with uc machine ls
  4. Test connectivity: nc -u PEER_IP 51820

​
Handshake time too old

If handshake is more than 3 minutes old:
  1. Check network connectivity between machines
  2. Verify both machines are running (uc machine ls)
  3. Check for firewall changes
  4. Look for NAT/routing issues

​
No data transfer

If transfer shows 0 bytes despite services running:
  1. Check if services are using the mesh network
  2. Verify container IP addresses with uc ps
  3. Test connectivity: uc service exec SERVICE -- ping PEER_IP
  4. Check DNS resolution: uc service exec SERVICE -- nslookup service.internal

​
Endpoint shows wrong IP

If the endpoint doesn’t match the machine’s public IP:
  1. Update machine’s public IP: uc machine update NAME --public-ip NEW_IP
  2. Check automatic IP detection
  3. Verify NAT/port forwarding configuration

​
Network Architecture

Each machine in an Uncloud cluster:
  • Has a unique subnet (e.g., 10.210.X.0/24)
  • Gets its first IP in that subnet (e.g., 10.210.X.1)
  • Connects to all other machines via WireGuard tunnels
  • Routes traffic for peer subnets through appropriate tunnels
Example for 3-machine cluster: 
Machine 1: 10.210.0.1/24 (subnet: 10.210.0.0/24)
Machine 2: 10.210.1.1/24 (subnet: 10.210.1.0/24)
Machine 3: 10.210.2.1/24 (subnet: 10.210.2.0/24)

​
Security Notes

  • Private keys are never displayed for security
  • WireGuard uses modern cryptography (ChaCha20, Poly1305, Curve25519)
  • All cluster traffic is encrypted through the mesh network
  • Peers can only access allowed IP ranges
The wg show command displays sensitive network information including public keys and endpoints. Don’t share this output publicly.

Build docs developers (and LLMs) love

Get started for freeTalk to us