salt.modules.network

Module for gathering and managing network information

salt.modules.network.active_tcp()

Return a dict containing information on all of the running TCP connections (currently linux and solaris only)

Changed in version 2015.8.4: Added support for SunOS

CLI Example:

salt '*' network.active_tcp

salt.modules.network.arp(expand=None)

Return the arp table from the minion

expandNone

If True, return a list of neighbour entry dicts of the form {"ip": ..., "mac": ..., "dev": ..., "state": ...} instead of the legacy {mac: ip} mapping. The legacy mapping can only hold one entry per MAC address, so any further IP addresses sharing that MAC are silently dropped from it. Keys that arp -an does not report on a given platform are set to None.

Changed in version 2015.8.0: Added support for SunOS

Changed in version 3008.5: Added the expand argument. The list-of-entries shape it enables will become the default return shape in salt 3011; until then, calling this function without expand emits a DeprecationWarning. Unresolved (incomplete) entries are no longer included in either shape.

Changed in version 3009.0: On Linux, fall back to ip neigh (iproute2) when the deprecated net-tools arp command is not available.

CLI Example:

salt '*' network.arp
salt '*' network.arp expand=True

salt.modules.network.calc_net(ip_addr, netmask=None)

Returns the CIDR of a subnet based on an IP address (CIDR notation supported) and optional netmask.

CLI Example:

salt '*' network.calc_net 172.17.0.5 255.255.255.240
salt '*' network.calc_net 2a02:f6e:a000:80:84d8:8332:7866:4e07/64

New in version 2015.8.0.

salt.modules.network.connect(host, port=None, **kwargs)

Test connectivity to a host using a particular port from the minion.

New in version 2014.7.0.

CLI Example:

salt '*' network.connect archlinux.org 80

salt '*' network.connect archlinux.org 80 timeout=3

salt '*' network.connect archlinux.org 80 timeout=3 family=ipv4

salt '*' network.connect google-public-dns-a.google.com port=53 proto=udp timeout=3

salt.modules.network.convert_cidr(cidr)

returns the network address, subnet mask and broadcast address of a cidr address

New in version 2016.3.0.

CLI Example:

salt '*' network.convert_cidr 172.31.0.0/16

salt.modules.network.default_route(family=None)

Return default route(s) from routing table

Changed in version 2015.8.0: Added support for SunOS (Solaris 10, Illumos, SmartOS)

Changed in version 2016.11.4: Added support for AIX

CLI Example:

salt '*' network.default_route

salt.modules.network.dig(host)

Performs a DNS lookup with dig

CLI Example:

salt '*' network.dig archlinux.org

salt.modules.network.fqdns()

Return all known FQDNs for the system by enumerating all interfaces and then trying to reverse resolve them (excluding 'lo' interface).

CLI Example:

salt '*' network.fqdns

salt.modules.network.get_bufsize(iface)

Return network buffer sizes as a dict (currently linux only)

CLI Example:

salt '*' network.get_bufsize eth0

salt.modules.network.get_fqdn()

Get fully qualified domain name

CLI Example:

salt '*' network.get_fqdn

salt.modules.network.get_hostname()

Get hostname

CLI Example:

salt '*' network.get_hostname

salt.modules.network.get_route(ip)

Return routing information for given destination ip

New in version 2015.5.3.

Changed in version 2015.8.0: Added support for SunOS (Solaris 10, Illumos, SmartOS) Added support for OpenBSD

Changed in version 2016.11.4: Added support for AIX

CLI Example:

salt '*' network.get_route 10.10.10.10

salt.modules.network.hw_addr(iface)

Return the hardware address (a.k.a. MAC address) for a given interface

CLI Example:

salt '*' network.hw_addr eth0

salt.modules.network.hwaddr(iface)

This function is an alias of hw_addr.

Return the hardware address (a.k.a. MAC address) for a given interface

CLI Example:

salt '*' network.hw_addr eth0

salt.modules.network.ifacestartswith(cidr)

Retrieve the interface name from a specific CIDR

New in version 2016.11.0.

CLI Example:

salt '*' network.ifacestartswith 10.0

salt.modules.network.in_subnet(cidr)

Returns True if host is within specified subnet, otherwise False.

CLI Example:

salt '*' network.in_subnet 10.0.0.0/16

salt.modules.network.interface(iface)

Return the inet address for a given interface

New in version 2014.7.0.

CLI Example:

salt '*' network.interface eth0

salt.modules.network.interface_ip(iface)

Return the inet address for a given interface

New in version 2014.7.0.

CLI Example:

salt '*' network.interface_ip eth0

salt.modules.network.interfaces()

Return a dictionary of information about all the interfaces on the minion

CLI Example:

salt '*' network.interfaces

salt.modules.network.ip_addrs(interface=None, include_loopback=False, cidr=None, type=None)

Returns a list of IPv4 addresses assigned to the host. 127.0.0.1 is ignored, unless 'include_loopback=True' is indicated. If 'interface' is provided, then only IP addresses from that interface will be returned. Providing a CIDR via 'cidr="10.0.0.0/8"' will return only the addresses which are within that subnet. If 'type' is 'public', then only public addresses will be returned. Ditto for 'type'='private'.

Changed in version 3001: interface can now be a single interface name or a list of interfaces. Globbing is also supported.

CLI Example:

salt '*' network.ip_addrs

salt.modules.network.ip_addrs6(interface=None, include_loopback=False, cidr=None)

Returns a list of IPv6 addresses assigned to the host. ::1 is ignored, unless 'include_loopback=True' is indicated. If 'interface' is provided, then only IP addresses from that interface will be returned. Providing a CIDR via 'cidr="2000::/3"' will return only the addresses which are within that subnet.

Changed in version 3001: interface can now be a single interface name or a list of interfaces. Globbing is also supported.

CLI Example:

salt '*' network.ip_addrs6

salt.modules.network.ip_in_subnet(ip_addr, cidr)

Returns True if given IP is within specified subnet, otherwise False.

CLI Example:

salt '*' network.ip_in_subnet 172.17.0.4 172.16.0.0/12

salt.modules.network.ip_neighs(expand=None)

Return the ip neighbour (arp) table from the minion for IPv4 addresses

expandNone

If True, return a list of neighbour entry dicts of the form {"ip": ..., "mac": ..., "dev": ..., "state": ...} instead of the legacy {mac: ip} mapping. The legacy mapping can only hold one entry per MAC address, so any further IP addresses sharing that MAC are silently dropped from it.

New in version 3007.0.

Changed in version 3008.5: Added the expand argument. The list-of-entries shape it enables will become the default return shape in salt 3011; until then, calling this function without expand emits a DeprecationWarning. Unresolved entries (those without a link-layer address) are no longer included in either shape.

CLI Example:

salt '*' network.ip_neighs
salt '*' network.ip_neighs expand=True

salt.modules.network.ip_neighs6(expand=None)

Return the ip neighbour (arp) table from the minion for IPv6 addresses

expandNone

If True, return a list of neighbour entry dicts of the form {"ip": ..., "mac": ..., "dev": ..., "state": ...} instead of the legacy {mac: ip} mapping. The legacy mapping can only hold one entry per MAC address, so any further IP addresses sharing that MAC are silently dropped from it. Because IPv6 hosts normally hold at least a link-local and a global address on the same MAC, the legacy mapping loses entries for practically every neighbour; expand=True is strongly recommended.

New in version 3007.0.

Changed in version 3008.5: Added the expand argument. The list-of-entries shape it enables will become the default return shape in salt 3011; until then, calling this function without expand emits a DeprecationWarning. Unresolved entries (those without a link-layer address) are no longer included in either shape.

CLI Example:

salt '*' network.ip_neighs6
salt '*' network.ip_neighs6 expand=True

salt.modules.network.ip_networks(interface=None, include_loopback=False, verbose=False)

New in version 3001.

Returns a list of IPv4 networks to which the minion belongs.

interface

Restrict results to the specified interface(s). This value can be either a single interface name or a list of interfaces. Globbing is also supported.

CLI Example:

salt '*' network.ip_networks
salt '*' network.ip_networks interface=docker0
salt '*' network.ip_networks interface=docker0,enp*
salt '*' network.ip_networks interface=eth*

salt.modules.network.ip_networks6(interface=None, include_loopback=False, verbose=False)

New in version 3001.

Returns a list of IPv6 networks to which the minion belongs.

interface

Restrict results to the specified interface(s). This value can be either a single interface name or a list of interfaces. Globbing is also supported.

CLI Example:

salt '*' network.ip_networks6
salt '*' network.ip_networks6 interface=docker0
salt '*' network.ip_networks6 interface=docker0,enp*
salt '*' network.ip_networks6 interface=eth*

salt.modules.network.ipaddrs(interface=None, include_loopback=False, cidr=None, type=None)

This function is an alias of ip_addrs.

Returns a list of IPv4 addresses assigned to the host. 127.0.0.1 is ignored, unless 'include_loopback=True' is indicated. If 'interface' is provided, then only IP addresses from that interface will be returned. Providing a CIDR via 'cidr="10.0.0.0/8"' will return only the addresses which are within that subnet. If 'type' is 'public', then only public addresses will be returned. Ditto for 'type'='private'.

Changed in version 3001: interface can now be a single interface name or a list of interfaces. Globbing is also supported.

CLI Example:

salt '*' network.ip_addrs

salt.modules.network.ipaddrs6(interface=None, include_loopback=False, cidr=None)

This function is an alias of ip_addrs6.

Returns a list of IPv6 addresses assigned to the host. ::1 is ignored, unless 'include_loopback=True' is indicated. If 'interface' is provided, then only IP addresses from that interface will be returned. Providing a CIDR via 'cidr="2000::/3"' will return only the addresses which are within that subnet.

Changed in version 3001: interface can now be a single interface name or a list of interfaces. Globbing is also supported.

CLI Example:

salt '*' network.ip_addrs6

salt.modules.network.iphexval(ip)

Retrieve the hexadecimal representation of an IP address

New in version 2016.11.0.

CLI Example:

salt '*' network.iphexval 10.0.0.1

salt.modules.network.ipneighs(expand=None)

This function is an alias of ip_neighs.

Return the ip neighbour (arp) table from the minion for IPv4 addresses

expandNone

If True, return a list of neighbour entry dicts of the form {"ip": ..., "mac": ..., "dev": ..., "state": ...} instead of the legacy {mac: ip} mapping. The legacy mapping can only hold one entry per MAC address, so any further IP addresses sharing that MAC are silently dropped from it.

New in version 3007.0.

Changed in version 3008.5: Added the expand argument. The list-of-entries shape it enables will become the default return shape in salt 3011; until then, calling this function without expand emits a DeprecationWarning. Unresolved entries (those without a link-layer address) are no longer included in either shape.

CLI Example:

salt '*' network.ip_neighs
salt '*' network.ip_neighs expand=True

salt.modules.network.ipneighs6(expand=None)

This function is an alias of ip_neighs6.

Return the ip neighbour (arp) table from the minion for IPv6 addresses

expandNone

If True, return a list of neighbour entry dicts of the form {"ip": ..., "mac": ..., "dev": ..., "state": ...} instead of the legacy {mac: ip} mapping. The legacy mapping can only hold one entry per MAC address, so any further IP addresses sharing that MAC are silently dropped from it. Because IPv6 hosts normally hold at least a link-local and a global address on the same MAC, the legacy mapping loses entries for practically every neighbour; expand=True is strongly recommended.

New in version 3007.0.

Changed in version 3008.5: Added the expand argument. The list-of-entries shape it enables will become the default return shape in salt 3011; until then, calling this function without expand emits a DeprecationWarning. Unresolved entries (those without a link-layer address) are no longer included in either shape.

CLI Example:

salt '*' network.ip_neighs6
salt '*' network.ip_neighs6 expand=True

salt.modules.network.is_loopback(ip_addr)

Check if the given IP address is a loopback address

New in version 2014.7.0.

Changed in version 2015.8.0: IPv6 support

CLI Example:

salt '*' network.is_loopback 127.0.0.1

salt.modules.network.is_private(ip_addr)

Check if the given IP address is a private address

New in version 2014.7.0.

Changed in version 2015.8.0: IPv6 support

CLI Example:

salt '*' network.is_private 10.0.0.3

salt.modules.network.mod_bufsize(iface, *args, **kwargs)

Modify network interface buffers (currently linux only)

CLI Example:

salt '*' network.mod_bufsize tx=<val> rx=<val> rx-mini=<val> rx-jumbo=<val>

salt.modules.network.mod_hostname(hostname)

Modify hostname

Changed in version 2015.8.0: Added support for SunOS (Solaris 10, Illumos, SmartOS)

CLI Example:

salt '*' network.mod_hostname master.saltstack.com

salt.modules.network.netstat()

Return information on open ports and states

Note

On BSD minions, the output contains PID info (where available) for each netstat entry, fetched from sockstat/fstat output.

Changed in version 2014.1.4: Added support for OpenBSD, FreeBSD, and NetBSD

Changed in version 2015.8.0: Added support for SunOS

Changed in version 2016.11.4: Added support for AIX

CLI Example:

salt '*' network.netstat

salt.modules.network.ping(host, timeout=False, return_boolean=False)

Performs an ICMP ping to a host

Changed in version 2015.8.0: Added support for SunOS

CLI Example:

salt '*' network.ping archlinux.org

New in version 2015.5.0.

Return a True or False instead of ping output.

salt '*' network.ping archlinux.org return_boolean=True

Set the time to wait for a response in seconds.

salt '*' network.ping archlinux.org timeout=3

salt.modules.network.reverse_ip(ip_addr)

Returns the reversed IP address

Changed in version 2015.8.0: IPv6 support

CLI Example:

salt '*' network.reverse_ip 172.17.0.4

salt.modules.network.routes(family=None)

Return currently configured routes from routing table

Changed in version 2015.8.0: Added support for SunOS (Solaris 10, Illumos, SmartOS)

Changed in version 2016.11.4: Added support for AIX

CLI Example:

salt '*' network.routes

salt.modules.network.subnets(interfaces=None)

Returns a list of IPv4 subnets to which the host belongs

CLI Example:

salt '*' network.subnets
salt '*' network.subnets interfaces=eth1

salt.modules.network.subnets6()

Returns a list of IPv6 subnets to which the host belongs

CLI Example:

salt '*' network.subnets

salt.modules.network.traceroute(host)

Performs a traceroute to a 3rd party host

Changed in version 2015.8.0: Added support for SunOS

Changed in version 2016.11.4: Added support for AIX

CLI Example:

salt '*' network.traceroute archlinux.org

salt.modules.network.wol(mac, bcast='255.255.255.255', destport=9)

Send Wake On Lan packet to a host

CLI Example:

salt '*' network.wol 08-00-27-13-69-77
salt '*' network.wol 080027136977 255.255.255.255 7
salt '*' network.wol 08:00:27:13:69:77 255.255.255.255 7