title: tc-tunnel_key(8)

text:
# tc-tunnel_key(8)

## NAME
tunnel_key - Tunnel metadata manipulation

## SYNOPSIS

tc ... action tunnel_key { unset | SET }

SET := set src_ip ADDRESS dst_ip ADDRESS id KEY_ID dst_port UDP_PORT tos TOS ttl TTL [ csum | nocsum ]

## DESCRIPTION
The tunnel_key action combined with a shared IP tunnel device, allows one to perform IP tunnel en- or decapsulation on a packet, reflected by the operation modes UNSET and SET. The UNSET mode is optional - even without using it, the metadata information will be released automatically when packet processing will be finished. UNSET function could be used in cases when traffic is forwarded between two tunnels, where the metadata from the first tunnel will be used for encapsulation done by the second tunnel. SET mode requires the source and destination ip ADDRESS and the tunnel key id KEY_ID which will be used by the ip tunnel shared device to create the tunnel header. The tunnel_key action is useful only in combination with a mirred redirect action to a shared IP tunnel device which will use the metadata (for SET ) and unset the metadata created by it (for UNSET ).

## OPTIONS
unset

Unset the tunnel metadata created by the IP tunnel device. This function is not mandatory and might be used only in some specific use cases (as explained above).

set

Set tunnel metadata to be used by the IP tunnel device. Requires src_ip and dst_ip options. id , dst_port , geneve_opts , vxlan_opts and erspan_opts are optional.

id

Tunnel ID (for example VNI in VXLAN tunnel)

src_ip

Outer header source IP address (IPv4 or IPv6)

dst_ip

Outer header destination IP address (IPv4 or IPv6)

dst_port

Outer header destination UDP port

geneve_opts

Geneve variable length options. geneve_opts is specified in the form CLASS:TYPE:DATA, where CLASS is represented as a 16bit hexadecimal value, TYPE as an 8bit hexadecimal value and DATA as a variable length hexadecimal value. Additionally multiple options may be listed using a comma delimiter.

vxlan_opts

Vxlan metadata options. vxlan_opts is specified in the form GBP, as a 32bit number. Multiple options is not supported.

erspan_opts

Erspan metadata options. erspan_opts is specified in the form VERSION:INDEX:DIR:HWID, where VERSION is represented as a 8bit number, INDEX as an 32bit number, DIR and HWID as a 8bit number. Multiple options is not supported. Note INDEX is used when VERSION is 1, and DIR and HWID are used when VERSION is 2.

tos

Outer header TOS

ttl

Outer header TTL

[no]csum

Controls outer UDP checksum. When set to csum (which is default), the outer UDP checksum is calculated and included in the packets. When set to nocsum, outer UDP checksum is zero. Note that when using zero UDP checksums with IPv6, the other tunnel endpoint must be configured to accept such packets. In Linux, this would be the udp6zerocsumrx option for the VXLAN tunnel interface.

If using nocsum with IPv6, be sure you know what you are doing. Zero UDP checksums provide weaker protection against corrupted packets. See RFC6935 for details.

nofrag

disallow IP fragmentation.

## EXAMPLES
The following example encapsulates incoming ICMP packets on eth0 into a vxlan tunnel, by setting metadata to VNI 11, source IP 11.11.0.1 and destination IP 11.11.0.2, and by redirecting the packet with the metadata to device vxlan0, which will do the actual encapsulation using the metadata:

```
#tc qdisc add dev eth0 handle ffff: ingress
#tc filter add dev eth0 protocol ip parent ffff: \

  flower \

    ip_proto icmp \

  action tunnel_key set \

    src_ip 11.11.0.1 \

    dst_ip 11.11.0.2 \

    id 11 \

  action mirred egress redirect dev vxlan0
```

Here is an example of the unset function: Incoming VXLAN traffic with outer IP's and VNI 11 is decapsulated by vxlan0 and metadata is unset before redirecting to tunl1 device:

```
#tc qdisc add dev eth0 handle ffff: ingress
#tc filter add dev vxlan0 protocol ip parent ffff:   flower \
	  enc_src_ip 11.11.0.2 enc_dst_ip 11.11.0.1 enc_key_id 11 	action tunnel_key unset 	action mirred egress redirect dev tunl1
```

## SEE ALSO
tc(8)


title: tc-u32(8)

summary: universal 32bit traffic control filter

text:
# tc-u32(8)

## NAME
u32 - universal 32bit traffic control filter

## SYNOPSIS

tc filter ... [ handle HANDLE ] u32 OPTION_LIST [ offset OFFSET ] [ hashkey HASHKEY ] [ classid CLASSID ] [ divisor uint_value ] [ order u32_value ] [ ht HANDLE ] [ sample SELECTOR [ divisor uint_value ] ] [ link HANDLE ] [ indev ifname ] [ skip_hw | skip_sw ] [ help ]

HANDLE := { u12_hex_htid:[u8_hex_hash:[u12_hex_nodeid] | 0xu32_hex_value }

OPTION_LIST := [ OPTION_LIST ] OPTION

HASHKEY := [ mask u32_hex_value ] [ at 4*int_value ]

CLASSID := { root | none | [u16_major]:u16_minor | u32_hex_value }

OFFSET := [ plus int_value ] [ at 2*int_value ] [ mask u16_hex_value ] [ shift int_value ] [ eat ]

OPTION := { match SELECTOR | action ACTION }

SELECTOR := { u32 VAL_MASK_32 | u16 VAL_MASK_16 | u8 VAL_MASK_8 | ip IP | ip6 IP6 | { tcp | udp } TCPUDP | icmp ICMP | mark VAL_MASK_32 | ether ETHER }

IP := { { src | dst } { default | any | all | ip_address [ / { prefixlen | netmask } ] } AT | { dsfield | ihl | protocol | precedence | icmp_type | icmp_code } VAL_MASK_8 | { sport | dport } VAL_MASK_16 | nofrag | firstfrag | df | mf }

IP6 := { { src | dst } { default | any | all | ip6_address [/prefixlen ] } AT | priority VAL_MASK_8 | { protocol | icmp_type | icmp_code } VAL_MASK_8 | flowlabel VAL_MASK_32 | { sport | dport } VAL_MASK_16 }

TCPUDP := { src | dst } VAL_MASK_16

ICMP := { type VAL_MASK_8 | code VAL_MASK_8 }

ETHER := { src | dst } ether_address AT

VAL_MASK_32 := u32_value u32_hex_mask [ AT ]

VAL_MASK_16 := u16_value u16_hex_mask [ AT ]

VAL_MASK_8 := u8_value u8_hex_mask [ AT ]

AT := [ at [ nexthdr+ ] int_value ]

## DESCRIPTION
The Universal/Ugly 32bit filter allows one to match arbitrary bitfields in the packet. Due to breaking everything down to values, masks and offsets, It is equally powerful and hard to use. Luckily many abstracting directives are present which allow defining rules on a higher level and therefore free the user from having to fiddle with bits and masks in many cases.

There are two general modes of invocation: The first mode creates a new filter to delegate packets to different destinations. Apart from the obvious ones, namely classifying the packet by specifying a CLASSID or calling an action, one may link one filter to another one (or even a list of them), effectively organizing filters into a tree-like hierarchy.

Typically filter delegation is done by means of a hash table, which leads to the second mode of invocation: it merely serves to set up these hash tables. Filters can select a hash table and provide a key selector from which a hash is to be computed and used as key to lookup the table's bucket which contains filters for further processing. This is useful if a high number of filters is in use, as the overhead of performing the hash operation and table lookup becomes negligible in that case. Using hashtables with u32 basically involves the following pattern:

(1)

Creating a new hash table, specifying it's size using the divisor parameter and ideally a handle by which the table can be identified. If the latter is not given, the kernel chooses one on it's own, which has to be guessed later.

(2)

Creating filters which link to the created table in (1) using the link parameter and defining the packet data which the kernel will use to calculate the hashkey.

(3)

Adding filters to buckets in the hash table from (1). In order to avoid having to know how exactly the kernel creates the hash key, there is the sample parameter, which gives sample data to hash and thereby define the table bucket the filter should be added to.

In fact, even if not explicitly requested u32 creates a hash table for every priority a filter is being added with. The table's size is 1 though, so it is in fact merely a linked list.

## VALUES
Options and selectors require values to be specified in a specific format, which is often non-intuitive. Therefore the terminals in SYNOPSIS have been given descriptive names to indicate the required format and/or maximum allowed numeric value: Prefixes u32, u16 and u8 indicate four, two and single byte unsigned values. E.g. u16 indicates a two byte-sized value in range between 0 and 65535 (0xFFFF) inclusive. A prefix of int indicates a four byte signed value. A middle part of _hex_ indicates that the value is parsed in hexadecimal format. Otherwise, the value's base is automatically detected, i.e. values prefixed with 0x are considered hexadecimal, a leading 0 indicates octal format and decimal format otherwise. There are some values with special formatting as well: ip_address and netmask are in dotted-quad formatting as usual for IPv4 addresses. An ip6_address is specified in common, colon-separated hexadecimal format. Finally, prefixlen is an unsigned, decimal integer value in range from 0 to the address width in bits (32 for IPv4 and 128 for IPv6).

Sometimes values need to be dividable by a certain number. In that case a name of the form N*val was chosen, indicating that val must be dividable by N. Or the other way around: the resulting value must be a multiple of N.

## OPTIONS
U32 recognizes the following options:

handle HANDLE

The handle is used to reference a filter and therefore must be unique. It consists of a hash table identifier htid and optional hash (which identifies the hash table's bucket) and nodeid. All these values are parsed as unsigned, hexadecimal numbers with length 12bits ( htid and nodeid) or 8bits ( hash). Alternatively one may specify a single, 32bit long hex number which contains the three fields bits in concatenated form. Other than the fields themselves, it has to be prefixed by 0x.

offset OFFSET

Set an offset which defines where matches of subsequent filters are applied to. Therefore this option is useful only when combined with link or a combination of ht and sample. The offset may be given explicitly by using the plus keyword, or extracted from the packet data with at. It is possible to mangle the latter using mask and/or shift keywords. By default, this offset is recorded but not implicitly applied. It is used only to substitute the nexthdr+ statement. Using the keyword eat though inverses this behaviour: the offset is applied always, and nexthdr+ will fall back to zero.

hashkey HASHKEY

Specify what packet data to use to calculate a hash key for bucket lookup. The kernel adjusts the value according to the hash table's size. For this to work, the option link must be given.

classid CLASSID

Classify matching packets into the given CLASSID, which consists of either 16bit major and minor numbers or a single 32bit value combining both.

divisor u32_value

Specify a modulo value. Used when creating hash tables to define their size or for declaring a sample to calculate hash table keys from. Must be a power of two with exponent not exceeding eight.

order u32_value

A value to order filters by, ascending. Conflicts with handle which serves the same purpose.

sample SELECTOR

Used together with ht to specify which bucket to add this filter to. This allows one to avoid having to know how exactly the kernel calculates hashes. The additional divisor defaults to 256, so must be given for hash tables of different size.

link HANDLE

Delegate matching packets to filters in a hash table. HANDLE is used to only specify the hash table, so only htid may be given, hash and nodeid have to be omitted. By default, bucket number 0 will be used and can be overridden by the hashkey option.

indev ifname

Filter on the incoming interface of the packet. Obviously works only for forwarded traffic.

skip_sw

Do not process filter by software. If hardware has no offload support for this filter, or TC offload is not enabled for the interface, operation will fail.

skip_hw

Do not process filter by hardware.

help

Print a brief help text about possible options.

## SELECTORS
Basically the only real selector is u32 . All others merely provide a higher level syntax and are internally translated into u32 .

u32 VAL_MASK_32

u16 VAL_MASK_16

u8 VAL_MASK_8

Match packet data to a given value. The selector name defines the sample length to extract (32bits for u32, 16bits for u16 and 8bits for u8). Before comparing, the sample is binary AND'ed with the given mask. This way uninteresting bits can be cleared before comparison. The position of the sample is defined by the offset specified in AT.

ip IP

ip6 IP6

Assume packet starts with an IPv4 ( ip) or IPv6 ( ip6) header. IP/IP6 then allows one to match various header fields:

src ADDR

dst ADDR

Compare Source or Destination Address fields against the value of ADDR. The reserved words default, any and all effectively match any address. Otherwise an IP address of the particular protocol is expected, optionally suffixed by a prefix length to match whole subnets. In case of IPv4 a netmask may also be given.

dsfield VAL_MASK_8

IPv4 only. Match the packet header's DSCP/ECN field. Synonyms to this are tos and precedence.

ihl VAL_MASK_8

IPv4 only. Match the Internet Header Length field. Note that the value's unit is 32bits, so to match a packet with 24byte header length u8_value has to be 6.

protocol VAL_MASK_8

Match the Protocol (IPv4) or Next Header (IPv6) field value, e.g. 6 for TCP.

icmp_type VAL_MASK_8

icmp_code VAL_MASK_8

Assume a next-header protocol of icmp or ipv6-icmp and match Type or Code field values. This is dangerous, as the code assumes minimal header size for IPv4 and lack of extension headers for IPv6.

sport VAL_MASK_16

dport VAL_MASK_16

Match layer four source or destination ports. This is dangerous as well, as it assumes a suitable layer four protocol is present (which has Source and Destination Port fields right at the start of the header and 16bit in size). Also minimal header size for IPv4 and lack of IPv6 extension headers is assumed.

nofrag

firstfrag

df

mf

IPv4 only, check certain flags and fragment offset values. Match if the packet is not a fragment (nofrag), the first fragment of a fragmented packet (firstfrag), if Don't Fragment (df) or More Fragments (mf) bits are set.

priority VAL_MASK_8

IPv6 only. Match the header's Traffic Class field, which has the same purpose and semantics of IPv4's ToS field since RFC 3168: upper six bits are DSCP, the lower two ECN.

flowlabel VAL_MASK_32

IPv6 only. Match the Flow Label field's value. Note that Flow Label itself is only 20bytes long, which are the least significant ones here. The remaining upper 12bytes match Version and Traffic Class fields.

tcp TCPUDP

udp TCPUDP

Match fields of next header of protocol TCP or UDP. The possible values for TCPDUP are:

src VAL_MASK_16

Match on Source Port field value.

dst VALMASK_16

Match on Destination Port field value.

icmp ICMP

Match fields of next header of protocol ICMP. The possible values for ICMP are:

type VAL_MASK_8

Match on ICMP Type field.

code VAL_MASK_8

Match on ICMP Code field.

mark VAL_MASK_32

Match on netfilter fwmark value.

ether ETHER

Match on ethernet header fields. Possible values for ETHER are:

src ether_address AT

dst ether_address AT

Match on source or destination ethernet address. This is dangerous: It assumes an ethernet header is present at the start of the packet. This will probably lead to unexpected things if used with layer three interfaces like e.g. tun or ppp.

## EXAMPLES

```
tc filter add dev eth0 parent 999:0 prio 99 protocol ip u32 \

        match ip src 192.168.8.0/24 classid 1:1
```

This attaches a filter to the qdisc identified by 999:0. It's priority is 99, which affects in which order multiple filters attached to the same parent are consulted (the lower the earlier). The filter handles packets of protocol type ip, and matches if the IP header's source address is within the 192.168.8.0/24 subnet. Matching packets are classified into class 1.1. The effect of this command might be surprising at first glance:

```
filter parent 1: protocol ip pref 99 u32
filter parent 1: protocol ip pref 99 u32 \

        fh 800: ht divisor 1
filter parent 1: protocol ip pref 99 u32 \

        fh 800::800 order 2048 key ht 800 bkt 0 flowid 1:1 \

        match c0a80800/ffffff00 at 12
```

So parent 1: is assigned a new u32 filter, which contains a hash table of size 1 (as the divisor indicates). The table ID is 800. The third line then shows the actual filter which was added above: it sits in table 800 and bucket 0, classifies packets into class ID 1:1 and matches the upper three bytes of the four byte value at offset 12 to be 0xc0a808, which is 192, 168 and 8.

Now for something more complicated, namely creating a custom hash table:

```
tc filter add dev eth0 prio 99 handle 1: u32 divisor 256
```

This creates a table of size 256 with handle 1: in priority 99. The effect is as follows:

```
filter parent 1: protocol all pref 99 u32
filter parent 1: protocol all pref 99 u32 fh 1: ht divisor 256
filter parent 1: protocol all pref 99 u32 fh 800: ht divisor 1
```

So along with the requested hash table (handle 1:), the kernel has created his own table of size 1 to hold other filters of the same priority.

The next step is to create a filter which links to the created hash table:

```
tc filter add dev eth0 parent 1: prio 1 u32 \

        link 1: hashkey mask 0x0000ff00 at 12 \

        match ip src 192.168.0.0/16
```

The filter is given a lower priority than the hash table itself so u32 consults it before manually traversing the hash table. The options link and hashkey determine which table and bucket to redirect to. In this case the hash key should be constructed out of the second byte at offset 12, which corresponds to an IP packet's third byte of the source address field. Along with the match statement, this effectively maps all class C networks below 192.168.0.0/16 to different buckets of the hash table.

Filters for certain subnets can be created like so:

```
tc filter add dev eth0 parent 1: prio 99 u32 \

        ht 1: sample u32 0x00000800 0x0000ff00 at 12 \

        match ip src 192.168.8.0/24 classid 1:1
```

The bucket is defined using the sample option: In this case, the second byte at offset 12 must be 0x08, exactly. In this case, the resulting bucket ID is obviously 8, but as soon as sample selects an amount of data which could exceed the divisor, one would have to know the kernel-internal algorithm to deduce the destination bucket. This filter's match statement is redundant in this case, as the entropy for the hash key does not exceed the table size and therefore no collisions can occur. Otherwise it's necessary to prevent matching unwanted packets.

Matching upper layer fields is problematic since IPv4 header length is variable and IPv6 supports extension headers which affect upper layer header offset. To overcome this, there is the possibility to specify nexthdr+ when giving an offset, and to make things easier there are the tcp and udp matches which use nexthdr+ implicitly. This offset has to be calculated in beforehand though, and the only way to achieve that is by doing it in a separate filter which then links to the filter which wants to use it. Here is an example of doing so:

```
tc filter add dev eth0 parent 1:0 protocol ip handle 1: \

        u32 divisor 1
tc filter add dev eth0 parent 1:0 protocol ip \

        u32 ht 1: \

        match tcp src 22 FFFF \

        classid 1:2
tc filter add dev eth0 parent 1:0 protocol ip \

        u32 ht 800: \

        match ip protocol 6 FF \

        match u16 0 1fff at 6 \

        offset at 0 mask 0f00 shift 6 \

        link 1:
```

This is what is being done: In the first call, a single element sized hash table is created so there is a place to hold the linked to filter and a known handle (1:) to reference to it. The second call then adds the actual filter, which pushes packets with TCP source port 22 into class 1:2. Using ht, it is moved into the hash table created by the first call. The third call then does the actual magic: It matches IPv4 packets with next layer protocol 6 (TCP), only if it's the first fragment (usually TCP sets DF bit, but if it doesn't and the packet is fragmented, only the first one contains the TCP header), and then sets the offset based on the IP header's IHL field (right-shifting by 6 eliminates the offset of the field and at the same time converts the value into byte unit). Finally, using link, the hash table from first call is referenced which holds the filter from second call.

## SEE ALSO
tc(8),

cls_u32.txt at http://linux-tc-notes.sourceforge.net/


tc-vlan

title: tc-vlan(8)

text:
# tc-vlan(8)

## NAME
vlan - vlan manipulation module

## SYNOPSIS

tc ... action vlan { pop | pop_eth | PUSH | MODIFY | PUSH_ETH } [ CONTROL ]

PUSH := push [ protocol VLANPROTO ] [ priority VLANPRIO ] id VLANID

MODIFY := modify [ protocol VLANPROTO ] [ priority VLANPRIO ] id VLANID

PUSH_ETH := push_eth dst_mac LLADDR src_mac LLADDR

CONTROL := { reclassify | pipe | drop | continue | pass | goto chain CHAIN_INDEX }

## DESCRIPTION
The vlan action allows one to perform 802.1Q en- or decapsulation on a packet, reflected by the operation modes POP, PUSH and MODIFY. The POP mode is simple, as no further information is required to just drop the outer-most VLAN encapsulation. The PUSH and MODIFY modes require at least a VLANID and allow one to optionally choose the VLANPROTO to use.

The vlan action can also be used to add or remove the base Ethernet header. The pop_eth mode, which takes no argument, is used to remove the base Ethernet header. All existing VLANs must have been previously dropped. The opposite operation, adding a base Ethernet header, is done with the push_eth mode. In that case, the packet must have no MAC header (stacking MAC headers is not permitted). This mode is mostly useful when a previous action has encapsulated the whole original frame behind a network header and one needs to prepend an Ethernet header before forwarding the resulting packet.

## OPTIONS
pop

Decapsulation mode, no further arguments allowed.

push

Encapsulation mode. Requires at least id option.

modify

Replace mode. Existing 802.1Q tag is replaced. Requires at least id option.

pop_eth

Ethernet header decapsulation mode. Only works on a plain Ethernet header: VLANs, if any, must be removed first.

push_eth

Ethernet header encapsulation mode. The Ethertype is automatically set using the network header type. Chaining Ethernet headers is not allowed: the packet must have no MAC header when using this mode. Requires the dst_mac and src_mac options.

id VLANID

Specify the VLAN ID to encapsulate into. VLANID is an unsigned 16bit integer, the format is detected automatically (e.g. prefix with '0x' for hexadecimal interpretation, etc.).

protocol VLANPROTO

Choose the VLAN protocol to use. At the time of writing, the kernel accepts only 802.1Q or 802.1ad.

priority VLANPRIO

Choose the VLAN priority to use. Decimal number in range of 0-7.

dst_mac LLADDR

Choose the destination MAC address to use.

src_mac LLADDR

Choose the source MAC address to use.

CONTROL

How to continue after executing this action.

reclassify

Restarts classification by jumping back to the first filter attached to this action's parent.

pipe

Continue with the next action, this is the default.

drop

Packet will be dropped without running further actions.

continue

Continue classification with next filter in line.

pass

Return to calling qdisc for packet processing. This ends the classification process.

## EXAMPLES
The following example encapsulates incoming ICMP packets on eth0 from 10.0.0.2 into VLAN ID 123:

```
#tc qdisc add dev eth0 handle ffff: ingress
#tc filter add dev eth0 parent ffff: pref 11 protocol ip \
	u32 match ip protocol 1 0xff flowid 1:1 \
	    match ip src 10.0.0.2 flowid 1:1 \
	action vlan push id 123
```

Here is an example of the pop function: Incoming VLAN packets on eth0 are decapsulated and the classification process then restarted for the plain packet:

```
#tc qdisc add dev eth0 handle ffff: ingress
#tc filter add dev $ETH parent ffff: pref 1 protocol 802.1Q \
	u32 match u32 0 0 flowid 1:1 \
	action vlan pop reclassify
```

For an example of the pop_eth and push_eth modes, see tc-mpls(8).

## SEE ALSO
tc(8), tc-mpls(8)


tipc

title: tipc(8)

text:
# tipc(8)

## NAME
tipc - a TIPC configuration and management tool

## SYNOPSIS

tipc [ OPTIONS ] COMMAND ARGUMENTS

COMMAND := { bearer | link | media | nametable | node | socket }

OPTIONS := { -h[help] }

## DESCRIPTION
The Transparent Inter-Process Communication (TIPC) protocol offers total address transparency between processes which allows applications in a clustered computer environment to communicate quickly and reliably with each other, regardless of their location within the cluster.

TIPC originated at the telecommunications manufacturer Ericsson. The first open source version of TIPC was created in 2000 when Ericsson released its first Linux version of TIPC. TIPC was introduced in the mainline Linux kernel in 2006 and is now widely used both within and outside of Ericsson.

## OPTIONS
-h, --help

Show help about last given command. For example tipc bearer --help will show bearer help and tipc --help will show general help. The position of the option in the string is irrelevant.

-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.

## COMMANDS
BEARER

- Show or modify TIPC bearers

LINK

- Show or modify TIPC links

MEDIA

- Show or modify TIPC media

NAMETABLE

- Show TIPC nametable

NODE

- Show or modify TIPC node parameters

SOCKET

- Show TIPC sockets

## ARGUMENTS
Command arguments are described in a command specific man page and typically consists of nested commands along with key value pairs. If no arguments are given a command typically shows its help text. The explicit help option -h or --help can occur anywhere among the arguments and will show help for the last valid command given.

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

## SEE ALSO
tipc-bearer(8), tipc-link(8), tipc-media(8), tipc-nametable(8), tipc-node(8), tipc-peer(8), tipc-socket(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
Richard Alpe <richard.alpe@ericsson.com>


tipc-bearer

title: tipc-bearer(8)

summary: show or modify TIPC bearers

text:
# tipc-bearer(8)

## NAME
tipc-bearer - show or modify TIPC bearers

## SYNOPSIS

tipc bearer add media udp name NAME remoteip REMOTEIP

tipc bearer enable [ domain DOMAIN ] [ priority PRIORITY ] media

{ { eth | ib } device DEVICE } |

{ udp name NAME localip LOCALIP [ localport LOCALPORT ] [ remoteip REMOTEIP ] [ remoteport REMOTEPORT ] }

tipc bearer disable media

{ { eth | ib } device DEVICE } |

{ udp name NAME }

tipc bearer set { priority PRIORITY | tolerance TOLERANCE | window WINDOW } media

{ { eth | ib } device DEVICE } |

{ udp name NAME }

tipc bearer get [ priority | tolerance | window ] media

{ { eth | ib } device DEVICE } |

{ udp name NAME [ localip | localport | remoteip | remoteport ] }

tipc bearer list

## OPTIONS
Options (flags) that can be passed anywhere in the command chain.

-h, --help

Show help about last valid command. For example tipc bearer --help will show bearer help and tipc --help will show general help. The position of the option in the string is irrelevant.

## DESCRIPTION

### Bearer identification
media MEDIA

Specifies the TIPC media type for a particular bearer to operate on. Different media types have different ways of identifying a unique bearer. For example, ib and eth identify a bearer with a DEVICE while udp identify a bearer with a LOCALIP and a NAME ib - Infiniband

eth - Ethernet

udp - User Datagram Protocol (UDP)

name NAME

Logical bearer identifier valid for bearers on udp media.

device DEVICE

Physical bearer device valid for bearers on eth and ib media.

### Bearer properties
domain

The addressing domain (region) in which a bearer will establish links and accept link establish requests.

priority

Default link priority inherited by all links subsequently established over a bearer. A single bearer can only host one link to a particular node. This means the default link priority for a bearer typically affects which bearer to use when communicating with a particular node in an multi bearer setup. For more info about link priority see tipc-link(8)

tolerance

Default link tolerance inherited by all links subsequently established over a bearer. For more info about link tolerance see tipc-link(8)

window

Default link window inherited by all links subsequently established over a bearer. For more info about the link window size see tipc-link(8)

### UDP bearer options
localip LOCALIP

Specify a local IP v4/v6 address for a udp bearer.

localport LOCALPORT

Specify the local port for a udp bearer. The default port 6118 is used if no port is specified.

remoteip REMOTEIP

Specify a remote IP for a udp bearer. If no remote IP is specified a udp bearer runs in multicast mode and tries to auto-discover its neighbours. The multicast IP address is generated based on the TIPC network ID. If a remote IP is specified the udp bearer runs in point-to-point mode. Multiple remoteip addresses can be added via the bearer add command. Adding one or more unicast remoteip addresses to an existing udp bearer puts the bearer in replicast mode where IP multicast is emulated by sending multiple unicast messages to each configured remoteip. When a peer sees a TIPC discovery message from an unknown peer the peer address is automatically added to the remoteip (replicast) list, thus only one side of a link needs to be manually configured. A remoteip address cannot be added to a multicast bearer.

remoteport REMOTEPORT

Specify the remote port for a udp bearer. The default port 6118 is used if no port is specified.

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

## SEE ALSO
tipc(8), tipc-link(8), tipc-media(8), tipc-nametable(8), tipc-node(8), tipc-peer(8), tipc-socket(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
Richard Alpe <richard.alpe@ericsson.com>


tipc-link

title: tipc-link(8)

summary: show links or modify link properties

text:
# tipc-link(8)

## NAME
tipc-link - show links or modify link properties

## SYNOPSIS

tipc link set

[ { priority PRIORITY | tolerance TOLERANCE | window WINDOW } link LINK ] |

[ { broadcast [ BROADCAST | REPLICAST | AUTOSELECT [ ratio SIZE ] ] } ]

tipc link get

[ { priority | tolerance | window } link LINK ] |

[ { broadcast } ]

tipc link statistics { show [ link LINK ] | reset link LINK }

tipc link list

tipc link monitor set { threshold }

tipc link monitor get { threshold }

tipc link monitor summary

tipc link monitor list

[ media { eth | ib } device DEVICE ] |

[ media udp name NAME ]

## OPTIONS
Options (flags) that can be passed anywhere in the command chain.

-h, --help

Show help about last valid command. For example tipc link --help will show link help and tipc --help will show general help. The position of the option in the string is irrelevant.

-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.

## DESCRIPTION

### Link statistics
ACTIVE link state

An ACTIVE link is serving traffic. Two links to the same node can become ACTIVE if they have the same link priority. If there is more than two links with the same priority the additional links will be put in STANDBY state.

STANDBY link state

A STANDBY link has lower link priority than an ACTIVE link. A STANDBY link has control traffic flowing and is ready to take over should the ACTIVE link(s) go down.

MTU

The Maximum Transmission Unit. The two endpoints advertise their default or configured MTU at initial link setup and will agree to use the lower of the two values should they differ.

Packets

The total amount of transmitted or received TIPC packets on a link. Including fragmented and bundled packets.

Fragments

Represented in the form fragments/fragmented. Where fragmented is the amount of data messages which have been broken into fragments. Subsequently the fragments are the total amount of packets that the fragmented messages has been broken into.

Bundles

Represented in the form bundles/bundled. If a link becomes congested the link will attempt to bundle data from small bundled packets into bundles of full MTU size packets before they are transmitted.

Profile

Shows the average packet size in octets/bytes for a sample of packets. It also shows the packet size distribution of the sampled packets in the intervals 0-64 bytes

64-256 bytes

256-1024 bytes

1024-4096 bytes

4096-16384 bytes

16384-32768 bytes

32768-66000 bytes

Message counters

states - Number of link state messages

probes - Link state messages with probe flag set. Typically sent when a link is idle

nacks - Number of negative acknowledgement (NACK) packets sent and received by the link

defs - Number of packets received out of order

dups - Number of duplicate packets received

Congestion link

The number of times an application has tried to send data when the TIPC link was congested

Send queue

Max is the maximum amount of messages that has resided in the out queue during the statistics collection period of a link. Avg is the average outqueue size during the lifetime of a link.

### Link properties
priority

The priority between logical TIPC links to a particular node. Link priority can range from 0 (lowest) to 31 (highest).

tolerance

Link tolerance specifies the maximum time in milliseconds that TIPC will allow a communication problem to exist before taking the link down. The default value is 1500 milliseconds.

window

The link window controls how many unacknowledged messages a link endpoint can have in its transmit queue before TIPC's congestion control mechanism is activated.

### Monitor properties
threshold

The threshold specifies the cluster size exceeding which the link monitoring algorithm will switch from "full-mesh" to "overlapping-ring". If set of 0 the overlapping-ring monitoring is always on and if set to a value larger than anticipated cluster size the overlapping-ring is disabled. The default value is 32.

### Monitor information
table_generation

Represents the event count in a node's local monitoring list. It steps every time something changes in the local monitor list, including changes in the local domain.

cluster_size

Represents the current count of cluster members.

algorithm

The current supervision algorithm used for neighbour monitoring for the bearer. Possible values are full-mesh or overlapping-ring.

status

The node status derived by the local node. Possible status are up or down.

monitored

Represent the type of monitoring chosen by the local node. Possible values are direct or indirect.

generation

Represents the domain generation which is the event count in a node's local domain. Every time something changes (peer add/remove/up/down) the domain generation is stepped and a new version of node record is sent to inform the neighbors about this change. The domain generation helps the receiver of a domain record to know if it should ignore or process the record.

applied_node_status

The node status reported by the peer node for the succeeding peers in the node list. The Node list is a circular list of ascending addresses starting with the local node. Possible status are: U or D. The status U implies up and D down.

[non_applied_node:status]

Represents the nodes and their status as reported by the peer node. These nodes were not applied to the monitoring list for this peer node. They are usually transient and occur during the cluster startup phase or network reconfiguration. Possible status are: U or D. The status U implies up and D down.

### Broadcast properties
BROADCAST

Forces all multicast traffic to be transmitted via broadcast only, irrespective of cluster size and number of destinations.

REPLICAST

Forces all multicast traffic to be transmitted via replicast only, irrespective of cluster size and number of destinations.

AUTOSELECT

Auto switching to broadcast or replicast depending on cluster size and destination node number.

ratio SIZE

Set the AUTOSELECT criteria, percentage of destination nodes vs cluster size.

## EXAMPLES
tipc link monitor list

Shows the link monitoring information for cluster members on device data0.

tipc link monitor summary

The monitor summary command prints the basic attributes.

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

## SEE ALSO
tipc(8), tipc-media(8), tipc-bearer(8), tipc-nametable(8), tipc-node(8), tipc-peer(8), tipc-socket(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
Richard Alpe <richard.alpe@ericsson.com>


tipc-media

title: tipc-media(8)

summary: list or modify media properties

text:
# tipc-media(8)

## NAME
tipc-media - list or modify media properties

## SYNOPSIS

tipc media set { priority PRIORITY | tolerance TOLERANCE | window WINDOW } media MEDIA

tipc media get { priority | tolerance | window } media MEDIA

tipc media list

## OPTIONS
Options (flags) that can be passed anywhere in the command chain.

-h, --help

Show help about last valid command. For example tipc media --help will show media help and tipc --help will show general help. The position of the option in the string is irrelevant.

## DESCRIPTION

### Media properties
priority

Default link priority inherited by all bearers subsequently enabled on a media. For more info about link priority see tipc-link(8)

tolerance

Default link tolerance inherited by all bearers subsequently enabled on a media. For more info about link tolerance see tipc-link(8)

window

Default link window inherited by all bearers subsequently enabled on a media. For more info about link window see tipc-link(8)

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

## SEE ALSO
tipc(8), tipc-bearer(8), tipc-link(8), tipc-nametable(8), tipc-node(8), tipc-peer(8), tipc-socket(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
Richard Alpe <richard.alpe@ericsson.com>


tipc-nametable

title: tipc-nametable(8)

summary: show TIPC nametable

text:
# tipc-nametable(8)

## NAME
tipc-nametable - show TIPC nametable

## SYNOPSIS

tipc nametable show

## OPTIONS
Options (flags) that can be passed anywhere in the command chain.

-h, --help

-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. Show help about last valid command. For example tipc nametable --help will show nametable help and tipc --help will show general help. The position of the option in the string is irrelevant.

## DESCRIPTION
The nametable shows TIPC publication information.

### Nametable format
Type

The 32-bit type field of the port name. The type field often indicates the class of service provided by a port.

Lower

The lower bound of the 32-bit instance field of the port name. The instance field is often used as a sub-class indicator.

Upper

The upper bound of the 32-bit instance field of the port name. The instance field is often used as a sub-class indicator. A difference in lower and upper means the socket is bound to the port name range [lower,upper]

Port Identity

The unique socket (port) identifier within the TIPC cluster. The port identity consists of a node identity followed by a socket reference number.

Publication

The publication ID is a random number used internally to represent a publication.

Scope

The publication scope specifies the visibility of a bound port name. The scope can be specified to comprise three different domains: node, cluster and zone. Applications residing within the specified scope can see and access the port using the displayed port name.

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

## SEE ALSO
tipc(8), tipc-bearer(8), tipc-link(8), tipc-media(8), tipc-node(8), tipc-peer(8), tipc-socket(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
Richard Alpe <richard.alpe@ericsson.com>


tipc-node

title: tipc-node(8)

text:
# tipc-node(8)

## NAME
tipc-node - modify and show local node parameters or list peer nodes

## SYNOPSIS

tipc node set { address ADDRESS | netid NETID }

tipc node get { address | netid }

tipc node list

## OPTIONS
Options (flags) that can be passed anywhere in the command chain.

-h, --help

Show help about last valid command. For example tipc node --help will show node help and tipc --help will show general help. The position of the option in the string is irrelevant.

## DESCRIPTION

### Node parameters
address

The TIPC logical address. On the form x.y.z where x, y and z are unsigned integers.

netid

Network identity. Can by used to create individual TIPC clusters on the same media.

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

## SEE ALSO
tipc(8), tipc-bearer(8), tipc-link(8), tipc-media(8), tipc-nametable(8), tipc-peer(8), tipc-socket(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
Richard Alpe <richard.alpe@ericsson.com>


tipc-peer

title: tipc-peer(8)

summary: modify peer information

text:
# tipc-peer(8)

## NAME
tipc-peer - modify peer information

## SYNOPSIS

tipc peer remove address ADDRESS

## OPTIONS
Options (flags) that can be passed anywhere in the command chain.

-h, --help

Show help about last valid command. For example tipc peer --help will show peer help and tipc --help will show general help. The position of the option in the string is irrelevant.

## DESCRIPTION

### Peer remove
Remove an offline peer node from the local data structures. The peer is identified by its address

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

## SEE ALSO
tipc(8), tipc-bearer(8), tipc-link(8), tipc-media(8), tipc-nametable(8), tipc-node(8), tipc-socket(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
Richard Alpe <richard.alpe@ericsson.com>


tipc-socket

title: tipc-socket(8)

summary: show TIPC socket (port) information

text:
# tipc-socket(8)

## NAME
tipc-socket - show TIPC socket (port) information

## SYNOPSIS

tipc socket list

## OPTIONS
Options (flags) that can be passed anywhere in the command chain.

-h, --help

Show help about last valid command. For example tipc socket --help will show socket help and tipc --help will show general help. The position of the option in the string is irrelevant.

## DESCRIPTION
A TIPC socket is represented by an unsigned integer.

### Bound state
A bound socket has a logical TIPC port name associated with it.

### Connected state
A connected socket is directly connected to another socket creating a point to point connection between TIPC sockets. If the connection to X was made using a logical port name Y that name will show up as connected to X via Y

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

## SEE ALSO
tipc(8), tipc-bearer(8) tipc-link(8), tipc-media(8), tipc-nametable(8), tipc-node(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
Richard Alpe <richard.alpe@ericsson.com>


vdpa

title: vdpa(8)

summary: vdpa management tool

text:
# vdpa(8)

## NAME
vdpa - vdpa management tool

## SYNOPSIS

vdpa [ OPTIONS ] { dev|mgmtdev } { COMMAND | help }

## OPTIONS
-V, --Version

Print the version of the vdpa utility and exit.

-j, --json

Generate JSON output.

-p, --pretty

When combined with -j generate a pretty JSON output.

### OBJECT
dev

- vdpa device.

mgmtdev

- vdpa management device.

### COMMAND
Specifies the action to perform on the object. The set of possible actions depends on the object type. It is possible to show (or list ) objects. 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 show 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
vdpa-dev(8), vdpa-mgmtdev(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
Parav Pandit <parav@nvidia.com>


vdpa-dev

title: vdpa-dev(8)

summary: vdpa device configuration

text:
# vdpa-dev(8)

## NAME
vdpa-dev - vdpa device configuration

## SYNOPSIS

vdpa dev [ OPTIONS ] { COMMAND| help }

OPTIONS := { -V[ersion] }

vdpa dev show [ DEV ]

vdpa dev help

vdpa dev add name NAME mgmtdev MGMTDEV [ device_features DEVICE_FEATURES ] [ mac MACADDR ] [ mtu MTU ] [ max_vqp MAX_VQ_PAIRS ]

vdpa dev del DEV

vdpa dev config show [ DEV ]

vdpa dev vstats show DEV qidx QUEUE_INDEX

## DESCRIPTION

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

Format is:

VDPA_DEVICE_NAME

### vdpa dev add - add a new vdpa device.
name NAME

Name of the new vdpa device to add.

mgmtdev MGMTDEV

Name of the management device to use for device addition.

device_features DEVICE_FEATURES Specifies the virtio device features bit-mask that is provisioned for the new vdpa device.

The bits can be found under include/uapi/linux/virtio*h.

see macros such as VIRTIO_F_ and VIRTIO_XXX(e.g NET)_F_ for specific bit values.

This is optional.

mac MACADDR - specifies the mac address for the new vdpa device. This is applicable only for the network type of vdpa device. This is optional.

mtu MTU - specifies the mtu for the new vdpa device. This is applicable only for the network type of vdpa device. This is optional.

### vdpa dev del - Delete the vdpa device.
DEV - specifies the vdpa device to delete.

### vdpa dev config show - Show configuration of specific device or all devices.
DEV - specifies the vdpa device to show its configuration. If this argument is omitted all devices configuration is listed.

Format is:

VDPA_DEVICE_NAME

### vdpa dev vstats show - shows vendor specific statistics for the given device and virtqueue index. The information is presented as name-value pairs where name is the name of the field and value is a numeric value for it.
DEV

- specifies the vdpa device to query

qidx QUEUE_INDEX

- specifies the virtqueue index to query

## EXAMPLES
vdpa dev show

Shows the all vdpa devices on the system.

vdpa dev show foo

Shows the specified vdpa device.

vdpa dev add name foo mgmtdev vdpa_sim_net

Add the vdpa device named foo on the management device vdpa_sim_net.

vdpa dev add name foo mgmtdev vdpa_sim_net device_features 0x300020000

Add the vdpa device named foo on the management device vdpa_sim_net with device_features of 0x300020000

vdpa dev add name foo mgmtdev vdpa_sim_net mac 00:11:22:33:44:55

Add the vdpa device named foo on the management device vdpa_sim_net with mac address of 00:11:22:33:44:55.

vdpa dev add name foo mgmtdev vdpa_sim_net mac 00:11:22:33:44:55 mtu 9000

Add the vdpa device named foo on the management device vdpa_sim_net with mac address of 00:11:22:33:44:55 and mtu of 9000 bytes.

vdpa dev add name foo mgmtdev auxiliary/mlx5_core.sf.1 mac 00:11:22:33:44:55 max_vqp 8

Add the vdpa device named foo on the management device auxiliary/mlx5_core.sf.1 with mac address of 00:11:22:33:44:55 and max 8 virtqueue pairs

vdpa dev del foo

Delete the vdpa device named foo which was previously created.

vdpa dev config show foo

Shows the vdpa device configuration of device named foo.

vdpa dev vstats show vdpa0 qidx 1

Shows vendor specific statistics information for vdpa device vdpa0 and virtqueue index 1

## SEE ALSO
vdpa(8), vdpa-mgmtdev(8),

## AUTHOR
Parav Pandit <parav@nvidia.com>


vdpa-mgmtdev

title: vdpa-mgmtdev(8)

summary: vdpa management device view

text:
# vdpa-mgmtdev(8)

## NAME
vdpa-dev - vdpa management device view

## SYNOPSIS

vdpa mgmtdev { COMMAND| help }

OPTIONS := { -V[ersion] }

vdpa mgmtdev show [ MGMTDEV ]

vdpa mgmtdev help

## DESCRIPTION

### vdpa mgmtdev show - display vdpa management device attributes
MGMTDEV - specifies the vdpa management device to show. If this argument is omitted all management devices are listed.

## EXAMPLES
vdpa mgmtdev show

Shows all the vdpa management devices on the system.

vdpa mgmtdev show bar

Shows the specified vdpa management device.

## SEE ALSO
vdpa(8), vdpa-dev(8),

## AUTHOR
Parav Pandit <parav@nvidia.com>


ipset

package: ipset

title: ipset(8)

summary: administration tool for IP sets

text:
# ipset(8)

## NAME
ipset — administration tool for IP sets

## SYNOPSIS
ipset [ OPTIONS ] COMMAND [ COMMAND-OPTIONS ]

COMMANDS := { create | add | del | test | destroy | list | save | restore | flush | rename | swap | help | version | - }

OPTIONS := { -exist | -output { plain | save | xml } | json } | -quiet | -resolve | -sorted | -name | -terse | -file filename }

ipset create SETNAME TYPENAME [ CREATE-OPTIONS ]

ipset add SETNAME ADD-ENTRY [ ADD-OPTIONS ]

ipset del SETNAME DEL-ENTRY [ DEL-OPTIONS ]

ipset test SETNAME TEST-ENTRY [ TEST-OPTIONS ]

ipset destroy [ SETNAME ]

ipset list [ SETNAME ]

ipset save [ SETNAME ]

ipset restore

ipset flush [ SETNAME ]

ipset rename SETNAME-FROM SETNAME-TO

ipset swap SETNAME-FROM SETNAME-TO

ipset help [ TYPENAME ]

ipset version

ipset -

## DESCRIPTION
ipset is used to set up, maintain and inspect so called IP sets in the Linux kernel. Depending on the type of the set, an IP set may store IP(v4/v6) addresses, (TCP/UDP) port numbers, IP and MAC address pairs, IP address and port number pairs, etc. See the set type definitions below.

Iptables matches and targets referring to sets create references, which protect the given sets in the kernel. A set cannot be destroyed while there is a single reference pointing to it.

## OPTIONS
The options that are recognized by ipset can be divided into several different groups.

### COMMANDS
These options specify the desired action to perform. Only one of them can be specified on the command line unless otherwise specified below. For all the long versions of the command names, you need to use only enough letters to ensure that ipset can differentiate it from all other commands. The ipset parser follows the order here when looking for the shortest match in the long command names.

n, create SETNAME TYPENAME [ CREATE-OPTIONS ]

Create a set identified with setname and specified type. The type may require type specific options. If the -exist option is specified, ipset ignores the error otherwise raised when the same set (setname and create parameters are identical) already exists.

add SETNAME ADD-ENTRY [ ADD-OPTIONS ]

Add a given entry to the set. If the -exist option is specified, ipset ignores if the entry already added to the set.

del SETNAME DEL-ENTRY [ DEL-OPTIONS ]

Delete an entry from a set. If the -exist option is specified and the entry is not in the set (maybe already expired), then the command is ignored.

test SETNAME TEST-ENTRY [ TEST-OPTIONS ]

Test whether an entry is in a set or not. Exit status number is zero if the tested entry is in the set and nonzero if it is missing from the set.

x, destroy [ SETNAME ]

Destroy the specified set or all the sets if none is given. If the set has got reference(s), nothing is done and no set destroyed.

list [ SETNAME ] [ OPTIONS ]

List the header data and the entries for the specified set, or for all sets if none is given. The -resolve option can be used to force name lookups (which may be slow). When the -sorted option is given, the entries are listed/saved sorted (which may be slow). The option -output can be used to control the format of the listing: plain, save, xml or json. (The default is plain.) If the option -name is specified, just the names of the existing sets are listed. If the option -terse is specified, just the set names and headers are listed. The output is printed to stdout, the option -file can be used to specify a filename instead of stdout.

save [ SETNAME ]

Save the given set, or all sets if none is given to stdout in a format that restore can read. The option -file can be used to specify a filename instead of stdout.

restore

Restore a saved session generated by save. The saved session can be fed from stdin or the option -file can be used to specify a filename instead of stdin. Please note, existing sets and elements are not erased by restore unless specified so in the restore file. All commands are allowed in restore mode except list, help, version, interactive mode and restore itself.

flush [ SETNAME ]

Flush all entries from the specified set or flush all sets if none is given.

e, rename SETNAME-FROM SETNAME-TO

Rename a set. Set identified by SETNAME-TO must not exist.

w, swap SETNAME-FROM SETNAME-TO

Swap the content of two sets, or in another words, exchange the name of two sets. The referred sets must exist and compatible type of sets can be swapped only.

help [ TYPENAME ]

Print help and set type specific help if TYPENAME is specified.

version

Print program version.

-

If a dash is specified as command, then ipset enters a simple interactive mode and the commands are read from the standard input. The interactive mode can be finished by entering the pseudo-command quit.

### OTHER OPTIONS
The following additional options can be specified. The long option names cannot be abbreviated.

-!, -exist

Ignore errors when exactly the same set is to be created or already added entry is added or missing entry is deleted.

-o, -output { plain | save | xml | json }

Select the output format to the list command.

-q, -quiet

Suppress any output to stdout and stderr. ipset will still exit with error if it cannot continue.

-r, -resolve

When listing sets, enforce name lookup. The program will try to display the IP entries resolved to host names which requires slow DNS lookups.

-s, -sorted

Sorted output. When listing or saving sets, the entries are listed sorted.

-n, -name

List just the names of the existing sets, i.e. suppress listing of set headers and members.

-t, -terse

List the set names and headers, i.e. suppress listing of set members.

-f, -file filename

Specify a filename to print into instead of stdout (list or save commands) or read from instead of stdin (restore command).

## INTRODUCTION
A set type comprises of the storage method by which the data is stored and the data type(s) which are stored in the set. Therefore the TYPENAME parameter of the create command follows the syntax

TYPENAME := method:datatype[,datatype[,datatype]]

where the current list of the methods are bitmap, hash, and list and the possible data types are ip, net, mac, port and iface. The dimension of a set is equal to the number of data types in its type name.

When adding, deleting or testing entries in a set, the same comma separated data syntax must be used for the entry parameter of the commands, i.e

ipset add foo ipaddr,portnum,ipaddr

If host names or service names with dash in the name are used instead of IP addresses or service numbers, then the host name or service name must be enclosed in square brackets. Example:

ipset add foo [test-hostname],[ftp-data]

In the case of host names the DNS resolver is called internally by ipset but if it returns multiple IP addresses, only the first one is used.

The bitmap and list types use a fixed sized storage. The hash types use a hash to store the elements. In order to avoid clashes in the hash, a limited number of chaining, and if that is exhausted, the doubling of the hash size is performed when adding entries by the ipset command. When entries added by the SET target of iptables/ip6tables, then the hash size is fixed and the set won't be duplicated, even if the new entry cannot be added to the set.

## GENERIC CREATE AND ADD OPTIONS

### timeout
All set types supports the optional timeout parameter when creating a set and adding entries. The value of the timeout parameter for the create command means the default timeout value (in seconds) for new entries. If a set is created with timeout support, then the same timeout option can be used to specify non-default timeout values when adding entries. Zero timeout value means the entry is added permanent to the set. The timeout value of already added elements can be changed by re-adding the element using the -exist option. The largest possible timeout value is 2147483 (in seconds). Example:

ipset create test hash:ip timeout 300

ipset add test 192.168.0.1 timeout 60

ipset -exist add test 192.168.0.1 timeout 600

When listing the set, the number of entries printed in the header might be larger than the listed number of entries for sets with the timeout extensions: the number of entries in the set is updated when elements added/deleted to the set and periodically when the garbage collector evicts the timed out entries.

### counters, packets, bytes
All set types support the optional counters option when creating a set. If the option is specified then the set is created with packet and byte counters per element support. The packet and byte counters are initialized to zero when the elements are (re-)added to the set, unless the packet and byte counter values are explicitly specified by the packets and bytes options. An example when an element is added to a set with non-zero counter values:

ipset create foo hash:ip counters

ipset add foo 192.168.1.1 packets 42 bytes 1024

### comment
All set types support the optional comment extension. Enabling this extension on an ipset enables you to annotate an ipset entry with an arbitrary string. This string is completely ignored by both the kernel and ipset itself and is purely for providing a convenient means to document the reason for an entry's existence. Comments must not contain any quotation marks and the usual escape character (\) has no meaning. For example, the following shell command is illegal:

ipset add foo 1.1.1.1 comment "this comment is \"bad\""

In the above, your shell will of course escape the quotation marks and ipset will see the quote marks in the argument for the comment, which will result in a parse error. If you are writing your own system, you should avoid creating comments containing a quotation mark if you do not want to break "ipset save" and "ipset restore", nonetheless, the kernel will not stop you from doing so. The following is perfectly acceptable:

ipset create foo hash:ip comment

ipset add foo 192.168.1.1/24 comment "allow access to SMB share on \\\\fileserv\\"

the above would appear as: "allow access to SMB share on \\fileserv\"

### skbinfo, skbmark, skbprio, skbqueue
All set types support the optional skbinfo extension. This extension allows you to store the metainfo (firewall mark, tc class and hardware queue) with every entry and map it to packets by usage of SET netfilter target with --map-set option. skbmark option format: MARK or MARK/MASK, where MARK and MASK are 32bit hex numbers with 0x prefix. If only mark is specified mask 0xffffffff are used. skbprio option has tc class format: MAJOR:MINOR, where major and minor numbers are hex without 0x prefix. skbqueue option is just decimal number.

ipset create foo hash:ip skbinfo

ipset add foo 192.168.0.1 skbmark 0x1111/0xff00ffff skbprio 1:10 skbqueue 10

### hashsize
This parameter is valid for the create command of all hash type sets. It defines the initial hash size for the set, default is 1024. The hash size must be a power of two, the kernel automatically rounds up non power of two hash sizes to the first correct value. Example:

ipset create test hash:ip hashsize 1536

### maxelem
This parameter is valid for the create command of all hash type sets. It defines the maximal number of elements which can be stored in the set, default 65536. Example:

ipset create test hash:ip maxelem 2048

### bucketsize
This parameter is valid for the create command of all hash type sets. It specifies the maximal number of elements which can be stored in a hash bucket. Possible values are any even number between 2-14 and the default is 14. Setting the value lower forces ipset to create larger hashes which consumes more memory but gives more speed at matching in the set. Example:

ipset create test hash:ip bucketsize 2

### family { inet | inet6 }
This parameter is valid for the create command of all hash type sets except for hash:mac. It defines the protocol family of the IP addresses to be stored in the set. The default is inet, i.e IPv4. For the inet family one can add or delete multiple entries by specifying a range or a network of IPv4 addresses in the IP address part of the entry:

ipaddr := { ip | fromaddr-toaddr | ip/cidr }

netaddr := { fromaddr-toaddr | ip/cidr }

Example:

ipset create test hash:ip family inet6

### nomatch
The hash set types which can store net type of data (i.e. hash:*net*) support the optional nomatch option when adding entries. When matching elements in the set, entries marked as nomatch are skipped as if those were not added to the set, which makes possible to build up sets with exceptions. See the example at hash type hash:net below.

When elements are tested by ipset, the nomatch flags are taken into account. If one wants to test the existence of an element marked with nomatch in a set, then the flag must be specified too.

### forceadd
All hash set types support the optional forceadd parameter when creating a set. When sets created with this option become full the next addition to the set may succeed and evict a random entry from the set.

ipset create foo hash:ip forceadd

### wildcard
This flag is valid when adding elements to a hash:net,iface set. If the flag is set, then prefix matching is used when comparing with this element. For example, an element containing the interface name "eth" will match any name with that prefix.

## SET TYPES

### bitmap:ip
The bitmap:ip set type uses a memory range to store either IPv4 host (default) or IPv4 network addresses. A bitmap:ip type of set can store up to 65536 entries.

CREATE-OPTIONS := range fromip-toip|ip/cidr [ netmask cidr ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]

ADD-ENTRY := { ip | fromip-toip | ip/cidr }

ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [ comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]

DEL-ENTRY := { ip | fromip-toip | ip/cidr }

TEST-ENTRY := ip

Mandatory create options:

range fromip-toip|ip/cidr

Create the set from the specified inclusive address range expressed in an IPv4 address range or network. The size of the range (in entries) cannot exceed the limit of maximum 65536 elements.

Optional create options:

netmask cidr

When the optional netmask parameter specified, network addresses will be stored in the set instead of IP host addresses. The cidr prefix value must be between 1-32. An IP address will be in the set if the network address, which is resulted by masking the address with the specified netmask, can be found in the set.

The bitmap:ip type supports adding or deleting multiple entries in one command.

Examples:

ipset create foo bitmap:ip range 192.168.0.0/16

ipset add foo 192.168.1/24

ipset test foo 192.168.1.1

### bitmap:ip,mac
The bitmap:ip,mac set type uses a memory range to store IPv4 and a MAC address pairs. A bitmap:ip,mac type of set can store up to 65536 entries.

CREATE-OPTIONS := range fromip-toip|ip/cidr [ timeout value ] [ counters ] [ comment ] [ skbinfo ]

ADD-ENTRY := ip[,macaddr]

ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [ comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]

DEL-ENTRY := ip[,macaddr]

TEST-ENTRY := ip[,macaddr]

Mandatory options to use when creating a bitmap:ip,mac type of set:

range fromip-toip|ip/cidr

Create the set from the specified inclusive address range expressed in an IPv4 address range or network. The size of the range cannot exceed the limit of maximum 65536 entries.

The bitmap:ip,mac type is exceptional in the sense that the MAC part can be left out when adding/deleting/testing entries in the set. If we add an entry without the MAC address specified, then when the first time the entry is matched by the kernel, it will automatically fill out the missing MAC address with the MAC address from the packet. The source MAC address is used if the entry matched due to a src parameter of the set match, and the destination MAC address is used if available and the entry matched due to a dst parameter. If the entry was specified with a timeout value, the timer starts off when the IP and MAC address pair is complete.

The bitmap:ip,mac type of sets require two src/dst parameters of the set match and SET target netfilter kernel modules. For matches on destination MAC addresses, see COMMENTS below.

Examples:

ipset create foo bitmap:ip,mac range 192.168.0.0/16

ipset add foo 192.168.1.1,12:34:56:78:9A:BC

ipset test foo 192.168.1.1

### bitmap:port
The bitmap:port set type uses a memory range to store port numbers and such a set can store up to 65536 ports.

CREATE-OPTIONS := range fromport-toport [ timeout value ] [ counters ] [ comment ] [ skbinfo ]

ADD-ENTRY := { [proto:]port | [proto:]fromport-toport }

ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [ comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]

DEL-ENTRY := { [proto:]port | [proto:]fromport-toport }

TEST-ENTRY := [proto:]port

Mandatory options to use when creating a bitmap:port type of set:

range [proto:]fromport-toport

Create the set from the specified inclusive port range.

The set match and SET target netfilter kernel modules interpret the stored numbers as TCP or UDP port numbers.

proto only needs to be specified if a service name is used and that name does not exist as a TCP service. The protocol is never stored in the set, just the port number of the service.

Examples:

ipset create foo bitmap:port range 0-1024

ipset add foo 80

ipset test foo 80

ipset del foo udp:[macon-udp]-[tn-tl-w2]

### hash:ip
The hash:ip set type uses a hash to store IP host addresses (default) or network addresses. Zero valued IP address cannot be stored in a hash:ip type of set.

CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ maxelem value ] [ bucketsize value ] [ netmask cidr ] [ bitmask mask ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]

ADD-ENTRY := ipaddr

ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [ comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]

DEL-ENTRY := ipaddr

TEST-ENTRY := ipaddr

Optional create options:

netmask cidr

When the optional netmask parameter specified, network addresses will be stored in the set instead of IP host addresses. The cidr prefix value must be between 1-32 for IPv4 and between 1-128 for IPv6. An IP address will be in the set if the network address, which is resulted by masking the address with the netmask, can be found in the set. Examples:

ipset create foo hash:ip netmask 30

ipset add foo 192.168.1.0/24

ipset test foo 192.168.1.2

bitmask mask

This works similar to netmask but it will accept any valid IPv4/v6 address. It does not have to be a valid netmask.

### hash:mac
The hash:mac set type uses a hash to store MAC addresses. Zero valued MAC addresses cannot be stored in a hash:mac type of set. For matches on destination MAC addresses, see COMMENTS below.

CREATE-OPTIONS := [ hashsize value ] [ maxelem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]

ADD-ENTRY := macaddr

ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [ comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]

DEL-ENTRY := macaddr

TEST-ENTRY := macaddr

Examples:

ipset create foo hash:mac

ipset add foo 01:02:03:04:05:06

ipset test foo 01:02:03:04:05:06

### hash:ip,mac
The hash:ip,mac set type uses a hash to store IP and a MAC address pairs. Zero valued MAC addresses cannot be stored in a hash:ip,mac type of set. For matches on destination MAC addresses, see COMMENTS below.

CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ maxelem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]

ADD-ENTRY := ipaddr,macaddr

ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [ comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]

DEL-ENTRY := ipaddr,macaddr

TEST-ENTRY := ipaddr,macaddr

Examples:

ipset create foo hash:ip,mac

ipset add foo 1.1.1.1,01:02:03:04:05:06

ipset test foo 1.1.1.1,01:02:03:04:05:06

### hash:net
The hash:net set type uses a hash to store different sized IP network addresses. Network address with zero prefix size cannot be stored in this type of sets.

CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ maxelem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]

ADD-ENTRY := netaddr

ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes value ] [ comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]

DEL-ENTRY := netaddr

TEST-ENTRY := netaddr

where netaddr := ip[/cidr]

When adding/deleting/testing entries, if the cidr prefix parameter is not specified, then the host prefix value is assumed. When adding/deleting entries, the exact element is added/deleted and overlapping elements are not checked by the kernel. When testing entries, if a host address is tested, then the kernel tries to match the host address in the networks added to the set and reports the result accordingly.

From the set netfilter match point of view the searching for a match always starts from the smallest size of netblock (most specific prefix) to the largest one (least specific prefix) added to the set. When adding/deleting IP addresses to the set by the SET netfilter target, it will be added/deleted by the most specific prefix which can be found in the set, or by the host prefix value if the set is empty.

The lookup time grows linearly with the number of the different prefix values added to the set.

Example:

ipset create foo hash:net

ipset add foo 192.168.0.0/24

ipset add foo 10.1.0.0/16

ipset add foo 192.168.0/24

ipset add foo 192.168.0/30 nomatch

When matching the elements in the set above, all IP addresses will match from the networks 192.168.0.0/24, 10.1.0.0/16 and 192.168.0/24 except the ones from 192.168.0/30.

### hash:net,net
The hash:net,net set type uses a hash to store pairs of different sized IP network addresses. Bear in mind that the first parameter has precedence over the second, so a nomatch entry could be potentially be ineffective if a more specific first parameter existed with a suitable second parameter. Network address with zero prefix size cannot be stored in this type of set.

CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ maxelem value ] [ bucketsize value ] [ netmask cidr ] [ bitmask mask ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]

ADD-ENTRY := netaddr,netaddr

ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes value ] [ comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]

DEL-ENTRY := netaddr,netaddr

TEST-ENTRY := netaddr,netaddr

where netaddr := ip[/cidr]

When adding/deleting/testing entries, if the cidr prefix parameter is not specified, then the host prefix value is assumed. When adding/deleting entries, the exact element is added/deleted and overlapping elements are not checked by the kernel. When testing entries, if a host address is tested, then the kernel tries to match the host address in the networks added to the set and reports the result accordingly.

From the set netfilter match point of view the searching for a match always starts from the smallest size of netblock (most specific prefix) to the largest one (least specific prefix) with the first param having precedence. When adding/deleting IP addresses to the set by the SET netfilter target, it will be added/deleted by the most specific prefix which can be found in the set, or by the host prefix value if the set is empty.

The lookup time grows linearly with the number of the different prefix values added to the first parameter of the set. The number of secondary prefixes further increases this as the list of secondary prefixes is traversed per primary prefix.

Optional create options:

netmask cidr

When the optional netmask parameter specified, network addresses will be stored in the set instead of IP host addresses. The cidr prefix value must be between 1-32 for IPv4 and between 1-128 for IPv6. An IP address will be in the set if the network address, which is resulted by masking the address with the netmask, can be found in the set.

bitmask mask

This works similar to netmask but it will accept any valid IPv4/v6 address. It does not have to be a valid netmask.

Example:

ipset create foo hash:net,net

ipset add foo 192.168.0.0/24,10.0.1.0/24

ipset add foo 10.1.0.0/16,10.255.0.0/24

ipset add foo 192.168.0/24,192.168.54.0-192.168.54.255

ipset add foo 192.168.0/30,192.168.64/30 nomatch

When matching the elements in the set above, all IP addresses will match from the networks 192.168.0.0/24<->10.0.1.0/24, 10.1.0.0/16<->10.255.0.0/24 and 192.168.0/24<->192.168.54.0/24 except the ones from 192.168.0/30<->192.168.64/30.

### hash:ip,port
The hash:ip,port set type uses a hash to store IP address and port number pairs. The port number is interpreted together with a protocol (default TCP) and zero protocol number cannot be used.

CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ maxelem value ] [ bucketsize value ] [ netmask cidr ] [ bitmask mask ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]

ADD-ENTRY := ipaddr,[proto:]port

ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [ comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]

DEL-ENTRY := ipaddr,[proto:]port

TEST-ENTRY := ipaddr,[proto:]port

The [proto:]port part of the elements may be expressed in the following forms, where the range variations are valid when adding or deleting entries:

portname[-portname]

TCP port or range of ports expressed in TCP portname identifiers from /etc/services

portnumber[-portnumber]

TCP port or range of ports expressed in TCP port numbers

tcp|sctp|udp|udplite:portname|portnumber[-portname|portnumber]

TCP, SCTP, UDP or UDPLITE port or port range expressed in port name(s) or port number(s)

icmp:codename|type/code

ICMP codename or type/code. The supported ICMP codename identifiers can always be listed by the help command.

icmpv6:codename|type/code

ICMPv6 codename or type/code. The supported ICMPv6 codename identifiers can always be listed by the help command.

proto:0

All other protocols, as an identifier from /etc/protocols or number. The pseudo port number must be zero.

The hash:ip,port type of sets require two src/dst parameters of the set match and SET target kernel modules.

Optional create options:

netmask cidr

When the optional netmask parameter specified, network addresses will be stored in the set instead of IP host addresses. The cidr prefix value must be between 1-32 for IPv4 and between 1-128 for IPv6. An IP address will be in the set if the network address, which is resulted by masking the address with the netmask, can be found in the set.

bitmask mask

This works similar to netmask but it will accept any valid IPv4/v6 address. It does not have to be a valid netmask.

Examples:

ipset create foo hash:ip,port

ipset add foo 192.168.1.0/24,80-82

ipset add foo 192.168.1.1,udp:53

ipset add foo 192.168.1.1,vrrp:0

ipset test foo 192.168.1.1,80

### hash:net,port
The hash:net,port set type uses a hash to store different sized IP network address and port pairs. The port number is interpreted together with a protocol (default TCP) and zero protocol number cannot be used. Network address with zero prefix size is not accepted either.

CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ maxelem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]

ADD-ENTRY := netaddr,[proto:]port

ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes value ] [ comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]

DEL-ENTRY := netaddr,[proto:]port

TEST-ENTRY := netaddr,[proto:]port

where netaddr := ip[/cidr]

For the netaddr part of the elements see the description at the hash:net set type. For the [proto:]port part of the elements see the description at the hash:ip,port set type.

When adding/deleting/testing entries, if the cidr prefix parameter is not specified, then the host prefix value is assumed. When adding/deleting entries, the exact element is added/deleted and overlapping elements are not checked by the kernel. When testing entries, if a host address is tested, then the kernel tries to match the host address in the networks added to the set and reports the result accordingly.

From the set netfilter match point of view the searching for a match always starts from the smallest size of netblock (most specific prefix) to the largest one (least specific prefix) added to the set. When adding/deleting IP addresses to the set by the SET netfilter target, it will be added/deleted by the most specific prefix which can be found in the set, or by the host prefix value if the set is empty.

The lookup time grows linearly with the number of the different prefix values added to the set.

Examples:

ipset create foo hash:net,port

ipset add foo 192.168.0/24,25

ipset add foo 10.1.0.0/16,80

ipset test foo 192.168.0/24,25

### hash:ip,port,ip
The hash:ip,port,ip set type uses a hash to store IP address, port number and a second IP address triples. The port number is interpreted together with a protocol (default TCP) and zero protocol number cannot be used.

CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ maxelem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]

ADD-ENTRY := ipaddr,[proto:]port,ip

ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [ comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]

DEL-ENTRY := ipaddr,[proto:]port,ip

TEST-ENTRY := ipaddr,[proto:]port,ip

For the first ipaddr and [proto:]port parts of the elements see the descriptions at the hash:ip,port set type.

The hash:ip,port,ip type of sets require three src/dst parameters of the set match and SET target kernel modules.

Examples:

ipset create foo hash:ip,port,ip

ipset add foo 192.168.1.1,80,10.0.0.1

ipset test foo 192.168.1.1,udp:53,10.0.0.1

### hash:ip,port,net
The hash:ip,port,net set type uses a hash to store IP address, port number and IP network address triples. The port number is interpreted together with a protocol (default TCP) and zero protocol number cannot be used. Network address with zero prefix size cannot be stored either.

CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ maxelem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]

ADD-ENTRY := ipaddr,[proto:]port,netaddr

ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes value ] [ comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]

DEL-ENTRY := ipaddr,[proto:]port,netaddr

TEST-ENTRY := ipaddr,[proto:]port,netaddr

where netaddr := ip[/cidr]

For the ipaddr and [proto:]port parts of the elements see the descriptions at the hash:ip,port set type. For the netaddr part of the elements see the description at the hash:net set type.

From the set netfilter match point of view the searching for a match always starts from the smallest size of netblock (most specific cidr) to the largest one (least specific cidr) added to the set. When adding/deleting triples to the set by the SET netfilter target, it will be added/deleted by the most specific cidr which can be found in the set, or by the host cidr value if the set is empty.

The lookup time grows linearly with the number of the different cidr values added to the set.

The hash:ip,port,net type of sets require three src/dst parameters of the set match and SET target kernel modules.

Examples:

ipset create foo hash:ip,port,net

ipset add foo 192.168.1,80,10.0.0/24

ipset add foo 192.168.2,25,10.1.0.0/16

ipset test foo 192.168.1,80.10.0.0/24

### hash:ip,mark
The hash:ip,mark set type uses a hash to store IP address and packet mark pairs.

CREATE-OPTIONS := [ family { inet | inet6 } ] [ markmask value ] [ hashsize value ] [ maxelem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]

ADD-ENTRY := ipaddr,mark

ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [ comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]

DEL-ENTRY := ipaddr,mark

TEST-ENTRY := ipaddr,mark

Optional create options:

markmask value

Allows you to set bits you are interested in the packet mark. This value is then used to perform bitwise AND operation for every mark added. markmask can be any value between 1 and 4294967295, by default all 32 bits are set.

The mark can be any value between 0 and 4294967295.

The hash:ip,mark type of sets require two src/dst parameters of the set match and SET target kernel modules.

Examples:

ipset create foo hash:ip,mark

ipset add foo 192.168.1.0/24,555

ipset add foo 192.168.1.1,0x63

ipset add foo 192.168.1.1,111236

### hash:net,port,net
The hash:net,port,net set type behaves similarly to hash:ip,port,net but accepts a cidr value for both the first and last parameter. Either subnet is permitted to be a /0 should you wish to match port between all destinations.

CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ maxelem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]

ADD-ENTRY := netaddr,[proto:]port,netaddr

ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes value ] [ comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]

DEL-ENTRY := netaddr,[proto:]port,netaddr

TEST-ENTRY := netaddr,[proto:]port,netaddr

where netaddr := ip[/cidr]

For the [proto:]port part of the elements see the description at the hash:ip,port set type. For the netaddr part of the elements see the description at the hash:net set type.

From the set netfilter match point of view the searching for a match always starts from the smallest size of netblock (most specific cidr) to the largest one (least specific cidr) added to the set. When adding/deleting triples to the set by the SET netfilter target, it will be added/deleted by the most specific cidr which can be found in the set, or by the host cidr value if the set is empty. The first subnet has precedence when performing the most-specific lookup, just as for hash:net,net

The lookup time grows linearly with the number of the different cidr values added to the set and by the number of secondary cidr values per primary.

The hash:net,port,net type of sets require three src/dst parameters of the set match and SET target kernel modules.

Examples:

ipset create foo hash:net,port,net

ipset add foo 192.168.1.0/24,0,10.0.0/24

ipset add foo 192.168.2.0/24,25,10.1.0.0/16

ipset test foo 192.168.1.1,80,10.0.0.1

### hash:net,iface
The hash:net,iface set type uses a hash to store different sized IP network address and interface name pairs.

CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ maxelem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]

ADD-ENTRY := netaddr,[physdev:]iface

ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes value ] [ comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ] [ wildcard ]

DEL-ENTRY := netaddr,[physdev:]iface

TEST-ENTRY := netaddr,[physdev:]iface

where netaddr := ip[/cidr]

For the netaddr part of the elements see the description at the hash:net set type.

When adding/deleting/testing entries, if the cidr prefix parameter is not specified, then the host prefix value is assumed. When adding/deleting entries, the exact element is added/deleted and overlapping elements are not checked by the kernel. When testing entries, if a host address is tested, then the kernel tries to match the host address in the networks added to the set and reports the result accordingly.

From the set netfilter match point of view the searching for a match always starts from the smallest size of netblock (most specific prefix) to the largest one (least specific prefix) added to the set. When adding/deleting IP addresses to the set by the SET netfilter target, it will be added/deleted by the most specific prefix which can be found in the set, or by the host prefix value if the set is empty.

The second direction parameter of the set match and SET target modules corresponds to the incoming/outgoing interface: src to the incoming one (similar to the -i flag of iptables), while dst to the outgoing one (similar to the -o flag of iptables). When the interface is flagged with physdev:, the interface is interpreted as the incoming/outgoing bridge port.

The lookup time grows linearly with the number of the different prefix values added to the set.

The internal restriction of the hash:net,iface set type is that the same network prefix cannot be stored with more than 64 different interfaces in a single set.

Examples:

ipset create foo hash:net,iface

ipset add foo 192.168.0/24,eth0

ipset add foo 10.1.0.0/16,eth1

ipset test foo 192.168.0/24,eth0

### list:set
The list:set type uses a simple list in which you can store set names.

CREATE-OPTIONS := [ size value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]

ADD-ENTRY := setname [ { before | after } setname ]

ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [ comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]

DEL-ENTRY := setname [ { before | after } setname ]

TEST-ENTRY := setname [ { before | after } setname ]

Optional create options:

size value

The size of the list, the default is 8. The parameter is ignored since ipset version 6.24.

By the ipset command you can add, delete and test set names in a list:set type of set.

By the set match or SET target of netfilter you can test, add or delete entries in the sets added to the list:set type of set. The match will try to find a matching entry in the sets and the target will try to add an entry to the first set to which it can be added. The number of direction options of the match and target are important: sets which require more parameters than specified are skipped, while sets with equal or less parameters are checked, elements added/deleted. For example if a and b are list:set type of sets then in the command

iptables -m set --match-set a src,dst -j SET --add-set b src,dst

the match and target will skip any set in a and b which stores data triples, but will match all sets with single or double data storage in a set and stop matching at the first successful set, and add src to the first single or src,dst to the first double data storage set in b to which the entry can be added. You can imagine a list:set type of set as an ordered union of the set elements.

Please note: by the ipset command you can add, delete and test the setnames in a list:set type of set, and not the presence of a set's member (such as an IP address).

## GENERAL RESTRICTIONS
Zero valued set entries cannot be used with hash methods. Zero protocol value with ports cannot be used.

## COMMENTS
If you want to store same size subnets from a given network (say /24 blocks from a /8 network), use the bitmap:ip set type. If you want to store random same size networks (say random /24 blocks), use the hash:ip set type. If you have got random size of netblocks, use hash:net.

Matching on destination MAC addresses using the dst parameter of the set match netfilter kernel modules will only work if the destination MAC address is available in the packet at the given processing stage, that is, it only applies for incoming packets in the PREROUTING, INPUT and FORWARD chains, against the MAC address as originally found in the received packet (typically, one of the MAC addresses of the local host). This is not the destination MAC address a destination IP address resolves to, after routing. If the MAC address is not available (e.g. in the OUTPUT chain), the packet will simply not match.

Backward compatibility is maintained and old ipset syntax is still supported.

The iptree and iptreemap set types are removed: if you refer to them, they are automatically replaced by hash:ip type of sets.

## DIAGNOSTICS
Various error messages are printed to standard error. The exit code is 0 for correct functioning.

## BUGS
Bugs? No, just funny features. :-) OK, just kidding...

## SEE ALSO
iptables(8), ip6tables(8) iptables-extensions(8)

## AUTHORS
Jozsef Kadlecsik wrote ipset, which is based on ippool by Joakim Axelsson, Patrick Schaaf and Martin Josefsson.

Sven Wegener wrote the iptreemap type.

## LAST REMARK
I stand on the shoulders of giants.


ipset-translate

title: ipset-translate(8)

text:
# ipset-translate(8)

## NAME
ipset-translate — translation tool to migrate from ipset to nftables

## DESCRIPTION
This tool allows system administrators to translate a given IP sets file to nftables(8).

The only available command is:

•

ipset-translate restore < file.ipt

## USAGE
The ipset-translate tool reads an IP sets file in the syntax produced by ipset(8) save. No set modifications occur, this tool is a text converter.

## EXAMPLES
Basic operation examples.

Single command translation, assuming the original file:

```
create test1 hash:ip,port family inet counters timeout 300 hashsize 1024 maxelem 65536 bucketsize 12 initval 0xb5c4be5d
add test1 1.1.1.1,udp:20
add test1 1.1.1.1,21
create test2 hash:ip,port family inet hashsize 1024 maxelem 65536 bucketsize 12 initval 0xb5c4be5d
```

which results in the following translation:

```
root@machine:~# ipset-translate restore < file.ipt
add set inet global test1 { type ipv4_addr . inet_proto . inet_service; counter; timeout 300s; size 65536; }
add element inet global test1 { 1.1.1.1 . udp . 20 }
add element inet global test1 { 1.1.1.1 . tcp . 21 }
add set inet global test2 { type ipv4_addr . inet_proto . inet_service; size 65536; }
```

## LIMITATIONS
A few IP sets options may be not supported because they are not yet implemented in nftables(8).

Contrary to nftables(8), IP sets are not attached to a specific table. The translation utility assumes that sets are created in a table whose name is global and family is inet. You might want to update the resulting translation to use a different table name and family for your sets.

To get up-to-date information about this, please head to https://wiki.nftables.org/.

## SEE ALSO
nft(8), ipset(8)

## AUTHORS
The nftables framework has been written by the Netfilter Project (https://www.netfilter.org).

This manual page was written by Pablo Neira Ayuso <pablo@netfilter.org>.

This documentation is free/libre under the terms of the GPLv2+.

This tool was funded through the NGI0 PET Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 825310.