Skip to main content

Interface

The network interfaces of the host. osapi behavior get --name interface and osapi behavior method get show the same. Its chain shows each call that its examples make.

Behavior​

Nameinterface
DescriptionThe network interfaces of the host
Placementnode
Groupnetwork
Internalno
APIyes
CLIyes
Nextno
Platformsdebian, linux, darwin
Sudonone
Runsnone
Writes/etc/netplan/osapi-*.yaml
Keeps stateno
Usesnetplan
Used bynone

Methods (5)​

NAMEVERBHTTPROUTEPERMISSIONDESCRIPTION
listreadGET/api/node/{hostname}/network/interfacenetwork:readList the network interfaces of the host
getreadGET/api/node/{hostname}/network/interface/{name}network:readGet a network interface of the host
createwritePOST/api/node/{hostname}/network/interface/{name}network:writeConfigure a network interface
updatewritePUT/api/node/{hostname}/network/interface/{name}network:writeChange the config osapi has of a network interface
deletewriteDELETE/api/node/{hostname}/network/interface/{name}network:writeDrop the config osapi has of a network interface

Types (5)​

NAMEINPUTOUTPUT
listListInput[]Entry { name, state, mac, mtu, ipv4, ipv6, addresses, dhcp4, primary }
getGetInput { name* }Entry { name, state, mac, mtu, ipv4, ipv6, addresses, dhcp4, primary }
createCreateInput { name*, dhcp4, dhcp6, addresses, gateway4, gateway6, mtu, mac_address, wakeonlan }Result { name, changed }
updateUpdateInput { name*, dhcp4, dhcp6, addresses, gateway4, gateway6, mtu, mac_address, wakeonlan }Result { name, changed }
deleteDeleteInput { name* }Result { name, changed }

Settings (0)​

None. Declare them with behavior.Config.

Telemetry​

Spanbehavior.interface.<method>
Child spansbehavior.netplan.<method>, behavior.managedfile.<method>, exec ip, exec ifconfig, exec netstat, exec ethtool, exec netplan, exec chown, exec stat, file.write, file.remove, file.chmod, kv.get, kv.put
Metricsosapi_behavior_calls_total, osapi_behavior_duration_seconds, osapi_behavior_changes_total
Attributesosapi.behavior.name, osapi.behavior.method, osapi.behavior.verb, osapi.behavior.outcome, osapi.behavior.changed
Recorded inputsname (get, create, update, delete)

Method list​

Namelist
Verbread
DescriptionList the network interfaces of the host
DetailReads each interface but the loopback, in the order of its index: /sys/class/net and ip on Linux, ifconfig and netstat on macOS. dhcp4 is true when a route of the interface has proto dhcp, and primary when it has the default route.
HTTPGET
Route/api/node/{hostname}/network/interface
Permissionnetwork:read
Commandosapi client node network interface list
Input typeListInput
Output type[]Entry

Input (0)​

None. The method takes no input; its command needs only --target.

Output (9)​

FIELDTYPEDESCRIPTION
namestringThe interface
statestringup or down
macstringIts MAC address; empty for one without, such as lo
mtuintegerIts MTU
ipv4stringIts first IPv4 address that is not link-local
ipv6stringIts first IPv6 address that is not link-local
addressesarrayEach of its addresses, in CIDR notation
dhcp4booleanWhether DHCP gave it an IPv4 address: a route of it has proto dhcp
primarybooleanWhether it has the default route

Examples (2)​

EXAMPLEINPUTOUTPUT
A Linux host(none)[addresses=[10.0.0.5/24 2001:db8::5/64 fe80::5054:ff:fe12:3456/64], dhcp4=true, ipv4=10.0.0.5, ipv6=2001:db8::5, mac=52:54:00:12:34:56, mtu=1500, name=eth0, primary=true, state=up]
A Mac(none)[addresses=[192.168.0.40/24], dhcp4=false, ipv4=192.168.0.40, ipv6=, mac=3c:22:fb:00:00:01, mtu=1500, name=en0, primary=true, state=up]

Method get​

Nameget
Verbread
DescriptionGet a network interface of the host
DetailReads the interface as list does.
HTTPGET
Route/api/node/{hostname}/network/interface/{name}
Permissionnetwork:read
Commandosapi client node network interface get
Input typeGetInput
Output typeEntry

Input (1)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
namestringyespattern ^(@fact.[a-z0-9_.]+|[a-zA-Z0-9][a-zA-Z0-9._-]{0,14})$The interface, such as eth0, or a fact such as @fact.interface.primary

Output (9)​

FIELDTYPEDESCRIPTION
namestringThe interface
statestringup or down
macstringIts MAC address; empty for one without, such as lo
mtuintegerIts MTU
ipv4stringIts first IPv4 address that is not link-local
ipv6stringIts first IPv6 address that is not link-local
addressesarrayEach of its addresses, in CIDR notation
dhcp4booleanWhether DHCP gave it an IPv4 address: a route of it has proto dhcp
primarybooleanWhether it has the default route

Examples (2)​

EXAMPLEINPUTOUTPUT
An interface with a DHCP addressname=eth0name=eth0, state=up, mac=52:54:00:12:34:56, mtu=1500, ipv4=10.0.0.5, ipv6=2001:db8::5, addresses=[10.0.0.5/24 2001:db8::5/64 fe80::5054:ff:fe12:3456/64], dhcp4=true, primary=true
A Macname=en0name=en0, state=up, mac=3c:22:fb:00:00:01, mtu=1500, ipv4=192.168.0.40, ipv6=, addresses=[192.168.0.40/24], dhcp4=false, primary=true

Method create​

Namecreate
Verbwrite
DescriptionConfigure a network interface
DetailWrites a netplan file of the interface's own, such as /etc/netplan/osapi-osapi0.yaml for osapi0, under a netplan definition that is the interface's own, and applies it. An interface the host does not have is not found. dhcp4 and dhcp6 are false unless given, so the interface has only the addresses given. An interface that a match defines, such as cloud-init's all for en*, is refused, because the config would change each interface the match takes, now and later. An interface osapi already configures does not change: update replaces its config. It runs on the Debian family, and elsewhere, and in a container, reports skipped.
HTTPPOST
Route/api/node/{hostname}/network/interface/{name}
Permissionnetwork:write
Commandosapi client node network interface create
Input typeCreateInput
Output typeResult

Input (9)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
namestringyespattern ^(@fact.[a-z0-9_.]+|[a-zA-Z0-9][a-zA-Z0-9._-]{0,14})$The interface, such as eth0, or a fact such as @fact.interface.primary
dhcp4booleannoTake an IPv4 address from DHCP
dhcp6booleannoTake an IPv6 address from DHCP
addressesarraynoThe static addresses, in CIDR notation, such as 10.0.0.5/24
gateway4stringnoformat ipv4The IPv4 default gateway
gateway6stringnoformat ipv6The IPv6 default gateway
mtuintegernomin 68, max 9000The MTU, from 68 to 9000
mac_addressstringnopattern ^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$The MAC address to set
wakeonlanbooleannoTurn on wake-on-LAN

Output (2)​

FIELDTYPEDESCRIPTION
namestringThe interface
changedbooleanWhether the host changed

Examples (3)​

EXAMPLEINPUTOUTPUT
A static addressname=osapi0, addresses=[10.0.1.5/24]name=osapi0, changed=true
Each settingname=osapi0, dhcp6=true, addresses=[2001:db8::5/64], mtu=9000, mac_address=52:54:00:aa:bb:cc, wakeonlan=truename=osapi0, changed=true
An interface osapi already configuresname=osapi0, addresses=[10.0.1.5/24]name=osapi0, changed=false

Method update​

Nameupdate
Verbwrite
DescriptionChange the config osapi has of a network interface
DetailWrites the interface's netplan file over the one osapi has, as create writes it, and applies it. An interface osapi does not configure is not found: create configures it.
HTTPPUT
Route/api/node/{hostname}/network/interface/{name}
Permissionnetwork:write
Commandosapi client node network interface update
Input typeUpdateInput
Output typeResult

Input (9)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
namestringyespattern ^(@fact.[a-z0-9_.]+|[a-zA-Z0-9][a-zA-Z0-9._-]{0,14})$The interface, such as eth0, or a fact such as @fact.interface.primary
dhcp4booleannoTake an IPv4 address from DHCP
dhcp6booleannoTake an IPv6 address from DHCP
addressesarraynoThe static addresses, in CIDR notation, such as 10.0.0.5/24
gateway4stringnoformat ipv4The IPv4 default gateway
gateway6stringnoformat ipv6The IPv6 default gateway
mtuintegernomin 68, max 9000The MTU, from 68 to 9000
mac_addressstringnopattern ^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$The MAC address to set
wakeonlanbooleannoTurn on wake-on-LAN

Output (2)​

FIELDTYPEDESCRIPTION
namestringThe interface
changedbooleanWhether the host changed

Examples (1)​

EXAMPLEINPUTOUTPUT
Move an interface to DHCPname=osapi0, dhcp4=truename=osapi0, changed=true

Method delete​

Namedelete
Verbwrite
DescriptionDrop the config osapi has of a network interface
DetailRemoves the interface's netplan file and applies what is left. An interface osapi does not configure does not change.
HTTPDELETE
Route/api/node/{hostname}/network/interface/{name}
Permissionnetwork:write
Commandosapi client node network interface delete
Input typeDeleteInput
Output typeResult

Input (1)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
namestringyespattern ^(@fact.[a-z0-9_.]+|[a-zA-Z0-9][a-zA-Z0-9._-]{0,14})$The interface, such as eth0, or a fact such as @fact.interface.primary

Output (2)​

FIELDTYPEDESCRIPTION
namestringThe interface
changedbooleanWhether the host changed

Examples (2)​

EXAMPLEINPUTOUTPUT
An interface osapi configuresname=osapi0name=osapi0, changed=true
An interface osapi does not configurename=osapi0name=osapi0, changed=false