Differential D25447 Diff 78526 lib/flua/libifconfig/ifconfig.3lua

Changeset View

Standalone View

lib/flua/libifconfig/ifconfig.3lua

This file was added.

				.\"
				.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
				.\"
				.\" Copyright (c) 2020, Ryan Moeller <freqlabs@FreeBSD.org>
				.\"
				.\" Redistribution and use in source and binary forms, with or without
				.\" modification, are permitted provided that the following conditions
				.\" are met:
				.\" 1. Redistributions of source code must retain the above copyright
				.\" notice, this list of conditions and the following disclaimer.
				.\" 2. Redistributions in binary form must reproduce the above copyright
				.\" notice, this list of conditions and the following disclaimer in the
				.\" documentation and/or other materials provided with the distribution.
				.\"
				.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
				.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
				.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
				.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
				.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
				.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
				.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
				.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
				.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
				.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
				.\" SUCH DAMAGE.
				.\"
				.\" $FreeBSD$
				.\"
				.Dd October 11, 2020
				.Dt IFCONFIG 3lua
				.Os
				.Sh NAME
				.Nm open ,
				.Nm close ,
				.Nm error ,
				.Nm foreach_iface ,
				.Nm foreach_ifaddr ,
				.Nm get_description ,
				.Nm set_description ,
				.Nm unset_description ,
				.Nm set_name ,
				.Nm get_orig_name ,
				.Nm get_fib ,
				.Nm set_mtu ,
				.Nm get_mtu ,
				.Nm get_nd6 ,
				.Nm set_metric ,
				.Nm get_metric ,
				.Nm set_capabilities ,
				.Nm get_capabilities ,
				.Nm get_groups ,
				.Nm get_status ,
				.Nm get_media ,
				.Nm get_carp ,
				.Nm addr_info ,
				.Nm get_bridge_status ,
				.Nm get_lagg_status ,
				.Nm get_laggport_laggdev ,
				.Nm destroy ,
				.Nm create ,
				.Nm create_vlan ,
				.Nm set_vlantag ,
				.Nm list_cloners ,
				.Nm get_sfp_info ,
				.Nm get_sfp_vendor_info ,
				.Nm get_sfp_status ,
				.Nm get_sfp_dump
				.Nd Lua binding to
				.Xr ifconfig 3
				.Sh SYNOPSIS
				.Bd -literal
				local ifconfig = require('ifconfig')
				.Ed
				.Pp
				.Bl -tag -width XXXX -compact
				.It Dv ifcfg = ifconfig.open()
				.It Dv ifcfg:close()
				.It Dv errtype, errno, ioctlname = ifcfg:error()
				.It Dv udata = ifcfg:foreach_iface(cb, udata )
				.It Dv udata = ifcfg:foreach_ifaddr(iface, cb, udata )
				.It Dv desc = ifcfg:get_description(name)
				.It Dv res = ifcfg:set_description(name, desc )
				.It Dv res = ifcfg:unset_description(name)
				.It Dv res = ifcfg:set_name(name, newname )
				.It Dv name = ifcfg:get_orig_name(name)
				.It Dv fib = ifcfg:get_fib(name)
				.It Dv res = ifcfg:set_mtu(name, mtu )
				.It Dv mtu = ifcfg:get_mtu(name)
				.It Dv nd6 = ifcfg:get_nd6(name)
				.It Dv res = ifcfg:set_metric(name, metric )
				.It Dv metric = ifcfg:get_metric(name)
				.It Dv res = ifcfg:set_capabilities(name, caps )
				.It Dv caps = ifcfg:get_capabilities(name)
				.It Dv groups = ifcfg:get_groups(name)
				.It Dv status = ifcfg:get_status(name)
				.It Dv media = ifcfg:get_media(name)
				.It Dv carp = ifcfg:get_carp(name)
				.It Dv ai = ifcfg:addr_info(addr)
				.It Dv status = ifcfg:get_bridge_status(name)
				.It Dv status = ifcfg:get_lagg_status(name)
				.It Dv lagg = ifcfg:get_laggport_laggdev(name)
				.It Dv res = ifcfg:destroy(name)
				.It Dv name = ifcfg:create(name)
				.It Dv name = ifcfg:create_vlan(name, vlandev, vlantag )
				.It Dv res = ifcfg:set_vlantag(name, vlandev, vlantag )
				.It Dv cloners = ifcfg:list_cloners()
				.It Dv info = ifcfg:get_sfp_info(name)
				.It Dv vendor_info = ifcfg:get_sfp_vendor_info(name)
				.It Dv status = ifcfg:get_sfp_status(name)
				.It Dv dump = ifcfg:get_sfp_dump(name)
				.It Vt struct ifaddrs *
				.El
				.Sh DESCRIPTION
				The
				.Nm ifconfig
				module is a binding to the
				.Xr ifconfig 3
				library.
				It provides a high-level interface for many socket ioctls that query and
				control network interface configuration and status information.
				.Bl -tag -width XXXX
				.It Dv ifcfg = ifconfig.open()
				Open a libifconfig handle.
				The handle is a userdata object used to perform the various socket operations
				underlying most libifconfig functionality.
				An open handle will be closed when garbage collected, or it can be explicitly
				closed with
				.Fn close .
				.It Dv ifcfg:close()
				Explicitly close a handle opened by
				.Fn open .
				.It Dv errtype, errno, ioctlname = ifcfg:error()
				Get information about the last error.
				If the last operation was succcessful,
				.Dv nil
				is returned.
				Otherwise, returns the error type, errno, and if applicable the name of the
				ioctl that failed.
				The error type is one of "OTHER", "IOCTL", or "SOCKET".
				.It Dv udata = ifcfg:foreach_iface(cb, udata )
				Iterate over interfaces.
				This is a higher-order fold operation, where
				.Fa cb
				is a callback function of the form
				.Dl (handle, iface, udata) -> udata
				which is called for each interface in succession.
				.Pp
				The
				.Fa handle
				passed to the callback is the handle that was used to invoke
				.Fn foreach_iface .
				.Pp
				The
				.Fa iface
				passed to the callback is a
				.Vt struct ifaddrs *
				userdata object that is only valid until the callback function returns.
				It must not be retained outside the scope of the callback.
				.Pp
				The
				.Fa udata
				parameter is an accumulator.
				The initial value passed to
				.Fn foreach_iface
				is forwarded to the callback function on the first iteration.
				The return value of the callback function is passed to the callback as
				.Fa udata
				on the next iteration.
				The value returned from the callback function on the final iteration is
				returned from
				.Fn foreach_iface
				on success.
				.Pp
				An error may be raised if iteration fails due to an internal error.
				.It Dv udata = ifcfg:foreach_ifaddr(iface, cb, udata )
				Iterate over interface addresses.
				This is a higher-order fold operation, where
				.Fa cb
				is a callback function of the form
				.Dl (handle, ifaddr, udata) -> udata
				which is called for each interface address in succession.
				.Pp
				The interface
				.Fa iface
				is the
				.Vt struct ifaddrs *
				userdata object passed to the callback function for
				.Fn foreach_iface .
				.Pp
				The
				.Fa handle
				passed to the callback is the handle that was used to invoke
				.Fn foreach_ifaddr .
				.Pp
				The
				.Fa udata
				parameter is an accumulator.
				The initial value passed to
				.Fn foreach_ifaddr
				is forwarded to the callback function on the first iteration.
				The return value of the callback function is passed to the callback as
				.Fa udata
				on the next iteration.
				The value returned from the callback function on the final iteration is
				returned from
				.Fn foreach_ifaddr .
				.It Dv desc = ifcfg:get_description(name)
				Given the
				.Fa name
				of an interface, returns the description string if set, otherwise
				.Dv nil .
				.It Dv res = ifcfg:set_description(name, desc )
				Given the
				.Fa name
				of an interface, sets the description string to
				.Fa desc .
				.It Dv res = ifcfg:unset_description(name)
				Given the
				.Fa name
				of an interface, unsets the description string if set.
				.It Dv res = ifcfg:set_name(name, newname )
				Given the
				.Fa name
				of an interface, changes the interface name to
				.Fa newname .
				.It Dv name = ifcfg:get_orig_name(name)
				Given the
				.Fa name
				of an interface, returns the original name string of the interface.
				.It Dv fib = ifcfg:get_fib(name)
				Given the
				.Fa name
				of an interface, returns the interface FIB number.
				.It Dv res = ifcfg:set_mtu(name, mtu )
				Given the
				.Fa name
				of an interface, sets the interface MTU to
				.Fa mtu .
				.It Dv mtu = ifcfg:get_mtu(name)
				Given the
				.Fa name
				of an interface, returns the interface MTU.
				.It Dv nd6 = ifcfg:get_nd6(name)
				Given the
				.Fa name
				of an interface, returns a list of the enabled ICMPv6 Neighbor Discovery
				Protocol options.
				.It Dv res = ifcfg:set_metric(name, metric )
				Given the
				.Fa name
				of an interface, sets the interface metric to
				.Fa metric .
				.It Dv metric = ifcfg:get_metric(name)
				Given the
				.Fa name
				of an interface, returns the interface metric.
				.It Dv res = ifcfg:set_capabilities(name, caps )
				Given the
				.Fa name
				of an interface, enables the list of capabilities given as strings in the list
				.Fa caps
				and disables the capabilities not in the list, returning true if successful or
				false if an error occurs.
				.It Dv caps = ifcfg:get_capabilities(name)
				Given the
				.Fa name
				of an interface, returns a table of the form
				.Bd -literal -compact
				{
				enabled = { "", ... },
				supported = { "", ... }
				}
				.Ed
				where
				.Nm enabled
				and
				.Nm supported
				are the lists of enabled and supported capabilities with each capability
				represented by a string.
				.It Dv groups = ifcfg:get_groups(name)
				Given the
				.Fa name
				of an interface, returns a list of the names of the groups containing the
				interface.
				.It Dv status = ifcfg:get_status(name)
				Given the
				.Fa name
				of an interface, returns the interface status as a string.
				.It Dv media = ifcfg:get_media(name)
				Given the
				.Fa name
				of an interface, returns a table of the form
				.Bd -literal -compact
				{
				current = {},
				active = {},
				supported = { {}, ... },
				status = ""
				}
				.Ed
				where
				.Nm current
				and
				.Nm active
				are tables of the form
				.Bd -literal -compact
				{
				type = "",
				subtype = "",
				options = ""
				}
				.Ed
				and
				.Nm supported
				is a list of the same form of tables.
				.It Dv carp = ifcfg:get_carp(name)
				Given the
				.Fa name
				of an interface, returns a list of tables of the form
				.Bd -literal -compact
				{
				state = "",
				vhid = #,
				advbase = #,
				advskew = #
				}
				.Ed
				describing the interface
				.Xr carp 4
				VHIDs.
				.It Dv ai = ifcfg:addr_info(addr)
				Given a
				.Vt struct ifaddrs *
				userdata object as
				.Fa addr ,
				returns a table describing the address.
				The format of the table depends on the type of address.
				.Bl -inset
				.It Nm AF_INET
				addresses are described by a table of the form
				.Bd -literal -compact
				{
				inet = "",
				netmask = "",
				[ destination = "",]
				[ broadcast = "",]
				[ vhid = # ]
				}
				.Ed
				.It Nm AF_INET6
				addresses are described by a table of the form
				.Bd -literal -compact
				{
				inet6 = "",
				prefixlen = #,
				flags = { "", ... },
				[ destination = "",]
				[ scopeid = #,]
				[ preferred_lifetime = #, valid_lifetime = #,]
				[ vhid = # ]
				}
				.Ed
				.It Nm AF_LINK
				addresses are described by a table of the form
				.Bd -literal -compact
				{
				ether = ""
				}
				.Ed
				for link types
				.Nm IFT_ETHER ,
				.Nm IFT_L2VLAN ,
				and
				.Nm IFT_BRIDGE
				or
				.Bd -literal -compact
				{
				lladdr = ""
				}
				.Ed
				for other link types.
				.It Nm AF_LOCAL
				addresses are described by a table of the form
				.Bd -literal -compact
				{
				path = ""
				}
				.Ed
				.El
				.It Dv status = ifcfg:get_bridge_status(name)
				Given the
				.Fa name
				of a
				.Xr bridge 4
				interface, returns a table of the form
				.Bd -literal -compact
				{
				address_cache_size = #,
				address_cache_lifetime = #,
				priority = #,
				protocol = ""\|#,
				hello_time = #,
				forward_delay = #,
				hold_count = #,
				max_age = #,
				id = "",
				root_id = "",
				root_priority = #,
				root_path_cost = #,
				root_port = #,
				members = { {}, ... }
				}
				.Ed
				where
				.Nm members
				is a list of tables of the form
				.Bd -literal -compact
				{
				flags = { "", ... },
				ifmaxaddr = #,
				port = #,
				priority = #,
				[ protocol = ""\|#, role = ""\|#, state = ""\|#]
				}
				.Ed
				.It Dv status = ifcfg:get_lagg_status(name)
				Given the
				.Fa name
				of a
				.Xr lagg 4
				interface, returns a table of the form
				.Bd -literal -compact
				{
				options = {},
				stats = {},
				ports = { {}, ... }
				}
				.Ed
				where
				.Nm options
				is a table of the form
				.Bd -literal -compact
				{
				laggproto = "",
				lagghash = { "", ... },
				flags = { "", ... },
				flowid_shift = #,
				[ rr_limit = # ]
				}
				.Ed
				.Nm stats
				is a table of the form
				.Bd -literal -compact
				{
				active = #,
				flapping = #
				}
				.Ed
				and
				.Nm ports
				is a list of tables of the form
				.Bd -literal -compact
				{
				laggport = "",
				flags = { "", ... },
				[ lacp_state = { "", ... } ]
				}
				.Ed
				.It Dv lagg = ifcfg:get_laggport_laggdev(name)
				Given the
				.Fa name
				of an interface, returns the parent lagg device name.
				error occurs.
				.It Dv res = ifcfg:destroy(name)
				Given the
				.Fa name
				of an interface, destroys the interface.
				.It Dv name = ifcfg:create(name)
				Given the
				.Fa name
				of in interface, creates the interface and returns the name of the created
				interface.
				.It Dv name = ifcfg:create_vlan(name, vlandev, vlantag )
				Creates a
				.Xr vlan 4 interface with the given
				.Fa name
				attached to
				.Fa vlandev
				and using the vlan number specified by
				.Fa vlantag ,
				returning the name of the create interface.
				occurs.
				.It Dv res = ifcfg:set_vlantag(name, vlandev, vlantag )
				Given the
				.Fa name
				of an existing
				.Xr vlan 4
				interface, sets the specified
				.Fa vlandev
				and
				.Fa vlantag .
				.It Dv cloners = ifcfg:list_cloners()
				Returns a list of the names of all the interface cloners available on the
				system.
				.It Dv info = ifcfg:get_sfp_info(name)
				Given the
				.Fa name
				of an interface, returns SFP module information as a table of the form
				.Bd -literal -compact
				{
				[ sfp_id = {},]
				[ sfp_conn = {},]
				[ sfp_eth_10g = {},]
				[ sfp_eth = {},]
				[ sfp_fc_len = {},]
				[ sfp_cab_tech = {},]
				[ sfp_fc_media = {},]
				[ sfp_eth_1040g = {},]
				[ sfp_eth_ext = {},]
				[ sfp_rev = {}]
				}
				.Ed
				where each field, if present, is a table of the form
				.Bd -literal -compact
				{
				description = "",
				string = "",
				value = #
				}
				.Ed
				or
				.Dv nil
				if no SFP module is present.
				.It Dv vendor_info = ifcfg:get_sfp_vendor_info(name)
				Given the
				.Fa name
				of an interface, returns SFP module vendor information as a table of the form
				.Bd -literal -compact
				{
				name = "",
				part_number = "",
				serial_number = "",
				date = ""
				}
				.Ed
				or
				.Dv nil
				if no SFP module is present.
				.It Dv status = ifcfg:get_sfp_status(name)
				Given the
				.Fa name
				of an interface, returns SFP module status as a table of the form
				.Bd -literal -compact
				{
				voltage = #,
				channels = { {}, ... },
				[ temperature = #,]
				[ bitrate = #]
				}
				.Ed
				where
				.Nm channels
				is a list of tables of the form
				.Bd -literal -compact
				{
				rx_power = {},
				tx_bias = {}
				}
				.Ed
				.Nm rx_power
				is a table of the form
				.Bd -literal -compact
				{
				value = #,
				mW = #,
				dBm = #
				}
				.Ed
				.Nm tx_bias
				is a table of the form
				.Bd -literal -compact
				{
				raw = #,
				mA = #
				}
				.Ed
				or
				.Dv nil
				if no SFP module is present.
				.It Dv dump = ifcfg:get_sfp_dump(name)
				Given the
				.Fa name
				of an interface, returns a userdata blob containing a dump of the SFP module's
				I2C memory or
				.Dv nil
				if no SFP module is present.
				The userdata blob coerces to a string formatted as a hex dump similar to
				.Xr ifconfig 8
				with
				.Fl vv .
				.It Vt struct ifaddrs *
				The
				.Vt struct ifaddrs *
				userdata type describes an interface and various address types associated with
				it.
				An object of this type provides two address-agnostic methods:
				.Bl -tag -width XXXX
				.It Dv name = ifaddr:name()
				Get the name of the interface to which this address is assigned.
				.It Dv flags = ifaddr:flags()
				Get the flags set on the interface to which this address is assigned.
				.El
				Address-specific information is obtained by passing a
				.Vt struct ifaddrs *
				userdata object to the
				.Fn addr_info
				function.
				.El
				.Sh RETURN VALUES
				The
				.Fn open
				function returns an open
				.Vt ifconfig_handle_t
				userdata object on success, or
				.Dv nil
				on error.
				.Pp
				The
				.Fn error
				function returns multiple values on success, or
				.Dv nil
				on error.
				The values returned are the error type, errno, and the ioctl name if the error
				type is "IOCTL".
				The
				.Fn foreach_iface
				and
				.Fn foreach_ifaddr
				functions return the value returned by the
				.Fa cb
				function on the final iteration, or the initial
				.Fa udata
				argument if
				.Fa cb
				was not invoked.
				.Pp
				The functions
				.Fn get_description ,
				.Fn get_orig_name ,
				.Fn get_status ,
				.Fn get_laggport_laggdev ,
				.Fn create ,
				and
				.Fn create_vlan
				return a string on success, or
				.Dv nil
				on error.
				The string returned by
				.Fn create
				and
				.Fn create_vlan
				is the name of the created interface.
				.Pp
				The functions
				.Fn get_fib ,
				.Fn get_mtu ,
				and
				.Fn get_metric
				return an integer on success, or
				.Dv nil
				on error.
				.Pp
				The functions
				.Fn get_nd6 ,
				.Fn get_groups ,
				and
				.Fn list_cloners
				return a list of strings on success, or
				.Dv nil
				on error.
				.Pp
				The functions
				.Fn get_capabilities ,
				.Fn get_media ,
				.Fn get_carp ,
				.Fn addr_info ,
				.Fn get_bridge_status ,
				.Fn get_lagg_status ,
				.Fn get_sfp_info ,
				.Fn get_sfp_vendor_info ,
				.Fn get_sfp_status ,
				and
				.Fn get_sfp_dump
				return a table described for each function in the
				.Sx DESCRIPTION
				section, or
				.Dv nil
				on error.
				.Pp
				The functions
				.Fn set_description ,
				.Fn unset_description ,
				.Fn set_name ,
				.Fn set_mtu ,
				.Fn set_metric ,
				.Fn set_capabilities ,
				.Fn set_vlantag ,
				and
				.Fn destroy
				return
				.Dv true
				on success, or
				.Dv false
				on error.
				.Pp
				The
				.Fn ifaddr:name
				method returns a string and the
				.Fn ifaddr:flags
				method returns a list of strings.
				.Sh EXAMPLES
				Get a list of the names of all interfaces:
				.Bd -literal -offset indent
				local ifcfg = require('ifconfig').open()
				local ucl = require('ucl')

				local ifnames = ifcfg:foreach_iface(function(ifcfg, iface, ifnames)
				table.insert(ifnames, iface:name())
				return ifnames
				end, {})

				print(ucl.to_json(ifnames))
				.Ed
				.Pp
				Retrieve information about all SFP modules:
				.Bd -literal -offset indent
				local ifcfg = require('ifconfig').open()
				local ucl = require('ucl')

				local modules = ifcfg:foreach_iface(function(ifcfg, iface, modules)
				local name = iface:name()
				local sfp = ifcfg:get_sfp_info(name)
				if sfp then
				modules[name] = {
				info = sfp,
				vendor_info = ifcfg:get_sfp_vendor_info(name),
				status = ifcfg:get_sfp_status(name),
				-- Not generally interesting,
				-- but for completeness:
				-- dump = tostring(ifcfg:get_sfp_dump(name)),
				}
				end
				return modules
				end, {})

				print(ucl.to_json(modules))
				.Ed
				.Pp
				Get error information:
				.Bd -literal -offset indent
				local ifcfg = require('ifconfig').open()

				local status = ifcfg:get_status('usb')
				if not status then
				print(ifcfg:error())
				-- Prints:
				-- IOCTL 6 SIOCGIFSTATUS
				end

				local dump = ifcfg:get_sfp_dump('usb')
				if not dump then
				local errtype, errno, ioctlname = ifcfg:error()
				assert(errno == 6) -- ENXIO
				print(errtype .. ':' .. ioctlname .. ' failed')
				-- Prints:
				-- IOCTL:SIOCGI2C failed
				end
				.Ed
				.Sh SEE ALSO
				.Xr ifconfig 8
				.Sh HISTORY
				The
				.Nm ifconfig
				Lua module for flua first appeared in
				.Fx 13.0 .
				.Sh AUTHORS
				.An Ryan Moeller ,
				with inspiration from
				.Nx
				gpio(3lua), by
				.An Mark Balmer .