An instance defines entry points (physical interfaces) in PacketShield and one or more applicable rule sets (context).

  • An instance is designated by a name.

  • Each instance owns its own session table and configuration.

Note

The keywords instances and version are reserved and cannot be used as an instance name.

Use sysfs entry

You manage instances using the sysfs entry /sys/packetshield/instances.

Create an instance

Using the GUI

Use the statement instances followed by the <instance name>.

instances myinst

Using sysfs

Write +<instance name> in the sysfs entry.

$ echo "+myinst" > /sys/packetshield/instances

Destroy an instance

Warning

When you destroy an instance, you also destroy all its configuration, contexts, and statistics and detach all attached network interfaces.

Using the GUI

Remove the instances line that creates it.

Using sysfs

Write -<instance name> in the sysfs entry.

$ echo "-myinstance" > /sys/packetshield/instances

List a currently configured instance

This function is only available using the CLI.

Read the content of the file /sys/packetshield/instances.

$ cat /sys/packetshield/instances
myinst3
myinst2
myinst1

Set options

sysfs

Display and set options using respectively read / write operations on sysfs files present in the directory /sys/packetshield/<instance name>/<option>.

$ echo 30 > /sys/packetshield/myinst/ack_session_timeout
$ echo 4 > /sys/packetshield/myinst/syn_session_timeout

GUI

Configure options using the following scheme: <instance name>/<option> followed by the desired parameter value.

myinst/ack_session_timeout 30
myinst/syn_session_timeout 4

The following options are available:

Option

Default

Description

ack_session_timeout

60 s

When an ACK packet arrives, the corresponding session is considered invalid if the elapsed time since the previous packet is greater than this value

syn_session_timeout

10 s

When a SYN packet arrives, the corresponding session is considered invalid if the elapsed time since the previous packet is greater than this value

rst_session_timeout

60 s

When an RST packet arrives, the corresponding session is considered invalid if the elapsed time since the previous packet is greater than this value

dns_session_timeout

60 s

When a DNS response packet arrives, the corresponding session is considered invalid if the elapsed time since the corresponding DNS request is greater than this value

Get instance statistics

This function is only available using CLI.

You can get an instance's statistics counters using the sysfs entry /sys/packetshield/<instance name>/stats.

$ cat /sys/packetshield/myinst/stats
rx_total  : 56741
capmissed : 56502
tx_total  : 11329

rx_total

total incoming packets on current instance

tx_total

total outgoing packets on current instance (except packets generated by PacketShield like syncookies)

capmissed

incoming packets not copied to debugging capture slots

Note

During a capture dump, if the capmissed statistic continues to rise, it means that the capture reader does not read fast enough and some packets are not captured because the slots are full.

Debug instance

This function is only available using CLI.

PacketShield provides an interface to retrieve all incoming packets capture on an instance.

This interface is available in the directory /sys/packetshield/<instance name>/

raw.cap

This sysfs entry is directly readable and provides capture in pcap format.

 
$ tcpdump -r /sys/packetshield/myinst/raw.cap
reading from file raw.cap, link-type EN10MB (Ethernet)

This interface does not give the best performances because:

  • A sysfs read operation is limited and cannot return more that one page size (4096 Bytes).

  • A read operation induces a memory copy of all packets capture.

Note

PacketShield uses a limited number of recycled memory slots to capture packets. If the reader is not fast enough, all slots are used and some packets will not be captured.