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