This is a very powerful and useful command that should be part of every voice engineer's toolbelt. It allows you to perform an immediate network capture ("sniffer", packet capture, etc.) of traffic as it is hitting the Unified Communications server. It also includes configurable filters to limit the information that is captured to ensure you see only what you want!
For example, having trouble with NTP synchronization on your publisher to an external time source? How about SDL Link OOS between nodes in your cluster? Want to see what traffic you are receiving from an unknown network device? There are literally an endless number of uses for this tool to assist with your troubleshooting. Read below for syntax examples.
utils network capture eth0 : captures IP packets on the specified Ethernet interface
utils network capture eth0 [page] [numeric] [file fname] [count num] [size bytes] [src addr] [dest addr] [host prot addr] [port num]
- eth0 : command executed on traffic seen on this interface
- page : output one page at a time
- numeric : display hosts as IP addresses
- file fname : send output to a file, platform/cli/fname.cap. More information on how to retrieve trace capture files.
- count num : limits the output to a maximum of characters, screen maximum is 1000 & file maximum is 10,000
- size bytes : limits the output to a maximum of bytes, screen maximum is 128 & file maximum is any value or ALL
- src addr : limits capture from a specific source IP address
- dest addr : limits capture to a specific destination IP address
- host prot addr : limits capture to traffic to and from a specific host. Options for prot [IP | arp | rarp | all ], and addr should be in IPv4 or hostname format. If host is used, src or dest should not be provided.
- port num : limits capture to a specific port number (either source or destination port). More information about the ports typically used by CUCM.
Note the additional options above to alter these commands even further.
Example #1: NTP synchronization
utils network capture eth0 port 123 : This command dumps to the screen all NTP (UDP port 123) traffic seen hitting interface eth0 on the Unified Communications server. It would make most sense to run this command on the publisher of the cluster.
Example #2: SDL Link OOS
utils network capture eth0 port 8002 page : This command dumps to the screen all SDL (TCP port 8002) traffic seen hitting interface eth0 on the Unified Communications server. The output is paused after each page. If you ever receive one of these errors, CCM_CALLMANAGER-CALLMANAGER-3-SDLLinkOOS or CCM_CALLMANAGER-CALLMANAGER-3-SDLLinkAppProtocol you may find yourself wanting to know what (if any) traffic is reaching your Unified Communications server. SDL traffic is full mesh between all members of the cluster, so in larger clusters expect to receive more with this command.
Example #3: Traffic from an Unknown Network Device
utils network capture eth0 file rogue size 300000 src 10.100.1.2 : This command dumps to a file (platform/cli/rogue.cap) all traffic received on interface eth0 from the network device having the IPv4 address of 10.100.1.2. The file size will be limited to 300,000 bytes. More information on how to retrieve trace capture files.
Example #4: SIP Phone
Example #4: SIP Phone
utils network capture eth0 port 5060 host ip 10.100.1.50 : This command dumps to the screen all SIP (UDP port 5060) traffic seen between the interface eth0 on the Unified Communications server and the device using IP address 10.100.1.50. In this case, the IP address provided could be that of a SIP phone.
As you can see above, there are many different ways that this command can be used. Submit your examples and thoughts as comments below - we would love to see them!
See the example output below for an example of what you could receive with the commands shown above. The voice engineer was investigating TCP Port 389, which is acommonly used port for LDAP. The actual output you will receive (and it's readability) will vary depending on the options specified in the trace.
admin:utils network capture port 389
Executing command with options:
size=128 count=1000 interface=eth0
src= dest= port=389
19:50:33.251722 IP cucm7pub.52678 > 10.101.1.9.ldap: S
332011513:332011513(0) win 5840 <mss 1460,sackOK,timestamp 53692015
19:50:33.258213 IP 10.101.1.9.ldap > cucm7pub.52678: S
3972356909:3972356909(0) ack 332011514 win 64240 <mss 1460,nop,wscale
0,nop,nop,timestamp 0 0,nop,nop,sackOK>
19:50:33.258299 IP cucm7pub.52678 > 10.101.1.9.ldap: . ack 1 win 1460
<nop,nop,timestamp 53692018 0>
19:50:33.266567 IP cucm7pub.52678 > 10.101.1.9.ldap: P 1:15(14) ack 1
win 1460 <nop,nop,timestamp 53692033 0>
19:50:33.267490 IP 10.101.1.9.ldap > cucm7pub.52678: P 1:23(22) ack
15 win 64226 <nop,nop,timestamp 254075 53692033>
19:50:33.267613 IP cucm7pub.52678 > 10.101.1.9.ldap: . ack 23 win
1460 <nop,nop,timestamp 53692035 254075>
19:50:33.269813 IP cucm7pub.52678 > 10.101.1.9.ldap: P 15:60(45) ack
23 win 1460 <nop,nop,timestamp 53692036 254075>
19:50:33.291480 IP 10.101.1.9.ldap > cucm7pub.52678: P 23:45(22) ack
60 win 64181 <nop,nop,timestamp 254076 53692036>
19:50:33.307339 IP cucm7pub.52678 > 10.101.1.9.ldap: P 60:183(123)
ack 45 win 1460 <nop,nop,timestamp 53692074 254076>
Using Wireshark to View Captures
Thanks to Tim Smith (@TimHughSmith) for this suggestion!
Wireshark works well to display network captures in a more readable format once you have retrieved them from the Unified Communications server. This can be done via SFTP from the CLI or using the RTMT application.
- utils network connectivity : verifies the servers network connection to the first node in the cluster
- utils network arp : displays, changes, or deletes address resolution protocol (ARP) table entries
- utils network host : resolves a hostname to an address or vice versa
- utils network ping : pings another server or device on the network
- utils network tracert : traces IP packets sent to a remote destination