AnetTest utility

User guide

 

Contents

General description

Installation

Installation under Unix

Installation under Windows

Home directory

General notions

Basic operating modes

Packet generator

Send/receive scenario

Multi-interface mode

Tracing packets

Test reports

Tcp/udp connections

Scanner mode

Working with trace files

Packet filter test

Imitation of network applications work

Command line

Program return status

Anettest script

Byte pointer

Types of values

Strings

Automatically calculated values

Defining custom fields in packet

Fields with variable position and size

Building packet from blocks

Packet mask

Variables

Conditions and cycles

Packets content analysis

System interaction

Miscellaneous commands

All commands and special values table

Integration with text editors

Text highlighting

Midnight commander editor for UNIX

Context editor for Windows (www.contexteditor.org)

Notepad++

Auto-completion

Notepad++

For Developers

Compiling with MinGW.

Extending by new custom code.

 

General description

The program Anettest may be used as a packet generator. It is possible to generate any packets at channel layer (for Ethernet networks), some types of packets at network layer (IP protocol), and at application layer (sending data blocks within TCP session).

Descriptions of packets can be stored in text files or be specified in command line. The syntax of description is simple enough (field name - value). The fields (format of packet) are specified in header files (headers). There are some headers provided for commonly known network protocols. The program allows you to define own headers. Numerical data types, strings, IP address, MAC addresses are available.

The generation of packets can be alternated with waiting of others. In the case of waiting a packet mask is used which is based on packets content (an equality condition) but it may also have special conditions: not equal, greater than, etc.

The program provides a simple but rather flexible language with variable, branches and cycles. Thus, the statuses of received packets, their content may be deeply analyzed to determine following actions.

It is possible to use the program for implementing the automated tests of various network devices and applications. It is achieved by the ability that after packets description you may specify the requests according to which the packets will be searched in trace-files or network will be scanned in real time. Generally it will be possible to generate sets of packets then wait for the reaction of various network devices and applications caused by these packets and finally obtain the message successful test or the list of discrepancies.

It is possible to use the program as a slightly unusual sniffer. If you describe a set of packets in a file the program may be a scanner of network about the presence of specified packets. At a specified interval a report is displayed about the total number and the intensity of packets of each type.

The program also has several operation modes for network filter (firewall) testing and the ability of modifying trace-files.

 

Installation

Installation under Unix

Before installing the program libpcap (www.tcpdump.org) must be installed.

Try running "sudo apt-get install libpcap-dev" (for Ubuntu).

For installation run INSTALL

You may use ant, ant1, ant2, ... scripts instead of anettest.

Installation under Windows

Before running the program WinPcap (www.winpcap.org) must be installed. Then you can just run program.

Use file registry.reg. Before adding info from this file to registry you must set your own default parameters in it. The addition may be performed by clicking on file.

Home directory

In home folder program will search for "headers" folder, "samples" folder, "traces" folder with headers, samples and trace files.

For UNIX it's /usr/local/anettest (if not changed during installation).

For Windows it's folder from file "registry.reg".

If you use another home folder it must be specified by -I option. The current directory is also home directory (it has the highest priority when searching for referenced files). Thus if you run program from the folder where its been unpacked to then no problem must be.

Base header

There is a special header file among headers. Its name is "base.fws".

It will be processed before any file explicitly specified by -f option.

All useful global definitions may be contained in this file.

 

General notions

Main interface - by default its the first interface specified by option -d. At this interface packets will be generated. For some commands just on this interface packets will be waited by default (command WAIT). It can be changed by command MI.

Packet mask a part of packets description which will be used while comparing of the packet with anyone accepted on physical interface or from trace-file. In simple case the mask consists of those fields for which values have been specified in packets description but it is not always true (see command CLEARMASK, special mask conditions). Only values of fields from mask will be considered while comparison a packet with another. More about packet mask

Reception interfaces physical network interfaces of computer or trace-files, i.e. packets can be captured in real time or obtained from specified trace-files. The logic of work does not change. Requests to packet (as parameters to command SEND or WAIT) will correspond to each reception interface. For the most of operating modes reception interfaces all opened physical interfaces (go in the same order as they are specified by option -d). In online-test of packet filter the first opened physical interface becomes the main interface the others will be reception interfaces.

Requests to packet the list of requests like "is accepted" (ACCEPT, >>), "is not accepted" (DROP, <<), has no meaning (ANY). Can be specified for any packet. Each request corresponds to one reception interface. The first in the list - for the first reception interface, the second - for the second, etc. They are specified optionally as parameters to commands SEND and WAIT. It allows program to display summary report about correspondence of those requests to what actually has happened.

Syntax of the list:

<request>:: = << | >> | DROP | ACCEPT | ANY

<list of requests>:: = { <request> }

While working in multi-interface mode the list of requests is another.

Unique name of interface a name used to reference interface. It may be specified in d option after symbol # (eth0#myname). The unique name for trace-file may be specified while its opening by c option.

 

Basic operating modes

All options and work modes are described in Table 1.

Further the review of the basic modes with examples is resulted.

Packet generator

For the generation of packets start the program by one of the next ways:

anettest -d eth0 -f packets.fws

anettest -d 10.0.0.1 -f packets.fws

By means of option -d the name of a network adapter for work at channel level may be specified (ex: eth0). It is possible to look at the list of accessible adapters, using option -i. Instead of adapters name it is possible to specify the corresponding IP-address (as shown in the second case). The IP-addresses corresponding to adapters can also be obtained by option -i.

The description of packets can be stored in text file which may be specified by option -f.

File packets.fws (the test script) can be like the following:

INCLUDE tcp.fws

srcip lpc10

dstip 1.1.1.1

dstport 80

SEND

Before packets description it is recommended to include one of header files using command INCLUDE. Instead of include tcp.fws it would be possible to type simply tcp, and program would try to find a similar header file. The header file tcp.fws includes other header files so that values of all the fields of each network header (Ethernet, IP, TCP) are initialized by correct default values, otherwise these values would just be equal to 0. In the shown example after the inclusion of header file the values of three fields (with names srcip, dstip, dstport) are changing how it is necessary for concrete packet. Command SEND generates the packet described before it. After command SEND it would be possible to continue the packet description, i.e. change values of some fields, and then use command SEND again to send the second packet which is different from the first. More about the syntax of script.

In the program distribute there must be a HEADERS folder with headers of network protocols. Names of fields of network protocols can be learned by watching corresponding header files or by using option -k.

It is possible to specify packets description directly in command line:

anettest -d eth0 tcp dstip 1.1.1.1 dstport 80

In the end of packets description command SEND is automatically added so its not necessary to type it. Word tcp means including of header file (this word is treated as a part of packets description in command line).

Ex: samples/generate_udp_packet, samples/generate_sequence_packets.

See also:

options -T (working with data segments over TCP-sessions),

command REP (multiple generation),

command PAUSE,

command INC (autoincrementing value of some field).

 

Send/receive scenario

Alternation of sending and receiving packets can be implemented in general operating mode.

The program should be started in usual mode (as packet generator):

anettest -d eth0 -f packets.fws

To generate packets use command SEND (without parameters).

To wait packets use WAIT, OR, WAITALL, SENDWAIT, SENDWAITOTHER. Some of commands just register packet to wait but do not start waiting. Others just start waiting packets registered before. Others do both. Waiting continues till any of the registered packets arrives or timeout expires. Comparing packets is based on mask. RECV commands is more suitable when working with TCP(UDP) connections.

It is possible to specify a timeout of waiting by command TIMEOUT. IFR command allows you to determine when timeout happens and run a different branch.

COPYREC command enables a mode when content of received packet is copied to the buffer of current packet so then you can run complex code analyzing packets content.

Results of waiting of packets that has been added by commands WAIT or OR will be displayed in report which will be displayed upon program termination. Command CLEARREG typed at the end of script causes that report not to be displayed.

See also PAUSE.

 

Multi-interface mode

Generally you can use many opened interfaces but only the first one will be generating. To change generating interface as you want during script execution you need to enable special mode. It is performed by command EXTENDED.

In this mode main interface can be changed by command MI. This command also automatically calls EXTENDED when met first time.

Requests for packets in this mode must be specified differently:

<request1>:: = DROP | ACCEPT | ANY

<request2>:: = << | >>

<request>:: = (<request1> <unique name of interface>) | (<request2> [ ] <unique name of interface>)

<list of requests>:: = { <request> }

After each request there must be the unique name of interface for which request is specified.

<< and >> may not be separated by space from unique name.

Example:

SEND <<0 >>1 <<2

SEND DROP 0 ACCEPT 1 DROP 2

Similarly requests in command DEFAULTS and in command WAIT must be specified.

 

Tracing packets

The program implements one of standard functions of sniffers - tracing packets and recording to file. The program does not display packets description but only writes down their content in file (a file format libpcap). The physical adapter (where to trace packets) is specified by option -d. The name of file for record is specified by option -t. Packets content are fully stored by default (see also option -s).

Example:

anettest -d eth0 -t trace.pcap

Note: if the intensity of packets will be too high during enough big time interval then some packets might not be registered (are not written down in file). Nevertheless, the general number of packets accepted on the main interface which will be displayed at the end of program work, will show the real number of accepted packets.

Total number of packets recieved on first interface = 1

 

Test reports

By default program outputs test reports with status for each packet that has been waited during script execution.

CLEARREG clear all statuses info, no report will be displayed,

SHOWREP display report immediately,

LASTRES value that holds the general status of last report displayed by SHOWREP: all match or not.

 

Tcp/udp connections

Use T option to work with tcp connection using system socket.

Generally you can open tcp/udp connection using OPEN command.

OPEN tcp client:1.1.1.1:80#optional_name_of_this_connection

Above connects to server with specified address (waits till connected).

OPEN tcp server:localhost:80

Above binds to given local address and listens for client connections (waits till connected). TIMEOUT command may be used to set timeout of waiting for connection.

It works similarly for udp but without connecting/waiting happening while opening.

OPEN udp client:1.1.1.1:80

OPEN udp server:localhost:80

Then to send data use

data data

SEND

To wait any data

RECV

For udp everything is similar but use udp.data.

Use CLOSE command to close connection.

CLOSE name_of_this_connection_specified_while_opening

IFR command may be used to check the status of last waiting operation: ok, error or timeout.

See samples/tcp_gateway, samples/http_client, samples/http_server.

See also NEWLINEIS command.

Scanner mode

The scanner will display statistics for packets described in script (separated by SEND command), show their intensity (the number of packets and the amount of data) in real time, displaying periodically reports. This mode is alternative to packet filter test since there will be displayed information about the conformance of current state of network and the requests to packets specified in scenario. As well as in the test of the packet filter packets are divided by command SEND after which it is possible to specify requirements to packet.

Example of start of the program:

anettest -d eth0 r -v srcport 22

Program will show statistic about packets with number of source port = 22. The sniffer mode is turned on by option -r. The used network adapters are specified by option -d. Packets description may be specified in command line (like in shown example). It is possible to describe several packets in file (option -f) then the program will periodically display statistic for each of packets in the form of the table (report). While working in this mode not packets content but packet mask will be used when comparing packet from script with some received packet.

In the previous example to the end of packets description command SEND will be added (like in the mode of packet generator).

ALL open physical interfaces specified by option -d will be reception interfaces. Unlike the test of packet filter in sniffer mode the first network adapter which is specified by option -d, will be also the first reception interface (i.e. the first request to packet will correspond to it). All subsequent adapters will be considered as the second, the third reception interfaces. This difference should be considered while using commands SEND or DEFAULTS.

Example: samples/tracing_packets.fws.

See also: option -u (changing period of displaying reports).

Working with trace files

The program allows to change trace files (having libpcap format) by special commands. Trace file can be open by command TRACE. To write down the changed file on disk there is a command WRITE.

After file opening it is possible to use some simple commands:

getpac - loads packet from trace file in the buffer of currently described packet;

setpac - writes down current packet in file over existing packet;

inspac - writes down current packet in file, inserting a new packet into trace file;

delpac - deletes specified packet from trace file.

There is a command for changing several packets at once: chtrace.

Examples: samples/work_with_traces, samples/work_with_traces1.

 

Packet filter test

It is a mode for implementing automated tests of various packet filters. Automatization means that you dont need for manual review of sniffers output in order to conclude if packets are passed through filter.

If the all used network segments (corresponding to physical interfaces) where it is necessary to trace packets, are connected to one computer then its possible to implement fast test: while generating packets tracing will be performed. Right after generation of all packets the result of test will be available (called online-test). If network segments are connected to different hosts then while packets generating from one host it is necessary to trace packets on other hosts, recording them in trace-files and then to copy all of these files on one computer and run offline-test. Both tests will be described below.

The file with the description of packets which is set through an option-f, can look so:

fasttest // while online-test this command must be specified at the beginning of script

 

INCLUDE tcp

fullmask

tcp.flags = syn

dstport http

send drop accept

dstport ssh

send accept drop

dstport ftp

send drop accept

Here three packets are described. They are separated from each other by the command SEND. The packets differ in the values of destination TCP-port (dstport). The values of TCP-flags (tcp.flags) are equal for all the packets. The values of other fields are defined in the included header file tcp. After the each command SEND requests for packet (ACCEPT or DROP) are specified. More details about syntax of script are in other section.

The using of FULLMASK will be explained below.

The Offline-test

To implement the offline-test at first its necessary to start sniffers on all participating hosts, for example:

anettest -d eth0 -t trace1.fws

anettest -d eth0 -t trace2.fws

anettest -d eth0 -t trace3.fws

These sniffers will store any received packets in file.

Then start packet generator on one computer, for example:

anettest -f packets.fws -d eth0

Then collect all the resulted trace-files in one place and perform the direct offline-test:

anettest -f packets.fws -c trace1 -c trace2 -c trace3

During the direct offline-test each of the packets described in the script packets.fws will be searched in the trace-files. While the comparison of packets packet mask will be used. The result of search is compared with the requests to packets which have been mentioned earlier. The first request after command SEND will correspond to the file trace1, the second and the third - to the files trace2 and trace3. ACCEPT - means that the packet must be found in a trace-file, DROP not found. Thus, the program checks the conformance of the requests specified in the file packets.fws, and search results for the trace-files. The message successful test that all requests are met, or the list of discrepancies will be displayed.

The offline-test mode is always turned on by option -c.

The Online-test

Trace-file is a special type of reception interface. Files trace1, trace2, trace3 were the first, second and third reception interfaces.

If all of reception interfaces are connected to one host then its possible to perform fast online-test:

Only one start is necessary:

anettest -f packets.fws -d eth1#1 -d eth2#2 -d eth3#3

After symbol # unique number of the interface is specified.

For implementing such a test at the beginning of script file command FASTTEST must be typed which turns on the online-test mode. If not to use this command packets from script will be simply generated.

Packets will be generated from interface eth1 (main interface) and will be registered on reception interfaces: eth2, eth3. The first request will correspond to eth2, the second - eth3. In other operating modes (sniffer mode, using command WAIT) all open physical interfaces are reception interfaces, i.e. the first requirement would correspond to eth1. While online-test only there is a shift.

During the test at first sniffers will be started on all opened interfaces, then there will be an instant generation of all packets from script from the main interface. After the generation of packets sniffers will be stopped, and there will be performed the search of packets from script among the packets registered by sniffers (is similarly to searching in trace-files).

Pause between starting of sniffers and the beginning of generation of packets = 100 ms.

Pause between the termination of generation and sniffers termination = 200 ms.

If packets in the beginning or in the end of script are registered as not accepted (though actually they are passed through filter either too quickly, or too slowly) try to increase pauses by command PAUSE, having inserted it in the beginning or in the end.

Reports

The output of program for any type of test may be like this:

Packet on line 10 (./test.fws): accepted (dev 2)

Packet on line 14 (./test.fws): dropped (dev 2)

Packet on line 19 (./test.fws): accepted (dev 2)

For each found discrepancy the name of file and the line in file are displayed, where packets description was met (more precisely the position of command SEND before which there was packets description), the result of search for the concrete reception interface (interface number is enclosed in brackets). If unique number has been specified for interface (in option d) then it will be shown (with prefix dev), otherwise the consecutive number according to the order of opening interfaces will be shown (with prefix sdev).

Command NAME allows to set the name for packet which will be displayed in report.

Command REP allows to specify that must be received not one but several packets.

Remark:

If in the previous example someone not used the command FULLMASK then while the comparison of packets there would be considered only those fields whose values are explicitly specified in the script (they are tcp.flags and dstport). The other fields of tcp header whose values are specified in the file tcp.fws would not participate in the comparison because the command CLEARMASK is used in standard header files including tcp header (it has been done for convenience while working in other operating modes). Thus, it would be possible not to notice some changes of packets content on their way or to treat foreign tcp packets as own ones.

Examples: samples/compare_mode, samples/compare_mode1, samples/fasttest.

 

Imitation of network applications work

The imitation of application's work is performed based on information from a trace-file (specified by command TRACE). During a test program imitates the work of one or several network applications sending packets in strict sequence (following the trace-file) from different physical interfaces (corresponding to a predefined test configuration a set of end points).

The program doesnt only send packets but also can check that other packets from trace-file are being successfully received. Commonly, packets generation process is synchronized with receiving process: a packet from trace-file is generated only if all the previous packets have been received. If they havent then after a timeout last packets are generated again and after several repeated generations the non-received packets are marked as dropped and the process of generation continues.

In requests to the result of test it is possible to specify what packets should be received and what are dropped. So you can implement automated tests of sophisticated application firewalls using prepared complex templates in trace files.

Those packets from trace-file that must be generated or received are specified by end points: generating and receiving ones. Other packets from trace-file are not considered at all, which are not covered by an end point.

Before imitation start (command RUN) it is necessary to define some end points (command EP, header "configSession"), for example:

ep togen 0 srcip first //1

ep torecv 1 srcip first //2

ep togen 1 srcip second //3

ep torecv 0 srcip second //4

The example above corresponds to the imitation of an interaction between two hosts. The first packet in trace file must be from the first host, the second packet from the second host. The first end point (generating one) indicates that packets from trace file that have the value of field srcmac equal to the value from first packet must be generated from the interface with unique name = 0. The second end point (receiving one) indicates that the same packets are expected to be received at the interface with unique name = 1.

During imitation packets from trace-file are traversed consistently. Each generating end point can send its packet only when all previous packets are accepted by receiving end points. The first packet from trace-file covered by end point 1 is generated immediately at interface 0. The second packet covered by end point 3 cannot be generated untill end point 2 receives the first packet at interface 1. When it happens the second packet is generated. If not then the first packet is generated again several times, then marked as dropped and the second packet is generated. It must be received at interface 0 by end point 4.

Each packet can belong to a single generating end point and a single receiving one. If receiving end points are not specified packets will be simply generated. If generating end points are not specified packets will be simply waited and marked as dropped after timeout.

It is possible to start two parties of imitator on different hosts. The timeout for the first packet is increased to 3 seconds so after the start of waiting its enough time to start the generation of packets. If you dont satisfy with 3 seconds then the first packet may be marked as dropped.

Configured test may be started by command RUN.

The program must be started in general mode:

anettest -d eth0#0 -d eth1#1 -f session_test.fws

After implementing the first test it is possible to reset the configuration by command DEFAULTTEST and then configure the next test.

If some intermediate point changes packets on their way (in a priory known manner) it is possible to use command RM. It may be useful when testing NAT (Network Address Translation).

If before the test it is not known how the intermediate point will change packets, but it will become known during the test then it is possible to use command ARM (testing NAT).

If the values of some fields of packets do not need to be considered while comparison, then it is possible to use command CIEVE.

Command NUMRET sets the number of repeated generations.

Command TIMEOUT set the timeout before repeated generation.

Example:

Trace-file content:

1 0.000000 194.85.99.33 88.210.60.143 TCP 54840> smtp [SYN] Seq=0 Len=0 WS=1

2 0.013321 88.210.60.143 194.85.99.33 TCP smtp> 54840 [SYN, ACK] Seq=0 Ack=1

3 0.013750 194.85.99.33 88.210.60.143 TCP 54840> smtp [ACK] Seq=1 Ack=1

4 0.030554 88.210.60.143 194.85.99.33 SMTP Response: 220 imap.r-and-k.com ESMTP

5 0.030996 194.85.99.33 88.210.60.143 TCP 54840> smtp [ACK] Seq=1 Ack=37

6 0.032663 194.85.99.33 88.210.60.143 SMTP Command: EHLO xperts1.rtc.ru

7 0.046934 88.210.60.143 194.85.99.33 SMTP Response: 250-imap.r-and-k.com

Test configuration (see command EP):

//generating end point 1

ep togen 0 srcip 194.85.99.33 //generating packets for client on interface 0

//generating end point 2

ep togen 2 srcip 88.210.60.143 //generating packets for server on interface 2

//recieving end point 3

ep torecv 2 srcip 194.85.99.33 //waiting packets for client on interface 2

//recieving end point 4

ep torecv 0 srcip 88.210.60.143 //waiting packets for server on interface 0

The same configuration can be also written so:

//generating end point 1

ep togen 0 srcip first //generating packets for client on interface 0

//generating end point 2

ep togen 2 srcip second //generating packets for server on interface 2

//recieving end point 3

ep torecv 2 srcip first //waiting packets for client on interface 2

//recieving end point 4

ep torecv 0 srcip second //waiting packets for server on interface 0

At the imitation beginning the packet which must be first waited will be found. It is packet 1 belonging to end point 3. The packet will be waited on interface 2. Then the packet which must be generated will be found. It is packet 1 belonging to end point 1.

Packet 1 will be generated on interface 0. The following packet which needs to be generated is packet 2 belonging to end point 2. This packet cannot be generated, while packet 1 is waited on interface 2. When the packet 1 will be accepted on interface 2 transition to a following waited packet will be performed. It is packet 2 belonging to end point 4. After such a transition packet 2 can be generated by end point 2.

If packet 1 is not accepted during timeout on interface 2 then packet 1 will be repeatedly generated on interface 0. After several repeated generations packet 1 can be marked as dropped and waiting of packet 2 will be started.

Full content of test script may be the following:

trace smtp_client.pcap

 

//generating end point 1

ep togen 0 srcip 194.85.99.33 //generating packets for client on interface 0

//generating end point 2

ep togen 2 srcip 88.210.60.143 //generating packets for server on interface 2

//recieving end point 3

ep torecv 2 srcip 194.85.99.33 //waiting packets for client on interface 2

//recieving end point 4

ep torecv 0 srcip 88.210.60.143 //waiting packets for server on interface 0

 

run drop 6 // all the packets, since 6 should be dropped

Examples: samples/convtest1, samples/convtest2.

The standard configuration for imitation of client-server session is presented in file headers/configSession.fws.

The standard configuration for imitation of client-server session with NAT between them - headers/natConfigSession.fws.

Configuration NAT should be stored in file headers/natDefines.fws.

 

Command line

Table 1. Command line options

 

Name

Description

Example

List of adapters

(-i)

Displays the list of physical interfaces (adapters) for generating and tracing packets on channel level. In the list after adapters number there is his name and may be IP address if it has been associated.

anettest -i

Opening

adapter

(-d)

 

Parameter to option: the name of opened interface.

By default the adapters for work on channel level are opened. For the list of available adapters use option i.

It is possible to specify an adapter by its IP-address or DNS-name.

Interfaces name may contain symbol # after which a unique name of adapter is specified.

When using TCP the format of interfaces name is different (see option T).

anettest -d eth0 -f packets.fws

 

anettest -d 10.0.0.10
-d 10.0.1.10
-d 10.0.2.10
-f packets.fws

 

anettest -d 10.0.0.10#0
-d 10.0.1.10#1
-d 10.0.2.10#2
-f packets.fws

 

Opening trace-files

(-c)

Parameter to option: the name of opened trace file (having libpcap format).

If this option is specified then program will search packet from script in trace-files (offline-test). See the description of packet filter test.

Note: if the size of stored part of packet in trace is less than the size of packet from script then packets are not equal.

If in the name of trace-file there is a number then it will become the user name of interface.

anettest -c file1.pcap
-c file2.pcap
-c file3.pcap
-f packets.fws

Tracing packets to file

(-t)

Parameter to option: the name of trace file for recording captured packets.

If this option is specified then program will capture packet and record them in trace file (having libpcap format).

Packets content is fully copied by default. Consider the use of option s.

anettest -t file.pcap -d eth0

Test script

(-f)

The scenario of work of the program (the description of packets, etc.). In the majority of operating modes it needs to be set. The description of syntax of the scenario is resulted in separate section of the documentation. It is possible to transfer the description of packets in a command line. The first word not similar to an option will be considered as the packet description.

anettest -f packets.fws -d eth0

Snaplen

(-s)

Parameter to option: the maximum size of packet which will be captured. This parameter is applied globally for all tracing procedures.

Implemented only for UNIX.

anettest -t file.pcap
-d eth0 s 120

Sniffer mode

(-r)

Activates the sniffer mode.

anettest -r -f packets.fws
-d eth0

RAW IP (-p)

Indicates to use generation and tracing packets not on channel level, but on network (IP) level. The names of adapters which are specified in option -d, must be IP addresses.

For packets generation only it is not necessary to specify IP address.

The Generation of the majority of packets in OS Windows XP will be blocked by system with Service Pack 2 (any TCP packets, packets with no local IP source address).

In Linux it is impossible to generate datagramms with size larger than MTU. IP datagramms may be captured only globally without distinguishing interfaces.

In FreeBSD neither generation of packets nor tracing are not implemented.

For other systems program not tested.

anettest -p

Working with TCP-sessions

(-T)

This option specifies to work not with packets, but with blocks of data over TCP-connection.

In option -d it is necessary to specify an adapter name in format client:host:port (client mode) or server:host:port (server mode).

Parameter to option: the timeout when waiting for connections while server mode.

In client mode program will try to establish a connection to the specified address.

In server mode program will wait for connections on the specified address (so the address must be local).

In script you should use the field with name tcp.data (or its alias - td) to specify what data must be send (by command SEND) or be waited (by command WAIT).

In this mode command WAIT takes the full block of data received from other side and compares it to that packet which is described before command.

So the block will be treated as one packet.

If at least one byte is received then it will be a packet.

So there is no ability to implement absolutely reliable tests but it works in practice.

Note: while working in this mode command CLEARMASK must be used after inclusion of standard headers (ex: tcp): all fields except tcp.data (data) must not be in packet mask.

See samples/mail_reader.

anettest T 99999
d client:remotehost:110
-f data.fws

 

anettest T 99999
d server:localhost:110
-f data.fws

 

anettest -T 9999
-d c:lpc10:21
-f data.fws

 

anettest T 99999
d s:localhost:110
-f data.fws

-h

Causes that numbers in script will be processed as hexadecimal by default. Without using this option - decimal.

 

Verbose output

(-v)

If this option is used when in report there will be displayed statistic for all packets. Otherwise only for those packet for which requests arent met.

 

-w

Causes that program asks for pressing any key before terminating.

 

-q

Causes that network adapters are not switched in promisc mode (see libpcap documentation).

 

-u

Parameter to option: the interval in milliseconds between displaying reports while working in sniffer mode.

anettest u 1000

Search paths

(-I)

Parameter to option: a new path where included files will be searched (see command INCLUDE).

anettest headers -I

Fields info

(-k)

Prints the table with information about defined fields of network protocols.

In command-line you can specify the name of concrete header(s). Program will process this header(s) and then will print the table.

anettest -k tcp

anettest -k tcp_header

anettest k all_headers

Program return status

If a fatal error raises then program terminates, returning status = 1.

If there are no fatal errors (test was completed) but specified requests dont correspond with test results then returned status = 2.

If test is successfully completed (all requests correspond with test results) then returned status = 0.

Command EXIT enables you to explicitly define the returned status.

Anettest script

Script file is a usual text file which can be edited in any text editor. It is recommended to create such files with *.fws extension (for example: packets.fws).

 

Comments are the same as for languages C/C ++, Java.

// - the beginning of comments till the end of line.

/* */ - comments of any number of lines.

 

Most of elements must be separated by space.

 

Formal syntax:

<script> ::= { <element of script> }

<element of script> ::= <command> | <packet modification> | <variable modification> | <file inclusion> | <field definition>

Packet description

Script works with one packet which consists of content and mask. The content is a sequence of bytes, the mask is a set of conditions.

Packets content is initially filled by 0. Packet mask has no conditions initially, i.e. corresponds to any packet.

You can modify the packet using several operators:

<packet modification> :: = <packets content modification> | <packet mask modification>

<packets content modification> ::= <fields name> [=] <value>

Content modification means specifying some value for some field, ex:

srcport = 100

srcport 100

While content modification packet mask will also change: there will be added a new condition that the specified field must have the specified value. So the mask is based on content.

If you include some header file then packets content is filled by correct values which are specified in header.

Actually in script you dont describe multiple packets but only one packet. Commands SEND and others can simply get the current packets content and mask and then generate it or store in separate buffer. It looks like describing several packets but next packet inherits the content and mask of previous.

Byte pointer

There is a byte pointer which is used in different operations. This pointer is initially equal to 0. After a <packets content modification> it will be set just after the field and will be equal to (fields position + fields size). Commands to manage byte pointer:

POS sets position,

PASS increases pointer,

BACK decreases pointer,

CURPOS gets current position.

Program also works with packets size. This size may be used, for example, while packet generation. It will be equal to maximum position of byte pointer which was fixed from the start of script processing. So by default the size cannot decrease and next packet cannot be smaller than previous. One exception works: the size may decrease if the size of higher field decreases. The higher field is field with maximum position. It may have string type of value. Ex:

tcp.data hello

SEND

tcp.data hel

SEND // size of this packet will be smaller then size of previous

The mask notion is described later.

CLEARHISTORY, CLEARMASK commands are used to start working as though nothing has been written before.

Simple file inclusion

<file inclusion> ::= <name of file>

To include a file you may not use command INCLUDE but simply type the name of file. Program will search the specified file.

Types of values

Numbers

By default numbers are decimal, but while using option -h they will be hexadecimal.

If you want to explicitly specify the type of number then use 0x prefix for hexadecimal number and dot at the end for decimal numbers:

scrport = 0x8888 // hexadecimal number

ethproto = 5. // decimal number

ethproto = 5 // decimal number if option h is not used

The size of hexadecimal number will be determined by its form:

ttl = 0x8 // one byte

ttl = 0x88 // one byte

ethproto = 0x188 // two bytes

For big numbers the number of digits must be even.

For decimal number you dont need to explicitly specify its size: the size will be determined by fields size.

srcport 4 // field srcport has size = 2, so 4 means the value of two bytes

While field definition you must explicitly specify the size for decimal numbers:

.srcport 4s2 // after symbol s the size of number is specified

IP the address

Examples:

.srcip 1.1.1.1

srcip localhost

srcip mycomp

srcip www.yandex.ru

While field definition must be used the first format: four numbers (indicates that the type of field is IP address). Further you can use DNS name.

MAC the address

Examples:

.srcmac 11:22:33:44:55:66

srcmac 11-22-33-44-55-66

srcmac 0x112233445566

srcmac 112233445566

While field definition must be used the first or second formats (indicates that the type of field is MAC address). Further you can use any format.

IPv6 address

ip6.src 1122:3344:5566:7788:99aa:bbcc:ddee:ff00

ip6.src 0:0:0:0:0:0cc:d00:0

DNS the name is not accepted.

Strings

String is a set of characters enclosed with quotation marks or apostrophes.

The standard escape sequences are available:

\r, \n, \, \, \t, \a, \b, \x00.

If a string is enclosed with apostrophes then its possible to insert references in this string. The reference is a name of field, variable, substitution (defined by DEFINE or GDEF command) or some special value which is enclosed with $.

value of field = $name$

The reference will be replaced by its value:

value of field = 2

If name of field is referenced then its value is generally obtained from the buffer of current packet, not received one (only command MES gets it from received packet). Use command COPYREC to get that value from received packet.

Fields with string type of value dont have concrete size. So strings of any length may be specified as value. It may be changed by command SETSIZE.

See also command NEWLINEIS.

 

Automatically calculated values

There are some special fields for which values may be automaticly calculated.

Names of values: IPlen, IPcrc, IPv6len, TCPcrc, UDPcrc, UDPlen, ICMPcrc.

It is possible to specify such values for corresponding fields of network headers. Ex:

ip.crc = IPcrc

They are already specified in standart headers, so when generating, for example, TCP packet it will contain correctly calculated check sums.

While calculating some values, program will demand, that certain fields have been defined. For example, for values IPlen, IPcrc the field with name ip.ver must be defined. Its position points to beginning of IP header. The standard ip header (ip.fws) defines this field. Thus you can build own packets where ip header has not standart position. The position of redefined ip.ver field (see field definition) must point to actual position of ip header.

It is possible not to use automatic values. If you specify own value then it will be used:

ip.crc = 0

After some actions (command CLEARHISTORY, command GETPAC) all automatic values will be marked as no active so they will not be calculated. In this case after these actions you must again explicitly specify

ip.crc = IPcrc

ip.len = Iplen

For developers

ProtocolsExpert class is used to calculate such values. IpTcpExpert class is derived from it. You can implement your own class and add it in ExtendHelper :: getProtocolsExperts method.

Defining custom fields in packet

Sometimes it is necessary to define new fields for the description of headers of custom network protocols or simply to redefine the parameters of already known fields.

Fields parameters: position (as the displacement in bytes from the beginning of channel level header), size, type (i.e. the type of value).

<field definition> ::= . <new fields name> <initial value>

Ex:

.new_field1 11 // one-byte field, type: decimal number

.new_field2 0x1122 // two-byte field, type: hexadecimal number

.new_field3 11s2 // two-byte field, 11 in decimal format

.new_field4 GET host // type: string, size: till the end of data

.new_field5 1.2.3.4 // type: IP address

.new_field6 22-22-22-22-22-22 // type: MAC address

.new_field7 11:11:11:11:11:11 // type: MAC address

See types of values for more info.

The type of field and its size are defined by specified value. Packets content will also change: the specified value will be written in packets buffer.

The position of a newly created field is defined by the current position of byte pointer. After field definition byte pointer will be increased by the size of defined field. So it will point to position just after the defined field.

MASK, OFFSET commands used when a field corresponds to specific bits (see how they used in headers).

See files in headers folder.

Fields with variable position and size

Commands SETPOS, SETSIZE allow you to set the position and size of a field later. They may be calculated before. It happens usually during the analysis of a received packet. After correct position and size are set you can reference that field and get the corresponding part of packets content.

.text_field

int calc_pos = 0

int calc_size = 0

 

//

// a packet received, calculate its position and size

// and store them in calc_pos and calc_size

 

SETPOS text_field calc_pos

SETSIZE text_field calc_size

PRINTL text_field

See samples/http_parser.

If some field with specified name already exists then its parameters will be rewritten to correspond to the new definition.

Building packet from blocks

Full packet (packets template) consists of several headers of different network protocols. Program enables you to build such complex templates using prepared headers.

Example:

include vlan

include ip_header

include tcp_header

In example above its shown how to build tcp packet with vlan header instead of simple Ethernet II header (which is defined in standard header tcp.fws). Parameters of fields from standard ip and tcp headers will be redefined.

If you are going to work with different formats of packet in single script then you may define all variants of format at once.

INCLUDE vlan

INCLUDE ip_header

 

int ip_header_end = curpos // store the position where ip header ends

 

INCLUDE tcp_header

 

POS ip_header_end // restore the position where ip header ends

 

INCLUDE udp_header

Now you can work with tcp and udp packets over vlan.

 

Packet mask

Packet mask is used while comparing a packet from script with some packet from trace-file or packet received on physical interface. Mask is a set of conditions and is based on packet content:

srcport = 40 // modifies content but also adds condition in mask

// that value of srcport must be equal to 40

When new field definition is processed the mask is similarly changed.

Some special operations with mask are also available:

<packet mask modification> ::= <adding a new condition to mask> | <removing condition from mask>

<adding a new condition to mask> ::= <fields name> <comparison qualifier> <value>

<comparison qualifier> ::= != | > | < | >= | <=

<removing condition from mask> ::= <fields name> [=] any

Example:

srcport != 40 // adds condition that srcport must not be equal to 40

srcport > 20 // adds condition that srcport must be greater than 40

srcport >= 20

srcport = any // removes from mask all the conditions related to field srcport

Mask is always inherited by packet below in script.

However equality conditions for a single field are being overwritten.

CLEARMASK command is used to clear the mask so it corresponds to any packet.

FILTER command allows you to set fast basic filter (in pcap library format).

See also FULLMASK, FIXMASK, UNFIXMASK.

Variables

Variables are some values stored separately from packets content. They may be changed by special commands and their names may be used in parameters to commands instead of concrete values.

If you need just a simple variable then use this syntax

String var1 =

Int int1 = 0

Hex hex1 = 0x0 // will be displayed as hexedicaimal, any length

Variables are generally created by command VAR.

VAR (v1, num, 1)

This command also provides some additional options. See its description.

Variable may be associated with some field and the type of variables value is the same as the type of fields value. In the above example num is a field from TCP header (program knows this field a priory, you dont need to always include tcp header). A variable can be set to be auto-updated by a received packet. Value of field in packet will be copied to variable.

See samples/variables.

Created variables may be modified by commands INCVAR, DECVAR, MULVAR, DIVVAR.

To store and load variable from file see LOADVAR, WRITEVAR.

For modifying variables you can also use the following syntax:

<variable modification> ::= <variables name> <operation with variable> <value>

<operation with variable> ::= [=] | += | -=

Ex:

v1 += 2 // adds 2 to variable

v1 -= 4 // subtract 2 from variable

v1 = 4 // sets value of variable

 

 

Conditions and cycles

IF to compare any two entities and decide between two branches;

IFR decide based on status of last waiting command;

IFDEF, IFNDEF based on the fact whether something was defined by DEFINE (GDEF),

CYC to make cycle;

BREAK breaks cycle;

RETURN break processing of current included file;

EXIT exits program;

 

Packets content analysis

To analyze a received packet you need at first copy it to buffer of current packet by COPYREC command or via use of RECV command. After that you can reference a field by its name and value from received packet will be used. Then use variables and conditions. Position and size of some fields are not known beforehand and need to be calculated based on values of other fields. Read here about it.

GOTO searches for specified string in packet starting from current position of byte pointer.

GOTOB like GOTO but searches backwards.

See samples/http_parser.

Command MES allows you to output received packet content easily but without complex analysis.

Do not try to include header files or use any new field definitions after receiving a packet as it will overwrite content of received packet. All fields and variants of packets structure must be defined before waiting.

See samples/http_parser.

 

System interaction

SYSCALL - to run another program,

PLAY play wav sound under Windows,

BEEP makes sound via system speaker,

LOADVAR read variable from file,

WRITEVAR - store variable in file,

GETCH wait for key press

 

Miscellaneous commands

NEWLINEIS defines what new line is \r\n or \n.

DEFINE, GDEF define something like constant values with assigned names, in oder to not write the same string each time,

RAND to get random value,

QUIET do not display some auxiliary messages on console,

CURSIZE to get the size of current packet,

CURTIME to get current time,

PRINT, PRINTL display message,

MES show message for each received packet.

 

All commands and special values table

<command> ::= <commands name> <commands parameters>

Parameters to command may be enclosed in round brackets.

Parameters to command may be separated by space or by commas.

Between the name of command and its parameters symbol = may be typed.

 

SEND

PARAMETERS: {accept | drop | any }

In common regime generates the packet defined above. In other regimes (testing packet filter, see command FASTTEST and option -c) may simply separate packets one from another, so by this command the current content of buffer will be fixed and the new packet will be registered. The requests after command don't make sense in common regime (only while testing packet filter).

PAUSE

PARAMETERS: <number of milliseconds>

Pauses the execution for a specified interval of time.

DROP

PARAMETERS: {accept | drop | any }

Request specification. The request that the packet must not be received. May be used as command - replacement for "SEND DROP". It may be processed as command while testing packet filter only (command FASTTEST or option -c). In common regime it may be among parameters to command only.

ACCEPT

PARAMETERS: {accept | drop | any }

Request specification. The request that the packet must be received. Analog of SEND ACCEPT. It may be processed as command while testing packet filter only (command FASTTEST or option -c). In common regime it may be among parameters to command only.

ANY

PARAMETERS: {accept | drop | any }

Request specification. No requests: the packet may be received or not. Analog of SEND ANY. It may be processed as command while testing packet filter only (command FASTTEST or option -c). In common regime it may be amoung parameters to command only. This special word may also be used as value for field that means exclusion the all conditions with this field from current mask of packet - value of the field may be any.

REP

PARAMETERS: <the number of generation>

The next generation command (command SEND) will generate not one, but several packets.

The use of this command also affects the request for packet: the packet must be accepted the specified number of times.

CLEARMASK

PARAMETERS: no parameters

The mask of packet (the set of previously defined conditions) will be cleared. New mask will correspond to any packet. This command is usually contained in headers to make the mask correspond to all packets of given type (ex: TCP packets).

INC

PARAMETERS:

The field for which the value will be specified below becomes autoincremented. While generating several packets (command REP) the value of field will be incremented. See "samples/synflood.fws"

OFFSET

PARAMETERS: <number of bites>

The position of the next defined field will be shifted to the left for the given <number of bits> which must be from 1 to 7. So every written value will be shifter to the left before writing. Nevertheless, after the writing the left bits will be also changed and set to 0. To avoid this use command MASK. See "headers/tcp_header.fws"

DEFAULTS

PARAMETERS: {accept | drop | any | revers }

Defines default requests for packets. These requests will be applied when there are not enough explicitly defined requests for some packet (specified as parameters to command SEND, WAIT and its analogs). Initially default requests are ACCEPT ANY ANY... i.e. a single request for the first interface specified via option -d.

INCLUDE

PARAMETERS: <name of file>

Starts processing the content of given file. The search of file will be performed in the current directory, all search paths (see option -I). For every path the content of samples, headers, traces folders will be also examined. You can also type just the name of file without include before it.

DEVICE

PARAMETERS: <type of device> {<name of interface>}

Reopens interfaces. The type of device: eth, ip, tcp. The name of device is the same as for -d option, depends on the type of device. New line terminates the list of names.

WAIT

PARAMETERS: {accept | drop | any }

Waits for packet whose mask is defined above. The command will finish work when such packet is received on waitable interface. The waitable interface is interface for which strict request (accept or drop) have been specified in parameters to command or in defaults (command DEFAULT). For TCP device the command will only wait data on the main interface. In the general case command may wait no one but several packets (added by ADD command). If any of them is received then command terminates. Command waits packets until timeout expires (command TIMEOUT). See "samples/waiting_packets.fws".

EXIT

PARAMETERS: <status>

Terminates the execution. The status may be some decimal number. Value 0 is reserved for successful test, 1 - fatal error, 2 - not successful test, 3 - error while TCP connecting or listening (timeout expires).

PASS

PARAMETERS: <number of bytes>

Increases the byte pointer for the given <number of bytes>.

DEFINE

PARAMETERS: <name> <value>

Defines the substitution which will be applied while reading some values (in parameters to commands and others). <name> will be replaced by <value>. This substitution may be also performed in strings enclosed in apostrophes. In this case the <name> must be enclosed in $ (ex: 'value = $name$'. See also command GDEF.

MASK

PARAMETERS: <field's mask>

Defines the mask for the next defined field. Mask is hexadecimal number. Value for field will be written only in bits corresponding not null bits of mask. See "headers/tcp_header.fws".

POS

PARAMETERS: <new position> | <field's name>

Sets the <new position> of byte pointer. In the case of <field's name> new position will be equal to field's position.

BACK

PARAMETERS: <number of bytes>

Reduces the pointer for the given <number of bytes>.

CLEARHISTORY

PARAMETERS: no parameters

Clears info about the maximum size of previous packets. New packet may be smaller than previous ones. This command also makes all auto-calculated values inactive.

VAR

PARAMETERS: <name of variable> <name of field> <initial value> ("autoset"| ["static"] )

Command creates the new variable <name of variable> or reinitializes the old one if some variable of the same name is already exist. The newly created variable will have the same value's type as <name of field>. This command also sets the <initial value> for variable. Variable's value is stored separately from packet's buffer. The "autoset" type of variable indicates that the variable will be initialized by received packet (while using WAIT command or its analogs), i.e. from received packet will be obtained value of <name of field> and copied to variable. "static" type indicates that variable must not be changed while receiving packet. The "static" keyword may be omitted only if parameters to command are enclosed in round brackets.

The <name of variable> may appear among parameters to other commands. In this case it will be replaced by its value. Such a replacement will be also performed in strings enclosed in apostrophes. In this case the <name of variable> must be enclosed in $ (ex: 'value of variable = $name$').

See "samples/ask_mac.fws", "samples/variables.fws".

NAME

PARAMETERS: <name of packet>

Defines the name of currently described packet which will be displayed in report instead of "Packet on line ..."

MES

PARAMETERS: <string of message>

Defines the message which will be displayed the every time on receiving the currently described packet. Substitutions are allowed in the form of $name$. The 'name' may reference to the field's name, variable's name, someone defined by GDEF command. In the case of field's name field's value will be retrieved from the content of received packet.

EXTENDED

PARAMETERS: no parameters

Enables extended regime. Generating interface can be change by MI command. While specifying the requests for packet each request must be followed by the unique name of interface.

MI

PARAMETERS: <name of interface>

Sets the main interface at which packets will be generated or waited (by default it's the first opened interface). The unique name of interface must be specified which may be defined while opening (-d option or OPEN command) after symbol # (e.g. "-d eth0#0"). If no unique name is specified then it will be assigned to number 0,1,2,3,... Default requests are being overwritten: a single ACCEPT request is set for the new main interface, others are ANY. This means that further WAIT command (its analogs) will wait packet ONLY at the new main interface. In order to wait a packet at several interfaces use command DEFAULTS after command MI or explicitly specify requests after WAIT command.

REVERS

PARAMETERS: not command

Request specification. May only be given in parameters for DEFAULT command. Instructs to reverse the request for every packet.

BEEP

PARAMETERS: no parameters

Plays the sound via PC speaker.

SAFETERM

PARAMETERS: no parameters

If the intensity of packets is very high and the program fails in deadlock on terminating, then this command will help. Terminating may become slower.

INTERVAL

PARAMETERS: <number of milliseconds>

Sets the value of interval between generating multiple packets while using command REP.

INCVAR

PARAMETERS: <name of variable> <value to add>

Increases the given <name of variable> for the specified <value to add>. The <value to add> may be negative.

TOWAIT

PARAMETERS: {accept | drop | any }

Analog of WAIT command. Adds the above packet to the set of packets which will be waited by command WAIT or its analogs. This command does not start actual waiting (doesn't suspend script execution). Nevertheless, just after adding the packet may be registered as received. If some packet is registered as received before the call to WAIT (WAITALL) then the command will ignore it and wait for a next packet (see also SENDWAITOTHER).

GDEF

PARAMETERS: <new name> <original name>

Defines the substitution which will be applied while reading almost any read word from text. <New name> will be replaced by <original name>. This substitution may be also performed in strings enclosed in apostrophes. In this case the name must be enclosed in $ (ex: 'value = $name$').

TIMEOUT

PARAMETERS: <interval in milliseconds>

Defines the timeout for WAIT command (and its analogs), also for imitation of application's work. Null value means infinite timeout (such timeout will not be applied for imitation of application's work). In the case of negative value its absolute value will be obtained as timeout, but WAIT command (its analogs) will work differently: it will always wait for the whole timeout (not terminating on first received packet). So several packets may be registered as received. This command also defines the timeout for TCP server while waiting for connections.

QUIET

PARAMETERS: no parameters

Instructs to not display some annoying messages.

CYC

PARAMETERS: <number of iterations>

Command instructs that next WAIT command (its analogs) or next block of script will be processed by several times = <number of iterations>. The "inf" value is available which means infinite iterant processing.

SYSCALL

PARAMETERS: <command>

Implements the system call. <command> must specify command's name (path to program) with parameters. Special value CALLRES may be used to obtain the status of last system call.

NOTDOUBLEMES

PARAMETERS: no parameters

Avoids displaying of double messages (specified by command MES). It also avoids the receiving of corresponding double packets, i.e. such packets will be ignored and don't cause WAIT command (its analogs) to terminate on them.

RAND

PARAMETERS: no command

Specifies the random value for field.

PRECISEWAIT

PARAMETERS: no parameters

After the work of WAIT command (its analogs) all trace threads will be blocked until the next call to WAIT command. So there will be no missed packets between subsequent calls to WAIT command.

TRACE

PARAMETERS: <name of trace file>

Opens the given trace file for subsequent work with it.

EP

PARAMETERS: <type> <name of interface> <name of field> <field's value>

Defines an end point. While imitation of application's work the end point is a entity used for distinguishing between packets in trace file belonging to different sources (so they, for example, must be generated from different interfaces). All the packets for which the given <name of field> has the given <field's value> will belong to defined end point.

There are two <types> of end points: "torecv" (receiving ep) and "togen" (generating ep). Generating end points search their packets in trace file and generate them. receiving end points - wait for their packets. The packets from trace file are scanned in series. The generation can only be performed after receiving previous packets. The wait will be started after generation previous packets. The <unique name of interface> specifies the interface from which packets will be generated or waited. See "headers/configSession"

RUN

PARAMETERS: <base request> <list of packets>

This command starts imitation of application's work. Parameters to command specify the request to result of test. <Base request> may be: drop, any, accept. List of packets, for example: 1;2;3-5;7-. Minus at the end of list means expanding to last packet in trace file. List "any" is equal to "1-".

The result for packets from list must correspond to base request. The result for packets not from list must correspond to inverted base request. Ex: "run accept 1-" means "all packets must be accepted", "run drop 6-" means "all packets before 6 must be accepted, rest of packets - dropped", "run any any" means no requests. See "samples/convtest1"

WRITE

PARAMETERS: no parameters

Writes the trace file opened by TRACE command on disk

GETPAC

PARAMETERS: <number of packet>

Copies the specified packet from trace file to the buffer of current packet.

SETPAC

PARAMETERS: <number of packet>

Replaces the specified packet in trace file by the current packet.

INSPAC

PARAMETERS: <number of packet>

Insert the current packet in trace file, moving the all packets with given number and higher.

DELPAC

PARAMETERS: <number of packet>

Deletes the specified packet from trace file.

FULLMASK

PARAMETERS: no parameters

Fills the mask of packet so that the all fields will be included in mask. So while comparing packets the full packet's content will be compared. By default while describing packet's content the mask will be also added by new conditions, so the using of this command make sense only after the use of CLEARMASK command (this command is used in headers). It must be well realized that packets will be compared only by mask which is not always synchronized with packet's content.

IFR

PARAMETERS: <name of packet or status of last wait operation> "{" <block of script> "}" [ "else" "{" <second block of script> "}" ]

Processes the block of script if the last received packet (command WAIT, its analogs) has the given name (which was specified by command NAME). "timeout" may be specified as the name of packet what means that the block must be processed in the case of timeout. Command will not distinguish newly added packets and old ones if they have the same name. Take a note of it when using UNFIX command. See also CLEARREG command.

For tcp (udp) this command is also used to check the general status of last waiting operation. Status string "error" may be given to check if connection is closed already. Check for timeout or error may be also performed just after opening of connection by command OPEN. See samples/tcp_gateway, samples/http_client, samples/http_server.

PRINT

PARAMETERS: <message>

Displays the given message. Use symbol \n in message to indicate that line feed must be performed.

FILTER

PARAMETERS: <name of interface> <filter string>

Sets the fast low-level filter (which is used by tcpdump) for the given interface. The format of filter is described in libpcap (WinPcap) or tcpdump documentation. See "samples/my_gateway"

UNFIX

PARAMETERS: no parameters

By default after the work of WAIT command (its analogs) the statuses for all waited packets will be fixed, so there may be no packets to wait for the next call to WAIT. This command marks these old packets as newly added. The previous status for them will be lost. Take a note of that ALL old packets will be unfixed, so they will be waited: this may cause unexpected results. Consider the use of CLEARREG command.

WAITALL

PARAMETERS: no parameters

The analog of WAIT command. Doesn't add the previously defined packet to the list of waited ones. Starts waiting simply. Packets may be already added by ADD command (or using of UNFIX command).

CHTRACE

PARAMETERS: "{" <block of script> "}"

The given block of script may contain field's values definitions or command PRINT. These definitions will be applied to every packet from trace file which corresponds the mask described before the command.

COPYREC

PARAMETERS: no parameters

The received packet (see command WAIT, its analogs) will be copied to the buffer of current packet. Precision waiting must be first enabled (command PRECISEWAIT). See also NOTCOPYREC command.

FASTTEST

PARAMETERS: no parameters

Enables fasttest regime for packet filter test. See "samples/fasttest".

GETCH

PARAMETERS: no parameters

Waits for press <Enter>

NUMRET

PARAMETERS: <number of retransmitions>

While imitation of application's work if some packets have not been received for a long time (command TIMEOUT), then the previously generated packets will be retransmitted. One retransmission by default.

RM

PARAMETERS: <type> <name of field> <sought value> <value to set>

While imitation of application's work some values in packets from trace file may be automatically replaced before generating packet or before waiting one. So the <type> of replacement ("TORECV" or "TOGEN") instructs when the replacement must be applied: before generating packet or before forming the packet which will be waited.

So it is possible to generate one packet but wait another. It may be useful if packets are modified on their way.

The <name of field> specifies the field for which the replacement must be applied. The <sought value> is the value of field which will be sought in packets to replace it. It will be replaced by the given <value to set>. Some special values are allowed: "first" and "second". In this case the concrete value will be obtained from the first or second packet in trace file. See "headers/natConfigSession"

ARM

PARAMETERS: <name of field> <field's value>

Defines an adaptive replacement. This command gets two previously defined replacements (command RM), marks them as not active initially. While imitation of application's work program will wait for the first packet for which the given <name of field> has the given <field's value>. Then for each of two replacements program sets its <value to set>, copying it from the received packet, then marks replacements as active. So the test will be finally configured after receiving some packet only.

Note: from received packet will be obtained value of that field which has been specified for the first replacement. Then this value will be copied to <value to set> of second replacement.

See "headers/natConfigSession"

RANGE

PARAMETERS: <number of start packet> <number of stop packet>

While imitation of application's work the work will be performed with packets (from trace file) which are within the given range. Null value for start packet means first packet in file. Null value for stop packet means last packet in file.

HELP

PARAMETERS: <name of command> | <part of the field's name>

Displays the description of the command. The "all" value is available to display info about all commands. Also displays the list of fields which have the given string in their name.

TIMED

PARAMETERS: no parameters

Imitation of application's work will be implemented with considering time stamps from trace file. The test may become slower.

DEFAULTTEST

PARAMETERS: no parameters

Sets the default parameters for imitation of application's work (timeout, number of retransmitions, packets range, timed mode), removes all previously added end points (command EP) replacements (command RM), adaptive replacements (command ARM), cieves (command CIEVE). In short: full reset.

SETSIZE

PARAMETERS: <name of field> <decimal value of a new size of field>

Allows to specify the size for fields which don't have concrete size initially (strings). It can be also used to change the size for fields with concrete size (hexadecimal numbers). Value "any" may be used to specify the undefined size. A variable may be given so the size may be calculated before. See "samples/http_parser".

IF

PARAMETERS: <value1> <type of compare> <value2> "{" <first block of script> "}" [ "else" "{" <second block of script> "}" ]

Processes the first block of script if condition is met, otherwise processes the second block if it is specified. <Types of compare>: = (==), !=, >, <, >=, <=. Hexadecimals number are treated as strings (with 0x prefix). If you have problems try to watch how these values are represented by string using PRINT command for example.

CURPOS

PARAMETERS: no command

This special value allows to get the current value of byte pointer.

CURSIZE

PARAMETERS: no command

This special value allows to get the current size of packet.

GOTO

PARAMETERS: <value of any type> [<stop position>]

Performs the search of the given value in current packet. The search will be started from the current position of byte pointer. Value may have any type. The result of search is available through GOTORES keyword. In the case of successful search the byte pointer will be moved to the found entry. Stop position may be equal to -1. It means search to the end of packet. Stop position may be omitted but in this case parameters must be enclosed in brackets.

GOTOB

PARAMETERS: <value of any type> [<stop position>]

Is similar to GOTO command but performs back search.

GOTORES

PARAMETERS: no command

This is a special value which allows to get the result of last search performed by GOTO or GOTOB command. 1 - successful search, 0 - not successful search.

SETPOS

PARAMETERS: <field's name> <decimal value of a new position>

Sets a new position for the given field.

DECVAR

PARAMETERS: <name of variable> <value to subtract>

Analog of INCVAR. Subtracts the given value from variable.

BREAK

PARAMETERS: no parameters

Breaks the cycle caused by using CYC command.

TORECV

PARAMETERS: no command

This special word specifies that some entity must perform its function upon the receiving of a packet.

TOGEN

PARAMETERS: no command

This special word specifies that some entity must perform its function upon the sending of a packet.

FIRST

PARAMETERS: no command

This special value retrieves field's value from the first packet in trace file.

SECOND

PARAMETERS: no command

This special value retrieves field's value from the second packet in trace file.

CIEVE

PARAMETERS: <name of field>

Causes that while imitation of application's work the value of specified field will not be considered when comparing waited packet with receiving one.

IFNDEF

PARAMETERS: <name of entity> "{" <script's block> "}"

Executes block if given entity has not been defined (entity: variable, field, someone defined by GDEF or DEFINE commands).

CALLRES

PARAMETERS: no command

This special value allows to get the result of last system call (command SYSCALL). Only for UNIX.

MULVAR

PARAMETERS: <name of variable> <multiplier>

Multiply given variable by specified value.

DIVVAR

PARAMETERS: <name of variable> <divisor>

Divide given variable by specified value.

SENDWAIT

PARAMETERS: <requests>

Similar to SENDWAITOTHER command but also adds packet before it to wait list. Useful when you need to send a packet from one interface and receive the same one at another (when they are connected somehow).

NOTCOPYREC

PARAMETERS: no parameters

Reverses the action of COPYREC command.

CLEARREG

PARAMETERS: no parameters

Clears the information about all the packets which were added to the waited ones (by WAIT, ADD commands). They will not be displayed in final report (or in the report that is displayed by SHOWREP command). If this command is typed at the end of script then it omits the displaying of final report (sense there are no packets in it).

SHOWREP

PARAMETERS: no parameters

Displays a report which is the same as that displayed while program termination.

LASTRES

PARAMETERS: no command

This special value enables to get the last result of statistic analyzing performed by SHOWREP. 0 - successful, 2 - some discrepancy is found.

CURTIME

PARAMETERS: no command

This special value allows to get the current time.

PRINTL

PARAMETERS: <message>

Analog of PRINT command. Additionally performs the line feed.

FIXMASK

PARAMETERS: no parameters

Fixes the mask of packet so that the defining of field's values (also fields definitions) doesn't cause its changing.

UNFIXMASK

PARAMETERS: no parameters

Performs the action reversed to the action of FIXMASK

LOADVAR

PARAMETERS: <name of variable> <name of file>

Loads the file in variable's current value. The variable must have undefined size: use variables with string type or use SETSIZE command.

WRITEVAR

PARAMETERS: <name of variable> <name of file>

Writes variable's value to the file on disk.

IFDEF

PARAMETERS: <name of entity> "{" <script's block> "}"

Executes block if given entity has been defined (entity: variable, field, someone defined by GDEF or DEFINE commands).

PLAY

PARAMETERS: <name of wav file>

Windows only. Plays the specified sound, WAV-file. Sound system must be enabled. If the file is not found then default Windows sound will be played. If the file is in current folder or in standard system folder then the full path is not required (Media/<name>).

Under UNIX the sound will be played by PC speaker.

NEWLINEIS

PARAMETERS: <string>

Sets the string which must replace any original LF symbol while working with strings. See "samples/strings.fws"

SENDWAITOTHER

PARAMETERS: no parameters

Works similar to "SEND WAITALL" sequence. Purpose: make atomic operation. Without this command there would be a chance that a waited packet did not cause command WAITALL stop waiting if it was accepted after SEND but before WAITALL started waiting. However it would be registered as received in any case. This command should be always used when you need to send a request and RELIABLY receive a response on it never missing.

OPEN

PARAMETERS: <interface's type> <interface's name>

Opens interface of given type. Types: eth, ip, tcp, udp. For tcp this command will wait till connection with server is established or a client connection is accepted. For other types the command won't wait. See more in -d,-p,-T options.

CLOSE

PARAMETERS: <interface's name>

Closes interface with given name.

OR

PARAMETERS:

Alias of TOWAIT command.

ADD

PARAMETERS:

Alias of TOWAIT command.

RESET

PARAMETERS:

Deprecated. Use CLEARMASK

CLEAR

PARAMETERS:

Deprecated. Use CLEARHISTORY

RECV

PARAMETERS:

Analog of WAIT command. This command is more convenient to use when working with tcp(udp). It clears the mask of packet automatically so stops working after receiving any data. It also enables mode when received packet is copied to the buffer of current packet (COPYREC command).

RETURN

PARAMETERS:

Stops processing current file. If it was included in another file then processing will continue from that include command.

 

Integration with text editors

Text highlighting

Midnight commander editor for UNIX

Copy file "fw.syntax" to /usr/share/mc/syntax folder

Add the following record in file /usr/share/mc/syntax/Syntax

file ..\*\\.fws$ AnetTest\fwsFile

include fw.syntax

Context editor for Windows (www.contexteditor.org)

Copy file "anettest.chl" to "Program Files\ConTEXT\Highlighters" folder.

Notepad++

Copy userDefineLang.xml to AppData\Roaming\Notepad++ or copy only single UserLang tag to existing userDefineLang.xml file if it contains some other languages.

Auto-completion

Notepad++

Copy fws.xml to Program Files\Notepad++\plugins\APIs, enable auto-completion in settings (function completion) with parameters hint. To see the description of command type its name with opening bracket symbol then tooltip will be displayed.

 

For Developers

Compiling with MinGW.

Add gcc/g++ and make packages to MinGW.

Download binary WinPcap package and copy Lib\libwpcap.a to MinGW/lib.

Download sources WinPcap package, run create_include.bat and copy created \WpdPack\Include\ to MinGW/include.

Run

./configure && make.

Extending by new custom code.

See ExtendHelper in sources. You can add new commands, values' types, automatically calculated values (like tcpcrc), devices to access to network (or anything).