1 OVROUTE(1M) Maintenance Commands OVROUTE(1M) 2 3 NAME 4 ovroute - overlay router management 5 6 SYNOPSIS 7 ovroute router create -d overlay -m macaddr -v vlan -a address/mask 8 [-a address/mask] [-r route_table_id] router_id 9 ovroute router delete -d overlay router_id 10 ovroute router get -d overlay [-o field[,...] [-p]] [router_id...] 11 ovroute router set-routing-table -d overlay -r route_table_id router_id 12 ovroute route-table create -d overlay route_table_id 13 ovroute route-table delete -d overlay route_table_id 14 ovroute route-table get -d overlay route_table_id [-o field[,...] [-p]] 15 [route_table_id...] 16 ovroute route-table set-default -d overlay route_table_id 17 ovroute route-table add -d overlay -i route_table_id destination target 18 ovroute route-table del -d overlay -i route_table_id destination target 19 20 DESCRIPTION 21 The ovroute utility is used to manage routers within an overlay(5) 22 network. overlay(5) routers are used to move packets within an overlay 23 network off the virtual layer two (VL2) network. 24 25 For example, two VL2 subnets may wish to route packets to each other, 26 regardless of which physical system instances using those VL2 networks 27 reside. As long as the underlay IPs (the UL3 address ka the IP address 28 of the underlying interface the overlay instance sits on, e.g. the IP 29 address of `sdc_underlay0') of the source and destination systems are 30 reachable to each other, and the virtual layer three (VL3) -> virtual 31 layer two (VL2) mappings for the source and destination VL3 IPs, the 32 ovroute command can be run to setup routing between these two subnets. 33 Normally, these entries are managed automatically -- e.g. by the Triton 34 `net-agent' process, and should normally not need to be altered by an 35 operator. 36 37 To route packets between VL2 subnets, an overlay(5) router instance is 38 created for each VL2 network where packets are intended to be routed. A 39 overlay(5) router instance should be created on any physical machine 40 where the corresponding VL2 subnet is in use. 41 42 For example, if a subnet with a vlan id of `2112' and an address range of 43 `192.168.1.0/24' on overlay `sdc_underlay42' exists, then any machine 44 that houses an instance with an IP address within `192.168.1.0/24' should 45 have an overlay router instance for the `192.168.1.0/24' subnet created 46 on it. The address/mask and macaddr parameters should be the same for 47 all such systems. It is also recommended, but not required, that the 48 router id used also match. It is not necessary to create an overlay(5) 49 router instance on a machine if the corresponding subnet is not in use 50 (no instances have IP assigned to the subnet) on that machine. 51 52 Additionally, an overlay(5) route table must be associated with each 53 overlay(5) router instance before any routing will occur. Multiple 54 router instances in a given overlay(5) instance can share the same route 55 table. Both the source and destination systems must be configured with 56 overlay(5) router instances for any VL2 networks that wish to route 57 packets between each other. Failure to do so will result in dropped 58 packets. 59 60 Once the router instances and router tables have been created, any 61 packets sent to the VL3 router IP by the instance (using the instance's 62 routing table), will then have the destination VL3 IP matched in the 63 overlay(5) routing table for the router instance that received the 64 packet. The match is a longest prefix match, similar to how route(7P) 65 works for traditional IP forwarding. If the target address is the "any" 66 (`0.0.0.0' or `::0') address, the packets are routed to the destination 67 subnet and the destionation machine. If another address in the 68 overlay(5) routing table is the longest prefix match for the VL3 69 destination IP, the corresponding target IP:port value is the underlay IP 70 address where the encapsulated packet is sent. This is normally used for 71 features such as EIP, NAT or ELB. If there is no matching destination, 72 the packet is dropped. 73 74 OPTIONS 75 The following options are supported: 76 77 ovroute router create -d overlay -m macaddr -v vlan -a address/mask [-a 78 address/mask] [-r -route_table_id] router_id 79 80 Create an overlay(5) router instance on the overlay device 81 overlay with an id of router_id. The router_id must be a unique 82 identifer across all the overlay(5) router instances for the 83 given overlay(5) instance. Valid id values consists of 84 characters from the set [A-Za-z0-9.-]. The MAC address for the 85 router instance is specified by macaddr and the vlan id of the 86 network for the router is given by vlan. The IP address and 87 subnet mask the router instance listens on is given by 88 address/mask. If the subnet has both an IPv4 and IPv6 address, 89 an additional -a address/mask option may be specified, but at 90 most only 1 IPv4 and 1 IPv6 address may be given (and at least 1 91 address must be specified). 92 93 Optionally, if an overlay(5) routing table has already been 94 defined, the -r route_table_id option can be specified to 95 associate the the VL2 subnet to the given overlay(5) route 96 table. If no route table is specified, the default route table 97 for the overlay(5) device (if set) will be used. 98 99 ovroute router delete -d overlay router_id 100 Delete the overlay(5) router instance denoted by router_id. 101 102 ovroute router get -d overlay [-o field[,...] [-p]] [router_id...] 103 Get the information about overlay(5) router router_id. If no 104 router_id is specified, all overlay(5) router instances defined 105 for overlay are printed. If the -o option is specified, the 106 output is limited to the comma separated list of fields given by 107 the field arguments(s): 108 109 id The router_id as passed in to the ovroute 110 router create command. 111 112 network The overlay IPv4 network and CIDR mask the 113 router listens on, e.g. `192.168.1.0/24'. 114 115 network-v6 The overlay IPv6 network and CIDR mask the 116 router listens on. 117 118 vlan The VLAN id of the subnet the overlay router 119 instance is listening on. 120 121 mac The MAC address the overlay router instance 122 uses for the given subnet. 123 124 rtable The overlay routing table associated with this 125 subnet (if any). 126 127 Additionally, the -p option may be passed with the -o option to 128 indicate the output should be in a machine parsable (colon 129 delimited) format. The -p option requires specifying the -o 130 option to indicate the fields to output. 131 132 ovroute router set-routing-table -d overlay -r route_table_id router_id 133 Set the the routing table for router_id on overlay overlay to 134 route_table_id. route_table_id must already exist, or the 135 command will return an error. 136 137 ovroute route-table create -d overlay -r route_table_id router_id 138 Creates an empty overlay(5) router table with an id Ar 139 route_table_id for overlay overlay. If the route table already 140 exists, an error is returned. 141 142 ovroute route-table delete -d overlay route_table_id 143 Deletes the route table route_table_id on overlay overlay. 144 145 ovroute route-table get -d overlay [-o field[,...] [-p]] 146 [route_table_id...] 147 Display the routing table route_table_id on overlay overlay. If 148 more than one route_table_id is specified, each route table is 149 displayed. If no route tables are specified, all route tables 150 on overlay are displayed. If the -o option is specified, a 151 comma separated list of fields must be specified to indicate the 152 fields to display. The field values may be any combination of: 153 154 id The overlay route table id as is given in the 155 ovroute route-table create command. 156 157 destination The virtual layer three (VL3) address of the 158 destination in CIDR format. In other words, 159 the destination subnet and CIDR mask as seen 160 by instances in the overlay network. 161 162 target The underlay layer three (UL3) address and 163 port to send the matching traffic. In other 164 words, the destination address of the 165 encapsulated packet. 166 167 Additionally, the -p option may be given with the -o option to 168 generate output in machine parsable (colon delimited) format. 169 170 ovroute route-table set-default -d overlay route_table_id 171 Set the default routing table for overlay to route_table_id. If 172 route_table_id doesn't exist, an error is returned. 173 174 ovroute route-table add -d overlay -i route_table_id destination target 175 Adds an route table entry to the route table route_table_id in 176 overlay overlay. 177 178 ovroute route-table del -d overlay -i route_table_id destination target 179 Removes a route table entry from the route table route_table_id 180 in overlay overlay. 181 182 OPERANDS 183 The following operands are supported: 184 185 overlay The overlay device to operate on. For example 186 `sdc_underlay1234'. 187 188 macaddr A MAC address such as `90:01:02:03:04:05'. 189 190 vlan A VLAN id. Valid VLAN ids range from 1 - 4096. 191 192 address/mask An IPv4 or IPv6 address and CIDR mask length, e.g. 193 `192.168.1.0/24'. 194 195 route_table_id 196 A routing table id. 197 198 router_id An overlay(5) router id. 199 200 destination The virtual layer three (VL3) destination CIDR block for an 201 overlay(5) route table entry. For example, `10.1.2.0/24' 202 or `2001::1/96'. 203 204 target The underlay layer three (UL3) address and port that 205 receives the encapsulated virtual packet. For IPv4 206 addresses this in the form of `IP addr:port'. For IPv6 207 addresses, to disambiguate the address from the port, the 208 address must be in the form of `[IPv6 addr]:port'. The 209 IPv4 address can optionally be given in this form as well, 210 but it is not required. An "any" (e.g. `0.0.0.0/0' or 211 `::0/0') address (with no port) indicates the encapsulated 212 packet should be routed and delivered to the machine that 213 contains the VL3 destination address of the packet. 214 215 EXIT STATUS 216 The ovroute utility exits 0 on success, and >0 if an error occurs. 217 218 EXAMPLES 219 Example 1 220 221 In this setup, we have the following hosts, all using an overlay instance 222 `sdc_overlay7224243' with a vnet ID of `7224243': 223 +------+------+----------------+ 224 |HOST | VLAN | SUBNET | 225 +------+------+----------------+ 226 |hostA | 42 | 192.168.1.0/24 | 227 +------+------+----------------+ 228 |hostB | 2112 | 192.168.2.0/24 | 229 +------+------+----------------+ 230 |hostC | 42 | 192.168.1.0/24 | 231 | | 2112 | 192.168.2.0/24 | 232 +------+------+----------------+ 233 The router instances will be as follows: 234 +---------------+-------------+-------------------+ 235 | SUBNET | ROUTER IP | ROUTER MAC | 236 +---------------+-------------+-------------------+ 237 |192.168.1.0/24 | 192.168.1.1 | 90:b8:d0:17:f7:be | 238 +---------------+-------------+-------------------+ 239 |192.168.2.0/24 | 192.168.2.2 | 90:b8:d0:7f:36:ac | 240 +---------------+-------------+-------------------+ 241 To enable all three vnics to route traffic between the two subnets, the 242 appropriate router instances must be created on each host. Additionally, 243 a routing table must be created to indicate that the traffic sent to the 244 router IP should be routed to the other subnets. 245 246 The following commands are run on the respective hosts to enable this: 247 248 hostA# ovroute router create -d sdc_overlay7224243 -m 90:b8:d0:17:f7:be -v 42 -a 192.168.1.1/24 router-42 249 hostA# ovroute route-table create -d sdc_overlay7224243 rtab-default 250 hostA# ovroute route-table set-default -d sdc_overlay7224243 rtab-default 251 hostA# ovroute route-table add -d sdc_overlay7224243 -i rtab-default 0.0.0.0/0 0.0.0.0 252 253 hostB# ovroute router create -d sdc_overlay7224243 -m 90:b8:d0:7f:36:ac -v 2112 -a 192.168.2.1/24 router-2112 254 hostB# ovroute route-table create -d sdc_overlay7224243 rtab-default 255 hostB# ovroute route-table set-default -d sdc_overlay7224243 rtab-default 256 hostB# ovroute route-table add -d sdc_overlay7224243 -i rtab-default 0.0.0.0/0 0.0.0.0 257 258 hostC# ovroute router create -d sdc_overlay7224243 -m 90:b8:d0:17:f7:be -v 42 -a 192.168.1.1/24 router-42 259 hostC# ovroute router create -d sdc_overlay7224243 -m 90:b8:d0:7f:36:ac -v 2112 -a 192.168.2.1/24 router-2112 260 hostC# ovroute route-table create -d sdc_overlay7224243 rtab-default 261 hostC# ovroute route-table set-default -d sdc_overlay7224243 rtab-default 262 hostC# ovroute route-table add -d sdc_overlay7224243 -i rtab-default 0.0.0.0/0 0.0.0.0 263 264 Note that `192.168.0.0/16 0.0.0.0' or similar could also have been used 265 in the routing table to route the traffic. As long as the destination 266 network and mask match the traffic. 267 268 INTERFACE STABILITY 269 Private 270 271 This is intented to be an internal Triton utility, and it's command line 272 interface may change without notice. 273 274 SEE ALSO 275 overlay(5), route(7P) 276 277 illumos October 26, 2020 illumos