source: rtems/doc/shell/network.t @ b422c549

4.115
Last change on this file since b422c549 was b422c549, checked in by Joel Sherrill <joel.sherrill@…>, on 09/18/14 at 13:57:03

doc/shell: Correct build issues from fc9f8f5085724622a189ba5d44ac116d7b27e27c

  • Property mode set to 100644
File size: 21.0 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2008.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5
6@chapter Network Commands
7
8@section Introduction
9
10The RTEMS shell has the following network commands:
11
12@itemize @bullet
13
14@item @code{netstats} - obtain network statistics
15@item @code{ifconfig} - configure a network interface
16@item @code{route} - show or manipulate the IP routing table
17@item @code{ping} - ping a host or IP address
18
19@end itemize
20
21@section Commands
22
23This section details the Network Commands available.  A
24subsection is dedicated to each of the commands and
25describes the behavior and configuration of that
26command as well as providing an example usage.
27
28@c
29@c
30@c
31@page
32@subsection netstats - obtain network statistics
33
34@pgindex netstats
35
36@subheading SYNOPSYS:
37
38@example
39netstats [-Aimfpcut]
40@end example
41
42@subheading DESCRIPTION:
43
44This command is used to display various types of network statistics.  The
45information displayed can be specified using command line arguments in
46various combinations.  The arguments are interpreted as follows:
47
48@table @b
49@item -A
50print All statistics
51
52@item -i
53print Inet Routes
54
55@item -m
56print MBUF Statistics
57
58@item -f
59print IF Statistics
60
61@item -p
62print IP Statistics
63
64@item -c
65print ICMP Statistics
66
67@item -u
68print UDP Statistics
69
70@item -t
71print TCP Statistics
72
73@end table
74
75@subheading EXIT STATUS:
76
77This command returns 0 on success and non-zero if an error is encountered.
78
79@subheading NOTES:
80
81NONE
82
83@subheading EXAMPLES:
84
85The following is an example of how to use @code{netstats}:
86
87The following is an example of using the @code{netstats}
88command to print the IP routing table:
89
90@smallexample
91[/] $ netstats -i
92Destination     Gateway/Mask/Hw    Flags     Refs     Use Expire Interface
93default         192.168.1.14       UGS         0        0      0 eth1
94192.168.1.0     255.255.255.0      U           0        0      1 eth1
95192.168.1.14    00:A0:C8:1C:EE:28  UHL         1        0   1219 eth1
96192.168.1.51    00:1D:7E:0C:D0:7C  UHL         0      840   1202 eth1
97192.168.1.151   00:1C:23:B2:0F:BB  UHL         1       23   1219 eth1
98@end smallexample
99
100The following is an example of using the @code{netstats}
101command to print the MBUF statistics:
102
103@smallexample
104[/] $ netstats -m
105************ MBUF STATISTICS ************
106mbufs:2048    clusters: 128    free:  63
107drops:   0       waits:   0  drains:   0
108      free:1967          data:79          header:2           socket:0
109       pcb:0           rtable:0           htable:0           atable:0
110    soname:0           soopts:0           ftable:0           rights:0
111    ifaddr:0          control:0          oobdata:0
112@end smallexample
113
114The following is an example of using the @code{netstats}
115command to print the print the interface statistics:
116
117@smallexample
118[/] $ netstats -f
119************ INTERFACE STATISTICS ************
120***** eth1 *****
121Ethernet Address: 00:04:9F:00:5B:21
122Address:192.168.1.244   Broadcast Address:192.168.1.255   Net mask:255.255.255.0
123Flags: Up Broadcast Running Active Multicast
124Send queue limit:50   length:1    Dropped:0
125      Rx Interrupts:889            Not First:0               Not Last:0
126              Giant:0              Non-octet:0
127            Bad CRC:0                Overrun:0              Collision:0
128      Tx Interrupts:867             Deferred:0         Late Collision:0
129   Retransmit Limit:0               Underrun:0             Misaligned:0
130@end smallexample
131
132The following is an example of using the @code{netstats}
133command to print the print IP statistics:
134
135@smallexample
136[/] $ netstats -p
137************ IP Statistics ************
138             total packets received         894
139  packets rcvd for unreachable dest          13
140 datagrams delivered to upper level         881
141    total ip packets generated here         871
142
143@end smallexample
144
145The following is an example of using the @code{netstats}
146command to print the ICMP statistics:
147
148@smallexample
149[/] $ netstats -c
150************ ICMP Statistics ************
151                        Type 0 sent         843
152                number of responses         843
153                    Type 8 received         843
154
155@end smallexample
156
157The following is an example of using the @code{netstats}
158command to print the UDP statistics:
159
160@smallexample
161[/] $ netstats -u
162************ UDP Statistics ************
163
164@end smallexample
165
166The following is an example of using the @code{netstats}
167command to print the TCP statistics:
168
169@smallexample
170[/] $ netstats -t
171************ TCP Statistics ************
172               connections accepted           1
173            connections established           1
174     segs where we tried to get rtt          34
175                 times we succeeded          35
176                  delayed acks sent           2
177                 total packets sent          37
178                  data packets sent          35
179                    data bytes sent        2618
180              ack-only packets sent           2
181             total packets received          47
182       packets received in sequence          12
183         bytes received in sequence         307
184                   rcvd ack packets          35
185           bytes acked by rcvd acks        2590
186      times hdr predict ok for acks          27
187 times hdr predict ok for data pkts          10
188@end smallexample
189
190@subheading CONFIGURATION:
191
192@findex CONFIGURE_SHELL_NO_COMMAND_NETSTATS
193@findex CONFIGURE_SHELL_COMMAND_NETSTATS
194
195This command is included in the default shell command set.
196When building a custom command set, define
197@code{CONFIGURE_SHELL_COMMAND_NETSTATS} to have this
198command included.
199
200This command can be excluded from the shell command set by
201defining @code{CONFIGURE_SHELL_NO_COMMAND_NETSTATS} when all
202shell commands have been configured.
203
204@subheading PROGRAMMING INFORMATION:
205
206@findex rtems_shell_rtems_main_netstats
207
208The @code{netstats} is implemented by a C language function
209which has the following prototype:
210
211@example
212int rtems_shell_rtems_main_netstats(
213  int    argc,
214  char **argv
215);
216@end example
217
218The configuration structure for the @code{netstats} has the
219following prototype:
220
221@example
222extern rtems_shell_cmd_t rtems_shell_NETSTATS_Command;
223@end example
224
225@c
226@c
227@c
228@page
229@subsection ifconfig - configure a network interface
230
231@pgindex ifconfig
232
233@subheading SYNOPSYS:
234
235@example
236ifconfig
237ifconfig interface
238ifconfig interface [up|down]
239ifconfig interface [netmask|pointtopoint|broadcast] IP
240
241@end example
242
243@subheading DESCRIPTION:
244
245This command may be used to display information about the
246network interfaces in the system or configure them.
247
248@subheading EXIT STATUS:
249
250This command returns 0 on success and non-zero if an error is encountered.
251
252@subheading NOTES:
253
254Just like its counterpart on GNU/Linux and BSD systems, this command
255is complicated.  More example usages would be a welcome submission.
256
257@subheading EXAMPLES:
258
259The following is an example of how to use @code{ifconfig}:
260
261@smallexample
262 ************ INTERFACE STATISTICS ************
263***** eth1 *****
264Ethernet Address: 00:04:9F:00:5B:21
265Address:192.168.1.244   Broadcast Address:192.168.1.255   Net mask:255.255.255.0
266Flags: Up Broadcast Running Active Multicast
267Send queue limit:50   length:1    Dropped:0
268      Rx Interrupts:5391           Not First:0               Not Last:0
269              Giant:0              Non-octet:0
270            Bad CRC:0                Overrun:0              Collision:0
271      Tx Interrupts:5256            Deferred:0         Late Collision:0
272   Retransmit Limit:0               Underrun:0             Misaligned:0
273@end smallexample
274
275@subheading CONFIGURATION:
276
277@findex CONFIGURE_SHELL_NO_COMMAND_IFCONFIG
278@findex CONFIGURE_SHELL_COMMAND_IFCONFIG
279
280This command is included in the default shell command set.
281When building a custom command set, define
282@code{CONFIGURE_SHELL_COMMAND_IFCONFIG} to have this
283command included.
284
285This command can be excluded from the shell command set by
286defining @code{CONFIGURE_SHELL_NO_COMMAND_IFCONFIG} when all
287shell commands have been configured.
288
289@subheading PROGRAMMING INFORMATION:
290
291@findex rtems_shell_rtems_main_ifconfig
292
293The @code{ifconfig} is implemented by a C language function
294which has the following prototype:
295
296@example
297int rtems_shell_rtems_main_ifconfig(
298  int    argc,
299  char **argv
300);
301@end example
302
303The configuration structure for the @code{ifconfig} has the
304following prototype:
305
306@example
307extern rtems_shell_cmd_t rtems_shell_IFCONFIG_Command;
308@end example
309
310@c
311@c
312@c
313@page
314@subsection route - show or manipulate the ip routing table
315
316@pgindex route
317
318@subheading SYNOPSYS:
319
320@example
321route [subcommand] [args]
322@end example
323
324@subheading DESCRIPTION:
325
326This command is used to display and manipulate the routing table.
327When invoked with no arguments, the current routing information is
328displayed.  When invoked with the subcommands @code{add} or @code{del},
329then additional arguments must be provided to describe the route.
330
331Command templates include the following:
332
333@smallexample
334route [add|del] -net IP_ADDRESS gw GATEWAY_ADDRESS [netmask MASK]
335route [add|del] -host IP_ADDRESS gw GATEWAY_ADDRES [netmask MASK]
336@end smallexample
337
338When not provided the netmask defaults to @code{255.255.255.0}
339
340@subheading EXIT STATUS:
341
342This command returns 0 on success and non-zero if an error is encountered.
343
344@subheading NOTES:
345
346Just like its counterpart on GNU/Linux and BSD systems, this command
347is complicated.  More example usages would be a welcome submission.
348
349@subheading EXAMPLES:
350
351The following is an example of how to use @code{route} to display,
352add, and delete a new route:
353
354@smallexample
355[/] $ route
356Destination     Gateway/Mask/Hw    Flags     Refs     Use Expire Interface
357default         192.168.1.14       UGS         0        0      0 eth1
358192.168.1.0     255.255.255.0      U           0        0      1 eth1
359192.168.1.14    00:A0:C8:1C:EE:28  UHL         1        0   1444 eth1
360192.168.1.51    00:1D:7E:0C:D0:7C  UHL         0    10844   1202 eth1
361192.168.1.151   00:1C:23:B2:0F:BB  UHL         2       37   1399 eth1
362[/] $  route add -net 192.168.3.0 gw 192.168.1.14
363[/] $ route
364Destination     Gateway/Mask/Hw    Flags     Refs     Use Expire Interface
365default         192.168.1.14       UGS         0        0      0 eth1
366192.168.1.0     255.255.255.0      U           0        0      1 eth1
367192.168.1.14    00:A0:C8:1C:EE:28  UHL         2        0   1498 eth1
368192.168.1.51    00:1D:7E:0C:D0:7C  UHL         0    14937   1202 eth1
369192.168.1.151   00:1C:23:B2:0F:BB  UHL         2       96   1399 eth1
370192.168.3.0     192.168.1.14       UGS         0        0      0 eth1
371[/] $ route del -net 192.168.3.0 gw 192.168.1.14
372[/] $ route
373Destination     Gateway/Mask/Hw    Flags     Refs     Use Expire Interface
374default         192.168.1.14       UGS         0        0      0 eth1
375192.168.1.0     255.255.255.0      U           0        0      1 eth1
376192.168.1.14    00:A0:C8:1C:EE:28  UHL         1        0   1498 eth1
377192.168.1.51    00:1D:7E:0C:D0:7C  UHL         0    15945   1202 eth1
378192.168.1.151   00:1C:23:B2:0F:BB  UHL         2      117   1399 eth1
379@end smallexample
380
381@subheading CONFIGURATION:
382
383@findex CONFIGURE_SHELL_NO_COMMAND_ROUTE
384@findex CONFIGURE_SHELL_COMMAND_ROUTE
385
386This command is included in the default shell command set.
387When building a custom command set, define
388@code{CONFIGURE_SHELL_COMMAND_ROUTE} to have this
389command included.
390
391This command can be excluded from the shell command set by
392defining @code{CONFIGURE_SHELL_NO_COMMAND_ROUTE} when all
393shell commands have been configured.
394
395@subheading PROGRAMMING INFORMATION:
396
397@findex rtems_shell_rtems_main_route
398
399The @code{route} is implemented by a C language function
400which has the following prototype:
401
402@example
403int rtems_shell_rtems_main_route(
404  int    argc,
405  char **argv
406);
407@end example
408
409The configuration structure for the @code{route} has the
410following prototype:
411
412@example
413extern rtems_shell_cmd_t rtems_shell_ROUTE_Command;
414@end example
415
416@c
417@c
418@c
419@page
420@subsection ping - ping a host or IP address
421
422@pgindex ping
423
424@subheading SYNOPSYS:
425
426@example
427ping [-AaDdfnoQqRrv] [-c count] [-G sweepmaxsize] [-g sweepminsize]
428     [-h sweepincrsize] [-i wait] [-l preload] [-M mask | time] [-m ttl]
429     [-p pattern] [-S src_addr] [-s packetsize] [-t timeout]
430     [-W waittime] [-z tos] host
431ping [-AaDdfLnoQqRrv] [-c count] [-I iface] [-i wait] [-l preload]
432     [-M mask | time] [-m ttl] [-p pattern] [-S src_addr]
433     [-s packetsize] [-T ttl] [-t timeout] [-W waittime]
434     [-z tos] mcast-group
435@end example
436
437@subheading DESCRIPTION:
438
439The ping utility uses the ICMP protocol's mandatory ECHO_REQUEST
440datagram to elicit an ICMP ECHO_RESPONSE from a host or gateway.
441ECHO_REQUEST datagrams (``pings'') have an IP and ICMP header,
442followed by a ``struct timeval'' and then an arbitrary number of
443``pad'' bytes used to fill out the packet.  The options are as
444follows:
445
446@table @b
447@item -A
448Audible.  Output a bell (ASCII 0x07) character when no packet is
449received before the next packet is transmitted.  To cater for
450round-trip times that are longer than the interval between
451transmissions, further missing packets cause a bell only if the
452maximum number of unreceived packets has increased.
453
454@item -a
455Audible.  Include a bell (ASCII 0x07) character in the output when any
456packet is received.  This option is ignored if other format options
457are present.
458
459@item -c count
460Stop after sending (and receiving) count ECHO_RESPONSE packets.  If
461this option is not specified, ping will operate until interrupted.  If
462this option is specified in conjunction with ping sweeps, each sweep
463will consist of count packets.
464
465@item -D
466Set the Don't Fragment bit.
467
468@item -d
469Set the SO_DEBUG option on the socket being used.
470
471@item -f
472Flood ping.  Outputs packets as fast as they come back or one
473hundred times per second, whichever is more.  For every ECHO_REQUEST
474sent a period ``.'' is printed, while for every ECHO_REPLY received a
475backspace is printed.  This provides a rapid display of how many
476packets are being dropped.  Only the super-user may use this option.
477This can be very hard on a network and should be used with caution.
478
479@item -G sweepmaxsize
480Specify the maximum size of ICMP payload when sending sweeping pings.
481This option is required for ping sweeps.
482
483@item -g sweepminsize
484Specify the size of ICMP payload to start with when sending sweeping
485pings.  The default value is 0.
486
487@item -h sweepincrsize
488Specify the number of bytes to increment the size of ICMP payload
489after each sweep when sending sweeping pings.  The default value is 1.
490
491@item -I iface
492Source multicast packets with the given interface address.  This flag
493only applies if the ping destination is a multicast address.
494
495@item -i wait
496Wait wait seconds between sending each packet.  The default is to wait
497for one second between each packet.  The wait time may be fractional,
498but only the super-user may specify values less than 1 second.  This
499option is incompatible with the -f option.
500
501@item -L
502Suppress loopback of multicast packets.  This flag only applies if the
503ping destination is a multicast address.
504
505@item -l preload
506If preload is specified, ping sends that many packets as fast as
507possible before falling into its normal mode of behavior.  Only the
508super-user may use this option.
509
510@item -M mask | time
511Use ICMP_MASKREQ or ICMP_TSTAMP instead of ICMP_ECHO.  For mask, print
512the netmask of the remote machine.  Set the net.inet.icmp.maskrepl MIB
513variable to enable ICMP_MASKREPLY.  For time, print the origination,
514reception and transmission timestamps.
515
516@item -m ttl
517Set the IP Time To Live for outgoing packets.  If not specified, the
518kernel uses the value of the net.inet.ip.ttl MIB variable.
519
520@item -n
521Numeric output only.  No attempt will be made to lookup symbolic names
522for host addresses.
523
524@item -o
525Exit successfully after receiving one reply packet.
526
527@item -p pattern
528You may specify up to 16 ``pad'' bytes to fill out the packet you
529send.  This is useful for diagnosing data-dependent problems in a
530network.  For example, ``-p ff'' will cause the sent packet to be
531filled with all ones.
532
533@item -Q
534Somewhat quiet output.  Don't display ICMP error messages that are in
535response to our query messages.  Originally, the -v flag was required
536to display such errors, but -v displays all ICMP error messages.  On a
537busy machine, this output can be overbear- ing.  Without the -Q flag,
538ping prints out any ICMP error mes- sages caused by its own
539ECHO_REQUEST messages.
540
541@item -q
542Quiet output.  Nothing is displayed except the summary lines at
543startup time and when finished.
544
545@item -R
546Record route.  Includes the RECORD_ROUTE option in the ECHO_REQUEST
547packet and displays the route buffer on returned packets.  Note that
548the IP header is only large enough for nine such routes; the
549traceroute(8) command is usually better at determining the route
550packets take to a particular destination.  If more routes come back
551than should, such as due to an illegal spoofed packet, ping will print
552the route list and then truncate it at the correct spot.  Many hosts
553ignore or discard the RECORD_ROUTE option.
554
555@item -r
556Bypass the normal routing tables and send directly to a host on an
557attached network.  If the host is not on a directly-attached network,
558an error is returned.  This option can be used to ping a local host
559through an interface that has no route through it (e.g., after the
560interface was dropped).
561
562@item -S src_addr
563Use the following IP address as the source address in outgoing
564packets.  On hosts with more than one IP address, this option can be
565used to force the source address to be something other than the IP
566address of the interface the probe packet is sent on.  If the IP
567address is not one of this machine's interface addresses, an error is
568returned and nothing is sent.
569
570@item -s packetsize
571Specify the number of data bytes to be sent.  The default is 56, which
572translates into 64 ICMP data bytes when combined with the 8 bytes of
573ICMP header data.  Only the super-user may specify val- ues more than
574default.  This option cannot be used with ping sweeps.
575
576@item -T ttl
577Set the IP Time To Live for multicasted packets.  This flag only
578applies if the ping destination is a multicast address.
579
580@item -t timeout
581Specify a timeout, in seconds, before ping exits regardless of how
582many packets have been received.
583
584@item -v
585Verbose output.  ICMP packets other than ECHO_RESPONSE that are
586received are listed.
587
588@item -W waittime
589Time in milliseconds to wait for a reply for each packet sent.  If a
590reply arrives later, the packet is not printed as replied, but
591considered as replied when calculating statistics.
592
593@item -z tos
594Use the specified type of service.
595
596@end table
597
598@subheading EXIT STATUS:
599The ping utility exits with one of the following values:
600
6010    At least one response was heard from the specified host.
602
6032    The transmission was successful but no responses were
604     received.
605
606any other value an error occurred.  These values are defined in
607<sysexits.h>.
608
609@subheading NOTES:
610
611When using ping for fault isolation, it should first be run on the
612local host, to verify that the local network interface is up and
613running.  Then, hosts and gateways further and further away should be
614``pinged''.  Round-trip times and packet loss statistics are computed.
615If duplicate packets are received, they are not included in the packet
616loss calculation, although the round trip time of these packets is
617used in calculating the round-trip time statistics.  When the
618specified number of packets have been sent a brief summary is
619displayed, showing the number of packets sent and received, and the
620minimum, mean, maximum, and standard deviation of the round-trip
621times.
622
623This program is intended for use in network testing, measurement and
624management.  Because of the load it can impose on the network, it is
625unwise to use ping during normal operations or from automated scripts.
626
627@subheading EXAMPLES:
628
629The following is an example of how to use @code{oing} to ping:
630
631@smallexample
632[/] # ping 10.10.10.1
633PING 10.10.10.1 (10.10.10.1): 56 data bytes
63464 bytes from 10.10.10.1: icmp_seq=0 ttl=63 time=0.356 ms
63564 bytes from 10.10.10.1: icmp_seq=1 ttl=63 time=0.229 ms
63664 bytes from 10.10.10.1: icmp_seq=2 ttl=63 time=0.233 ms
63764 bytes from 10.10.10.1: icmp_seq=3 ttl=63 time=0.235 ms
63864 bytes from 10.10.10.1: icmp_seq=4 ttl=63 time=0.229 ms
639
640--- 10.10.10.1 ping statistics ---
6415 packets transmitted, 5 packets received, 0.0% packet loss
642round-trip min/avg/max/stddev = 0.229/0.256/0.356/0.050 ms
643[/] # ping -f -c 10000  10.10.10.1
644PING 10.10.10.1 (10.10.10.1): 56 data bytes
645.
646--- 10.10.10.1 ping statistics ---
64710000 packets transmitted, 10000 packets received, 0.0% packet loss
648round-trip min/avg/max/stddev = 0.154/0.225/0.533/0.027 ms
649@end smallexample
650
651@subheading CONFIGURATION:
652
653@findex CONFIGURE_SHELL_NO_COMMAND_PING
654@findex CONFIGURE_SHELL_COMMAND_PING
655
656This command is included in the default shell command set.
657When building a custom command set, define
658@code{CONFIGURE_SHELL_COMMAND_PING} to have this
659command included.
660
661This command can be excluded from the shell command set by
662defining @code{CONFIGURE_SHELL_NO_COMMAND_PING} when all
663shell commands have been configured.
664
665@subheading PROGRAMMING INFORMATION:
666
667@findex rtems_shell_rtems_main_ping
668
669The @code{ping} is implemented by a C language function
670which has the following prototype:
671
672@example
673int rtems_shell_rtems_main_ping(
674  int    argc,
675  char **argv
676);
677@end example
678
679The configuration structure for the @code{ping} has the
680following prototype:
681
682@example
683extern rtems_shell_cmd_t rtems_shell_PING_Command;
684@end example
685
Note: See TracBrowser for help on using the repository browser.