This document describes how to use NicheTool, InterNiche Technologies' customer-extendible diagnostic suite for debugging, monitoring, and runtime configuration of the TCP/IP stack and applications. NicheTool:
The NicheTool is a command line driven interface and requires that the InterNiche TCP/IP stack software be installed and operational in order to function properly.
This section describes the various line commands and is organized into two of utility: General commands and Diagnostic commands. Note that there is a third category of menus available, though they are application-specific and are included only if you have licensed and included the additional protocols from InterNiche as a part of your system.
When the stack executable is run, it initializes and presents the INET> prompt on the system console. The line commands can be displayed as Help menu lists or simply entered directly at the prompt. The device on which this prompt is displayed is determined by the porting engineer and will vary depending on the nature of the target system. For purpose of this discussion we will refer to this user interface input/output device as the target system's "console".
Commands are available when the option IN_MENUS is defined in the file ipport.h . It is recommended that this define be disabled for shipping product as it presents a possible security hole, increases memory requirements and has not necessarily been subjected to the level reentrancy checking appropriate for a commercial product.
The InterNiche user interface prompts the user with the following prompt:
INET>_
At this point the user can type any of dozens of commands for execution by the agent. Our command interface is a "smart" interface and only requires that you enter enough of the command name to uniquely identify it. Many commands can also take 1 or more parameters typed on the command line.
As an introduction to these commands, an annotated session transcript is reproduced here. Some commonly used commands are host
and ping
.
INET> host 10.0.0.5
The host command sets a default remote host IP address for those commands that require a remote host to be specified.
INET> ping ping 0 to 10.0.0.5: ping 1 sent… got ping reply; len:62 seq 0 from 10.0.0.5
The ping command checks if a host is reachable or not.
INET> ping INET> quit
Note: In most environments, this will terminate the stack and application execution.
The Help menu for the InterNiche console displays a list of available commands. The commands can be brought up on the display by entering help or a question mark, ?. The help command by itself displays the general commands. When given diagnostic as an argument, it lists the diagnostic command set.
The "Also try" line at the bottom of the Help menu lists the other InterNiche modules that are installed and for which diagnostic help is available.
Command
help
Syntax
help [submenu]
Parameters
general | Displays the most commonly used commands |
diagnostic | Displays commands that are used for reporting statistics |
module_name | The remaining parameters in the help list will vary according to which options were included in your build. |
Description
This command is used to list all the other commands. When typed by itself, the general commands are listed. When followed by diagnostic or a specific configuration name the appropriate command sets are listed. Similarly, help snmp
would display the commands for SNMP.
A question mark, '?' is the same as help.
Parameters can be abbreviated to as few as a single letter when the meaning is unambiguous.
Command
state
- show current setup
Parameters
None
Description
Displays current state information, interfaces, and default settings.
Example
INET> state iface 0- IP addr:10.0.0.53 subnet:255.0.0.0 gateway:10.0.0.1 current tick count 10372370 Task wakeups:netmain: 51156 nettick: 5185540 keyboard: 5185496
Command
quit
- quit station program
Parameters
None
Description
quit
will cause the application to do a clean exit of the stack and application to the OS, bootloader, or underlying monitor.
Example
INET> quit c:\> _
Command
version
- display version information
Parameters
None
Description
Displays current version of the InterNiche TCP/IP stack.
Example
INET> version InterNiche NicheLite TCP/IP for Coldfire, v3.0 INET> _
When IN_MENUS is defined in ipport.h, the Diagnostic Command menu is available and the list will vary according to what other options have been defined in the file ipport.h for inclusion. If NET_STATS is defined, NicheTool will have the ability to display certain statistics.
Command
help diagnostic
Parameters
diagnostic
Description
Used as a parameter for Help, this command displays a list of the diagnostic commands that return current statistical data concerning the features included in your build.
Example
INET> ? diag SNMP Station: diagnostic commands: arps - display ARP stats and table buffers - display free q buffer stats queues - dump packet buffer queues dbytes - dump block of memory debug - set IP stack debug tracing dtrap - try to hook debugger dir - directory of VFS files iface - display net interface stats linkstats - display link layer specific stats memory - list currently alloced memory tcp - display TCP stats sockets - display socket list tbconn - tcp BSD connection stats tbsend - tcp BSD send stats tbrcv - tcp BSD receive stats allocsize - set size for alloc() breakpoint ipstat - display IP layer stats icmpstat - display ICMP layer stats udp - display UDP layer stats upcall - trace received packets tkstats - tasking system status dcstats - DHCP Client statistics users - list all users adduser - add a new user
Command
buffers
- display allocated packet buffer statistics
Parameters
None
Description
Shows statistics for the allocated buffers.
Example
INET> buffers PACKET len buffer que data offset 0 8100112c,1536,81001188,big:00 00 ff ff ff ff ff ff 00 48 54 8e .........HT. 810017a8,1536,81001804,big:00 00 ff ff ff ff ff ff 00 0d 60 78 ..........`x 81001e24,1536,81001e80,big:00 00 ff ff ff ff ff ff 00 a0 cc e0 ............ 810024a0,1536,810024fc,big:00 00 ff ff ff ff ff ff 00 a0 cc e0 ............ 81002b1c,1536,81002b78,big:00 00 ff ff ff ff ff ff 00 0c 6e 6c ..........nl 81003198,1536,810031f4,big:00 00 ff ff ff ff ff ff 00 10 75 00 ..........u. 81003814,1536,81003870,big:00 00 ff ff ff ff ff ff 00 a0 cc e0 ............ 81003e90,1536,81003eec,big:00 00 ff ff ff ff ff ff 00 a0 cc e0 ............ 8100450c, 128,81004568,lil:00 00 ff ff ff ff ff ff 00 14 2a 05 ..........*. 81004608, 128,81004664,lil:00 00 ff ff ff ff ff ff 00 11 5b 4b ..........[K 81004704, 128,81004760,lil:00 00 ff ff ff ff ff ff 00 11 11 be ............ 81004800, 128,8100485c,lil:00 00 00 0f 66 92 2c ff 00 50 c2 48 ....f.,..P.H 810048fc, 128,81004958,lil:00 00 ff ff ff ff ff ff 00 50 c2 48 .........P.H 810049f8, 128,81004a54,lil:00 00 00 50 c2 48 5a 86 00 0f 66 92 ...P.HZ...f. 81004af4, 128,81004b50,lil:00 00 00 50 c2 48 5a 86 00 0f 66 92 ...P.HZ...f. 81004bf0, 128,81004c4c,lil:00 00 ff ff ff ff ff ff 00 0e 35 1f ..........5. 81004cec, 128,81004d48,lil:00 00 00 50 c2 48 5a 86 00 0f 66 92 ...P.HZ...f. 81004de8, 128,81004e44,lil:00 00 00 0f 66 92 2c ff 00 50 c2 48 ....f.,..P.H 81004ee4, 128,81004f40,lil:00 00 ff ff ff ff ff ff 00 11 5b 4b ..........[K ....press any key for more (ESC to break).... INET> _
Command
queues
- dump packet buffer queues
Parameters
None
Description
The first two lines provide tally information about the big and little packet buffer free queues. The len field gives an instantaneous snapshot of how many packet buffers of each type are in the queues. The min field shows how low len
has gotten, indicating whether or not the application is running out of packet buffers. When min
is 0 it means that the stack has run out of packet buffers in the listed queue type at least once since the stack was initialized.
The line about rcvdq is telling you how big the packet receive queue has gotten. rcvdq len tells you that you have packets in the receive queue that have not yet been processed by the IP layer. rcvdq max lets you know how high len has gotten to be since boot time. A high value in rcvdq max would be an indication that the stack isn't getting around to processing the receive queue in a timely manner.
Example
INET> queue bigfreeq: head:8100112c, tail:81003e90, len:8, min:3, max:8 lilfreeq: head:81004704, tail:81004608, len:12, min:4, max:12 rcvdq: head:0, tail:0, len:0, min:0, max:8 INET> _
Command
dbytes
- dump block of memory
Parameters
location [length]
Description
This command helps in debugging.
The location
parameter us a single 32 bit number that indicates the address.
Example
INET> dbytes enter memory location in hex, followed by optional length. INET> dbytes 0x0 100 18 f0 9f e5 18 f0 9f e5 18 f0 9f e5 18 f0 9f e5 ................ 18 f0 9f e5 00 00 a0 e1 f0 ff 1f e5 18 f0 9f e5 ................ 40 00 00 80 10 6a 01 80 0c 6a 01 80 08 6a 01 80 @....j...j...j.. 04 6a 01 80 00 00 00 00 00 6a 01 80 20 ca 00 80 .j.......j.. ... b0 00 9f e5 aa 10 a0 e3 55 20 a0 e3 24 30 a0 e3 ........U ..$0.. 04 30 80 e5 01 30 a0 e3 00 30 80 e5 0c 10 80 e5 .0...0...0...... 0c 20 80 e5 08 30 90 e5 01 3b 13 e2 fc ff ff 0a . ...0...;...... 03 30 a0 e3 00 30 80 e5 0c 10 80 e5 0c 20 80 e5 .0...0....... .. 74 00 9f e5 04 10 a0 e3 04 10 80 e5 02 10 a0 e3 t............... 00 10 80 e5 64 00 9f e5 db f0 21 e3 00 d0 a0 e1 ....d.....!..... 04 00 40 e2 d7 f0 21 e3 00 d0 a0 e1 04 00 40 e2 ..@...!.......@. d1 f0 21 e3 00 d0 a0 e1 04 00 40 e2 d2 f0 21 e3 ..!.......@...!. 00 d0 a0 e1 80 00 40 e2 d3 f0 21 e3 00 d0 a0 e1 ......@...!..... 04 00 40 e2 10 f0 21 e3 00 d0 a0 e1 20 00 9f e5 ..@...!..... ... 01 00 10 e3 1c e0 9f 05 1c e0 9f 15 10 ff 2f e1 ............../. fe ff ff ea fe e7 c0 46 80 c0 1f e0 00 c0 1f e0 .......F........ INET> _
Command
debug
- set IP stack debug tracing
Parameters
[bitmask]
Description
This diagnostic command sets an internal flag which results in the application printing out scores of status messages as packets are received or sent up and down the protocol stack. This can be helpful for detecting at exactly what protocol stack layer a bad packet's error occurs. Often the nature of the error will be reported, i.e. "bad cksum".
The debug command accepts an optional parameter, which is a hex number that represents a bit mask in which each bit specifies whether a particular type of IP stack tracing will occur. Below are the definitions of the various bits:
BUGHALT | 0x01 | halt on a gross applications level error that is detected in the network code |
DUMP | 0x02 | Works in conjunction with other options: BUGHALT - Dump all arriving packets PROTERR - Dump header for level of error NETTRACE, etc. - Dump headers at trace level |
INFOMSG | 0x04 | Print general informational messages |
NETERR | 0x08 | Display net interface error messages |
PROTERR | 0x10 | Display protocol level error messages |
NETRACE | 0x20 | Trace packet in link level net layer |
TMO | 0x40 | Print message on timeout |
APTRACE | 0x80 | Trace packet through application |
TPTRACE | 0x100 | Transport protocol (UDP/TCP/RVD) trace |
IPTRACE | 0x200 | Trace packet in internet layer |
UPCTRACE | 0x400 | Trace upcall progress - DANGEROUS! |
Example
INET> debug IP stack debug tracing on INET> debug IP stack debug tracing off INET> _
See Also
upcall
- Debug tracing will not occur on packets being processed in ISR context unless both these options are enabled.
Command
dtrap
- try to hook debugger
Parameters
None
Description
dtrap
causes a call to the porting engineer provided dtrap() function to occur.
Example
INET> dtrap ??? INET> _
Command
dump
- hexdump incoming packets
Parameters
None
Description
This dumps the SNMP protocol portion of all packets received and sent. It ignores other protocols such as ARP and PING.
Example
INET> dump Packet hex dumping enabled INET> INET> host 10.0.0.1 active host number set to 10.0.0.1 INET> dump Packet hex dumping enabled INET> dump Packet hex dumping disabled INET> _
Known Issues
With some Ethernet drivers this can hang the system after a received packet is dumped. It is reliable when used on the loopback driver.
Command
linkstats
- display link layer specific statistics
Parameters
An optional interface number
Description
This command displays statistics for the hardware associated with the given interface. The format, content, and accuracy of these statistics will vary from link driver to link driver. This command differs from the iface command in that these counters are generally read from the hardware driver, and are maintained since the driver was installed, not since the station started as is the case with the iface counters. Exceptions to this principle are the upcalls, pkts dropped, and pktdrvq.
In general, packet counts should be obtained from the iface command, since those counters are well defined (by MIB-2) and are uniform across all devices.
Example
INET> linkstats Interrups: rx:51245, tx:552 alloc:551, total:10377516 coll1:0 collx:0 overrun:526 Sendq max:2, current 0. IObase: 0x82000300 ISR 0 Tx Status: 0x0081 TxENA: On Pad:On Rx Status: 0x0300 RxENA: On CTR: 0x1af0 Int MSK: 0xf3 Status:0x0c Tx Alloc, Tx FIFO empty, INET> _
See Also
iface
Command
allocsize
- set size for alloc() breakpoint
Parameters
Number of bytes to be allocated
Description
The stack code expects the porting engineer to provide an implementation of a function called npalloc() that the stack uses for memory allocation. npalloc() take a single parameter which specifies the number of bytes to be allocated by the call.
Notes
This capability may not be implemented in all ports.
Example
INET> allocsize 128 malloc trap size set to 128 INET> _
Command
upcall
- trace received packets
Parameters
None
Description
Enables protocol stack trace reporting on incoming packets. upcall toggles the UPCTRACE bit in the tracing bit mask that is affected by the debug command. Its just a shorthand way of setting this one particular bit.
Example
INET> upcall Upcall debugging enabled INET> _
See Also
debug
NET_STATS must be defined in ipport.h for the features in this section to be available.
Command
arps
- display ARP statistics and table
Parameters
None
Description
The ARP command displays some arp
statistics and dumps data from the entries in the current ARP table. The most interesting fields are the MAC address and the associated IP address. The entry "X)
" field is the position in the ARP table of this entry. Entries are allocated last first, so this compile has 8 ARP entries (0-7). iface
is the logical interface the arp was resolved on. pend
indicates whether the stack is holding an outgoing packet awaiting the results of an arp reply. It will almost always be N
for "no". The time
is the internal timestamp when the ARP reply was last referenced. This is kept so that if we run out of room in the ARP table, we can delete the entry that has not been used for the longest time.
This command is included in the menu list if NET_STATS was defined in ipport.h.
Example
INET> host 10.0.0.80 active host number set to 192.9.200.3 INET> p ping 0 to 10.0.0.80: Arping for host... got ping reply; len :62 seq 0 from 192.9.200.3 ping complete; send 1, received 1 INET> arp arp Requests In: 75, out: 28 arp Replys In: 8, out: 75 X) MAC Address iface pend IP ctime ltime 7) 0080C8-E2AF2A 1 N 10.0.0.80 4669168 4670448 INET> _
Command
ipstat
- display IP layer statistics
Parameters
None
Description
ipstat
displays the standard IP SNMP MIB statistics.
This command is included in the menu list if NET_STATS was defined in ipport.h.
Example
INET> ipstat IP MIB statistics: Gateway: NO default TTL: 30 rcv: total: 39002 header err: 0 address err: 0 rcv: unknown Protocols: 0 delivered: 39002 send: total: 2360 discarded: 0 No routes: 0 Routing; forwarded: 0 discarded: 0 Recvd fragments: 0, Frames reassembled: 0 Pkts fragmented: 0, Fragments sent: 0, dropped: 0 Reasm.Timeouts: 0, Reasm.Errors: 0 INET> _
Command
icmpstat
- display ICMP layer statisticsParameters
None
Description
icmpstat
displays the standard ICMP SNMP MIB statistics
This command is included in the menu list if NET_STATS was defined in ipport.h.
Example
INET> icmpstat ICMP layer stats: icmpInMsgs 1 icmpInErrors 0 In counters: DestUnreach 0 TimeExceed 0 ParmProb 0 SrcQuench 0 Redirect 0 Echo(ping) 0 EchoReps 1 Timestmp 0 TStmpRep 0 AddrMasks 0 AddrMaskRep 0 icmpOutMsgs 2 icmpOutErrors 0 Out counts: DestUnreach 2 TimeExceed 0 ParmProb 0 SrcQuench 0 Redirect 0 Echo(ping) 0 EchoReps 0 Timestmp 0 TStmpRep 0 AddrMasks 0 AddrMaskRep 0 INET> _
Command
udp
- display UDP layer statistics
Parameters
None
Description
The udp
command displays the standard UDP SNMP MIB statistics.
This command is included in the menu list if NET_STATS was defined in ipport.h.
Example
INET> udp UDP MIB dump: In: Good: 26 No Port: 2 Bad: 0 Out: 26 INET> _
DNS_CLIENT and NET_STATS must be defined in ipport.h for the features in this section to be available.
Command
dnsstats
- display DNS setup and statistics
Parameters
None
Description
This command shows statistics about the DNS Client. It shows a list of DNS servers that the client is configured to know about, a listing of the client side DNS cache which is a kind of a history of DNS resolutions that the client has performed, and some general DNS statistics.
This command is included in the menu list if DNS_CLIENT and NET_STATS was defined in ipport.h.
Example
INET> dnsstats DNS servers:0.0.0.0 0.0.0.0 0.0.0.0 DNS cache: name: , IP: 0.0.0.0, retry:0, ID:0, rcode:0, err:0 name: , IP: 0.0.0.0, retry:0, ID:0, rcode:0, err:0 name: , IP: 0.0.0.0, retry:0, ID:0, rcode:0, err:0 name: , IP: 0.0.0.0, retry:0, ID:0, rcode:0, err:0 name: , IP: 0.0.0.0, retry:0, ID:0, rcode:0, err:0 name: , IP: 0.0.0.0, retry:0, ID:0, rcode:0, err:0 protocol/implementation runtime errors:0 requests sent:0 replys received:0 usable replys:0 total reties:0 timeouts:0 INET> _
Both INCLUDE_TCP and NET_STATS must be defined in ipport.h for the commands in this section to be available.
Command
tcp
- display TCP statisticsParameters
None
Description
Displays the standard TCP SNMP MIB statistics.
This command is included in the menu list if INCLUDE_TCP and NET_STATS was defined in ipport.h.
Example
INET> tcp tcpRtoAlgorithm 0, tcpRtoMin 0 tcpRtoMax 0, tcpMaxConn 0 tcpActiveOpens 11, tcpPassiveOpens 6 tcpAttemptFails 0, tcpEstabResets 3 tcpCurrEstab 0, tcpInSegs 2344 tcpOutSegs 2567, tcpRetransSegs 16 tcpInErrs 0, tcpOutRsts 0 INET> _
Command
memory
- list currently allocated memory
Parameters
None
Example
INET> memory free list: 0: at 8100513c, 0x3aec8 bytes heap; start: 262132, min: 241168, current: 241352; actual: 241352 alloc faile d: 0 wrappers: allocs: 1437, frees: 1390, allocbytes: 236244 freebytes: 216840 alloced: current bytes: 19404 max bytes: 19560 biggest block: 2048, allocs failed: 0 Block sizes, in size[alloc - free = cur] format: 40[3-0=3] 2048[2-0=2] 60[20-0=20] 1541[8-0=8] 133[12-0=12] 32[2-0=2] 156[1403-1403=0] INET> _
Description
Dumps address and size of all allocated but un-freed memory since the application started. This is useful in detecting memory leaks during ports on the InterNiche SNMP API when no other such tools are available.
This command is included in the menu list if MEM_BLOCKS was defined in ipport.h.