avocado.utils.network package

Submodules

avocado.utils.network.common module

avocado.utils.network.common.run_command(command, host, sudo=False)

avocado.utils.network.exceptions module

exception avocado.utils.network.exceptions.NWException

Bases: Exception

Base Exception Class for all exceptions

avocado.utils.network.hosts module

This module provides an useful API for hosts in a network.

class avocado.utils.network.hosts.Host(host)

Bases: object

This class represents a base Host and shouldn’t be instantiated.

Use one of the child classes (LocalHost or RemoteHost).

During the initialization of a child, all interfaces will be detected and available via interfaces attribute. This could be accessed on LocalHost and RemoteHost instances.

So, for instance, you could have a local and a remote host:

remote = RemoteHost(host='foo', port=22,
                    username='foo', password='bar')
local = LocalHost()

You can iterate over the network interfaces of any host:

for i in remote.interfaces:
    print(i.name, i.is_link_up())
get_all_hwaddr()

Get a list of all mac address in the host

Returns:

list of mac addresses

get_default_route_interface()

Get a list of default routes interfaces

Returns:

list of interface names

get_interface_by_hwaddr(mac)

Return an interface that has a specific mac.

get_interface_by_ipaddr(ipaddr)

Return an interface that has a specific ipaddr.

property interfaces
validate_mac_addr(mac_id)

Check if mac address is valid. This method checks if the mac address is 12 digit hexadecimal number.

Valid:

36:84:37:5a:ea:02

Invalid:

36:84:37-5a-ea-02 36-84-37-5a-ea-02 36.84.37.5a.ea 36:84:37:5a:ea:0ff 2345:84:37:5a:ea:0 3684375aea02

Parameters:

mac_id – Network mac address

Returns:

True if a user provided a valid mac address else False

Return type:

bool

class avocado.utils.network.hosts.LocalHost(host='localhost')

Bases: Host

This class represents a local host and inherit from Host.

You should use this class when trying to get information about your localhost.

Example:

local = LocalHost()

class avocado.utils.network.hosts.RemoteHost(host, username, port=22, key=None, password=None)

Bases: Host

This class represents a remote host and inherit from Host.

You must provide at least an username to establish a connection.

Example with password:

remote = RemoteHost(host=’192.168.0.1’,

port=22, username=’foo’, password=’bar’)

You can also provide a key instead of a password.

avocado.utils.network.interfaces module

class avocado.utils.network.interfaces.NetworkInterface(if_name, host, if_type='Ethernet')

Bases: object

This class represents a network card interface (NIC).

An “NetworkInterface” is attached to some host. This could be an instance of LocalHost or RemoteHost. If a RemoteHost then all commands will be executed on a remote_session (host.remote_session). Otherwise will be executed locally.

Here you will find a few methods to perform basic operations on a NIC.

add_ipaddr(ipaddr, netmask)

Add an IP Address (with netmask) to the interface.

This method will try to add a new ipaddr/netmask this interface, if fails it will raise a NWException.

You must have sudo permissions to run this method on a host.

Parameters:

  • ipaddr – IP Address

  • netmask – Network mask

add_vlan_tag(vlan_num, vlan_name=None)

Configure 802.1Q VLAN tagging to the interface.

This method will attempt to add a VLAN tag to this interface. If it fails, the method will raise a NWException.

Parameters:

  • vlan_num – VLAN ID

  • vlan_name – option to name VLAN interface, by default it is named <interface_name>.<vlan_num>

are_packets_lost(peer_ip, options=None, sudo=False)

Check packet loss that occurs during ping.

Function returns True for 0% packet loss and False if packet loss occurs.

Parameters:

  • peer_ip – Peer IP address (IPv4 or IPv6)

  • options – Type is List. Options such as -c, -f. Default is None

  • sudo – If sudo permissions are needed. Default is False

bring_down()

Shutdown the interface.

This will shutdown the interface link. Be careful, you might lost connection to the host.

You must have sudo permissions to run this method on a host.

bring_up()

“Wake-up the interface.

This will wake-up the interface link.

You must have sudo permissions to run this method on a host.

property config_file_path
property config_filename
flush_ipaddr()

Flush all the IP address for this interface.

This method will try to flush the ip address from this interface and if fails it will raise a NWException. Be careful, you can lost connection.

You must have sudo permissions to run this method on a host.

get_device_IPI_name()

Function to convert IO device name to device_ipi names according to “/proc/interrupts” context. Ex: vnic@30000009 to vnic-30000009

:return : A converted Network device according to device_ipi name. :rtype : string

get_hwaddr()

Get the Hardware Address (MAC) of this interface.

This method will try to get the address and if fails it will raise a NWException.

get_ipaddrs(version=4)

Get the IP addresses from a network interface.

Interfaces can hold multiple IP addresses. This method will return a list with all addresses on this interface.

Parameters:

version – Address Family Version (4 or 6). This must be a integer and default is 4.

Returns:

IP address as string.

get_mtu()

Return the current MTU value of this interface.

This method will try to get the current MTU value, if fails will raise a NWException.

Check the admin link state is up or not.

Returns:

True or False, True if network interface state is ‘UP’ otherwise will return False.

is_available()

Check if interface is available.

This method checks if the interface is available.

rtype: bool

is_bond()

Check if interface is a bonding device.

This method checks if the interface is a bonding device or not.

rtype: bool

Check if the interface is up or not.

Returns:

True or False. True if admin link state and operational link state is up otherwise will return False.

Check Operational link state is up or not.

Returns:

True or False. True if operational link state is LOWER_UP, otherwise will return False.

is_sriov()

Check if interface is a SRIOV virtual interface.

This method checks if the interface is SRIOV logical interface or not.

rtype: bool

is_veth()

Check if interface is a Virtual Ethernet.

This method checks if the interface is a Virtual Ethernet or not.

rtype: bool

is_vnic()

Check if interface is a virtual network.

This method checks if the interface is a virtual NIC or not.

rtype: bool

netmask_to_cidr(netmask)

Function is used to check the netmask value and convert

it into short form (mask) of netmask values Example : 255.255.255.0 = 24 255.255.252.0 = 22

Parameters:

netmask – Netmask value example 255.255.255.0

Returns:

Returns mask value of given netmask

nm_flush_ipaddr()

Remove all the IPv4 address for this interface by using IP tool.

This method will explicitly identifies all available IP addresses with netmask of interfaces and deletes them.

You must have sudo permissions to run this method on a host.

ping_check(peer_ip, count=2, options=None)

This method will try to ping a peer address (IPv4 or IPv6).

You should provide a IPv4 or IPV6 that would like to ping. This method will try to ping the peer and if fails it will raise a NWException.

Parameters:

  • peer_ip – Peer IP address (IPv4 or IPv6)

  • count – How many packets to send. Default is 2

  • options – ping command options. Default is None

ping_flood(int_name, peer_ip, ping_count)

Function to start ping to remote machine with “-f” [ flood ] option, on given interface.

Also this function enables to track the live data to determine the ping flood failure, in case of failure the program will exit.

Parameters:

  • int_name – source interface name.

  • peer_ip – Peer IP address (IPv4 or IPv6)

  • ping_count – How many ICMP echo packets to send.

Returns:

returns True on successful ping flood. returns False on ping flood failure.

Return type:

boolean

remove_all_vlans()

Remove all VLANs of this interface.

This method will remove all the VLAN interfaces associated by the interface. If it fails, the method will raise a NWException.

remove_cfg_file()

Remove any config files that is created as a part of the test

remove_ipaddr(ipaddr, netmask)

Removes an IP address from this interface.

This method will try to remove the address from this interface and if fails it will raise a NWException. Be careful, you can lost connection.

You must have sudo permissions to run this method on a host.

Deletes virtual interface link.

This method will try to delete the virtual device link and the interface will no more be listed with ‘ip a’ and if fails it will raise a NWException. Be careful, you can lost connection.

You must have sudo permissions to run this method on a host.

remove_vlan_by_tag(vlan_num)

Remove the VLAN of the interface by tag number.

This method will try to remove the VLAN tag of this interface. If it fails, the method will raise a NWException.

Parameters:

vlan_num – VLAN ID

Returns:

True or False, True if it found the VLAN interface and removed it successfully, otherwise it will return False.

restore_from_backup()

Revert interface file from backup.

This method checks if a backup version is available for given interface then it copies backup file to interface file in /sysfs path.

restore_slave_cfg_file()

Restore or delete slave config files.

save(ipaddr, netmask)

Save current interface IP Address to the system configuration file.

If the ipaddr is valid (currently being used by the interface) this will try to save the current settings into /etc/. This check is necessary to avoid inconsistency. Before save, you should add_ipaddr, first.

Currently, only RHEL, Fedora and SuSE are supported. And this will create a backup file of your current configuration if found.

:param ipaddr : IP Address which need to configure for interface :param netmask: Network mask which is associated to the provided IP

set_hwaddr(hwaddr)

Sets a Hardware Address (MAC Address) to the interface.

This method will try to set a new hwaddr to this interface, if fails it will raise a NWException.

You must have sudo permissions to run this method on a host.

Parameters:

hwaddr – Hardware Address (Mac Address)

set_mtu(mtu, timeout=30)

Sets a new MTU value to this interface.

This method will try to set a new MTU value to this interface, if fails it will raise a NWException. Also it will wait until the Interface is up before returning or until timeout be reached.

You must have sudo permissions to run this method on a host.

Parameters:

  • mtu – mtu size that need to be set. This must be an int.

  • timeout – how many seconds to wait until the interface is up again. Default is 30.

property slave_config_filename
validate_ipv4_format(ip)

This function validates IPv4 address with following format set.

  1. A string in decimal-dot notation, consisting of four decimal integers in the inclusive range 0-255,separated by dots (e.g- 192.168.0.1).Each integer represents an octet in the address.

  2. An integer that fits into 32 bits.

  3. An integer packed into a bytes object of length 4.

And for IP address which are not met above conditions, raises AddressValueError and returns False.

Parameters:

ip – IP address

Returns:

True when IP address pattern/format matches if not return False

Return type:

boolean

validate_ipv4_netmask_format(netmask)

This function validates IPv4 Netmask address with following format set.

  1. A string in decimal-dot notation,consisting of four decimal integers starting from 255 and octets separated by dots (e.g 255.255.255.0)

  2. An integer packed into a bytes object of length 4

And for Netmask which are not met above conditions, [ eg : 255.0.255.0, 255.255.255, 255.255.255.256, 255.255.255.255.0] returns False.

Parameters:

netmask – netmask address

Returns:

True when netmask address pattern/format matches if not return False

Return type:

boolean

property vlans

Return all interface’s VLAN.

This is a dict were key is the VLAN number and the value is the name of the VLAN interface.

rtype: dict

avocado.utils.network.ports module

Module with network related utility functions

avocado.utils.network.ports.FAMILIES = (AddressFamily.AF_INET, AddressFamily.AF_INET6)

Families taken into account in this class

avocado.utils.network.ports.PROTOCOLS = (SocketKind.SOCK_STREAM, SocketKind.SOCK_DGRAM)

Protocols taken into account in this class

class avocado.utils.network.ports.PortTracker

Bases: Borg

Tracks ports used in the host machine.

find_free_port(start_port=None)
register_port(port)
release_port(port)
avocado.utils.network.ports.find_free_port(start_port=1024, end_port=65535, address='localhost', sequent=False, family=AddressFamily.AF_INET, protocol=SocketKind.SOCK_STREAM)

Return a host free port in the range [start_port, end_port].

Parameters:

  • start_port – header of candidate port range, defaults to 1024

  • end_port – ender of candidate port range, defaults to 65535

  • address – Socket address to bind or connect

  • sequent – Find port sequentially, random order if it’s False

  • family (socket.AddressFamily.AF_*) – Default is socket.AF_INET. Accepted values are: socket.AF_INET or socket.AF_INET6.

  • protocol (socket.AddressFamily.SOCK_*) – Protocol type. Default is socket.SOCK_STREAM (TCP). Accepted values are: socket.SOCK_STREAM or socket.SOCK_DGRAM.

Return type:

int or None if no free port found

avocado.utils.network.ports.find_free_ports(start_port, end_port, count, address='localhost', sequent=False, family=AddressFamily.AF_INET, protocol=SocketKind.SOCK_STREAM)

Return count of host free ports in the range [start_port, end_port].

Parameters:

  • start_port – header of candidate port range

  • end_port – ender of candidate port range

  • count – Initial number of ports known to be free in the range.

  • address – Socket address to bind or connect

  • sequent – Find port sequentially, random order if it’s False

  • family (socket.AddressFamily.AF_*) – Default is socket.AF_INET. Accepted values are: socket.AF_INET or socket.AF_INET6.

  • protocol (socket.AddressFamily.SOCK_*) – Protocol type. Default is socket.SOCK_STREAM (TCP). Accepted values are: socket.SOCK_STREAM or socket.SOCK_DGRAM.

avocado.utils.network.ports.is_port_available(port, address, family=AddressFamily.AF_INET, protocol=SocketKind.SOCK_STREAM)

Return True if the given port is available for use.

Parameters:

  • port (int) – Port value to check.

  • address (str) – Address to use this port.

  • family – Default is socket.AF_INET. Accepted values are: socket.AF_INET or socket.AF_INET6.

  • protocol – Protocol type. Default is socket.SOCK_STREAM (TCP). Accepted values are: socket.SOCK_STREAM or socket.SOCK_DGRAM.

avocado.utils.network.ports.is_port_free(port, address)

This method is deprecated. Please use is_port_available().

Module contents