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