| blob | 1d647304b2349756662fe1ca2e2381551cc0866b |
1 '\" te
2 .\" Copyright (c) 2008, 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 SVCADM 1M "May 9, 2008"
7 .SH NAME
8 svcadm \- manipulate service instances
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB/usr/sbin/svcadm\fR [\fB-S state\fR] [\fB-v\fR] [\fB-Z\fR | \fB-z\fR \fIzone\fR] enable [\fB-rst\fR]
13 [{\fIFMRI\fR | \fIpattern\fR}...]
14 .fi
16 .LP
17 .nf
18 \fB/usr/sbin/svcadm\fR [\fB-S state\fR] [\fB-v\fR] [\fB-Z\fR | \fB-z\fR \fIzone\fR] disable [\fB-s\fR]
19 [{\fIFMRI\fR | \fIpattern\fR}...]
20 .fi
22 .LP
23 .nf
24 \fB/usr/sbin/svcadm\fR [\fB-S state\fR] [\fB-v\fR] [\fB-Z\fR | \fB-z\fR \fIzone\fR] restart [\fB-d\fR]
25 [{\fIFMRI\fR | \fIpattern\fR}...]
26 .fi
28 .LP
29 .nf
30 \fB/usr/sbin/svcadm\fR [\fB-S state\fR] [\fB-v\fR] [\fB-Z\fR | \fB-z\fR \fIzone\fR] refresh
31 [{\fIFMRI\fR | \fIpattern\fR}...]
32 .fi
34 .LP
35 .nf
36 \fB/usr/sbin/svcadm\fR [\fB-S state\fR] [\fB-v\fR] [\fB-Z\fR | \fB-z\fR \fIzone\fR] clear
37 [{\fIFMRI\fR | \fIpattern\fR}...]
38 .fi
40 .LP
41 .nf
42 \fB/usr/sbin/svcadm\fR [\fB-S state\fR] [\fB-v\fR] [\fB-Z\fR | \fB-z\fR \fIzone\fR] mark [\fB-It] \fIinstance_state\fR
43 [{\fIFMRI\fR | \fIpattern\fR}...]
44 .fi
46 .LP
47 .nf
48 \fB/usr/sbin/svcadm\fR [\fB-v\fR] milestone [\fB-d\fR] \fImilestone_FMRI\fR
49 .fi
51 .SH DESCRIPTION
52 .sp
53 .LP
54 \fBsvcadm\fR issues requests for actions on services executing within the
55 service management facility (see \fBsmf\fR(5)). Actions for a service are
56 carried out by its assigned service restarter agent. The default service
57 restarter is \fBsvc.startd\fR (see \fBsvc.startd\fR(1M)).
58 .SH OPTIONS
59 .sp
60 .LP
61 The following options are supported:
62 .sp
63 .ne 2
64 .na
65 \fB-S\fR \fIstate\fR
66 .ad
67 .RS 20n
68 For the subcommands which normally operate on explicit \fIFMRI\fRs or an
69 \fIFMRI\fR pattern, the \fB-S\fR option can be used to select all \fIFMRI\fRs
70 in the given state.
71 .RE
73 .sp
74 .ne 2
75 .na
76 \fB\fB-v\fR\fR
77 .ad
78 .RS 20n
79 Print actions verbosely to standard output.
80 .RE
82 .sp
83 .ne 2
84 .na
85 \fB-Z\fR
86 .ad
87 .RS 20n
88 Administer services in all zones. This option is only applicable
89 from the global zone, see \fBzones\fR(5).
90 .RE
92 .sp
93 .ne 2
94 .na
95 \fB-z\fR \fIzone\fR
96 .ad
97 .RS 20n
98 Administer services in the specified zone. This option is only applicable
99 from the global zone, see \fBzones\fR(5).
100 .RE
102 .SH SUBCOMMANDS
103 .SS "Common Operations"
104 .sp
105 .LP
106 The subcommands listed below are used during the typical administration of a
107 service instance.
108 .sp
109 .LP
110 For subcommands taking one or more operands, if the operand specifies a service
111 (instead of a service instance), and that service has only a single instance,
112 \fBsvcadm\fR operates on that instance. If an abbreviated \fIFMRI\fR (a fault
113 management resource identifier) matches more than one service or instance, a
114 warning message is displayed and that operand is ignored.
115 If a pattern matches more than one service or instance, the subcommand is
116 applied to all matches. See \fBsmf\fR(5).
117 .sp
118 .LP
119 In the case that the service has more than one instance, \fBsvcadm\fR return a
120 non-zero exit status.
121 .sp
122 .ne 2
123 .na
124 \fB\fBenable\fR \fB[\fR\fB-rst\fR\fB]\fR {\fIFMRI\fR | \fIpattern\fR}. . .\fR
125 .ad
126 .sp .6
127 .RS 4n
128 Enables the service instances specified by the operands. For each service
129 instance, the assigned restarter will try to bring it to the online state. This
130 action requires permission to modify the "general" property group of the
131 service instance (see \fBsmf_security\fR(5)).
132 .sp
133 If the \fB-r\fR option is specified, \fBsvcadm\fR enables each service instance
134 and recursively enables its dependencies.
135 .sp
136 If the \fB-s\fR option is specified, \fBsvcadm\fR enables each service instance
137 and then waits for each service instance to enter the \fBonline\fR or
138 \fBdegraded\fR state. \fBsvcadm\fR will return early if it determines that the
139 service cannot reach these states without administrator intervention.
140 .sp
141 If the \fB-t\fR option is specified, \fBsvcadm\fR temporarily enables each
142 service instance. Temporary enable only lasts until reboot. This action
143 requires permission to modify the "restarter_actions" property group of the
144 service instance (see \fBsmf_security\fR(5)). By default, \fBenable\fR is
145 persistent across reboot.
146 .RE
148 .sp
149 .ne 2
150 .na
151 \fB\fBdisable\fR [\fB-st\fR] {\fIFMRI\fR | \fIpattern\fR}. . .\fR
152 .ad
153 .sp .6
154 .RS 4n
155 Disables the service instance specified by the operands. For each service
156 instance, the assigned restarter will try to bring it to the disabled state.
157 This action requires permission to modify the "general" property group of the
158 service instance (see \fBsmf_security\fR(5)).
159 .sp
160 If the \fB-s\fR option is specified, \fBsvcadm\fR disables each service
161 instance and then waits for each service instance to enter the disabled state.
162 \fBsvcadm\fR will return early if it determines that the service cannot reach
163 this state without administrator intervention.
164 .sp
165 If the \fB-t\fR option is specified, \fBsvcadm\fR temporarily disables each
166 service instance. Temporary disable only lasts until reboot. This action
167 requires permission to modify the "restarter_actions" property group of the
168 service instance (see \fBsmf_security\fR(5)). By default, \fBdisable\fR is
169 persistent across reboot.
170 .RE
172 .sp
173 .ne 2
174 .na
175 \fB\fBrestart\fR [\fB-d\fR] {\fIFMRI\fR | \fIpattern\fR}. . .\fR
176 .ad
177 .sp .6
178 .RS 4n
179 Requests that the service instances specified by the operands be restarted.
180 This action requires permission to modify the "restarter_actions" property
181 group of the service instance (see \fBsmf_security\fR(5)).
182 .sp
183 This subcommand can restart only those services that are in the online or
184 degraded states, as those states are defined in \fBsmf\fR(5).
185 .sp
186 If the \fB-d\fR option is specified, the restarter sends a \fBSIGABRT\fR to all
187 members of the contract, which should cause a core dump, before restarting
188 the service.
189 .RE
191 .sp
192 .ne 2
193 .na
194 \fB\fBrefresh\fR {\fIFMRI\fR | \fIpattern\fR}. . .\fR
195 .ad
196 .sp .6
197 .RS 4n
198 For each service instance specified by the operands, requests that the assigned
199 restarter update the service's running configuration snapshot with the values
200 from the current configuration. Some of these values take effect immediately
201 (for example, dependency changes). Other values do not take effect until the
202 next service \fBrestart\fR. See the restarter and service documentation for
203 more information.
204 .sp
205 If the service is managed by \fBsvc.startd\fR(1M), the \fBrefresh\fR method
206 will be invoked if it exists to request the service reread its own
207 configuration. For other restarters, see the restarter documentation.
208 .sp
209 This action requires permission to modify the "restarter_actions" property
210 group of the service instance (see \fBsmf_security\fR(5)).
211 .RE
213 .sp
214 .ne 2
215 .na
216 \fB\fBclear\fR {\fIFMRI\fR | \fIpattern\fR}. . .\fR
217 .ad
218 .sp .6
219 .RS 4n
220 For each service instance specified by the operands, if the instance is in the
221 \fBmaintenance\fR state, signal to the assigned restarter that the service has
222 been repaired. If the instance is in the \fBdegraded\fR state, request that the
223 assigned restarter take the service to the \fBonline\fR state. This action
224 requires permission to modify the "restarter_actions" property group of the
225 service instance (see \fBsmf_security\fR(5)).
226 .RE
228 .SS "Exceptional Operations"
229 .sp
230 .LP
231 The following subcommands are used for service development and temporary
232 administrative manipulation.
233 .sp
234 .ne 2
235 .na
236 \fB\fBmark [\fR\fB-It\fR\fB]\fR \fIinstance_state\fR {\fIFMRI\fR |
237 \fIpattern\fR}. . .\fR
238 .ad
239 .sp .6
240 .RS 4n
241 If \fIinstance_state\fR is "maintenance", then for each service specified by
242 the operands, \fBsvcadm\fR requests that the assigned restarter place the
243 service in the \fBmaintenance\fR state. See \fBsvc.startd\fR(1M) and
244 \fBinetd\fR(1M) for a detailed description of the actions taken for each
245 restarter.
246 .sp
247 If \fIinstance_state\fR is "degraded", then for services specified by the
248 operands in the online state, \fBsvcadm\fR requests that the restarters
249 assigned to the services move them into the \fBdegraded\fR state.
250 .sp
251 If the \fB-I\fR option is specified, the request is flagged as immediate.
252 .sp
253 The \fB-t\fR option is only valid for maintenance requests. When this option is
254 specified, the request is flagged as temporary, and its effect will only last
255 until the next reboot.
256 .RE
258 .sp
259 .ne 2
260 .na
261 \fB\fBmilestone\fR [\fB-d\fR] \fImilestone_FMRI\fR\fR
262 .ad
263 .sp .6
264 .RS 4n
265 If \fImilestone_FMRI\fR is the keyword "none", all services other than the
266 master restarter, \fBsvc:/system/svc/restarter:default\fR, will be temporarily
267 disabled.
268 .sp
269 If \fImilestone_FMRI\fR is the keyword "all", temporary enable and disable
270 requests for all services will be nullified.
271 .sp
272 If \fImilestone_FMRI\fR is one of the following:
273 .sp
274 .in +2
275 .nf
276 svc:/milestone/single-user:default
277 svc:/milestone/multi-user:default
278 svc:/milestone/multi-user-server:default
279 .fi
280 .in -2
281 .sp
283 then temporary enable and disable requests for the indicated service and all
284 services it depends on (directly or indirectly) will be nullified. All other
285 services will be temporarily disabled.
286 .sp
287 Changing the system's current milestone with the "milestone" subcommand will
288 not change the current run level of the system. To change the system's run
289 level, invoke \fB/sbin/init\fR directly.
290 .sp
291 This action requires permission to modify the "options_ovr" property group of
292 the \fBsvc:/system/svc/restarter:default\fR service instance (see
293 \fBsmf_security\fR(5)).
294 .sp
295 The \fB-d\fR option immediately changes the milestone to the requested
296 milestone, as above. Additionally, it makes the specified milestone the default
297 boot milestone, which persists across reboot. The default milestone is defined
298 by the \fBoptions/milestone\fR property on the master restarter,
299 \fBsvc:/system/svc/restarter:default\fR. If this property is absent, "all" is
300 the default. This action requires permission to modify the "options" property
301 group of the \fBsvc:/system/svc/restarter:default\fR service instance (see
302 \fBsmf_security\fR(5)).
303 .RE
305 .SS "Operands"
306 .sp
307 .LP
308 The following operands are supported:
309 .sp
310 .ne 2
311 .na
312 \fB\fIFMRI\fR\fR
313 .ad
314 .RS 11n
315 An \fIFMRI\fR that specifies one or more instances. \fIFMRI\fRs can be
316 abbreviated by specifying the instance name, or the trailing portion of the
317 service name. For example, given the \fIFMRI\fR:
318 .sp
319 .in +2
320 .nf
321 svc:/network/smtp:sendmail
322 .fi
323 .in -2
324 .sp
326 All the following are valid abbreviations:
327 .sp
328 .in +2
329 .nf
330 sendmail
331 :sendmail
332 smtp
333 smtp:sendmail
334 network/smtp
335 .fi
336 .in -2
337 .sp
339 While the following are invalid:
340 .sp
341 .in +2
342 .nf
343 mail
344 network
345 network/smt
346 .fi
347 .in -2
348 .sp
350 If the \fIFMRI\fR specifies a service, then the command applies to all
351 instances of that service. Abbreviated forms of \fIFMRI\fRs are unstable, and
352 should not be used in scripts or other permanent tools.
353 .RE
355 .sp
356 .ne 2
357 .na
358 \fB\fIpattern\fR\fR
359 .ad
360 .RS 11n
361 A pattern that is matched against the \fIFMRIs\fR of service instances
362 according to the "globbing" rules described by \fBfnmatch\fR(5). If the pattern
363 does not begin with "svc:", then "svc:/" is prepended.
364 .RE
366 .sp
367 .LP
368 If an abbreviated \fIFMRI\fR or pattern matches more than one service, a
369 warning message is displayed and that operand is ignored.
370 .SH EXAMPLES
371 .LP
372 \fBExample 1 \fRRestarting a Service Instance
373 .sp
374 .LP
375 The following command restarts the \fBNFS\fR server. The full \fIFMRI\fR for
376 the default service instance is: \fBsvc:/network/nfs/server:default\fR
378 .sp
379 .LP
380 However, you can abbreviate the full \fIFMRI\fR as follows:
382 .sp
383 .in +2
384 .nf
385 # svcadm restart nfs/server
386 .fi
387 .in -2
388 .sp
390 .LP
391 \fBExample 2 \fRDisabling the Standard HTTP Server
392 .sp
393 .LP
394 The following command disables the standard HTTP server, using an abbreviated
395 \fIFMRI\fR:
397 .sp
398 .in +2
399 .nf
400 $ svcadm disable http
401 .fi
402 .in -2
403 .sp
405 .LP
406 \fBExample 3 \fREnabling an Instance and Its Dependent Instances
407 .sp
408 .LP
409 The following command enables the \fBfoo:bar\fR instance, and all instances on
410 which it depends:
412 .sp
413 .in +2
414 .nf
415 $ svcadm enable -r foo:bar
416 .fi
417 .in -2
418 .sp
420 .LP
421 \fBExample 4 \fRSynchronously enabling an instance
422 .sp
423 .LP
424 The following command enables the \fBfoo:bar\fR instance. The command will not
425 return until the instance comes online or \fBsvcadm\fR determines it is not
426 possible for the service to come online.
428 .sp
429 .in +2
430 .nf
431 $ svcadm enable -s foo:bar
432 .fi
433 .in -2
434 .sp
436 .LP
437 \fBExample 5 \fRRestricting and Restoring the Running Services
438 .sp
439 .LP
440 The following command restricts the running services to single user mode:
442 .sp
443 .in +2
444 .nf
445 # svcadm milestone milestone/single-user
446 .fi
447 .in -2
448 .sp
450 .sp
451 .LP
452 The following command restores the running services:
454 .sp
455 .in +2
456 .nf
457 # svcadm milestone all
458 .fi
459 .in -2
460 .sp
462 .SH EXIT STATUS
463 .sp
464 .LP
465 The following exit values are returned:
466 .sp
467 .ne 2
468 .na
469 \fB\fB0\fR\fR
470 .ad
471 .RS 5n
472 Successful completion.
473 .RE
475 .sp
476 .ne 2
477 .na
478 \fB\fB1\fR\fR
479 .ad
480 .RS 5n
481 A fatal error occurred. One or more error messages are displayed on standard
482 error.
483 .RE
485 .sp
486 .ne 2
487 .na
488 \fB\fB2\fR\fR
489 .ad
490 .RS 5n
491 Invalid command line options were specified.
492 .RE
494 .sp
495 .ne 2
496 .na
497 \fB\fB3\fR\fR
498 .ad
499 .RS 5n
500 \fBsvcadm\fR determined that a service instance that it was waiting for could
501 not reach the desired state without administrator intervention due to a problem
502 with the service instance itself.
503 .RE
505 .sp
506 .ne 2
507 .na
508 \fB\fB4\fR\fR
509 .ad
510 .RS 5n
511 \fBsvcadm\fR determined that a service instance that it was waiting for could
512 not reach the desired state without administrator intervention due to a problem
513 with the service's dependencies.
514 .RE
516 .SH ATTRIBUTES
517 .sp
518 .LP
519 See \fBattributes\fR(5) for descriptions of the following attributes:
520 .sp
522 .sp
523 .TS
524 box;
525 c | c
526 l | l .
527 ATTRIBUTE TYPE ATTRIBUTE VALUE
528 _
529 Interface Stability See below.
530 .TE
532 .sp
533 .LP
534 The interactive output is Uncommitted. The invocation and non-interactive
535 output are Committed.
536 .SH SEE ALSO
537 .sp
538 .LP
539 \fBsvcprop\fR(1), \fBsvcs\fR(1), \fBinetd\fR(1M), \fBinit\fR(1M),
540 \fBsvccfg\fR(1M), \fBsvc.startd\fR(1M), \fBlibscf\fR(3LIB), \fBcontract\fR(4),
541 \fBattributes\fR(5), \fBsmf\fR(5), \fBsmf_security\fR(5), \fBzones\fR(5)
542 .SH NOTES
543 .sp
544 .LP
545 The amount of time \fBsvcadm\fR will spend waiting for services and their
546 dependencies to change state is implicitly limited by their method timeouts.
547 For example, a service using the default restarter whose start method hangs
548 will be transitioned to the maintenance state when its timeout expires.
549 \fBsvcadm\fR will then consider it impossible for this service to come online
550 without administrator intervention.
551 .sp
552 .LP
553 Attempts to synchronously enable a service which depends (directly or
554 indirectly) on a file may fail with an exit status indicating that dependencies
555 are unsatisfied if the caller does not have the privileges necessary to search
556 the directory containing the file. This limitation may be removed in a future
557 Solaris release.