ip_address

Manage ip address interfaces on a remote server in ruby
linux manual

Actions

name	description
list	Shows IPv4 and IPv6 addresses assigned to all network interfaces. The ‘show’ subcommand can be omitted.
add	Add an IPv4 or IPv6 address to a network interface
delete	Delete an address from a network interface
flush	This command flushes the protocol addresses selected by some criteria.

List

Get details for protocol addresses.

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.
scope	`string`	Only list addresses with this scope.
to	`string`	Only list addresses matching this prefix.
label	`string`	Only list addresses with labels matching the PATTERN.
dynamic	`boolean`	(IPv6 only) only list addresses installed due to stateless address configuration.
permanent	`boolean`	(IPv6 only) only list addresses installed due to permanent address configuration
tenative	`boolean`	(IPv6 only) only list addresses which have not yet passed duplicate address detection.
deprecated	`boolean`	(IPv6 only) only list deprecated addresses.
primary	`boolean`	List only primary addresses, in IPv6 exclude temporary ones.
secondary	`boolean`	List temporary IPv6 or secondary IPv4 addresses only.
up	`boolean`	Only list running interfaces.

Result

Returns an array of IPAddressProperty structs.

IPAddressProperty 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_type	`string`	For virtual devices, the link type
mac_address	`string`	Unique ID assigned to the interface device.
address_info	`array`	Array of IPAddressInfo structs set on the interface
stats	`IPStats`	TX and RX stats for the interface.

IPAddressInfo Fields

Field	Type	Description
family	`string`	The protocol family identifier
ip	`IPAddr`	IP address assigned to this interface.
broadcast	`string`	The broadcast address.
scope	`string`	Ip addresses and routes have a scope to indicate to the kernel the distance to other networks/addresses
dynamic	`boolean`	Is this a dynamic address
valid_life_time	`integer`	Lifetime setting that determines how long the address can be used before it must be refreshed or replaced.
preferred_life_time	`integer`	This is the length of time during which the address can be used freely as both a source and a destination address for traffic exchanges with other devices

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

host.ip('address', 'show', up: true, family: 'ipv4').to_a
[
  [0] #<Struct:Kanrisuru::Core::IP::IPAddressProperty:0x00000dc0
    address_info = [
      [0] #<Struct:Kanrisuru::Core::IP::IPAddressInfo:0x00000e10
        broadcast = nil,
        dynamic = false,
        family = "inet",
        ip = #<IPAddr: IPv4:127.0.0.1/255.255.255.255>,
        preferred_life_time = 4294967295,
        scope = "host",
        valid_life_time = 4294967295
      >
    ],
    flags = [
      [0] "LOOPBACK",
      [1] "UP",
      [2] "LOWER_UP"
    ],
    group = "default",
    index = 1,
    link_type = nil,
    mac_address = nil,
    mtu = 65536,
    name = "lo",
    qdisc = "noqueue",
    qlen = 1000,
    state = "UNKNOWN",
    stats = nil
  >,
  [1] #<Struct:Kanrisuru::Core::IP::IPAddressProperty:0x00000ff0
    address_info = [
      [0] #<Struct:Kanrisuru::Core::IP::IPAddressInfo:0x00001040
        broadcast = "10.0.0.255",
        dynamic = true,
        family = "inet",
        ip = #<IPAddr: IPv4:10.0.0.100/255.255.255.255>,
        preferred_life_time = 65303,
        scope = "global",
        valid_life_time = 65303
      >
    ],
    flags = [
      [0] "BROADCAST",
      [1] "MULTICAST",
      [2] "UP",
      [3] "LOWER_UP"
    ],
    group = "default",
    index = 2,
    link_type = nil,
    mac_address = nil,
    mtu = 1500,
    name = "ens3",
    qdisc = "fq_codel",
    qlen = 1000,
    state = "UP",
    stats = nil
  >
]

Add

Add new protocol address to an interface.

This command needs escalated privileges to make changes to certain files and directory ownership.

Parameters

Field	Type	Description
dev	`string`	Name of device.
label	`string`	Each address may be tagged with a label string.
scope	`string`	The scope of the area where this address is valid. Scope values include: global, site, link and host.
address	`string`	The IPV4 or IPV6 address to add to 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('address', 'add', dev: 'ens3', address: '192.16.9.13')
result.success?
true

Delete

Delete a protocol address from an interface.

This command needs escalated privileges to make changes to certain files and directory ownership.

Parameters

Field	Type	Description
dev	`string`	Name of device.
label	`string`	Each address may be tagged with a label string.
scope	`string`	The scope of the area where this address is valid. Scope values include: global, site, link and host.
address	`string`	The IPV4 or IPV6 address to add to 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('address', 'delete', dev: 'ens3', address: '192.16.9.13')
result.success?
true

Flush

This command flushes the protocol addresses selected by some criteria.

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

Parameters

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

List Parameters

Example

host.su('root')
result = host.ip('address', 'flush', dev: 'ens3', scope: 'global')
result.success?
true

Result

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

Tested On

Ubuntu, Debian, Centos, Fedora, Redhat, OpenSuse, SLES