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_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
On this page