| blob | a3496050e6e19869e9fc53b35991326851af5ca2 |
1 '\" te
2 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH ROUTEADM 1M "May 13, 2017"
7 .SH NAME
8 routeadm \- IP forwarding and routing configuration
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBrouteadm\fR [\fB-p\fR [\fIoption\fR]]
13 .fi
15 .LP
16 .nf
17 \fBrouteadm\fR [\fB-R\fR \fIroot-dir\fR] [\fB-e\fR \fIoption\fR ...] [\fB-d\fR \fIoption\fR...]
18 [\fB-r\fR \fIoption\fR...] [\fB-s\fR \fIvar\fR=\fIvalue\fR]
19 .fi
21 .LP
22 .nf
23 \fBrouteadm\fR [\fB-l\fR \fIfmri\fR]
24 .fi
26 .LP
27 .nf
28 \fBrouteadm\fR [\fB-m\fR \fIfmri\fR \fIkey\fR=\fIvalue\fR [\fIkey\fR=\fIvalue\fR]...]
29 .fi
31 .LP
32 .nf
33 \fBrouteadm\fR [\fB-u\fR]
34 .fi
36 .SH DESCRIPTION
37 .LP
38 The \fBrouteadm\fR command is used to administer system-wide configuration for
39 IP forwarding and routing. IP forwarding is the passing of IP packets from one
40 network to another; IP routing is the use of a routing protocol to determine
41 routes.
42 .sp
43 .LP
44 IP forwarding and routing functions are also represented as services within the
45 service management facility (SMF), and can be administered by means of
46 \fBsvcadm\fR(1M) also, using the following fault management resource
47 identifiers (FMRIs):
48 .sp
49 .in +2
50 .nf
51 svc:/network/ipv4-forwarding:default
52 svc:/network/ipv6-forwarding:default
53 svc:/network/routing/route:default
54 svc:/network/routing/ripng:default
55 .fi
56 .in -2
58 .sp
59 .LP
60 See EXAMPLES for relevant examples.
61 .sp
62 .LP
63 In addition to enabling and disabling routing and forwarding, \fBrouteadm\fR is
64 used to interact with SMF-based routing daemon services. Routing daemon
65 services are identified by the presence of a \fBrouteadm\fR application
66 property group, which \fBrouteadm\fR uses in administering the given service.
67 Routing daemon services can also specify properties relating to their operation
68 in the \fBrouting\fR application property group; these can be modified by means
69 of routeadm -m. If an FMRI for a service without such a property group is
70 specified, an error is issued and the operation is not carried out. If a
71 routing daemon has not been converted to SMF, the \fBipv4\fI[or
72 6]\fR-routing-daemon\fR, \fBipv4\fI[or 6]\fR-routing-daemon-args\fR, and
73 \fBipv4\fI[or 6]\fR-routing-stop-cmd\fR variables can be used to specify the
74 appropriate daemon for IPv4 or IPv6 routing. \fBrouteadm\fR will then run that
75 daemon using the \fBsvc:/network/routing/legacy-routing:ipv4\fR\fI[or 6]\fR
76 service as appropriate. This conversion process occurs when you issue an enable
77 (\fB-e\fR), disable (\fB-d\fR) or an update (\fB-u\fR) command.
78 .sp
79 .LP
80 The first usage, in the SYNOPSIS above, reports the current configuration.
81 .SH OPTIONS
82 .LP
83 The following command-line options are supported:
84 .sp
85 .ne 2
86 .na
87 \fB\fB-p\fR [\fIoption\fR]\fR
88 .ad
89 .sp .6
90 .RS 4n
91 Print the configuration in parsable format. If \fIoption\fR is specified, only
92 the configuration for the specified option or variable is displayed.
93 .RE
95 .sp
96 .ne 2
97 .na
98 \fB\fB-R\fR \fIroot-dir\fR\fR
99 .ad
100 .sp .6
101 .RS 4n
102 Specify an alternate root directory where \fBrouteadm\fR applies changes.
103 .LP
104 Note -
105 .sp
106 .RS 2
107 The root file system of any non-global zones must not be referenced with the
108 \fB-R\fR option. Doing so might damage the global zone's file system, might
109 compromise the security of the global zone, and might damage the non-global
110 zone's file system. See \fBzones\fR(5).
111 .RE
112 .RE
114 .sp
115 .ne 2
116 .na
117 \fB\fB-e\fR \fIoption\fR...\fR
118 .ad
119 .sp .6
120 .RS 4n
121 Enable the specified option. The effect is to prepare the associated services
122 (\fBsvc:/network/ipv4-forwarding:default\fR in the case of
123 \fBipv4-forwarding\fR) for enabling. By means of the \fBrouting-svcs\fR
124 variable, the routing daemons are specified to be enabled on subsequent boot or
125 when \fBrouteadm\fR \fB-u\fR is run.
126 .RE
128 .sp
129 .ne 2
130 .na
131 \fB\fB-d\fR \fIoption\fR...\fR
132 .ad
133 .sp .6
134 .RS 4n
135 Disable the specified option. The effect is to prepare the associated services
136 (\fBsvc:/network/ipv4-forwarding:default\fR in the case of
137 \fBipv4-forwarding\fR) for enabling. By means of the \fBrouting-svcs\fR
138 variable, the routing daemons are specified to be disabled on subsequent boot
139 or when \fBrouteadm\fR \fB-u\fR is run.
140 .RE
142 .sp
143 .ne 2
144 .na
145 \fB\fB-l\fR \fIfmri\fR\fR
146 .ad
147 .sp .6
148 .RS 4n
149 List all properties in the routing application property group for the SMF
150 routing daemon service.
151 .RE
153 .sp
154 .ne 2
155 .na
156 \fB\fB-m\fR \fIfmri\fR\ \fIkey\fR=\fIvalue\fR\fR
157 .ad
158 .sp .6
159 .RS 4n
160 Change property value of property \fIkey\fR to \fIvalue\fR in routing
161 application property group for the SMF routing daemon service. For multi-valued
162 properties, the property name can be used multiple times in the modify
163 operation, and each associated value will be added.
164 .RE
166 .sp
167 .ne 2
168 .na
169 \fB\fB-r\fR \fIoption...\fR\fR
170 .ad
171 .sp .6
172 .RS 4n
173 Revert the specified option to the system default. The system defaults are
174 specified in the description of each \fIoption\fR.
175 .RE
177 .sp
178 .ne 2
179 .na
180 \fB\fB-u\fR\fR
181 .ad
182 .sp .6
183 .RS 4n
184 Apply the currently configured options to the running system. These options
185 might include enabling or disabling IP forwarding and launching or killing
186 routing daemons, if any are specified. It does not alter the state of the
187 system for those settings that have been set to default. This option is meant
188 to be used by administrators who do not want to reboot to apply their changes.
189 In addition, this option upgrades non-SMF configurations from the invocations
190 of daemon stop commands, which might include a set of arguments, to a simple
191 enabling of the appropriate service.
192 .RE
194 .sp
195 .ne 2
196 .na
197 \fB\fB-s\fR \fIkey\fR=\fIvalue\fR\fR
198 .ad
199 .sp .6
200 .RS 4n
201 Specify string values for specific variables in a comma-separated list with no
202 intervening spaces. If invalid options are specified, a warning message is
203 displayed and the program exits. The following variables can be specified:
204 .sp
205 .ne 2
206 .na
207 \fB\fBrouting-svcs=\fR\fIfmrilist\fR\fR
208 .ad
209 .sp .6
210 .RS 4n
211 Specifies the routing daemon services to be enabled. Routing daemon services
212 are determined to be IPv4 or IPv6 (and so enabled or disabled when
213 \fBrouteadm\fR \fB-e\fR/\fB-d\fR \fBipv4\fR\fI(6)\fR\fB-routing\fR is run) on
214 the basis of property values in the \fBrouteadm\fR application property group.
215 Default: \fBroute:default ripng:default\fR
216 .RE
218 .sp
219 .ne 2
220 .na
221 \fB\fBipv4-routing-daemon=\fI<full_path_to_routing_daemon>\fR\fR\fR
222 .ad
223 .sp .6
224 .RS 4n
225 Specifies the routing daemon to be started when \fBipv4-routing\fR is enabled.
226 The routing daemon specified must be an executable binary or shell-script. If
227 the specified program maps to an SMF service, the service will be used, and
228 daemon arguments to the program will be transferred to the properties of the
229 service at enable time. Default: \fB""\fR
230 .RE
232 .sp
233 .ne 2
234 .na
235 \fB\fBipv4-routing-daemon-args=\fI<args>\fR\fR\fR
236 .ad
237 .sp .6
238 .RS 4n
239 Specifies the startup arguments to be passed to the \fBipv4-routing-daemon\fR
240 when \fBipv4-routing\fR is enabled. Default: no arguments
241 .RE
243 .sp
244 .ne 2
245 .na
246 \fB\fBipv4-routing-stop-cmd=\fI<command>\fR\fR\fR
247 .ad
248 .sp .6
249 .RS 4n
250 Specifies the command to be executed to stop the routing daemon when
251 \fBipv4-routing\fR is disabled. \fI<command>\fR can be an executable binary or
252 shell-script, or a string that can be parsed by \fBsystem\fR(3C). Default:
253 \fB""\fR
254 .RE
256 .sp
257 .ne 2
258 .na
259 \fB\fBipv6-routing-daemon=\fI<full_path_to_routing_daemon>\fR\fR\fR
260 .ad
261 .sp .6
262 .RS 4n
263 Specifies the routing daemon to be started when \fBipv6-routing\fR is enabled.
264 The routing daemon specified must be an executable binary or shell-script. If
265 the specified program maps to an SMF service, the service will be used, and
266 daemon arguments to the program will be transferred to the properties of the
267 service at enable time. Default: \fB""\fR
268 .RE
270 .sp
271 .ne 2
272 .na
273 \fB\fBipv6-routing-daemon-args=\fI<args>\fR\fR\fR
274 .ad
275 .sp .6
276 .RS 4n
277 Specifies the startup arguments to be passed to the \fBipv6-routing-daemon\fR
278 when \fBipv6-routing\fR is enabled. Default: \fB""\fR
279 .RE
281 .sp
282 .ne 2
283 .na
284 \fB\fBipv6-routing-stop-cmd=\fI<command>\fR\fR\fR
285 .ad
286 .sp .6
287 .RS 4n
288 Specifies the command to be executed to stop the routing daemon when
289 \fBipv6-routing\fR is disabled. \fI<command>\fR can be an executable binary or
290 shell-script, or a string that can be parsed by \fBsystem\fR(3C). Default:
291 \fB""\fR
292 .RE
294 .RE
296 .sp
297 .LP
298 Multiple \fB-e\fR, \fB-d\fR, and \fB-r\fR options can be specified on the
299 command line. Changes made by \fB-e\fR, \fB-d\fR, and \fB-r\fR are persistent,
300 but are not applied to the running system unless \fBrouteadm\fR is called later
301 with the \fB-u\fR option.
302 .sp
303 .LP
304 Use the following options as arguments to the \fB-e\fR, \fB-d\fR, and \fB-r\fR
305 options (shown above as \fIoption...\fR).
306 .sp
307 .ne 2
308 .na
309 \fB\fBipv4-forwarding\fR\fR
310 .ad
311 .sp .6
312 .RS 4n
313 Controls the global forwarding configuration for all IPv4 interfaces. The
314 system default is \fBdisabled\fR. If enabled, IP will forward IPv4 packets to
315 and from interfaces when appropriate. If disabled, IP will not forward IPv4
316 packets to and from interfaces when appropriate. The SMF service associated
317 with this configuration variable is \fBsvc:/network/routing/ipv4-forwarding\fR.
318 This service will be enabled or disabled as appropriate when \fBrouteadm\fR is
319 called with the \fBu\fR option. As an alternative, you can use
320 \fBsvcadm\fR(1M). Services that require \fBipv4-forwarding\fR to be enabled
321 should specify a dependency on this service.
322 .RE
324 .sp
325 .ne 2
326 .na
327 \fB\fBipv4-routing\fR\fR
328 .ad
329 .sp .6
330 .RS 4n
331 Determines whether an IPv4 routing daemon is run. The system default is
332 \fBenabled\fR unless the \fB/etc/defaultrouter\fR file exists (see
333 \fBdefaultrouter\fR(4)), in which case the default is \fBdisabled\fR. The value
334 of this option reflects the state of all IPv4 routing services, such that if
335 any IPv4 routing service is enabled, \fBipv4-routing\fR is enabled. This allows
336 users to interact with routing services using \fBsvcadm\fR(1M), as well as
337 through \fBrouteadm\fR. IPv4 routing services, specified by means of the
338 \fBrouting-svcs\fR variable, will be prepared for enable on next boot when the
339 user explicitly enables \fBipv4-routing\fR. The SMF routing daemon service for
340 \fBin.routed\fR (\fBsvc:/network/routing/route:default\fR) is specified by
341 default.
342 .RE
344 .sp
345 .ne 2
346 .na
347 \fB\fBipv6-forwarding\fR\fR
348 .ad
349 .sp .6
350 .RS 4n
351 Controls the global forwarding configuration for all IPv6 interfaces. The
352 system default is \fBdisabled\fR. If enabled, IP will forward IPv6 packets to
353 and from interfaces when appropriate. If disabled, IP will not forward IPv6
354 packets to and from interfaces when appropriate. The SMF service associated
355 with this configuration variable is \fBsvc:/network/routing/ipv6-forwarding\fR.
356 This service will be enabled or disabled as appropriate when \fBrouteadm\fR is
357 called with the \fB-u\fR option, or \fBsvcadm\fR(1M) is used. Services that
358 require \fBipv6-forwarding\fR to be enabled should specify a dependency on this
359 service.
360 .RE
362 .sp
363 .ne 2
364 .na
365 \fB\fBipv6-routing\fR\fR
366 .ad
367 .sp .6
368 .RS 4n
369 Determines whether an IPv6 routing daemon is run. The system default is
370 \fBdisabled\fR. The value of this option reflects the state of all IPv6 routing
371 services, such that, if any IPv6 routing service is enabled, \fBipv6-routing\fR
372 is enabled. This allows users to interact with routing services via
373 \fBsvcadm\fR(1M) as well as through \fBrouteadm\fR. IPv6 routing services,
374 specified by means of the \fBrouting-svcs\fR variable, will be prepared for
375 enable on next boot when the user explicitly enables \fBipv6-routing\fR. The
376 SMF routing daemon service for \fBin.ripngd\fR
377 (\fBsvc:/network/routing/ripng:default\fR) is specified by default.
378 .RE
380 .sp
381 .LP
382 The forwarding and routing settings are related but not mutually dependent. For
383 example, a router typically forwards IP packets and uses a routing protocol,
384 but nothing would prevent an administrator from configuring a router that
385 forwards packets and does not use a routing protocol. In that case, the
386 administrator would enable forwarding, disable routing, and populate the
387 router's routing table with static routes.
388 .sp
389 .LP
390 The forwarding settings are global settings. Each interface also has an
391 \fBIFF_ROUTER\fR forwarding flag that determines whether packets can be
392 forwarded to or from a particular interface. That flag can be independently
393 controlled by means of \fBifconfig\fR(1M)'s router option. When the global
394 forwarding setting is changed (that is, \fB-u\fR is issued to change the value
395 from \fBenabled\fR to \fBdisabled\fR or vice-versa), all interface flags in the
396 system are changed simultaneously to reflect the new global policy. Interfaces
397 configured by means of DHCP automatically have their interface-specific
398 \fBIFF_ROUTER\fR flag cleared.
399 .sp
400 .LP
401 When a new interface is plumbed by means of \fBifconfig\fR, the value of the
402 interface-specific forwarding flag is set according to the current global
403 forwarding value. Thus, the forwarding value forms the "default" for all new
404 interfaces.
405 .SH EXAMPLES
406 .LP
407 \fBExample 1 \fREnabling IPv4 Forwarding
408 .sp
409 .LP
410 IPv4 forwarding is disabled by default. The following command enables IPv4
411 forwarding:
413 .sp
414 .in +2
415 .nf
416 example# \fBrouteadm -e ipv4-forwarding\fR
417 .fi
418 .in -2
419 .sp
421 .LP
422 \fBExample 2 \fRApply Configured Settings to the Running System
423 .sp
424 .LP
425 In the previous example, a system setting was changed, but will not take effect
426 until the next reboot unless a command such as the following is used:
428 .sp
429 .in +2
430 .nf
431 example# \fBrouteadm -u\fR
432 .fi
433 .in -2
434 .sp
436 .sp
437 .LP
438 An alternative to the above two steps is to simply enable the equivalent SMF
439 service:
441 .sp
442 .in +2
443 .nf
444 example# \fBsvcadm enable svc:/network/ipv4-forwarding\fR
445 .fi
446 .in -2
447 .sp
449 .sp
450 .LP
451 \&...or, using the abbreviated FMRI:
453 .sp
454 .in +2
455 .nf
456 example# \fBsvcadm enable ipv4-forwarding\fR
457 .fi
458 .in -2
459 .sp
461 .LP
462 \fBExample 3 \fRMaking a Setting Revert to its Default
463 .sp
464 .LP
465 To make the setting changed in the first example revert to its default, enter
466 the following:
468 .sp
469 .in +2
470 .nf
471 example# \fBrouteadm -r ipv4-forwarding\fR
472 example# \fBrouteadm -u\fR
473 .fi
474 .in -2
475 .sp
477 .LP
478 \fBExample 4 \fRStarting \fBin.routed\fR with the \fB-q\fR Flag
479 .sp
480 .LP
481 Setting the \fB-q\fR flag is represented in the SMF service by setting the
482 \fBquiet_mode\fR property to true. The following sequence of commands starts
483 \fBin.routed\fR with the \fB-q\fR flag:
485 .sp
486 .in +2
487 .nf
488 example# \fBrouteadm -m route:default quiet_mode=true\fR
489 example# \fBrouteadm -e ipv4-routing -u\fR
490 .fi
491 .in -2
492 .sp
494 .sp
495 .LP
496 See \fBin.routed\fR(1M) for details of property names and how they relate to
497 daemon behavior.
499 .SH EXIT STATUS
500 .LP
501 The following exit values are returned:
502 .sp
503 .ne 2
504 .na
505 \fB\fB0\fR\fR
506 .ad
507 .RS 7n
508 Successful completion.
509 .RE
511 .sp
512 .ne 2
513 .na
514 \fB\fB!=0\fR\fR
515 .ad
516 .RS 7n
517 An error occurred while obtaining or modifying the system configuration.
518 .RE
520 .SH FILES
521 .ne 2
522 .na
523 \fB\fB/etc/inet/routing.conf\fR\fR
524 .ad
525 .RS 26n
526 Parameters for IP forwarding and routing. (Not to be edited.)
527 .RE
529 .SH ATTRIBUTES
530 .LP
531 See \fBattributes\fR(5) for descriptions of the following attributes:
532 .sp
534 .sp
535 .TS
536 box;
537 c | c
538 l | l .
539 ATTRIBUTE TYPE ATTRIBUTE VALUE
540 _
541 Interface Stability Stable
542 .TE
544 .SH SEE ALSO
545 .LP
546 \fBifconfig\fR(1M), \fBin.routed\fR(1M), \fBsvcadm\fR(1M), \fBgateways\fR(4),
547 \fBattributes\fR(5), \fBsmf\fR(5)