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