This is the development version of Kanrisuru. Since this is still a pre-1.0 release, we don't recommend using this in system-critical production environments.

Kanrisuru

ip_link

Manage ip network device configuration on a remote server in ruby.
linux manual

Actions

name description
list Display device attributes.
add Add virtual link.
delete Delete virtual link.
set Change device attributes
Field Description
bridge Ethernet Bridge device
bond Bonding device
dummy Dummy network interface
hsr High-availability Seamless Redundancy device
ifb Intermediate Functional Block device
ipoib IP over Infiniband device
macvlan Virtual interface base on link layer address (MAC)
macvtap Virtual interface based on link layer address (MAC) and TAP.
vcan Virtual Controller Area Network interface
vxcan Virtual Controller Area Network tunnel interface
veth Virtual ethernet interface
vlan 802.1q tagged virtual LAN interface
vxlan Virtual eXtended LAN
ip6tnl Virtual tunnel interface IPv4|IPv6 over IPv6
ipip Virtual tunnel interface IPv4 over IPv4
sit Virtual tunnel interface IPv6 over IPv4
gre Virtual tunnel interface GRE over IPv4
gretap Virtual L2 tunnel interface GRE over IPv4
erspan Encapsulated Remote SPAN over GRE and IPv4
ip6gre Virtual tunnel interface GRE over IPv6
ip6gretap Virtual L2 tunnel interface GRE over IPv6
ip6erspan Encapsulated Remote SPAN over GRE and IPv6
vti Virtual tunnel interface
nlmon Netlink monitoring device
ipvlan Interface for L3 (IPv6/IPv4) based VLANs
ipvtap Interface for L3 (IPv6/IPv4) based VLANs and TAP
lowpan Interface for 6LoWPAN (IPv6) over IEEE 802.15.4 / Bluetooth
geneve GEneric NEtwork Virtualization Encapsulation
bareudp Bare UDP L3 encapsulation support
macsec Interface for IEEE 802.1AE MAC Security (MACsec)
vrf Interface for L3 VRF domains
netdevsim Interface for netdev API tests
rmnet Qualcomm rmnet device
xfrm Virtual xfrm interface

List

List the device attributes.

Parameters

Field Type Description
family string
 		Specifies the protocol family to use. The protocol family identifier can be one of inet, inet6, bridge, mpls or link.
stats boolean
 		Output additional statsitical information.
dev string
 		Name of device.
group string
 		GROUP specifies what group of devices to show.
up boolean
 		Only list running interfaces.
master string
 		Specify the master device which enslaves devices to show.
vrf string
 		Specify the VRF which enslaves devices to show.
type string
 		Specify the type of devices to show.

Result

Returns an array of IPAddressLabel structs.

IPLinkProperty Fields

Field Type Description
index integer Position of address property
name string Name of the device
flags array Specific flags that indicate what the state the device may be in.
mtu integer Maximum transmission unit (MTU), is the largest data packet that the network-connected device will accept.
qdisc string An algorithm that manages the queue of a device, either incoming (ingress) or outgoing (egress).
state string What state the interface is in, commonly UP, DOWN, UNKNOWN.
group string What group the interface belongs to, belongs to the default group by default.
qlen string Ethernet buffer transmit queue length
link_mode string Either in DEFAULT or DORMANT mode.
link_type string For virtual devices, the link type
mac_address string Unique ID assigned to the interface device.
alias string A symbolic name for easy reference.
stats IPStats TX and RX stats for the interface.

IPStats Fields

Field Type Description
rx IPStatsRX Receive stats
tx IPStatsTX Transmit stats

IPStatsRX Fields

Field Type Description
bytes integer Number of good received bytes
packets integer Number of good packets received by the interface.
errors integer Total number of bad packets received on this network device.
dropped integer Number of packets received but not processed, e.g. due to lack of resources or unsupported protocol.
over_errors integer Receiver FIFO overflow event counter.
multicast integer Multicast packets received.

IPStatsTX Fields

Field Type Description
bytes integer Number of good transmitted bytes.
packets integer Number of packets successfully transmitted.
errors integer Total number of transmit problems.
dropped integer Number of packets dropped on their way to transmission, e.g. due to lack of resources.
carrier_errors integer Number of frame transmission errors due to loss of carrier during transmission.
collisions integer Number of collisions during packet transmissions.

Example

result = host.ip('link', 'list')
result.success?
true

result.to_a
[
  [0] #<Struct:Kanrisuru::Core::IP::IPLinkProperty:0x00000668
    alias = nil,
    flags = [
      [0] "LOOPBACK",
      [1] "UP",
      [2] "LOWER_UP"
    ],
    group = "default",
    index = 1,
    link_mode = "DEFAULT",
    link_type = "loopback",
    mac_address = "00:00:00:00:00:00",
    mtu = 65536,
    name = "lo",
    qdisc = "noqueue",
    qlen = 1000,
    state = "UNKNOWN",
    stats = nil
  >,
  [1] #<Struct:Kanrisuru::Core::IP::IPLinkProperty:0x00000848
    alias = nil,
    flags = [
      [0] "BROADCAST",
      [1] "MULTICAST",
      [2] "UP",
      [3] "LOWER_UP"
    ],
    group = "default",
    index = 2,
    link_mode = "DEFAULT",
    link_type = "ether",
    mac_address = "ea:16:3f:76:53:92",
    mtu = 1500,
    name = "ens3",
    qdisc = "fq_codel",
    qlen = 1000,
    state = "UP",
    stats = nil
  >
]

Add

Add virtual link

Parameters

Field Type Description
dev string
 		Specifies the physical device to act operate on.
name string
 		Specifies the name of the new virtual device.
mtu string
 		Maximum transmission unit (MTU), is the largest data packet that the network-connected device will accept.
index string
 		Specifies the desired index of the new virtual device. The link creation fails, if the index is busy.
numtxqueues string
 		Specifies the number of transmit queues for new device.
numrxqueues string
 		Specifies the number of receive queues for new device.
gso_max_size string
 		Specifies the recommended maximum size of a Generic Segment Offload packet the new device should accept.
gso_max_segs string
 		Specifies the recommended maximum number of a Generic Segment Offload segments the new device should accept.
type string
 		Specify the type of devices to show.
VLAN params
protocol string
 		either 802.1Q or 802.1ad.
id string
 		Specifies the VLAN Identifier to use. Note that numbers with a leading " 0 " or " 0x " are interpreted as octal or hexadecimal, respectively.
reorder_hdr string
 		Specifies whether ethernet headers are reordered or not (on or off)
gvrp string
 		Specifies whether this VLAN should be registered using GARP VLAN Registration Protocol (on or off).
mvrp string
 		Specifies whether this VLAN should be registered using Multiple VLAN Registration Protoco (on or off).
loose_binding string
 		Specifies whether the VLAN device state is bound to the physical device state.
bridge_binding string
 		Specifies whether the VLAN device link state tracks the state of bridge ports that are members of the VLAN.
ingress_qos_map string
 		defines a mapping of VLAN header prio field to the Linux internal packet priority on incoming frames. The format is FROM:TO with multiple mappings separated by spaces.
egress-qos-map string
 		defines a mapping of Linux internal packet priority to VLAN header prio field but for outgoing frames.
VXLAN params
id integer
 		specifies the VXLAN Network Identifier (or VXLAN Segment Identifier) to use.
dev string
 		specifies the physical device to use for tunnel endpoint communication.
group string
 		specifies the multicast IP address to join. This parameter cannot be specified with the remote parameter.
remote string
 		specifies the unicast destination IP address to use in outgoing packets when the destination link layer address is not known in the VXLAN device forwarding database. This parameter cannot be specified with the group parameter.
local string
 		specifies the source IP address to use in outgoing packets.
ttl string
 		specifies the TTL value to use in outgoing packets.
tos string
 		specifies the TOS value to use in outgoing packets.
df string
 		specifies the usage of the Don't Fragment flag (DF) bit in outgoing packets with IPv4 headers.
flowlabel string
 		specifies the flow label to use in outgoing packets.
dstport string
 		specifies the UDP destination port to communicate to the remote VXLAN tunnel endpoint.
srcport string
 		specifies the range of port numbers to use as UDP source ports to communicate to the remote VXLAN tunnel endpoint.
learning boolean
 		specifies if unknown source link layer addresses and IP addresses are entered into the VXLAN device forwarding database.
rsc boolean
 		specifies if route short circuit is turned on.
proxy boolean
 		specifies ARP proxy is turned on.
l2miss boolean
 		specifies if netlink LLADDR miss notifications are generated.
l3miss boolean
 		specifies if netlink IP ADDR miss notifications are generated.
udpcsum boolean
 		specifies if UDP checksum is calculated for transmitted packets over IPv4.
udp6zerocsumtx boolean
 		skip UDP checksum calculation for transmitted packets over IPv6.
udp6zerocsumrx boolean
 		allow incoming UDP packets over IPv6 with zero checksum field.
ageing integer
 		specifies the lifetime in seconds of FDB entries learnt by the kernel.
maxaddress integer
 		specifies the maximum number of FDB entries.
external boolean
 		specifies whether an external control plane (e.g. ip route encap) or the internal FDB should be used.
gbp boolean
 		enables the Group Policy extension (VXLAN- GBP).
gpe boolean
 		enables the Generic Protocol extension (VXLAN-GPE). Currently, this is only supported together with the external keyword.
veth, vxcan params
peer_name string
 		specifies the virtual pair device name of the VETH/VXCAN tunnel.
IPIP & SIT params
remote string
 		specifies the remote address of the tunnel.
local string
 		specifies the fixed local address for tunneled packets. It must be an address on another interface on this host.
encap string
 		specifies type of secondary UDP encapsulation. "fou" indicates Foo- Over-UDP, "gue" indicates Generic UDP Encapsulation (fou | gue | none).
encap_sport string
 		specifies the source port in UDP encapsulation. PORT indicates the port by number, "auto" indicates that the port number should be chosen automatically (the kernel picks a flow based on the flow hash of the encapsulated packet).
encap_csum boolean
 		specifies if UDP checksums are enabled in the secondary encapsulation.
encap_remcsum boolean
 		specifies if Remote Checksum Offload is enabled. This is only applicable for Generic UDP Encapsulation.
mode string
 		specifies mode in which device should run. "ip6ip" indicates IPv6-Over-IPv4, "ipip" indicates "IPv4-Over-IPv4", "mplsip" indicates MPLS-Over-IPv4, "any" indicates IPv6, IPv4 or MPLS Over IPv4. Supported for SIT where the default is "ip6ip" and IPIP where the default is "ipip". IPv6-Over-IPv4 is not supported for IPIP (ip6ip | ipip | mplsip | any).
external boolean
 		make this tunnel externally controlled (e.g. ip route encap).
GRE params
remote string
 		specifies the remote address of the tunnel.
local string
 		specifies the fixed local address for tunneled packets. It must be an address on another interface on this host.
iseq boolean
 		Serialize all input packets.
oseq boolean
 		Serialize all outgoing packets.
ikey string
 boolean
 		Use keyed GRE with key. Is either a number or an IPv4 address-like dotted quad.
okey string
 boolean
 		Use keyed GRE with key. Is either a number or an IPv4 address-like dotted quad.
icsum boolean
 		generate/require checksums for tunneled packets. The icsum flag requires that all input packets have the correct checksum.
ocsum boolean
 		generate/require checksums for tunneled packets. The icsum flag requires that all input packets have the correct checksum.
ttl string
 		specifies the TTL value to use in outgoing packets.
tos string
 		specifies the TOS value to use in outgoing packets.
pmtudisc boolean
 		enables/disables Path MTU Discovery on this tunnel. It is enabled by default. Note that a fixed ttl is incompatible with this option: tunneling with a fixed ttl always makes pmtu discovery.
ignore-df boolean
 		enables/disables IPv4 DF suppression on this tunnel. Normally datagrams that exceed the MTU will be fragmented; the presence of the DF flag inhibits this, resulting instead in an ICMP Unreachable (Fragmentation Required) message. Enabling this attribute causes the DF flag to be ignored.
dev string
 		specifies the physical device to use for tunnel endpoint communication.
encap string
 		specifies type of secondary UDP encapsulation. "fou" indicates Foo- Over-UDP, "gue" indicates Generic UDP Encapsulation (fou | gue | none).
encap_sport string
 		specifies the source port in UDP encapsulation. PORT indicates the port by number, "auto" indicates that the port number should be chosen automatically (the kernel picks a flow based on the flow hash of the encapsulated packet).
encap_csum boolean
 		specifies if UDP checksums are enabled in the secondary encapsulation.
encap_remcsum boolean
 		specifies if Remote Checksum Offload is enabled. This is only applicable for Generic UDP Encapsulation.
external boolean
 		make this tunnel externally controlled (e.g. ip route encap).
IP6GRE/IP6GRETAP params
remote string
 		specifies the remote address of the tunnel.
local string
 		specifies the fixed local address for tunneled packets. It must be an address on another interface on this host.
iseq boolean
 		Serialize all input packets.
oseq boolean
 		Serialize all outgoing packets.
ikey string
 boolean
 		Use keyed GRE with key. Is either a number or an IPv4 address-like dotted quad.
okey string
 boolean
 		Use keyed GRE with key. Is either a number or an IPv4 address-like dotted quad.
icsum boolean
 		generate/require checksums for tunneled packets. The icsum flag requires that all input packets have the correct checksum.
ocsum boolean
 		generate/require checksums for tunneled packets. The icsum flag requires that all input packets have the correct checksum.
hoplimit integer
 		specifies Hop Limit value to use in outgoing packets.
allow-localremote boolean
 		specifies whether to allow remote endpoint to have an address configured on local host.
tclass string
 		specifies the traffic class field on tunneled packets, which can be specified as either a two-digit hex value (e.g. c0) or a predefined string (e.g. internet). The value inherit causes the field to be copied from the original IP header. The values inherit/STRING or inherit/00..ff will set the field to STRING or 00..ff when tunneling non-IP packets. The default value is 00.
external string
 		make this tunnel externally controlled (or not, which is the default). In the kernel, this is referred to as collect metadata mode. This flag is mutually exclusive with the remote, local, seq, key, csum, hoplimit, encaplimit, flowlabel and tclass options.
IPoIB params
pkey string
 		Specifies the IB P-Key to use.
mode string
 		Specifies the mode (datagram or connected) to use.
ERSPAN params
remote string
 		specifies the remote address of the tunnel.
local string
 		specifies the fixed local address for tunneled packets. It must be an address on another interface on this host.
erspan_ver string
 		specifies the ERSPAN version number. version indicates the ERSPAN version to be created: 0 for version 0 type I, 1 for version 1 (type II) or 2 for version 2 (type III).
erspan string
 		specifies the ERSPAN v1 index field. IDX indicates a 20 bit index/port number associated with the ERSPAN traffic's source port and direction.
erspan_dir string
 		specifies the ERSPAN v2 mirrored traffic's direction.
erspan_hwid string
 		an unique identifier of an ERSPAN v2 engine within a system. hwid is a 6-bit value for users to configure.
allow_localremote boolean
 		specifies whether to allow remote endpoint to have an address configured on local host.
external boolean
 		make this tunnel externally controlled (or not, which is the default). In the kernel, this is referred to as collect metadata mode. This flag is mutually exclusive with the remote, local, erspan_ver, erspan, erspan_dir and erspan_hwid options.
GENEVE params
id string
 		specifies the Virtual Network Identifier to use.
remote string
 		specifies the unicast destination IP address to use in outgoing packets.
ttl string
 		specifies the TTL value to use in outgoing packets. "0" or "auto" means use whatever default value, "inherit" means inherit the inner protocol's ttl. Default option is "0".
tos string
 		specifies the TOS value to use in outgoing packets.
df string
 		specifies the usage of the Don't Fragment flag (DF) bit in outgoing packets with IPv4 headers. The value inherit causes the bit to be copied from the original IP header. The values unset and set cause the bit to be always unset or always set, respectively. By default, the bit is not set.
flowlabel string
 		specifies the flow label to use in outgoing packets.
dstport string
 		select a destination port other than the default of 6081.
external boolean
 		make this tunnel externally controlled (or not, which is the default). This flag is mutually exclusive with the id, remote, ttl, tos and flowlabel options.
udpcsum boolean
 		specifies if UDP checksum is calculated for transmitted packets over IPv4.
udp6zerocsumtx boolean
 		skip UDP checksum calculation for transmitted packets over IPv6.
udp6zerocsumrx boolean
 		allow incoming UDP packets over IPv6 with zero checksum field.
Bareudp params
dstport string
 		specifies the destination port for the UDP tunnel.
ethertype string
 		specifies the ethertype of the L3 protocol being tunnelled.
srcportmin string
 		selects the lowest value of the UDP tunnel source port range.
multiproto boolean
 		activates support for protocols similar to the one specified by ethertype. When ETHERTYPE is "mpls_uc" (that is, unicast MPLS), this allows the tunnel to also handle multicast MPLS. When ETHERTYPE is "ipv4", this allows the tunnel to also handle IPv6. This option is disabled by default.
MACVLAN and MACVTAP params
type string
 		(macvlan | macvtap) specifies the link type to use. macvlan creates just a virtual interface, while macvtap in addition creates a character device /dev/tapX to be used just like a tuntap device.
mode string
 		Set mode to private, vepa, bridge, passthru, or source.
HSR params
slave1 string
 		Specifies the physical device used for the first of the two ring ports.
slave2 string
 		Specifies the physical device used for the second of the two ring ports.
supervision integer
 		The last byte of the multicast address used for HSR supervision frames. Default option is "0", possible values 0-255.
version string
 		Selects the protocol version of the interface. Default option is "0", which corresponds to the 2010 version of the HSR standard. Option "1" activates the 2012 version.
proto string
 		Selects the protocol at the interface. Default option is "0", which corresponds to the HSR standard. Option "1" activates the Parallel Redundancy Protocol (PRP).
BRIDGE params
ageing_time string
 		configure the bridge's FDB entries ageing time, ie the number of seconds a MAC address will be kept in the FDB after a packet has been received from that address. after this time has passed, entries are cleaned up.
group_fwd_mask string
 		set the group forward mask. This is the bitmask that is applied to decide whether to forward incoming frames destined to link-local addresses, ie addresses of the form 01:80:C2:00:00:0X (defaults to 0, ie the bridge does not forward any link-local frames).
group_address string
 		set the MAC address of the multicast group this bridge uses for STP. The address must be a link-local address in standard Ethernet MAC address format, ie an address of the form 01:80:C2:00:00:0X, with X in [0, 4..f].
forward_delay string
 		set the forwarding delay in seconds, ie the time spent in LISTENING state (before moving to LEARNING) and in LEARNING state (before moving to FORWARDING). Only relevant if STP is enabled. Valid values are between 2 and 30.
hello_time integer
 		set the time in seconds between hello packets sent by the bridge, when it is a root bridge or a designated bridges. Only relevant if STP is enabled. Valid values are between 1 and 10.
max_age string
 		set the hello packet timeout, ie the time in seconds until another bridge in the spanning tree is assumed to be dead, after reception of its last hello message. Only relevant if STP is enabled. Valid values are between 6 and 40.
stp_state string
 		turn spanning tree protocol on (STP_STATE > 0) or off (STP_STATE == 0). for this bridge.
priority integer
 		set this bridge's spanning tree priority, used during STP root bridge election.
vlan_filtering integer
 		turn VLAN filtering on (VLAN_FILTERING > 0) or off (VLAN_FILTERING == 0). When disabled, the bridge will not consider the VLAN tag when handling packets.
vlan_protocol string
 		set the protocol used for VLAN filtering (802.1Q, 802.1ad).
vlan_default_pvid string
 		set the default PVID (native/untagged VLAN ID) for this bridge.
vlan_stats_enabled integer
 		enable (VLAN_STATS_ENABLED == 1) or disable (VLAN_STATS_ENABLED == 0) per-VLAN stats accounting.
vlan_stats_per_port integer
 		enable (VLAN_STATS_PER_PORT == 1) or disable (VLAN_STATS_PER_PORT == 0) per-VLAN per-port stats accounting. Can be changed only when there are no port VLANs configured.
mcast_snooping integer
 		turn multicast snooping on (MULTICAST_SNOOPING > 0) or off (MULTICAST_SNOOPING == 0).
mcast_router integer
 		set bridge's multicast router if IGMP snooping is enabled. MULTICAST_ROUTER is an integer value having the following meaning: 0 - disabled. 1 - automatic (queried). 2 - permanently enabled.
mcast_query_use_ifaddr string
 		whether to use the bridge's own IP address as source address for IGMP queries (MCAST_QUERY_USE_IFADDR > 0) or the default of 0.0.0.0 (MCAST_QUERY_USE_IFADDR == 0).
mcast_querier integer
 		Enable (MULTICAST_QUERIER > 0) or disable (MULTICAST_QUERIER == 0) IGMP querier, ie sending of multicast queries by the bridge (default: disabled).
mcast_querier_interval integer
 		Interval between queries sent by other routers. if no queries are seen after this delay has passed, the bridge will start to send its own queries (as if mcast_querier was enabled).
mcast_hash_elasticity integer
 		Set multicast database hash elasticity, ie the maximum chain length in the multicast hash table (defaults to 4).
mcast_hash_max integer
 		Set maximum size of multicast hash table (defaults to 512, value must be a power of 2).
mcast_last_member_count integer
 		set multicast last member count, ie the number of queries the bridge will send before stopping forwarding a multicast group after a "leave" message has been received (defaults to 2).
mcast_last_member_interval integer
 		interval between queries to find remaining members of a group, after a "leave" message is received.
mcast_startup_query_count integer
 		set the number of IGMP queries to send during startup phase (defaults to 2).
mcast_startup_query_interval integer
 		interval between queries in the startup phase.
mcast_query_interval integer
 		Interval between queries sent by the bridge after the end of the startup phase.
mcast_query_response_interval integer
 		Set the Max Response Time/Maximum Response Delay for IGMP/MLD queries sent by the bridge.
mcast_membership_interval integer
 		delay after which the bridge will leave a group, if no membership reports for this group are received.
mcast_stats_enabled integer
 		enable (MCAST_STATS_ENABLED > 0) or disable (MCAST_STATS_ENABLED == 0) multicast (IGMP/MLD) stats accounting.
mcast_igmp_version integer
 		set the IGMP version.
mcast_mld_version integer
 		set the MLD version.
nf_call_iptables integer
 		enable (NF_CALL_IPTABLES > 0) or disable (NF_CALL_IPTABLES == 0) iptables hooks on the bridge.
nf_call_ip6tables integer
 		enable (NF_CALL_IP6TABLES > 0) or disable (NF_CALL_IP6TABLES == 0) ip6tables hooks on the bridge.
nf_call_arptables integer
 		enable (NF_CALL_ARPTABLES > 0) or disable (NF_CALL_ARPTABLES == 0) arptables hooks on the bridge.
MACsec params
address string
 		sets the system identifier component of secure channel for this MACsec device.
port integer
 		sets the port number component of secure channel for this MACsec device, in a range from 1 to 65535 inclusive. Numbers with a leading " 0 " or " 0x " are interpreted as octal and hexadecimal, respectively.
sci string
 		Sets the secure channel identifier for this MACsec device. SCI is a 64bit wide number in hexadecimal format.
cipher string
 		defines the cipher suite to use.
icvlen string
 		sets the length of the Integrity Check Value (ICV).
encrypt boolean
 		switches between authenticated encryption, or authenticity mode only.
send_sci boolean
 		specifies whether the SCI is included in every packet, or only when it is necessary.
end_station boolean
 		sets the End Station bit.
scb boolean
 		sets the Single Copy Broadcast bit.
protect boolean
 		enables MACsec protection on the device.
replay boolean
 		enables replay protection on the device.
window integer
 		sets the size of the replay window.
validate string
 		Set the validation mode on the device to strict, check or disabled.
encodingsa integer
 		sets the active secure association for transmission.
VRF params
table integer
 		table id associated with VRF device
RMNET params
mux_id integer
 		specifies the mux identifier for the rmnet device, possible values 1-254.
XFRM params
dev string
 		specifies the underlying physical interface from which transform traffic is sent and received.
if_id string
 		specifies the hexadecimal lookup key used to send traffic to and from specific xfrm policies. Policies must be configured with the same key. If not set, the key defaults to 0 and will match any policies which similarly do not have a lookup key configuration.

Result

No explicit data struct returned, only option is success?, failure?, and status to see if the program exited properly.

Example

host.su('root')
result = host.ip('link', 'add', dev: 'ens3.10', mtu: 9000, type: 'vlan', type_opts: { protocol: '802.1Q', id: 10 })
result.success?
true

Delete

Delete virtual link

Parameters

Field Type Description
dev string
 		specifies the virtual device to act operate on.
group string
 		specifies the group of virtual links to delete. Group 0 is not allowed to be deleted since it is the default group.
type string
 		specifies the type of the device.

Result

No explicit data struct returned, only option is success?, failure?, and status to see if the program exited properly.

Example

host.su('root')
result = host.ip('link', 'delete', dev: 'ens3.10')
result.success?
true

Set

Change device attributes

Parameters

Field Type Description
dev string
 		specifies the virtual device to act operate on.
group string
 		GROUP has a dual role: If both group and dev are present, then move the device to the specified group. If only a group is specified, then the command operates on all devices in that group.
direction string
 		Set the devices direction to up or down.
arp string
 		change the NOARP flag on the device (on or off).
multicast string
 		change the MULTICAST flag on the device (on or off).
allmulticast string
 		change the ALLMULTI flag on the device (on or off). When enabled, instructs network driver to retrieve all multicast packets from the network to the kernel for further processing.
promisc string
 		change the PROMISC flag on the device (on or off). When enabled, activates promiscuous operation of the network device.
protodown string
 		change the PROTODOWN state on the device (on or off). Indicates that a protocol error has been detected on the port. Switch drivers can react to this error by doing a phys down on the switch port.
protodown_reason integer
 		set PROTODOWN reasons on the device. protodown reason bit names can be enumerated under /etc/iproute2/protodown_reasons.d/. possible reasons bits 0-31
dynamic string
 		change the DYNAMIC flag on the device (on or off). Indicates that address can change when interface goes down (currently NOT used by the Linux).
name string
 		change the name of the device. This operation is not recommended if the device is running or has some addresses already configured.
txqueuelen integer
 		change the transmit queue length of the device.
mtu integer
 		change the MTU of the device.
address string
 		change the station address of the interface.
broadcast string
 		change the link layer broadcast address
peer string
 		change the link layer peer address
netns string
 integer
 		move the device to the network namespace associated with name NETNSNAME or process PID. Some devices are not allowed to change network namespace: loopback, bridge, wireless. These are network namespace local devices. In such case ip tool will return "Invalid argument" error.
alias string
 		give the device a symbolic name for easy reference.
group string
 		specify the group the device belongs to. The available groups are listed in file /etc/iproute2/group
VF params
vf integer
 		specify a Virtual Function device to be configured. The associated PF device must be specified using the dev parameter.
mac string
 		change the station address for the specified VF. The vf parameter must be specified.
vlan integer
 		change the assigned VLAN for the specified VF. When specified, all traffic sent from the VF will be tagged with the specified VLAN ID. Incoming traffic will be filtered for the specified VLAN ID, and will have all VLAN tags stripped before being passed to the VF. Setting this parameter to 0 disables VLAN tagging and filtering. The vf parameter must be specified.
qos integer
 		assign VLAN QOS (priority) bits for the VLAN tag. When specified, all VLAN tags transmitted by the VF will include the specified priority bits in the VLAN tag. If not specified, the value is assumed to be 0. Both the vf and vlan parameters must be specified. Setting both vlan and qos as 0 disables VLAN tagging and filtering for the VF.
proto string
 		Assign VLAN PROTOCOL for the VLAN tag, either 802.1Q or 802.1ad. Setting to 802.1ad, all traffic sent from the VF will be tagged with VLAN S-Tag. Incoming traffic will have VLAN S-Tags stripped before being passed to the VF. Setting to 802.1ad also enables an option to concatenate another VLAN tag, so both S-TAG and C-TAG will be inserted/stripped for outgoing/incoming traffic, respectively. If not specified, the value is assumed to be 802.1Q. Both the vf and vlan parameters must be specified.
rate integer
 		change the allowed transmit bandwidth, in Mbps, for the specified VF. Setting this parameter to 0 disables rate limiting. vf parameter must be specified. Please use new API max_tx_rate option instead.
max_tx_rate integer
 		change the allowed maximum transmit bandwidth, in Mbps, for the specified VF. Setting this parameter to 0 disables rate limiting. vf parameter must be specified.
min_tx_rate integer
 		change the allowed minimum transmit bandwidth, in Mbps, for the specified VF. Minimum TXRATE should be always <= Maximum TXRATE. Setting this parameter to 0 disables rate limiting. vf parameter must be specified.
spoofchk string
 		turn packet spoof checking on or off for the specified VF.
query_rss string
 		toggle the ability of querying the RSS configuration of a specific VF. VF RSS information like RSS hash key may be considered sensitive on some devices where this information is shared between VF and PF and thus its querying may be prohibited by default.
state string
 		set the virtual link state as seen by the specified VF. Setting to auto means a reflection of the PF link state, enable lets the VF to communicate with other VFs on this host even if the PF link state is down, disable causes the HW to drop any packets sent by the VF.
trust string
 		trust the specified VF user. This enables that VF user can set a specific feature which may impact security and/or performance. (e.g. VF multicast promiscuous mode)
node_guid integer
 		configure node GUID for Infiniband VFs.
port_guid integer
 		configure port GUID for Infiniband VFs.
xdp string
 		Set (or unset) a XDP ("eXpress Data Path") BPF program to run on every packet at driver level (object | pinned | off).
object string
 		Attaches a XDP/BPF program to the given device. The FILE points to a BPF ELF file (f.e. generated by LLVM) that contains the BPF program code, map specifications, etc.
section string
 		Specifies a section name that contains the BPF program code. If no section name is specified, the default one ("prog") will be used. This option is to be passed with the object option.
verbose boolean
 		Act in verbose mode. For example, even in case of success, this will print the verifier log in case a program was loaded from a BPF ELF file.
pinned string
 		Attaches a XDP/BPF program to the given device. The FILE points to an already pinned BPF program in the BPF file system. The option section doesn't apply here, but otherwise semantics are the same as with the option object described already.
master string
 boolean
 		set master device of the device (enslave device).
addrgenmode string
 		Set the IPv6 address generation mode (eui64 | none | stable_secret | random)
link-netnsid boolean
 		Set peer netnsid for a cross-netns interface
type string
 		Change type-specific settings, ie (bridge_slave, vf, bond_slave, macvlan)
Bridge Slave params
fdb_flush boolean
 		flush bridge slave's fdb dynamic entries.
state string
 		Set port state. STATE is a number representing the following states: 0 (disabled), 1 (listening), 2 (learning), 3 (forwarding), 4 (blocking).
priority integer
 		set port priority (allowed values are between 0 and 63, inclusively).
cost integer
 		set port cost (allowed values are between 1 and 65535, inclusively).
guard boolean
 		block incoming BPDU packets on this port.
hairpin boolean
 		enable hairpin mode on this port. This will allow incoming packets on this port to be reflected back.
fastleave boolean
 		enable multicast fast leave on this port.
root_block boolean
 		block this port from becoming the bridge's root port.
learning boolean
 		allow MAC address learning on this port.
flood boolean
 		open the flood gates on this port, i.e. forward all unicast frames to this port also. Requires proxy_arp and proxy_arp_wifi to be turned off.
proxy_arp boolean
 		enable proxy ARP on this port.
proxy_arp_wifi boolean
 		enable proxy ARP on this port which meets extended requirements by IEEE 802.11 and Hotspot 2.0 specifications.
mcast_router integer
 		configure this port for having multicast routers attached. A port with a multicast router will receive all multicast traffic. MULTICAST_ROUTER may be either 0 to disable multicast routers on this port, 1 to let the system detect the presence of of routers (this is the default), 2 to permanently enable multicast traffic forwarding on this port or 3 to enable multicast routers temporarily on this port, not depending on incoming queries.
mcast_fast_leave boolean
 		this is a synonym to the fastleave option above.
mcast_flood boolean
 		controls whether a given port will flood multicast traffic for which there is no MDB entry.
mcast_to_unicast boolean
 		controls whether a given port will replicate packets using unicast instead of multicast. By default this flag is off.
group_fwd_mask integer
 		set the group forward mask. This is the bitmask that is applied to decide whether to forward incoming frames destined to link-local addresses, ie addresses of the form 01:80:C2:00:00:0X (defaults to 0, ie the bridge does not forward any link-local frames coming on this port).
neigh_suppress boolean
 		controls whether neigh discovery (arp and nd) proxy and suppression is enabled on the port. By default this flag is off.
vlan_tunnel boolean
 		controls whether vlan to tunnel mapping is enabled on the port. By default this flag is off.
backup_port integer
 		if the port loses carrier all traffic will be redirected to the configured backup port
Bonding Slave params
queue_id integer
 		set the slave's queue ID (a 16bit unsigned value).

Result

No explicit data struct returned, only option is success?, failure?, and status to see if the program exited properly.

Example

host.su('root')
result = host.ip('link', 'set', dev: 'eth0', xdp: 'object', object: 'prog.o')
result.success?
true
On this page