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

  <refentryinfo>
    <date>02 June 2007</date>
  </refentryinfo>

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

  <refnamediv>
    <refname>nexp-numspec</refname>
    <refpurpose>
      Documentation for numeric specifications used in Network Expect
      PDU definitions
    </refpurpose>
  </refnamediv>

  <refsynopsisdiv>

    <para>
      Numbers:
    </para>

    <itemizedlist>
      <listitem>
	<para><replaceable class="option">1234</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">telnet</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">1234++</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">1234--</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">1234+=5</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">1234-=5</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">1234*=5</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">1234/=5</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">1234%=5</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">1234&lt;&lt;=5</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">1234&gt;&gt;=5</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">1 + 5*(3 + 5)/2</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">&lt;telnet, www, ssh, 8080&gt;</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">1..1024</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">random</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">random(1..1024)</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">random(23, 75%)</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">random(telnet, 75%)</replaceable>
	</para>
      </listitem>

    </itemizedlist>

    <para>
      IPv4 Addresses:
    </para>

    <itemizedlist>

      <listitem>
	<para><replaceable class="option">192.168.0.1</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">hostname</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">hostname.example.com</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">192.168.0.0/24</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">hostname/24</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">hostname.example.com/24</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">192.168.0.0/255.255.255.0</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">hostname/255.255.255.0</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">hostname.example.com/255.255.255.0</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">192.168.0.1
	  .. 192.168.0.255</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">&lt;192.168.0.1, 192.168.0.20,
	  hostname.example.com&gt;</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">random</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">random(192.168.0.0/24)</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">random(hostname/24)</replaceable>
	</para>
      </listitem>

      <listitem>
	<para><replaceable class="option">random(hostname.example.com/24)</replaceable>
	</para>
      </listitem>

    </itemizedlist>

  </refsynopsisdiv>


  <refsect1>
    <title>Introduction</title>

    <para>
      When defining packets, <command>Network Expect</command> allows
      to specify values for most fields in protocol headers using a
      syntax that gives great flexibility. This syntax, called a
      <emphasis>Numeric Specification</emphasis>, allows to make the
      value of a field <emphasis>change</emphasis> with each packet
      that is created. A numeric specification may specify that the
      value of a field changes in different ways, like randomly, by
      incrementing, decrementing, multiplying, or dividing by an
      arbitrary amount, by choosing a value from a list of values; or
      it may specify that that the value does not change at all.
    </para>

    <para>
      If the numeric specification specifies that the value of the
      field changes then a number of packets will be generated to
      cover all possible combinations. If the packet definition has
      several numeric specifications then all numeric specifications
      will be combined when the packets are created so all
      combinations are covered.
    </para>

    <para>
      Currently, <command>Network Expect</command> numeric
      specifications support regular numbers and IP version 4
      addresses.
    </para>

    <para>
      The rest of this manual page documents the exact syntax that is
      supported by numeric specifications. Specific examples will be
      used to make the syntax easier to present.
    </para>

  </refsect1>

  <refsect1>
    <title>Numbers</title>

    <itemizedlist>

      <listitem>
	<para><emphasis>23</emphasis>: the generated value will always be
	  the same number.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>telnet</emphasis>: the generated value will
	  always be 23, the telnet port number. The port number is
	  resolved by calling getservbyname().
	</para>
      </listitem>

      <listitem>
	<para><emphasis>23++</emphasis>: the generated value will be 23
	  initially, and will be incremented by one with each
	  successive packet.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>23--</emphasis>: the generated value will be 23
	  initially, and will be decremented by one with each
	  successive packet.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>23+=5</emphasis>: the generated value will be 23
	  initially, and will be incremented by 5 with each successive
	  packet.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>23-=5</emphasis>: the generated value will be 23
	  initially, and will be decremented by 5 with each successive
	  packet.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>23*=5</emphasis>: the generated value will be 23
	  initially, and will be multiplied by 5 with each successive
	  packet.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>23/=5</emphasis>: the generated value will be 23
	  initially, and will be divided by 5 with each successive
	  packet.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>23%=5</emphasis>: the generated value will be 23
	  initially, and then will be the reminder of a division by 5
	  (modulus) with each successive packet.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>23&lt;&lt;=5</emphasis>: the generated value will
	  be 23 initially, and will bit-shifted 5 bits to the left
	  with each successive packet.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>23&gt;&gt;=5</emphasis>: the generated value will
	  be 23 initially, and will bit-shifted 5 bits to the right
	  with each successive packet.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>1 + 5*(3 + 5)/2</emphasis>: an expression - the
	  generated value will always be the same, the result of the
	  expression. Valid operators are '+', '-', '*', '/', unary
	  minus ('-'), and the parenthesis ('(' and ')') to force
	  precedence.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>&lt;telnet, www, ssh, 8080&gt;</emphasis>: a list
	  of values - the generated values will be 23 (the telnet
	  port), 80 (the HTTP port), 22 (the SSH port), and 8080.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>23..25</emphasis>: the generated value
	  will start with 23, will be incremented by one until it
	  reaches 25, and then will go back to 23. This specifies a
	  range of values.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>random</emphasis>: the generated value will be a
	  random number in each successive packet.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>random(1..1024)</emphasis>: the generated
	  value will be a random number between 1 and 1024.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>random(23, 75%)</emphasis>: the generated
	  value will be 23 twenty-five percent of the time and a
	  random number seventy-five percent of the time.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>random(23, 75%)</emphasis>: the generated
	  value will be 23 (the telnet port) twenty-five percent of
	  the time and a random number seventy-five percent of the
	  time. The port number is resolved via the getservname()
	  system call.
	</para>
      </listitem>

    </itemizedlist>

  </refsect1>

  <refsect1>
    <title>IPv4 Addresses</title>

    <itemizedlist>

      <listitem>
	<para><emphasis>192.168.0.1</emphasis>: the generated value will
	  always be the IP address 192.168.0.1.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>hostname</emphasis>: the generated value will
	  always be the IP address of host
	  <emphasis>hostname</emphasis>.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>hostname.example.com</emphasis>: the generated
	  value will always be the IP address of host
	  <emphasis>hostname.example.com</emphasis>.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>192.168.0.0/24</emphasis>: the generated value
	  will be the IP address 192.168.0.0 the first time and then
	  will increment by one with each successive packet until
	  192.168.0.255 is reached.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>hostname/24</emphasis>:
	  <emphasis>hostname</emphasis> will be resolved and all IP
	  addresses in the corresponding /24 IP subnetwork will be
	  generated, starting at the bottom of the subnet and
	  incrementing by one with each successive packet until the
	  top of the subnet is reached.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>hostname.example.com/24</emphasis>:
	  <emphasis>hostname.example.com</emphasis> will be resolved
	  and all IP addresses in the corresponding /24 IP subnetwork
	  will be generated, starting at the bottom of the subnet and
	  incrementing by one with each successive packet until the
	  top of the subnet is reached.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>192.168.0.0/255.255.255.0</emphasis>: the
	  generated value will be the IP address 192.168.0.0 the first
	  time and then will increment by one with each successive
	  packet until all addresses in the 255.255.255.0 subnetwork
	  are covered.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>hostname/255.255.255.0</emphasis>:
	  <emphasis>hostname</emphasis> will be resolved and then all
	  IP addresses in the 255.255.255.0 subnetwork will be
	  generated starting at the bottom of the subnetwork and
	  incrementing by one with each successive packet until the
	  highest address in the subnetwork is reached.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>hostname.example.com/255.255.255.0</emphasis>:
	  <emphasis>hostname.example.com</emphasis> will be resolved
	  and then all IP addresses in the 255.255.255.0 subnetwork
	  will be generated starting at the bottom of the subnetwork
	  and incrementing by one with each successive packet until
	  the highest address in the subnetwork is reached.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>192.168.0.1 .. 192.168.0.255</emphasis>: the
	  generated value will start with 192.168.0.1 and increment by
	  one with each packet until 192.168.0.255 is reached.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>192.168.0.1, 192.168.0.20,
	  hostname.example.com</emphasis>: list definition - each
	  packet will use a different IP address from the list.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>random</emphasis>: the generated value will be a
	  random IP address with each packet.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>random(192.168.0.0/24)</emphasis>: the generated
	  value will be a random IP address within the 192.168.0.0/24
	  subnetwork.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>random(hostname/24)</emphasis>:
	  <emphasis>hostname</emphasis> will be resolved and then the
	  generated value will be a random IP address within the /24
	  subnetwork <emphasis>hostname</emphasis> resides in.
	</para>
      </listitem>

      <listitem>
	<para><emphasis>random(hostname.example.com/24)</emphasis>:
	  <emphasis>hostname.example.com</emphasis> will be resolved
	  and then the generated value will be a random IP address
	  within the /24 subnetwork
	  <emphasis>hostname.example.com</emphasis> resides in.
	</para>
      </listitem>

    </itemizedlist>

  </refsect1>

  <refsect1>
    <title>EXAMPLES</title>

    <orderedlist>

      <listitem>
	<para>The following packet definition would generate a single
	  packet since all fields use numeric specifications that
	  result in fixed numbers and IP addresses:
	</para>

	<programlisting>
ip(src = 192.168.0.1, dst = 192.168.0.10)/ \
tcp(src = random, dst = 80, window = 16384, \
    syn, seq = random, ack-seq = 0)
	</programlisting>

      </listitem>

      <listitem>
	<para>The following packet definition will generate eight
	  packets because there are two numeric specifications (for IP
	  TTL and destination IP address) that produce two values and
	  one (for TCP destination port) that produces four values.
	</para>

	<programlisting>
ip(src = 192.168.0.1, dst = &lt;192.168.0.10, 192.168.0.11&gt;,
   ttl = &lt;1, 2&gt;)/ \
tcp(src = random, dst = &lt;22..25&gt;, window = 16384, \
    syn, seq = random, ack-seq = 0)
	</programlisting>

      </listitem>

    </orderedlist>

  </refsect1>

  <refsect1>
    <title>BUGS</title>

    <para>
      Error-checking is almost non-existant.
    </para>

  </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>
    </para>
  </refsect1>

  <refsect1>
    <title>AUTHOR</title>
	
    <para>
      <command>Network Expect</command> was written by Eloy Paris
      &lt;peloy@netexpect.org&gt;.
    </para>
	
    <para>
      This man page was written by Eloy Paris.
    </para>
  </refsect1>

</refentry>
