<?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-ip">

  <refentryinfo>
    <date>29 May 2007</date>
  </refentryinfo>

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

  <refnamediv>
    <refname>nexp-ip</refname>
    <refpurpose>
      Internet Protocol (IP) version 4 support for Network Expect
    </refpurpose>
  </refnamediv>

  <refsynopsisdiv>

    <para>
      PDU definition:
    </para>

    <cmdsynopsis>
      <command>ip</command>(<arg
      choice="opt"><option>version</option>=<replaceable
      class="option">num</replaceable>,</arg><arg
      choice="opt"><option>src</option>=<replaceable
      class="option">ipaddr</replaceable>,</arg><arg
      choice="opt"><option>dst</option>=<replaceable
      class="option">ipaddr</replaceable>,</arg><arg
      choice="opt"><option>ttl</option>=<replaceable
      class="option">num</replaceable>,</arg><arg
      choice="opt"><option>length</option>=<replaceable
      class="option">num</replaceable>,</arg><arg choice="opt"><option>cksum</option>=
      <replaceable class="option">num</replaceable>,</arg><arg
      choice="opt"><option>ihl</option>=<replaceable class="option">num</replaceable>,</arg><arg choice="opt"><option>tos</option>=<replaceable
      class="option">num</replaceable>,</arg><arg
      choice="opt"><option>fragoff</option>=<replaceable
      class="option">num</replaceable>,</arg><arg
      choice="opt"><option>proto</option>=<replaceable
      class="option">num</replaceable>,</arg><arg
      choice="opt"><option>id</option>=<replaceable
      class="option">num</replaceable>,</arg><arg
      choice="opt"><option>options</option>(<replaceable
      class="option">IPv4 options</replaceable>)</arg> )
    </cmdsynopsis>

    <para>
      PDU decoding:
    </para>

    <para>
      <varname>$ip(version)</varname>, <varname>$ip(ihl)</varname>,
      <varname>$ip(id)</varname>, <varname>$ip(ttl)</varname>,
      <varname>$ip(tot_len)</varname>,
      <varname>$ip(protocol)</varname> <varname>$ip(src)</varname>,
      <varname>$ip(dst)</varname>,
      <varname>$iperror(version)</varname>,
      <varname>$iperror(ihl)</varname>,
      <varname>$iperror(id)</varname>,
      <varname>$iperror(ttl)</varname>,
      <varname>$iperror(tot_len)</varname>,
      <varname>$iperror(protocol)</varname>,
      <varname>$iperror(src)</varname>,
      <varname>$iperror(dst)</varname>
    </para>

  </refsynopsisdiv>

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

    <para>
      The following parameters allow to define the different parts of
      an IPv4 protocol data unit (PDU) in <command>Network
      Expect</command>:
    </para>

    <variablelist>

      <varlistentry>
	<term><option>version</option> = <replaceable>NUMSPEC</replaceable></term>
	<listitem>
	  <para>
	    The 4-bit <varname>Version</varname> field of the Internet
	    Protocol header. Default: 4.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>src</option> = <replaceable>NUMSPEC</replaceable></term>
	<listitem>
	  <para>
	    Specifies the source IP address.  IP addresses can be
	    specified in numeric format (separated by dots) or by
	    fully-qualified domain name (FQDN), in which case the name
	    is resolved to its IP address. Note that this is a numeric
	    specification. Default: IP address of egress interface.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>dst</option> = <replaceable>NUMSPEC</replaceable></term>
	<listitem>
	  <para>
	    Specifies the destination IP address.  IP addresses can be
	    specified in numeric format (separated by dots) or by
	    fully-qualified domain name (FQDN), in which case the name
	    is resolved to its IP address. Note that this is a numeric
	    specification.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>id</option> = <replaceable>NUMSPEC</replaceable></term>
	<listitem>
	  <para>
	    Specifies the value of the ID field in the IPv4
	    header. Default: 256 for little endian architectures and 1
	    for big endian architectures.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>ttl</option> = <replaceable>NUMSPEC</replaceable></term>
	<listitem>
	  <para>
	    Specifies the value of the Time-to-live field in the IPv4
	    header. Default: 64.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>tos</option> = <replaceable>NUMSPEC</replaceable></term>
	<listitem>
	  <para>
	    Specifies the value of the Type Of Service field in the
	    IPv4 header. Default: 0.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <command>options</command>(<arg
	    choice="opt"><option>eol</option>,</arg><arg
	    choice="opt"><option>nop</option>,</arg><arg choice="opt"><option>raw</option>=<replaceable>PAYLOADSPEC</replaceable>,</arg>
	  <arg choice="opt"><option>rr</option>(<replaceable
	      class="option">record route definition</replaceable>),</arg><arg choice="opt"><option>lsrr</option>(<replaceable
	      class="option">record route definition</replaceable>),</arg><arg choice="opt"><option>ssrr</option>(<replaceable
	      class="option">record route definition</replaceable>)</arg> )
	</term>

	<listitem>
	  <para>
	    Defines IPv4 options. The following IPv4 options are available:
	  </para>

	  <variablelist>

	    <varlistentry>
	      <term><option>eol</option></term>
	      <listitem>
		<para>
		  Specifies that an IP end-of-option-list option be
		  added to the IPv4 header. Note that when specifying
		  IPv4 options it is up to the user to make sure that
		  the correct padding is specified so the entire
		  option section is correctly
		  aligned. <emphasis>nop</emphasis> options should be
		  used to pad between options and
		  <emphasis>eol</emphasis> should be used to pad at
		  the end of the option list. See RFC 791 to know
		  about padding requirements. You
		  <emphasis>need</emphasis> to make sure that the IP
		  header has enough space for this option. Remember
		  that the IP header only has space for 40 bytes of
		  options.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><option>nop</option></term>
	      <listitem>
		<para>
		  Specifies that an IP no-operation option be added to
		  the IPv4 header. Note that when specifying IPv4
		  options it is up to the user to make sure that the
		  correct padding is specified so the entire option
		  section is correctly
		  aligned. <emphasis>nop</emphasis> options should be
		  used to pad between options and
		  <emphasis>eol</emphasis> should be used to pad at
		  the end of the option list. See RFC 791 to know
		  about padding requirements. You
		  <emphasis>need</emphasis> to make sure that the IP
		  header has enough space for this option. Remember
		  that the IP header only has space for 40 bytes of
		  options.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><option>raw</option> = <replaceable>PAYLOADSPEC</replaceable></term>
	      <listitem>
		<para>
		  Defines a raw IP option which allows to enter
		  arbitrary values in the option
		  definition. <replaceable>PAYLOADSPEC</replaceable>
		  is a payload specification.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>
		<command>rr</command>(<arg
		  choice="opt"><option>length</option>=<replaceable>num</replaceable>,</arg><arg
		  choice="opt"><option>ptr</option>=<replaceable>num</replaceable>,</arg><arg
		  choice="opt"><option>router</option>=<replaceable>hostname
		  or IP addr</replaceable>,</arg> ...)
	      </term>
	      <listitem>
		<para>
		  Specifies that an IP record-route option be added to
		  the IPv4 header. The option definition uses the
		  following parameters:
		</para>

		<variablelist>

		  <varlistentry>
		    <term><option>length</option>=<replaceable>number</replaceable></term>
		    <listitem>
		      <para>
			Specifies the total space that should be
			reserved for this option. It is not a numeric
			specification, just a number.
		      </para>
		    </listitem>
		  </varlistentry>

		  <varlistentry>
		    <term><option>ptr</option>=<replaceable>number</replaceable></term>
		    <listitem>
		      <para>
			Another number and <emphasis>not</emphasis> a
			numeric specification, represents the value of
			the PTR field in the option.
		      </para>
		    </listitem>
		  </varlistentry>

		  <varlistentry>
		    <term><option>router</option>=<replaceable>hostname
		    or IP addr</replaceable></term>
		    <listitem>
		      <para>
			After specifying <option>length</option> and
			<option>pointer</option> a list of IP
			addresses can optionally follow. IP addresses
			can be specified in numeric format (separated
			by dots) or by fully-qualified domain name
			(FQDN), in which case the name is resolved to
			its IP address. Note that fields are separated
			by commas and that no space between commas is
			allowed. You <emphasis>need</emphasis> to make
			sure that the IP header has enough space for
			this option. Remember that the IP header only
			has space for 40 bytes of options.
		      </para>
		    </listitem>
		  </varlistentry>

		</variablelist>

	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>
		<command>lsrr</command>(<arg
		  choice="opt"><option>length</option>=<replaceable>num</replaceable>,</arg><arg
		  choice="opt"><option>ptr</option>=<replaceable>num</replaceable>,</arg><arg
		  choice="opt"><option>router</option>=<replaceable>hostname
		  or IP addr</replaceable>,</arg> ...)
	      </term>

	      <listitem>
		<para>
		  Specifies that an IP loose-source, record-route
		  option be added to the IPv4 header. The parameters
		  of the option definition are explained above in the
		  description of the <option>rr</option> option. You
		  <emphasis>need</emphasis> to make sure that the IP
		  header has enough space for this option. Remember
		  that the IP header only has space for 40 bytes of
		  options.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>
		<command>ssrr</command>(<arg
		  choice="opt"><option>length</option>=<replaceable>num</replaceable>,</arg><arg
		  choice="opt"><option>ptr</option>=<replaceable>num</replaceable>,</arg><arg
		  choice="opt"><option>router</option>=<replaceable>hostname
		  or IP addr</replaceable>,</arg> ...)
	      </term>

	      <listitem>
		<para>
		  Specifies that an IP strict-source, record-route
		  option be added to the IPv4 header. The parameters
		  of the option definition are explained above in the
		  description of the <option>rr</option> option. You
		  <emphasis>need</emphasis> to make sure that the IP
		  header has enough space for this option. Remember
		  that the IP header only has space for 40 bytes of
		  options.
		</para>
	      </listitem>
	    </varlistentry>

	  </variablelist>

	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>protocol</option> = <replaceable>NUMSPEC</replaceable></term>
	<listitem>
	  <para>
	    Specifies the value of the Protocol field in the IPv4
	    header. You should only use this option if you are not
	    specifying a higher layer protocol like UDP, TCP or ICMP,
	    and want to inject a raw IPv4 payload. Default: IP
	    protocol number if upper layer protocol is known.
	  </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>$ip(version)</term>
	<listitem>
	  <para>
	    The 4-bit <varname>Version</varname> field of the Internet
	    Protocol header of the received packet.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>$ip(ihl)</term>
	<listitem>
	  <para>
	    The 4-bit <varname>Internet Header Name</varname> (IHL)
	    field in the Internet Protocol header of the received
	    packet.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>$ip(id)</term>
	<listitem>
	  <para>
	    The 16-bit <varname>Identification</varname> field in the
	    Internet Protocol header of the received packet.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>$ip(ttl)</term>
	<listitem>
	  <para>
	    The 8-bit <varname>Time to Live</varname> (TTL) field in
	    the Internet Protocol header of the received packet.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>$ip(tot_len)</term>
	<listitem>
	  <para>
	    The 16-bit <varname>Total Length</varname> field in the
	    Internet Protocol header of the received packet.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>$ip(protocol)</term>
	<listitem>
	  <para>
	    The 8-bit <varname>Protocol</varname> field in the
	    Internet Protocol header of the received packet.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>$ip(src)</term>
	<listitem>
	  <para>
	    The source IP address of the received IP packet.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>$ip(dst)</term>
	<listitem>
	  <para>
	    The destination IP address of the received IP packet.
	    </para>
	  </listitem>
	</varlistentry>

      <varlistentry>
	<term>$iperror(version)</term>
	<listitem>
	  <para>
	    The 4-bit <varname>Version</varname> field of the Internet
	    Protocol header of the packet
	    <emphasis>embedded</emphasis> in the received ICMP error message.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>$iperror(ihl)</term>
	<listitem>
	  <para>
	    The 4-bit <varname>Internet Header Name</varname> (IHL)
	    field in the Internet Protocol header of the packet
	    <emphasis>embedded</emphasis> in the received ICMP error
	    message.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>$iperror(id)</term>
	<listitem>
	  <para>
	    The 16-bit <varname>Identification</varname> field in the
	    Internet Protocol header of the packet
	    <emphasis>embedded</emphasis> in the received ICMP error
	    message.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>$iperror(ttl)</term>
	<listitem>
	  <para>
	    The 8-bit <varname>Time to Live</varname> (TTL) field in
	    the Internet Protocol header of the packet
	    <emphasis>embedded</emphasis> in the received ICMP error
	    message.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>$iperror(tot_len)</term>
	<listitem>
	  <para>
	    The 16-bit <varname>Total Length</varname> field in the
	    Internet Protocol header of the packet
	    <emphasis>embedded</emphasis> in the received ICMP error
	    message.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>$iperror(protocol)</term>
	<listitem>
	  <para>
	    The 8-bit <varname>Protocol</varname> field in the
	    Internet Protocol header of the packet
	    <emphasis>embedded</emphasis> in the received ICMP error
	    message.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>$iperror(src)</term>
	<listitem>
	  <para>
	    The source IP address of the IP packet
	    <emphasis>embedded</emphasis> in the received ICMP error
	    message.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>$iperror(dst)</term>
	<listitem>
	  <para>
	    The destination IP address of the IP packet
	    <emphasis>embedded</emphasis> in the received ICMP error
	    message.
	  </para>
	</listitem>
      </varlistentry>

    </variablelist>

  </refsect1>

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

    <para>
      <command>Network Expect</command> IP version 4 PDUs support the
      <command>send_expect</command> command.
    </para>

    <para>
      The hash of an IP version 4 PDU is the bitwise exclusive OR (XOR) of the source
      and destination IP addresses (4 bytes) followed by the IP
      protocol field (1 byte) for a hash total length of 5 bytes.
    </para>

    <para>
      A received IP version 4 PDU is considered to be a response to an
      injected stimulus if the hash of the received IP packet is the
      same to that of the injected stimulus <emphasis>and</emphasis>
      the IP protocol field is the same in both the received and
      injected packets <emphasis>and</emphasis> the source IP address
      of the received packet is the destination IP address of the
      injected stimulus.
    </para>

    <para>
      Please note that IP packets can be embedded in ICMP error
      messages.
    </para>

  </refsect1>

  <refsect1>
    <title>Examples</title>

    <orderedlist>

      <listitem>
	<para>
	  A simple IP packet:
	</para>

	<programlisting>
ip(dst = www.netexpect.org, ttl = 64)
	</programlisting>

      </listitem>

      <listitem>
	<para>
	  An IP packet with simple options:
	</para>

	<programlisting>
ip(dst = www.netexpect.org, options(nop, nop, nop, eol) )
	</programlisting>

      </listitem>

      <listitem>
	<para>
	  The same IP packet but using a raw option:
	</para>

	<programlisting>
ip(dst = www.netexpect.org, options(raw='\x01\x01\x01\x00') )
	</programlisting>

      </listitem>

      <listitem>
	<para>
	  An IP packet with a record-route option:
	</para>

	<programlisting>
ip(dst = www.netexpect.org, options(rr(length = 7, ptr = 4, \
    router = 30.30.30.30) ) )
	</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>,
      nexp-payload<manvolnum>1</manvolnum>, RFC 791
    </para>
  </refsect1>

  <refsect1>
    <title>AUTHOR</title>
	
    <para>
      IP version 4 support for <command>Network Expect</command> was
      written by Eloy Paris &lt;peloy@netexpect.org&gt;. The "Send and
      Expect" functionality of the IPv4 modules 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>
