1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 2020 Joyent, Inc.
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 "May 11, 2020"
8 .SH NAME
9 svcadm \- manipulate service instances
10 .SH SYNOPSIS
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
19 [\fB-c\fR -\fIcomment\fR] [\fB-st\fR] [{\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 \fBsvcadm\fR issues requests for actions on services executing within the
53 service management facility (see \fBsmf\fR(5)). Actions for a service are
54 carried out by its assigned service restarter agent. The default service
55 restarter is \fBsvc.startd\fR (see \fBsvc.startd\fR(1M)).
56 .SH OPTIONS
57 The following options are supported:
58 .sp
59 .ne 2
60 .na
61 \fB-S\fR \fIstate\fR
62 .ad
63 .RS 20n
64 For the subcommands which normally operate on explicit \fIFMRI\fRs or an
65 \fIFMRI\fR pattern, the \fB-S\fR option can be used to select all \fIFMRI\fRs
66 in the given state.
67 .RE
68
69 .sp
70 .ne 2
71 .na
72 \fB\fB-v\fR\fR
73 .ad
74 .RS 20n
75 Print actions verbosely to standard output.
76 .RE
77
78 .sp
79 .ne 2
80 .na
81 \fB-Z\fR
82 .ad
83 .RS 20n
84 Administer services in all zones. This option is only applicable
85 from the global zone, see \fBzones\fR(5).
86 .RE
87
88 .sp
89 .ne 2
90 .na
91 \fB-z\fR \fIzone\fR
92 .ad
93 .RS 20n
94 Administer services in the specified zone. This option is only applicable
95 from the global zone, see \fBzones\fR(5).
96 .RE
97
98 .SH SUBCOMMANDS
99 .SS "Common Operations"
100 The subcommands listed below are used during the typical administration of a
101 service instance.
102 .sp
103 .LP
104 For subcommands taking one or more operands, if the operand specifies a service
105 (instead of a service instance), and that service has only a single instance,
106 \fBsvcadm\fR operates on that instance. If an abbreviated \fIFMRI\fR (a fault
107 management resource identifier) matches more than one service or instance, a
108 warning message is displayed and that operand is ignored.
109 If a pattern matches more than one service or instance, the subcommand is
110 applied to all matches. See \fBsmf\fR(5).
111 .sp
112 .LP
113 In the case that the service has more than one instance, \fBsvcadm\fR return a
114 non-zero exit status.
115 .sp
116 .ne 2
117 .na
118 \fB\fBenable\fR \fB[\fR\fB-rst\fR\fB]\fR {\fIFMRI\fR | \fIpattern\fR}...\fR
119 .ad
120 .sp .6
121 .RS 4n
122 Enables the service instances specified by the operands. For each service
123 instance, the assigned restarter will try to bring it to the online state. This
124 action requires permission to modify the "general" property group of the
125 service instance (see \fBsmf_security\fR(5)).
126 .sp
127 If the \fB-r\fR option is specified, \fBsvcadm\fR enables each service instance
128 and recursively enables its dependencies.
129 .sp
130 If the \fB-s\fR option is specified, \fBsvcadm\fR enables each service instance
131 and then waits for each service instance to enter the \fBonline\fR or
132 \fBdegraded\fR state. \fBsvcadm\fR will return early if it determines that the
133 service cannot reach these states without administrator intervention.
134 .sp
135 If the \fB-t\fR option is specified, \fBsvcadm\fR temporarily enables each
136 service instance. Temporary enable only lasts until reboot. This action
137 requires permission to modify the "restarter_actions" property group of the
138 service instance (see \fBsmf_security\fR(5)). By default, \fBenable\fR is
139 persistent across reboot.
140 .RE
141
142 .sp
143 .ne 2
144 .na
145 \fB\fBdisable\fR [\fB-c\fR \fIcomment\fR] [\fB-st\fR] {\fIFMRI\fR | \fIpattern\fR}...\fR
146 .ad
147 .sp .6
148 .RS 4n
149 Disables the service instance specified by the operands. For each service
150 instance, the assigned restarter will try to bring it to the disabled state.
151 This action requires permission to modify the "general" property group of the
152 service instance (see \fBsmf_security\fR(5)).
153 .sp
154 If the \fB-s\fR option is specified, \fBsvcadm\fR disables each service
155 instance and then waits for each service instance to enter the disabled state.
156 \fBsvcadm\fR will return early if it determines that the service cannot reach
157 this state without administrator intervention.
158 .sp
159 If the \fB-t\fR option is specified, \fBsvcadm\fR temporarily disables each
160 service instance. Temporary disable only lasts until reboot. This action
161 requires permission to modify the "restarter_actions" property group of the
162 service instance (see \fBsmf_security\fR(5)). By default, \fBdisable\fR is
163 persistent across reboot.
164 .sp
165 If the \fB-c\fR option is specified, the given free-form comment is recorded
166 in the (temporary) service configuration under the \fBgeneral/comment\fR
167 property. This can serve as an administrator reason for disabling the service,
168 and is reported by \fBsvcs\fR(1).
169 .RE
170
171 .sp
172 .ne 2
173 .na
174 \fB\fBrestart\fR [\fB-d\fR] {\fIFMRI\fR | \fIpattern\fR}...\fR
175 .ad
176 .sp .6
177 .RS 4n
178 Requests that the service instances specified by the operands be restarted.
179 This action requires permission to modify the "restarter_actions" property
180 group of the service instance (see \fBsmf_security\fR(5)).
181 .sp
182 This subcommand can restart only those services that are in the online or
183 degraded states, as those states are defined in \fBsmf\fR(5).
184 .sp
185 If the \fB-d\fR option is specified, the restarter sends a \fBSIGABRT\fR to all
186 members of the contract, which should cause a core dump, before restarting
187 the service.
188 .RE
189
190 .sp
191 .ne 2
192 .na
193 \fB\fBrefresh\fR {\fIFMRI\fR | \fIpattern\fR}...\fR
194 .ad
195 .sp .6
196 .RS 4n
197 For each service instance specified by the operands, requests that the assigned
198 restarter update the service's running configuration snapshot with the values
199 from the current configuration. Some of these values take effect immediately
200 (for example, dependency changes). Other values do not take effect until the
201 next service \fBrestart\fR. See the restarter and service documentation for
202 more information.
203 .sp
204 If the service is managed by \fBsvc.startd\fR(1M), the \fBrefresh\fR method
205 will be invoked if it exists to request the service reread its own
206 configuration. For other restarters, see the restarter documentation.
207 .sp
208 This action requires permission to modify the "restarter_actions" property
209 group of the service instance (see \fBsmf_security\fR(5)).
210 .RE
211
212 .sp
213 .ne 2
214 .na
215 \fB\fBclear\fR {\fIFMRI\fR | \fIpattern\fR}...\fR
216 .ad
217 .sp .6
218 .RS 4n
219 For each service instance specified by the operands, if the instance is in the
220 \fBmaintenance\fR state, signal to the assigned restarter that the service has
221 been repaired. If the instance is in the \fBdegraded\fR state, request that the
222 assigned restarter take the service to the \fBonline\fR state. This action
223 requires permission to modify the "restarter_actions" property group of the
224 service instance (see \fBsmf_security\fR(5)).
225 .RE
226
227 .SS "Exceptional Operations"
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 only valid for maintenance 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 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 \fBExample 1 \fRRestarting a Service Instance
369 .sp
370 .LP
371 The following command restarts the \fBNFS\fR server. The full \fIFMRI\fR for
372 the default service instance is: \fBsvc:/network/nfs/server:default\fR
373
374 .sp
375 .LP
376 However, you can abbreviate the full \fIFMRI\fR as follows:
377
378 .sp
379 .in +2
380 .nf
381 # svcadm restart nfs/server
382 .fi
383 .in -2
384 .sp
385
386 .LP
387 \fBExample 2 \fRDisabling a service
388 .sp
389 .LP
390 The following command synchronously disables a service, using an abbreviated
391 \fIFMRI\fR, and recording a ticket ID as the administrative reason:
392
393 .sp
394 .in +2
395 .nf
396 $ svcadm disable -c "OPS-1000" -s http
397 .fi
398 .in -2
399 .sp
400
401 .LP
402 \fBExample 3 \fREnabling an Instance and Its Dependent Instances
403 .sp
404 .LP
405 The following command enables the \fBfoo:bar\fR instance, and all instances on
406 which it depends:
407
408 .sp
409 .in +2
410 .nf
411 $ svcadm enable -r foo:bar
412 .fi
413 .in -2
414 .sp
415
416 .LP
417 \fBExample 4 \fRSynchronously enabling an instance
418 .sp
419 .LP
420 The following command enables the \fBfoo:bar\fR instance. The command will not
421 return until the instance comes online or \fBsvcadm\fR determines it is not
422 possible for the service to come online.
423
424 .sp
425 .in +2
426 .nf
427 $ svcadm enable -s foo:bar
428 .fi
429 .in -2
430 .sp
431
432 .LP
433 \fBExample 5 \fRRestricting and Restoring the Running Services
434 .sp
435 .LP
436 The following command restricts the running services to single user mode:
437
438 .sp
439 .in +2
440 .nf
441 # svcadm milestone milestone/single-user
442 .fi
443 .in -2
444 .sp
445
446 .sp
447 .LP
448 The following command restores the running services:
449
450 .sp
451 .in +2
452 .nf
453 # svcadm milestone all
454 .fi
455 .in -2
456 .sp
457
458 .SH EXIT STATUS
459 The following exit values are returned:
460 .sp
461 .ne 2
462 .na
463 \fB\fB0\fR\fR
464 .ad
465 .RS 5n
466 Successful completion.
467 .RE
468
469 .sp
470 .ne 2
471 .na
472 \fB\fB1\fR\fR
473 .ad
474 .RS 5n
475 A fatal error occurred. One or more error messages are displayed on standard
476 error.
477 .RE
478
479 .sp
480 .ne 2
481 .na
482 \fB\fB2\fR\fR
483 .ad
484 .RS 5n
485 Invalid command line options were specified.
486 .RE
487
488 .sp
489 .ne 2
490 .na
491 \fB\fB3\fR\fR
492 .ad
493 .RS 5n
494 \fBsvcadm\fR determined that a service instance that it was waiting for could
495 not reach the desired state without administrator intervention due to a problem
496 with the service instance itself.
497 .RE
498
499 .sp
500 .ne 2
501 .na
502 \fB\fB4\fR\fR
503 .ad
504 .RS 5n
505 \fBsvcadm\fR determined that a service instance that it was waiting for could
506 not reach the desired state without administrator intervention due to a problem
507 with the service's dependencies.
508 .RE
509
510 .SH ATTRIBUTES
511 See \fBattributes\fR(5) for descriptions of the following attributes:
512 .sp
513
514 .sp
515 .TS
516 box;
517 c | c
518 l | l .
519 ATTRIBUTE TYPE ATTRIBUTE VALUE
520 _
521 Interface Stability See below.
522 .TE
523
524 .sp
525 .LP
526 The interactive output is Uncommitted. The invocation and non-interactive
527 output are Committed.
528 .SH SEE ALSO
529 \fBsvcprop\fR(1), \fBsvcs\fR(1), \fBinetd\fR(1M), \fBinit\fR(1M),
530 \fBsvccfg\fR(1M), \fBsvc.startd\fR(1M), \fBlibscf\fR(3LIB), \fBcontract\fR(4),
531 \fBattributes\fR(5), \fBsmf\fR(5), \fBsmf_security\fR(5), \fBzones\fR(5)
532 .SH NOTES
533 The amount of time \fBsvcadm\fR will spend waiting for services and their
534 dependencies to change state is implicitly limited by their method timeouts.
535 For example, a service using the default restarter whose start method hangs
536 will be transitioned to the maintenance state when its timeout expires.
537 \fBsvcadm\fR will then consider it impossible for this service to come online
538 without administrator intervention.
539 .sp
540 .LP
541 Attempts to synchronously enable a service which depends (directly or
542 indirectly) on a file may fail with an exit status indicating that dependencies
543 are unsatisfied if the caller does not have the privileges necessary to search
544 the directory containing the file. This limitation may be removed in a future
545 release.