7711 SMF: Finish implementing support for degraded state

   1 SVCADM(1M)                   Maintenance Commands                   SVCADM(1M)
   2 
   3 
   4 
   5 NAME
   6        svcadm - manipulate service instances
   7 
   8 SYNOPSIS
   9        /usr/sbin/svcadm [-S state] [-v] [-Z | -z zone] enable [-rst]
  10             [{FMRI | pattern}...]
  11 
  12 
  13        /usr/sbin/svcadm [-S state] [-v] [-Z | -z zone] disable [-s]
  14             [{FMRI | pattern}...]
  15 
  16 
  17        /usr/sbin/svcadm [-S state] [-v] [-Z | -z zone] restart [-d]
  18             [{FMRI | pattern}...]
  19 
  20 
  21        /usr/sbin/svcadm [-S state] [-v] [-Z | -z zone] refresh
  22             [{FMRI | pattern}...]
  23 
  24 
  25        /usr/sbin/svcadm [-S state] [-v] [-Z | -z zone] clear
  26             [{FMRI | pattern}...]
  27 
  28 
  29        /usr/sbin/svcadm [-S state] [-v] [-Z | -z zone] mark [-It] instance_state
  30             [{FMRI | pattern}...]
  31 
  32 
  33        /usr/sbin/svcadm [-v] milestone [-d] milestone_FMRI
  34 
  35 
  36 DESCRIPTION
  37        svcadm issues requests for actions on services executing within the
  38        service management facility (see smf(5)). Actions for a service are
  39        carried out by its assigned service restarter agent. The default
  40        service restarter is svc.startd (see svc.startd(1M)).
  41 
  42 OPTIONS
  43        The following options are supported:
  44 
  45        -S state
  46                            For the subcommands which normally operate on
  47                            explicit FMRIs or an FMRI pattern, the -S option
  48                            can be used to select all FMRIs in the given state.
  49 
  50 
  51        -v
  52                            Print actions verbosely to standard output.
  53 
  54 
  55        -Z
  56                            Administer services in all zones.  This option is
  57                            only applicable from the global zone, see zones(5).
  58 
  59 
  60        -z zone
  61                            Administer services in the specified zone.  This
  62                            option is only applicable from the global zone, see
  63                            zones(5).
  64 
  65 
  66 SUBCOMMANDS
  67    Common Operations
  68        The subcommands listed below are used during the typical administration
  69        of a service instance.
  70 
  71 
  72        For subcommands taking one or more operands, if the operand specifies a
  73        service (instead of a service instance), and that service has only a
  74        single instance, svcadm operates on that instance. If an abbreviated
  75        FMRI (a fault management resource identifier) matches more than one
  76        service or instance, a warning message is displayed and that operand is
  77        ignored.  If a pattern matches more than one service or instance, the
  78        subcommand is applied to all matches. See smf(5).
  79 
  80 
  81        In the case that the service has more than one instance, svcadm return
  82        a non-zero exit status.
  83 
  84        enable [-rst] {FMRI | pattern}...
  85 
  86            Enables the service instances specified by the operands. For each
  87            service instance, the assigned restarter will try to bring it to
  88            the online state. This action requires permission to modify the
  89            "general" property group of the service instance (see
  90            smf_security(5)).
  91 
  92            If the -r option is specified, svcadm enables each service instance
  93            and recursively enables its dependencies.
  94 
  95            If the -s option is specified, svcadm enables each service instance
  96            and then waits for each service instance to enter the online or
  97            degraded state. svcadm will return early if it determines that the
  98            service cannot reach these states without administrator
  99            intervention.
 100 
 101            If the -t option is specified, svcadm temporarily enables each
 102            service instance. Temporary enable only lasts until reboot. This
 103            action requires permission to modify the "restarter_actions"
 104            property group of the service instance (see smf_security(5)). By
 105            default, enable is persistent across reboot.
 106 
 107 
 108        disable [-st] {FMRI | pattern}...
 109 
 110            Disables the service instance specified by the operands. For each
 111            service instance, the assigned restarter will try to bring it to
 112            the disabled state.  This action requires permission to modify the
 113            "general" property group of the service instance (see
 114            smf_security(5)).
 115 
 116            If the -s option is specified, svcadm disables each service
 117            instance and then waits for each service instance to enter the
 118            disabled state.  svcadm will return early if it determines that the
 119            service cannot reach this state without administrator intervention.
 120 
 121            If the -t option is specified, svcadm temporarily disables each
 122            service instance. Temporary disable only lasts until reboot. This
 123            action requires permission to modify the "restarter_actions"
 124            property group of the service instance (see smf_security(5)). By
 125            default, disable is persistent across reboot.
 126 
 127 
 128        restart [-d] {FMRI | pattern}...
 129 
 130            Requests that the service instances specified by the operands be
 131            restarted.  This action requires permission to modify the
 132            "restarter_actions" property group of the service instance (see
 133            smf_security(5)).
 134 
 135            This subcommand can restart only those services that are in the
 136            online or degraded states, as those states are defined in smf(5).
 137 
 138            If the -d option is specified, the restarter sends a SIGABRT to all
 139            members of the contract, which should cause a core dump, before
 140            restarting the service.
 141 
 142 
 143        refresh {FMRI | pattern}...
 144 
 145            For each service instance specified by the operands, requests that
 146            the assigned restarter update the service's running configuration
 147            snapshot with the values from the current configuration. Some of
 148            these values take effect immediately (for example, dependency
 149            changes). Other values do not take effect until the next service
 150            restart. See the restarter and service documentation for more
 151            information.
 152 
 153            If the service is managed by svc.startd(1M), the refresh method
 154            will be invoked if it exists to request the service reread its own
 155            configuration. For other restarters, see the restarter
 156            documentation.
 157 
 158            This action requires permission to modify the "restarter_actions"
 159            property group of the service instance (see smf_security(5)).
 160 
 161 
 162        clear {FMRI | pattern}...
 163 
 164            For each service instance specified by the operands, if the
 165            instance is in the maintenance state, signal to the assigned
 166            restarter that the service has been repaired. If the instance is in
 167            the degraded state, request that the assigned restarter take the
 168            service to the online state. This action requires permission to
 169            modify the "restarter_actions" property group of the service
 170            instance (see smf_security(5)).
 171 
 172 
 173    Exceptional Operations
 174        The following subcommands are used for service development and
 175        temporary administrative manipulation.
 176 
 177        mark [-It] instance_state {FMRI | pattern}...
 178 
 179            If instance_state is "maintenance", then for each service specified
 180            by the operands, svcadm requests that the assigned restarter place
 181            the service in the maintenance state. See svc.startd(1M) and
 182            inetd(1M) for a detailed description of the actions taken for each
 183            restarter.
 184 
 185            If instance_state is "degraded", then for services specified by the
 186            operands in the online state, svcadm requests that the restarters
 187            assigned to the services move them into the degraded state.
 188 
 189            If the -I option is specified, the request is flagged as immediate.
 190 
 191            The -t option is only valid for maintenance requests. When this
 192            option is specified, the request is flagged as temporary, and its
 193            effect will only last until the next reboot.
 194 
 195 
 196        milestone [-d] milestone_FMRI
 197 
 198            If milestone_FMRI is the keyword "none", all services other than
 199            the master restarter, svc:/system/svc/restarter:default, will be
 200            temporarily disabled.
 201 
 202            If milestone_FMRI is the keyword "all", temporary enable and
 203            disable requests for all services will be nullified.
 204 
 205            If milestone_FMRI is one of the following:
 206 
 207              svc:/milestone/single-user:default
 208              svc:/milestone/multi-user:default
 209              svc:/milestone/multi-user-server:default
 210 
 211 
 212            then temporary enable and disable requests for the indicated
 213            service and all services it depends on (directly or indirectly)
 214            will be nullified. All other services will be temporarily disabled.
 215 
 216            Changing the system's current milestone with the "milestone"
 217            subcommand will not change the current run level of the system. To
 218            change the system's run level, invoke /sbin/init directly.
 219 
 220            This action requires permission to modify the "options_ovr"
 221            property group of the svc:/system/svc/restarter:default service
 222            instance (see smf_security(5)).
 223 
 224            The -d option immediately changes the milestone to the requested
 225            milestone, as above. Additionally, it makes the specified milestone
 226            the default boot milestone, which persists across reboot. The
 227            default milestone is defined by the options/milestone property on
 228            the master restarter, svc:/system/svc/restarter:default. If this
 229            property is absent, "all" is the default. This action requires
 230            permission to modify the "options" property group of the
 231            svc:/system/svc/restarter:default service instance (see
 232            smf_security(5)).
 233 
 234 
 235    Operands
 236        The following operands are supported:
 237 
 238        FMRI
 239                   An FMRI that specifies one or more instances. FMRIs can be
 240                   abbreviated by specifying the instance name, or the trailing
 241                   portion of the service name. For example, given the FMRI:
 242 
 243                     svc:/network/smtp:sendmail
 244 
 245 
 246                   All the following are valid abbreviations:
 247 
 248                     sendmail
 249                     :sendmail
 250                     smtp
 251                     smtp:sendmail
 252                     network/smtp
 253 
 254 
 255                   While the following are invalid:
 256 
 257                     mail
 258                     network
 259                     network/smt
 260 
 261 
 262                   If the FMRI specifies a service, then the command applies to
 263                   all instances of that service. Abbreviated forms of FMRIs
 264                   are unstable, and should not be used in scripts or other
 265                   permanent tools.
 266 
 267 
 268        pattern
 269                   A pattern that is matched against the FMRIs of service
 270                   instances according to the "globbing" rules described by
 271                   fnmatch(5). If the pattern does not begin with "svc:", then
 272                   "svc:/" is prepended.
 273 
 274 
 275 
 276        If an abbreviated FMRI matches more than one service, a warning message
 277        is displayed and that operand is ignored.  If a pattern matches more
 278        than one service or instance, the subcommand is applied to all matches.
 279 
 280 EXAMPLES
 281        Example 1 Restarting a Service Instance
 282 
 283 
 284        The following command restarts the NFS server. The full FMRI for the
 285        default service instance is: svc:/network/nfs/server:default
 286 
 287 
 288 
 289        However, you can abbreviate the full FMRI as follows:
 290 
 291 
 292          # svcadm restart nfs/server
 293 
 294 
 295 
 296        Example 2 Disabling the Standard HTTP Server
 297 
 298 
 299        The following command disables the standard HTTP server, using an
 300        abbreviated FMRI:
 301 
 302 
 303          $ svcadm disable http
 304 
 305 
 306 
 307        Example 3 Enabling an Instance and Its Dependent Instances
 308 
 309 
 310        The following command enables the foo:bar instance, and all instances
 311        on which it depends:
 312 
 313 
 314          $ svcadm enable -r foo:bar
 315 
 316 
 317 
 318        Example 4 Synchronously enabling an instance
 319 
 320 
 321        The following command enables the foo:bar instance. The command will
 322        not return until the instance comes online or svcadm determines it is
 323        not possible for the service to come online.
 324 
 325 
 326          $ svcadm enable -s foo:bar
 327 
 328 
 329 
 330        Example 5 Restricting and Restoring the Running Services
 331 
 332 
 333        The following command restricts the running services to single user
 334        mode:
 335 
 336 
 337          # svcadm milestone milestone/single-user
 338 
 339 
 340 
 341 
 342        The following command restores the running services:
 343 
 344 
 345          # svcadm milestone all
 346 
 347 
 348 
 349 EXIT STATUS
 350        The following exit values are returned:
 351 
 352        0
 353             Successful completion.
 354 
 355 
 356        1
 357             A fatal error occurred. One or more error messages are displayed
 358             on standard error.
 359 
 360 
 361        2
 362             Invalid command line options were specified.
 363 
 364 
 365        3
 366             svcadm determined that a service instance that it was waiting for
 367             could not reach the desired state without administrator
 368             intervention due to a problem with the service instance itself.
 369 
 370 
 371        4
 372             svcadm determined that a service instance that it was waiting for
 373             could not reach the desired state without administrator
 374             intervention due to a problem with the service's dependencies.
 375 
 376 
 377 ATTRIBUTES
 378        See attributes(5) for descriptions of the following attributes:
 379 
 380 
 381 
 382 
 383        +--------------------+-----------------+
 384        |  ATTRIBUTE TYPE    | ATTRIBUTE VALUE |
 385        +--------------------+-----------------+
 386        |Interface Stability | See below.      |
 387        +--------------------+-----------------+
 388 
 389 
 390        The interactive output is Uncommitted. The invocation and non-
 391        interactive output are Committed.
 392 
 393 SEE ALSO
 394        svcprop(1), svcs(1), inetd(1M), init(1M), svccfg(1M), svc.startd(1M),
 395        libscf(3LIB), contract(4), attributes(5), smf(5), smf_security(5),
 396        zones(5)
 397 
 398 NOTES
 399        The amount of time svcadm will spend waiting for services and their
 400        dependencies to change state is implicitly limited by their method
 401        timeouts.  For example, a service using the default restarter whose
 402        start method hangs will be transitioned to the maintenance state when
 403        its timeout expires.  svcadm will then consider it impossible for this
 404        service to come online without administrator intervention.
 405 
 406 
 407        Attempts to synchronously enable a service which depends (directly or
 408        indirectly) on a file may fail with an exit status indicating that
 409        dependencies are unsatisfied if the caller does not have the privileges
 410        necessary to search the directory containing the file. This limitation
 411        may be removed in a future release.
 412 
 413 
 414 
 415                                October 17, 2017                     SVCADM(1M)
--- EOF ---