763 FMD msg URLs should refer to something visible
[illumos-gate.git] / usr / src / man / man1 / svcs.1
bloba7b9d1b5bed4a0a6b9fe098cbcbcadeac42c1615
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 SVCS 1 "Apr 17, 2011"
7 .SH NAME
8 svcs \- report service status
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBsvcs\fR [\fB-aHpv?\fR] [\fB-Z\fR | \fB-z\fR \fIzone\fR] [\fB-o\fR \fIcol\fR[,\fIcol\fR]]... [\fB-R\fR \fIFMRI-instance\fR]...
13      [\fB-sS\fR \fIcol\fR]... [\fIFMRI\fR | \fIpattern\fR]...
14 .fi
16 .LP
17 .nf
18 \fBsvcs\fR {\fB-d\fR | \fB-D\fR} [\fB-Hpv?\fR] [\fB-Z\fR | \fB-z\fR \fIzone\fR] [\fB-o\fR \fIcol\fR[,\fIcol\fR]]... [\fB-sS\fR \fIcol\fR]...
19      [\fIFMRI\fR | \fIpattern\fR] ...
20 .fi
22 .LP
23 .nf
24 \fBsvcs\fR [\fB-l\fR | \fB-L\fR] [\fB-vZ\fR] [\fB-z\fR \fIzone\fR] [\fIFMRI\fR | \fIpattern\fR]...
25 .fi
27 .LP
28 .nf
29 \fBsvcs\fR \fB-x\fR [\fB-v\fR] [\fB-Z\fR | \fB-z\fR \fIzone\fR] [\fIFMRI\fR]...
30 .fi
32 .SH DESCRIPTION
33 .sp
34 .LP
35 The \fBsvcs\fR command displays information about service instances as recorded
36 in the service configuration repository.
37 .sp
38 .LP
39 The first form of this command prints one-line status listings for service
40 instances specified by the arguments. Each instance is listed only once. With
41 no arguments, all enabled service instances, even if temporarily disabled, are
42 listed with the columns indicated below.
43 .sp
44 .LP
45 The second form prints one-line status listings for the dependencies or
46 dependents of the service instances specified by the arguments.
47 .sp
48 .LP
49 The third form prints detailed information about specific services and
50 instances.
51 .sp
52 .LP
53 The fourth form explains the states of service instances. For each argument, a
54 block of human-readable text is displayed which explains what state the service
55 is in, and why it is in that state. With no arguments, problematic services are
56 described.
57 .sp
58 .LP
59 Error messages are printed to the standard error stream.
60 .sp
61 .LP
62 The output of this command can be used appropriately as input to the
63 \fBsvcadm\fR(1M) command.
64 .SH OPTIONS
65 .sp
66 .LP
67 The following options are supported:
68 .sp
69 .ne 2
70 .na
71 \fB\fB-?\fR\fR
72 .ad
73 .RS 20n
74 Displays an extended usage message, including column specifiers.
75 .RE
77 .sp
78 .ne 2
79 .na
80 \fB\fB-a\fR\fR
81 .ad
82 .RS 20n
83 Show all services, even disabled ones. This option has no effect if services
84 are selected.
85 .RE
87 .sp
88 .ne 2
89 .na
90 \fB\fB-d\fR\fR
91 .ad
92 .RS 20n
93 Lists the services or service instances upon which the given service instances
94 depend.
95 .RE
97 .sp
98 .ne 2
99 .na
100 \fB\fB-D\fR\fR
102 .RS 20n
103 Lists the service instances that depend on the given services or service
104 instances.
108 .ne 2
110 \fB\fB-H\fR\fR
112 .RS 20n
113 Omits the column headers.
117 .ne 2
119 \fB\fB-l\fR\fR
121 .RS 20n
122 (The letter ell.) Displays all available information about the selected
123 services and service instances, with one service attribute displayed for each
124 line. Information for different instances are separated by blank lines.
126 The following specific attributes require further explanation:
128 .ne 2
130 \fB\fBdependency\fR\fR
132 .RS 14n
133 Information about a dependency. The grouping and \fBrestart_on\fR properties
134 are displayed first and are separated by a forward slash (\fB/\fR). Next, each
135 entity and its state is listed. See \fBsmf\fR(5) for information about states.
136 In addition to the standard states, each service dependency can have the
137 following state descriptions:
139 .ne 2
141 \fB\fBabsent\fR\fR
143 .RS 12n
144 No such service is defined on the system.
148 .ne 2
150 \fB\fBinvalid\fR\fR
152 .RS 12n
153 The fault management resource identifier (FMRI) is invalid (see \fBsmf\fR(5)).
157 .ne 2
159 \fB\fBmultiple\fR\fR
161 .RS 12n
162 The entity is a service with multiple instances.
165 File dependencies can only have one of the following state descriptions:
167 .ne 2
169 \fB\fBabsent\fR\fR
171 .RS 11n
172 No such file on the system.
176 .ne 2
178 \fB\fBonline\fR\fR
180 .RS 11n
181 The file exists.
183 If the file did not exist the last time that \fBsvc.startd\fR evaluated the
184 service's dependencies, it can consider the dependency to be unsatisfied.
185 \fBsvcadm refresh\fR forces dependency re-evaluation.
189 .ne 2
191 \fB\fBunknown\fR\fR
193 .RS 11n
194 \fBstat\fR(2) failed for a reason other than \fBENOENT\fR.
197 See \fBsmf\fR(5) for additional details about dependencies, grouping, and
198 \fBrestart_on\fR values.
202 .ne 2
204 \fB\fBenabled\fR\fR
206 .RS 14n
207 Whether the service is enabled or not, and whether it is enabled or disabled
208 temporarily (until the next system reboot). The former is specified as either
209 \fBtrue\fR or \fBfalse\fR, and the latter is designated by the presence of
210 \fB(temporary)\fR.
212 A service might be temporarily disabled because an administrator has run
213 \fBsvcadm disable -t\fR, used \fBsvcadm milestone\fR, or booted the system to a
214 specific milestone. See \fBsvcadm\fR(1M) for details.
220 .ne 2
222 \fB-L\fR
224 .RS 20n
225 Display the log file of the selected services and service instances, one
226 per-line.
230 .ne 2
232 \fB\fB-o\fR \fIcol\fR[,\fIcol\fR]...\fR
234 .RS 20n
235 Prints the specified columns. Each \fIcol\fR should be a column name. See
236 \fBCOLUMNS\fR below for available columns.
240 .ne 2
242 \fB\fB-p\fR\fR
244 .RS 20n
245 Lists processes associated with each service instance. A service instance can
246 have no associated processes. The process ID, start time, and command name
247 (\fBPID\fR, \fBSTIME\fR, and \fBCMD\fR fields from \fBps\fR(1)) are displayed
248 for each process.
252 .ne 2
254 \fB\fB-R\fR \fIFMRI-instance\fR\fR
256 .RS 20n
257 Selects service instances that have the given service instance as their
258 restarter.
262 .ne 2
264 \fB\fB-s\fR \fIcol\fR\fR
266 .RS 20n
267 Sorts output by column. \fIcol\fR should be a column name. See \fBCOLUMNS\fR
268 below for available columns. Multiple \fB-s\fR options behave additively.
272 .ne 2
274 \fB\fB-S\fR \fIcol\fR\fR
276 .RS 20n
277 Sorts by \fIcol\fR in the opposite order as option \fB-s\fR.
281 .ne 2
283 \fB\fB-v\fR\fR
285 .RS 20n
286 Without \fB-x\fR or \fB-l\fR, displays verbose columns: \fBSTATE\fR,
287 \fBNSTATE\fR, \fBSTIME\fR, \fBCTID\fR, and \fBFMRI\fR.
289 With \fB-x\fR, displays extra information for each explanation.
291 With \fB-l\fR, displays user-visible properties in property groups of type
292 \fBapplication\fR and their description.
296 .ne 2
298 \fB\fB-x\fR\fR
300 .RS 20n
301 Displays explanations for service states.
303 Without arguments, the \fB-x\fR option explains the states of services which:
304 .RS +4
306 .ie t \(bu
307 .el o
308 are enabled, but are not running.
310 .RS +4
312 .ie t \(bu
313 .el o
314 are preventing another enabled service from running.
319 .ne 2
321 \fB-z \fIzone\fR
323 .RS 20n
324 Display only the services in the \fIzone\fR.  This option is only applicable
325 in the global zone, see \fBzones\fR(5).
329 .ne 2
331 \fB-Z\fR
333 .RS 20n
334 Display services from all zones, with an additional column indicating in which
335 zone the service is running.  This option is only applicable in the global
336 zone, see \fBzones\fR(5).
339 .SH OPERANDS
342 The following operands are supported:
344 .ne 2
346 \fB\fIFMRI\fR\fR
348 .RS 17n
349 A fault management resource identifier (FMRI) that specifies one or more
350 instances (see \fBsmf\fR(5)). FMRIs can be abbreviated by specifying the
351 instance name, or the trailing portion of the service name. For example, given
352 the FMRI:
354 .in +2
356 svc:/network/smtp:sendmail
358 .in -2
361 The following are valid abbreviations:
363 .in +2
365 sendmail
366 :sendmail
367 smtp
368 smtp:sendmail
369 network/smtp
371 .in -2
374 The following are invalid abbreviations:
376 .in +2
378 mail
379 network
380 network/smt
382 .in -2
385 If the FMRI specifies a service, then the command applies to all instances of
386 that service, except when used with the \fB-D\fR option.
388 Abbreviated forms of FMRIs are unstable, and should not be used in scripts or
389 other permanent tools.
393 .ne 2
395 \fB\fIpattern\fR\fR
397 .RS 17n
398 A pattern that is matched against the \fIFMRI\fRs of service instances
399 according to the "globbing" rules described by \fBfnmatch\fR(5). If the pattern
400 does not begin with \fBsvc:\fR, then \fBsvc:/\fR is prepended. The following is
401 a typical example of a glob pattern:
403 .in +2
405 qexample% svcs \e*keyserv\e*
406 STATE          STIME     FMRI
407 disabled       Aug_02    svc:/network/rpc/keyserv:default
409 .in -2
415 .ne 2
417 \fB\fIFMRI-instance\fR\fR
419 .RS 17n
420 An FMRI that specifies an instance.
423 .SH COLUMNS
426 Column names are case insensitive. The default output format is equivalent to
427 "\fB-o\fR \fBstate,stime,fmri\fR". The default sorting columns are \fBSTATE\fR,
428 \fBSTIME\fR, \fBFMRI\fR.
430 .ne 2
432 \fB\fBCTID\fR\fR
434 .RS 10n
435 The primary contract ID for the service instance. Not all instances have valid
436 primary contract IDs.
440 .ne 2
442 \fB\fBDESC\fR\fR
444 .RS 10n
445 A brief description of the service, from its template element. A service might
446 not have a description available, in which case a hyphen (\fB\(hy\fR) is used
447 to denote an empty value.
451 .ne 2
453 \fB\fBFMRI\fR\fR
455 .RS 10n
456 The \fIFMRI\fR of the service instance.
460 .ne 2
462 \fB\fBINST\fR\fR
464 .RS 10n
465 The instance name of the service instance.
469 .ne 2
471 \fB\fBNSTA\fR\fR
473 .RS 10n
474 The abbreviated next state of the service instance, as given in the \fBSTA\fR
475 column description. A hyphen denotes that the instance is not transitioning.
476 Same as \fBSTA\fR otherwise.
480 .ne 2
482 \fB\fBNSTATE\fR\fR
484 .RS 10n
485 The next state of the service. A hyphen is used to denote that the instance is
486 not transitioning. Same as \fBSTATE\fR otherwise.
490 .ne 2
492 \fB\fBSCOPE\fR\fR
494 .RS 10n
495 The scope name of the service instance.
499 .ne 2
501 \fB\fBSVC\fR\fR
503 .RS 10n
504 The service name of the service instance.
508 .ne 2
510 \fB\fBSTA\fR\fR
512 .RS 10n
513 The abbreviated state of the service instance (see \fBsmf\fR(5)):
515 .ne 2
517 \fB\fBDGD\fR\fR
519 .RS 7n
520 degraded
524 .ne 2
526 \fB\fBDIS\fR\fR
528 .RS 7n
529 disabled
533 .ne 2
535 \fB\fBLRC\fR\fR
537 .RS 7n
538 legacy \fBrc*.d\fR script-initiated instance
542 .ne 2
544 \fB\fBMNT\fR\fR
546 .RS 7n
547 maintenance
551 .ne 2
553 \fB\fBOFF\fR\fR
555 .RS 7n
556 offline
560 .ne 2
562 \fB\fBON\fR\fR
564 .RS 7n
565 online
569 .ne 2
571 \fB\fBUN\fR\fR
573 .RS 7n
574 uninitialized
577 Absent or unrecognized states are denoted by a question mark (\fB?\fR)
578 character. An asterisk (\fB*\fR) is appended for instances in transition,
579 unless the \fBNSTA\fR or \fBNSTATE\fR column is also being displayed.
581 See \fBsmf\fR(5) for an explanation of service states.
585 .ne 2
587 \fB\fBSTATE\fR\fR
589 .RS 10n
590 The state of the service instance. An asterisk is appended for instances in
591 transition, unless the \fBNSTA\fR or \fBNSTATE\fR column is also being
592 displayed.
594 See \fBsmf\fR(5) for an explanation of service states.
598 .ne 2
600 \fB\fBSTIME\fR\fR
602 .RS 10n
603 If the service instance entered the current state within the last 24 hours,
604 this column indicates the time that it did so. Otherwise, this column indicates
605 the date on which it did so, printed with underscores (\fB_\fR) in place of
606 blanks.
609 .SH EXAMPLES
611 \fBExample 1 \fRDisplaying the Default Output
614 This example displays default output:
617 .in +2
619 example% svcs
620 STATE          STIME    FMRI
621 \&...
622 legacy_run     13:25:04 lrc:/etc/rc3_d/S42myscript
623 \&...
624 online         13:21:50 svc:/system/svc/restarter:default
625 \&...
626 online         13:25:03 svc:/milestone/multi-user:default
627 \&...
628 online         13:25:07 svc:/milestone/multi-user-server:default
629 \&...
631 .in -2
635 \fBExample 2 \fRListing All Local Instances
638 This example lists all local instances of the \fBservice1\fR service.
641 .in +2
643 example% svcs -o state,nstate,fmri service1
644 STATE        NSTATE        FMRI
645 online       -             svc:/service1:instance1
646 disabled     -             svc:/service1:instance2
648 .in -2
652 \fBExample 3 \fRListing Verbose Information
655 This example lists verbose information.
658 .in +2
660 example% svcs -v network/rpc/rstat:udp
661 STATE          NSTATE        STIME    CTID   FMRI
662 online         -             Aug_09        - svc:/network/rpc/rstat:udp
664 .in -2
668 \fBExample 4 \fRListing Detailed Information
671 This example lists detailed information about all instances of
672 \fBsystem/service3\fR. Additional fields can be displayed, as appropriate to
673 the managing restarter.
676 .in +2
678 example% svcs -l network/rpc/rstat:udp
680 fmri         svc:/network/rpc/rstat:udp
681 enabled      true
682 state        online
683 next_state   none
684 restarter    svc:/network/inetd:default
685 contract_id
686 dependency   require_all/error svc:/network/rpc/bind (online)
688 .in -2
692 \fBExample 5 \fRListing Processes
694 .in +2
696 example% svcs -p sendmail
697 STATE          STIME    FMRI
698 online         13:25:13 svc:/network/smtp:sendmail
699                13:25:15   100939 sendmail
700 13:25:15   100940 sendmail
702 .in -2
706 \fBExample 6 \fRExplaining Service States Using \fBsvcs\fR \fB-x\fR
709 (a) In this example, \fBsvcs\fR \fB-x\fR has identified that the print/server
710 service being disabled is the root cause of two services which are enabled but
711 not online. \fBsvcs\fR \fB-xv\fR shows that those services are
712 \fBprint/rfc1179\fR and \fBprint/ipp-listener\fR. This situation can be
713 rectified by either enabling \fBprint/server\fR or disabling \fBrfc1179\fR and
714 \fBipp-listener\fR.
717 .in +2
719 example% svcs -x
720 svc:/application/print/server:default (LP print server)
721  State: disabled since Mon Feb 13 17:56:21 2006
722 Reason: Disabled by an administrator.
723    See: http://illumos.org/msg/SMF-8000-05
724    See: lpsched(1M)
725 Impact: 2 dependent services are not running. (Use -v for list.)
727 .in -2
732 (b) In this example, NFS is not working:
735 .in +2
737 example$ svcs nfs/client
738 STATE          STIME    FMRI
739 offline        16:03:23 svc:/network/nfs/client:default
741 .in -2
746 (c) The following example shows that the problem is \fBnfs/status\fR.
747 \fBnfs/client\fR is waiting because it depends on \fBnfs/nlockmgr\fR, which
748 depends on \fBnfs/status\fR:
751 .in +2
753 example$ svcs -xv nfs/client
754 svc:/network/nfs/client:default (NFS client)
755  State: offline since Mon Feb 27 16:03:23 2006
756 Reason: Service svc:/network/nfs/status:default
757         is not running because a method failed repeatedly.
758    See: http://illumos.org/msg/SMF-8000-GE
759   Path: svc:/network/nfs/client:default
760           svc:/network/nfs/nlockmgr:default
761             svc:/network/nfs/status:default
762    See: man -M /usr/share/man -s 1M mount_nfs
763    See: /var/svc/log/network-nfs-client:default.log
764 Impact: This service is not running.
766 .in -2
769 .SH EXIT STATUS
772 The following exit values are returned:
774 .ne 2
776 \fB\fB0\fR\fR
778 .RS 5n
779 Successful command invocation.
783 .ne 2
785 \fB\fB1\fR\fR
787 .RS 5n
788 Fatal error.
792 .ne 2
794 \fB\fB2\fR\fR
796 .RS 5n
797 Invalid command line options were specified.
800 .SH ATTRIBUTES
803 See \fBattributes\fR(5) for descriptions of the following attributes:
808 box;
809 c | c
810 l | l .
811 ATTRIBUTE TYPE  ATTRIBUTE VALUE
813 Interface Stability     See below.
818 Screen output is Uncommitted. The invocation is Committed.
819 .SH SEE ALSO
822 \fBps\fR(1), \fBsvcprop\fR(1), \fBsvcadm\fR(1M), \fBsvccfg\fR(1M),
823 \fBsvc.startd\fR(1M), \fBstat\fR(2), \fBlibscf\fR(3LIB), \fBattributes\fR(5),
824 \fBfnmatch\fR(5), \fBsmf\fR(5), \fBzones\fR(5)