Route
The routes of the host. osapi behavior get --name route and
osapi behavior method get show the same. Its chain
shows each call that its examples make.
Behavior
| Name | route |
| Description | The routes 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-*-routes.yaml |
| Keeps state | no |
| Uses | netplan |
| Used by | none |
Methods (5)
| NAME | VERB | HTTP | ROUTE | PERMISSION | DESCRIPTION |
|---|---|---|---|---|---|
| list | read | GET | /api/node/{hostname}/network/route | network:read | List the routes of the host |
| get | read | GET | /api/node/{hostname}/network/route/{interface_name} | network:read | Get the routes of an interface |
| create | write | POST | /api/node/{hostname}/network/route/{interface_name} | network:write | Add static routes to an interface |
| update | write | PUT | /api/node/{hostname}/network/route/{interface_name} | network:write | Change the routes osapi has of an interface |
| delete | write | DELETE | /api/node/{hostname}/network/route/{interface_name} | network:write | Drop the routes osapi has of an interface |
Types (5)
| NAME | INPUT | OUTPUT |
|---|---|---|
| list | ListInput | []Entry { destination, gateway, interface, family, metric, proto, scope } |
| get | GetInput { interface_name* } | []Entry { destination, gateway, interface, family, metric, proto, scope } |
| create | CreateInput { interface_name*, routes* } | Result { interface_name, changed } |
| update | UpdateInput { interface_name*, routes* } | Result { interface_name, changed } |
| delete | DeleteInput { interface_name* } | Result { interface_name, changed } |
Settings (0)
None. Declare them with behavior.Config.
Telemetry
| Span | behavior.route.<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 | interface_name (get, create, update, delete) |
Method list
| Name | list |
| Verb | read |
| Description | List the routes of the host |
| Detail | Reads each route of the main table: ip route on Linux, netstat on macOS. proto says where a route came from, such as dhcp, kernel or static. |
| HTTP | GET |
| Route | /api/node/{hostname}/network/route |
| Permission | network:read |
| Command | osapi client node network route list |
| Input type | ListInput |
| Output type | []Entry |
Input (0)
None. The method takes no input; its command needs only --target.
Output (7)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| destination | string | The destination in CIDR notation, or default |
| gateway | string | The gateway; empty for a route on the link |
| interface | string | The interface the route goes out of |
| family | string | inet or inet6 |
| metric | integer | The metric; 0 when the kernel gives none |
| proto | string | Where the route came from, such as kernel, dhcp or static; empty on macOS |
| scope | string | The scope, such as link; empty for a global route |
Examples (2)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| A Linux host | (none) | [destination=default, family=inet, gateway=10.0.0.1, interface=eth0, metric=100, proto=dhcp, scope=] [destination=10.0.0.0/24, family=inet, gateway=, interface=eth0, metric=0, proto=kernel, scope=link] [destination=10.20.0.0/16, family=inet, gateway=10.0.0.254, interface=eth0, metric=50, proto=static, scope=] |
| A Mac | (none) | [destination=default, family=inet, gateway=192.168.0.1, interface=en0, metric=0, proto=, scope=] |
Method get
| Name | get |
| Verb | read |
| Description | Get the routes of an interface |
| Detail | Reads the routes of the main table that go out of the interface, as list does. An interface with no routes has none; one the host does not have is not found. |
| HTTP | GET |
| Route | /api/node/{hostname}/network/route/{interface_name} |
| Permission | network:read |
| Command | osapi client node network route get |
| Input type | GetInput |
| Output type | []Entry |
Input (1)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| interface_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 (7)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| destination | string | The destination in CIDR notation, or default |
| gateway | string | The gateway; empty for a route on the link |
| interface | string | The interface the route goes out of |
| family | string | inet or inet6 |
| metric | integer | The metric; 0 when the kernel gives none |
| proto | string | Where the route came from, such as kernel, dhcp or static; empty on macOS |
| scope | string | The scope, such as link; empty for a global route |
Examples (3)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| An interface with routes | interface_name=eth0 | [destination=default, family=inet, gateway=10.0.0.1, interface=eth0, metric=100, proto=dhcp, scope=] [destination=10.0.0.0/24, family=inet, gateway=, interface=eth0, metric=0, proto=kernel, scope=link] [destination=10.20.0.0/16, family=inet, gateway=10.0.0.254, interface=eth0, metric=50, proto=static, scope=] |
| An interface with no routes | interface_name=eth1 | |
| A Mac | interface_name=en0 | [destination=default, family=inet, gateway=192.168.0.1, interface=en0, metric=0, proto=, scope=] |
Method create
| Name | create |
| Verb | write |
| Description | Add static routes to an interface |
| Detail | Writes a netplan file of the interface's routes, such as /etc/netplan/osapi-osapi0-routes.yaml for osapi0, under a netplan definition that is the interface's own, and applies it. A default route is refused: the interface behavior sets the gateway. An interface the host does not have is not found. An interface that a match defines, such as cloud-init's all for en*, is refused, because the routes would go on each interface the match takes, now and later. An interface osapi already has routes of does not change: update replaces them. It runs on the Debian family, and elsewhere, and in a container, reports skipped. |
| HTTP | POST |
| Route | /api/node/{hostname}/network/route/{interface_name} |
| Permission | network:write |
| Command | osapi client node network route create |
| Input type | CreateInput |
| Output type | Result |
Input (2)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| interface_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 |
| routes | array | yes | Each route as ip route writes it: <destination> via <gateway>, with metric <n> after it when you give one, such as 10.0.0.0/8 via 192.168.1.1 metric 100 |
Output (2)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| interface_name | string | The interface |
| changed | boolean | Whether the host changed |
Examples (2)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| Two routes | interface_name=osapi0, routes=[198.51.100.0/24 via 192.0.2.1 2001:db8:1::/48 via 2001:db8::1 metric 200] | interface_name=osapi0, changed=true |
| An interface osapi already has routes of | interface_name=osapi0, routes=[198.51.100.0/24 via 192.0.2.1 2001:db8:1::/48 via 2001:db8::1 metric 200] | interface_name=osapi0, changed=false |
Method update
| Name | update |
| Verb | write |
| Description | Change the routes osapi has of an interface |
| Detail | Writes the interface's routes file over the one osapi has, as create writes it, and applies it. An interface osapi has no routes of is not found: create adds them. |
| HTTP | PUT |
| Route | /api/node/{hostname}/network/route/{interface_name} |
| Permission | network:write |
| Command | osapi client node network route update |
| Input type | UpdateInput |
| Output type | Result |
Input (2)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| interface_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 |
| routes | array | yes | Each route as ip route writes it: <destination> via <gateway>, with metric <n> after it when you give one, such as 10.0.0.0/8 via 192.168.1.1 metric 100 |
Output (2)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| interface_name | string | The interface |
| changed | boolean | Whether the host changed |
Examples (1)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| One route in place of two | interface_name=osapi0, routes=[203.0.113.0/24 via 192.0.2.1 metric 10] | interface_name=osapi0, changed=true |
Method delete
| Name | delete |
| Verb | write |
| Description | Drop the routes osapi has of an interface |
| Detail | Removes the interface's routes file and applies what is left. An interface osapi has no routes of does not change. |
| HTTP | DELETE |
| Route | /api/node/{hostname}/network/route/{interface_name} |
| Permission | network:write |
| Command | osapi client node network route delete |
| Input type | DeleteInput |
| Output type | Result |
Input (1)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| interface_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 |
|---|---|---|
| interface_name | string | The interface |
| changed | boolean | Whether the host changed |
Examples (2)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| An interface osapi has routes of | interface_name=osapi0 | interface_name=osapi0, changed=true |
| An interface osapi has no routes of | interface_name=osapi0 | interface_name=osapi0, changed=false |