Skip to main content

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​

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

Methods (5)​

NAMEVERBHTTPROUTEPERMISSIONDESCRIPTION
listreadGET/api/node/{hostname}/network/routenetwork:readList the routes of the host
getreadGET/api/node/{hostname}/network/route/{interface_name}network:readGet the routes of an interface
createwritePOST/api/node/{hostname}/network/route/{interface_name}network:writeAdd static routes to an interface
updatewritePUT/api/node/{hostname}/network/route/{interface_name}network:writeChange the routes osapi has of an interface
deletewriteDELETE/api/node/{hostname}/network/route/{interface_name}network:writeDrop the routes osapi has of an interface

Types (5)​

NAMEINPUTOUTPUT
listListInput[]Entry { destination, gateway, interface, family, metric, proto, scope }
getGetInput { interface_name* }[]Entry { destination, gateway, interface, family, metric, proto, scope }
createCreateInput { interface_name*, routes* }Result { interface_name, changed }
updateUpdateInput { interface_name*, routes* }Result { interface_name, changed }
deleteDeleteInput { interface_name* }Result { interface_name, changed }

Settings (0)​

None. Declare them with behavior.Config.

Telemetry​

Spanbehavior.route.<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 inputsinterface_name (get, create, update, delete)

Method list​

Namelist
Verbread
DescriptionList the routes of the host
DetailReads 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.
HTTPGET
Route/api/node/{hostname}/network/route
Permissionnetwork:read
Commandosapi client node network route list
Input typeListInput
Output type[]Entry

Input (0)​

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

Output (7)​

FIELDTYPEDESCRIPTION
destinationstringThe destination in CIDR notation, or default
gatewaystringThe gateway; empty for a route on the link
interfacestringThe interface the route goes out of
familystringinet or inet6
metricintegerThe metric; 0 when the kernel gives none
protostringWhere the route came from, such as kernel, dhcp or static; empty on macOS
scopestringThe scope, such as link; empty for a global route

Examples (2)​

EXAMPLEINPUTOUTPUT
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​

Nameget
Verbread
DescriptionGet the routes of an interface
DetailReads 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.
HTTPGET
Route/api/node/{hostname}/network/route/{interface_name}
Permissionnetwork:read
Commandosapi client node network route get
Input typeGetInput
Output type[]Entry

Input (1)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
interface_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 (7)​

FIELDTYPEDESCRIPTION
destinationstringThe destination in CIDR notation, or default
gatewaystringThe gateway; empty for a route on the link
interfacestringThe interface the route goes out of
familystringinet or inet6
metricintegerThe metric; 0 when the kernel gives none
protostringWhere the route came from, such as kernel, dhcp or static; empty on macOS
scopestringThe scope, such as link; empty for a global route

Examples (3)​

EXAMPLEINPUTOUTPUT
An interface with routesinterface_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 routesinterface_name=eth1
A Macinterface_name=en0[destination=default, family=inet, gateway=192.168.0.1, interface=en0, metric=0, proto=, scope=]

Method create​

Namecreate
Verbwrite
DescriptionAdd static routes to an interface
DetailWrites 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.
HTTPPOST
Route/api/node/{hostname}/network/route/{interface_name}
Permissionnetwork:write
Commandosapi client node network route create
Input typeCreateInput
Output typeResult

Input (2)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
interface_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
routesarrayyesEach 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)​

FIELDTYPEDESCRIPTION
interface_namestringThe interface
changedbooleanWhether the host changed

Examples (2)​

EXAMPLEINPUTOUTPUT
Two routesinterface_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 ofinterface_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​

Nameupdate
Verbwrite
DescriptionChange the routes osapi has of an interface
DetailWrites 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.
HTTPPUT
Route/api/node/{hostname}/network/route/{interface_name}
Permissionnetwork:write
Commandosapi client node network route update
Input typeUpdateInput
Output typeResult

Input (2)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
interface_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
routesarrayyesEach 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)​

FIELDTYPEDESCRIPTION
interface_namestringThe interface
changedbooleanWhether the host changed

Examples (1)​

EXAMPLEINPUTOUTPUT
One route in place of twointerface_name=osapi0, routes=[203.0.113.0/24 via 192.0.2.1 metric 10]interface_name=osapi0, changed=true

Method delete​

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

Input (1)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
interface_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
interface_namestringThe interface
changedbooleanWhether the host changed

Examples (2)​

EXAMPLEINPUTOUTPUT
An interface osapi has routes ofinterface_name=osapi0interface_name=osapi0, changed=true
An interface osapi has no routes ofinterface_name=osapi0interface_name=osapi0, changed=false