dcb-rewr

title: dcb-rewr(8)

summary: show / manipulate the rewrite table of

text:
# dcb-rewr(8)

## NAME
dcb-rewr - show / manipulate the rewrite table of the DCB (Data Center Bridging) subsystem

## SYNOPSIS

dcb [ OPTIONS ] rewr { COMMAND | help }

dcb rewr { show | flush } dev DEV [ prio-dscp ] [ prio-pcp ]

dcb rewr { add | del | replace } dev DEV [ prio-dscp DSCP-MAP ] [ prio-pcp PCP-MAP ]

DSCP-MAP := [ DSCP-MAP ] DSCP-MAPPING

DSCP-MAPPING := PRIO:{ DSCP | all }

PCP-MAP := [ PCP-MAP ] PCP-MAPPING

PCP-MAPPING := PRIO:PCP

DSCP := { 0 .. 63 }

PCP := { 0(nd/de) .. 7(nd/de) }

PRIO := { 0 .. 7 }

## DESCRIPTION
dcb rewr is used to configure the rewrite table, in the DCB (Data Center Bridging) subsystem. The rewrite table is used to rewrite certain values in the packet headers, based on packet priority.

DCB rewrite entries are, like DCB APP entries, 3-tuples of selector, protocol ID, and priority. Selector is an enumeration that picks one of the prioritization namespaces. Currently, only the DSCP and PCP selector namespaces are supported by dcb rewr.

The rewrite table is a list of DCB rewrite rules, that applies to packets with matching priority. Notably, it is valid to have conflicting rewrite assignment for the same selector and priority. For example, the set of two rewrite entries (DSCP, 10, 1) and (DSCP, 11, 1), where packets with priority 1 should have its DSCP value rewritten to both 10 and 11, form a well-defined rewrite table. dcb rewr tool allows low-level management of the rewrite table by adding and deleting individual rewrite 3-tuples through add and del commands. On the other hand, the command replace does what one would typically want in this situation--first adds the new configuration, and then removes the obsolete one, so that only one rewrite rule is in effect for a given selector and priority.

## COMMANDS
show

Display all entries with a given selector. When no selector is given, shows all rewrite table entries categorized per selector.

flush

Remove all entries with a given selector. When no selector is given, removes all rewrite table entries.

add

del

Add and, respectively, remove individual rewrite 3-tuples to and from the DCB rewrite table.

replace

Take the list of entries mentioned as parameter, and add those that are not present in the rewrite table yet. Then remove those entries, whose selector and priority have been mentioned as parameter, but not with the exact same protocol ID. This has the effect of, for the given selector and priority, causing that the table only contains the protocol ID (or ID's) given as parameter.

## PARAMETERS
The following table shows parameters in a way that they would be used with add, del and replace commands. For show and flush, the parameter name is to be used as a simple keyword without further arguments.

prio-dscp DSCP-MAP

DSCP-MAP uses the array parameter syntax, see dcb(8) for details. Keys are priorities, values are DSCP points for traffic with matching priority. DSCP points can be written either directly as numeric values, or using symbolic names specified in /etc/iproute2/rt_dsfield (however note that the file specifies full 8-bit dsfield values, whereas dcb rewr will only use the higher six bits). dcb rewr show will similarly format DSCP values as symbolic names if possible. The command line option -N turns the show translation off.

prio-pcp PCP-MAP

PCP-MAP uses the array parameter syntax, see dcb(8) for details. Keys are priorities. Values are PCP/DEI for traffic with matching priority. PCP/DEI values are written as a combination of numeric- and symbolic values, to accommodate for both. PCP always in numeric form e.g 0 .. 7 and DEI in symbolic form e.g 'de' (drop-eligible), indicating that the DEI bit is 1 or 'nd' (not-drop-eligible), indicating that the DEI bit is 0. In combination 1:2de translates to a mapping of priority 1 to PCP=2 and DEI=1.

## EXAMPLE & USAGE
Add a rule to rewrite DSCP to 0, 24 and 48 for traffic with priority 0, 3 and 6, respectively:

\# dcb rewr add dev eth0 prio-dscp 0:0 3:24 6:48

Add a rule to rewrite DSCP to 25 for traffic with priority 3:

\# dcb rewr add dev eth0 prio-dscp 3:25

\# dcb rewr show dev eth0 prio-dscp

prio-dscp 0:0 3:CS3 3:25 6:CS6

\# dcb -N rewr show dev eth0 prio-dscp

prio-dscp 0:0 3:24 3:25 6:48

Reconfigure the table so that only one rule exists for rewriting traffic with priority 3.

\# dcb rewr replace dev eth0 prio-dscp 3:26

\# dcb rewr -N show dev eth0 prio-dscp

prio-dscp 0:0 3:26 6:48

Flush all DSCP rules:

\# dcb rewr flush dev eth0 prio-dscp

\# dcb rewr show dev eth0 prio-dscp

(nothing)

Add a rule to rewrite PCP to 1 and DEI to 0 for traffic with priority 1 and a rule to rewrite PCP to 2 and DEI to 1 for traffic with priority 2:

\# dcb rewr add dev eth0 prio-pcp 1:1nd 2:2de

\# dcb rewr show dev eth0 prio-pcp

prio-pcp 1:1nd 2:2de

## EXIT STATUS
Exit status is 0 if command was successful or a positive integer upon failure.

## SEE ALSO
dcb(8) dcb-app(8) dcb-apptrust(8)

## REPORTING BUGS
Report any bugs to the Network Developers mailing list <netdev@vger.kernel.org> where the development and maintenance is primarily done. You do not have to be subscribed to the list to send a message there.

## AUTHOR
Daniel Machon <daniel.machon@microchip.com>


devlink

title: devlink(8)

summary: Devlink tool

text:
# devlink(8)

## NAME
devlink - Devlink tool

## SYNOPSIS

devlink [ OPTIONS ] { dev|port|monitor|sb|resource|region|health|trap } { COMMAND | help }

devlink [ -force ] -batch filename

## OPTIONS
-V, --Version

Print the version of the devlink utility and exit.

-b, -batch <FILENAME>

Read commands from provided file or standard input and invoke them. First failure will cause termination of devlink.

-force

Don't terminate devlink on errors in batch mode. If there were any errors during execution of the commands, the application return code will be non zero.

-n, --no-nice-names

Turn off printing out nice names, for example netdevice ifnames instead of devlink port identification.

-j, --json

Generate JSON output.

-p, --pretty

When combined with -j generate a pretty JSON output.

-v, --verbose

Turn on verbose output.

-s, --statistics

Output statistics.

-N, -Netns <NETNSNAME>

Switches to the specified network namespace.

-i, --iec

Print human readable rates in IEC units (e.g. 1Ki = 1024).

-x, --hex

Print dump numbers in hexadecimal format.

### OBJECT
dev

- devlink device.

port

- devlink port.

monitor

- watch for netlink messages.

sb

- devlink shared buffer configuration.

resource

- devlink device resource configuration.

region

- devlink address region access

health

- devlink reporting and recovery

trap

- devlink trap configuration

### COMMAND
Specifies the action to perform on the object. The set of possible actions depends on the object type. As a rule, it is possible to show (or list ) objects, but some objects do not allow all of these operations or have some additional commands. The help command is available for all objects. It prints out a list of available commands and argument syntax conventions.

If no command is given, some default command is assumed. Usually it is list or, if the objects of this class cannot be listed, help.

## EXIT STATUS
Exit status is 0 if command was successful or a positive integer upon failure.

## SEE ALSO
devlink-dev(8), devlink-port(8), devlink-monitor(8), devlink-sb(8), devlink-resource(8), devlink-region(8), devlink-health(8), devlink-trap(8),

## REPORTING BUGS
Report any bugs to the Network Developers mailing list <netdev@vger.kernel.org> where the development and maintenance is primarily done. You do not have to be subscribed to the list to send a message there.

## AUTHOR
Jiri Pirko <jiri@mellanox.com>


devlink-dev

title: devlink-dev(8)

summary: devlink device configuration

text:
# devlink-dev(8)

## NAME
devlink-dev - devlink device configuration

## SYNOPSIS

devlink [ OPTIONS ] dev { COMMAND | help }

OPTIONS := { -V[ersion] | -n[no-nice-names] }

devlink dev show [ DEV ]

devlink dev help

devlink dev eswitch set DEV [ mode { legacy | switchdev } ] [ inline-mode { none | link | network | transport } ] [ encap-mode { none | basic } ]

devlink dev eswitch show DEV

devlink dev param set DEV name PARAMETER value VALUE cmode { runtime | driverinit | permanent }

devlink dev param show [ DEV name PARAMETER ]

devlink dev reload DEV [ netns { PID | NAME | ID } ] [ action { driver_reinit | fw_activate } ] [ limit no_reset ]

devlink dev info [ DEV ]

devlink dev flash DEV file PATH [ target ID ]

devlink dev selftests show [ DEV ]

devlink dev selftests run DEV [ id ID... ]

## DESCRIPTION

### devlink dev show - display devlink device attributes
DEV - specifies the devlink device to show. If this argument is omitted all devices are listed.

Format is:

BUS_NAME/BUS_ADDRESS

### devlink dev eswitch set - sets devlink device eswitch attributes
mode { legacy | switchdev }

Set eswitch mode legacy - Legacy SRIOV

switchdev - SRIOV switchdev offloads

inline-mode { none | link | network | transport }

Some HWs need the VF driver to put part of the packet headers on the TX descriptor so the e-switch can do proper matching and steering. none - None

link - L2 mode

network - L3 mode

transport - L4 mode

encap-mode { none | basic }

Set eswitch encapsulation support none - Disable encapsulation support

basic - Enable encapsulation support

### devlink dev param set - set new value to devlink device configuration parameter
name PARAMETER

Specify parameter name to set.

value VALUE

New value to set.

cmode { runtime | driverinit | permanent }

Configuration mode in which the new value is set. runtime - Set new value while driver is running. This configuration mode doesn't require any reset to apply the new value.

driverinit - Set new value which will be applied during driver initialization. This configuration mode requires restart driver by devlink reload command to apply the new value.

permanent - New value is written to device's non-volatile memory. This configuration mode requires hard reset to apply the new value.

### devlink dev param show - display devlink device supported configuration parameters attributes
name PARAMETER Specify parameter name to show. If this argument is omitted all parameters supported by devlink devices are listed.

### devlink dev reload - perform hot reload of the driver.
DEV - Specifies the devlink device to reload.

netns { PID | NAME | ID } - Specifies the network namespace to reload into, either by pid, name or id.

action { driver_reinit | fw_activate } - Specifies the reload action required. If this argument is omitted driver_reinit action will be used. Note that even though user asks for a specific action, the driver implementation might require to perform another action alongside with it. For example, some driver do not support driver reinitialization being performed without fw activation. Therefore, the devlink reload command returns the list of actions which were actrually performed.

driver_reinit - Driver entities re-initialization, applying devlink-param and devlink-resource values.

fw_activate - Activates new firmware if such image is stored and pending activation. If no limitation specified this action may involve firmware reset. If no new image pending this action will reload current firmware image.

limit no_reset - Specifies limitation on reload action. If this argument is omitted limit is unspecified and the reload action is not limited. In such case driver implementation may include reset or downtime as needed to perform the actions.

no_reset - No reset allowed, no down time allowed, no link flap and no configuration is lost.

### devlink dev info - display device information.
Display device information provided by the driver. This command can be used to query versions of the hardware components or device components which can't be updated ( fixed ) as well as device firmware which can be updated. For firmware components running displays the versions of firmware currently loaded into the device, while stored reports the versions in device's flash. Running and stored versions may differ after flash has been updated, but before reboot.

DEV - specifies the devlink device to show. If this argument is omitted all devices are listed.

### devlink dev flash - write device's non-volatile memory.
DEV - specifies the devlink device to write to.

file PATH - Path to the file which will be written into device's flash. The path needs to be relative to one of the directories searched by the kernel firmware loader, such as /lib/firmware.

component NAME - If device stores multiple firmware images in non-volatile memory, this parameter may be used to indicate which firmware image should be written. The value of NAME should match the component names from devlink dev info and may be driver-dependent.

### devlink dev selftests show - shows supported selftests on devlink device.
DEV - specifies the devlink device. If this argument is omitted all selftests for devlink devices are listed.

### devlink dev selftests run - runs selftests on devlink device.
DEV - specifies the devlink device to execute selftests.

id ID... - The value of ID(s) should match the selftests shown in devlink dev selftests show to execute selftests on the devlink device. If this argument is omitted all selftests supported by devlink devices are executed.

## EXAMPLES
devlink dev show

Shows the state of all devlink devices on the system.

devlink dev show pci/0000:01:00.0

Shows the state of specified devlink device.

devlink dev eswitch show pci/0000:01:00.0

Shows the eswitch mode of specified devlink device.

devlink dev eswitch set pci/0000:01:00.0 mode switchdev

Sets the eswitch mode of specified devlink device to switchdev.

devlink dev param show pci/0000:01:00.0 name max_macs

Shows the parameter max_macs attributes.

devlink dev param set pci/0000:01:00.0 name internal_error_reset value true cmode runtime

Sets the parameter internal_error_reset of specified devlink device to true.

devlink dev reload pci/0000:01:00.0

Performs hot reload of specified devlink device.

devlink dev flash pci/0000:01:00.0 file firmware.bin

Flashes the specified devlink device with provided firmware file name. If the driver supports it, user gets updates about the flash status. For example:

Preparing to flash

Flashing 100%

Flashing done

devlink dev selftests show pci/0000:01:00.0

Shows the supported selftests by the devlink device.

devlink dev selftests run pci/0000:01:00.0 id flash

Perform a flash test on the devlink device.

## SEE ALSO
devlink(8), devlink-port(8), devlink-sb(8), devlink-monitor(8),

## AUTHOR
Jiri Pirko <jiri@mellanox.com>


devlink-dpipe

title: devlink-dpipe(8)

text:
# devlink-dpipe(8)

## NAME
devlink-dpipe - devlink dataplane pipeline visualization

## SYNOPSIS

devlink [ OPTIONS ] dpipe { table | header } { COMMAND | help }

OPTIONS := { -V[ersion] }

devlink dpipe table show DEV [ name TABLE_NAME ]

devlink dpipe table set DEV name TABLE_NAME

devlink dpipe table dump DEV name TABLE_NAME

devlink dpipe header show DEV

devlink dpipe help

## DESCRIPTION

### devlink dpipe table show - display devlink dpipe table attributes
name TABLE_NAME

Specifies the table to operate on.

### devlink dpipe table set - set devlink dpipe table attributes
name TABLE_NAME

Specifies the table to operate on.

### devlink dpipe table dump - dump devlink dpipe table entries
name TABLE_NAME

Specifies the table to operate on.

### devlink dpipe header show - display devlink dpipe header attributes
name TABLE_NAME

Specifies the table to operate on.

## EXAMPLES
devlink dpipe table show pci/0000:01:00.0

Shows all dpipe tables on specified devlink device.

devlink dpipe table show pci/0000:01:00.0 name mlxsw_erif

Shows mlxsw_erif dpipe table on specified devlink device.

devlink dpipe table set pci/0000:01:00.0 name mlxsw_erif counters_enabled true

Turns on the counters on mlxsw_erif table.

devlink dpipe table dump pci/0000:01:00.0 name mlxsw_erif

Dumps content of mlxsw_erif table.

devlink dpipe header show pci/0000:01:00.0

Shows all dpipe headers on specified devlink device.

## SEE ALSO
devlink(8), devlink-dev(8), devlink-monitor(8),

## AUTHOR
Jiri Pirko <jiri@mellanox.com>


devlink-health

title: devlink-health(8)

summary: devlink health reporting and recovery

text:
# devlink-health(8)

## NAME
devlink-health - devlink health reporting and recovery

## SYNOPSIS

devlink [ OPTIONS ] health { COMMAND | help }

OPTIONS := { -V[ersion] }

devlink health show [ { DEV | DEV/PORT_INDEX } reporter REPORTER ]

devlink health recover { DEV | DEV/PORT_INDEX } reporter REPORTER

devlink health diagnose { DEV | DEV/PORT_INDEX } reporter REPORTER

devlink health dump show { DEV | DEV/PORT_INDEX } reporter REPORTER

devlink health test { DEV | DEV/PORT_INDEX } reporter REPORTER

devlink health dump clear { DEV | DEV/PORT_INDEX } reporter REPORTER

devlink health set { DEV | DEV/PORT_INDEX } reporter REPORTER [ grace_period MSEC ] [ auto_recover { true | false } ] [ auto_dump { true | false } ]

devlink health help

## DESCRIPTION

### devlink health show - Show status and configuration on all supported reporters.
Displays info about reporters registered on devlink devices and ports.

DEV - specifies the devlink device.

DEV/PORT_INDEX - specifies the devlink port.

REPORTER - specifies the reporter's name registered on specified devlink device or port.

### devlink health recover - Initiate a recovery operation on a reporter.
This action performs a recovery and increases the recoveries counter on success.

DEV - specifies the devlink device.

DEV/PORT_INDEX - specifies the devlink port.

REPORTER - specifies the reporter's name registered on specified devlink device or port.

### devlink health diagnose - Retrieve diagnostics data on a reporter.
DEV - specifies the devlink device.

DEV/PORT_INDEX - specifies the devlink port.

REPORTER - specifies the reporter's name registered on specified devlink device or port.

### devlink health test - Trigger a test event on a reporter.
DEV - specifies the devlink device.

REPORTER - specifies the reporter's name registered on the devlink device.

### devlink health dump show - Display the last saved dump.
devlink health saves a single dump per reporter. If an dump is

not already stored by the Devlink, this command will generate a new

dump. The dump can be generated either automatically when a

reporter reports on an error or manually at the user's request.

DEV - specifies the devlink device.

DEV/PORT_INDEX - specifies the devlink port.

REPORTER - specifies the reporter's name registered on specified devlink device or port.

### devlink health dump clear - Delete the saved dump.
Deleting the saved dump enables a generation of a new dump on

the next "devlink health dump show" command.

DEV - specifies the devlink device.

DEV/PORT_INDEX - specifies the devlink port.

REPORTER - specifies the reporter's name registered on specified devlink device or port.

### devlink health set - Configure health reporter.
Please note that some params are not supported on a reporter which doesn't support a recovery or dump method.

DEV - specifies the devlink device.

DEV/PORT_INDEX - specifies the devlink port.

REPORTER - specifies the reporter's name registered on specified devlink device or port.

grace_period MSEC

Time interval between consecutive auto recoveries.

auto_recover { true | false }

Indicates whether the devlink should execute automatic recover on error.

auto_dump { true | false }

Indicates whether the devlink should execute automatic dump on error.

## EXAMPLES
devlink health show

List status and configuration of available reporters on devices and ports.

devlink health show pci/0000:00:09.0/1 reporter tx

List status and configuration of tx reporter registered on port on pci/0000:00:09.0/1

devlink health recover pci/0000:00:09.0 reporter fw_fatal

Initiate recovery on fw_fatal reporter registered on device on pci/0000:00:09.0.

devlink health recover pci/0000:00:09.0/1 reporter tx

Initiate recovery on tx reporter registered on port on pci/0000:00:09.0/1.

devlink health diagnose pci/0000:00:09.0 reporter fw

List diagnostics data on the specified device and reporter.

devlink health dump show pci/0000:00:09.0/1 reporter tx

Display the last saved dump on the specified port and reporter.

devlink health dump clear pci/0000:00:09.0/1 reporter tx

Delete saved dump on the specified port and reporter.

devlink health set pci/0000:00:09.0 reporter fw_fatal grace_period 3500

Set time interval between auto recoveries to minimum of 3500 msec on the specified device and reporter.

devlink health set pci/0000:00:09.0/1 reporter tx grace_period 3500

Set time interval between auto recoveries to minimum of 3500 msec on the specified port and reporter.

devlink health set pci/0000:00:09.0 reporter fw_fatal auto_recover false

Turn off auto recovery on the specified device and reporter.

## SEE ALSO
devlink(8), devlink-dev(8), devlink-port(8), devlink-param(8), devlink-region(8),

## AUTHOR
Aya Levin <ayal@mellanox.com>


devlink-lc

title: devlink-lc(8)

summary: devlink line card configuration

text:
# devlink-lc(8)

## NAME
devlink-lc - devlink line card configuration

## SYNOPSIS

devlink [ OPTIONS ] lc { COMMAND | help }

OPTIONS := { -V[ersion] }

devlink lc set DEV lc LC_INDEX [ type { LC_TYPE | notype } ]

devlink lc show [ DEV [ lc LC_INDEX ] ]

devlink lc help

## DESCRIPTION

### devlink lc set - change line card attributes
DEV

Specifies the devlink device to operate on.

Format is:

BUS_NAME/BUS_ADDRESS

lc LC_INDEX

Specifies index of a line card slot to set.

type {

LC_TYPE | notype } Type of line card to provision. Each driver provides a list of supported line card types which is shown in the output of devlink lc show command.

### devlink lc show - display line card attributes
DEV

Specifies the devlink device to operate on. If this and lc arguments are omitted all line cards of all devices are listed.

lc LC_INDEX

Specifies index of a line card slot to show.

## EXAMPLES
devlink lc show

Shows the state of all line cards on the system.

devlink lc show pci/0000:01:00.0 lc 1

Shows the state of line card with index 1.

devlink lc set pci/0000:01:00.0 lc 1 type 16x100G

Sets type of specified line card to type 16x100G.

devlink lc set pci/0000:01:00.0 lc 1 notype

Clears provisioning on a line card.

## SEE ALSO
devlink(8), devlink-dev(8), devlink-port(8), devlink-monitor(8),

## AUTHOR
Jiri Pirko <jiri@nvidia.com>


devlink-monitor

title: devlink-monitor(8)

summary: state monitoring

text:
# devlink-monitor(8)

## NAME
devlink-monitor - state monitoring

## SYNOPSIS

devlink monitor [ all | OBJECT-LIST ]

## DESCRIPTION
The devlink utility can monitor the state of devlink devices and ports continuously. This option has a slightly different format. Namely, the monitor command is the first in the command line and then the object list.

OBJECT-LIST is the list of object types that we want to monitor. It may contain dev, port, health, trap, trap-group, trap-policer.

devlink opens Devlink Netlink socket, listens on it and dumps state changes.

## SEE ALSO
devlink(8), devlink-dev(8), devlink-sb(8), devlink-port(8), devlink-health(8), devlink-trap(8),

## AUTHOR
Jiri Pirko <jiri@mellanox.com>


devlink-port

title: devlink-port(8)

summary: devlink port configuration

text:
# devlink-port(8)

## NAME
devlink-port - devlink port configuration

## SYNOPSIS

devlink [ OPTIONS ] port { COMMAND | help }

OPTIONS := { -V[ersion] | -n[no-nice-names] }

devlink port set DEV/PORT_INDEX [ type { eth | ib | auto } ]

devlink port split DEV/PORT_INDEX count COUNT

devlink port unsplit DEV/PORT_INDEX

devlink port show [ DEV/PORT_INDEX ]

devlink port health { show | recover | diagnose | dump | set }

devlink port add { DEV | DEV/PORT_INDEX } [ flavour FLAVOUR ] [ pfnum PFNUMBER ] [ sfnum SFNUMBER ] [ controller CNUM ]

devlink port del DEV/PORT_INDEX

devlink port function set DEV/PORT_INDEX [ hw_addr ADDR ] [ state { active | inactive } ] [ roce { enable | disable } ] [ migratable { enable | disable } ] [ ipsec_crypto { enable | disable } ] [ ipsec_packet { enable | disable } ] [ max_io_eqs EQS ]

devlink port function rate { show | set | add | del | help }

devlink dev param set DEV/PORT_INDEX name PARAMETER value VALUE cmode { runtime | driverinit | permanent }

devlink dev param show [ DEV/PORT_INDEX name PARAMETER ]

devlink port help

## DESCRIPTION

### devlink port set - change devlink port attributes
DEV/PORT_INDEX - specifies the devlink port to operate on.

Format is:

BUS_NAME/BUS_ADDRESS/PORT_INDEX

type { eth | ib | auto }

set port type eth - Ethernet

ib - Infiniband

auto - autoselect

### devlink port split - split devlink port into more
DEV/PORT_INDEX - specifies the devlink port to operate on.

count COUNT

number of ports to split to.

### devlink port unsplit - unsplit previously split devlink port
Could be performed on any split port of the same split group.

DEV/PORT_INDEX - specifies the devlink port to operate on.

### devlink port show - display devlink port attributes
DEV/PORT_INDEX - specifies the devlink port to show. If this argument is omitted all ports are listed.

### devlink port health - devlink health reporting and recovery
Is an alias for devlink-health(8).

### devlink port add - add a devlink port
DEV - specifies the devlink device to operate on. or

DEV/PORT_INDEX - specifies the devlink port index to use for the requested new port. This is optional. When omitted, driver allocates unique port index.

flavour { pcipf | pcisf }

set port flavour pcipf - PCI PF port

pcisf - PCI SF port

pfnum PFNUMBER

Specifies PCI pfnumber to use on which a SF device to create

sfnum SFNUMBER

Specifies sfnumber to assign to the device of the SF. This field is optional for those devices which supports auto assignment of the SF number.

controller CNUM

Specifies controller number for which the SF port is created. This field is optional. It is used only when SF port is created for the external controller.

### devlink port function set - Set the port function attribute(s).
DEV/PORT_INDEX - specifies the devlink port to operate on.

hw_addr ADDR

Hardware address of the function to set. This is a Ethernet MAC address when port type is Ethernet.

state { active | inactive }

New state of the function to change to. active - Once configuration of the function is done, activate the function.

inactive - To inactivate the function and its device(s), set to inactive.

roce { enable | disable }

Set the RoCE capability of the function.

migratable { enable | disable }

Set the migratable capability of the function.

ipsec_crypto { enable | disable }

Set the IPsec crypto offload capability of the function. Controls XFRM state crypto operation (Encrypt/Decrypt) offload.

ipsec_packet { enable | disable }

Set the IPsec packet offload capability of the function. Controls XFRM state and policy offload (Encrypt/Decrypt operation and IPsec encapsulation).

max_io_eqs EQS

Set the maximum number of IO event queues of the function.

### devlink port del - delete a devlink port
DEV/PORT_INDEX - specifies the devlink port to delete.

### devlink port param set - set new value to devlink port configuration parameter
DEV/PORT_INDEX - specifies the devlink port to operate on.

name PARAMETER

Specify parameter name to set.

value VALUE

New value to set.

cmode { runtime | driverinit | permanent }

Configuration mode in which the new value is set. runtime - Set new value while driver is running. This configuration mode doesn't require any reset to apply the new value.

driverinit - Set new value which will be applied during driver initialization. This configuration mode requires restart driver by devlink reload command to apply the new value.

permanent - New value is written to device's non-volatile memory. This configuration mode requires hard reset to apply the new value.

### devlink port param show - display devlink port supported configuration parameters attributes
DEV/PORT_INDEX - specifies the devlink port to operate on.

name PARAMETER Specify parameter name to show. If this argument, as well as port index, are omitted - all parameters supported by devlink device ports are listed.

### devlink port function rate - manage devlink rate objects
Is an alias for devlink-rate(8).

## EXAMPLES
devlink port show

Shows the state of all devlink ports on the system.

devlink port show pci/0000:01:00.0/1

Shows the state of specified devlink port.

devlink port set pci/0000:01:00.0/1 type eth

Set type of specified devlink port to Ethernet.

devlink port split pci/0000:01:00.0/1 count 4

Split the specified devlink port into four ports.

devlink port unsplit pci/0000:01:00.0/1

Unplit the specified previously split devlink port.

devlink port health show

Shows status and configuration of all supported reporters registered on all devlink ports.

devlink port health show pci/0000:01:00.0/1 reporter tx

Shows status and configuration of tx reporter registered on pci/0000:01:00.0/1 devlink port.

devlink port add pci/0000:06:00.0 flavour pcisf pfnum 0 sfnum 88

Add a devlink port of flavour PCI SF on PCI PF having number 0 with SF number 88. To make use of the function an example sequence is to add a port, configure the function attribute and activate the function. Once function usage is completed, inactivate the function and finally delete the port. When there is desire to reuse the port without deletion, it can be reconfigured and activated again when function is in inactive state and function's operational state is detached.

devlink port del pci/0000:06:00.0/1

Delete previously created devlink port. It is recommended to first deactivate the function if the function supports state management.

devlink port function set pci/0000:01:00.0/1 hw_addr 00:00:00:11:22:33

Configure hardware address of the PCI function represented by devlink port. If the port supports change in function state, hardware address must be configured before activating the function.

devlink port function set pci/0000:01:00.0/1 state active

Activate the function. This will initiate the function enumeration and driver loading.

devlink port function set pci/0000:01:00.0/1 state inactive

Deactivate the function. This will initiate the function teardown which results in driver unload and device removal.

devlink port function set pci/0000:01:00.0/1 roce enable

This will enable the RoCE functionality of the function.

devlink port function set pci/0000:01:00.0/1 migratable enable

This will enable the migratable functionality of the function.

devlink port function set pci/0000:01:00.0/1 ipsec_crypto enable

This will enable the IPsec crypto offload functionality of the function.

devlink port function set pci/0000:01:00.0/1 ipsec_packet enable

This will enable the IPsec packet offload functionality of the function.

devlink port function set pci/0000:01:00.0/1 max_io_eqs 4

This will set the maximum number of IO event queues of the function to 4.

devlink port function set pci/0000:01:00.0/1 hw_addr 00:00:00:11:22:33 state active

Configure hardware address and also active the function. When a function is activated together with other configuration in a single command, all the configuration is applied first before changing the state to active.

devlink dev param show

Shows (dumps) all the port parameters across all the devices registered in the devlink.

devlink dev param set pci/0000:01:00.0/1 name internal_error_reset value true cmode runtime

Sets the parameter internal_error_reset of specified devlink port (#1) to true.

devlink port add pci/0000:06:00.0 flavour pcisf pfnum 0 sfnum 88 controller 1

Add a devlink port of flavour PCI SF on controller 1 which has PCI PF of number 0 with SF number 88. To make use of the function an example sequence is to add a port, configure the function attribute and activate the function. Once the function usage is completed, deactivate the function and finally delete the port. When there is desire to reuse the port without deletion, it can be reconfigured and activated again when function is in inactive state and function's operational state is detached.

## SEE ALSO
devlink(8), devlink-dev(8), devlink-sb(8), devlink-monitor(8), devlink-health(8),

## AUTHOR
Jiri Pirko <jiri@mellanox.com>


devlink-rate

title: devlink-rate(8)

summary: devlink rate management

text:
# devlink-rate(8)

## NAME
devlink-rate - devlink rate management

## SYNOPSIS

devlink [ OPTIONS ] port function rate { COMMAND | help }

OPTIONS := { -j[son] | -p[retty] | -i[ec] }

devlink port function rate show [ { DEV/PORT_INDEX | DEV/NODE_NAME } ]

devlink port function rate set { DEV/PORT_INDEX | DEV/NODE_NAME } [ tx_share VALUE ] [ tx_max VALUE ] [ tx_priority N ] [ tx_weight N ] [ { parent NODE_NAME | noparent } ]

devlink port function rate add DEV/NODE_NAME [ tx_share VALUE ] [ tx_max VALUE ] [ tx_priority N ] [ tx_weight N ] [ { parent NODE_NAME | noparent } ]

devlink port function rate del DEV/NODE_NAME

devlink port function rate help

## DESCRIPTION

### devlink port function rate show - display rate objects.
Displays specified rate object or, if not specified, all rate objects. Rate object can be presented by one of the two types:

leaf

Represents a single devlink port; created/destroyed by the driver and bound to the devlink port. As example, some driver may create leaf rate object for every devlink port associated with VF. Since leaf have 1to1 mapping to it's devlink port, in user space it is referred as corresponding devlink port DEV/PORT_INDEX;

node

Represents a group of rate objects; created/deleted by the user (see command below) and bound to the devlink device rather then to the devlink port. In userspace it is referred as DEV/NODE_NAME, where node name can be any, except decimal number, to avoid collisions with leafs.

Command output show rate object identifier, it's type and rate values along with parent node name. Rate values printed in SI units which are more suitable to represent specific value. To print values in IEC units -i switch is used. JSON (-j) output always print rate values in bytes per second. Zero rate values means "unlimited" rates and omitted in output, as well as parent node name.

### devlink port function rate set - set rate object parameters.
Allows set rate object's parameters. If any parameter specified multiple times the last occurrence is used.

DEV/PORT_INDEX - specifies devlink leaf rate object.

DEV/NODE_NAME - specifies devlink node rate object.

tx_share VALUE - specifies minimal tx rate value shared among all rate objects. If rate object is a part of some rate group, then this value shared with rate objects of this rate group.

tx_max VALUE - specifies maximum tx rate value.

tx_priority N - allows for usage of strict priority arbiter among siblings. This arbitration scheme attempts to schedule nodes based on their priority as long as the nodes remain within their bandwidth limit. The higher the priority the higher the probability that the node will get selected for scheduling.

tx_weight N - allows for usage of Weighted Fair Queuing arbitration scheme among siblings. This arbitration scheme can be used simultaneously with the strict priority. As a node is configured with a higher rate it gets more BW relative to it's siblings. Values are relative like a percentage points, they basically tell how much BW should node take relative to it's siblings.

VALUE

These parameter accept a floating point number, possibly followed by either a unit (both SI and IEC units supported).

bit or a bare number

Bits per second

kbit

Kilobits per second

mbit

Megabits per second

gbit

Gigabits per second

tbit

Terabits per second

bps

Bytes per second

kbps

Kilobytes per second

mbps

Megabytes per second

gbps

Gigabytes per second

tbps

Terabytes per second

To specify in IEC units, replace the SI prefix (k-, m-, g-, t-) with IEC prefix (ki-, mi-, gi- and ti-) respectively. Input is case-insensitive.

N

These parameter accept integer meaning weight or priority of a node.

parent NODE_NAME | noparent - set rate object parent to existing node with name NODE_NAME or unset parent. Rate limits of the parent node applied to all it's children. Actual behaviour is details of driver's implementation. Setting parent to empty ("") name due to the kernel logic treated as parent unset.

### devlink port function rate add - create node rate object with specified parameters.
Creates rate object of type node and sets parameters. Parameters same as for the "set" command.

DEV/NODE_NAME - specifies the devlink node rate object to create.

### devlink port function rate del - delete node rate object
Delete specified devlink node rate object. Node can't be deleted if there is any child, user must explicitly unset the parent.

DEV/NODE_NAME - specifies devlink node rate object to delete.

### devlink port function rate help - display usage information
Display devlink rate usage information

## EXAMPLES
* Display all rate objects:

\# devlink port function rate show

pci/0000:03:00.0/1 type leaf parent some_group

pci/0000:03:00.0/2 type leaf tx_share 12Mbit

pci/0000:03:00.0/some_group type node tx_share 1Gbps tx_max 5Gbps

* Display leaf rate object bound to the 1st devlink port of the pci/0000:03:00.0 device:

\# devlink port function rate show pci/0000:03:00.0/1

pci/0000:03:00.0/1 type leaf

* Display leaf rate object rate values using IEC units:

\# devlink -i port function rate show pci/0000:03:00.0/2

pci/0000:03:00.0/2 type leaf 11718Kibit

* Display node rate object with name some_group of the pci/0000:03:00.0 device:

\# devlink port function rate show pci/0000:03:00.0/some_group

pci/0000:03:00.0/some_group type node

* Display pci/0000:03:00.0/2 leaf rate object as pretty JSON output:

\# devlink -jp port function rate show pci/0000:03:00.0/2

{

"rate": {

"pci/0000:03:00.0/2": {

"type": "leaf",

"tx_share": 1500000

}

}

}

* Create node rate object with name "1st_group" on pci/0000:03:00.0 device:

\# devlink port function rate add pci/0000:03:00.0/1st_group

* Create node rate object with specified parameters:

\# devlink port function rate add pci/0000:03:00.0/2nd_group \

tx_share 10Mbit tx_max 30Mbit parent 1st_group

* Set parameters to the specified leaf rate object:

\# devlink port function rate set pci/0000:03:00.0/1 \

tx_share 2Mbit tx_max 10Mbit

* Set leaf's parent to "1st_group":

\# devlink port function rate set pci/0000:03:00.0/1 parent 1st_group

* Unset leaf's parent:

\# devlink port function rate set pci/0000:03:00.0/1 noparent

* Delete node rate object:

\# devlink port function rate del pci/0000:03:00.0/2nd_group

## SEE ALSO
devlink(8), devlink-port(8)

## AUTHOR
Dmytro Linkin <dlinkin@nvidia.com>


devlink-region

title: devlink-region(8)

summary: devlink address region access

text:
# devlink-region(8)

## NAME
devlink-region - devlink address region access

## SYNOPSIS

devlink [ OPTIONS ] region { COMMAND | help }

OPTIONS := { -V[ersion] | -n[no-nice-names] }

devlink region show [ DEV/REGION ]

devlink region new DEV/REGION [ snapshot SNAPSHOT_ID ]

devlink region del DEV/REGION snapshot SNAPSHOT_ID

devlink region dump DEV/REGION snapshot SNAPSHOT_ID

devlink region read DEV/REGION [ snapshot SNAPSHOT_ID ] address ADDRESS length LENGTH

devlink region help

## DESCRIPTION

### devlink region show - Show all supported address regions names, snapshots and sizes
DEV/REGION - specifies the devlink device and address-region to query.

### devlink region new - Create a snapshot specified by address-region name and snapshot ID
DEV/REGION - specifies the devlink device and address-region to snapshot

snapshot SNAPSHOT_ID - optionally specifies the snapshot ID to assign. If not specified, devlink will assign a unique ID to the snapshot.

### devlink region del - Delete a snapshot specified by address-region name and snapshot ID
DEV/REGION - specifies the devlink device and address-region to delete the snapshot from

snapshot SNAPSHOT_ID - specifies the snapshot ID to delete

### devlink region dump - Dump all the available data from a region or from snapshot of a region
DEV/REGION - specifies the device and address-region to dump from.

snapshot SNAPSHOT_ID - specifies the snapshot-id of the region to dump.

### devlink region read - Read from a specific region address for a given length
DEV/REGION - specifies the device and address-region to read from.

snapshot SNAPSHOT_ID - specifies the snapshot-id of the region to read.

address ADDRESS - specifies the address to read from.

length LENGTH - specifies the length of data to read.

## EXAMPLES
devlink region show

List available address regions and snapshot.

devlink region new pci/0000:00:05.0/cr-space

Create a new snapshot from cr-space address region from device pci/0000:00:05.0.

devlink region del pci/0000:00:05.0/cr-space snapshot 1

Delete snapshot id 1 from cr-space address region from device pci/0000:00:05.0.

devlink region dump pci/0000:00:05.0/cr-space snapshot 1

Dump the snapshot taken from cr-space address region with ID 1

devlink region read pci/0000:00:05.0/cr-space snapshot 1 address 0x10 length 16

Read from address 0x10, 16 Bytes of snapshot ID 1 taken from cr-space address region

## SEE ALSO
devlink(8), devlink-dev(8), devlink-port(8), devlink-monitor(8),

## AUTHOR
Alex Vesker <valex@mellanox.com>


devlink-resource

title: devlink-resource(8)

summary: devlink device resource configuration

text:
# devlink-resource(8)

## NAME
devlink-resource - devlink device resource configuration

## SYNOPSIS

devlink [ OPTIONS ] resource { COMMAND | help }

OPTIONS := { -v[erbose] }

devlink resource show DEV

devlink resource help

devlink resource set DEV path RESOURCE_PATH size RESOURCE_SIZE

## DESCRIPTION

### devlink resource show - display devlink device's resosources
DEV - specifies the devlink device to show.

Format is:

BUS_NAME/BUS_ADDRESS

### devlink resource set - sets resource size of specific resource
DEV - specifies the devlink device.

path RESOURCE_PATH

Resource's path.

size RESOURCE_SIZE

The new resource's size.

## EXAMPLES
devlink resource show pci/0000:01:00.0

Shows the resources of the specified devlink device.

devlink resource set pci/0000:01:00.0 path /kvd/linear size 98304

Sets the size of the specified resource for the specified devlink device.

## SEE ALSO
devlink(8), devlink-port(8), devlink-sb(8), devlink-monitor(8),

## AUTHOR
Arkadi Sharshevsky <arkadis@mellanox.com>


devlink-sb

title: devlink-sb(8)

summary: devlink shared buffer configuration

text:
# devlink-sb(8)

## NAME
devlink-sb - devlink shared buffer configuration

## SYNOPSIS

devlink [ OPTIONS ] sb { COMMAND | help }

OPTIONS := { -V[ersion] | -n[no-nice-names] }

devlink sb show [ DEV [ sb SB_INDEX ] ]

devlink sb pool show [ DEV [ sb SB_INDEX ]

pool POOL_INDEX ]

devlink sb pool set DEV [ sb SB_INDEX ]

pool POOL_INDEX

size POOL_SIZE

thtype { static | dynamic }

devlink sb port pool show [ DEV/PORT_INDEX [ sb SB_INDEX ]

pool POOL_INDEX ]

devlink sb port pool set DEV/PORT_INDEX [ sb SB_INDEX ]

pool POOL_INDEX

th THRESHOLD

devlink sb tc bind show [ DEV/PORT_INDEX [ sb SB_INDEX ]

tc TC_INDEX

type { ingress | egress } ]

devlink sb tc bind set DEV/PORT_INDEX [ sb SB_INDEX ]

tc TC_INDEX

type { ingress | egress }

pool POOL_INDEX

th THRESHOLD

devlink sb occupancy show { DEV | DEV/PORT_INDEX } [ sb SB_INDEX ]

devlink sb occupancy snapshot DEV [ sb SB_INDEX ]

devlink sb occupancy clearmax DEV [ sb SB_INDEX ]

devlink sb help

## DESCRIPTION

### devlink sb show - display available shared buffers and their attributes
DEV - specifies the devlink device to show shared buffers. If this argument is omitted all shared buffers of all devices are listed.

SB_INDEX - specifies the shared buffer. If this argument is omitted shared buffer with index 0 is selected. Behaviour of this argument it the same for every command.

### devlink sb pool show - display available pools and their attributes
DEV - specifies the devlink device to show pools. If this argument is omitted all pools of all devices are listed.

Display available pools listing their type, size, thtype and cell_size. cell_size is the allocation granularity of memory within the shared buffer. Drivers may round up, round down or reject size passed to the set command if it is not multiple of cell_size.

### devlink sb pool set - set attributes of pool
DEV - specifies the devlink device to set pool.

size POOL_SIZE

size of the pool in Bytes.

thtype { static | dynamic }

pool threshold type. static - Threshold values for the pool will be passed in Bytes.

dynamic - Threshold values ("to_alpha") for the pool will be used to compute alpha parameter according to formula:

alpha = 2 ^ (to_alpha - 10)

The range of the passed value is between 0 to 20. The computed alpha is used to determine the maximum usage of the flow:

max_usage = alpha / (1 + alpha) * Free_Buffer

### devlink sb port pool show - display port-pool combinations and threshold for each
DEV/PORT_INDEX - specifies the devlink port.

pool POOL_INDEX

pool index.

### devlink sb port pool set - set port-pool threshold
DEV/PORT_INDEX - specifies the devlink port.

pool POOL_INDEX

pool index.

th THRESHOLD

threshold value. Type of the value is either Bytes or "to_alpha", depends on thtype set for the pool.

### devlink sb tc bind show - display port-TC to pool bindings and threshold for each
DEV/PORT_INDEX - specifies the devlink port.

tc TC_INDEX

index of either ingress or egress TC, usually in range 0 to 8 (depends on device).

type { ingress | egress }

TC type.

### devlink sb tc bind set - set port-TC to pool binding with specified threshold
DEV/PORT_INDEX - specifies the devlink port.

tc TC_INDEX

index of either ingress or egress TC, usually in range 0 to 8 (depends on device).

type { ingress | egress }

TC type.

pool POOL_INDEX

index of pool to bind this to.

th THRESHOLD

threshold value. Type of the value is either Bytes or "to_alpha", depends on thtype set for the pool.

### devlink sb occupancy show - display shared buffer occupancy values for device or port
This command is used to browse shared buffer occupancy values. Values are showed for every port-pool combination as well as for all port-TC combinations (with pool this port-TC is bound to). Format of value is:

current_value/max_value

Note that before showing values, one has to issue occupancy snapshot command first.

DEV - specifies the devlink device to show occupancy values for.

DEV/PORT_INDEX - specifies the devlink port to show occupancy values for.

### devlink sb occupancy snapshot - take occupancy snapshot of shared buffer for device
This command is used to take a snapshot of shared buffer occupancy values. After that, the values can be showed using occupancy show command.

DEV - specifies the devlink device to take occupancy snapshot on.

### devlink sb occupancy clearmax - clear occupancy watermarks of shared buffer for device
This command is used to reset maximal occupancy values reached for whole device. Note that before browsing reset values, one has to issue occupancy snapshot command.

DEV - specifies the devlink device to clear occupancy watermarks on.

## EXAMPLES
devlink sb show

List available share buffers.

devlink sb pool show

List available pools and their config.

devlink sb port pool show pci/0000:03:00.0/1 pool 0

Show port-pool setup for specified port and pool.

sudo devlink sb port pool set pci/0000:03:00.0/1 pool 0 th 15

Change threshold for port specified port and pool.

devlink sb tc bind show pci/0000:03:00.0/1 tc 0 type ingress

Show pool binding and threshold for specified port and TC.

sudo devlink sb tc bind set pci/0000:03:00.0/1 tc 0 type ingress pool 0 th 9

Set pool binding and threshold for specified port and TC.

sudo devlink sb occupancy snapshot pci/0000:03:00.0

Make a snapshot of occupancy of shared buffer for specified devlink device.

devlink sb occupancy show pci/0000:03:00.0/1

Show occupancy for specified port from the snapshot.

sudo devlink sb occupancy clearmax pci/0000:03:00.0

Clear watermarks for shared buffer of specified devlink device.

## SEE ALSO
devlink(8), devlink-dev(8), devlink-port(8), devlink-monitor(8),

## AUTHOR
Jiri Pirko <jiri@mellanox.com>


devlink-trap

title: devlink-trap(8)

summary: devlink trap configuration

text:
# devlink-trap(8)

## NAME
devlink-trap - devlink trap configuration

## SYNOPSIS

devlink [ OPTIONS ] trap { COMMAND | help }

OPTIONS := { -v[erbose] | -s[tatistics] }

devlink trap show [ DEV trap TRAP ]

devlink trap set DEV trap TRAP [ action { trap | drop | mirror } ]

devlink trap group show [ DEV group GROUP ]

devlink trap group set DEV group GROUP [ action { trap | drop | mirror } ]

[ policer POLICER ] [ nopolicer ]

devlink trap policer set DEV policer POLICER [ rate RATE ] [ burst BURST ]

devlink trap help

## DESCRIPTION

### devlink trap show - display available packet traps and their attributes
DEV - specifies the devlink device from which to show packet traps. If this argument is omitted all packet traps of all devices are listed.

trap TRAP - specifies the packet trap. Only applicable if a devlink device is also specified.

### devlink trap set - set attributes of a packet trap
DEV - specifies the devlink device the packet trap belongs to.

trap TRAP - specifies the packet trap.

action { trap | drop | mirror }

packet trap action. trap - the sole copy of the packet is sent to the CPU.

drop - the packet is dropped by the underlying device and a copy is not sent to the CPU.

mirror - the packet is forwarded by the underlying device and a copy is sent to the CPU.

### devlink trap group show - display available packet trap groups and their attributes
DEV - specifies the devlink device from which to show packet trap groups. If this argument is omitted all packet trap groups of all devices are listed.

group GROUP - specifies the packet trap group. Only applicable if a devlink device is also specified.

### devlink trap group set - set attributes of a packet trap group
DEV - specifies the devlink device the packet trap group belongs to.

group GROUP - specifies the packet trap group.

action { trap | drop | mirror }

packet trap action. The action is set for all the packet traps member in the trap group. The actions of non-drop traps cannot be changed and are thus skipped.

policer POLICER

packet trap policer. The policer to bind to the packet trap group. A value of "0" will unbind the currently bound policer.

nopolicer

Unbind packet trap policer from the packet trap group.

### devlink trap policer set - set attributes of packet trap policer
DEV - specifies the devlink device the packet trap policer belongs to.

policer POLICER - specifies the packet trap policer.

rate RATE - packet trap policer rate in packets per second.

burst BURST - packet trap policer burst size in packets.

## EXAMPLES
devlink trap show

List available packet traps.

devlink trap group show

List available packet trap groups.

devlink -vs trap show pci/0000:01:00.0 trap source_mac_is_multicast

Show attributes and statistics of a specific packet trap.

devlink -s trap group show pci/0000:01:00.0 group l2_drops

Show attributes and statistics of a specific packet trap group.

devlink trap set pci/0000:01:00.0 trap source_mac_is_multicast action trap

Set the action of a specific packet trap to 'trap'.

devlink trap policer show

List available packet trap policers.

devlink -s trap policer show pci/0000:01:00.0 policer 1

Show attributes and statistics of a specific packet trap policer.

devlink trap policer set pci/0000:01:00.0 policer 1 rate 1000 burst 128

Set the rate and burst size of a specific packet trap policer.

## SEE ALSO
devlink(8), devlink-dev(8), devlink-monitor(8),

## AUTHOR
Ido Schimmel <idosch@mellanox.com>


genl

title: genl(8)

summary: generic netlink utility frontend

text:
# genl(8)

## NAME
genl - generic netlink utility frontend

## SYNOPSIS

genl [ -s[tatistics] ] [ -d[etails] ] [ -r[aw] ] OBJECT

genl { -V[ersion] | -h[elp] }

OBJECT := { ctrl CTRL_OPTS }

CTRL_OPTS := { help | list | monitor | get PARMS }

PARMS := { name NAME | id ID }

## DESCRIPTION
The genl utility provides a simple frontend to the generic netlink library. Although it's designed to support multiple OBJECTs, for now only the ctrl object is available, which is used to query the generic netlink controller.

### ctrl
The generic netlink controller can be queried in various ways:

help

This command just prints a help text for the ctrl object.

list

Show the registered netlink users.

monitor

Listen for generic netlink notifications.

get

Query the controller for a given user, identified either by name or id.

## OPTIONS
genl supports the following options.

-h, -help

Show summary of options.

-V, -Version

Show version of program.

-s, -stats, -statistics

Show object statistics.

-d, -details

Show object details.

-r, -raw

Dump raw output only.

## SEE ALSO
ip(8)

## AUTHOR
genl was written by Jamal Hadi Salim <hadi@cyberus.ca>.

This manual page was written by Petr Sabata <contyk@redhat.com>.


ifstat

title: ifstat(8)

text:
# ifstat(8)

## NAME
ifstat - handy utility to read network interface statistics

## SYNOPSIS

ifstat [ OPTIONS ] [ INTERFACE_LIST ]

INTERFACE_LIST := INTERFACE_LIST | interface

## DESCRIPTION
ifstat neatly prints out network interface statistics. The utility keeps records of the previous data displayed in history files and by default only shows difference between the last and the current call. Location of the history files defaults to /tmp/.ifstat.u$UID but may be overridden with the IFSTAT_HISTORY environment variable. Similarly, the default location for xstat (extended stats) is /tmp/.<xstat name>_ifstat.u$UID.

## OPTIONS
-h, --help

Show summary of options.

-V, --version

Show version of program.

-a, --ignore

Ignore the history file.

-d, --scan=SECS

Sample statistics every SECS second.

-e, --errors

Show errors.

-n, --nooutput

Don't display any output. Update the history file only.

-r, --reset

Reset history.

-s, --noupdate

Don't update the history file.

-t, --interval=SECS

Report average over the last SECS seconds.

-z, --zeros

Show entries with zero activity.

-j, --json

Display results in JSON format

-p, --pretty

If combined with --json, pretty print the output.

-x, --extended=TYPE

Show extended stats of TYPE. Supported types are:

cpu_hits - Counts only packets that went via the CPU.

## ENVIRONMENT
IFSTAT_HISTORY

If set, it's value is interpreted as alternate history file path.

## SEE ALSO
ip(8)

## AUTHOR
ifstat was written by Alexey Kuznetsov <kuznet@ms2.inr.ac.ru>.

This manual page was written by Petr Sabata <contyk@redhat.com>.


ip

title: ip(8)

text:
# ip(8)

## NAME
ip - show / manipulate routing, network devices, interfaces and tunnels

## SYNOPSIS

ip [ OPTIONS ] OBJECT { COMMAND | help }

ip [ -force ] -batch filename

OBJECT := { address | addrlabel | fou | help | ila | ioam | l2tp | link | macsec | maddress | monitor | mptcp | mroute | mrule | neighbor | neighbour | netconf | netns | nexthop | ntable | ntbl | route | rule | sr | tap | tcpmetrics | token | tunnel | tuntap | vrf | xfrm }

OPTIONS := { -V[ersion] | -h[uman-readable] | -s[tatistics] | -d[etails] | -r[esolve] | -iec | -f[amily] { inet | inet6 | link } | -4 | -6 | -B | -0 | -l[oops] { maximum-addr-flush-attempts } | -o[neline] | -rc[vbuf] [size] | -t[imestamp] | -ts[hort] | -n[etns] name | -N[umeric] | -a[ll] | -c[olor] | -br[ief] | -j[son] | -p[retty] }

## OPTIONS
-V, -Version

Print the version of the ip utility and exit.

-h, -human, -human-readable

output statistics with human readable values followed by suffix.

-b, -batch <FILENAME>

Read commands from provided file or standard input and invoke them. First failure will cause termination of ip.

-force

Don't terminate ip on errors in batch mode. If there were any errors during execution of the commands, the application return code will be non zero.

-s, -stats, -statistics

Output more information. If the option appears twice or more, the amount of information increases. As a rule, the information is statistics or some time values.

-d, -details

Output more detailed information.

-l, -loops <COUNT>

Specify maximum number of loops the 'ip address flush' logic will attempt before giving up. The default is 10. Zero (0) means loop until all addresses are removed.

-f, -family <FAMILY>

Specifies the protocol family to use. The protocol family identifier can be one of inet, inet6, bridge, mpls or link. If this option is not present, the protocol family is guessed from other arguments. If the rest of the command line does not give enough information to guess the family, ip falls back to the default one, usually inet or any. link is a special family identifier meaning that no networking protocol is involved.

-4

shortcut for -family inet.

-6

shortcut for -family inet6.

-B

shortcut for -family bridge.

-M

shortcut for -family mpls.

-0

shortcut for -family link.

-o, -oneline

output each record on a single line, replacing line feeds with the '\' character. This is convenient when you want to count records with wc(1) or to grep(1) the output.

-r, -resolve

use the system's name resolver to print DNS names instead of host addresses.

-n, -netns <NETNS>

switches ip to the specified network namespace NETNS. Actually it just simplifies executing of: ip netns exec NETNS ip [ OPTIONS ] OBJECT { COMMAND | help }

to

ip -n[etns] NETNS [ OPTIONS ] OBJECT { COMMAND | help }

-N, -Numeric

Print the number of protocol, scope, dsfield, etc directly instead of converting it to human readable name.

-a, -all

executes specified command over all objects, it depends if command supports this option.

-c[color][={always|auto|never}

Configure color output. If parameter is omitted or always, color output is enabled regardless of stdout state. If parameter is auto, stdout is checked to be a terminal before enabling color output. If parameter is never, color output is disabled. If specified multiple times, the last one takes precedence. This flag is ignored if -json is also given. Used color palette can be influenced by COLORFGBG environment variable (see ENVIRONMENT).

-t, -timestamp

display current time when using monitor option.

-ts, -tshort

Like -timestamp, but use shorter format.

-rc, -rcvbuf<SIZE>

Set the netlink socket receive buffer size, defaults to 1MB.

-iec

print human readable rates in IEC units (e.g. 1Ki = 1024).

-br, -brief

Print only basic information in a tabular format for better readability. This option is currently only supported by ip addr show , ip link show & ip neigh show commands.

-j, -json

Output results in JavaScript Object Notation (JSON).

-p, -pretty

The default JSON format is compact and more efficient to parse but hard for most users to read. This flag adds indentation for readability.

-echo

Request the kernel to send the applied configuration back.

## IP - COMMAND SYNTAX

### OBJECT
address

- protocol (IP or IPv6) address on a device.

addrlabel

- label configuration for protocol address selection.

fou

- Foo-over-UDP receive port configuration.

ila

- manage identifier locator addresses (ILA).

ioam

- manage IOAM namespaces and IOAM schemas.

l2tp

- tunnel ethernet over IP (L2TPv3).

link

- network device.

macsec

- MACsec device configuration.

maddress

- multicast address.

monitor

- watch for netlink messages.

mptcp

- manage MPTCP path manager.

mroute

- multicast routing cache entry.

mrule

- rule in multicast routing policy database.

neighbour

- manage ARP or NDISC cache entries.

netconf

- network configuration monitoring.

netns

- manage network namespaces.

nexthop

- manage nexthop objects.

ntable

- manage the neighbor cache's operation.

route

- routing table entry.

rule

- rule in routing policy database.

sr

- manage IPv6 segment routing.

stats

- manage and show interface statistics.

tcp_metrics/tcpmetrics

- manage TCP Metrics.

token

- manage tokenized interface identifiers.

tunnel

- tunnel over IP.

tuntap

- manage TUN/TAP devices.

vrf

- manage virtual routing and forwarding devices.

xfrm

- manage IPSec policies.

The names of all objects may be written in full or abbreviated form, for example address can be abbreviated as addr or just a.

### COMMAND
Specifies the action to perform on the object. The set of possible actions depends on the object type. As a rule, it is possible to add, delete and show (or list ) objects, but some objects do not allow all of these operations or have some additional commands. The help command is available for all objects. It prints out a list of available commands and argument syntax conventions.

If no command is given, some default command is assumed. Usually it is list or, if the objects of this class cannot be listed, help.

## ENVIRONMENT
COLORFGBG

If set, it's value is used for detection whether background is dark or light and use contrast colors for it. COLORFGBG environment variable usually contains either two or three values separated by semicolons; we want the last value in either case. If this value is 0-6 or 8, chose colors suitable for dark background:

COLORFGBG=";0" ip -c a

## EXIT STATUS
Exit status is 0 if command was successful, and 1 if there is a syntax error. If an error was reported by the kernel exit status is 2.

## EXAMPLES
ip addr

Shows addresses assigned to all network interfaces.

ip neigh

Shows the current neighbour table in kernel.

ip link set x up

Bring up interface x.

ip link set x down

Bring down interface x.

ip route

Show table routes.

## HISTORY
ip was written by Alexey N. Kuznetsov and added in Linux 2.2.

## SEE ALSO
ip-address(8), ip-addrlabel(8), ip-fou(8), ip-ioam(8), ip-l2tp(8), ip-link(8), ip-macsec(8), ip-maddress(8), ip-monitor(8), ip-mptcp(8), ip-mroute(8), ip-neighbour(8), ip-netconf(8), ip-netns(8), ip-nexthop(8), ip-ntable(8), ip-route(8), ip-rule(8), ip-sr(8), ip-stats(8), ip-tcp_metrics(8), ip-token(8), ip-tunnel(8), ip-vrf(8), ip-xfrm(8)

IP Command reference ip-cref.ps

## REPORTING BUGS
Report any bugs to the Network Developers mailing list <netdev@vger.kernel.org> where the development and maintenance is primarily done. You do not have to be subscribed to the list to send a message there.

## AUTHOR
Original Manpage by Michail Litvak <mci@owl.openwall.com>


ip-address

title: ip-address(8)

summary: protocol address management

text:
# ip-address(8)

## NAME
ip-address - protocol address management

## SYNOPSIS

ip [ OPTIONS ] address { COMMAND | help }

ip address { add | change | replace } IFADDR dev IFNAME [ LIFETIME ] [ CONFFLAG-LIST ]

ip address delete IFADDR dev IFNAME [ mngtmpaddr ]

ip address { save | flush } [ dev IFNAME ] [ scope SCOPE-ID ] [ metric METRIC ] [ to PREFIX ] [ FLAG-LIST ] [ label PATTERN ] [ up ]

ip address [ show [ dev IFNAME ] [ scope SCOPE-ID ] [ to PREFIX ] [ FLAG-LIST ] [ label PATTERN ] [ master DEVICE ] [ type TYPE ] [ vrf NAME ] [ up ] [ nomaster ] proto ADDRPROTO ] ]

ip address { showdump | restore }

IFADDR := PREFIX | ADDR peer PREFIX [ broadcast ADDR ] [ anycast ADDR ] [ label LABEL ] [ scope SCOPE-ID ] [ proto ADDRPROTO ]

SCOPE-ID := [ host | link | global | NUMBER ]

ADDRPROTO := [ NAME | NUMBER ]

FLAG-LIST := [ FLAG-LIST ] FLAG

FLAG := [ [-]permanent | [-]dynamic | [-]secondary | [-]primary | [-]tentative | [-]deprecated | [-]dadfailed | [-]temporary | CONFFLAG-LIST ]

CONFFLAG-LIST := [ CONFFLAG-LIST ] CONFFLAG

CONFFLAG := [ home | mngtmpaddr | nodad | optimistic | noprefixroute | autojoin ]

LIFETIME := [ valid_lft LFT ] [ preferred_lft LFT ]

LFT := [ forever | SECONDS ]

TYPE := [ bridge | bridge_slave | bond | bond_slave | can | dummy | hsr | ifb | ipoib | macvlan | macvtap | vcan | veth | vlan | vxlan | ip6tnl | ipip | sit | gre | gretap | erspan | ip6gre | ip6gretap | ip6erspan | vti | vrf | nlmon | ipvlan | lowpan | geneve | macsec | netkit ]

## DESCRIPTION
The address is a protocol (IPv4 or IPv6) address attached to a network device. Each device must have at least one address to use the corresponding protocol. It is possible to have several different addresses attached to one device. These addresses are not discriminated, so that the term alias is not quite appropriate for them and we do not use it in this document.

The ip address command displays addresses and their properties, adds new addresses and deletes old ones.

### ip address add - add new protocol address.
dev IFNAME

the name of the device to add the address to.

local ADDRESS (default)

the address of the interface. The format of the address depends on the protocol. It is a dotted quad for IP and a sequence of hexadecimal halfwords separated by colons for IPv6. The ADDRESS may be followed by a slash and a decimal number which encodes the network prefix length.

peer ADDRESS

the address of the remote endpoint for pointopoint interfaces. Again, the ADDRESS may be followed by a slash and a decimal number, encoding the network prefix length. If a peer address is specified, the local address cannot have a prefix length. The network prefix is associated with the peer rather than with the local address.

broadcast ADDRESS

the broadcast address on the interface. It is possible to use the special symbols '+' and '-' instead of the broadcast address. In this case, the broadcast address is derived by setting/resetting the host bits of the interface prefix.

label LABEL

Each address may be tagged with a label string. The maximum allowed total length of label is 15 characters.

scope SCOPE_VALUE

the scope of the area where this address is valid. The available scopes are listed in /usr/share/iproute2/rt_scopes or /etc/iproute2/rt_scopes (has precedence if exists). Predefined scope values are:

global - the address is globally valid.

site - (IPv6 only, deprecated) the address is site local, i.e. it is valid inside this site.

link - the address is link local, i.e. it is valid only on this device.

host - the address is valid only inside this host.

metric NUMBER

priority of prefix route associated with address.

valid_lft LFT

the valid lifetime of this address; see section 5.5.4 of RFC 4862. When it expires, the address is removed by the kernel. Defaults to forever.

preferred_lft LFT

the preferred lifetime of this address; see section 5.5.4 of RFC 4862. When it expires, the address is no longer used for new outgoing connections. Defaults to forever.

home

(IPv6 only) designates this address the "home address" as defined in RFC 6275.

mngtmpaddr

(IPv6 only) make the kernel manage temporary addresses created from this one as template on behalf of Privacy Extensions (RFC3041). For this to become active, the use_tempaddr sysctl setting has to be set to a value greater than zero. The given address needs to have a prefix length of 64. This flag allows to use privacy extensions in a manually configured network, just like if stateless auto-configuration was active.

nodad

(IPv6 only) do not perform Duplicate Address Detection (RFC 4862) when adding this address.

optimistic

(IPv6 only) When performing Duplicate Address Detection, use the RFC 4429 optimistic variant.

noprefixroute

Do not automatically create a route for the network prefix of the added address, and don't search for one to delete when removing the address. Changing an address to add this flag will remove the automatically added prefix route, changing it to remove this flag will create the prefix route automatically.

autojoin

Joining multicast groups on Ethernet level via ip maddr command does not work if connected to an Ethernet switch that does IGMP snooping since the switch would not replicate multicast packets on ports that did not have IGMP reports for the multicast addresses. Linux VXLAN interfaces created via ip link add vxlan have the group option that enables them to do the required join.

Using the autojoin flag when adding a multicast address enables similar functionality for Openvswitch VXLAN interfaces as well as other tunneling mechanisms that need to receive multicast traffic.

proto ADDRPROTO

the protocol identifier of this route. ADDRPROTO may be a number or a string from the file /etc/iproute2/rt_addrprotos. If the protocol ID is not given, ip assumes protocol 0. Several protocol values have a fixed interpretation. Namely:

kernel_lo - The ::1 address that kernel installs on a loopback netdevice has this

protocol value

kernel_ra - IPv6 addresses installed in response to router advertisement messages

kernel_ll - Link-local addresses have this protocol value

The rest of the values are not reserved and the administrator is free to assign (or not to assign) protocol tags.

### ip address delete - delete protocol address
Arguments: coincide with the arguments of ip address add.

The device name is a required argument.

### ip address show - look at protocol addresses
dev IFNAME (default)

name of device.

scope SCOPE_VAL

only list addresses with this scope.

to PREFIX

only list addresses matching this prefix.

label PATTERN

only list addresses with labels matching the PATTERN. PATTERN is a usual shell style pattern.

master DEVICE

only list interfaces enslaved to this master device.

vrf NAME

only list interfaces enslaved to this vrf.

type TYPE

only list interfaces of the given type. Note that the type name is not checked against the list of supported types - instead it is sent as-is to the kernel. Later it is used to filter the returned interface list by comparing it with the relevant attribute in case the kernel didn't filter already. Therefore any string is accepted, but may lead to empty output.

up

only list running interfaces.

nomaster

only list interfaces with no master.

dynamic and permanent

(IPv6 only) only list addresses installed due to stateless address configuration or only list permanent (not dynamic) addresses. These two flags are inverses of each other, so -dynamic is equal to permanent and -permanent is equal to dynamic.

tentative

(IPv6 only) only list addresses which have not yet passed duplicate address detection.

-tentative

(IPv6 only) only list addresses which are not in the process of duplicate address detection currently.

deprecated

(IPv6 only) only list deprecated addresses.

-deprecated

(IPv6 only) only list addresses not being deprecated.

dadfailed

(IPv6 only) only list addresses which have failed duplicate address detection.

-dadfailed

(IPv6 only) only list addresses which have not failed duplicate address detection.

temporary or secondary

List temporary IPv6 or secondary IPv4 addresses only. The Linux kernel shares a single bit for those, so they are actually aliases for each other although the meaning differs depending on address family.

-temporary or -secondary

These flags are aliases for primary.

primary

List only primary addresses, in IPv6 exclude temporary ones. This flag is the inverse of temporary and secondary.

-primary

This is an alias for temporary or secondary.

proto ADDRPROTO

Only show addresses with a given protocol, or those for which the kernel response did not include protocol. See the corresponding argument to ip address add for details about address protocols.

### ip address flush - flush protocol addresses
This command flushes the protocol addresses selected by some criteria.

This command has the same arguments as show except that type and master selectors are not supported. Another difference is that it does not run when no arguments are given.

Warning: This command and other flush commands are unforgiving. They will cruelly purge all the addresses.

With the -statistics option, the command becomes verbose. It prints out the number of deleted addresses and the number of rounds made to flush the address list. If this option is given twice, ip address flush also dumps all the deleted addresses in the format described in the previous subsection.

## EXAMPLES
ip address show

Shows IPv4 and IPv6 addresses assigned to all network interfaces. The 'show' subcommand can be omitted.

ip address show up

Same as above except that only addresses assigned to active network interfaces are shown.

ip address show dev eth0

Shows IPv4 and IPv6 addresses assigned to network interface eth0.

ip address add 2001:0db8:85a3::0370:7334/64 dev eth1

Adds an IPv6 address to network interface eth1.

ip address delete 2001:0db8:85a3::0370:7334/64 dev eth1

Delete the IPv6 address added above.

ip address flush dev eth4 scope global

Removes all global IPv4 and IPv6 addresses from device eth4. Without 'scope global' it would remove all addresses including IPv6 link-local ones.

## SEE ALSO
ip(8)

## AUTHOR
Original Manpage by Michail Litvak <mci@owl.openwall.com>


ip-addrlabel

title: ip-addrlabel(8)

summary: protocol address label management

text:
# ip-addrlabel(8)

## NAME
ip-addrlabel - protocol address label management

## SYNOPSIS

ip addrlabel { COMMAND | help }

ip addrlabel { add | del } prefix PREFIX [ dev DEV ] [ label NUMBER ]

ip addrlabel { list | flush }

## DESCRIPTION
IPv6 address labels are used for address selection; they are described in RFC 3484. Precedence is managed by userspace, and only the label itself is stored in the kernel.

### ip addrlabel add - add an address label
add an address label entry to the kernel.

prefix PREFIX

dev DEV

the outgoing interface.

label NUMBER

the label for the prefix. 0xffffffff is reserved.

### ip addrlabel del - delete an address label
delete an address label entry from the kernel. Arguments: coincide with the arguments of ip addrlabel add but the label is not required.

### ip addrlabel list - list address labels
list the current address label entries in the kernel.

### ip addrlabel flush - flush address labels
flush all address labels in the kernel. This does not restore any default settings.

## SEE ALSO
ip(8)

## AUTHOR
Manpage by Yoshifuji Hideaki / 吉藤英明


ip-fou

title: ip-fou(8)

summary: Foo-over-UDP receive port configuration

text:
# ip-fou(8)

## NAME
ip-fou - Foo-over-UDP receive port configuration

ip-gue - Generic UDP Encapsulation receive port configuration

## SYNOPSIS

ip [ OPTIONS ] fou { COMMAND | help }

ip fou add port PORT { gue | ipproto PROTO } [ 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

## DESCRIPTION
The ip fou commands are used to create and delete receive ports for Foo-over-UDP (FOU) as well as Generic UDP Encapsulation (GUE).

Foo-over-UDP allows encapsulating packets of an IP protocol directly over UDP. The receiver infers the protocol of a packet received on a FOU UDP port to be the protocol configured for the port.

Generic UDP Encapsulation (GUE) encapsulates packets of an IP protocol within UDP and an encapsulation header. The encapsulation header contains the IP protocol number for the encapsulated packet.

When creating a FOU or GUE receive port, the port number is specified in PORT argument. If FOU is used, the IP protocol number associated with the port is specified in PROTO argument. You can bind a port to a local address/interface, by specifying the address in the local IFADDR argument or the device in the IFNAME argument. If you would like to connect the port, you can specify the peer address in the peer IFADDR argument and peer port in the peer_port PORT argument.

A FOU or GUE receive port is deleted by specifying PORT in the delete command, as well as local address/interface or peer address/port (if set).

## EXAMPLES

### Configure a FOU receive port for GRE bound to 7777

```
# ip fou add port 7777 ipproto 47
```

### Configure a FOU receive port for IPIP bound to 8888

```
# ip fou add port 8888 ipproto 4
```

### Configure a GUE receive port bound to 9999

```
# ip fou add port 9999 gue
```

### Delete the GUE receive port bound to 9999

```
# ip fou del port 9999
```

### Configure a FOU receive port for GRE bound to 1.2.3.4:7777

```
# ip fou add port 7777 ipproto 47 local 1.2.3.4
```

## SEE ALSO
ip(8)

## AUTHOR
Tom Herbert <therbert@google.com>


ip-ioam

title: ip-ioam(8)

summary: IPv6 In-situ OAM (IOAM)

text:
# ip-ioam(8)

## NAME
ip-ioam - IPv6 In-situ OAM (IOAM)

## SYNOPSIS

ip ioam { COMMAND | help }

ip ioam namespace show

ip ioam namespace add ID [ data DATA32 ] [ wide DATA64 ]

ip ioam namespace del ID

ip ioam schema show

ip ioam schema add ID DATA

ip ioam schema del ID

ip ioam namespace set ID schema { ID | none }

ip ioam monitor

## DESCRIPTION
The ip ioam command is used to configure IPv6 In-situ OAM (IOAM6) internal parameters, namely IOAM namespaces and schemas.

Those parameters also include the mapping between an IOAM namespace and an IOAM schema.

The ip ioam monitor command displays IOAM data received.

## EXAMPLES

### Configure an IOAM namespace (ID = 1) with both data (32 bits) and wide data (64 bits)

```
# ip ioam namespace add 1 data 0xdeadbeef wide 0xcafec0caf00dc0de
```

### Link an existing IOAM schema (ID = 7) to an existing IOAM namespace (ID = 1)

```
# ip ioam namespace set 1 schema 7
```

## SEE ALSO
ip-route(8)

## AUTHOR
Justin Iurman <justin.iurman@uliege.be>


title: ip-l2tp(8)

text:
# ip-l2tp(8)

## NAME
ip-l2tp - L2TPv3 static unmanaged tunnel configuration

## SYNOPSIS

ip [ OPTIONS ] l2tp { COMMAND | help }

ip l2tp add tunnel

remote ADDR local ADDR

tunnel_id ID peer_tunnel_id ID

[ encap { ip | udp } ]

[ udp_sport PORT ] [ udp_dport PORT ]

[ udp_csum { on | off } ]

[ udp6_csum_tx { on | off } ]

[ udp6_csum_rx { on | off } ]

ip l2tp add session [ name NAME ]

tunnel_id ID session_id ID peer_session_id ID

[ cookie HEXSTR ] [ peer_cookie HEXSTR ]

[ l2spec_type { none | default } ]

[ seq { none | send | recv | both } ]

ip l2tp del tunnel tunnel_id ID

ip l2tp del session tunnel_id ID session_id ID

ip l2tp show tunnel [ tunnel_id ID ]

ip l2tp show session [ tunnel_id ID.B ] [ session_id ID ]

NAME := STRING ADDR := { IP_ADDRESS | any } PORT := { NUMBER } ID := { NUMBER } HEXSTR := { 8 or 16 hex digits (4 / 8 bytes) }

## DESCRIPTION
The ip l2tp commands are used to establish static, or so-called unmanaged L2TPv3 ethernet tunnels. For unmanaged tunnels, there is no L2TP control protocol so no userspace daemon is required - tunnels are manually created by issuing commands at a local system and at a remote peer.

L2TPv3 is suitable for Layer-2 tunneling. Static tunnels are useful to establish network links across IP networks when the tunnels are fixed. L2TPv3 tunnels can carry data of more than one session. Each session is identified by a session_id and its parent tunnel's tunnel_id. A tunnel must be created before a session can be created in the tunnel.

When creating an L2TP tunnel, the IP address of the remote peer is specified, which can be either an IPv4 or IPv6 address. The local IP address to be used to reach the peer must also be specified. This is the address on which the local system will listen for and accept received L2TP data packets from the peer.

L2TPv3 defines two packet encapsulation formats: UDP or IP. UDP encapsulation is most common. IP encapsulation uses a dedicated IP protocol value to carry L2TP data without the overhead of UDP. Use IP encapsulation only when there are no NAT devices or firewalls in the network path.

When an L2TPv3 ethernet session is created, a virtual network interface is created for the session, which must then be configured and brought up, just like any other network interface. When data is passed through the interface, it is carried over the L2TP tunnel to the peer. By configuring the system's routing tables or adding the interface to a bridge, the L2TP interface is like a virtual wire (pseudowire) connected to the peer.

Establishing an unmanaged L2TPv3 ethernet pseudowire involves manually creating L2TP contexts on the local system and at the peer. Parameters used at each site must correspond or no data will be passed. No consistency checks are possible since there is no control protocol used to establish unmanaged L2TP tunnels. Once the virtual network interface of a given L2TP session is configured and enabled, data can be transmitted, even if the peer isn't yet configured. If the peer isn't configured, the L2TP data packets will be discarded by the peer.

To establish an unmanaged L2TP tunnel, use l2tp add tunnel and l2tp add session commands described in this document. Then configure and enable the tunnel's virtual network interface, as required.

Note that unmanaged tunnels carry only ethernet frames. If you need to carry PPP traffic (L2TPv2) or your peer doesn't support unmanaged L2TPv3 tunnels, you will need an L2TP server which implements the L2TP control protocol. The L2TP control protocol allows dynamic L2TP tunnels and sessions to be established and provides for detecting and acting upon network failures.

### ip l2tp add tunnel - add a new tunnel
tunnel_id ID

set the tunnel id, which is a 32-bit integer value. Uniquely identifies the tunnel. The value used must match the peer_tunnel_id value being used at the peer.

peer_tunnel_id ID

set the peer tunnel id, which is a 32-bit integer value assigned to the tunnel by the peer. The value used must match the tunnel_id value being used at the peer.

remote ADDR

set the IP address of the remote peer. May be specified as an IPv4 address or an IPv6 address.

local ADDR

set the IP address of the local interface to be used for the tunnel. This address must be the address of a local interface. May be specified as an IPv4 address or an IPv6 address.

encap ENCAP

set the encapsulation type of the tunnel.

Valid values for encapsulation are: udp, ip.

udp_sport PORT

set the UDP source port to be used for the tunnel. Must be present when udp encapsulation is selected. Ignored when ip encapsulation is selected.

udp_dport PORT

set the UDP destination port to be used for the tunnel. Must be present when udp encapsulation is selected. Ignored when ip encapsulation is selected.

udp_csum STATE

(IPv4 only) control if IPv4 UDP checksums should be calculated and checked for the encapsulating UDP packets, when UDP encapsulating is selected. Default is off.

Valid values are: on, off.

udp6_csum_tx STATE

(IPv6 only) control if IPv6 UDP checksums should be calculated for encapsulating UDP packets, when UDP encapsulating is selected. Default is on.

Valid values are: on, off.

udp6_csum_rx STATE

(IPv6 only) control if IPv6 UDP checksums should be checked for the encapsulating UDP packets, when UDP encapsulating is selected. Default is on.

Valid values are: on, off.

### ip l2tp del tunnel - destroy a tunnel
tunnel_id ID

set the tunnel id of the tunnel to be deleted. All sessions within the tunnel must be deleted first.

### ip l2tp show tunnel - show information about tunnels
tunnel_id ID

set the tunnel id of the tunnel to be shown. If not specified, information about all tunnels is printed.

### ip l2tp add session - add a new session to a tunnel
name NAME

sets the session network interface name. Default is l2tpethN.

tunnel_id ID

set the tunnel id, which is a 32-bit integer value. Uniquely identifies the tunnel into which the session will be created. The tunnel must already exist.

session_id ID

set the session id, which is a 32-bit integer value. Uniquely identifies the session being created. The value used must match the peer_session_id value being used at the peer.

peer_session_id ID

set the peer session id, which is a 32-bit integer value assigned to the session by the peer. The value used must match the session_id value being used at the peer.

cookie HEXSTR

sets an optional cookie value to be assigned to the session. This is a 4 or 8 byte value, specified as 8 or 16 hex digits, e.g. 014d3636deadbeef. The value must match the peer_cookie value set at the peer. The cookie value is carried in L2TP data packets and is checked for expected value at the peer. Default is to use no cookie.

peer_cookie HEXSTR

sets an optional peer cookie value to be assigned to the session. This is a 4 or 8 byte value, specified as 8 or 16 hex digits, e.g. 014d3636deadbeef. The value must match the cookie value set at the peer. It tells the local system what cookie value to expect to find in received L2TP packets. Default is to use no cookie.

l2spec_type L2SPECTYPE

set the layer2specific header type of the session.

Valid values are: none, default.

seq SEQ

controls sequence numbering to prevent or detect out of order packets. send puts a sequence number in the default layer2specific header of each outgoing packet. recv reorder packets if they are received out of order. Default is none.

Valid values are: none, send, recv, both.

### ip l2tp del session - destroy a session
tunnel_id ID

set the tunnel id in which the session to be deleted is located.

session_id ID

set the session id of the session to be deleted.

### ip l2tp show session - show information about sessions
tunnel_id ID

set the tunnel id of the session(s) to be shown. If not specified, information about sessions in all tunnels is printed.

session_id ID

set the session id of the session to be shown. If not specified, information about all sessions is printed.

## EXAMPLES

### Setup L2TP tunnels and sessions

```
site-A:# ip l2tp add tunnel tunnel_id 3000 peer_tunnel_id 4000 \

           encap udp local 1.2.3.4 remote 5.6.7.8 \

           udp_sport 5000 udp_dport 6000
site-A:# ip l2tp add session tunnel_id 3000 session_id 1000 \

           peer_session_id 2000
site-B:# ip l2tp add tunnel tunnel_id 4000 peer_tunnel_id 3000 \

           encap udp local 5.6.7.8 remote 1.2.3.4 \

           udp_sport 6000 udp_dport 5000
site-B:# ip l2tp add session tunnel_id 4000 session_id 2000 \

           peer_session_id 1000
site-A:# ip link set l2tpeth0 up mtu 1488
site-B:# ip link set l2tpeth0 up mtu 1488
```

Notice that the IP addresses, UDP ports and tunnel / session ids are matched and reversed at each site.

### Configure as IP interfaces
The two interfaces can be configured with IP addresses if only IP data is to be carried. This is perhaps the simplest configuration.

```
site-A:# ip addr add 10.42.1.1 peer 10.42.1.2 dev l2tpeth0
site-B:# ip addr add 10.42.1.2 peer 10.42.1.1 dev l2tpeth0
site-A:# ping 10.42.1.2
```

Now the link should be usable. Add static routes as needed to have data sent over the new link.

### Configure as bridged interfaces
To carry non-IP data, the L2TP network interface is added to a bridge instead of being assigned its own IP address, using standard Linux utilities. Since raw ethernet frames are then carried inside the tunnel, the MTU of the L2TP interfaces must be set to allow space for those headers.

```
site-A:# ip link set l2tpeth0 up mtu 1446
site-A:# ip link add br0 type bridge
site-A:# ip link set l2tpeth0 master br0
site-A:# ip link set eth0 master br0
site-A:# ip link set br0 up
```

If you are using VLANs, setup a bridge per VLAN and bridge each VLAN over a separate L2TP session. For example, to bridge VLAN ID 5 on eth1 over an L2TP pseudowire:

```
site-A:# ip link set l2tpeth0 up mtu 1446
site-A:# ip link add brvlan5 type bridge
site-A:# ip link set l2tpeth0.5 master brvlan5
site-A:# ip link set eth1.5 master brvlan5
site-A:# ip link set brvlan5 up
```

Adding the L2TP interface to a bridge causes the bridge to forward traffic over the L2TP pseudowire just like it forwards over any other interface. The bridge learns MAC addresses of hosts attached to each interface and intelligently forwards frames from one bridge port to another. IP addresses are not assigned to the l2tpethN interfaces. If the bridge is correctly configured at both sides of the L2TP pseudowire, it should be possible to reach hosts in the peer's bridged network.

When raw ethernet frames are bridged across an L2TP tunnel, large frames may be fragmented and forwarded as individual IP fragments to the recipient, depending on the MTU of the physical interface used by the tunnel. When the ethernet frames carry protocols which are reassembled by the recipient, like IP, this isn't a problem. However, such fragmentation can cause problems for protocols like PPPoE where the recipient expects to receive ethernet frames exactly as transmitted. In such cases, it is important that frames leaving the tunnel are reassembled back into a single frame before being forwarded on. To do so, enable netfilter connection tracking (conntrack) or manually load the Linux netfilter defrag modules at each tunnel endpoint.

```
site-A:# modprobe nf_defrag_ipv4
site-B:# modprobe nf_defrag_ipv4
```

If L2TP is being used over IPv6, use the IPv6 defrag module.

## INTEROPERABILITY
Unmanaged (static) L2TPv3 tunnels are supported by some network equipment vendors such as Cisco.

In Linux, L2TP Hello messages are not supported in unmanaged tunnels. Hello messages are used by L2TP clients and servers to detect link failures in order to automate tearing down and reestablishing dynamic tunnels. If a non-Linux peer supports Hello messages in unmanaged tunnels, it must be turned off to interoperate with Linux.

Linux defaults to use the Default Layer2SpecificHeader type as defined in the L2TPv3 protocol specification, RFC3931. This setting must be consistent with that configured at the peer. Some vendor implementations (e.g. Cisco) default to use a Layer2SpecificHeader type of None.

## SEE ALSO
ip(8)

## AUTHOR
James Chapman <jchapman@katalix.com>