A packet_monitor command macro

Blue Bar separator

The packet_monitor command is used to trace IP network traffic. Typically you do not want to display the packets to a terminal screen since that slows slow the collection process and increases the likelihood that packets will be dropped. You also of course don't have a permanent record when output goes to your terminal. This command macro pm creates an out file, sets implicating locking and starts packet_monitor as a started process sending the output to the just created file. It also sets my favorite arguments -numeric -time_stamp -verbose. If you need to set a filter you can add a filter string - note that you do not need to prefix that string with the -filter argument. If you do add a filter string the macro will also add filters for ARP and ICMP. I recommend that you also provide an interface so that packet_monitor only traces that specific interface (or starting in 15.1.2ah a specific set of interfaces (stcp-2193)).

Do not forget to stop the pm process when you are done. I once left a trace running for over 2 years. Luckily the trace was filtering for packets that didn't occur too often but still have 2 years the disk was filling up. Luckily it was stopped before there was a significant problem. Of course this does demonstrate how long a VOS module can remain operational.

Note packet_monitor can use a large amount of streams memory; if you are experiencing streams memory problems don't run packet_monitor.

Also note that running packet_monitor can create performance problems because each packet has to be copied and there are more locking issues etc.

Finally, if you are trying to capture a specific event it may be necssary to let the packet_monitor process run for an extended period of time. This will create a very large file. One solution is to let the cycle_output_files macro start this macro. The cycle_output_files macro will watch output file and when it grows too large it will stop the process and restart it using a different output_path. You will end up with many (you decide how many) smaller (you decide on an approximate max size)output_fliles instead of one large file.

Some examples:

No specific filter but a specific interface

                                                                                    
pm #sdlmuxA.m15.10.3
ready  20:02:12

A simple filter capturing all UDP packets

                                                                                    
pm #sdlmuxA.m15.10.3 -protocol udp
ready  20:02:29

Capturing UDP packets from all interfaces - note the * in place of the interface name. Actually any single character can be used.

                                                                                    
pm * -protocol udp
ready  20:02:59

Capturing packets from (or to) two different hosts

                                                                                    
pm #sdlmuxA.m15.10.3 -host 10.10.1.27 -filter -host 10.10.1.26
ready  20:03:16

The above four commands created 4 output files.

ls pm*out

Files: 4, Blocks: 229
                                                                                    
w         72 pm.06-07-27.20:02:12.out
w         92 pm.06-07-27.20:02:29.out
w         46 pm.06-07-27.20:02:59.out
w         19 pm.06-07-27.20:03:16.out

I have found that it is usually a good idea to always look for ARP and ICMP packets when doing a trace. For example, while tracing a connection attempt with a host filter packet_monitor reports no outgoing packets. But when you include a ARP filter you see that the system is sending ARP requests which are not getting answered. Or with just the host filter you see the packet go out but nothing come back. When you add the icmp protocol filter you see that a router is returning a time exceeded error. However if you want to turn off these filters you can use the -no_arp and no_icmp arguments.

I have also found myself editing the macro to remove the hex_dump option so it is now an argument as well. If you want to see the data leave it as yes, it all you care about are the headers you can cycle it to no.

Version 1.4 has added the all_headers control argument. If set to yes (the default) it will cause packet_monitor to print out the Ethernet header and also the IP header as a hex dump. This output was added so that the pm2text2pcap perl script can parse the output to create a file which can be further processed by the wireshark text2pcap command. The resulting pcap file can then be read by wireshark or any protocol analyzer that accepts a pcap file.

Version 1.5 added the output_path and process_name arguments. They default to the values that were used in previous version and were added so that cycle_output_files could be used to call the pm macro and control the output file size.

-------------------------------------- pm ------------------------------------  
 interface:
 -arp:          yes
 -icmp:         yes
 -hex:          yes
 -all_headers:  yes
 -output_path:  pm.(date).(time).out
 -process_name: pm
 options:

pm.cm

                                                                   
& pm begins here                                                                
&
& pm.cm
& version 1.0 06-06-06
& version 1.1 06-07-18 added arp and ICMP arguments
& version 1.2 07-01-30 changed so that a hex_dump is control by an
&                      argument instead of always doing a hex_dump
& version 1.3 07-03-22 added code to dump the first few lines of the
&                      outfile to confirm that packet_monitoring is
&                      running correctly. Also sanity check the interface
&                      string. If is > 1 character it has to start with a #
& version 1.4 07-10-18 added all_headers switch to control adding the
&                      pkt_hdr and hex_header switches to the packet_monitor
&                      command.
& version 1.5 08-04-10 Added the ability to specify the output file and
&                      process names. This is needed so that the macro
&                      can be started by the cycle_output_files macro.
& version 1.6 10-11-26 Added disclaimer
&
& Noah Davids Stratus CAC noah.davids@stratus.com
&
& This software is provided on an "AS IS" basis, WITHOUT ANY WARRANTY OR ANY
& SUPPORT OF ANY KIND. The AUTHOR SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTIES
& OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE.  This disclaimer
& applies, despite any verbal representations of any kind provided by the
& author or anyone else.
&
&begin_parameters
INTERFACE interface:string
ARP       switch(-arp),=1
ICMP      switch(-icmp),=1
HEX       switch(-hex),=1
ALL_HEADERS switch(-all_headers),=1
OUTPUT_PATH option(-output_path),string='pm.(date).(time).out'
PROCESS_NAME option(-process_name),string='pm'
ARGS      options:unclaimed
&end_parameters

&if (length &INTERFACE&) > 1
&then &do
      &if X(substr &INTERFACE& 1 1)Y ^= X#Y
      &then &do
            display_line &INTERFACE&  is not an interface name.
            display_line packet_monitor not started.
            display_line
            &goto endnow
      &end
      &set_string CMD (string &+
          (master_disk)>system>stcp>command_library>packet_monitor &+
          -interface &INTERFACE& -numeric -time_stamp -verbose)
&end     
&else &set_string CMD (string &+
   (master_disk)>system>stcp>command_library>packet_monitor &+
   -numeric -time_stamp -verbose)
&
&if &ALL_HEADERS&
&then &set_string CMD (string &CMD& -pkt_hdr -hex_header)
&
&if &HEX&
&then &set_string CMD (string &CMD& -hex_dump -length 1500)
&
&if (length &ARGS&) > 1
&then &set_string CMD (string &CMD& -filter &ARGS&)
&
&if &ARP&
&then &set_string CMD (string &CMD& -filter -arp)
&
&if &ICMP&
&then &set_string CMD (string &CMD& -filter -protocol ICMP)
&
display_line &CMD&
create_file &OUTPUT_PATH&
set_implicit_locking &OUTPUT_PATH&
start_process (string &CMD&) -process_name &PROCESS_NAME& &+
    -output_path &OUTPUT_PATH& -privileged
&
sleep -seconds 5
display &OUTPUT_PATH& -last_line 6
&
&label endnow
&
& pm ends here



Blue Bar separator
This page was last modified on 10-11-26
mailbox Send comments and suggestions
to ndav1@cox.net