Build and Test a Linux MACsec Link with ip macsec

You will create a temporary MACsec device on an existing Ethernet link, add one transmit and one receive secure association, inspect the resulting configuration, and remove the test device. The commands match iproute2 6.1.0-1ubuntu6.4 installed on this machine.

Allow about twenty minutes if the parent interface and peer values are ready. You need iproute2, an Ethernet interface you can take responsibility for, and root privileges for the state-changing commands. Use a maintenance window: adding or removing a device can disrupt traffic, and the test keys below are examples only. Do not use them for production traffic.

1. Check the installed syntax

Start with read-only checks. These do not need elevated privileges unless your host restricts access to network information:

$ ip -V
ip utility, iproute2-6.1.0, libbpf 1.3.0
$ dpkg-query -W -f='${Package} ${Version}\n' iproute2
iproute2 6.1.0-1ubuntu6.4
$ ip macsec help
Usage: ip macsec add DEV tx sa { 0..3 } [ OPTS ] key ID KEY
...

The help output is the quickest way to catch a syntax difference on another release. The installed command accepts 128-bit or 256-bit keys, secure association numbers from 0 to 3, packet numbers with pn, and extended packet numbers with xpn.

Checkpoint: identify the parent link and make sure it is the interface you intend to use:

$ ip -br link
$ PARENT='eth0'
$ ip link show dev "$PARENT"

Replace eth0 with the real parent interface. Do not guess from a tutorial: a wrong parent can put the test on the wrong network.

2. Create the MACsec device

Choose a local device name and a port number. The port is part of the secure channel identifier, so it must match the peer's design. This example enables encryption and leaves offload disabled, which is the documented default:

$ DEV='macsec-test0'
$ sudo ip link add link "$PARENT" name "$DEV" type macsec port 11 encrypt on
$ ip link show dev "$DEV"
42: macsec-test0@eth0: <BROADCAST,MULTICAST> mtu 1500 ...

The interface number and flags vary. The useful result is that a device named macsec-test0 exists and references the intended parent. Creating the device changes kernel network state, so stop here if the parent or name is wrong.

If the command fails with an existing-device error, choose another name or inspect the current device. Do not delete an existing interface merely to make this example fit.

3. Add a transmit secure association

A secure association needs an association number, a packet number, a key identifier and a key. Use the following values only for a disposable lab test:

$ TX_SA_ID='01'
$ TX_KEY='81818181818181818181818181818181'
$ sudo ip macsec add "$DEV" tx sa 0 pn 1 on key "$TX_SA_ID" "$TX_KEY"
$ sudo ip macsec show dev "$DEV"
Device macsec-test0
    tx
        0: PN 1, state on, key 01

Output formatting differs between releases and may not display secret material. The command should show a transmit association numbered 0, with packet number 1 and state on. Never log real keys in a shell history, ticket or shared terminal. A production key must come from your key-management process, not from a copied example.

The packet number is not a harmless counter you can reset while reusing a key. MACsec uses the packet number when deriving its IV. Reusing a key with the same IV can break the security guarantee, so do not treat static command-line keys as a permanent deployment.

4. Add a receive channel and association

A receive secure channel identifies the peer by port and MAC address. Replace the address with the peer's real source address. The example address is the value used by the local manual page and is not a discovery mechanism:

$ PEER_PORT='11'
$ PEER_MAC='c6:19:52:8f:e6:a0'
$ sudo ip macsec add "$DEV" rx port "$PEER_PORT" address "$PEER_MAC"
$ sudo ip macsec add "$DEV" rx port "$PEER_PORT" address "$PEER_MAC" sa 0 pn 1 on key 00 "$TX_KEY"
$ sudo ip macsec show dev "$DEV"
Device macsec-test0
    rx port 11 address c6:19:52:8f:e6:a0
        0: PN 1, state on, key 00

In a real two-host setup, the receive key and key identifier must be coordinated with the peer's transmit configuration. The receive association is separate from the transmit association even when both use the same test key here. If the peer address, port or key is wrong, the configuration may still be accepted locally but traffic will not authenticate.

5. Inspect without changing state

Use the device-specific form while troubleshooting:

$ sudo ip macsec show dev "$DEV"
$ ip -d link show dev "$DEV"
$ ip -s link show dev "$DEV"

ip macsec show lists all MACsec devices, while show dev narrows the output. The detailed link view helps confirm the parent and device attributes; statistics help show whether packets are moving. Exact counters and formatting depend on traffic and kernel support.

Do not infer successful encryption from the device existing. A working test also needs a correctly configured peer, matching association details and traffic that exercises the link. The manual describes these commands as useful for debugging and testing, and points to 802.1X-2010 with wpa_supplicant for standard key management.

6. Remove the test configuration

Warning: deletion removes the MACsec device and its associations. It can interrupt applications using it and is not reversible through ip. Confirm the exact device name before running the command:

$ ip link show dev "$DEV"
$ sudo ip link delete dev "$DEV"
$ ip link show dev "$DEV"
Device "macsec-test0" does not exist.

Deleting the device removes its transmit and receive associations with it. If you need to preserve a test for later, leave the device in place and record the values securely instead of deleting it. If an existing production device was used by mistake, stop and follow that system's network recovery procedure rather than repeating cleanup commands against a guessed name.

Common failure points

• Permission denied: use sudo for device and association changes. Keep discovery and inspection unprivileged where they work.
• Invalid key: the key must be a 128-bit or 256-bit hexadecimal value, and the key identifier is a 128-bit hexadecimal value. Check character count without printing a real secret.
• Missing peer traffic: local configuration does not create a peer or negotiate keys. Check the peer's SCI, port, address, cipher and association values.
• Offload confusion: the device starts with offload disabled. The explicit form is sudo ip macsec offload "$DEV" off; phy and mac depend on hardware and driver support. Do not enable offload as a guess.
• Extended packet numbers: if the device is created with cipher gcm-aes-xpn-128 or gcm-aes-xpn-256, use xpn and also provide salt and ssci for the associations. Do not mix the ordinary pn form with an XPN cipher.