OVROUTE(1M) Maintenance Commands OVROUTE(1M)

ovroute —
overlay router management

ovroute router create -d overlay -m macaddr -v vlan -a address/mask [-a address/mask] [-r route_table_id] router_id

ovroute router delete -d overlay router_id

ovroute router get -d overlay [-o field[,...] [-p]] [router_id...]

ovroute router set-routing-table -d overlay -r route_table_id router_id

ovroute route-table create -d overlay route_table_id

ovroute route-table delete -d overlay route_table_id

ovroute route-table get -d overlay route_table_id [-o field[,...] [-p]] [route_table_id...]

ovroute route-table set-default -d overlay route_table_id

ovroute route-table add -d overlay -i route_table_id destination target

ovroute route-table del -d overlay -i route_table_id destination target

The ovroute utility is used to manage routers within an overlay(5) network. overlay(5) routers are used to move packets within an overlay network off the virtual layer two (VL2) network.

For example, two VL2 subnets may wish to route packets to each other, regardless of which physical system instances using those VL2 networks reside. As long as the underlay IPs (the UL3 address ka the IP address of the underlying interface the overlay instance sits on, e.g. the IP address of ‘sdc_underlay0’) of the source and destination systems are reachable to each other, and the virtual layer three (VL3) → virtual layer two (VL2) mappings for the source and destination VL3 IPs, the ovroute command can be run to setup routing between these two subnets. Normally, these entries are managed automatically — e.g. by the Triton ‘net-agent’ process, and should normally not need to be altered by an operator.

To route packets between VL2 subnets, an overlay(5) router instance is created for each VL2 network where packets are intended to be routed. A overlay(5) router instance should be created on any physical machine where the corresponding VL2 subnet is in use.

For example, if a subnet with a vlan id of ‘2112’ and an address range of ‘192.168.1.0/24’ on overlay ‘sdc_underlay42’ exists, then any machine that houses an instance with an IP address within ‘192.168.1.0/24’ should have an overlay router instance for the ‘192.168.1.0/24’ subnet created on it. The address/mask and macaddr parameters should be the same for all such systems. It is also recommended, but not required, that the router id used also match. It is not necessary to create an overlay(5) router instance on a machine if the corresponding subnet is not in use (no instances have IP assigned to the subnet) on that machine.

Additionally, an overlay(5) route table must be associated with each overlay(5) router instance before any routing will occur. Multiple router instances in a given overlay(5) instance can share the same route table. Both the source and destination systems must be configured with overlay(5) router instances for any VL2 networks that wish to route packets between each other. Failure to do so will result in dropped packets.

Once the router instances and router tables have been created, any packets sent to the VL3 router IP by the instance (using the instance's routing table), will then have the destination VL3 IP matched in the overlay(5) routing table for the router instance that received the packet. The match is a longest prefix match, similar to how route(7P) works for traditional IP forwarding. If the target address is the “any” (‘0.0.0.0’ or ‘::0’) address, the packets are routed to the destination subnet and the destionation machine. If another address in the overlay(5) routing table is the longest prefix match for the VL3 destination IP, the corresponding target IP:port value is the underlay IP address where the encapsulated packet is sent. This is normally used for features such as EIP, NAT or ELB. If there is no matching destination, the packet is dropped.

The following options are supported:
ovroute router create -d overlay -m macaddr -v vlan -a address/mask [-a address/mask] [-r -route_table_id] router_id

Create an overlay(5) router instance on the overlay device overlay with an id of router_id. The router_id must be a unique identifer across all the overlay(5) router instances for the given overlay(5) instance. Valid id values consists of characters from the set [A-Za-z0-9.-]. The MAC address for the router instance is specified by macaddr and the vlan id of the network for the router is given by vlan. The IP address and subnet mask the router instance listens on is given by address/mask. If the subnet has both an IPv4 and IPv6 address, an additional -a address/mask option may be specified, but at most only 1 IPv4 and 1 IPv6 address may be given (and at least 1 address must be specified).

Optionally, if an overlay(5) routing table has already been defined, the -r route_table_id option can be specified to associate the the VL2 subnet to the given overlay(5) route table. If no route table is specified, the default route table for the overlay(5) device (if set) will be used.

ovroute router delete -d overlay router_id
Delete the overlay(5) router instance denoted by router_id.
ovroute router get -d overlay [-o field[,...] [-p]] [router_id...]
Get the information about overlay(5) router router_id. If no router_id is specified, all overlay(5) router instances defined for overlay are printed. If the -o option is specified, the output is limited to the comma separated list of fields given by the field arguments(s):
id
The router_id as passed in to the ovroute router create command.
network
The overlay IPv4 network and CIDR mask the router listens on, e.g. ‘192.168.1.0/24’.
network-v6
The overlay IPv6 network and CIDR mask the router listens on.
vlan
The VLAN id of the subnet the overlay router instance is listening on.
mac
The MAC address the overlay router instance uses for the given subnet.
rtable
The overlay routing table associated with this subnet (if any).

Additionally, the -p option may be passed with the -o option to indicate the output should be in a machine parsable (colon delimited) format. The -p option requires specifying the -o option to indicate the fields to output.

ovroute router set-routing-table -d overlay -r route_table_id router_id
Set the the routing table for router_id on overlay overlay to route_table_id. route_table_id must already exist, or the command will return an error.
ovroute route-table create -d overlay -r route_table_id router_id
Creates an empty overlay(5) router table with an id Ar route_table_id for overlay overlay. If the route table already exists, an error is returned.
ovroute route-table delete -d overlay route_table_id
Deletes the route table route_table_id on overlay overlay.
ovroute route-table get -d overlay [-o field[,...] [-p]] [route_table_id...]
Display the routing table route_table_id on overlay overlay. If more than one route_table_id is specified, each route table is displayed. If no route tables are specified, all route tables on overlay are displayed. If the -o option is specified, a comma separated list of fields must be specified to indicate the fields to display. The field values may be any combination of:
id
The overlay route table id as is given in the ovroute route-table create command.
destination
The virtual layer three (VL3) address of the destination in CIDR format. In other words, the destination subnet and CIDR mask as seen by instances in the overlay network.
target
The underlay layer three (UL3) address and port to send the matching traffic. In other words, the destination address of the encapsulated packet.

Additionally, the -p option may be given with the -o option to generate output in machine parsable (colon delimited) format.

ovroute route-table set-default -d overlay route_table_id
Set the default routing table for overlay to route_table_id. If route_table_id doesn't exist, an error is returned.
ovroute route-table add -d overlay -i route_table_id destination target
Adds an route table entry to the route table route_table_id in overlay overlay.
ovroute route-table del -d overlay -i route_table_id destination target
Removes a route table entry from the route table route_table_id in overlay overlay.

The following operands are supported:
overlay
The overlay device to operate on. For example ‘sdc_underlay1234’.
macaddr
A MAC address such as ‘90:01:02:03:04:05’.
vlan
A VLAN id. Valid VLAN ids range from 1 - 4096.
address/mask
An IPv4 or IPv6 address and CIDR mask length, e.g. ‘192.168.1.0/24’.
route_table_id
A routing table id.
router_id
An overlay(5) router id.
destination
The virtual layer three (VL3) destination CIDR block for an overlay(5) route table entry. For example, ‘10.1.2.0/24’ or ‘2001::1/96’.
target
The underlay layer three (UL3) address and port that receives the encapsulated virtual packet. For IPv4 addresses this in the form of ‘IP addr:port’. For IPv6 addresses, to disambiguate the address from the port, the address must be in the form of ‘[IPv6 addr]:port’. The IPv4 address can optionally be given in this form as well, but it is not required. An “any” (e.g. ‘0.0.0.0/0’ or ‘::0/0’) address (with no port) indicates the encapsulated packet should be routed and delivered to the machine that contains the VL3 destination address of the packet.

The ovroute utility exits 0 on success, and >0 if an error occurs.

Example 1

In this setup, we have the following hosts, all using an overlay instance ‘sdc_overlay7224243’ with a vnet ID of ‘7224243’:

HOST VLAN SUBNET
hostA 42 192.168.1.0/24
hostB 2112 192.168.2.0/24
hostC 42 192.168.1.0/24
2112 192.168.2.0/24

The router instances will be as follows:

SUBNET ROUTER IP ROUTER MAC
192.168.1.0/24 192.168.1.1 90:b8:d0:17:f7:be
192.168.2.0/24 192.168.2.2 90:b8:d0:7f:36:ac

To enable all three vnics to route traffic between the two subnets, the appropriate router instances must be created on each host. Additionally, a routing table must be created to indicate that the traffic sent to the router IP should be routed to the other subnets.

The following commands are run on the respective hosts to enable this:

hostA# ovroute router create -d sdc_overlay7224243 -m 90:b8:d0:17:f7:be -v 42 -a 192.168.1.1/24 router-42
hostA# ovroute route-table create -d sdc_overlay7224243 rtab-default
hostA# ovroute route-table set-default -d sdc_overlay7224243 rtab-default
hostA# ovroute route-table add -d sdc_overlay7224243 -i rtab-default 0.0.0.0/0 0.0.0.0

hostB# ovroute router create -d sdc_overlay7224243 -m 90:b8:d0:7f:36:ac -v 2112 -a 192.168.2.1/24 router-2112
hostB# ovroute route-table create -d sdc_overlay7224243 rtab-default
hostB# ovroute route-table set-default -d sdc_overlay7224243 rtab-default
hostB# ovroute route-table add -d sdc_overlay7224243 -i rtab-default 0.0.0.0/0 0.0.0.0

hostC# ovroute router create -d sdc_overlay7224243 -m 90:b8:d0:17:f7:be -v 42 -a 192.168.1.1/24 router-42
hostC# ovroute router create -d sdc_overlay7224243 -m 90:b8:d0:7f:36:ac -v 2112 -a 192.168.2.1/24 router-2112
hostC# ovroute route-table create -d sdc_overlay7224243 rtab-default
hostC# ovroute route-table set-default -d sdc_overlay7224243 rtab-default
hostC# ovroute route-table add -d sdc_overlay7224243 -i rtab-default 0.0.0.0/0 0.0.0.0

Note that ‘192.168.0.0/16 0.0.0.0’ or similar could also have been used in the routing table to route the traffic. As long as the destination network and mask match the traffic.

Private

This is intented to be an internal Triton utility, and it's command line interface may change without notice.

overlay(5), route(7P)
October 26, 2020 illumos