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
  14             [-c -comment] [-st] [{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 [-c comment] [-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            If the -c option is specified, the given free-form comment is
 128            recorded in the (temporary) service configuration under the
 129            general/comment property.  This can serve as an administrator
 130            reason for disabling the service, and is reported by svcs(1).
 131 
 132 
 133        restart [-d] {FMRI | pattern}...
 134 
 135            Requests that the service instances specified by the operands be
 136            restarted.  This action requires permission to modify the
 137            "restarter_actions" property group of the service instance (see
 138            smf_security(5)).
 139 
 140            This subcommand can restart only those services that are in the
 141            online or degraded states, as those states are defined in smf(5).
 142 
 143            If the -d option is specified, the restarter sends a SIGABRT to all
 144            members of the contract, which should cause a core dump, before
 145            restarting the service.
 146 
 147 
 148        refresh {FMRI | pattern}...
 149 
 150            For each service instance specified by the operands, requests that
 151            the assigned restarter update the service's running configuration
 152            snapshot with the values from the current configuration. Some of
 153            these values take effect immediately (for example, dependency
 154            changes). Other values do not take effect until the next service
 155            restart. See the restarter and service documentation for more
 156            information.
 157 
 158            If the service is managed by svc.startd(1M), the refresh method
 159            will be invoked if it exists to request the service reread its own
 160            configuration. For other restarters, see the restarter
 161            documentation.
 162 
 163            This action requires permission to modify the "restarter_actions"
 164            property group of the service instance (see smf_security(5)).
 165 
 166 
 167        clear {FMRI | pattern}...
 168 
 169            For each service instance specified by the operands, if the
 170            instance is in the maintenance state, signal to the assigned
 171            restarter that the service has been repaired. If the instance is in
 172            the degraded state, request that the assigned restarter take the
 173            service to the online state. This action requires permission to
 174            modify the "restarter_actions" property group of the service
 175            instance (see smf_security(5)).
 176 
 177 
 178    Exceptional Operations
 179        The following subcommands are used for service development and
 180        temporary administrative manipulation.
 181 
 182        mark [-It] instance_state {FMRI | pattern}...
 183 
 184            If instance_state is "maintenance", then for each service specified
 185            by the operands, svcadm requests that the assigned restarter place
 186            the service in the maintenance state. See svc.startd(1M) and
 187            inetd(1M) for a detailed description of the actions taken for each
 188            restarter.
 189 
 190            If instance_state is "degraded", then for services specified by the
 191            operands in the online state, svcadm requests that the restarters
 192            assigned to the services move them into the degraded state.
 193 
 194            If the -I option is specified, the request is flagged as immediate.
 195 
 196            The -t option is only valid for maintenance requests. When this
 197            option is specified, the request is flagged as temporary, and its
 198            effect will only last until the next reboot.
 199 
 200 
 201        milestone [-d] milestone_FMRI
 202 
 203            If milestone_FMRI is the keyword "none", all services other than
 204            the master restarter, svc:/system/svc/restarter:default, will be
 205            temporarily disabled.
 206 
 207            If milestone_FMRI is the keyword "all", temporary enable and
 208            disable requests for all services will be nullified.
 209 
 210            If milestone_FMRI is one of the following:
 211 
 212              svc:/milestone/single-user:default
 213              svc:/milestone/multi-user:default
 214              svc:/milestone/multi-user-server:default
 215 
 216 
 217            then temporary enable and disable requests for the indicated
 218            service and all services it depends on (directly or indirectly)
 219            will be nullified. All other services will be temporarily disabled.
 220 
 221            Changing the system's current milestone with the "milestone"
 222            subcommand will not change the current run level of the system. To
 223            change the system's run level, invoke /sbin/init directly.
 224 
 225            This action requires permission to modify the "options_ovr"
 226            property group of the svc:/system/svc/restarter:default service
 227            instance (see smf_security(5)).
 228 
 229            The -d option immediately changes the milestone to the requested
 230            milestone, as above. Additionally, it makes the specified milestone
 231            the default boot milestone, which persists across reboot. The
 232            default milestone is defined by the options/milestone property on
 233            the master restarter, svc:/system/svc/restarter:default. If this
 234            property is absent, "all" is the default. This action requires
 235            permission to modify the "options" property group of the
 236            svc:/system/svc/restarter:default service instance (see
 237            smf_security(5)).
 238 
 239 
 240    Operands
 241        The following operands are supported:
 242 
 243        FMRI
 244                   An FMRI that specifies one or more instances. FMRIs can be
 245                   abbreviated by specifying the instance name, or the trailing
 246                   portion of the service name. For example, given the FMRI:
 247 
 248                     svc:/network/smtp:sendmail
 249 
 250 
 251                   All the following are valid abbreviations:
 252 
 253                     sendmail
 254                     :sendmail
 255                     smtp
 256                     smtp:sendmail
 257                     network/smtp
 258 
 259 
 260                   While the following are invalid:
 261 
 262                     mail
 263                     network
 264                     network/smt
 265 
 266 
 267                   If the FMRI specifies a service, then the command applies to
 268                   all instances of that service. Abbreviated forms of FMRIs
 269                   are unstable, and should not be used in scripts or other
 270                   permanent tools.
 271 
 272 
 273        pattern
 274                   A pattern that is matched against the FMRIs of service
 275                   instances according to the "globbing" rules described by
 276                   fnmatch(5). If the pattern does not begin with "svc:", then
 277                   "svc:/" is prepended.
 278 
 279 
 280 
 281        If an abbreviated FMRI matches more than one service, a warning message
 282        is displayed and that operand is ignored.  If a pattern matches more
 283        than one service or instance, the subcommand is applied to all matches.
 284 
 285 EXAMPLES
 286        Example 1 Restarting a Service Instance
 287 
 288 
 289        The following command restarts the NFS server. The full FMRI for the
 290        default service instance is: svc:/network/nfs/server:default
 291 
 292 
 293 
 294        However, you can abbreviate the full FMRI as follows:
 295 
 296 
 297          # svcadm restart nfs/server
 298 
 299 
 300 
 301        Example 2 Disabling a service
 302 
 303 
 304        The following command synchronously disables a service, using an
 305        abbreviated FMRI, and recording a ticket ID as the administrative
 306        reason:
 307 
 308 
 309          $ svcadm disable -c "OPS-1000" -s http
 310 
 311 
 312 
 313        Example 3 Enabling an Instance and Its Dependent Instances
 314 
 315 
 316        The following command enables the foo:bar instance, and all instances
 317        on which it depends:
 318 
 319 
 320          $ svcadm enable -r foo:bar
 321 
 322 
 323 
 324        Example 4 Synchronously enabling an instance
 325 
 326 
 327        The following command enables the foo:bar instance. The command will
 328        not return until the instance comes online or svcadm determines it is
 329        not possible for the service to come online.
 330 
 331 
 332          $ svcadm enable -s foo:bar
 333 
 334 
 335 
 336        Example 5 Restricting and Restoring the Running Services
 337 
 338 
 339        The following command restricts the running services to single user
 340        mode:
 341 
 342 
 343          # svcadm milestone milestone/single-user
 344 
 345 
 346 
 347 
 348        The following command restores the running services:
 349 
 350 
 351          # svcadm milestone all
 352 
 353 
 354 
 355 EXIT STATUS
 356        The following exit values are returned:
 357 
 358        0
 359             Successful completion.
 360 
 361 
 362        1
 363             A fatal error occurred. One or more error messages are displayed
 364             on standard error.
 365 
 366 
 367        2
 368             Invalid command line options were specified.
 369 
 370 
 371        3
 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 instance itself.
 375 
 376 
 377        4
 378             svcadm determined that a service instance that it was waiting for
 379             could not reach the desired state without administrator
 380             intervention due to a problem with the service's dependencies.
 381 
 382 
 383 ATTRIBUTES
 384        See attributes(5) for descriptions of the following attributes:
 385 
 386 
 387 
 388 
 389        +--------------------+-----------------+
 390        |  ATTRIBUTE TYPE    | ATTRIBUTE VALUE |
 391        +--------------------+-----------------+
 392        |Interface Stability | See below.      |
 393        +--------------------+-----------------+
 394 
 395 
 396        The interactive output is Uncommitted. The invocation and non-
 397        interactive output are Committed.
 398 
 399 SEE ALSO
 400        svcprop(1), svcs(1), inetd(1M), init(1M), svccfg(1M), svc.startd(1M),
 401        libscf(3LIB), contract(4), attributes(5), smf(5), smf_security(5),
 402        zones(5)
 403 
 404 NOTES
 405        The amount of time svcadm will spend waiting for services and their
 406        dependencies to change state is implicitly limited by their method
 407        timeouts.  For example, a service using the default restarter whose
 408        start method hangs will be transitioned to the maintenance state when
 409        its timeout expires.  svcadm will then consider it impossible for this
 410        service to come online without administrator intervention.
 411 
 412 
 413        Attempts to synchronously enable a service which depends (directly or
 414        indirectly) on a file may fail with an exit status indicating that
 415        dependencies are unsatisfied if the caller does not have the privileges
 416        necessary to search the directory containing the file. This limitation
 417        may be removed in a future release.
 418 
 419 
 420 
 421                                  May 11, 2020                       SVCADM(1M)