feat: Add `uc wg show` command to inspect a machine's uncloud wireguard network #161

jabr · 2025-11-03T06:20:43Z

Update:

Table output now looks like this:

$ ./dist/uncloud wg show
Machine Name:         himalia
WireGuard interface:  uncloud
WireGuard public key: LnH...bRho=
WireGuard port:       51820

MACHINE    PUBLIC KEY   ENDPOINT       HANDSHAKE   RECEIVED   SENT      ALLOWED IPS
amalthea   9dK...Oio=   65.xxx:51820   37s ago     275.4MB    262.7MB   fdcc:...:c8b1/128, 10.210.1.0/24
thebe      1Wg...yFI=   93.xxx:51820   1m1s ago    257.9MB    260.6MB   fdcc:...:9275/128, 10.210.0.0/24

$ ./dist/uncloud wg show --connect ssh+cli://administrator@thebe
Machine Name:         thebe
WireGuard interface:  uncloud
WireGuard public key: 1Wg...yFI=
WireGuard port:       51820

MACHINE    PUBLIC KEY   ENDPOINT       HANDSHAKE   RECEIVED   SENT      ALLOWED IPS
amalthea   9dK...Oio=   65.xxx:51820   53s ago     13.36MB    13.07MB   fdcc:...:c8b1/128, 10.210.1.0/24
himalia    LnH...Rho=   98.xxx:51820   49s ago     13.61MB    13.26MB   fdcc:...:a5f/128, 10.210.2.0/24

Also added --machine/-m option to proxy call:

$ ./dist/uncloud wg show -m thebe
Machine Name:         thebe
WireGuard interface:  uncloud
WireGuard public key: 1Wgi7SFiK0FGAVCLknXSSzxO559Tbh6GeiUQaoOYyFI=
WireGuard port:       51820

...

Note: I haven't figured out how to compile gRPC proto files cleanly so they don't result in a bunch of unrelated changes, so I did not commit those changes. It will need a make proto before it will compile. After that, it does compile, but I haven't tested the daemon. Ah, make proto-mise. 😄

Nothing urgent on this, and no need to follow up on it right away. I just wanted to push the work it had done for when me/you/someone gets back to this.

Note on approach: It only shows the wireguard info on the machine that is used to connect to the cluster. As I imagine the primary use of this would be when machines are having trouble communicating, the idea of running the command via proxy from one machine to another seemed likely pointless. But because of that, the --connect option to the command is very import, and the usability will benefit greatly from #162.

Deployed daemon to one of my machines and tested:

$ uc wg show
Showing WireGuard configuration for machine: thebe
---
interface: uncloud
  public key: 1Wgi...yFI=
  listen port: 51820

peer: 9dKc...Oio=
  endpoint: 65.xx:51820
  latest handshake: 44s ago
  transfer: 2.256GB received, 2.293GB sent
  allowed ips: fdcc:...:c8b1/128, 10.210.1.0/24

peer: LnHx...Rho=
  endpoint: 174.xx:51820
  latest handshake: 50s ago
  transfer: 1.163GB received, 1.249GB sent
  allowed ips: fdcc:...:a5f/128, 10.210.2.0/24

jabr · 2025-11-04T05:10:00Z

I've tested this one and it is working. I haven't looked at automated tests for it yet, though. Let me know if you have any thoughts on what/how would be good unit/e2e tests for it.

psviderski

As I imagine the primary use of this would be when machines are having trouble communicating, the idea of running the command via proxy from one machine to another seemed likely pointless.

I think this makes sense if you troubleshoot just the first 2 machines. But after that, when adding the 3rd machine and having issues, I think being able to see network status from both machines with uc wg show -m <name> will be useful. This becomes a common way of addressing machines in multiple commands. Having both options (-m/--machine and --connect) would be ideal.

Overall, I think a more higher level API like GetWireGuardNetwork (not just the wg device) that returns the data from WireGuardNetwork

uncloud/internal/machine/network/wireguard_linux.go

Lines 24 to 34 in b39585d

    
           type WireGuardNetwork struct { 
        
           	link netlink.Link 
        
           	// peers is a map of peers indexed by their public key. 
        
           	peers map[string]*peer 
        
           	// watchers is a list of channels that are notified when the endpoints of the peers change. 
        
           	watchers []chan EndpointChangeEvent 
        
           	// running indicates whether the network control loop (Run) is currently running. 
        
           	running bool 
        
           	// mu synchronises concurrent network configuration changes. 
        
           	mu sync.Mutex 
        
           }

with peer statuses and subnets will provide more user-friendly data helpful for troubleshooting. But we can do this in the next iterations.

Please see one comment about the table output below.

psviderski · 2025-11-06T06:35:22Z

cmd/uncloud/wg/wg.go

+			fmt.Printf("  listen port: %d\n", resp.ListenPort)
+			fmt.Println()
+
+			for _, peer := range resp.Peers {


What do you think about printing the peers using the table format to be consistent with other commands?

For reference, here are status commands from Talos:

$ talosctl get KubeSpanPeerStatuses -n 192.168.40.86 NODE NAMESPACE TYPE ID VERSION LABEL ENDPOINT STATE RX TX 192.168.40.86 kubespan KubeSpanPeerStatus 7UjNwRpSgyavO0u8kHH3QmAAzlMxALSfJ80m6Yq5RD4= 112407 talos-w1-hl 192.168.40.195:51820 up 4159176728 15656286512 192.168.40.86 kubespan KubeSpanPeerStatus 92/g5xDo6Tj6VbuqtM4+f6g8L3ClWBS5Uo/zmUA8Z0k= 112366 talos-cp1 192.168.40.140:51820 up 94067626756 98541961672 192.168.40.86 kubespan KubeSpanPeerStatus 9R3ZzBgn04jbdqvr1UOs6jZo/9QC4DUsxaCnPCKbmwU= 112407 talos-w2-rpi 192.168.40.186:51820 up 11813561276 29340364276 $ talosctl get KubeSpanPeerStatuses -n 192.168.40.186 NODE NAMESPACE TYPE ID VERSION LABEL ENDPOINT STATE RX TX 192.168.40.186 kubespan KubeSpanPeerStatus 7UjNwRpSgyavO0u8kHH3QmAAzlMxALSfJ80m6Yq5RD4= 112407 talos-w1-hl 192.168.40.195:51820 up 493982656 465667280 192.168.40.186 kubespan KubeSpanPeerStatus 92/g5xDo6Tj6VbuqtM4+f6g8L3ClWBS5Uo/zmUA8Z0k= 112367 talos-cp1 192.168.40.140:51820 up 513380728 580264784 192.168.40.186 kubespan KubeSpanPeerStatus zqD3p+WQiB7xl5sUmUAkKvwQsQIZ6Z9m+T0qC9UoBAI= 112407 talos-cp1-hl 192.168.40.86:51820 up 29340654816 11813636672

It will also be helpful to output the machine names where possible so that a user doesn't need to map public keys to machines on their own.

Yeah, changing the layout to match uncloud conventions is a good idea.

It was just mirroring what WireGuard's own wg show does currently, as my first "design spec" for this was just "do what wg does but without me having to ssh to the machine and install that tool first". 😆

It will also be helpful to output the machine names where possible so that a user doesn't need to map public keys to machines on their own.

I was going to do that initially, but it wasn't immediately obvious where to get the mapping easily and also not certain how well it would work the in "WireGuard having issue" partitioned network state. I can take a closer look at it, though.

A bit of a tangent, perhaps, but have you thought at all about a client local cache of machine name to id (and perhaps the wg public key) mappings? (Maybe even just a periodic client-local snapshot in ~/.config/uncloud/ of some subset of the corrosion store.db?)

The "named connection" idea was another place that could come up, and it seems like it would be more broadly useful, but not sure how general the "name -> machine id without having to call the server" problem really will be...

it wasn't immediately obvious where to get the mapping easily and also not certain how well it would work the in "WireGuard having issue" partitioned network state.

I think we can make the peers field and peer struct public to be able to access its fields. This is the uncloud's view of the network we want to see (e.g. what endpoints are probed and rotated and what the status of the currently chosen one). Nothing really changes in the event of partitioning. As long as we're able to connect to the machine, we should be able to show this info.

have you thought at all about a client local cache of machine name to id (and perhaps the wg public key) mappings? (Maybe even just a periodic client-local snapshot in ~/.config/uncloud/ of some subset of the corrosion store.db?)

We discussed this a bit with @tonyo. This is his comment on storing machine metadata in config.yaml:

You mean updating metadata in the config file, right?
It’ll be problematic to get this right (or at least to use it as an authoritative source) because we don’t prohibit having two (or more) client/control machines.

What we could try is: when using uc CLI, in the background compare the enabled connections in the config file with the “cluster state”, and output a warning “Your configuration is out of date” when it detects changes such as out-of-date machine name attached to the connection.

I was hesitant to do anything fancy in the config because all this becomes best effort once you have more than one user/client for the cluster. The config is not the source of truth. Correctly handling the possible discrepancies seems like the effort that doesn't worth it to me.

What do you think having the local cache help you achieve?

What do you think having the local cache help you achieve?

Just cross-over between this command and the "named connections" discussion.

When I was using wg on the machines to debug my issues I needed to connect from "both" sides of the issue to look at the WireGuard states, and so I was thinking about how that experience would translate into using this uc wg command.

I needed to know more about the machines than the client currently does: basically how machine names 1) map to an ssh connection to connect, and then 2) their machine ID and WireGuard public keys to make sense of the data.

So the "named connections" and "client cache of metadata" are both rooted in thinking about how to make the client "smarter" for commands like this.

But I think for both, there's not yet an obvious answer on how best to do it, so I'm in favor of setting them aside in favor of a more incremental approach.

I've updated this to use a tabwriter table format for output.

It also looks up the corresponding machine name for wg peer public keys.

jabr · 2025-12-13T08:18:06Z

Added --machine option to proxy call to fetch wireguard device info from other machines than the connection.

psviderski · 2025-12-29T09:51:08Z

@jabr I'm sorry for the delay with responding to this PR. Can you please rebase it on top of the main and regenerate the proto. Then we can merge it.

…rd network (draft / work in progress)

jabr · 2026-01-05T03:02:43Z

@psviderski Sorry for the delay. I was out of town on holiday for a bit.

Can you please rebase it on top of the main and regenerate the proto.

Rebased with regenerated protos (from make proto-mise).

psviderski · 2026-01-10T05:49:27Z

Thanks, merging now! 👍

jabr changed the title ~~feat: Add uc wg show command to inspect a machine's uncloud wireguard network (draft)~~ feat: Add uc wg show command to inspect a machine's uncloud wireguard network Nov 4, 2025

psviderski reviewed Nov 6, 2025

View reviewed changes

jabr changed the title ~~feat: Add uc wg show command to inspect a machine's uncloud wireguard network~~ feat: [draft] Add uc wg show command to inspect a machine's uncloud wireguard network Nov 9, 2025

jabr force-pushed the inspect-wg branch from 97d87c7 to fbd4777 Compare December 2, 2025 06:52

jabr changed the title ~~feat: [draft] Add uc wg show command to inspect a machine's uncloud wireguard network~~ feat: Add uc wg show command to inspect a machine's uncloud wireguard network Dec 2, 2025

jabr force-pushed the inspect-wg branch from fbd4777 to 7804fe3 Compare December 13, 2025 08:16

jabr added 7 commits January 4, 2026 18:57

feat: Add uc wg show command to inspect a machine's uncloud wiregua…

9771cb0

…rd network (draft / work in progress)

Compile proto files with make proto-mise

7fb8129

Fix lint errors

a427fe7

Output peers in tabwriter table

1c90451

Lookup machine name for wireguard peer public key

7667c89

Add --machine flag to uc wg show to proxy call to specific machine

e58f6e4

Small refactor to move wg show logic out into a separate function

28dd6c5

jabr force-pushed the inspect-wg branch from 7804fe3 to 28dd6c5 Compare January 5, 2026 02:59

psviderski merged commit a945291 into psviderski:main Jan 10, 2026
3 of 4 checks passed

	type WireGuardNetwork struct {
	link netlink.Link
	// peers is a map of peers indexed by their public key.
	peers map[string]*peer
	// watchers is a list of channels that are notified when the endpoints of the peers change.
	watchers []chan EndpointChangeEvent
	// running indicates whether the network control loop (Run) is currently running.
	running bool
	// mu synchronises concurrent network configuration changes.
	mu sync.Mutex
	}

Uh oh!

feat: Add uc wg show command to inspect a machine's uncloud wireguard network #161

feat: Add uc wg show command to inspect a machine's uncloud wireguard network #161

Uh oh!

Conversation

jabr commented Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jabr commented Nov 4, 2025

Uh oh!

psviderski left a comment

Choose a reason for hiding this comment

Uh oh!

psviderski Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

jabr Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

psviderski Nov 9, 2025

Choose a reason for hiding this comment

Uh oh!

jabr Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

jabr Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

jabr commented Dec 13, 2025

Uh oh!

psviderski commented Dec 29, 2025

Uh oh!

jabr commented Jan 5, 2026

Uh oh!

psviderski commented Jan 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat: Add `uc wg show` command to inspect a machine's uncloud wireguard network #161

feat: Add `uc wg show` command to inspect a machine's uncloud wireguard network #161

jabr commented Nov 3, 2025 •

edited

Loading

jabr Nov 6, 2025 •

edited

Loading