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

  <refentryinfo>
    <date>30 May 2007</date>
  </refentryinfo>

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

  <refnamediv>
    <refname>nexp-ether</refname>
    <refpurpose>
      Ethernet support for Network Expect
    </refpurpose>
  </refnamediv>

  <refsynopsisdiv>

    <para>
      PDU definition:
    </para>

    <cmdsynopsis>
      <command>ether</command>(<arg
      choice="opt"><option>src</option>=<replaceable
      class="option">MAC addr</replaceable>,</arg><arg
      choice="opt"><option>dst</option>=<replaceable
      class="option">MAC addr</replaceable>,</arg><arg
      choice="opt"><option>proto</option>=<replaceable
      class="option">num</replaceable></arg> )
    </cmdsynopsis>

    <para>
      PDU decoding:
    </para>

    <para>
      <varname>$ether(src)</varname>, <varname>$ether(dst)</varname>,
      <varname>$ether(type)</varname>
    </para>

  </refsynopsisdiv>

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

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

    <variablelist>

      <varlistentry>
	<term><option>src</option> = <replaceable>MACADDR</replaceable></term>
	<listitem>
	  <para>
	    Specifies the source MAC
	    address. <replaceable>MACADDR</replaceable> is the MAC
	    address in aa:bb:cc:dd:ee:ff format.  Default: MAC address
	    of egress interface.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>dst</option> = <replaceable>NUMSPEC</replaceable></term>
	<listitem>
	  <para>
	    Specifies the destination MAC
	    address. <replaceable>MACADDR</replaceable> is the MAC
	    address in aa:bb:cc:dd:ee:ff format.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>proto</option> = <replaceable>NUMSPEC</replaceable></term>
	<listitem>
	  <para>
	    Specifies the type of payload that the Ethernet frame is
	    carrying. <replaceable>NUMSPEC</replaceable> is a numeric
	    specification. You should only use this option if you are
	    not specifying a higher layer protocol like ARP, IPv4 or
	    IPv6, and want to inject a raw Ethernet payload.
	  </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>$ether(src)</term>
	<listitem>
	  <para>
	    The source MAC address of the received Ethernet frame.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>$ether(dst)</term>
	<listitem>
	  <para>
	    The destination MAC address of the received Ethernet
	    frame.
	    </para>
	  </listitem>
	</varlistentry>

      <varlistentry>
	<term>$ether(type)</term>
	<listitem>
	  <para>
	    The 16-bit <varname>ethertype</varname> field of the
	    received Ethernet frame.
	  </para>
	</listitem>
      </varlistentry>

    </variablelist>

  </refsect1>

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

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

    <para>
      The hash of an Ethernet PDU is the 16-bit Ethernet type, in
      network byte order.
    </para>

    <para>
      A received Ethernet PDU is considered to be a response to an
      injected stimulus if the hash of the received Ethernet frame is the
      same to that of the injected stimulus <emphasis>and</emphasis>
      the Ethernet type is the same in both the received and
      injected frames.
    </para>

  </refsect1>

  <refsect1>
    <title>Examples</title>

    <orderedlist>

      <listitem>
	<para>
	  A simple Ethernet frame:
	</para>

	<programlisting>
ether(dst = 00:11:22:33:44:55, proto = 6)
	</programlisting>

      </listitem>

      <listitem>
	<para>
	  An Ethernet frame carrying an IPv4 packet with simple options:
	</para>

	<programlisting>
ether(dst = 00:11:22:33:44:55)/ip(dst = www.netexpect.org, \
                                  options(nop, nop, nop, eol) )
	</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>
      Ethernet support for <command>Network Expect</command> was
      written by Eloy Paris &lt;peloy@netexpect.org&gt;. The "Send and
      Expect" functionality of the Ethernet 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>
