.TH NETSHAPER 8 "19 May 2026" "iproute2" "Linux"
.SH NAME
netshaper \- show / manipulate network device hardware shaping configuration
.SH SYNOPSIS

.ad l
.in +8
.ti -8
.B netshaper
.RI "[ " OPTIONS " ] { " COMMAND " | "
.BR help " }"
.sp

.ti -8
.IR OPTIONS " := { "
\fB\-V\fR[\fIersion\fR] |
\fB\-c\fR[\fIolor\fR] |
\fB\-help\fR }

.ti -8
.B "netshaper set"
.B dev
.I DEV
.B handle scope
.I HANDLE_SCOPE
.RB "[ " id
.IR HANDLE_ID " ]"
.RB "[ " bw-min
.IR BW_MIN " ]"
.RB "[ " bw-max
.IR BW_MAX " ]"
.RB "[ " weight
.IR WEIGHT " ]"

.ti -8
.B "netshaper" " { " show " | " delete " }"
.B dev
.I DEV
.B handle scope
.I HANDLE_SCOPE
.RB "[ " id
.IR HANDLE_ID " ]"

.ti -8
.B "netshaper group"
.B dev
.I DEV
.B handle scope
.RB "{ " node " | " netdev " }"
.RB "[ " id
.IR HANDLE_ID " ]"
.RB "[ " "parent scope" " { " "netdev" " [ " id
.IR PARENT_ID " ] | "
.BR node " " id
.IR PARENT_ID " } ]"
.RB "[ " bw-min
.IR BW_MIN " ]"
.RB "[ " bw-max
.IR BW_MAX " ]"
.RB "[ " weight
.IR WEIGHT " ]"
.B leaves
.IR LEAF_SPEC " [ " LEAF_SPEC " ... ]"
.sp
.in +4
.IR LEAF_SPEC " := "
.B "scope queue id"
.I ID
.RB "[ " weight
.IR WEIGHT " ]"
.RB "[ " priority
.IR PRIO " ]"
.in -4

.SH DESCRIPTION
.B netshaper
allows configuration and management of hardware rate limiting (shaping) capabilities
available on network devices. The API provides control over shapers at different levels
including network devices, queues, and scheduling nodes, enabling manipulation of the
device's scheduling tree.

Each shaper is uniquely identified within a device by a
.IR handle ,
which consists of a
.I scope
and an optional
.IR id .
Depending on the scope value, shapers are attached to specific hardware objects:

.TP
.B netdev
Shapers attached to the entire network device. The
.I id
parameter is optional for this scope (defaults to 0 if not specified).

.TP
.B queue
Shapers attached to specific device queues. The
.I id
parameter is required and specifies the queue number.

.TP
.B node
Intermediate scheduling nodes that can be placed at arbitrary
locations in the scheduling tree. The
.I id
parameter is required for
.BR set ", " show ", and " delete
commands. For the
.B group
command it is optional; if omitted, the kernel auto-assigns one.

.SH COMMANDS

.SS
.B netshaper set
- Create or update a shaper configuration

Creates or updates a shaper with the specified parameters. At least one of
.BR bw-min ", " bw-max ", or " weight
must be provided. The
.I id
parameter is required for queue and node scopes and optional for netdev scope.

.SS
.B netshaper show
- Display shaper information

Shows the current configuration of the specified shaper, including bandwidth
limits, weight, and parent information.

.SS
.B netshaper delete
- Remove a shaper configuration

Removes the specified shaper configuration from the device.

.SS
.B netshaper group
- Create a scheduling hierarchy

Creates a scheduling group by binding one or more queue leaf shapers to a
netdev or node handle in a single operation. The command specifies the
target handle, its parent, optional bandwidth and weight parameters, and
the set of queue leaves to attach.

.SH PARAMETERS

.TP
.BI dev " DEV"
Specifies the network device name on which to operate.

.TP
.B handle
Defines the shaper handle consisting of:

.RS
.TP
.BI scope " HANDLE_SCOPE"
The shaper scope, which can be:
.BR netdev " (device-level shaper), "
.BR queue " (queue-level shaper), "
or
.BR node " (scheduling node shaper)."

.TP
.BI id " HANDLE_ID"
Numeric identifier for the shaper. Required for
.B queue
and
.B node
scopes. Optional for
.B netdev
scope (defaults to 0). For the
.B group
command, node
.I id
may be omitted to let the kernel auto-assign one.
.RE

.TP
.BI bw-min " BW_MIN"
Minimum guaranteed bandwidth for the shaper. Accepts values with suffixes:
.BR kbit ", " mbit ", " gbit
for kilobits, megabits, and gigabits per second respectively.

.TP
.BI bw-max " BW_MAX"
Maximum bandwidth limit for the shaper. Accepts the same suffixes as
.BR bw-min .

.TP
.BI weight " WEIGHT"
Scheduling weight for the shaper, used for weighted fair sharing among
siblings under the same parent node. Value is an unsigned integer.

.TP
.B parent
Defines the parent for the
.B group
command. The parent scope must be
.B node
or
.BR netdev ;
.B queue
is not valid as a parent scope.
For parent scope
.BR node ,
.I id
is required. For parent scope
.BR netdev ,
.I id
is optional.
When omitted, the parent is inherited from the leaves' current
parent, which requires all leaves to share the same parent.

.TP
.B leaves
Specifies one or more leaf shapers to attach to the group. Each leaf
must use scope
.BR queue ;
no other scope is accepted for leaves.
Each leaf is given as
.BI "scope queue id " ID\fR,
with optional
.B weight
and
.B priority
parameters for per-queue scheduling within the group.
Multiple leaves can be specified in sequence.

.SH OPTIONS

.TP
.BR \-V ", " \-Version
Print the version of the
.B netshaper
utility and exit.

.TP
.BR \-c [ color "] = {" always " | " auto " | " never }
Configure color output. If the parameter is omitted or
.BR always ,
color output is enabled regardless of stdout state. If the parameter is
.BR auto ,
stdout is checked to be a terminal before enabling color output. If the parameter is
.BR never ,
color output is disabled. If specified multiple times, the last one takes
precedence.

.TP
.B \-help
Display usage information and exit.

.SH EXAMPLES

.TP
.B Example 1: Create a device-level shaper
.nf
# netshaper set dev foo handle scope netdev bw-max 10gbit
.fi
.RS
Creates a netdev-scoped shaper with maximum bandwidth of 10 Gbit/s.
.RE

.TP
.B Example 2: Set bandwidth and weight on a queue shaper
.nf
# netshaper set dev foo handle scope queue id 0 \e
    bw-min 1gbit bw-max 5gbit weight 10
.fi
.RS
Creates a queue-scoped shaper on queue 0 with minimum/maximum bandwidth
limits and a scheduling weight.
.RE

.TP
.B Example 3: Show shaper configuration
.nf
# netshaper show dev foo handle scope netdev
.fi
.RS
Displays the current shaper configuration for the specified device and handle.
.RE

.TP
.B Example 4: Create a scheduling hierarchy with group
.nf
# netshaper group dev foo handle scope node \e
    parent scope netdev bw-max 10gbit \e
    leaves scope queue id 0 weight 3 \e
    scope queue id 1 weight 2
.fi
.RS
Creates a node shaper under the netdev parent, grouping queues 0 and 1
as leaves. The 10 Gbit/s cap applies to the node itself.
.RE

.TP
.B Example 5: Delete shaper configuration
.nf
# netshaper delete dev foo handle scope netdev
.fi
.RS
Removes the specified shaper configuration.
.RE

.SH NOTES
.IP \(bu
For
.B netdev
scope, the
.I id
parameter is optional and defaults to 0 if not specified.
.IP \(bu
For
.B queue
and
.B node
scopes, the
.I id
parameter is required. For the
.B group
command, node
.I id
may be omitted to let the kernel auto-assign one.
.IP \(bu
Bandwidth values support standard suffixes:
.BR kbit " (kilobits per second), "
.BR mbit " (megabits per second), "
.BR gbit " (gigabits per second)."
.IP \(bu
The
.B group
command attaches queue leaves to a netdev or node handle in a single
atomic operation.

.SH SEE ALSO
.BR ip (8),
.BR ip-link (8),
.BR tc (8)

.SH AUTHOR
Erni Sri Satya Vennela <ernis@linux.microsoft.com>
.br
Mohsin Bashir <hmohsin@meta.com>