IP-NEXTHOP(8)

📦

version 7.3.0 · 3 versions

7.3.0 · arch rolling (latest)
6.1.0 · debian bookworm, ubuntu jammy, ubuntu noble
7.2.0 · alpine 3.22, alpine 3.23, alpine 3.24, arch rolling, centos-stream 10, centos-stream 9, debian trixie, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 NAME 💖

ip-nexthop — nexthop object management ✨

okay so bestie, this is IP-NEXTHOP(8), the page that lives in section 8 of the Linux manual, and it's literally all about nexthop object management. that's it, that's the name. iconic behavior, no notes 💅

🦋 SYNOPSIS 🦋

ip [ ip-OPTIONS ] nexthop  { COMMAND | help }

ip nexthop { show | flush } SELECTOR

ip nexthop { add | replace } id ID NH

ip nexthop { get | del } id ID

ip nexthop bucket list BUCKET_SELECTOR

ip nexthop bucket get id ID index INDEX

SELECTOR := [ id ID ] [ dev DEV ] [ vrf NAME ] [ master DEV ] [ groups ]
        [ fdb ]

BUCKET_SELECTOR := SELECTOR  | [ nhid ID ]

NH := { blackhole | [ via ADDRESS ] [ dev DEV ] [ onlink ] [ encap ENCAP
        ] [ fdb ] [ dst_port PORT ] | group GROUP [ hw_stats { on | off
        }  ] [ fdb ] [ type TYPE [ TYPE_ARGS ] ] }

ENCAP := [ ENCAP_MPLS ]

ENCAP_MPLS := mpls [ LABEL ] [ ttl TTL ]

GROUP := id[,weight[/...]

TYPE := { mpath | resilient }

TYPE_ARGS := [ RESILIENT_ARGS ]

RESILIENT_ARGS := [ buckets BUCKETS ] [ idle_timer IDLE ] [
        unbalanced_timer UNBALANCED ]

like… look at all those := definitions. the grammar girlies ATE 🔥

🌸 DESCRIPTION 🌸

ip nexthop is used to manipulate entries in the kernel's nexthop tables. that's the whole mission statement, bestie 🫶

`ip nexthop add id ID`

add new nexthop entry 🎀

`ip nexthop replace id ID`

change the configuration of a nexthop or add new one.

here's everything you can sprinkle into it:

via [ FAMILY ] ADDRESS — the address of the nexthop router, in the address family FAMILY. the address family must match the address family of the nexthop instance, so don't try to be cute about it 🙈
dev NAME — is the output device.
onlink — pretend that the nexthop is directly attached to this link, even if it does not match any interface prefix. fake it till you make it, lowkey 💜
encap ENCAPTYPE ENCAPHDR — attach tunnel encapsulation attributes to this route.

ENCAPTYPE is a string specifying the supported encapsulation type. Namely:

mpls — encapsulation type MPLS

ENCAPHDR is a set of encapsulation attributes specific to the ENCAPTYPE.

mpls
- MPLSLABEL — mpls label stack with labels separated by /
- ttl TTL — TTL to use for MPLS header or 0 to inherit from IP header

group GROUP [ type TYPE [ TYPE_ARGS ] ] — create a nexthop group. Group specification is id with an optional weight (id,weight) and a / as a separator between entries.

TYPE is a string specifying the nexthop group type. Namely:

mpath — Multipath nexthop group backed by the hash-threshold algorithm. The default when the type is unspecified.
resilient — Resilient nexthop group. Group is resilient to addition and deletion of nexthops.

TYPE_ARGS is a set of attributes specific to the TYPE.

resilient
- buckets BUCKETS — Number of nexthop buckets. Cannot be changed for an existing group.
- idle_timer IDLE — Time in seconds in which a nexthop bucket does not see traffic and is therefore considered idle. Default is 120 seconds.
- unbalanced_timer UNBALANCED — Time in seconds in which a nexthop group is unbalanced and is therefore considered unbalanced. The kernel will try to rebalance unbalanced groups, which might result in some flows being reset. A value of 0 means that no rebalancing will take place. Default is 0 seconds.

blackhole — create a blackhole nexthop. the void, but make it networking 💀
fdb — nexthop and nexthop groups for use with layer-2 fdb entries. A fdb nexthop group can only have fdb nexthops. Example: Used to represent a vxlan remote vtep ip. layer-2 vxlan fdb entry pointing to an ecmp nexthop group containing multiple remote vtep ips. okay that one's dense but it's giving exactly what it says 🧚
dst_port PORT — UDP destination port to use for an fdb nexthop, in place of the VXLAN device's default port. Only valid together with fdb and a gateway.

bestie note: group GROUP [ hw_stats { on | off } ] [ fdb ] [ type TYPE [ TYPE_ARGS ] ] is how it shows up in the synopsis — hw_stats takes on or off ✨

`ip nexthop delete id ID`

delete nexthop with given id. bye girl 👋

`ip nexthop show`

show the contents of the nexthop table or the nexthops selected by some criteria.

dev DEV — show the nexthops using the given device.
vrf NAME — show the nexthops using devices associated with the vrf name
master DEV — show the nexthops using devices enslaved to given master device
groups — show only nexthop groups
fdb — show only fdb nexthops and nexthop groups

`ip nexthop flush`

flushes nexthops selected by some criteria. Criteria options are the same as show. so yeah, same menu, different energy 🫧

`ip nexthop get id ID`

get a single nexthop by id. one (1) nexthop. no more, no less 🎯

`ip nexthop bucket show`

show the contents of the nexthop bucket table or the nexthop buckets selected by some criteria.

id ID — show the nexthop buckets that belong to a nexthop group with a given id
nhid ID — show the nexthop buckets that hold a nexthop with a given id
dev DEV — show the nexthop buckets using the given device
vrf NAME — show the nexthop buckets using devices associated with the vrf name
master DEV — show the nexthop buckets using devices enslaved to given master device

heads up: the synopsis says ip nexthop bucket list BUCKET_SELECTOR and this section says bucket show — that's literally what the page says, both of them, i'm just the messenger 💅

`ip nexthop bucket get id ID index INDEX`

get a single nexthop bucket by nexthop group id and bucket index.

🍓 EXAMPLES 🍓

the part you actually came for, periodt ✨

ip nexthop ls

Show all nexthop entries in the kernel.

ip nexthop add id 1 via 192.168.1.1 dev eth0

Adds an IPv4 nexthop with id 1 using the gateway 192.168.1.1 out device eth0.

ip nexthop add id 2 encap mpls 200/300 via 10.1.1.1 dev eth0

Adds an IPv4 nexthop with mpls encapsulation attributes attached to it.

ip nexthop add id 3 group 1/2

Adds a nexthop with id 3. The nexthop is a group using nexthops with ids 1 and 2 at equal weight.

ip nexthop add id 4 group 1,5/2,11

Adds a nexthop with id 4. The nexthop is a group using nexthops with ids 1 and 2 with nexthop 1 at weight 5 and nexthop 2 at weight 11.

ip nexthop add id 5 via 192.168.1.2 fdb

Adds a fdb nexthop with id 5.

ip nexthop add id 6 via 192.168.1.2 fdb dst_port 4790

Adds a fdb nexthop with id 6 forwarding to 192.168.1.2 on UDP port 4790.

ip nexthop add id 7 group 5/6 fdb

Adds a fdb nexthop group with id 7. A fdb nexthop group can only have fdb nexthops.

ip nexthop add id 10 group 1/2 type resilient buckets 32

Add a resilient nexthop group with id 10 and 32 nexthop buckets.

🌈 SEE ALSO 🌈

ip(8)

👑 AUTHOR 👑

Original Manpage by David Ahern <dsahern@kernel.org>

okay bestie that's the whole page, you're officially a nexthop girlie now 💖 this one shipped with iproute2, dated 30 May 2019 — no cap, that's the version and date right there in the footer. go forth and manipulate those kernel nexthop tables, i believe in you 🦋✨💅

📦 where this page comes from

arch rolling: iproute2 7.3.0-1 · GPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms