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