1 System Administration Commands ipmpstat(1M)
2
3 NAME
4 ipmpstat - display IPMP subsystem status
5
6 SYNOPSIS
7
8 ipmpstat [-n] [-o _field_ [-P]] -a|-g|-i|-p|-t
9
10 DESCRIPTION
11
12 The *ipmpstat* command concisely displays information about
13 the IPMP subsystem. It supports five different output
14 modes, each of which provides a different view of the IPMP
15 subsystem (address, group, interface, probe, and target),
16 described below. At most one output mode may be specified
17 per invocation, and the displayed information is guaranteed
18 to be self-consistent. It also provides a parsable output
19 format which may be used by scripts to examine the state of
20 the IPMP subsystem. Only basic privileges are needed to
21 invoke ipmpstat, with the exception of probe mode which
22 requires all privileges.
23
24 OPTIONS
25
26 -a
27
28 Display IPMP data address information ("address"
29 output mode).
30
31 -g
32
33 Display IPMP group information ("group" output mode).
34
35 -i
36
37 Display IP interface information ("interface" output
38 mode).
39
40 -n
41
42 Display IP addresses numerically, rather than
43 attempting to resolve them to hostnames. This option
44 may be used in any output mode.
45
46
47 -o _field_[,...]
48
49 Display only the specified output fields, in order.
50 The list of field names is case-insensitive and
51 comma-separated. The field names that are supported
52 depend on the selected output mode, described below.
53 The special field name "all" may be used to print all
54 fields for a given output mode.
55
56 -p
57
58 Display IPMP probe information ("probe" output mode).
59
60 -t
61
62 Display IPMP target information ("target" output mode).
63
64 -P
65
66 Display using a machine-parsable format, described
67 below. If this option is specified, an explicit list
68 of fields must be specified using the *-o* option.
69
70
71 OUTPUT MODES
72
73 Address Mode
74
75 Address mode displays the state of all IPMP data
76 addresses on the system. The following output fields are
77 supported:
78
79 ADDRESS The hostname (or IP address) associated with
80 the information. Note that because duplicate
81 down addresses may exist, the address must be
82 taken together with the GROUP to form a
83 unique identity. For a given IPMP group, if
84 duplicate addresses exist, at most one will
85 be displayed, and an up address will always
86 take precedence.
87
88 STATE The state of the address. Either *up* if the
89 address is IFF_UP (see ifconfig(1M)), or
90 *down* if the address is not IFF_UP.
91
92 GROUP The IPMP IP interface hosting the address.
93
94 INBOUND The underlying IP interface that will receive
95 packets for this address. This may change in
96 response to external events such as IP
97 interface failure. If this field is empty,
98 then the system will not accept IP packets
99 sent to this address (e.g., because the
100 address is down or because there are no
101 active IP interfaces left in the IPMP group).
102
103 OUTBOUND The underlying IP interfaces that will send
104 packets using this source address. This may
105 change in response to external events such as
106 IP interface failure. If this field is
107 empty, then the system will not send packets
108 with this address as a source (e.g., because
109 the address is down or because there are no
110 active IP interfaces left in the IPMP group).
111
112 If *-o* is not specified, all output fields are displayed.
113
114 Group Mode
115
116 Group mode displays the state of all IPMP groups on the
117 system. The following output fields are supported:
118
119 GROUP The IPMP IP interface name associated with
120 the information. For the anonymous group
121 (see *in.mpathd(1M)*), this field will be
122 empty.
123
124 GROUPNAME The IPMP group name. For the anonymous
125 group, this field will be empty.
126
127 STATE The state of the group:
128
129 *ok* All interfaces in the group are
130 usable.
131 *degraded* Some (but not all) interfaces in
132 the group are usable.
133 *failed* No interfaces in the group are
134 usable.
135
136 FDT The probe-based failure detection time. If
137 probe-based failure detection is disabled,
138 this field will be empty.
139
140 INTERFACES The list of underlying IP interfaces in the
141 group. The list is divided into three parts:
142
143 1. Active interfaces are listed first and not
144 enclosed in any brackets or parenthesis.
145 Active interfaces are those being used by
146 the system to send or receive data traffic.
147
148 2. *INACTIVE* interfaces are listed next and
149 enclosed in parenthesis. *INACTIVE*
150 interfaces are those that are functioning,
151 but not being used according to
152 administrative policy.
153
154 3. Unusable interfaces are listed last and
155 enclosed in brackets. Unusable interfaces
156 are those that cannot be used at all in
157 their present configuration (e.g.,
158 *FAILED* or *OFFLINE*).
159
160 If *-o* is not specified, all output fields are displayed.
161
162 Interface Mode
163
164 Interface mode displays the state of all IP interfaces
165 that are tracked by *in.mpathd* on the system. The
166 following output fields are supported:
167
168 INTERFACE The IP interface name associated with the
169 information.
170
171 ACTIVE Either *yes* or *no*, depending on if the IP
172 interface is being used by the system for
173 IP data traffic.
174
175 GROUP The IPMP IP interface associated with the IP
176 interface. For IP interfaces in the
177 anonymous group (see *in.mpathd(1M)*), this
178 field will be empty.
179
180 FLAGS Assorted information about the IP interface:
181
182 i Unusable due to being *INACTIVE*.
183
184 s Marked *STANDBY*.
185
186 m Nominated to send/receive IPv4 multicast
187 for its IPMP group.
188
189 b Nominated to receive IPv4 broadcast for
190 its IPMP group.
191
192 M Nominated to send/receive IPv6 multicast
193 for its IPMP group.
194
195 d Unusable due to being *down*.
196
197 h Unusable due to being brought *OFFLINE* by
198 *in.mpathd* because of a duplicate
199 hardware address
200
201 LINK The state of link-based failure detection:
202
203 *up* The link is up.
204
205 *down* The link is down.
206
207 *unknown* The network driver does not
208 detect link state changes.
209
210 PROBE The state of probe-based failure detection:
211
212 *ok* Probes detect no problems.
213
214 *failed* Probes detect failure.
215
216 *unknown* Probes cannot be sent since no
217 suitable probe targets are known.
218
219 *disabled* Probes have been disabled because
220 a unique IP test address has not
221 been configured.
222
223 STATE The overall state of the interface:
224
225 *ok* The interface is online and
226 functioning properly based on the
227 configured failure detection
228 methods.
229
230 *failed* The interface is online but has a
231 link state of *down* or a probe
232 state of *failed*.
233
234 *offline* The interface is offline.
235
236 *unknown* The interface is online but may
237 or may not be functioning because
238 the configured failure detection
239 methods are in *unknown* states.
240
241 If *-o* is not specified, all output fields are displayed.
242
243 Probe Mode
244
245 Probe mode displays information about the probes being
246 sent by *in.mpathd*. Unlike other output modes, this
247 mode runs until explicitly terminated using *^C*. The
248 following output fields are supported:
249
250 TIME The time the probe was sent, relative to when
251 *ipmpstat* was started. If the probe was
252 sent prior to starting *ipmpstat*, the time
253 will be negative.
254
255 PROBE An identifier representing the probe. The
256 identifier will start at zero and will
257 monotonically increment for each probe sent
258 by *in.mpathd* over a given interface. To
259 enable more detailed analysis by packet
260 monitoring tools, this identifier matches the
261 *icmp_seq* field of the ICMP probe packet.
262
263 INTERFACE The IP interface the probe was sent on.
264
265 TARGET The hostname (or IP address) of the target
266 the probe was sent to.
267
268 NETRTT The network round-trip-time for the probe.
269 This is the time between when the IP module
270 sends the probe and when the IP module
271 receives the ack. If *in.mpathd* has
272 concluded that the probe has been lost, this
273 field will be empty.
274
275 RTT The total round-trip-time for the probe.
276 This is the time between when *in.mpathd*
277 starts executing the code to send the probe,
278 and when it completes processing the ack. If
279 *in.mpathd* has concluded that the probe has
280 been lost, this field will be empty. Spikes
281 in the total round-trip time that are not
282 present in the network round-trip time
283 indicate that the local system itself is
284 overloaded.
285
286 RTTAVG The average round-trip-time to *TARGET* over
287 *INTERFACE*. This aids identification of
288 slow targets. If there is insufficient data
289 to calculate the average, this field will be
290 empty.
291
292 RTTDEV The standard deviation for the
293 round-trip-time to *TARGET* over *INTERFACE*.
294 This aids identification of jittery targets.
295 If there is insufficient data to calculate
296 the standard deviation, this field will be
297 empty.
298
299 If *-o* is not specified, all fields except for *RTTAVG*
300 and *RTTDEV* are displayed.
301
302 Target Mode
303
304 Target mode displays IPMP probe target information. The
305 following output fields are supported:
306
307 INTERFACE The IP interface name associated with the
308 information.
309
310 MODE The probe target discovery mode:
311
312 *routes* Probe targets found via the
313 routing table.
314
315 *multicast* Probe targets found via multicast
316 ICMP probes.
317
318 *disabled* Probe-based failure detection is
319 disabled.
320
321 TESTADDR The hostname (or IP address) that will be
322 used for sending and receiving probes. If a
323 unique test address has not been configured,
324 this field will be empty. Note that if an IP
325 interface is configured with both IPv4 and
326 IPv6 test addresses, probe target information
327 will be displayed separately for each test
328 address.
329
330 TARGETS A space-separated list of probe target
331 hostnames (or IP addresses), in firing order.
332 If no probe targets could be found, this
333 field will be empty.
334
335 If *-o* is not specified, all output fields are displayed.
336
337 OUTPUT FORMAT
338
339 By default, ipmpstat uses a human-friendly tabular format
340 for its output modes, where each row contains one or more
341 fields of information about a given object, which is in turn
342 uniquely identified by one or more of those fields. In this
343 format, a header identifying the fields is displayed above
344 the table (and after each screenful of information), fields
345 are separated by whitespace, empty fields are represented by
346 *--*, and other visual aids are used.
347
348 Machine-parsable format also uses a tabular format, but is
349 designed to be efficient to programmatically parse.
350 Specifically, machine-parsable format differs from
351 human-friendly format in the following ways:
352
353 * No headers are displayed.
354
355 * Fields with empty values yield no output, rather than
356 *--*.
357
358 * Fields are separated by a single *:*, rather than
359 variable amounts of whitespace.
360
361 * If multiple fields are requested, and a literal *:* or
362 *\* occur in a field's value, they are escaped by
363 prefixing them with *\*.
364
365 EXAMPLES
366
367 Use the machine-parsable output format to create a *ksh*
368 function that outputs the failure detection time of a given
369 IPMP IP interface:
370
371 getfdt() {
372 ipmpstat -gP -o group,fdt | while IFS=: read group fdt; do
373 [[ "$group" = "$1" ]] && { echo "$fdt"; return; }
374 done
375 }
376
377 ATTRIBUTES
378
379 See attributes(5) for descriptions of the following
380 attributes:
381
382 /usr/sbin
383
384 ____________________________________________________________
385 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
386 |_____________________________|_____________________________|
387 | Availability | SUNWcsu |
388 |_____________________________|_____________________________|
389 | Interface Stability | Committed |
390 |_____________________________|_____________________________|
391 | Machine-Parsable Format | Committed |
392 |_____________________________|_____________________________|
393 | Human-Friendly Format | Not-an-Interface |
394 |_____________________________|_____________________________|
395
396
397 SEE ALSO
398
399 in.mpathd(1M), ifconfig(1M), if_mpadm(1M)