1 .\" 2 .\" The contents of this file are subject to the terms of the 3 .\" Common Development and Distribution License (the "License"). 4 .\" You may not use this file except in compliance with the License. 5 .\" 6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 7 .\" or http://www.opensolaris.org/os/licensing. 8 .\" See the License for the specific language governing permissions 9 .\" and limitations under the License. 10 .\" 11 .\" When distributing Covered Code, include this CDDL HEADER in each 12 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 13 .\" If applicable, add the following below this CDDL HEADER, with the 14 .\" fields enclosed by brackets "[]" replaced with your own identifying 15 .\" information: Portions Copyright [yyyy] [name of copyright owner] 16 .\" 17 .\" 18 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved 19 .\" Copyright 2018 Nexenta Systems, Inc. 20 .\" 21 .Dd July 4, 2018 22 .Dt ROUTEADM 1M 23 .Os 24 .Sh NAME 25 .Nm routeadm 26 .Nd IP forwarding and routing configuration 27 .Sh SYNOPSIS 28 .Nm 29 .Op Fl p Op Ar option 30 .Nm 31 .Op Fl R Ar root-dir 32 .Op Fl e Ar option ... 33 .Op Fl d Ar option ... 34 .Op Fl r Ar option ... 35 .Op Fl s Ar var Ns = Ns Ar value 36 .Nm 37 .Fl l Ar fmri 38 .Nm 39 .Fl m Ar fmri 40 .Ar key Ns = Ns Ar value Oo Ar key Ns = Ns Ar value Oc Ns ... 41 .Nm 42 .Fl u 43 .Sh DESCRIPTION 44 The 45 .Nm 46 command is used to administer system-wide configuration for IP forwarding and 47 routing. 48 IP forwarding is the passing of IP packets from one network to another; IP 49 routing is the use of a routing protocol to determine routes. 50 .Pp 51 IP forwarding and routing functions are also represented as services within the 52 service management facility (SMF), and can be administered by means of 53 .Xr svcadm 1M 54 also, using the following fault management resource identifiers (FMRIs): 55 .Bd -literal 56 svc:/network/ipv4-forwarding:default 57 svc:/network/ipv6-forwarding:default 58 svc:/network/routing/route:default 59 svc:/network/routing/ripng:default 60 .Ed 61 .Pp 62 See 63 .Sx EXAMPLES 64 for relevant examples. 65 .Pp 66 In addition to enabling and disabling routing and forwarding, 67 .Nm 68 is used to interact with SMF-based routing daemon services. 69 Routing daemon services are identified by the presence of a 70 .Nm 71 application property group, which 72 .Nm 73 uses in administering the given service. 74 Routing daemon services can also specify properties relating to their operation 75 in the 76 .Cm routing 77 application property group; these can be modified by means of 78 .Nm Fl m . 79 If an FMRI for a service without such a property group is specified, an error is 80 issued and the operation is not carried out. 81 If a routing daemon has not been converted to SMF, the 82 .Cm ipv4-routing-daemon , ipv6-routing-daemon , 83 .Cm ipv4-routing-daemon-args , ipv6-routing-daemon-args , 84 and 85 .Cm ipv4-routing-stop-cmd , ipv6-routing-stop-cmd 86 variables can be used to specify the appropriate daemon for IPv4 or IPv6 87 routing. 88 .Nm 89 will then run that daemon using the 90 .Em svc:/network/routing/legacy-routing:ipv4 91 or 92 .Em svc:/network/routing/legacy-routing:ipv6 93 service as appropriate. 94 This conversion process occurs when you issue an enable 95 .Pq Fl e , 96 disable 97 .Pq Fl d 98 or an update 99 .Pq Fl u 100 command. 101 .Pp 102 The first usage, in the 103 .Sx SYNOPSIS 104 above, reports the current configuration. 105 .Sh OPTIONS 106 The following command-line options are supported: 107 .Bl -tag -width Ds 108 .It Fl d Ar option ... 109 Disable the specified option. 110 The effect is to prepare the associated services 111 .Po Em svc:/network/ipv4-forwarding:default 112 in the case of 113 .Cm ipv4-forwarding 114 .Pc 115 for disabling. 116 By means of the 117 .Cm routing-svcs 118 variable, the routing daemons are specified to be disabled on subsequent boot 119 or when 120 .Nm Fl u 121 is run. 122 .It Fl e Ar option ... 123 Enable the specified option. 124 The effect is to prepare the associated services 125 .Po Em svc:/network/ipv4-forwarding:default 126 in the case of 127 .Cm ipv4-forwarding 128 .Pc 129 for enabling. 130 By means of the 131 .Cm routing-svcs 132 variable, the routing daemons are specified to be enabled on subsequent boot or 133 when 134 .Nm Fl u 135 is run. 136 .It Fl l Ar fmri 137 List all properties in the routing application property group for the SMF 138 routing daemon service. 139 .It Fl m Ar fmri Ar key Ns = Ns Ar value 140 Change property value of property 141 .Ar key 142 to 143 .Ar value 144 in routing application property group for the SMF routing daemon service. 145 For multi-valued properties, the property name can be used multiple times in the 146 modify operation, and each associated value will be added. 147 .It Fl p Op Ar option 148 Print the configuration in parsable format. 149 If 150 .Ar option 151 is specified, only the configuration for the specified option or variable is 152 displayed. 153 .It Fl r Ar option ... 154 Revert the specified option to the system default. 155 The system defaults are specified in the description of each 156 .Ar option . 157 .It Fl R Ar root-dir 158 Specify an alternate root directory where 159 .Nm 160 applies changes. 161 .Pp 162 Note: The root file system of any non-global zones must not be referenced with 163 the 164 .Fl R 165 option. 166 Doing so might damage the global zone's file system, might compromise the 167 security of the global zone, and might damage the non-global zone's file system. 168 See 169 .Xr zones 5 . 170 .It Fl s Ar key Ns = Ns Ar value 171 Specify string values for specific variables in a comma-separated list with no 172 intervening spaces. 173 If invalid options are specified, a warning message is displayed and the program 174 exits. 175 The following variables can be specified: 176 .Bl -tag -width Ds 177 .It Cm routing-svcs Ns = Ns Ar fmrilist 178 Specifies the routing daemon services to be enabled. 179 Routing daemon services are determined to be IPv4 or IPv6 180 .Po and so enabled or disabled when 181 .Nm Fl e Ns / Ns Fl d Sy ipv4(6)-routing 182 is run 183 .Pc 184 on the basis of property values in the 185 .Nm 186 application property group. 187 Default: empty. 188 .It Cm ipv4-routing-daemon Ns = Ns Pa full_path_to_routing_daemon 189 Specifies the routing daemon to be started when 190 .Cm ipv4-routing 191 is enabled. 192 The routing daemon specified must be an executable binary or shell-script. 193 If the specified program maps to an SMF service, the service will be used, and 194 daemon arguments to the program will be transferred to the properties of the 195 service at enable time. 196 Default: empty string. 197 .It Cm ipv4-routing-daemon-args Ns = Ns Ar args 198 Specifies the startup arguments to be passed to the 199 .Cm ipv4-routing-daemon 200 when 201 .Cm ipv4-routing 202 is enabled. 203 Default: no arguments 204 .It Cm ipv4-routing-stop-cmd Ns = Ns Ar command 205 Specifies the command to be executed to stop the routing daemon when 206 .Cm ipv4-routing 207 is disabled. 208 .Ar command 209 can be an executable binary or shell-script, or a string that can be parsed by 210 .Xr system 3C . 211 Default: empty string. 212 .It Cm ipv6-routing-daemon Ns = Ns Pa full_path_to_routing_daemon 213 Specifies the routing daemon to be started when 214 .Cm ipv6-routing 215 is enabled. 216 The routing daemon specified must be an executable binary or shell-script. 217 If the specified program maps to an SMF service, the service will be used, and 218 daemon arguments to the program will be transferred to the properties of the 219 service at enable time. 220 Default: empty string. 221 .It Cm ipv6-routing-daemon-args Ns = Ns Ar args 222 Specifies the startup arguments to be passed to the 223 .Cm ipv6-routing-daemon 224 when 225 .Cm ipv6-routing 226 is enabled. 227 Default: empty string. 228 .It Cm ipv6-routing-stop-cmd Ns = Ns Ar command 229 Specifies the command to be executed to stop the routing daemon when 230 .Cm ipv6-routing 231 is disabled. 232 .Ar command 233 can be an executable binary or shell-script, or a string that can be parsed by 234 .Xr system 3C . 235 Default: empty string. 236 .El 237 .It Fl u 238 Apply the currently configured options to the running system. 239 These options might include enabling or disabling IP forwarding and launching or 240 killing routing daemons, if any are specified. 241 It does not alter the state of the system for those settings that have been set 242 to default. 243 This option is meant to be used by administrators who do not want to reboot to 244 apply their changes. 245 In addition, this option upgrades non-SMF configurations from the invocations 246 of daemon stop commands, which might include a set of arguments, to a simple 247 enabling of the appropriate service. 248 .El 249 .Pp 250 Multiple 251 .Fl e , 252 .Fl d , 253 and 254 .Fl r 255 options can be specified on the command line. 256 Changes made by 257 .Fl e , 258 .Fl d , 259 and 260 .Fl r 261 are persistent, but are not applied to the running system unless 262 .Nm 263 is called later with the 264 .Fl u 265 option. 266 .Pp 267 Use the following options as arguments to the 268 .Fl e , 269 .Fl d , 270 and 271 .Fl r 272 options 273 .Po shown above as 274 .Ar option ... 275 .Pc : 276 .Bl -tag -width Ds 277 .It Cm ipv4-forwarding 278 Controls the global forwarding configuration for all IPv4 interfaces. 279 The system default is 280 .Cm disabled . 281 If enabled, IP will forward IPv4 packets to and from interfaces when 282 appropriate. 283 If disabled, IP will not forward IPv4 packets to and from interfaces when 284 appropriate. 285 The SMF service associated with this configuration variable is 286 .Em svc:/network/routing/ipv4-forwarding . 287 This service will be enabled or disabled as appropriate when 288 .Nm 289 is called with the 290 .Fl u 291 option. 292 As an alternative, you can use 293 .Xr svcadm 1M . 294 Services that require 295 .Cm ipv4-forwarding 296 to be enabled should specify a dependency on this service. 297 .It Cm ipv4-routing 298 Determines whether an IPv4 routing daemon is run. 299 The system default is 300 .Cm disabled . 301 The value of this option reflects the state of all IPv4 routing services, such 302 that if any IPv4 routing service is enabled, 303 .Cm ipv4-routing 304 is enabled. 305 This allows users to interact with routing services using 306 .Xr svcadm 1M , 307 as well as through 308 .Nm . 309 IPv4 routing services, specified by means of the 310 .Cm routing-svcs 311 variable, will be prepared for enable on next boot when the user explicitly 312 enables 313 .Cm ipv4-routing . 314 .It Cm ipv6-forwarding 315 Controls the global forwarding configuration for all IPv6 interfaces. 316 The system default is 317 .Cm disabled . 318 If enabled, IP will forward IPv6 packets to and from interfaces when 319 appropriate. 320 If disabled, IP will not forward IPv6 packets to and from interfaces when 321 appropriate. 322 The SMF service associated with this configuration variable is 323 .Em svc:/network/routing/ipv6-forwarding . 324 This service will be enabled or disabled as appropriate when 325 .Nm 326 is called with the 327 .Fl u 328 option, or 329 .Xr svcadm 1M 330 is used. 331 Services that require 332 .Cm ipv6-forwarding 333 to be enabled should specify a dependency on this service. 334 .It Cm ipv6-routing 335 Determines whether an IPv6 routing daemon is run. 336 The system default is 337 .Cm disabled . 338 The value of this option reflects the state of all IPv6 routing services, such 339 that, if any IPv6 routing service is enabled, 340 .Cm ipv6-routing 341 is enabled. 342 This allows users to interact with routing services via 343 .Xr svcadm 1M 344 as well as through 345 .Nm . 346 IPv6 routing services, specified by means of the 347 .Cm routing-svcs 348 variable, will be prepared for enable on next boot when the user explicitly 349 enables 350 .Cm ipv6-routing . 351 .El 352 .Pp 353 The forwarding and routing settings are related but not mutually dependent. 354 For example, a router typically forwards IP packets and uses a routing protocol, 355 but nothing would prevent an administrator from configuring a router that 356 forwards packets and does not use a routing protocol. 357 In that case, the administrator would enable forwarding, disable routing, and 358 populate the router's routing table with static routes. 359 .Pp 360 The forwarding settings are global settings. 361 Each interface also has an 362 .Em IFF_ROUTER 363 forwarding flag that determines whether packets can be forwarded to or from a 364 particular interface. 365 That flag can be independently controlled by means of 366 .Xr ifconfig 1M 367 router option. 368 When the global forwarding setting is changed 369 .Po that is, 370 .Fl u 371 is issued to change the value from 372 .Cm enabled 373 to 374 .Cm disabled 375 or vice-versa 376 .Pc , 377 all interface flags in the system are changed simultaneously to reflect the new 378 global policy. 379 Interfaces configured by means of DHCP automatically have their 380 interface-specific 381 .Em IFF_ROUTER 382 flag cleared. 383 .Pp 384 When a new interface is plumbed by means of 385 .Nm ifconfig , 386 the value of the interface-specific forwarding flag is set according to the 387 current global forwarding value. 388 Thus, the forwarding value forms the "default" for all new interfaces. 389 .Sh FILES 390 .Bl -tag -width Pa 391 .It Pa /etc/inet/routing.conf 392 Parameters for IP forwarding and routing. 393 (Not to be edited.) 394 .El 395 .Sh EXIT STATUS 396 .Ex -std 397 .Sh EXAMPLES 398 .Bl -tag -width Ds 399 .It Sy Example 1 No Enabling IPv4 Forwarding 400 IPv4 forwarding is disabled by default. 401 The following command enables IPv4 forwarding: 402 .Bd -literal 403 # routeadm -e ipv4-forwarding 404 .Ed 405 .It Sy Example 2 No Apply Configured Settings to the Running System 406 In the previous example, a system setting was changed, but will not take effect 407 until the next reboot unless a command such as the following is used: 408 .Bd -literal 409 # routeadm -u 410 .Ed 411 .Pp 412 An alternative to the above two steps is to simply enable the equivalent SMF 413 service: 414 .Bd -literal 415 # svcadm enable svc:/network/ipv4-forwarding 416 .Ed 417 .Pp 418 \&...or, using the abbreviated FMRI: 419 .Bd -literal 420 # svcadm enable ipv4-forwarding 421 .Ed 422 .It Sy Example 3 No Making a Setting Revert to its Default 423 To make the setting changed in the first example revert to its default, enter 424 the following: 425 .Bd -literal 426 # routeadm -r ipv4-forwarding 427 # routeadm -u 428 .Ed 429 .It Sy Example 4 No Starting in.routed with the -q Flag 430 Setting the 431 .Fl q 432 flag is represented in the SMF service by setting the 433 .Cm quiet_mode 434 property to true. 435 The following sequence of commands starts 436 .Nm in.routed 437 with the 438 .Fl q 439 flag: 440 .Bd -literal 441 # routeadm -m route:default quiet_mode=true 442 # routeadm -e ipv4-routing -u 443 .Ed 444 .Pp 445 See 446 .Xr in.routed 1M 447 for details of property names and how they relate to daemon behavior. 448 .El 449 .Sh INTERFACE STABILITY 450 .Sy Stable . 451 .Sh SEE ALSO 452 .Xr ifconfig 1M , 453 .Xr in.routed 1M , 454 .Xr svcadm 1M , 455 .Xr gateways 4 , 456 .Xr attributes 5 , 457 .Xr smf 5