<?xml version="1.0" encoding="iso-8859-1"?>

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "/usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd" []>

<refentry id="nexp-udp">

  <refentryinfo>
    <date>26 June 2007</date>
  </refentryinfo>

  <refmeta>
    <refentrytitle>nexp-udp</refentrytitle>
    <manvolnum>5</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>nexp-udp</refname>
    <refpurpose>
      User Datagram Protocol (UDP) support for Network Expect
    </refpurpose>
  </refnamediv>

  <refsynopsisdiv>

    <para>
      PDU definition:
    </para>

    <cmdsynopsis>
      <command>udp</command>(<arg
      choice="opt"><option>src</option>=<replaceable
      class="option">num</replaceable>,</arg><arg
      choice="opt"><option>dst</option>=<replaceable
      class="option">num</replaceable>,</arg><arg
      choice="opt"><option>cksum</option>=<replaceable
      class="option">num</replaceable>,</arg><arg
      choice="opt"><option>length</option>=<replaceable
      class="option">num</replaceable></arg> )
    </cmdsynopsis>

    <para>
      PDU decoding:
    </para>

    <para>
      <varname>$udp(srcport)</varname>, <varname>$udp(dstport)</varname>,
      <varname>$udp(length)</varname>,
      <varname>$udperror(srcport)</varname>,
      <varname>$udperror(dstport)</varname>, <varname>$udperror(length)</varname>
    </para>

  </refsynopsisdiv>

  <refsect1>
    <title>PDU Definition</title>

    <variablelist>

      <varlistentry>
	<term><option>src</option> = <replaceable>NUMSPEC</replaceable></term>
	<listitem>
	  <para>
	    Specifies the source UDP port. Default: 1073.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>dst</option> = <replaceable>NUMSPEC</replaceable></term>
	<listitem>
	  <para>
	    Specifies the destination UDP port.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>cksum</option> = <replaceable>NUMSPEC</replaceable></term>
	<listitem>
	  <para>
	    Forces a specific UDP checksum. Default: valid,
	    auto-calculated checksum of the UDP datagram.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>length</option> = <replaceable>NUMSPEC</replaceable></term>
	<listitem>
	  <para>
	    Forces a specific UDP length. Default: valid,
	    auto-calculated length of the UDP datagram.
	  </para>
	</listitem>
      </varlistentry>

    </variablelist>

  </refsect1>

  <refsect1>
    <title>PDU Decoding</title>

    <para>
      The following Tcl variables are available to Tcl scripts after
      any <command>Network Expect</command> command that reads and
      decodes packets has decoded a packet. Commands that read and
      decode packets include the <command>expect_network</command>
      family of commands as well as the <command>pdu decode</command>
      command.
    </para>

    <variablelist>

      <varlistentry>
	<term>$udp(srcport)</term>
	<listitem>
	  <para>
	    The UDP source port the received UDP datagram.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>$udp(dstport)</term>
	<listitem>
	  <para>
	    The UDP destination port of the received UDP datagram.
	    </para>
	  </listitem>
	</varlistentry>

      <varlistentry>
	<term>$udp(length)</term>
	<listitem>
	  <para>
	    The 16-bit <varname>length</varname> field of the
	    received UDP datagram.
	  </para>
	</listitem>
      </varlistentry>

    </variablelist>

  </refsect1>

  <refsect1>
    <title>send_expect Support</title>

    <para>
      <command>Network Expect</command> UDP PDUs support the
      <command>send_expect</command> command.
    </para>

    <para>
      The hash of an UDP PDU is the bitwise XOR of the source and
      destination UDP ports, which is a 16-bit value.
    </para>

    <para>
      A received UDP PDU is considered to be a response to an
      injected stimulus if the hash of the received UDP datagram is the
      same as that of the injected stimulus <emphasis>and</emphasis>
      the following conditions are met:
    </para>

    <itemizedlist>

      <listitem>
	<para>
	  The source port of the injected UDP datagram is the same as
	  the destination port of the received UDP datagram.
	</para>
      </listitem>

      <listitem>
	<para>
	  The destination port of the injected UDP datagram is the
	  same as the source port of the received UDP datagram.
	</para>
      </listitem>

    </itemizedlist>

  </refsect1>

  <refsect1>
    <title>Examples</title>

    <orderedlist>

      <listitem>
	<para>
	  A simple UDP datagram:
	</para>

	<programlisting>
ip(dst = www.example.com)/udp(src = random, dst = 53)/raw('ABCDEFG')
	</programlisting>

      </listitem>

      <listitem>
	<para>
	  A definition for an UDP datagram that forces a bogus length
	  field in the UDP header:
	</para>

	<programlisting>
ip(dst = www.example.com)/udp(src = random, dst = 53, \
   length = 5)/raw('ABCDEFG')
	</programlisting>

      </listitem>

    </orderedlist>

  </refsect1>

  <refsect1>
    <title>VERSION</title>

    <para>This man page is correct for version 1.0 of <command>Network
      Expect</command>.
    </para>
  </refsect1>

  <refsect1>
    <title>SEE ALSO</title>
    
    <para>
      nexp<manvolnum>1</manvolnum>,
      nexp-numspec<manvolnum>1</manvolnum>
    </para>
  </refsect1>

  <refsect1>
    <title>AUTHOR</title>
	
    <para>
      UDP support for <command>Network Expect</command> was
      written by Eloy Paris &lt;peloy@netexpect.org&gt;. The "Send and
      Expect" functionality of the UDP module was borrowed from
      Scapy, the packet manipulation program written in Python by
      Philippe Biondi.
    </para>
	
    <para>
      This man page was written by Eloy Paris.
    </para>
  </refsect1>

</refentry>
