1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 2019 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 "Oct 24, 2019"
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 [\fB-st\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 \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-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 .RE
165
166 .sp
167 .ne 2
168 .na
169 \fB\fBrestart\fR [\fB-d\fR] {\fIFMRI\fR | \fIpattern\fR}...\fR
170 .ad
171 .sp .6
172 .RS 4n
173 Requests that the service instances specified by the operands be restarted.
174 This action requires permission to modify the "restarter_actions" property
175 group of the service instance (see \fBsmf_security\fR(5)).
176 .sp
177 This subcommand can restart only those services that are in the online or
178 degraded states, as those states are defined in \fBsmf\fR(5).
179 .sp
180 If the \fB-d\fR option is specified, the restarter sends a \fBSIGABRT\fR to all
181 members of the contract, which should cause a core dump, before restarting
182 the service.
183 .RE
184
185 .sp
186 .ne 2
187 .na
188 \fB\fBrefresh\fR {\fIFMRI\fR | \fIpattern\fR}...\fR
189 .ad
190 .sp .6
191 .RS 4n
192 For each service instance specified by the operands, requests that the assigned
193 restarter update the service's running configuration snapshot with the values
194 from the current configuration. Some of these values take effect immediately
195 (for example, dependency changes). Other values do not take effect until the
196 next service \fBrestart\fR. See the restarter and service documentation for
197 more information.
198 .sp
199 If the service is managed by \fBsvc.startd\fR(1M), the \fBrefresh\fR method
200 will be invoked if it exists to request the service reread its own
201 configuration. For other restarters, see the restarter documentation.
202 .sp
203 This action requires permission to modify the "restarter_actions" property
204 group of the service instance (see \fBsmf_security\fR(5)).
205 .RE
206
207 .sp
208 .ne 2
209 .na
210 \fB\fBclear\fR {\fIFMRI\fR | \fIpattern\fR}...\fR
211 .ad
212 .sp .6
213 .RS 4n
214 For each service instance specified by the operands, if the instance is in the
215 \fBmaintenance\fR state, signal to the assigned restarter that the service has
216 been repaired. If the instance is in the \fBdegraded\fR state, request that the
217 assigned restarter take the service to the \fBonline\fR state. This action
218 requires permission to modify the "restarter_actions" property group of the
219 service instance (see \fBsmf_security\fR(5)).
220 .RE
221
222 .SS "Exceptional Operations"
223 The following subcommands are used for service development and temporary
224 administrative manipulation.
225 .sp
226 .ne 2
227 .na
228 \fB\fBmark [\fR\fB-It\fR\fB]\fR \fIinstance_state\fR {\fIFMRI\fR |
229 \fIpattern\fR}...\fR
230 .ad
231 .sp .6
232 .RS 4n
233 If \fIinstance_state\fR is "maintenance", then for each service specified by
234 the operands, \fBsvcadm\fR requests that the assigned restarter place the
235 service in the \fBmaintenance\fR state. See \fBsvc.startd\fR(1M) and
236 \fBinetd\fR(1M) for a detailed description of the actions taken for each
237 restarter.
238 .sp
239 If \fIinstance_state\fR is "degraded", then for services specified by the
240 operands in the online state, \fBsvcadm\fR requests that the restarters
241 assigned to the services move them into the \fBdegraded\fR state.
242 .sp
243 If the \fB-I\fR option is specified, the request is flagged as immediate.
244 .sp
245 The \fB-t\fR option is only valid for maintenance requests. When this option is
246 specified, the request is flagged as temporary, and its effect will only last
247 until the next reboot.
248 .RE
249
250 .sp
251 .ne 2
252 .na
253 \fB\fBmilestone\fR [\fB-d\fR] \fImilestone_FMRI\fR\fR
254 .ad
255 .sp .6
256 .RS 4n
257 If \fImilestone_FMRI\fR is the keyword "none", all services other than the
258 master restarter, \fBsvc:/system/svc/restarter:default\fR, will be temporarily
259 disabled.
260 .sp
261 If \fImilestone_FMRI\fR is the keyword "all", temporary enable and disable
262 requests for all services will be nullified.
263 .sp
264 If \fImilestone_FMRI\fR is one of the following:
265 .sp
266 .in +2
267 .nf
268 svc:/milestone/single-user:default
269 svc:/milestone/multi-user:default
270 svc:/milestone/multi-user-server:default
271 .fi
272 .in -2
273 .sp
274
275 then temporary enable and disable requests for the indicated service and all
276 services it depends on (directly or indirectly) will be nullified. All other
277 services will be temporarily disabled.
278 .sp
279 Changing the system's current milestone with the "milestone" subcommand will
280 not change the current run level of the system. To change the system's run
281 level, invoke \fB/sbin/init\fR directly.
282 .sp
283 This action requires permission to modify the "options_ovr" property group of
284 the \fBsvc:/system/svc/restarter:default\fR service instance (see
285 \fBsmf_security\fR(5)).
286 .sp
287 The \fB-d\fR option immediately changes the milestone to the requested
288 milestone, as above. Additionally, it makes the specified milestone the default
289 boot milestone, which persists across reboot. The default milestone is defined
290 by the \fBoptions/milestone\fR property on the master restarter,
291 \fBsvc:/system/svc/restarter:default\fR. If this property is absent, "all" is
292 the default. This action requires permission to modify the "options" property
293 group of the \fBsvc:/system/svc/restarter:default\fR service instance (see
294 \fBsmf_security\fR(5)).
295 .RE
296
297 .SS "Operands"
298 The following operands are supported:
299 .sp
300 .ne 2
301 .na
302 \fB\fIFMRI\fR\fR
303 .ad
304 .RS 11n
305 An \fIFMRI\fR that specifies one or more instances. \fIFMRI\fRs can be
306 abbreviated by specifying the instance name, or the trailing portion of the
307 service name. For example, given the \fIFMRI\fR:
308 .sp
309 .in +2
310 .nf
311 svc:/network/smtp:sendmail
312 .fi
313 .in -2
314 .sp
315
316 All the following are valid abbreviations:
317 .sp
318 .in +2
319 .nf
320 sendmail
321 :sendmail
322 smtp
323 smtp:sendmail
324 network/smtp
325 .fi
326 .in -2
327 .sp
328
329 While the following are invalid:
330 .sp
331 .in +2
332 .nf
333 mail
334 network
335 network/smt
336 .fi
337 .in -2
338 .sp
339
340 If the \fIFMRI\fR specifies a service, then the command applies to all
341 instances of that service. Abbreviated forms of \fIFMRI\fRs are unstable, and
342 should not be used in scripts or other permanent tools.
343 .RE
344
345 .sp
346 .ne 2
347 .na
348 \fB\fIpattern\fR\fR
349 .ad
350 .RS 11n
351 A pattern that is matched against the \fIFMRIs\fR of service instances
352 according to the "globbing" rules described by \fBfnmatch\fR(5). If the pattern
353 does not begin with "svc:", then "svc:/" is prepended.
354 .RE
355
356 .sp
357 .LP
358 If an abbreviated \fIFMRI\fR matches more than one service, a warning message
359 is displayed and that operand is ignored.
360 If a pattern matches more than one service or instance, the subcommand is
361 applied to all matches.
362 .SH EXAMPLES
363 \fBExample 1 \fRRestarting a Service Instance
364 .sp
365 .LP
366 The following command restarts the \fBNFS\fR server. The full \fIFMRI\fR for
367 the default service instance is: \fBsvc:/network/nfs/server:default\fR
368
369 .sp
370 .LP
371 However, you can abbreviate the full \fIFMRI\fR as follows:
372
373 .sp
374 .in +2
375 .nf
376 # svcadm restart nfs/server
377 .fi
378 .in -2
379 .sp
380
381 .LP
382 \fBExample 2 \fRDisabling the Standard HTTP Server
383 .sp
384 .LP
385 The following command disables the standard HTTP server, using an abbreviated
386 \fIFMRI\fR:
387
388 .sp
389 .in +2
390 .nf
391 $ svcadm disable http
392 .fi
393 .in -2
394 .sp
395
396 .LP
397 \fBExample 3 \fREnabling an Instance and Its Dependent Instances
398 .sp
399 .LP
400 The following command enables the \fBfoo:bar\fR instance, and all instances on
401 which it depends:
402
403 .sp
404 .in +2
405 .nf
406 $ svcadm enable -r foo:bar
407 .fi
408 .in -2
409 .sp
410
411 .LP
412 \fBExample 4 \fRSynchronously enabling an instance
413 .sp
414 .LP
415 The following command enables the \fBfoo:bar\fR instance. The command will not
416 return until the instance comes online or \fBsvcadm\fR determines it is not
417 possible for the service to come online.
418
419 .sp
420 .in +2
421 .nf
422 $ svcadm enable -s foo:bar
423 .fi
424 .in -2
425 .sp
426
427 .LP
428 \fBExample 5 \fRRestricting and Restoring the Running Services
429 .sp
430 .LP
431 The following command restricts the running services to single user mode:
432
433 .sp
434 .in +2
435 .nf
436 # svcadm milestone milestone/single-user
437 .fi
438 .in -2
439 .sp
440
441 .sp
442 .LP
443 The following command restores the running services:
444
445 .sp
446 .in +2
447 .nf
448 # svcadm milestone all
449 .fi
450 .in -2
451 .sp
452
453 .SH EXIT STATUS
454 The following exit values are returned:
455 .sp
456 .ne 2
457 .na
458 \fB\fB0\fR\fR
459 .ad
460 .RS 5n
461 Successful completion.
462 .RE
463
464 .sp
465 .ne 2
466 .na
467 \fB\fB1\fR\fR
468 .ad
469 .RS 5n
470 A fatal error occurred. One or more error messages are displayed on standard
471 error.
472 .RE
473
474 .sp
475 .ne 2
476 .na
477 \fB\fB2\fR\fR
478 .ad
479 .RS 5n
480 Invalid command line options were specified.
481 .RE
482
483 .sp
484 .ne 2
485 .na
486 \fB\fB3\fR\fR
487 .ad
488 .RS 5n
489 \fBsvcadm\fR determined that a service instance that it was waiting for could
490 not reach the desired state without administrator intervention due to a problem
491 with the service instance itself.
492 .RE
493
494 .sp
495 .ne 2
496 .na
497 \fB\fB4\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's dependencies.
503 .RE
504
505 .SH ATTRIBUTES
506 See \fBattributes\fR(5) for descriptions of the following attributes:
507 .sp
508
509 .sp
510 .TS
511 box;
512 c | c
513 l | l .
514 ATTRIBUTE TYPE ATTRIBUTE VALUE
515 _
516 Interface Stability See below.
517 .TE
518
519 .sp
520 .LP
521 The interactive output is Uncommitted. The invocation and non-interactive
522 output are Committed.
523 .SH SEE ALSO
524 \fBsvcprop\fR(1), \fBsvcs\fR(1), \fBinetd\fR(1M), \fBinit\fR(1M),
525 \fBsvccfg\fR(1M), \fBsvc.startd\fR(1M), \fBlibscf\fR(3LIB), \fBcontract\fR(4),
526 \fBattributes\fR(5), \fBsmf\fR(5), \fBsmf_security\fR(5), \fBzones\fR(5)
527 .SH NOTES
528 The amount of time \fBsvcadm\fR will spend waiting for services and their
529 dependencies to change state is implicitly limited by their method timeouts.
530 For example, a service using the default restarter whose start method hangs
531 will be transitioned to the maintenance state when its timeout expires.
532 \fBsvcadm\fR will then consider it impossible for this service to come online
533 without administrator intervention.
534 .sp
535 .LP
536 Attempts to synchronously enable a service which depends (directly or
537 indirectly) on a file may fail with an exit status indicating that dependencies
538 are unsatisfied if the caller does not have the privileges necessary to search
539 the directory containing the file. This limitation may be removed in a future
540 release.