SSH server and packet capture
Next to the web interface, the Antimony server runs its own SSH server. It does two things:
- Shells. Connect to any node of a running lab from your own terminal, without knowing the node’s address or setting up keys on it.
- Packet capture. Stream the traffic of any node interface to your machine as a pcap stream. Pipe it into Wireshark to watch the lab live, or into a file to analyse later.
You don’t connect to the node itself. You connect to Antimony and tell it which node you want through the SSH username. Antimony then finds the node, whether it runs on the local Docker host or in a Kubernetes cluster.
Connecting
Section titled “Connecting”The server listens on ssh.sshHost and ssh.sshPort from the configuration. If your config doesn’t set a port, the server uses 6969. In the examples on this page, antimony stands for the host name of your Antimony server.
Choosing a node
Section titled “Choosing a node”The SSH username tells Antimony which node to use. It isn’t an account: there is no password, and your local user name plays no role. Antimony splits the username at / and accepts these forms:
| Username | Where to find the parts |
|---|---|
<collection-name>/<lab-name>/<node-name> |
The default. The collection and lab names as shown in the dashboard, and the node name from the topology. The copy buttons in the interface use this form. |
<lab-id>/<node-name> |
The lab’s UUID, shown in the lab info panel. |
<instance-name>/<node-name> |
The lab’s instance name, shown in the lab info panel. It’s the topology name in lower case, with every run of characters other than letters, digits and - replaced by a single -, plus a 12-character suffix. It isn’t the lab’s display name. |
<container-id> |
The node’s container ID, shown in the node panel. On containerlab, this is Docker’s 12-character short ID; the full 64-character ID doesn’t match. On clabernetes, it’s the pod UID. |
- With two parts, a UUID as first part is read as a lab ID, anything else as an instance name.
- Names must match exactly, including upper and lower case.
- Spaces are fine, but the username then has to be quoted. Pass it with
-l "…". - Without a username (
ssh antimony), your SSH client sends your local user name, which Antimony reads as a container ID and doesn’t find. - Four or more parts are rejected with
invalid node.
The lab must be running.
Opening a shell
Section titled “Opening a shell”Connect without a command to get an interactive shell on the node:
ssh -p 6969 <collection-name>/<lab-name>/<node-name>@antimony
# Names with spacesssh -p 6969 -l "<collection-name>/<lab-name>/<node-name>" antimonyAntimony opens the shell the same way as the browser terminal: it first logs in to the node over SSH on port 22, using the username and password from kinds.conf.yml. If that fails, for example on a plain Linux container without an SSH daemon, it falls back to bash or sh inside the container.
The shell needs a terminal. OpenSSH requests one by itself when you run it from a terminal; only when its standard input isn’t one, for example in a script, force it with -tt.
Terminal resizes are passed through. When you exit the node’s shell, the SSH session ends.
Capturing traffic
Section titled “Capturing traffic”Connect with a command to capture traffic. The command names the interface:
# Watch live in Wiresharkssh -p 6969 <collection-name>/<lab-name>/<node-name>@antimony eth1 | wireshark -k -i -
# Read with tcpdumpssh -p 6969 <collection-name>/<lab-name>/<node-name>@antimony eth1 | tcpdump -n -r -
# Save to a filessh -p 6969 <collection-name>/<lab-name>/<node-name>@antimony eth1 > capture.pcapYou don’t have to type these. In the lab view, every interface of a node has a Copy capture command button, and the node’s right-click menu has Copy SSH command and Copy capture for <interface>. They copy commands with the default username, passed with -l and quoted if a name contains spaces:
ssh -p 6969 -l <collection-name>/<lab-name>/<node-name> antimony -- eth1 | wireshark -k -i -The host is the one you opened Antimony with, and -p is left out when the server uses port 22.
Accepted commands
Section titled “Accepted commands”The command is either just the interface name, or a tcpdump command line. This means tools that run tcpdump remotely also work, such as Wireshark’s built-in SSH remote capture (sshdump), whose default command is sudo tcpdump -U -i <interface> -w -. In its settings, enter your Antimony server and SSH port, put <collection-name>/<lab-name>/<node-name> in the username field and leave the password empty.
| Command | Result |
|---|---|
eth1 |
Captures eth1 |
tcpdump -i eth1 -w - |
Captures eth1 |
sudo tcpdump -U -i eth1 -w - |
Captures eth1. A leading sudo is ignored. |
tcpdump -nUi eth1 or tcpdump --interface=eth1 |
Captures eth1 |
tcpdump -i eth1 port 179 |
Captures all traffic on eth1. Filters are ignored. |
ls |
Fails: Antimony tries to capture an interface called ls. |
Only the interface option is read; every other tcpdump option and any filter expression is ignored. To filter, apply a display filter in Wireshark, or pipe the stream through tcpdump -r - <filter> locally.
What you receive
Section titled “What you receive”- A standard pcap stream (Ethernet link type, snapshot length 65 536 bytes), starting with a pcap file header. Any tool that reads pcap from standard input works.
- Shared captures. If several people watch the same interface, Antimony captures it only once and sends a copy to everyone. The capture stops when the last viewer disconnects.
- No back-pressure. Each viewer has a buffer of 1 024 packets. If your connection can’t keep up, packets are dropped for you instead of slowing down the capture for others.
- Long-running. The capture continues until you disconnect, the node stops or the server shuts down. Antimony checks every 10 seconds whether your session is still alive, so
ssh -nand other sessions without input keep running.
How it works per provider
Section titled “How it works per provider”Antimony opens a raw packet socket (AF_PACKET) inside the node container’s network namespace. This is why the Antimony server needs to run on the same host as the containers, with host PID visibility and elevated privileges (the privileged and pid: host settings in the Docker deployment).
Antimony runs the packet capture tool of the pod’s clabwire sidecar through the Kubernetes API. Only the node’s lab link interfaces can be captured. The sidecar limits single captures to one hour; Antimony chains them so your stream keeps going. See traffic capture on clabernetes.
Excluded interfaces
Section titled “Excluded interfaces”capture.excludedInterfaces lists interface names that Antimony hides from the interface list and statistics in the UI, such as lo, management interfaces and the clabernetes underlay c9s0. Entries are glob patterns (mgmt0*).
Host key
Section titled “Host key”On its first start, the server generates an Ed25519 host key at ssh.sshKeyPath (default ./key, which is /app/key in the Docker image). If you don’t keep that file, a new container generates a new key and SSH clients warn that the host key changed.
Keep the key across restarts and upgrades by storing it on a volume.
Mounting a directory is the easiest way to do this. Point ssh.sshKeyPath at a file inside it and the server creates the key there on the first start:
ssh: sshKeyPath: ./ssh/host_keyservices: server: volumes: - ./mnt/ssh:/app/sshEnabling and disabling
Section titled “Enabling and disabling”ssh.enabled: falsestops the SSH server from starting. Shells from your own client and packet capture are then unavailable, and the copy buttons for SSH and capture commands are turned off or left out. Browser terminals don’t need the SSH server and keep working.capture.enabled: falsekeeps the SSH server running for shells, but rejects every capture command withtraffic capture is not enabled. The node’s right-click menu then leaves out its Copy capture for <interface> entries, and the Copy capture command buttons are turned off.
Errors
Section titled “Errors”The server writes errors to standard error and exits with code 2 for usage errors or 1 for other failures.
| Message | Meaning |
|---|---|
traffic capture is not enabled |
You sent a command, but capture.enabled is false. |
invalid node "…", expected … |
The username has four or more parts. Use one of the usernames. |
unable to connect to node: the specified lab has not been found |
No lab matches the collection and lab names or the lab ID. Check the spelling and case. |
unable to connect to node: the specified node was not found |
The lab has no node with that name, or no running node has that container ID. |
unable to connect to node: the specified lab is not running |
The lab exists but isn’t deployed, or no running lab has that instance name. |
a terminal is required for a shell, connect with ssh -t |
You asked for a shell without a terminal, for example from a script. Add -tt. |
missing interface to capture |
The command was empty. |
unexpected arguments [...], expected an interface name or a tcpdump command |
The command has several words but isn’t a tcpdump command. |
the tcpdump command has no interface (-i) |
Add -i <interface>. |
node <lab>/<node> is not running |
The node is stopped. Start it from the lab view first. |
failed to capture <interface> on <lab>/<node>: … |
The interface doesn’t exist or the provider refused the capture. On clabernetes, only link interfaces can be captured. |