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
| Name | interface |
| Description | The network interfaces of the host |
| Placement | node |
| Group | network |
| Internal | no |
| API | yes |
| CLI | yes |
| Next | no |
| Platforms | debian, linux, darwin |
| Sudo | none |
| Runs | none |
| Writes | /etc/netplan/osapi-*.yaml |
| Keeps state | no |
| Uses | netplan |
| Used by | none |
Methods (5)
| NAME | VERB | HTTP | ROUTE | PERMISSION | DESCRIPTION |
|---|---|---|---|---|---|
| list | read | GET | /api/node/{hostname}/network/interface | network:read | List the network interfaces of the host |
| get | read | GET | /api/node/{hostname}/network/interface/{name} | network:read | Get a network interface of the host |
| create | write | POST | /api/node/{hostname}/network/interface/{name} | network:write | Configure a network interface |
| update | write | PUT | /api/node/{hostname}/network/interface/{name} | network:write | Change the config osapi has of a network interface |
| delete | write | DELETE | /api/node/{hostname}/network/interface/{name} | network:write | Drop the config osapi has of a network interface |
Types (5)
| NAME | INPUT | OUTPUT |
|---|---|---|
| list | ListInput | []Entry { name, state, mac, mtu, ipv4, ipv6, addresses, dhcp4, primary } |
| get | GetInput { name* } | Entry { name, state, mac, mtu, ipv4, ipv6, addresses, dhcp4, primary } |
| create | CreateInput { name*, dhcp4, dhcp6, addresses, gateway4, gateway6, mtu, mac_address, wakeonlan } | Result { name, changed } |
| update | UpdateInput { name*, dhcp4, dhcp6, addresses, gateway4, gateway6, mtu, mac_address, wakeonlan } | Result { name, changed } |
| delete | DeleteInput { name* } | Result { name, changed } |
Settings (0)
None. Declare them with behavior.Config.
Telemetry
| Span | behavior.interface.<method> |
| Child spans | behavior.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 |
| Metrics | osapi_behavior_calls_total, osapi_behavior_duration_seconds, osapi_behavior_changes_total |
| Attributes | osapi.behavior.name, osapi.behavior.method, osapi.behavior.verb, osapi.behavior.outcome, osapi.behavior.changed |
| Recorded inputs | name (get, create, update, delete) |
Method list
| Name | list |
| Verb | read |
| Description | List the network interfaces of the host |
| Detail | Reads 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. |
| HTTP | GET |
| Route | /api/node/{hostname}/network/interface |
| Permission | network:read |
| Command | osapi client node network interface list |
| Input type | ListInput |
| Output type | []Entry |
Input (0)
None. The method takes no input; its command needs only --target.
Output (9)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| name | string | The interface |
| state | string | up or down |
| mac | string | Its MAC address; empty for one without, such as lo |
| mtu | integer | Its MTU |
| ipv4 | string | Its first IPv4 address that is not link-local |
| ipv6 | string | Its first IPv6 address that is not link-local |
| addresses | array | Each of its addresses, in CIDR notation |
| dhcp4 | boolean | Whether DHCP gave it an IPv4 address: a route of it has proto dhcp |
| primary | boolean | Whether it has the default route |
Examples (2)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| 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
| Name | get |
| Verb | read |
| Description | Get a network interface of the host |
| Detail | Reads the interface as list does. |
| HTTP | GET |
| Route | /api/node/{hostname}/network/interface/{name} |
| Permission | network:read |
| Command | osapi client node network interface get |
| Input type | GetInput |
| Output type | Entry |
Input (1)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| name | string | yes | pattern ^(@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)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| name | string | The interface |
| state | string | up or down |
| mac | string | Its MAC address; empty for one without, such as lo |
| mtu | integer | Its MTU |
| ipv4 | string | Its first IPv4 address that is not link-local |
| ipv6 | string | Its first IPv6 address that is not link-local |
| addresses | array | Each of its addresses, in CIDR notation |
| dhcp4 | boolean | Whether DHCP gave it an IPv4 address: a route of it has proto dhcp |
| primary | boolean | Whether it has the default route |
Examples (2)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| An interface with a DHCP address | name=eth0 | name=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 Mac | name=en0 | name=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
| Name | create |
| Verb | write |
| Description | Configure a network interface |
| Detail | Writes 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. |
| HTTP | POST |
| Route | /api/node/{hostname}/network/interface/{name} |
| Permission | network:write |
| Command | osapi client node network interface create |
| Input type | CreateInput |
| Output type | Result |
Input (9)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| name | string | yes | pattern ^(@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 |
| dhcp4 | boolean | no | Take an IPv4 address from DHCP | |
| dhcp6 | boolean | no | Take an IPv6 address from DHCP | |
| addresses | array | no | The static addresses, in CIDR notation, such as 10.0.0.5/24 | |
| gateway4 | string | no | format ipv4 | The IPv4 default gateway |
| gateway6 | string | no | format ipv6 | The IPv6 default gateway |
| mtu | integer | no | min 68, max 9000 | The MTU, from 68 to 9000 |
| mac_address | string | no | pattern ^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$ | The MAC address to set |
| wakeonlan | boolean | no | Turn on wake-on-LAN |
Output (2)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| name | string | The interface |
| changed | boolean | Whether the host changed |
Examples (3)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| A static address | name=osapi0, addresses=[10.0.1.5/24] | name=osapi0, changed=true |
| Each setting | name=osapi0, dhcp6=true, addresses=[2001:db8::5/64], mtu=9000, mac_address=52:54:00:aa:bb:cc, wakeonlan=true | name=osapi0, changed=true |
| An interface osapi already configures | name=osapi0, addresses=[10.0.1.5/24] | name=osapi0, changed=false |
Method update
| Name | update |
| Verb | write |
| Description | Change the config osapi has of a network interface |
| Detail | Writes 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. |
| HTTP | PUT |
| Route | /api/node/{hostname}/network/interface/{name} |
| Permission | network:write |
| Command | osapi client node network interface update |
| Input type | UpdateInput |
| Output type | Result |
Input (9)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| name | string | yes | pattern ^(@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 |
| dhcp4 | boolean | no | Take an IPv4 address from DHCP | |
| dhcp6 | boolean | no | Take an IPv6 address from DHCP | |
| addresses | array | no | The static addresses, in CIDR notation, such as 10.0.0.5/24 | |
| gateway4 | string | no | format ipv4 | The IPv4 default gateway |
| gateway6 | string | no | format ipv6 | The IPv6 default gateway |
| mtu | integer | no | min 68, max 9000 | The MTU, from 68 to 9000 |
| mac_address | string | no | pattern ^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$ | The MAC address to set |
| wakeonlan | boolean | no | Turn on wake-on-LAN |
Output (2)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| name | string | The interface |
| changed | boolean | Whether the host changed |
Examples (1)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| Move an interface to DHCP | name=osapi0, dhcp4=true | name=osapi0, changed=true |
Method delete
| Name | delete |
| Verb | write |
| Description | Drop the config osapi has of a network interface |
| Detail | Removes the interface's netplan file and applies what is left. An interface osapi does not configure does not change. |
| HTTP | DELETE |
| Route | /api/node/{hostname}/network/interface/{name} |
| Permission | network:write |
| Command | osapi client node network interface delete |
| Input type | DeleteInput |
| Output type | Result |
Input (1)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| name | string | yes | pattern ^(@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)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| name | string | The interface |
| changed | boolean | Whether the host changed |
Examples (2)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| An interface osapi configures | name=osapi0 | name=osapi0, changed=true |
| An interface osapi does not configure | name=osapi0 | name=osapi0, changed=false |