SOCKETSPY

NAME

socketspy — a tool to examine the contents of data streaming between two systems over socket ports.  

SYNOPSIS

socketspy [-h <input host>] [-p <input port>] [-o <output port>] [-f <frequency>] [-mb <max bytes>] [-1] [-pt] [-flag <byte>] [-asc|-noasc] [-bin|-nobin] [-hex|-nohex] [-4uint|-no4uint] [-4float|-no4float] [-8double|-no8double] [-swapendian]  

DESCRIPTION

The socketspy program is a tool for determining network protocols between devices and software over socket ports. It works as a man-in-the-middle interceptor that outputs data to a terminal or a file while at the same time passing data back and forth between server and client — to allow them to continue to operate.

Data traffic is directional, and so each line of information is preceded with a "From Server:" or "From Client:" if it originated from the server or client, respectively. This is then followed by the number of bytes that are reported on that line.

The default representation of the data is in one byte (two-digit) hexadecimal numbers. By default, after 16 values are printed a new line is begun.

Values for which the high bit is set (0x80 - 0xff) are highlighted in red. This can sometimes make it easier to see patterns in the data. In addition, one other value can be specified as the "flag" value, and it will be highlighted in green. If one knows or has a guess as to what value might always indicate the beginning of a packet, then flagging this byte can make it easier to notice the size of the packets.

There are a number of interactive commands that can be given via live keyboard input to help parse the data as it streams. In particular, if there is an obvious stride to the data, then adjusting the number of bytes per line (the frequency value) can be used to match the stride and view packets more naturally. In addition, the beginning of the line can be (phase) shifted one byte left or right to attempt to line up the beginning of regularly sized packets with the left-most column.

There are three types of information that can be displayed for each byte: the hexadecimal value, the ASCII value and the binary representation. By default socketspy will display only the hexadecimal values. What is displayed can be adjusted both by command-line-arguments, as well as interactively with the keyboard.

Several of the socketspy options can be adjusted live, while data is streaming. These options can then be used to effectively modify the representation of the stream and make it easier to decipher what is going on. The interactive commands are:

        'q' - quit
        '?' - print help information for the interactive keys
        '+' - increase the frequency
        '-' - decrease the frequency
        '>' - shift the phase to the right
        '<' - shift the phase to the left
        '0' - print remaining bytes in buffer
                (essentially a big phase shift left)
        'a' - toggle ASCII output display
        'b' - toggle binary output display
        'h' - toggle hex output display
        'u' - toggle unsigned integer display
        'f' - toggle 4-byte floating point display
        'd' - toggle 8-byte floating point (double) display
        's' - toggle between (swap) small and big endian for numerical encoding
        (backspace) - go into passthru mode
                (from which there currently is no return).

The program is terminated by pressing the 'q' or interrupt key (usually ^C). (When in pass-thru mode, the 'q' method will not work.)

Other tools that can be helpful for use along-side socketspy are netstat and ss. The netstat -nlup operation informs what UDP ports are currently open, and what programs are using them. Likewise, changing the 'u' option to 't' will report on TCP sockets:

% netstat -nlup % netstat -nltp

OPTIONS

-h <input host>

The -h option sets the value of the server or device host waiting to send data to a client.

-p <input port>

The -p option sets the port number the server is listening for new client connections on.

-o <output port>

The -o option sets the port on which socketspy listens for clients to connect to it, and whose data socketspy will pass on to the actual server or device while printing the communications to the terminal. NOTE: there is no equivalent <output host> as the machine on which socketspy is running is the host.

-f <frequency>

The -f option sets the "frequency" of the output, which is to say the number of values that will be displayed on each line. The default value is 16. This value can be interactively changed with the '+' and '-' keys.

-mb <max bytes>

The -mb option sets a maximum number of bytes that socketspy will process before ending operation. This allows one to have the program quit fairly early before pages and pages of data stream by, with perhaps the most interesting data (the initial interrogation) scrolling past the buffer and being lost. By default this feature is disabled, and assigning any negative value will serve to disable this feature.

-1

The -1 option sets the one-time flag that will do only one read from the device or server, process that data and then quit. Thus, however much data is ingested during the first read is all that will be processed.

-pt

The -pt option puts socketspy directly into pass-thru mode. Pass-thru mode signifies that socketspy will NOT b reading the keyboard and thus not allowing interactive changes to the data stream display.

NOTE: this feature is actually not all that useful for socketspy and is thus a remnant feature of serialspy. We will consider removing it from future versions.

-flag <byte>

The -flag option allows one byte value to be set as a value to highlight as the data streams by. This can be useful if one knows (or guesses) what value might be included in all packet headers and thus can see a marker that is associated with the beginning of each packet. By default no byte value will be flagged.

NOTE: the value is specified as a decimal number [0..255], but will be echoed back as a hexadecimal number.

-asc or -noasc

The -asc/-noasc options enable/disable the output of ASCII representation of each byte. The ASCII representation is off by default.

-bin or -nobin

The -bin/-nobin options enable/disable the output of binary representation of each byte. The binary representation is off by default.

-hex or -nohex

The -hex/-nohex options enable/disable the output of hexadecimal representation of each byte. The hexadecimal representation is on by default.

-4uint or -no4uint

The -4uint/-no4uint options enable/disable the output of unsigned 4-byte integers. The numeric representations will be on 4-byte alignment. The unsigned-integer representation is off by default.

-4float or -no4float

The -4float/-no4float options enable/disable the output of 4-byte floating point numbers. The numeric representations will be on 4-byte alignment. The 4-byte floating point representation is off by default.

-8double or -no8double

The -8double/-no8double options enable/disable the output of 8-byte floating point (double) numbers. The numeric representations will be on 8-byte alignment. The 8-byte floating point representation is off by default.

-swapendian

The -swapendian option changes the endianness of the printed data. Whether the data becomes big-endian or little-endian is determined by the incoming ordering. The data is streamed through unchanged. This option only affects how 4-byte and 8-byte numbers are output.

CAVEATS

Please note that the socketspy tool cannot be used to intercept network traffic for applications that the user does not have the authority to view. The client application must be specifically set to listen to the port to which socketspy is streaming.

NOTE also that the present settings of the default values are for viewing data from the Vrui VRDeviceDaemon (incoming on port 8555, and outgoing on port 8556 all on the localhost).  

EXAMPLES

Listen in on the communications between a VRPN server on the localhost listening on the default VRPN port (3883), and then outputting the data on port 6000 (which means the actual VRPN client must be told to connect to the server on port 6000).

% socketspy -p 3883 -o 6000

BUGS

socketspy should do a clean exit when an interrupt signal (or others) is received.

We need to figure out how to disable shell processing of keyboard keys, so hitting ^M sends a 0x0d rather than a 0x0a.

Consider removing the "-pt" (pass-thru) option, since that was designed for serialspy to allow one to type characters that would otherwise be gobbled up by the interactive interface.  

SEE ALSO

serialspy(1fv), freevr(7fv), netstat(8), ss(8)  

LOCATION

The source code for socketspy is in the "socketspy.c" file, which includes the vr_socket.c source.  

COPYRIGHT

Copyright 2024, Bill Sherman, All rights reserved.

Index

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

CAVEATS

EXAMPLES

BUGS

SEE ALSO

LOCATION

COPYRIGHT