Netfilter Simulation Environment

The --failtest option runs the script, but deliberately inserts failures (currently allocation failures and user-copying failures). At each potential failure, both failure and success will be simulated: where we fail, the script will no doubt fail later which is OK, but we ensure that the entire system doesn't fall over or leak memory. If an error is found, the path of successes/failures will be printed out, which can be replayed using --failpath

Given a failure path, (from --failtest), this will replay the sequence of sucesses/failures, allowing debugging. The input should be the same as the original which caused the failure.

This testing can be slow, but allows for testing of failure paths which would otherwise be very difficult to test automatically.

Sometimes code deliberately ignores the failures of a certain function. This suppresses complaints about that for any functions containing this name.

nfsim will echo each command before it is executed. Useful when commands are read from a file

Causes nfsim to reduce its output to the minimum possible - no prompt is displayed, and most warning messages are suppressed

If --exit is specified, nfsim will exit (with a non-zero error code) on the first script error it encounters (eg an expect command does not match). This is useful when nfsim is invoked as a non-interactive script

Usually all netfilter modules are loaded on startup, this option will suppress this behaviour. To load modules after invoking nfsim with this argument, use the insmod command

Causes nfsim to print its command line arguments and then exit

Prior to 2.6.10, there were many bugs involving nonlinear packets. Suppressing them allows testing for other bugs.

The --ignore-proc-issues can be used to suppress failure due to removing non-existent proc entries and leaving proc files behind, which happened in 2.6.10 and previous.

Displays general help, or help for a specified command

With no arguments, help will show general system help, and list the available commands. If an argument is specified, then help will show help for that command, if available.

Exit the simulator

The exit and quit commands are synonomous. They both exit the simulator.

Manage logging settings

Each log message is classified into one of the following types:

The log command allows you to select which messages are displayed. By default, all messages will be shown.

If the types argument is prefixed with a +, - or = character, those types will be added, removed or set as the current types of messages to be logged (repectively). If none of these characters is specified, = is assumed (the types are set to only those specified)

Messages generated as a result of user input are always logged.

Catch logging information for automated testing

expect will set up a set of patterns to expect in logging messages for a particular command. If that command finishes without matching the specified pattern, the simulator will exit with a non-zero return value. After the command is run, all expectations on that command are deleted.

expect with no arguments will print out the current list of expectations, as a command and a pattern.

expect command pattern will expect the specified pattern to occur the next time command is invoked. If an '!' appears before the command, then the expectation is negated - if the pattern appears in the output, then the simulator will exit with an error

The pattern itself is similar to a simple shell wildcard, except whitespace is loosely matched. The * character will match any a string of any length.

Run the iptables command on the simulator

The external iptables binary will be invoked, with its operations redirected to the simulator. If the NFSIM_IPTABLES_PREFIX environment variable is set, the command in that directory will be executed (useful for testing specific variants). Otherwise, the current PATH is searched, then /usr/local/sbin, /sbin, /usr/sbin.

You do not need to be root to use iptables in this way. If the iptables command fails, that will be reported as

iptables: command failed

; with the [-e] to nfsim, nfsim will abort.

Manipulate the IPv4 routing table.

route with no arguments, or a single argument "print" will display the current routing table.

route del network will delete the route to the sepecified network.

route add network interface will add a route to the sepecified network, via the specified interface.

Query or advance the kernel time

time with no arguments will show the current kernel time (in seconds).

time time will set the kernel time to time - which must be greater than the current time value. time +advance will increment the time by the value of advance, which must be positive.

When the kernel time is incremented, kernel timers may be triggered. If so, the simulator will show logging messages:

> time +30
running timer to ip_conntrack_core.c:init_conntrack()
>

The time +infinity command will forward time past all the currently pending timers, leaving a clean slate.

Insert simple netfilter hooks

The hook command allows new hooks to be inserted. These hooks will simply return the specified verdict for all packets.

All hooks are cleared after the next gen_ip command.

The hookname argument specifies which list to insert the hook into. One of IP_PRE_ROUTING, IP_INPUT, IP_FORWARD, IP_OUTPUT, IP_POST_ROUTING

The priority argument specifies the priority of the hook, from INT_MIN to INT_MAX.

The verdict argument specifies the verdict to return from the hook itself: ACCEPT, DROP, QUEUE, STOLEN, REPEAT

Generate IP packets and send through the protocol layers

gen_ip will construct an IP packet and send it on the specified interface, or if no interface is specified, the packet will be sent from as if from the local host.

If [protocol] is TCP, then the ports and TCP flags must be specified. The format of the [flags] is 'SYN/ACK' etc. The format of the [OPT=] option is a comma-separated list of numbers, and there must be a multiple of four of them, such as:

1,2,3,4

. If DATA is specified, then the data of the packet will be populated with the rest of the arguments, with escapes for \n, \r, \t and \0.

If [protocol] is UDP then the ports must be specified.

If [protocol] is ICMP then the type and code must be specified: the id and sequence fields are optional.

Displays and set /proc filesystem information

proc with no arguments will print the heirachy of the currently-registered proc files.

proc cat file will display the contents of the proc file specified.

proc write file args.. will write args to the proc file.

Generate an ICMP error packet and send it through the protocol layers

gen_err will use gen_ip to construct an IP packet, generate an ICMP error for that packet, as would be generated by a host at [srcip], then send it on the specified interface. If no interface is specified, the packet will be sent from as if from the local host. The [length] is the number of bytes to include from the original packet, default 28.

See gen_ip for how to specify the options for the initial packet.

Print out the kernel configuration used to build nfsim

This command is mainly used for scripts to determine what modules and/or features are available.

Print a message

echo prints a message.

Report information about all system calls and user-kernel copies

strace will report all system calls from iptables, and all copy_to_user and copy_from_user results. This is useful for debugging iptables, and checking that the kernel is returning the right error values.

Tracing will continue until the [off] argument is given.

Administer the simulated network interfaces. Interfaces can be brought up or down, or reconfigured while up.

At present, interfaces can be assigned only one interface (this limitiation is due solely to the ifconfig tool; the simulated kernel environment can handle multiple interface addresses)

If ifconfig is invoked with no arguments, it will show the configuration of all devices. If a single argument is specified, it is assumed to be a device name, and the configuration for that device is displayed.

To bring a new interface up, specify the interface name and a network specification:

ifconfig eth2 10.0.0.1 8 10.255.255.255 up

Alternatively, the netmask can be specified in dotted-decimal notation. This command is equivalent to the previous:

ifconfig eth2 10.0.0.1 mask 255.0.0.0 10.255.255.255 up

Interfaces can be brought down with the command

To reconfigure an interface, use the syntax

Manage the userspace packet queue

When a netfitler hook returns NF_QUEUE, it is stored within the simulator's own packet queue. When a packet enters this queue, a logging message is printed:

> gen_ip IF=eth0 192.168.0.2 192.168.0.1 50 udp 10 20
rcv:eth0
queue:added {IPv4 192.168.0.2 192.168.0.1 50 17 10 20}

The packet is assigned a unique id number (monotonically increasing over the life of the simulator session), which can be used to reinject packets in any order

The contents of the packet queue can be printed with the queue command with no arguments. Each packet in the queue is prefixed with its id:

> queue
0: {IPv4 192.168.0.2 192.168.0.1 50 17 10 20}
1: {IPv4 192.168.1.10 192.168.0.1 50 6 1025 80 SYN}

To reinject a packet from the queue, specify a verdict (one of the netfilter hook return values, for example NF_ACCEPT), and optionally, the id of the packet. If no id is specified, the packet at the front of the queue is reinjected.

Displays version information about the kernel simulator.

The version displays information about the nfsim version and the version of the kernel it's simulating. With the [kernel] argument, it only displays the version of the kernel (useful for testsuites).

List modules (both available and loaded)

lsmod lists all the loaded modules, one to a line.

Insert a module

insmod loads a module, or all modules. The caller must ensure that any other module this one expects are already loaded.

Remove a module

rmmod removes a loaded module. The caller must ensure that any module which is using this is already unloaded.

Generate TCP session

tcpsession is shorthand for creating a TCP session using multiple gen_ip commands. The four-argument [OPEN] form creates a simple connection (no NAT expected), the eight-argument form creates a connection which might be NATted. You can only have one open connection at a time: this is used for all operations. Sequence numbers will be 1001 for the sender, and 2001 for the recipient. Initial packet comes in eth0, replies come in eth1.

The [DATA] form sends data on the current connection, in a single packet (and sends an ACK in reply). [direction] is either 'original' or 'reply'.

The [LENCHANGE] command sets expected change in length of the next packet. It is used to tell tcpsession that the next packet is going to expected to be shortened or lengthened.

The [CLOSE] form sends the required FIN and ACK packets to close the connection: [direction] specifies who initiates the close.

The [ABANDON] argument causes the connection to simply be forgotten, so you can open a new one.

Displays information about the kernel simulator.

The subject argument to info must be one of the following: