Configure FOU and GUE UDP Receive Ports with ip fou

ip fou opens a UDP port that decapsulates other protocols, so a wrong flag turns into a live, unfiltered listener. This guide creates and verifies a Linux receive port for Foo-over-UDP (FOU) or Generic UDP Encapsulation (GUE), then removes the exact entry safely. The examples use the ip command from iproute2 6.1.0, installed here as package version 6.1.0-1ubuntu6.4. Allow about fifteen minutes if you already know the tunnel's protocol and addresses.

You need iproute2 and a shell. Creating or deleting a receive port changes kernel networking state, can affect tunnel traffic, and requires elevated privileges on a normal host. First test the syntax and inspect existing entries as an ordinary user. Do not run the add example on a production host until the UDP port, protocol and binding have been agreed with the sender.

1. Check the installed command

Confirm the binary and ask the installed command for its supported syntax. These are read-only checks:

$ command -v ip
/usr/sbin/ip
$ ip -V
ip utility, iproute2-6.1.0, libbpf 1.3.0
$ ip fou help
Usage: ip fou add port PORT { ipproto PROTO  | gue }
           [ local IFADDR ] [ peer IFADDR ]
           [ peer_port PORT ] [ dev IFNAME ]
       ip fou del port PORT [ local IFADDR ]
           [ peer IFADDR ] [ peer_port PORT ]
           [ dev IFNAME ]
       ip fou show

The subcommand is named fou even when you are configuring GUE. The installed help accepts a numeric protocol from 1 to 255, a UDP port from 1 to 65535, and an address or interface for a binding. The ip-gue(8) name is an alias for the same documented command, not a separate command you need to install.

Checkpoint: if ip fou help does not show the form above, stop and use the syntax reported by your installed iproute2 version. Do not copy options from a different host.

2. Inspect current receive ports

List the current FOU and GUE entries before changing anything:

$ ip fou show

An empty response means that no entries are currently displayed. If entries are present, save the relevant line or record its port, local address, peer address, peer port and device. Those details matter when you remove a restricted entry later. A port number alone may not identify the same configuration.

There is no general-purpose discovery step that can infer whether a peer expects FOU or GUE. FOU associates a receive port with one IP protocol number. GUE carries the encapsulated protocol number in its own header. Get that choice and the protocol design from the tunnel configuration before proceeding.

3. Choose the receive-port form

For FOU, select the IP protocol number that the receiver should infer. GRE is protocol 47 and IP-in-IP is protocol 4, so representative commands are:

# sudo ip fou add port 7777 ipproto 47
# sudo ip fou add port 8888 ipproto 4

For GUE, use the gue keyword instead of ipproto:

# sudo ip fou add port 9999 gue

These commands create kernel state immediately. They do not create a persistent configuration file, configure an IP address, or build a complete tunnel by themselves. A reboot or a network-management service may remove or recreate the state, depending on how your host is managed.

Checkpoint: replace the example ports with values allocated for your host. Check that the chosen UDP port is not already needed by another service, and that the encapsulated protocol matches the sender. Treat a successful command with no output as a state change, not as proof that traffic will flow.

4. Bind the port when wildcard reception is not wanted

Without a local address or device, the receive port is not restricted to one local address or interface by the command. Bind it when the host has several addresses or interfaces and the tunnel should arrive through one of them:

# sudo ip fou add port 7777 ipproto 47 local 192.0.2.10
# sudo ip fou add port 7777 ipproto 47 dev eth1

Use the address or device form that matches the deployment. Do not paste 192.0.2.10 or eth1 without checking that they exist on your host. The address is an example from the documentation range, not a promise that it is configured locally.

The command also accepts peer, peer_port and dev parameters. A connected receive port can be described with a peer address and peer port:

# sudo ip fou add port 7777 ipproto 47 local 192.0.2.10 peer 198.51.100.20 peer_port 7777

Use peer restrictions only when the sender's address and port are stable and the tunnel design calls for them. A mismatch can make otherwise valid encapsulated packets fail to match the receive configuration. Never use placeholder addresses in a live command.

5. Verify the entry and the command status

Immediately after adding an entry, display the table again:

$ ip fou show
port 7777 ipproto 47 local 192.0.2.10
$ printf 'status: %s\n' "$?"
status: 0

The exact display varies with the options used and the iproute2 release. Look for the port and the protocol or gue mode you requested, plus any local, peer or device restriction. The command's exit status is the useful automation check: status 0 means the show operation succeeded, not that a remote peer has sent traffic.

If adding an entry reports that it already exists, inspect the current table rather than adding another variation at random. If it reports an invalid address, port or protocol, correct the input. If it reports insufficient permission, rerun the state-changing command with the privilege mechanism approved for that host, normally sudo. Do not grant broad capabilities just to make a networking experiment convenient.

6. Test traffic without changing the entry

Test the complete tunnel separately from the receive-port registration. The ip fou table only confirms the registration. It does not prove that firewall rules allow the UDP port, that the peer sends to the selected address, or that an outer route exists.

Use your normal tunnel implementation and monitoring tools to send a controlled packet. Check the host firewall and packet counters according to your distribution's procedure. Keep the test narrow: use the agreed peer and a harmless payload, and avoid opening the UDP port more widely than the design requires. A successful table lookup followed by no traffic usually points to a peer, route, firewall or binding mismatch rather than a missing ip fou show command.

7. Remove the exact configuration

Removal is disruptive: matching traffic will stop using that receive registration. First capture the current entry, then delete it with the same identifying details used when it was created. For an unrestricted example:

# sudo ip fou del port 9999
$ ip fou show

For a locally bound entry, include its local address:

# sudo ip fou del port 7777 local 192.0.2.10

For an entry constrained by a peer or device, include the corresponding peer address, peer port or device as required by the current table. If deletion fails, do not broaden the command blindly. Re-run ip fou show, compare every field, and use the exact form it reports. If you need the receive port again, rerun the original add command after checking the tunnel service's recovery procedure.

There is no undo history. Keep a copy of the original add command in the change record so that restoration is deliberate and reviewable. If another service owns the entry, stop and coordinate before deleting it.

Done means