| blob | f08254a89f508413f056c44e7aaee46d81585bb6 |
1 '\" te
2 .\" Copyright (c) 2009, 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 IPMPSTAT 1M "Feb 10, 2009"
7 .SH NAME
8 ipmpstat \- display IPMP subsystem status
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBipmpstat\fR [\fB-n\fR] [\fB-o\fR \fIfield\fR[,...] [\fB-P\fR]] \fB-a\fR|\fB-g\fR|\fB-i\fR|\fB-p\fR|\fB-t\fR
13 .fi
15 .SH DESCRIPTION
16 .sp
17 .LP
18 The \fBipmpstat\fR command concisely displays information about the IPMP
19 subsystem. It supports five different output modes, each of which provides a
20 different view of the IPMP subsystem (address, group, interface, probe, and
21 target), described below. At most one output mode may be specified per
22 invocation, and the displayed information is guaranteed to be self-consistent.
23 It also provides a parseable output format which may be used by scripts to
24 examine the state of the IPMP subsystem. Only basic privileges are needed to
25 invoke \fBipmpstat\fR, with the exception of probe mode which requires all
26 privileges.
27 .SH OPTIONS
28 .sp
29 .LP
30 The following options are supported:
31 .sp
32 .ne 2
33 .na
34 \fB\fB-a\fR\fR
35 .ad
36 .sp .6
37 .RS 4n
38 Display IPMP data address information ("address" output mode).
39 .RE
41 .sp
42 .ne 2
43 .na
44 \fB\fB-g\fR\fR
45 .ad
46 .sp .6
47 .RS 4n
48 Display IPMP group information ("group" output mode).
49 .RE
51 .sp
52 .ne 2
53 .na
54 \fB\fB-i\fR\fR
55 .ad
56 .sp .6
57 .RS 4n
58 Display IP interface information ("interface" output mode).
59 .RE
61 .sp
62 .ne 2
63 .na
64 \fB\fB-n\fR\fR
65 .ad
66 .sp .6
67 .RS 4n
68 Display IP addresses numerically, rather than attempting to resolve them to
69 hostnames. This option may be used in any output mode.
70 .RE
72 .sp
73 .ne 2
74 .na
75 \fB\fB-o\fR \fIfield\fR[,...]\fR
76 .ad
77 .sp .6
78 .RS 4n
79 Display only the specified output fields, in order. The list of field names is
80 case-insensitive and comma-separated. The field names that are supported depend
81 on the selected output mode, described below. The special field name \fBall\fR
82 may be used to display all fields for a given output mode.
83 .RE
85 .sp
86 .ne 2
87 .na
88 \fB\fB-p\fR\fR
89 .ad
90 .sp .6
91 .RS 4n
92 Display IPMP probe information ("probe" output mode).
93 .RE
95 .sp
96 .ne 2
97 .na
98 \fB\fB-t\fR\fR
99 .ad
100 .sp .6
101 .RS 4n
102 Display IPMP target information ("target" output mode).
103 .RE
105 .sp
106 .ne 2
107 .na
108 \fB\fB-P\fR\fR
109 .ad
110 .sp .6
111 .RS 4n
112 Display using a machine-parseable format, described below. If this option is
113 specified, an explicit list of fields must be specified using the \fB-o\fR
114 option.
115 .RE
117 .SH OUTPUT MODES
118 .sp
119 .LP
120 The \fBipmpstat\fR utility supports the output modes listed below. Note that
121 these modes map to some of the options described above.
122 .sp
123 .ne 2
124 .na
125 \fBAddress Mode\fR
126 .ad
127 .sp .6
128 .RS 4n
129 Address mode displays the state of all IPMP data addresses on the system. The
130 following output fields are supported:
131 .sp
132 .ne 2
133 .na
134 \fB\fBADDRESS\fR\fR
135 .ad
136 .sp .6
137 .RS 4n
138 The hostname (or IP address) associated with the information. Note that because
139 duplicate down addresses may exist, the address must be taken together with the
140 \fBGROUP\fR to form a unique identity. For a given IPMP group, if duplicate
141 addresses exist, at most one will be displayed, and an up address will always
142 take precedence.
143 .RE
145 .sp
146 .ne 2
147 .na
148 \fB\fBSTATE\fR\fR
149 .ad
150 .sp .6
151 .RS 4n
152 The state of the address. Either \fBup\fR if the address is \fBIFF_UP\fR (see
153 \fBifconfig\fR(1M)), or \fBdown\fR if the address is not \fBIFF_UP\fR.
154 .RE
156 .sp
157 .ne 2
158 .na
159 \fB\fBGROUP\fR\fR
160 .ad
161 .sp .6
162 .RS 4n
163 The IPMP IP interface hosting the address.
164 .RE
166 .sp
167 .ne 2
168 .na
169 \fB\fBINBOUND\fR\fR
170 .ad
171 .sp .6
172 .RS 4n
173 The underlying IP interface that will receive packets for this address. This
174 may change in response to external events such as IP interface failure. If this
175 field is empty, then the system will not accept IP packets sent to this address
176 (for example, because the address is down or because there are no active IP
177 interfaces left in the IPMP group).
178 .RE
180 .sp
181 .ne 2
182 .na
183 \fB\fBOUTBOUND\fR\fR
184 .ad
185 .sp .6
186 .RS 4n
187 The underlying IP interfaces that will send packets using this source address.
188 This may change in response to external events such as IP interface failure. If
189 this field is empty, then the system will not send packets with this address as
190 a source (for example, because the address is down or because there are no
191 active IP interfaces left in the IPMP group).
192 .RE
194 If \fB-o\fR is not specified, all output fields are displayed.
195 .RE
197 .sp
198 .ne 2
199 .na
200 \fBGroup Mode\fR
201 .ad
202 .sp .6
203 .RS 4n
204 Group mode displays the state of all IPMP groups on the system. The following
205 output fields are supported:
206 .sp
207 .ne 2
208 .na
209 \fB\fBGROUP\fR\fR
210 .ad
211 .sp .6
212 .RS 4n
213 The IPMP IP interface name associated with the information. For the anonymous
214 group (see \fBin.mpathd\fR(1M)), this field will be empty.
215 .RE
217 .sp
218 .ne 2
219 .na
220 \fB\fBGROUPNAME\fR\fR
221 .ad
222 .sp .6
223 .RS 4n
224 The IPMP group name. For the anonymous group, this field will be empty.
225 .RE
227 .sp
228 .ne 2
229 .na
230 \fB\fBSTATE\fR\fR
231 .ad
232 .sp .6
233 .RS 4n
234 The state of the group:
235 .sp
236 .ne 2
237 .na
238 \fB\fBok\fR\fR
239 .ad
240 .RS 12n
241 All interfaces in the group are usable.
242 .RE
244 .sp
245 .ne 2
246 .na
247 \fB\fBdegraded\fR\fR
248 .ad
249 .RS 12n
250 Some (but not all) interfaces in the group are usable.
251 .RE
253 .sp
254 .ne 2
255 .na
256 \fB\fBfailed\fR\fR
257 .ad
258 .RS 12n
259 No interfaces in the group are usable.
260 .RE
262 .RE
264 .sp
265 .ne 2
266 .na
267 \fB\fBFDT\fR\fR
268 .ad
269 .sp .6
270 .RS 4n
271 The probe-based failure detection time. If probe-based failure detection is
272 disabled, this field will be empty.
273 .RE
275 .sp
276 .ne 2
277 .na
278 \fB\fBINTERFACES\fR\fR
279 .ad
280 .sp .6
281 .RS 4n
282 The list of underlying IP interfaces in the group. The list is divided into
283 three parts:
284 .RS +4
285 .TP
286 1.
287 Active interfaces are listed first and not enclosed in any brackets or
288 parenthesis. Active interfaces are those being used by the system to send or
289 receive data traffic.
290 .RE
291 .RS +4
292 .TP
293 2.
294 \fBINACTIVE\fR interfaces are listed next and enclosed in parenthesis.
295 \fBINACTIVE\fR interfaces are those that are functioning, but not being used
296 according to administrative policy.
297 .RE
298 .RS +4
299 .TP
300 3.
301 Unusable interfaces are listed last and enclosed in brackets. Unusable
302 interfaces are those that cannot be used at all in their present configuration
303 (for example, \fBFAILED\fR or \fBOFFLINE\fR).
304 .RE
305 .RE
307 If \fB-o\fR is not specified, all output fields are displayed.
308 .RE
310 .sp
311 .ne 2
312 .na
313 \fBInterface Mode\fR
314 .ad
315 .sp .6
316 .RS 4n
317 Interface mode displays the state of all IP interfaces that are tracked by
318 \fBin.mpathd\fR on the system. The following output fields are supported:
319 .sp
320 .ne 2
321 .na
322 \fB\fBINTERFACE\fR\fR
323 .ad
324 .sp .6
325 .RS 4n
326 The IP interface name associated with the information.
327 .RE
329 .sp
330 .ne 2
331 .na
332 \fB\fBACTIVE\fR\fR
333 .ad
334 .sp .6
335 .RS 4n
336 Either \fByes\fR or \fBno\fR, depending on whether the IP interface is being
337 used by the system for IP data traffic.
338 .RE
340 .sp
341 .ne 2
342 .na
343 \fB\fBGROUP\fR\fR
344 .ad
345 .sp .6
346 .RS 4n
347 The IPMP IP interface associated with the IP interface. For IP interfaces in
348 the anonymous group (see \fBin.mpathd\fR(1M)), this field will be empty.
349 .RE
351 .sp
352 .ne 2
353 .na
354 \fB\fBFLAGS\fR\fR
355 .ad
356 .sp .6
357 .RS 4n
358 Assorted information about the IP interface:
359 .sp
360 .ne 2
361 .na
362 \fB\fBi\fR\fR
363 .ad
364 .RS 5n
365 Unusable due to being \fBINACTIVE\fR.
366 .RE
368 .sp
369 .ne 2
370 .na
371 \fB\fBs\fR\fR
372 .ad
373 .RS 5n
374 Marked \fBSTANDBY\fR.
375 .RE
377 .sp
378 .ne 2
379 .na
380 \fB\fBm\fR\fR
381 .ad
382 .RS 5n
383 Nominated to send/receive IPv4 multicast for its IPMP group.
384 .RE
386 .sp
387 .ne 2
388 .na
389 \fB\fBb\fR\fR
390 .ad
391 .RS 5n
392 Nominated to send/receive IPv4 broadcast for its IPMP group.
393 .RE
395 .sp
396 .ne 2
397 .na
398 \fB\fBM\fR\fR
399 .ad
400 .RS 5n
401 Nominated to send/receive IPv6 multicast for its IPMP group.
402 .RE
404 .sp
405 .ne 2
406 .na
407 \fB\fBd\fR\fR
408 .ad
409 .RS 5n
410 Unusable due to being \fBdown\fR.
411 .RE
413 .sp
414 .ne 2
415 .na
416 \fB\fBh\fR\fR
417 .ad
418 .RS 5n
419 Unusable due to being brought \fBOFFLINE\fR by \fBin.mpathd\fR because of a
420 duplicate hardware address.
421 .RE
423 .RE
425 .sp
426 .ne 2
427 .na
428 \fB\fBLINK\fR\fR
429 .ad
430 .sp .6
431 .RS 4n
432 The state of link-based failure detection:
433 .sp
434 .ne 2
435 .na
436 \fB\fBup\fR\fR
437 .ad
438 .sp .6
439 .RS 4n
440 The link is up.
441 .RE
443 .sp
444 .ne 2
445 .na
446 \fB\fBdown\fR\fR
447 .ad
448 .sp .6
449 .RS 4n
450 The link is down.
451 .RE
453 .sp
454 .ne 2
455 .na
456 \fB\fBunknown\fR\fR
457 .ad
458 .sp .6
459 .RS 4n
460 The network driver does not report link state changes.
461 .RE
463 .RE
465 .sp
466 .ne 2
467 .na
468 \fB\fBPROBE\fR\fR
469 .ad
470 .sp .6
471 .RS 4n
472 The state of probe-based failure detection:
473 .sp
474 .ne 2
475 .na
476 \fB\fBok\fR\fR
477 .ad
478 .sp .6
479 .RS 4n
480 Probes detect no problems.
481 .RE
483 .sp
484 .ne 2
485 .na
486 \fB\fBfailed\fR\fR
487 .ad
488 .sp .6
489 .RS 4n
490 Probes detect failure.
491 .RE
493 .sp
494 .ne 2
495 .na
496 \fB\fBunknown\fR\fR
497 .ad
498 .sp .6
499 .RS 4n
500 Probes cannot be sent since no suitable probe targets are known.
501 .RE
503 .sp
504 .ne 2
505 .na
506 \fB\fBdisabled\fR\fR
507 .ad
508 .sp .6
509 .RS 4n
510 Probes have been disabled because a unique IP test address has not been
511 configured.
512 .RE
514 .RE
516 .sp
517 .ne 2
518 .na
519 \fB\fBSTATE\fR\fR
520 .ad
521 .sp .6
522 .RS 4n
523 The overall state of the interface:
524 .sp
525 .ne 2
526 .na
527 \fB\fBok\fR\fR
528 .ad
529 .sp .6
530 .RS 4n
531 The interface is online and functioning properly based on the configured
532 failure detection methods.
533 .RE
535 .sp
536 .ne 2
537 .na
538 \fB\fBfailed\fR\fR
539 .ad
540 .sp .6
541 .RS 4n
542 The interface is online but has a link state of \fBdown\fR or a probe state of
543 \fBfailed\fR.
544 .RE
546 .sp
547 .ne 2
548 .na
549 \fB\fBoffline\fR\fR
550 .ad
551 .sp .6
552 .RS 4n
553 The interface is offline.
554 .RE
556 .sp
557 .ne 2
558 .na
559 \fB\fBunknown\fR\fR
560 .ad
561 .sp .6
562 .RS 4n
563 The interface is online but may or may not be functioning because the
564 configured failure detection methods are in \fBunknown\fR states.
565 .RE
567 .RE
569 If \fB-o\fR is not specified, all output fields are displayed.
570 .RE
572 .sp
573 .ne 2
574 .na
575 \fBProbe Mode\fR
576 .ad
577 .sp .6
578 .RS 4n
579 Probe mode displays information about the probes being sent by \fBin.mpathd\fR.
580 Unlike other output modes, this mode runs until explicitly terminated using
581 \fBCtrl-C\fR. The following output fields are supported:
582 .sp
583 .ne 2
584 .na
585 \fB\fBTIME\fR\fR
586 .ad
587 .sp .6
588 .RS 4n
589 The time the probe was sent, relative to when \fBipmpstat\fR was started. If
590 the probe was sent prior to starting \fBipmpstat\fR, the time will be negative.
591 .RE
593 .sp
594 .ne 2
595 .na
596 \fB\fBPROBE\fR\fR
597 .ad
598 .sp .6
599 .RS 4n
600 An identifier representing the probe. The identifier will start at zero and
601 will monotonically increment for each probe sent by \fBin.mpathd\fR over a
602 given interface. To enable more detailed analysis by packet monitoring tools,
603 this identifier matches the \fBicmp_seq\fR field of the ICMP probe packet.
604 .RE
606 .sp
607 .ne 2
608 .na
609 \fB\fBINTERFACE\fR\fR
610 .ad
611 .sp .6
612 .RS 4n
613 The IP interface the probe was sent on.
614 .RE
616 .sp
617 .ne 2
618 .na
619 \fB\fBTARGET\fR\fR
620 .ad
621 .sp .6
622 .RS 4n
623 The hostname (or IP address) of the target the probe was sent to.
624 .RE
626 .sp
627 .ne 2
628 .na
629 \fB\fBNETRTT\fR\fR
630 .ad
631 .sp .6
632 .RS 4n
633 The network round-trip-time for the probe. This is the time between when the IP
634 module sends the probe and when the IP module receives the acknowledgment. If
635 \fBin.mpathd\fR has concluded that the probe has been lost, this field will be
636 empty.
637 .RE
639 .sp
640 .ne 2
641 .na
642 \fB\fBRTT\fR\fR
643 .ad
644 .sp .6
645 .RS 4n
646 The total round-trip-time for the probe. This is the time between when
647 \fBin.mpathd\fR starts executing the code to send the probe, and when it
648 completes processing the \fBack\fR. If \fBin.mpathd\fR has concluded that the
649 probe has been lost, this field will be empty. Spikes in the total round-trip
650 time that are not present in the network round-trip time indicate that the
651 local system itself is overloaded.
652 .RE
654 .sp
655 .ne 2
656 .na
657 \fB\fBRTTAVG\fR\fR
658 .ad
659 .sp .6
660 .RS 4n
661 The average round-trip-time to \fBTARGET\fR over \fBINTERFACE\fR. This aids
662 identification of slow targets. If there is insufficient data to calculate the
663 average, this field will be empty.
664 .RE
666 .sp
667 .ne 2
668 .na
669 \fB\fBRTTDEV\fR\fR
670 .ad
671 .sp .6
672 .RS 4n
673 The standard deviation for the round-trip-time to \fBTARGET\fR over
674 \fBINTERFACE\fR. This aids identification of jittery targets. If there is
675 insufficient data to calculate the standard deviation, this field will be
676 empty.
677 .RE
679 If \fB-o\fR is not specified, all fields except for \fBRTTAVG\fR and
680 \fBRTTDEV\fR are displayed.
681 .RE
683 .sp
684 .ne 2
685 .na
686 \fBTarget Mode\fR
687 .ad
688 .sp .6
689 .RS 4n
690 Target mode displays IPMP probe target information. The following output fields
691 are supported:
692 .sp
693 .ne 2
694 .na
695 \fB\fBINTERFACE\fR\fR
696 .ad
697 .sp .6
698 .RS 4n
699 The IP interface name associated with the information.
700 .RE
702 .sp
703 .ne 2
704 .na
705 \fB\fBMODE\fR\fR
706 .ad
707 .sp .6
708 .RS 4n
709 The probe target discovery mode:
710 .sp
711 .ne 2
712 .na
713 \fB\fBroutes\fR\fR
714 .ad
715 .RS 13n
716 Probe targets found by means of the routing table.
717 .RE
719 .sp
720 .ne 2
721 .na
722 \fB\fBmulticast\fR\fR
723 .ad
724 .RS 13n
725 Probe targets found by means of multicast ICMP probes.
726 .RE
728 .sp
729 .ne 2
730 .na
731 \fB\fBdisabled\fR\fR
732 .ad
733 .RS 13n
734 Probe-based failure detection is disabled.
735 .RE
737 .RE
739 .sp
740 .ne 2
741 .na
742 \fB\fBTESTADDR\fR\fR
743 .ad
744 .sp .6
745 .RS 4n
746 The hostname (or IP address) that will be used for sending and receiving
747 probes. If a unique test address has not been configured, this field will be
748 empty. Note that if an IP interface is configured with both IPv4 and IPv6 test
749 addresses, probe target information will be displayed separately for each test
750 address.
751 .RE
753 .sp
754 .ne 2
755 .na
756 \fB\fBTARGETS\fR\fR
757 .ad
758 .sp .6
759 .RS 4n
760 A space-separated list of probe target hostnames (or IP addresses), in firing
761 order. If no probe targets could be found, this field will be empty.
762 .RE
764 If \fB-o\fR is not specified, all output fields are displayed.
765 .RE
767 .SH OUTPUT FORMAT
768 .sp
769 .LP
770 By default, \fBipmpstat\fR uses a human-friendly tabular format for its output
771 modes, where each row contains one or more fields of information about a given
772 object, which is in turn uniquely identified by one or more of those fields. In
773 this format, a header identifying the fields is displayed above the table (and
774 after each screenful of information), fields are separated by whitespace, empty
775 fields are represented by \fB--\fR (double hyphens), and other visual aids are
776 used. If the value for a field cannot be determined, its value will be
777 displayed as "\fB?\fR" and a diagnostic message will be output to standard
778 error.
779 .sp
780 .LP
781 Machine-parseable format also uses a tabular format, but is designed to be
782 efficient to programmatically parse. Specifically, machine-parseable format
783 differs from human-friendly format in the following ways:
784 .RS +4
785 .TP
786 .ie t \(bu
787 .el o
788 No headers are displayed.
789 .RE
790 .RS +4
791 .TP
792 .ie t \(bu
793 .el o
794 Fields with empty values yield no output, rather than showing \fB--\fR.
795 .RE
796 .RS +4
797 .TP
798 .ie t \(bu
799 .el o
800 Fields are separated by a single colon (\fB:\fR), rather than variable amounts
801 of whitespace.
802 .RE
803 .RS +4
804 .TP
805 .ie t \(bu
806 .el o
807 If multiple fields are requested, and a literal \fB:\fR or a backslash
808 (\fB\e\fR) occur in a field's value, they are escaped by prefixing them with
809 \fB\e\fR\&.
810 .RE
811 .SH EXAMPLES
812 .LP
813 \fBExample 1 \fRObtaining Failure Detection Time of a Specific Interface
814 .sp
815 .LP
816 The following code uses the machine-parseable output format to create a
817 \fBksh\fR function that outputs the failure detection time of a given IPMP IP
818 interface:
820 .sp
821 .in +2
822 .nf
823 getfdt() {
824 ipmpstat -gP -o group,fdt | while IFS=: read group fdt; do
825 [[ "$group" = "$1" ]] && { echo "$fdt"; return; }
826 done
827 }
828 .fi
829 .in -2
830 .sp
832 .SH ATTRIBUTES
833 .sp
834 .LP
835 See \fBattributes\fR(5) for descriptions of the following attributes:
836 .sp
837 .LP
838 \fB/usr/sbin/ipmpstat\fR:
839 .sp
841 .sp
842 .TS
843 box;
844 c | c
845 l | l .
846 ATTRIBUTE TYPE ATTRIBUTE VALUE
847 _
848 Interface Stability Committed
849 _
850 Machine-Parseable Format Committed
851 _
852 Human-Friendly Format Not-an-Interface
853 .TE
855 .sp
856 .LP
857 \fB/sbin/ipmpstat\fR is not a Committed interface.
858 .SH SEE ALSO
859 .sp
860 .LP
861 \fBif_mpadm\fR(1M), \fBifconfig\fR(1M), \fBin.mpathd\fR(1M),
862 \fBattributes\fR(5)