1 .\"
   2 .\" The contents of this file are subject to the terms of the
   3 .\" Common Development and Distribution License (the "License").
   4 .\" You may not use this file except in compliance with the License.
   5 .\"
   6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   7 .\" or http://www.opensolaris.org/os/licensing.
   8 .\" See the License for the specific language governing permissions
   9 .\" and limitations under the License.
  10 .\"
  11 .\" When distributing Covered Code, include this CDDL HEADER in each
  12 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  13 .\" If applicable, add the following below this CDDL HEADER, with the
  14 .\" fields enclosed by brackets "[]" replaced with your own identifying
  15 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  16 .\"
  17 .\"
  18 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
  19 .\" Copyright 2015 Nexenta Systems, Inc.  All rights reserved.
  20 .\"
  21 .Dd April 23, 2015
  22 .Dt SVCS 1
  23 .Os
  24 .Sh NAME
  25 .Nm svcs
  26 .Nd report service status
  27 .Sh SYNOPSIS
  28 .Nm
  29 .Op Fl aHpv\?
  30 .Op Fl o Ar col Ns Oo , Ns Ar col Oc Ns ...
  31 .Oo Fl R Ar FMRI-instance Oc Ns ...
  32 .Oo Fl sS Ar col Oc Ns ...
  33 .Op Fl z Ar zone Ns | Ns Fl Z
  34 .Oo Ar FMRI Ns | Ns Ar pattern Oc Ns ...
  35 .Nm
  36 .Brq Fl d Ns | Ns Fl D
  37 .Fl Hpv\?
  38 .Op Fl o Ar col Ns Oo , Ns Ar col Oc Ns ...
  39 .Oo Fl sS Ar col Oc Ns ...
  40 .Op Fl z Ar zone Ns | Ns Fl Z
  41 .Oo Ar FMRI Ns | Ns Ar pattern Oc Ns ...
  42 .Nm
  43 .Brq Fl l Ns | Ns Fl L
  44 .Op Fl v
  45 .Op Fl z Ar zone Ns | Ns Fl Z
  46 .Bro Ar FMRI Ns |  Ns Ar pattern Brc Ns ...
  47 .Nm
  48 .Fl x
  49 .Op Fl v
  50 .Op Fl z Ar zone Ns | Ns Fl Z
  51 .Oo Ar FMRI Oc Ns ...
  52 .Sh DESCRIPTION
  53 The
  54 .Nm
  55 command displays information about service instances as recorded in the service
  56 configuration repository.
  57 .Pp
  58 The first form of this command prints one-line status listings for service
  59 instances specified by the arguments.
  60 Each instance is listed only once.
  61 With no arguments, all enabled service instances, even if temporarily disabled,
  62 are listed with the columns indicated below.
  63 .Pp
  64 The second form prints one-line status listings for the dependencies or
  65 dependents of the service instances specified by the arguments.
  66 .Pp
  67 The third form prints detailed information about specific services and
  68 instances.
  69 .Pp
  70 The fourth form explains the states of service instances.
  71 For each argument, a block of human-readable text is displayed which explains
  72 what state the service is in, and why it is in that state.
  73 With no arguments, problematic services are described.
  74 .Pp
  75 The output of this command can be used appropriately as input to the
  76 .Xr svcadm 1M
  77 command.
  78 .Sh OPTIONS
  79 The following options are supported:
  80 .Bl -tag -width "-R FMRI-instance"
  81 .It Fl \?
  82 Displays an extended usage message, including column specifiers.
  83 .It Fl a
  84 Show all services, even disabled ones.
  85 This option has no effect if services are selected.
  86 .It Fl d
  87 Lists the services or service instances upon which the given service instances
  88 depend.
  89 .It Fl D
  90 Lists the service instances that depend on the given services or service
  91 instances.
  92 .It Fl H
  93 Used for scripting mode.
  94 Do not print headers and separate fields by a single tab instead of arbitrary
  95 white space.
  96 .It Fl l
  97 Displays all available information about the selected services and service
  98 instances, with one service attribute displayed for each line.
  99 Information for different instances are separated by blank lines.
 100 .Pp
 101 The following specific attributes require further explanation:
 102 .Bl -tag -width "dependency"
 103 .It Sy dependency
 104 Information about a dependency.
 105 The grouping and
 106 .Ar restart_on
 107 properties are displayed first and are separated by a forward slash
 108 .Pq Sy / .
 109 Next, each entity and its state is listed.
 110 See
 111 .Xr smf 5
 112 for information about states.
 113 In addition to the standard states, each service dependency can have the
 114 following state descriptions:
 115 .Bl -tag -width "multiple"
 116 .It Sy absent
 117 No such service is defined on the system.
 118 .It Sy invalid
 119 The fault management resource identifier
 120 .Pq FMRI
 121 is invalid
 122 .Pq see Xr smf 5 .
 123 .It Sy multiple
 124 The entity is a service with multiple instances.
 125 .El
 126 .Pp
 127 File dependencies can only have one of the following state descriptions:
 128 .Bl -tag -width "unknown"
 129 .It Sy absent
 130 No such file on the system.
 131 .It Sy online
 132 The file exists.
 133 .Pp
 134 If the file did not exist the last time that
 135 .Nm svc.startd
 136 evaluated the service's dependencies, it can consider the dependency to be
 137 unsatisfied.
 138 .Nm svcadm Cm refresh
 139 forces dependency re-evaluation.
 140 .It Sy unknown
 141 .Xr stat 2
 142 failed for a reason other than
 143 .Dv ENOENT .
 144 .El
 145 .Pp
 146 See
 147 .Xr smf 5
 148 for additional details about dependencies, grouping, and
 149 .Ar restart_on
 150 values.
 151 .It Sy enabled
 152 Whether the service is enabled or not, and whether it is enabled or disabled
 153 temporarily
 154 .Pq until the next system reboot .
 155 The former is specified as either
 156 .Sy true
 157 or
 158 .Sy false ,
 159 and the latter is designated by the presence of
 160 .Pq Sy temporary .
 161 .Pp
 162 A service might be temporarily disabled because an administrator has run
 163 .Nm svcadm Cm disable Fl t ,
 164 used
 165 .Nm svcadm Cm milestone ,
 166 or booted the system to a specific milestone.
 167 See
 168 .Xr svcadm 1M
 169 for details.
 170 .El
 171 .It Fl L
 172 Display the log file of the selected services and service instances, one
 173 per-line.
 174 .It Fl o Ar col Ns Oo , Ns Ar col Oc Ns ...
 175 Prints the specified columns.
 176 Each
 177 .Ar col
 178 should be a column name.
 179 See
 180 .Sx COLUMNS
 181 below for available columns.
 182 .It Fl p
 183 Lists processes associated with each service instance.
 184 A service instance can have no associated processes.
 185 The process ID, start time, and command name
 186 .Po
 187 .Sy PID , STIME ,
 188 and
 189 .Sy CMD
 190 fields from
 191 .Xr ps 1
 192 .Pc
 193 are displayed for each process.
 194 .It Fl R Ar FMRI-instance
 195 Selects service instances that have the given service instance as their
 196 restarter.
 197 .It Fl s Ar col
 198 Sorts output by column.
 199 .Ar col
 200 should be a column name.
 201 See
 202 .Sx COLUMNS
 203 below for available columns.
 204 Multiple
 205 .Fl s
 206 options behave additively.
 207 .It Fl S Ar col
 208 Sorts by
 209 .Ar col
 210 in the opposite order as option
 211 .Fl s .
 212 .It Fl v
 213 Without
 214 .Fl x
 215 or
 216 .Fl l ,
 217 displays verbose columns:
 218 .Sy STATE , NSTATE , STIME , CTID ,
 219 and
 220 .Sy FMRI .
 221 .Pp
 222 With
 223 .Fl x ,
 224 displays extra information for each explanation.
 225 .Pp
 226 With
 227 .Fl l ,
 228 displays user-visible properties in property groups of type
 229 .Sy application
 230 and their description.
 231 .It Fl x
 232 Displays explanations for service states.
 233 .Pp
 234 Without arguments, the
 235 .Fl x
 236 option explains the states of services which:
 237 .Bl -bullet
 238 .It
 239 are enabled, but are not running.
 240 .It
 241 are preventing another enabled service from running.
 242 .El
 243 .It Fl z Ar zone
 244 Display only the services in the
 245 .Ar zone .
 246 This option is only applicable in the global zone, see
 247 .Xr zones 5 .
 248 .It Fl Z
 249 Display services from all zones, with an additional column indicating in which
 250 zone the service is running.
 251 This option is only applicable in the global zone, see
 252 .Xr zones 5 .
 253 .El
 254 .Sh OPERANDS
 255 The following operands are supported:
 256 .Bl -tag -width "FMRI-instance"
 257 .It Ar FMRI
 258 A fault management resource identifier
 259 .Pq FMRI
 260 that specifies one or more instances
 261 .Pq see Xr smf 5 .
 262 FMRIs can be abbreviated by specifying the instance name, or the trailing
 263 portion of the service name.
 264 For example, given the FMRI
 265 .Sy svc:/network/smtp:sendmail ,
 266 the following are valid abbreviations:
 267 .Sy sendmail :sendmail smtp smtp:sendmail network/smtp ,
 268 and the following are invalid abbreviations:
 269 .Sy mail network network/smt .
 270 .Pp
 271 If the FMRI specifies a service, then the command applies to all instances of
 272 that service, except when used with the
 273 .Fl D
 274 option.
 275 .Pp
 276 Abbreviated forms of FMRIs are unstable, and should not be used in scripts or
 277 other permanent tools.
 278 .It Ar pattern
 279 A pattern that is matched against the FMRI of service instances according to the
 280 "globbing" rules described by
 281 .Xr fnmatch 5 .
 282 If the pattern does not begin with
 283 .Sy svc: ,
 284 then
 285 .Sy svc:/
 286 is prepended.
 287 The following is a typical example of a glob pattern:
 288 .Bd -literal
 289 qexample% svcs \e*keyserv\e*
 290 STATE          STIME     FMRI
 291 disabled       Aug_02    svc:/network/rpc/keyserv:default
 292 .Ed
 293 .It Ar FMRI-instance
 294 An FMRI that specifies an instance.
 295 .El
 296 .Sh COLUMNS
 297 Column names are case insensitive.
 298 The default output format is equivalent to
 299 .Fl o Sy state,stime,fmri .
 300 The default sorting columns are
 301 .Sy STATE , STIME , FMRI .
 302 .Bl -tag -width "NSTATE"
 303 .It Sy CTID
 304 The primary contract ID for the service instance.
 305 Not all instances have valid primary contract IDs.
 306 .It Sy DESC
 307 A brief description of the service, from its template element.
 308 A service might not have a description available, in which case a hyphen
 309 .Pq Sy \(hy
 310 is used to denote an empty value.
 311 .It Sy FMRI
 312 The FMRI of the service instance.
 313 .It Sy INST
 314 The instance name of the service instance.
 315 .It Sy NSTA
 316 The abbreviated next state of the service instance, as given in the
 317 .Sy STA
 318 column description.
 319 A hyphen denotes that the instance is not transitioning.
 320 Same as
 321 .Sy STA
 322 otherwise.
 323 .It Sy NSTATE
 324 The next state of the service.
 325 A hyphen is used to denote that the instance is not transitioning.
 326 Same as
 327 .Sy STATE
 328 otherwise.
 329 .It Sy SCOPE
 330 The scope name of the service instance.
 331 .It Sy SVC
 332 The service name of the service instance.
 333 .It Sy STA
 334 The abbreviated state of the service instance:
 335 .Bl -tag -width "DGD"
 336 .It Sy DGD
 337 degraded
 338 .It Sy DIS
 339 disabled
 340 .It Sy LRC
 341 legacy rc*.d script-initiated instance
 342 .It Sy MNT
 343 maintenance
 344 .It Sy OFF
 345 offline
 346 .It Sy ON
 347 online
 348 .It Sy UN
 349 uninitialized
 350 .El
 351 .Pp
 352 Absent or unrecognized states are denoted by a question mark
 353 .Pq Sy \?
 354 character.
 355 An asterisk
 356 .Pq Sy *
 357 is appended for instances in transition, unless the
 358 .Sy NSTA
 359 or
 360 .Sy NSTATE
 361 column is also being displayed.
 362 .It Sy STATE
 363 The state of the service instance.
 364 An asterisk is appended for instances in transition, unless the
 365 .Sy NSTA
 366 or
 367 .Sy NSTATE
 368 column is also being displayed.
 369 .It Sy STIME
 370 If the service instance entered the current state within the last 24 hours,
 371 this column indicates the time that it did so.
 372 Otherwise, this column indicates the date on which it did so, printed with
 373 underscores
 374 .Pq Sy _
 375 in place of blanks.
 376 .El
 377 .Sh EXIT STATUS
 378 The following exit values are returned:
 379 .Bl -tag -width "0"
 380 .It Sy 0
 381 Successful command invocation.
 382 .It Sy 1
 383 Fatal error.
 384 .It Sy 2
 385 Invalid command line options were specified.
 386 .El
 387 .Sh EXAMPLES
 388 .Bl -tag -width ""
 389 .It Sy Example 1 No Displaying the Default Output
 390 This example displays default output:
 391 .Bd -literal
 392 example% svcs
 393 STATE          STIME    FMRI
 394 \&...
 395 legacy_run     13:25:04 lrc:/etc/rc3_d/S42myscript
 396 \&...
 397 online         13:21:50 svc:/system/svc/restarter:default
 398 \&...
 399 online         13:25:03 svc:/milestone/multi-user:default
 400 \&...
 401 online         13:25:07 svc:/milestone/multi-user-server:default
 402 \&...
 403 .Ed
 404 .It Sy Example 2 No Listing All Local Instances
 405 This example lists all local instances of the
 406 .Sy service1
 407 service:
 408 .Bd -literal
 409 example% svcs -o state,nstate,fmri service1
 410 STATE        NSTATE        FMRI
 411 online       -             svc:/service1:instance1
 412 disabled     -             svc:/service1:instance2
 413 .Ed
 414 .It Sy Example 3 No Listing Verbose Information
 415 This example lists verbose information:
 416 .Bd -literal
 417 example% svcs -v network/rpc/rstat:udp
 418 STATE          NSTATE        STIME    CTID   FMRI
 419 online         -             Aug_09        - svc:/network/rpc/rstat:udp
 420 .Ed
 421 .It Sy Example 4 No Listing Detailed Information
 422 This example lists detailed information about all instances of
 423 .Sy system/service3 .
 424 Additional fields can be displayed, as appropriate to the managing restarter.
 425 .Bd -literal
 426 example% svcs -l network/rpc/rstat:udp
 427 
 428 fmri         svc:/network/rpc/rstat:udp
 429 enabled      true
 430 state        online
 431 next_state   none
 432 restarter    svc:/network/inetd:default
 433 contract_id
 434 dependency   require_all/error svc:/network/rpc/bind (online)
 435 .Ed
 436 .It Sy Example 5 No Listing Processes
 437 .Bd -literal
 438 example% svcs -p sendmail
 439 STATE          STIME    FMRI
 440 online         13:25:13 svc:/network/smtp:sendmail
 441                13:25:15   100939 sendmail
 442                13:25:15   100940 sendmail
 443 .Ed
 444 .It Sy Example 6 No Explaining Service States Using Nm Fl x
 445 .Bl -enum
 446 .It
 447 In this example,
 448 .Nm
 449 .Fl x
 450 has identified that the
 451 .Sy print/server
 452 service being disabled is the root cause of two services which are enabled but
 453 not online.
 454 .Nm Fl xv
 455 shows that those services are
 456 .Sy print/rfc1179
 457 and
 458 .Sy print/ipp-listener .
 459 This situation can be rectified by either enabling
 460 .Sy print/server
 461 or disabling
 462 .Sy rfc1179
 463 and
 464 .Sy ipp-listener .
 465 .Bd -literal
 466 example% svcs -x
 467 svc:/application/print/server:default (LP print server)
 468  State: disabled since Mon Feb 13 17:56:21 2006
 469 Reason: Disabled by an administrator.
 470    See: http://illumos.org/msg/SMF-8000-05
 471    See: lpsched(1M)
 472 Impact: 2 dependent services are not running. (Use -v for list.)
 473 .Ed
 474 .It
 475 In this example, NFS is not working:
 476 .Bd -literal
 477 example$ svcs nfs/client
 478 STATE          STIME    FMRI
 479 offline        16:03:23 svc:/network/nfs/client:default
 480 .Ed
 481 .It
 482 The following example shows that the problem is
 483 .Sy nfs/status .
 484 .Sy nfs/client
 485 is waiting because it depends on
 486 .Sy nfs/nlockmgr ,
 487 which depends on
 488 .Sy nfs/status :
 489 .Bd -literal
 490 example$ svcs -xv nfs/client
 491 svc:/network/nfs/client:default (NFS client)
 492  State: offline since Mon Feb 27 16:03:23 2006
 493 Reason: Service svc:/network/nfs/status:default
 494         is not running because a method failed repeatedly.
 495    See: http://illumos.org/msg/SMF-8000-GE
 496   Path: svc:/network/nfs/client:default
 497           svc:/network/nfs/nlockmgr:default
 498             svc:/network/nfs/status:default
 499    See: man -M /usr/share/man -s 1M mount_nfs
 500    See: /var/svc/log/network-nfs-client:default.log
 501 Impact: This service is not running.
 502 .Ed
 503 .El
 504 .El
 505 .Sh INTERFACE STABILITY
 506 Screen output is
 507 .Sy Uncommitted .
 508 The invocation is
 509 .Sy Committed .
 510 .Sh SEE ALSO
 511 .Xr ps 1 ,
 512 .Xr svcprop 1 ,
 513 .Xr svc.startd 1M ,
 514 .Xr svcadm 1M ,
 515 .Xr svccfg 1M ,
 516 .Xr stat 2 ,
 517 .Xr libscf 3LIB ,
 518 .Xr attributes 5 ,
 519 .Xr fnmatch 5 ,
 520 .Xr smf 5 ,
 521 .Xr zones 5