1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
3 .\" Copyright 2020 Joyent, Inc.
4 .\" 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.
5 .\" 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.
6 .\" 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]
7 .TH SVCS 1 "May 11, 2020"
8 .SH NAME
9 svcs \- report service status
10 .SH SYNOPSIS
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
15
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
21
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
26
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
31
32 .SH DESCRIPTION
33 The \fBsvcs\fR command displays information about service instances as recorded
34 in the service configuration repository.
35 .sp
36 .LP
37 The first form of this command prints one-line status listings for service
38 instances specified by the arguments. Each instance is listed only once. With
39 no arguments, all enabled service instances, even if temporarily disabled, are
40 listed with the columns indicated below.
41 .sp
42 .LP
43 The second form prints one-line status listings for the dependencies or
44 dependents of the service instances specified by the arguments.
45 .sp
46 .LP
47 The third form prints detailed information about specific services and
48 instances.
49 .sp
50 .LP
51 The fourth form explains the states of service instances. For each argument, a
52 block of human-readable text is displayed which explains what state the service
53 is in, and why it is in that state. With no arguments, problematic services are
54 described.
55 .sp
56 .LP
57 Error messages are printed to the standard error stream.
58 .sp
59 .LP
60 The output of this command can be used appropriately as input to the
61 \fBsvcadm\fR(1M) command.
62 .SH OPTIONS
63 The following options are supported:
64 .sp
65 .ne 2
66 .na
67 \fB\fB-?\fR\fR
68 .ad
69 .RS 20n
70 Displays an extended usage message, including column specifiers.
71 .RE
72
73 .sp
74 .ne 2
75 .na
76 \fB\fB-a\fR\fR
77 .ad
78 .RS 20n
79 Show all services, even disabled ones. This option has no effect if services
80 are selected.
81 .RE
82
83 .sp
84 .ne 2
85 .na
86 \fB\fB-d\fR\fR
87 .ad
88 .RS 20n
89 Lists the services or service instances upon which the given service instances
90 depend.
91 .RE
92
93 .sp
94 .ne 2
95 .na
96 \fB\fB-D\fR\fR
97 .ad
98 .RS 20n
99 Lists the service instances that depend on the given services or service
100 instances.
101 .RE
102
103 .sp
104 .ne 2
105 .na
106 \fB\fB-H\fR\fR
107 .ad
108 .RS 20n
109 Omits the column headers.
110 .RE
111
112 .sp
113 .ne 2
114 .na
115 \fB\fB-l\fR\fR
116 .ad
117 .RS 20n
118 (The letter ell.) Displays all available information about the selected
119 services and service instances, with one service attribute displayed for each
120 line. Information for different instances are separated by blank lines.
121 .sp
122 The following specific attributes require further explanation:
123 .sp
124 .ne 2
125 .na
126 \fB\fBdependency\fR\fR
127 .ad
128 .RS 14n
129 Information about a dependency. The grouping and \fBrestart_on\fR properties
130 are displayed first and are separated by a forward slash (\fB/\fR). Next, each
131 entity and its state is listed. See \fBsmf\fR(5) for information about states.
132 In addition to the standard states, each service dependency can have the
133 following state descriptions:
134 .sp
135 .ne 2
136 .na
137 \fB\fBabsent\fR\fR
138 .ad
139 .RS 12n
140 No such service is defined on the system.
141 .RE
142
143 .sp
144 .ne 2
145 .na
146 \fB\fBinvalid\fR\fR
147 .ad
148 .RS 12n
149 The fault management resource identifier (FMRI) is invalid (see \fBsmf\fR(5)).
150 .RE
151
152 .sp
153 .ne 2
154 .na
155 \fB\fBmultiple\fR\fR
156 .ad
157 .RS 12n
158 The entity is a service with multiple instances.
159 .RE
160
161 File dependencies can only have one of the following state descriptions:
162 .sp
163 .ne 2
164 .na
165 \fB\fBabsent\fR\fR
166 .ad
167 .RS 11n
168 No such file on the system.
169 .RE
170
171 .sp
172 .ne 2
173 .na
174 \fB\fBonline\fR\fR
175 .ad
176 .RS 11n
177 The file exists.
178 .sp
179 If the file did not exist the last time that \fBsvc.startd\fR evaluated the
180 service's dependencies, it can consider the dependency to be unsatisfied.
181 \fBsvcadm refresh\fR forces dependency re-evaluation.
182 .RE
183
184 .sp
185 .ne 2
186 .na
187 \fB\fBunknown\fR\fR
188 .ad
189 .RS 11n
190 \fBstat\fR(2) failed for a reason other than \fBENOENT\fR.
191 .RE
192
193 See \fBsmf\fR(5) for additional details about dependencies, grouping, and
194 \fBrestart_on\fR values.
195 .RE
196
197 .sp
198 .ne 2
199 .na
200 \fB\fBenabled\fR\fR
201 .ad
202 .RS 14n
203 Whether the service is enabled or not, and whether it is enabled or disabled
204 temporarily (until the next system reboot). The former is specified as either
205 \fBtrue\fR or \fBfalse\fR, and the latter is designated by the presence of
206 \fB(temporary)\fR.
207 .sp
208 A service might be temporarily disabled because an administrator has run
209 \fBsvcadm disable -t\fR, used \fBsvcadm milestone\fR, or booted the system to a
210 specific milestone. See \fBsvcadm\fR(1M) for details.
211 .sp
212 If a service instance was disabled via
213 \fBsvcadm disable -c\fR
214 , then the provided comment will also be displayed.
215 .RE
216
217 .RE
218
219 .sp
220 .ne 2
221 .na
222 \fB-L\fR
223 .ad
224 .RS 20n
225 Display the log file of the selected services and service instances, one
226 per-line.
227 .RE
228
229 .sp
230 .ne 2
231 .na
232 \fB\fB-o\fR \fIcol\fR[,\fIcol\fR]...\fR
233 .ad
234 .RS 20n
235 Prints the specified columns. Each \fIcol\fR should be a column name. See
236 \fBCOLUMNS\fR below for available columns.
237 .RE
238
239 .sp
240 .ne 2
241 .na
242 \fB\fB-p\fR\fR
243 .ad
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.
249 .RE
250
251 .sp
252 .ne 2
253 .na
254 \fB\fB-R\fR \fIFMRI-instance\fR\fR
255 .ad
256 .RS 20n
257 Selects service instances that have the given service instance as their
258 restarter.
259 .RE
260
261 .sp
262 .ne 2
263 .na
264 \fB\fB-s\fR \fIcol\fR\fR
265 .ad
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.
269 .RE
270
271 .sp
272 .ne 2
273 .na
274 \fB\fB-S\fR \fIcol\fR\fR
275 .ad
276 .RS 20n
277 Sorts by \fIcol\fR in the opposite order as option \fB-s\fR.
278 .RE
279
280 .sp
281 .ne 2
282 .na
283 \fB\fB-v\fR\fR
284 .ad
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.
288 .sp
289 With \fB-x\fR, displays extra information for each explanation.
290 .sp
291 With \fB-l\fR, displays user-visible properties in property groups of type
292 \fBapplication\fR and their description.
293 .RE
294
295 .sp
296 .ne 2
297 .na
298 \fB\fB-x\fR\fR
299 .ad
300 .RS 20n
301 Displays explanations for service states.
302 .sp
303 Without arguments, the \fB-x\fR option explains the states of services which:
304 .RS +4
305 .TP
306 .ie t \(bu
307 .el o
308 are enabled, but are not running.
309 .RE
310 .RS +4
311 .TP
312 .ie t \(bu
313 .el o
314 are preventing another enabled service from running.
315 .RE
316 .RE
317
318 .sp
319 .ne 2
320 .na
321 \fB-z \fIzone\fR
322 .ad
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).
326 .RE
327
328 .sp
329 .ne 2
330 .na
331 \fB-Z\fR
332 .ad
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).
337 .RE
338
339 .SH OPERANDS
340 The following operands are supported:
341 .sp
342 .ne 2
343 .na
344 \fB\fIFMRI\fR\fR
345 .ad
346 .RS 17n
347 A fault management resource identifier (FMRI) that specifies one or more
348 instances (see \fBsmf\fR(5)). FMRIs can be abbreviated by specifying the
349 instance name, or the trailing portion of the service name. For example, given
350 the FMRI:
351 .sp
352 .in +2
353 .nf
354 svc:/network/smtp:sendmail
355 .fi
356 .in -2
357 .sp
358
359 The following are valid abbreviations:
360 .sp
361 .in +2
362 .nf
363 sendmail
364 :sendmail
365 smtp
366 smtp:sendmail
367 network/smtp
368 .fi
369 .in -2
370 .sp
371
372 The following are invalid abbreviations:
373 .sp
374 .in +2
375 .nf
376 mail
377 network
378 network/smt
379 .fi
380 .in -2
381 .sp
382
383 If the FMRI specifies a service, then the command applies to all instances of
384 that service, except when used with the \fB-D\fR option.
385 .sp
386 Abbreviated forms of FMRIs are unstable, and should not be used in scripts or
387 other permanent tools.
388 .RE
389
390 .sp
391 .ne 2
392 .na
393 \fB\fIpattern\fR\fR
394 .ad
395 .RS 17n
396 A pattern that is matched against the \fIFMRI\fRs of service instances
397 according to the "globbing" rules described by \fBfnmatch\fR(5). If the pattern
398 does not begin with \fBsvc:\fR, then \fBsvc:/\fR is prepended. The following is
399 a typical example of a glob pattern:
400 .sp
401 .in +2
402 .nf
403 qexample% svcs \e*keyserv\e*
404 STATE STIME FMRI
405 disabled Aug_02 svc:/network/rpc/keyserv:default
406 .fi
407 .in -2
408 .sp
409
410 .RE
411
412 .sp
413 .ne 2
414 .na
415 \fB\fIFMRI-instance\fR\fR
416 .ad
417 .RS 17n
418 An FMRI that specifies an instance.
419 .RE
420
421 .SH COLUMNS
422 Column names are case insensitive. The default output format is equivalent to
423 "\fB-o\fR \fBstate,stime,fmri\fR". The default sorting columns are \fBSTATE\fR,
424 \fBSTIME\fR, \fBFMRI\fR.
425 .sp
426 .ne 2
427 .na
428 \fB\fBCTID\fR\fR
429 .ad
430 .RS 10n
431 The primary contract ID for the service instance. Not all instances have valid
432 primary contract IDs.
433 .RE
434
435 .sp
436 .ne 2
437 .na
438 \fB\fBDESC\fR\fR
439 .ad
440 .RS 10n
441 A brief description of the service, from its template element. A service might
442 not have a description available, in which case a hyphen (\fB\(hy\fR) is used
443 to denote an empty value.
444 .RE
445
446 .sp
447 .ne 2
448 .na
449 \fB\fBFMRI\fR\fR
450 .ad
451 .RS 10n
452 The \fIFMRI\fR of the service instance.
453 .RE
454
455 .sp
456 .ne 2
457 .na
458 \fB\fBINST\fR\fR
459 .ad
460 .RS 10n
461 The instance name of the service instance.
462 .RE
463
464 .sp
465 .ne 2
466 .na
467 \fB\fBNSTA\fR\fR
468 .ad
469 .RS 10n
470 The abbreviated next state of the service instance, as given in the \fBSTA\fR
471 column description. A hyphen denotes that the instance is not transitioning.
472 Same as \fBSTA\fR otherwise.
473 .RE
474
475 .sp
476 .ne 2
477 .na
478 \fB\fBNSTATE\fR\fR
479 .ad
480 .RS 10n
481 The next state of the service. A hyphen is used to denote that the instance is
482 not transitioning. Same as \fBSTATE\fR otherwise.
483 .RE
484
485 .sp
486 .ne 2
487 .na
488 \fB\fBSCOPE\fR\fR
489 .ad
490 .RS 10n
491 The scope name of the service instance.
492 .RE
493
494 .sp
495 .ne 2
496 .na
497 \fB\fBSVC\fR\fR
498 .ad
499 .RS 10n
500 The service name of the service instance.
501 .RE
502
503 .sp
504 .ne 2
505 .na
506 \fB\fBSTA\fR\fR
507 .ad
508 .RS 10n
509 The abbreviated state of the service instance (see \fBsmf\fR(5)):
510 .sp
511 .ne 2
512 .na
513 \fB\fBDGD\fR\fR
514 .ad
515 .RS 7n
516 degraded
517 .RE
518
519 .sp
520 .ne 2
521 .na
522 \fB\fBDIS\fR\fR
523 .ad
524 .RS 7n
525 disabled
526 .RE
527
528 .sp
529 .ne 2
530 .na
531 \fB\fBLRC\fR\fR
532 .ad
533 .RS 7n
534 legacy \fBrc*.d\fR script-initiated instance
535 .RE
536
537 .sp
538 .ne 2
539 .na
540 \fB\fBMNT\fR\fR
541 .ad
542 .RS 7n
543 maintenance
544 .RE
545
546 .sp
547 .ne 2
548 .na
549 \fB\fBOFF\fR\fR
550 .ad
551 .RS 7n
552 offline
553 .RE
554
555 .sp
556 .ne 2
557 .na
558 \fB\fBON\fR\fR
559 .ad
560 .RS 7n
561 online
562 .RE
563
564 .sp
565 .ne 2
566 .na
567 \fB\fBUN\fR\fR
568 .ad
569 .RS 7n
570 uninitialized
571 .RE
572
573 Absent or unrecognized states are denoted by a question mark (\fB?\fR)
574 character. An asterisk (\fB*\fR) is appended for instances in transition,
575 unless the \fBNSTA\fR or \fBNSTATE\fR column is also being displayed.
576 .sp
577 See \fBsmf\fR(5) for an explanation of service states.
578 .RE
579
580 .sp
581 .ne 2
582 .na
583 \fB\fBSTATE\fR\fR
584 .ad
585 .RS 10n
586 The state of the service instance. An asterisk is appended for instances in
587 transition, unless the \fBNSTA\fR or \fBNSTATE\fR column is also being
588 displayed.
589 .sp
590 See \fBsmf\fR(5) for an explanation of service states.
591 .RE
592
593 .sp
594 .ne 2
595 .na
596 \fB\fBSTIME\fR\fR
597 .ad
598 .RS 10n
599 If the service instance entered the current state within the last 24 hours,
600 this column indicates the time that it did so. Otherwise, this column indicates
601 the date on which it did so, printed with underscores (\fB_\fR) in place of
602 blanks.
603 .RE
604
605 .SH EXAMPLES
606 \fBExample 1 \fRDisplaying the Default Output
607 .sp
608 .LP
609 This example displays default output:
610
611 .sp
612 .in +2
613 .nf
614 example% svcs
615 STATE STIME FMRI
616 \&...
617 legacy_run 13:25:04 lrc:/etc/rc3_d/S42myscript
618 \&...
619 online 13:21:50 svc:/system/svc/restarter:default
620 \&...
621 online 13:25:03 svc:/milestone/multi-user:default
622 \&...
623 online 13:25:07 svc:/milestone/multi-user-server:default
624 \&...
625 .fi
626 .in -2
627 .sp
628
629 .LP
630 \fBExample 2 \fRListing All Local Instances
631 .sp
632 .LP
633 This example lists all local instances of the \fBservice1\fR service.
634
635 .sp
636 .in +2
637 .nf
638 example% svcs -o state,nstate,fmri service1
639 STATE NSTATE FMRI
640 online - svc:/service1:instance1
641 disabled - svc:/service1:instance2
642 .fi
643 .in -2
644 .sp
645
646 .LP
647 \fBExample 3 \fRListing Verbose Information
648 .sp
649 .LP
650 This example lists verbose information.
651
652 .sp
653 .in +2
654 .nf
655 example% svcs -v network/rpc/rstat:udp
656 STATE NSTATE STIME CTID FMRI
657 online - Aug_09 - svc:/network/rpc/rstat:udp
658 .fi
659 .in -2
660 .sp
661
662 .LP
663 \fBExample 4 \fRListing Detailed Information
664 .sp
665 .LP
666 This example lists detailed information about all instances of
667 \fBsystem/service3\fR. Additional fields can be displayed, as appropriate to
668 the managing restarter.
669
670 .sp
671 .in +2
672 .nf
673 example% svcs -l network/rpc/rstat:udp
674
675 fmri svc:/network/rpc/rstat:udp
676 enabled true
677 state online
678 next_state none
679 restarter svc:/network/inetd:default
680 contract_id
681 dependency require_all/error svc:/network/rpc/bind (online)
682 .fi
683 .in -2
684 .sp
685
686 .LP
687 \fBExample 5 \fRListing Processes
688 .sp
689 .in +2
690 .nf
691 example% svcs -p sendmail
692 STATE STIME FMRI
693 online 13:25:13 svc:/network/smtp:sendmail
694 13:25:15 100939 sendmail
695 13:25:15 100940 sendmail
696 .fi
697 .in -2
698 .sp
699
700 .LP
701 \fBExample 6 \fRExplaining Service States Using \fBsvcs\fR \fB-x\fR
702 .sp
703 .LP
704 (a) In this example, \fBsvcs\fR \fB-x\fR has identified that the print/server
705 service being disabled is the root cause of two services which are enabled but
706 not online. \fBsvcs\fR \fB-xv\fR shows that those services are
707 \fBprint/rfc1179\fR and \fBprint/ipp-listener\fR. This situation can be
708 rectified by either enabling \fBprint/server\fR or disabling \fBrfc1179\fR and
709 \fBipp-listener\fR.
710
711 .sp
712 .in +2
713 .nf
714 example% svcs -x
715 svc:/application/print/server:default (LP print server)
716 State: disabled since Mon Feb 13 17:56:21 2006
717 Reason: Disabled by an administrator.
718 See: http://illumos.org/msg/SMF-8000-05
719 See: lpsched(1M)
720 Impact: 2 dependent services are not running. (Use -v for list.)
721 .fi
722 .in -2
723 .sp
724
725 .sp
726 .LP
727 (b) In this example, NFS is not working:
728
729 .sp
730 .in +2
731 .nf
732 example$ svcs nfs/client
733 STATE STIME FMRI
734 offline 16:03:23 svc:/network/nfs/client:default
735 .fi
736 .in -2
737 .sp
738
739 .sp
740 .LP
741 (c) The following example shows that the problem is \fBnfs/status\fR.
742 \fBnfs/client\fR is waiting because it depends on \fBnfs/nlockmgr\fR, which
743 depends on \fBnfs/status\fR:
744
745 .sp
746 .in +2
747 .nf
748 example$ svcs -xv nfs/client
749 svc:/network/nfs/client:default (NFS client)
750 State: offline since Mon Feb 27 16:03:23 2006
751 Reason: Service svc:/network/nfs/status:default
752 is not running because a method failed repeatedly.
753 See: http://illumos.org/msg/SMF-8000-GE
754 Path: svc:/network/nfs/client:default
755 svc:/network/nfs/nlockmgr:default
756 svc:/network/nfs/status:default
757 See: man -M /usr/share/man -s 1M mount_nfs
758 See: /var/svc/log/network-nfs-client:default.log
759 Impact: This service is not running.
760 .fi
761 .in -2
762 .sp
763
764 .SH EXIT STATUS
765 The following exit values are returned:
766 .sp
767 .ne 2
768 .na
769 \fB\fB0\fR\fR
770 .ad
771 .RS 5n
772 Successful command invocation.
773 .RE
774
775 .sp
776 .ne 2
777 .na
778 \fB\fB1\fR\fR
779 .ad
780 .RS 5n
781 Fatal error.
782 .RE
783
784 .sp
785 .ne 2
786 .na
787 \fB\fB2\fR\fR
788 .ad
789 .RS 5n
790 Invalid command line options were specified.
791 .RE
792
793 .SH ATTRIBUTES
794 See \fBattributes\fR(5) for descriptions of the following attributes:
795 .sp
796
797 .sp
798 .TS
799 box;
800 c | c
801 l | l .
802 ATTRIBUTE TYPE ATTRIBUTE VALUE
803 _
804 Interface Stability See below.
805 .TE
806
807 .sp
808 .LP
809 Screen output is Uncommitted. The invocation is Committed.
810 .SH SEE ALSO
811 \fBps\fR(1), \fBsvcprop\fR(1), \fBsvcadm\fR(1M), \fBsvccfg\fR(1M),
812 \fBsvc.startd\fR(1M), \fBstat\fR(2), \fBlibscf\fR(3LIB), \fBattributes\fR(5),
813 \fBfnmatch\fR(5), \fBsmf\fR(5), \fBzones\fR(5)