pdb.tex

The Packet Debugger, pdb is a program which allows people to work with packet streams as if they we

commands that allow you to inspect and move through a \class{Stream}.

\subsubsection{info}
\label{sec:cmd-info}

Get information on all the streams currently loaded into
\program{pdb}.  The stream displayed in Figure~\ref{fig:info-example}
has no breakpoints, was loaded from one of our standard test files,
\file{tests/test.out}, has no filter set, and contains 63 packets.  We
are currently at the first packet, position 0, in the stream.  The
\verb|Type| is not yet supported.  The stream is an ISO Layer 2
stream, with a \verb|Datalink| type of Ethernet, which has a 14 byte
offset between the link layer header and the next protocol.

\begin{figure}[h]
  \centering
\begin{verbatim}
Stream 0
---------
Breakpoints []
File tests/test.out
Filter 
Number of packets: 63
Current Position: 0
Type
Layer: 2
Datalink: 1     Offset: 14
\end{verbatim}
  \caption{Getting info on a \class{Stream}}
  \label{fig:info-example}
\end{figure}


\subsubsection{print}
\label{sec:cmd-print}

The \verb|print| command is used to show a single packet, either the
current packet or another one in the same stream.

\begin{figure}[h]
  \centering
\begin{verbatim}
0: <Ethernet: src: '\x00\r\x022{\x9c', dst: '\xff\xff\xff\xff\xff\xff', type: 2054>
  <ARP: spa: 3538819329L, tpa: 3538819566L, hln: 6, pro: 2048, 
        sha: '\x00\r\x022{\x9c', pln: 4, hrd: 1, 
        tha: '\x00\x00\x00\x00\x00\x00', op: 1>
\end{verbatim}
  \caption{print command}
  \label{fig:print-example}
\end{figure}

Figure~\ref{fig:print-example} shows the first, 0th, packet in one our
supplied test files, \file{test.out}.  Packet 0 is an Ethernet frame
containing an ARP request.  

The \verb|print| command gives a concise example of how packets are
displayed by \program{pdb}.  Packets are displayed from the lowest
available layer, upwards towards the highest available layer, as
viewed using the ISO standard for networking.  Ethernet is the lowest
layer we have captured, and the only other data we have is the ARP
packet placed, logically speaking, on top of it.  Each layer is
displayed on its own line.

With in each packet the fields are given somewhat human readable
names, that is, if the human is acquainted with network protocols.
Most of \program{pdb} assumes that the user has at least a passing
understanding of networking and the ability to look up information
about packet formats and field names on their own.

\subsubsection{list}
\label{sec:cmd-list}

The \verb|list| command shows a subset of the packets in a stream.
The number of packets shown is controlled by the \verb|list_length|
setting, see Section~\ref{sec:cmd-set}, which defaults to 10.

\begin{figure}[h]
  \centering
\begin{verbatim}
pdb> list
0: <Ethernet: src: '\x00\r\x022{\x9c', dst: '\xff\xff\xff\xff\xff\xff', type: 2054>
  <ARP: spa: 3538819329L, tpa: 3538819566L, hln: 6, pro: 2048, sha: '\x00\r\x022{\x9c', pln: 4, hrd: 1, tha: '\x00\x00\x00\x00\x00\x00', op: 1>

1: <Ethernet: src: '\x00\r\x022{\x9c', dst: '\xff\xff\xff\xff\xff\xff', type: 2054>
  <ARP: spa: 3538819329L, tpa: 3538819566L, hln: 6, pro: 2048, sha: '\x00\r\x022{\x9c', pln: 4, hrd: 1, tha: '\x00\x00\x00\x00\x00\x00', op: 1>

2: <Ethernet: src: '\x00\x17\xf2\xe8\x9a*', dst: '\x00\r\x022{\x9c', type: 2048>  <IPv4: hlen: 5, protocol: 6, src: 167844872, tos: 0, dst: 1074628338, ttl: 64, length: 105, version: 4, flags: 2, offset: 0, checksum: 47703, id: 37679>
  <TCP: reset: 6, reserved: 0, sequence: 3630104920L, ack: 1, checksum: 1430, offset: 8, syn: 12, urgent: 0, window: 65535, push: 3, ack_number: 4015249839L, dport: 993, sport: 49616, fin: 0, urg_pointer: 0>
  <Data: payload: 13461827120112604152439673499521091613012183756744016516126079577203641068557009167112742657168772916671786032510888690444211521996639179562876754643964994L>
\end{verbatim}
  \caption{The list command}
  \label{fig:list-example}
\end{figure}

In Figure~\ref{fig:list-example} we see a subset of the packets
printed by the \verb|list| command.  Each packet is represented just
as it is with the \verb|print| command, explained in
Section~\ref{sec:cmd-print}.

\subsubsection{next}
\label{sec:cmd-next}

To move within a \class{Stream} there are two commands provided, the
\verb|next| command moves you forward, while the \verb|prev| command,
Section~\ref{sec:cmd-prev} moves you backwards.  An optional numeric
argument can be given to move more than 1 packet at a time.  As we see
in Figure~\ref{fig:next-example} each time you use the \verb|next|
command the packet you have jumped to is printed for you, to let you
know where you are.

\begin{figure}[h]
  \centering
\begin{verbatim}
pdb> print
1: <Ethernet: src: '\x00\r\x022{\x9c', dst: '\xff\xff\xff\xff\xff\xff', type: 2054>
  <ARP: spa: 3538819329L, tpa: 3538819566L, hln: 6, pro: 2048, sha: '\x00\r\x022{\x9c', pln: 4, hrd: 1, tha: '\x00\x00\x00\x00\x00\x00', op: 1>
pdb> next
2: <Ethernet: src: '\x00\x17\xf2\xe8\x9a*', dst: '\x00\r\x022{\x9c', type: 2048>  <IPv4: hlen: 5, protocol: 6, src: 167844872, tos: 0, dst: 1074628338, ttl: 64, length: 105, version: 4, flags: 2, offset: 0, checksum: 47703, id: 37679>
  <TCP: reset: 6, reserved: 0, sequence: 3630104920L, ack: 1, checksum: 1430, offset: 8, syn: 12, urgent: 0, window: 65535, push: 3, ack_number: 4015249839L, dport: 993, sport: 49616, fin: 0, urg_pointer: 0>
  <Data: payload: 13461827120112604152439673499521091613012183756744016516126079577203641068557009167112742657168772916671786032510888690444211521996639179562876754643964994L>
\end{verbatim}
  \caption{The next command}
  \label{fig:next-example}
\end{figure}

We were originally at packet number 1, shown by the \verb|print|
command, and then after the \verb|next| command we are at packet
number 2.  Attempts to jump past the end or beginning of the stream
are reported as errors, and no change is made to your position in the
\class{Stream}.

\subsubsection{prev}
\label{sec:cmd-prev}

To move within a \class{Stream} there are two commands provided, the
\verb|prev| command moves you backwards, while the \verb|next|
command, Section~\ref{sec:cmd-next} moves you forwards.  An optional
numeric argument can be given to move more than 1 packet at a time.
Please refer to Section~\ref{sec:cmd-next} for more information.

\subsection{Running a Stream}
\label{sec:running-a-stream}

Once a stream is loaded or captured you may want to replay the stream
on an interface.  In almost all cases playing raw packets back on an
interface requires special privileges, usually those associated with
the \verb|root| user.  On modern Unix systems (FreeBSD, NetBSD,
OpenBSD, MacOS X, Linux, Solaris, etc.) the best way to gain this
privilege is via the \program{sudo} command.  If you do not understand
what was just explained here, please stop, and find someone to explain
it to you.

\subsubsection{run}
\label{sec:cmd-run}

The \verb|run| command is used to play a stream of packets on an
interface.  To use a network interface it must be specified when
\program{pdb} is started, see Section~\ref{sec:debugger-options}, and
at the moment the network interface used for output must match the
type of interface on which the packets were captured.  A stream of
packets captured on an Ethernet interface \emph{must} be run on an
Ethernet interface and a stream of packets captures on the localhost,
\verb|lo0|, interface \emph{must} be played back on the localhost
interface.

There is no output from the \verb|run| command to the CLI.  When
playback is complete the command line returns, as seen in
Figure~\ref{fig:run-example}.

\begin{figure}[h]
  \centering
\begin{verbatim}
pdb> run
pdb> 
\end{verbatim}
  \caption{The run command}
  \label{fig:run-example}
\end{figure}

\subsubsection{break}
\label{sec:cmd-break}

One of the main features of any debugger is to be able to stop a
program at a specific point in its execution.  Such a point is called
a break point and the \verb|break| command is used to set a break point
in a \class{Stream}.  Since \program{pdb} works with streams of
packets, and not lines of source code, the breakpoints are set on
packets, and not source code lines.

The \verb|break| command sets a break point at a particular packet so
that when the stream is \verb|run|, \program{pdb} will send packets up
to the break point, and then stop, returning control to the user at the
command line.

In Figure\ref{fig:break-example} we have set a break point at packet
number 5, and then run the stream using the \verb|run| command.  Just
before \program{pdb} is about to transmit packet number 5 it stops,
and returns control to the user.  The user can now inspect the packet,
wait for an event in their program, or do something else with
\program{pdb}.

\begin{figure}[h]
  \centering
\begin{verbatim}
pdb> break 5
pdb> run
Breakpoint at packet 5
5: <Ethernet: src: '\x00\x17\xf2\xe8\x9a*', dst: '\x00\r\x022{\x9c', type: 2048>  <IPv4: hlen: 5, protocol: 6, src: 167844872, tos: 0, dst: 1074628338, ttl: 64, length: 105, version: 4, flags: 2, offset: 0, checksum: 47701, id: 37681>
  <TCP: reset: 6, reserved: 0, sequence: 3630104973L, ack: 1, checksum: 26250, offset: 8, syn: 12, urgent: 0, window: 65535, push: 3, ack_number: 4015250212L, dport: 993, sport: 49616, fin: 0, urg_pointer: 0>
  <Data: payload: 13461827120112604152452570919187006348413092860400229175355376392182072120959206906515573156649336185430464894616649205210961904103139353088699445406157443L>
pdb> 
\end{verbatim}
  \caption{The break command}
  \label{fig:break-example}
\end{figure}

\subsubsection{continue}
\label{sec:cmd-continue}

When \program{pdb} reaches a break point, see
Section~\ref{sec:cmd-break}, it halts transmitting the packet stream.
If the user were to give the \verb|run| command again \program{pdb}
would start transmitting packets from the 0th packet and then reach
the same break point again.  The \verb|continue| command continues
transmitting packets from the stream from the current point, the one
it reached when it hit the break point.  With the \verb|continue|
command it is possible to set and reach several breakpoints and to
then move consistently through the packet stream.

\subsection{Working with Packets}
\label{sec:working-with-packets}

In the previous sections we were working with streams of packets, but
not with individual packets themselves.

\subsubsection{send}
\label{sec:cmd-send}

The \verb|send| command is used to send a single packet from the
current stream.  When used without any arguments it sends the packet
at the current position.  With a numeric argument it sends the packet
at the numbered index in the stream.  No output is shown in the CLI
when this command is used.

\subsubsection{delete}
\label{sec:cmd-delete}

The \verb|delete| command is used to remove a packet from the packet
stream.  When used without any arguments it deletes the packet at the
current position.  With a numeric argument deletes the packet at the
numbered index in the stream.  No output is shown in the CLI when this
command is used.

\subsection{Debugger Options}
\label{sec:debugger-options}

Various options may be globally set for the packet debugger.  The
\verb|show| and \verb|set| commands allow the user to see the options
and to modify them.

\subsubsection{show}
\label{sec:cmd-show}

The \verb|show| command lists the values of all the possible packet
debugger options.  Currently there are only two options,
\verb|list_length| and \verb|layer|.  The \verb|list_length| option
controls how many packets are displayed when the user invokes the
\verb|list| command, See Section~\ref{sec:cmd-list}.  

\begin{figure}[h]
  \centering
\begin{verbatim}
pdb> show
list_length = 10
layer = -1
\end{verbatim}
  \caption{Global Debugger Options}
  \label{fig:debugger-options}
\end{figure}

\subsubsection{set}
\label{sec:cmd-set}

The \verb|layer| option restricts packet output to a specific ISO
layer.  The default value, -1, shows all layers simultaneously.  If
the user wants to only inspect a particular layer of packets they can
set this to any value from 1 through 7.
Figure~\ref{fig:show-layer-example} shows an example of output
restricted to the data-link layer, in this case, Ethernet.

\begin{figure}[h]
  \centering
\begin{verbatim}
pdb> set layer 2
pdb> list
0: <Ethernet: src: '\x00\r\x022{\x9c', dst: '\xff\xff\xff\xff\xff\xff', type: 2054>
1: <Ethernet: src: '\x00\r\x022{\x9c', dst: '\xff\xff\xff\xff\xff\xff', type: 2054>
2: <Ethernet: src: '\x00\x17\xf2\xe8\x9a*', dst: '\x00\r\x022{\x9c', type: 2048>
3: <Ethernet: src: '\x00\r\x022{\x9c', dst: '\x00\x17\xf2\xe8\x9a*', type: 2048>
4: <Ethernet: src: '\x00\x17\xf2\xe8\x9a*', dst: '\x00\r\x022{\x9c', type: 2048>
5: <Ethernet: src: '\x00\x17\xf2\xe8\x9a*', dst: '\x00\r\x022{\x9c', type: 2048>
6: <Ethernet: src: '\x00\r\x022{\x9c', dst: '\x00\x17\xf2\xe8\x9a*', type: 2048>
7: <Ethernet: src: '\x00\x17\xf2\xe8\x9a*', dst: '\x00\r\x022{\x9c', type: 2048>
8: <Ethernet: src: '\x00\x17\xf2\xe8\x9a*', dst: '\x00\r\x022{\x9c', type: 2048>
9: <Ethernet: src: '\x00\r\x022{\x9c', dst: '\x00\x17\xf2\xe8\x9a*', type: 2048>
\end{verbatim}
  \caption{Output restricted to Layer 2, datalink}
  \label{fig:show-layer-example}
\end{figure}

\end{document}
\begin{thebibliography}{99} 
\end{thebibliography}