usr/src/man/man1m/svcadm.1m

   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.