Contexts

With PacketShield, context is identified by the destination of an incoming packet.

For each incoming packet, a lookup on available contexts in the instance is performed:

• If a context is found (by matching the packet’s destination IP and an optional VLAN tag), then the rules of the context will be applied to this packet.
• If the packet does not match any context, then the default context Other applies.

Creating an instance automatically creates the default context named Other which contains the policy used for packets which do not match any other created context.

PacketShield currently supports the following context identifiers:

• IPv4 address
• IPV4 suffixed by the “at” character (@) and a VLAN id

Use sysfs entry Jump to heading #

You manage a context using the sysfs entry:

/sys/packetshield/<instance name>/contexts.

/sys/packetshield/<instance name>/contexts.

Create a context Jump to heading #

The create operation also creates a new sysfs directory using the context identifier as name in:

/sys/packetshield/<instance name>/<context id>.

/sys/packetshield/<instance name>/<context id>.

A newly created context does not inherit the configuration from the default Other context.

sysfs Jump to heading #

Write the context identifier, prefixed by the the plus sign character (+) in the sysfs entry.

Example: Create a context for the IP address 1.2.3.5:

nix
echo "+10.2.3.5" > /sys/packetshield/myinst/contexts

nix
echo "+10.2.3.5" > /sys/packetshield/myinst/contexts

Example: Create a context for the IP address 1.2.3.5 in the tagged VLAN 100:

nix
echo "+10.2.3.5@100" > /sys/packetshield/myinst/contexts

nix
echo "+10.2.3.5@100" > /sys/packetshield/myinst/contexts

GUI Jump to heading #

Use the statement <instance name>/contexts followed by the context identifier.

Example: Create a context for the IP address 1.2.3.5:

myinst/contexts 10.2.3.5

myinst/contexts 10.2.3.5

Example: Create a context for the IP address 1.2.3.5 in the tagged vlan 100:

myinst/contexts 10.2.3.5@100

myinst/contexts 10.2.3.5@100

Destroy a context Jump to heading #

This operation also deletes the sysfs directory /sys/packetshield/<instance name>/<context id>.

sysfs Jump to heading #

Write the context identifier, prefixed by the minus sign character (-) in the sysfs entry.

Example: Destroy the context for the IP address 1.2.3.5:

nix
echo "-10.2.3.5" > /sys/packetshield/myinst/contexts

nix
echo "-10.2.3.5" > /sys/packetshield/myinst/contexts

Example: Destroy the context for the IP address 1.2.3.5 in the tagged VLAN 100:

nix
echo "-10.2.3.5@100" > /sys/packetshield/myinst/contexts

nix
echo "-10.2.3.5@100" > /sys/packetshield/myinst/contexts

GUI Jump to heading #

Remove the statement <instance name>/contexts <context id> that matches the context you want to remove.

List contexts Jump to heading #

This function is only available through the CLI.

To list existing contexts, open the contents of the sysfs entry /sys/packetshield/<instance name>/contexts.

One context identifier is displayed per line.

Although not listed, the context Other exists.

Example:

nix
cat /sys/packetshield/myinst/contexts

nix
cat /sys/packetshield/myinst/contexts

output
text
10.2.3.5
10.2.3.5@100

output
text
10.2.3.5
10.2.3.5@100

Set context options Jump to heading #

sysfs Jump to heading #

Display and set context options using read and write operations, respectively, on sysfs entries available in the directory /sys/packetshield/<instance name>/<context id>/<option>

GUI Jump to heading #

Set context options using the following statement:

<instance name>/<context id>/<option>

<instance name>/<context id>/<option>

The GUI can only set options, not read them.

Options Jump to heading #

Available options:

drop_empty_ack Jump to heading #

• default: 0, no drop

  • Ratio of empty outgoing ACKs to drop.
  • The purpose of this setting is to prevent ACK storms.

sysfs example
nix
echo 100 > /sys/packetshield/myinst/Other/drop_empty_ack

sysfs example
nix
echo 100 > /sys/packetshield/myinst/Other/drop_empty_ack

GUI example
myinst/Other/drop_empty_ack 100

GUI example
myinst/Other/drop_empty_ack 100

gateway Jump to heading #

• default: ff:ff:ff:ff:ff:ff

  • Destination MAC address for outgoing traffic.
  • By default, PacketShield uses the source MAC address from incoming packets as destination when generating SYN cookies.
  • Setting this value to a valid MAC address allows PacketShield to use an alternative gateway to send generated SYN cookies.

sysfs example
nix
echo '01:0c:23:fe:ab:10' > /sys/packetshield/myinst/Other/gateway

sysfs example
nix
echo '01:0c:23:fe:ab:10' > /sys/packetshield/myinst/Other/gateway

GUI example
myinst/Other/gateway 01:0c:23:fe:ab:10

GUI example
myinst/Other/gateway 01:0c:23:fe:ab:10

new_cookie_threshold Jump to heading #

• default: 0-0, disabled

  • Defines new-connections rate thresholds (per seconds) to enable / disable SYN cookie protection for TCP.
  • The purpose of this protection mode is to block SYN floods for TCP.
  • Applies to ports listed in protected TCP ports.

Example: To start sending SYN cookies when the incoming rate is above 10000 SYN/s and disable sending when the rate goes below 5000:

sysfs example
nix
echo '10000-5000' > /sys/packetshield/myinst/Other/new_cookie_threshold

sysfs example
nix
echo '10000-5000' > /sys/packetshield/myinst/Other/new_cookie_threshold

GUI example
myinst/Other/new_cookie_threshold 10000-5000

GUI example
myinst/Other/new_cookie_threshold 10000-5000

new_cookie_threshold Jump to heading #

• default: 0-0, disabled

  • Defines new-connections rate thresholds (per seconds) to enable / disable SYN cookie protection for TCP or HAProxy’s QUIC retry packets protection for UDP.
  • The purpose of this protection mode is to block SYN floods for TCP or QUIC INIT/0-RTT packet floods for UDP.
  • Applies to ports listed in protected TCP ports or protected UDP ports.

Example: To start sending SYN cookies when the incoming rate is above 10000 SYN/s and disable sending when the rate goes below 5000:

sysfs example
nix
echo '10000-5000' > /sys/packetshield/myinst/Other/new_cookie_threshold

sysfs example
nix
echo '10000-5000' > /sys/packetshield/myinst/Other/new_cookie_threshold

GUI example
myinst/Other/new_cookie_threshold 10000-5000

GUI example
myinst/Other/new_cookie_threshold 10000-5000

unmatch_drop_threshold Jump to heading #

• default: 0-0, protection is disabled

  • Defines unmatched-packets rate (per seconds) thresholds to enable / disable unmatched RST/ACK drop for TCP.
  • The purpose of this protection mode is to block RST or ACK floods (RSTs or ACKs that do not match any known session).
  • Applies to ports listed in protected TCP ports.

Example: To start blocking unmatched packets when the incoming rate is above 10000/s and disable blocking when the rate goes below 5000:

sysfs example
nix
echo '10000-5000' > /sys/packetshield/myinst/Other/unmatch_drop_threshold

sysfs example
nix
echo '10000-5000' > /sys/packetshield/myinst/Other/unmatch_drop_threshold

GUI example
myinst/Other/unmatch_drop_threshold 10000-5000

GUI example
myinst/Other/unmatch_drop_threshold 10000-5000

unmatch_drop_threshold Jump to heading #

• default: 0-0, protection is disabled

  • Defines unmatched-packets rate (per seconds) thresholds to enable / disable unmatched RST/ACK drop for TCP or QUIC handshake and short header packets drop for UDP.
  • The purpose of this protection mode is to block RST or ACK floods (RSTs or ACKs that do not match any known session) or QUIC handshake/short header packet floods for UDP.
  • Applies to ports listed in protected TCP ports or protected UDP ports.

Example: To start blocking unmatched packets when the incoming rate is above 10000/s and disable blocking when the rate goes below 5000:

sysfs example
nix
echo '10000-5000' > /sys/packetshield/myinst/Other/unmatch_drop_threshold

sysfs example
nix
echo '10000-5000' > /sys/packetshield/myinst/Other/unmatch_drop_threshold

GUI example
myinst/Other/unmatch_drop_threshold 10000-5000

GUI example
myinst/Other/unmatch_drop_threshold 10000-5000

unknown_ttlfilter_threshold Jump to heading #

• default: 0-0, protection is disabled

  • Defines unknown TTL packets rate (per seconds) thresholds to enable or disable filtering based on TTL
  • Applies to ports listed in protected TCP ports

Example: To start blocking packets with unknown TTL when the incoming rate is above 10000/s and disable blocking when the rate goes below 5000:

sysfs example
nix
echo '10000-5000' > /sys/packetshield/myinst/Other/unknown_ttlfilter_threshold

sysfs example
nix
echo '10000-5000' > /sys/packetshield/myinst/Other/unknown_ttlfilter_threshold

GUI example
myinst/Other/unknown_ttlfilter_threshold 10000-5000

GUI example
myinst/Other/unknown_ttlfilter_threshold 10000-5000

deliver_block_threshold Jump to heading #

• default: 0-0, protection is disabled

  • Defines delivered packets rate (per seconds) thresholds to enable or disable surge protection (those packets dropped instead of being filtered).
  • This filter affects each packet regardless of the status of the protected port

Example: To enable surge protection when outgoing rate is above 10000 packets/s and disable protection when the rate goes below 5000:

sysfs example
nix
echo '10000-5000' > /sys/packetshield/myinst/Other/deliver_block_threshold

sysfs example
nix
echo '10000-5000' > /sys/packetshield/myinst/Other/deliver_block_threshold

GUI example
myinst/Other/deliver_block_threshold 10000-5000

GUI example
myinst/Other/deliver_block_threshold 10000-5000

context_capture Jump to heading #

• default: 0, disabled

  • Defines whether incoming packets on current context are captured.
  • To enable packet capture, set this value to 1.

See the Context capture section for details.

Example: Enable capture of incoming packets for this context.

sysfs example
nix
echo 1 > /sys/packetshield/myinst/Other/context_capture

sysfs example
nix
echo 1 > /sys/packetshield/myinst/Other/context_capture

GUI example
myinst/Other/context_capture 1

GUI example
myinst/Other/context_capture 1

x_tcp_ecn Jump to heading #

• default: 0, disabled

  • Defines whether Explicit Congestion Notification (ECN) is available for SYN+ACK emitted packets from x_tcp_ports.
  • To enable ECN support, set this value to 1.

Example: Enable ECN support for the context.

sysfs example
nix
echo 1 > /sys/packetshield/myinst/Other/x_tcp_ecn

sysfs example
nix
echo 1 > /sys/packetshield/myinst/Other/x_tcp_ecn

GUI example
myinst/Other/x_tcp_ecn 1

GUI example
myinst/Other/x_tcp_ecn 1

x_tcp_mss Jump to heading #

• default: 1460

  • Defines the Maximum Segment Size (MSS) used for SYN+ACK emitted packets from x_tcp_ports.

Example: Set MSS to 1380.

sysfs example
nix
echo 1380 > /sys/packetshield/myinst/Other/x_tcp_mss

sysfs example
nix
echo 1380 > /sys/packetshield/myinst/Other/x_tcp_mss

GUI example
myinst/Other/x_tcp_mss 1380

GUI example
myinst/Other/x_tcp_mss 1380

x_tcp_sack Jump to heading #

• default: 0, disabled

  • Defines whether Selective Acknowledgement (SACK) is available for SYN+ACK emitted packets from x_tcp_ports.
  • To enable SACK support, set this value to 1.

Example: Enable SACK.

sysfs example
nix
echo 1 > /sys/packetshield/myinst/Other/x_tcp_sack

sysfs example
nix
echo 1 > /sys/packetshield/myinst/Other/x_tcp_sack

GUI example
myinst/Other/x_tcp_sack 1

GUI example
myinst/Other/x_tcp_sack 1

x_tcp_timestamps Jump to heading #

• default: 0, disabled

  • Defines whether timestamps are available for SYN+ACK emitted packets from x_tcp_ports.
  • To enable timestamp support, set this value to 1.

Example: Enable timestamp support.

sysfs example
nix
echo 1 > /sys/packetshield/myinst/Other/x_tcp_timestamps

sysfs example
nix
echo 1 > /sys/packetshield/myinst/Other/x_tcp_timestamps

GUI example
myinst/Other/x_tcp_timestamps 1

GUI example
myinst/Other/x_tcp_timestamps 1

x_tcp_wscale Jump to heading #

• default: none, no window scale support

  • Defines the window scale factor for SYN+ACK emitted packets from x_tcp_ports.
  • To enable window scale support, set this value to the desired window scale factor (0 - 14).

Example: Set window scaling to 14 for 1 GB/s network.

sysfs example
nix
echo 14 > /sys/packetshield/myinst/Other/x_tcp_wscale

sysfs example
nix
echo 14 > /sys/packetshield/myinst/Other/x_tcp_wscale

GUI example
myinst/Other/x_tcp_wscale 14

GUI example
myinst/Other/x_tcp_wscale 14

geoip_policy Jump to heading #

• default: none

  • Defines the policy for countries listed in the countries option (based on source IP).

  • Possible values, one of:

    • deny_countries

      Packets coming from any of the specified countries are dropped. Others are submitted to the PacketShield filtering process.

    • allow_countries

      Packets coming from any of the specified countries are submitted to the PacketShield filtering process. Others are dropped.

  • Use the countries option to specify countries to which the policy should be applied.

Example: Specify that only the countries specified in countries option will be allowed. Others will be blocked.

sysfs example
nix
echo allow_countries > /sys/packetshield/myinst/Other/geoip_policy

sysfs example
nix
echo allow_countries > /sys/packetshield/myinst/Other/geoip_policy

GUI example
myinst/Other/geoip_policy allow_countries

GUI example
myinst/Other/geoip_policy allow_countries

countries Jump to heading #

• default: none

  • Specify which countries should be handled according to the geoip_policy setting.

    • If geoip_policy is set to allow_countries, packets from these countries (or IP sets) are allowed and others are dropped.
    • If geoip_policy is set to deny_countries, packets from these countries (or IP sets) are dropped and others are allowed.

  • Countries are typically ISO 3166-1-alpha-2 country codes as supplied by geolocation services such as MaxMind or GeoIP.

  • Add/remove a country code using the prefix +/-.

Example: Set policy to deny_countries. Deny Russia and Colombia and allow others.

sysfs example
nix
echo deny_countries > /sys/packetshield/myinst/Other/geoip_policy
echo +CO > /sys/packetshield/myinst/Other/countries
echo +RU > /sys/packetshield/myinst/Other/countries

sysfs example
nix
echo deny_countries > /sys/packetshield/myinst/Other/geoip_policy
echo +CO > /sys/packetshield/myinst/Other/countries
echo +RU > /sys/packetshield/myinst/Other/countries

GUI example
myinst/Other/geoip_policy deny_countries
myinst/Other/countries CO,RU

GUI example
myinst/Other/geoip_policy deny_countries
myinst/Other/countries CO,RU

Optional: You can replace country codes with your own IP ranges or define your own non-standard codes. Enclose them in braces ({ }) and submit using awk.

• Changes made in braces using this method occur as an atomic change to the geoip4/geoip6 database residing at the instance level.
• Each entry in the list defines a single code. The code covers all IP addresses from the one specified in the entry up to but not including the next IP address in the list.

Example: The following file represents two ranges:

• Code US includes all IP addresses from 1.2.3.0 to 1.2.3.8.
• Code CA includes 1.2.3.9.

nix
cat mybase.4

nix
cat mybase.4

output
text
1.2.3.0    US
1.2.3.9    CA

output
text
1.2.3.0    US
1.2.3.9    CA

Example: The following command line submits the mybase.4 entries in a single atomic operation.

nix
awk 'BEGIN { print "{" ; fflush(); } { print $0; fflush(); } \
  END { print "}"; fflush();}' \
  mybase.4 > /sys/packetshield/myinst/Other/geoip4

nix
awk 'BEGIN { print "{" ; fflush(); } { print $0; fflush(); } \
  END { print "}"; fflush();}' \
  mybase.4 > /sys/packetshield/myinst/Other/geoip4

icmp_rate_max Jump to heading #

• default: 0, unlimited rate

  • Defines the maximum allowed rate of ICMP packets per second.

Example: Set the maximum ICMP rate to 1000/s.

sysfs example
nix
echo 1000 > /sys/packetshield/myinst/Other/icmp_rate_max

sysfs example
nix
echo 1000 > /sys/packetshield/myinst/Other/icmp_rate_max

GUI example
myinst/Other/icmp_rate_max 1000

GUI example
myinst/Other/icmp_rate_max 1000

dsr_mode Jump to heading #

• default: 0, classic mode

  • Enables the Direct Server Return (DSR) degraded mode. Sessions are created in incoming SYN packets and refreshed upon receiving a matching ACK/RST. If ACK and RST do not match a session, they are dropped if the unmatch_drop_threshold is reached.
  • To enable this mode, set this value to 1.

Example: Enable DSR mode.

sysfs example
nix
echo 1 > /sys/packetshield/myinst/Other/dsr_mode

sysfs example
nix
echo 1 > /sys/packetshield/myinst/Other/dsr_mode

GUI example
myinst/Other/dsr_mode 1

GUI example
myinst/Other/dsr_mode 1

cluster_secret Jump to heading #

• default: none

  • Defines the shared secret for use with the haproxy instance to identify sessions and validate tokens for haproxy’s QUIC protocol protection.

Example: Define the shared secret ABCDEF0123456789.

sysfs example
nix
echo 'ABCDEF0123456789' > /sys/packetshield/myinst/Other/cluster_secret

sysfs example
nix
echo 'ABCDEF0123456789' > /sys/packetshield/myinst/Other/cluster_secret

GUI example
myinst/Other/cluster_secret 'ABCDEF0123456789'

GUI example
myinst/Other/cluster_secret 'ABCDEF0123456789'

Context protection togglers Jump to heading #

A context protection toggler is a list of contexts having a specific protection. Use togglers to list, enable, and disable protections for contexts.

Add a context to a toggler using the plus sign prefix (+). Remove a context from a toggler using the minus sign prefix (-).

The togglers are:

new_cookie_toggled Jump to heading #

• List contexts protected against SYN floods using SYN cookies.

Example: Enable SYN flood protection for context 1.2.3.4:

sysfs example
nix
echo '+1.2.3.4' > /sys/packetshield/myinst/Other/new_cookie_toggled

sysfs example
nix
echo '+1.2.3.4' > /sys/packetshield/myinst/Other/new_cookie_toggled

GUI example
myinst/Other/new_cookie_toggled 1.2.3.4

GUI example
myinst/Other/new_cookie_toggled 1.2.3.4

new_cookie_toggled Jump to heading #

• List contexts protected against SYN floods using SYN cookies or QUIC INIT/0-RTT packet floods using QUIC retry packets.

Example: Enable SYN flood protection for context 1.2.3.4:

sysfs example
nix
echo '+1.2.3.4' > /sys/packetshield/myinst/Other/new_cookie_toggled

sysfs example
nix
echo '+1.2.3.4' > /sys/packetshield/myinst/Other/new_cookie_toggled

GUI example
myinst/Other/new_cookie_toggled 1.2.3.4

GUI example
myinst/Other/new_cookie_toggled 1.2.3.4

unmatch_drop_toggled Jump to heading #

• List contexts protected against ACK/RST floods.

Example: Enable ACK/RST flood protection for context 1.2.3.4:

sysfs example
nix
echo '+1.2.3.4' > /sys/packetshield/myinst/Other/unmatch_drop_toggled

sysfs example
nix
echo '+1.2.3.4' > /sys/packetshield/myinst/Other/unmatch_drop_toggled

GUI example
myinst/Other/unmatch_drop_toggled 1.2.3.4

GUI example
myinst/Other/unmatch_drop_toggled 1.2.3.4

unmatch_drop_toggled Jump to heading #

• List contexts protected against ACK/RST floods or QUIC handshake/short header packet floods.

Example: Enable ACK/RST (or QUIC handshake/short header packet) flood protection for context 1.2.3.4:

sysfs example
nix
echo '+1.2.3.4' > /sys/packetshield/myinst/Other/unmatch_drop_toggled

sysfs example
nix
echo '+1.2.3.4' > /sys/packetshield/myinst/Other/unmatch_drop_toggled

GUI example
myinst/Other/unmatch_drop_toggled 1.2.3.4

GUI example
myinst/Other/unmatch_drop_toggled 1.2.3.4

unknown_ttlfilter_toggled Jump to heading #

• List contexts protected against unknown TTL value.

Example: Disable unknown TTL protection in context 1.2.3.4:

sysfs example
nix
echo '-1.2.3.4' > /sys/packetshield/myinst/Other/unknown_ttlfilter_toggled

sysfs example
nix
echo '-1.2.3.4' > /sys/packetshield/myinst/Other/unknown_ttlfilter_toggled

GUI example
myinst/Other/unknown_ttlfilter_toggled 1.2.3.4

GUI example
myinst/Other/unknown_ttlfilter_toggled 1.2.3.4

deliver_block_toggled Jump to heading #

• List contexts protected against packet surges.

Example: Enable packet surge protection for context 1.2.3.4:

sysfs example
nix
echo '+1.2.3.4' > /sys/packetshield/myinst/Other/deliver_block_toggled

sysfs example
nix
echo '+1.2.3.4' > /sys/packetshield/myinst/Other/deliver_block_toggled

GUI example
myinst/Other/deliver_block_toggled 1.2.3.4

GUI example
myinst/Other/deliver_block_toggled 1.2.3.4

Context capture Jump to heading #

The sysfs entry /sys/packetshield/<instance>/context_capture.map provides the interface to retrieve a context’s packet capture. A read operation on this sysfs entry returns the size of packets captured available in a memory slot (4 bytes). An mmap on the same file descriptor using this size provide direct access (via pointer) to a full slot. This slot is split into chunks. A chunk provides packets captured on the same context.

Chunk header format:

output
text
0                   1                   2                   3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+                   Reserved                    |  Inet family  +
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+                                                               +
+-                                                             -+ 
+                                                               +
+-                    Layer3 address                           -+
+                                                               +
+-                                                             -+
+                                                               +
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+     Layer 4 address (port)    |         VLAN id               +
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+                     Payload length                            +
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

output
text
0                   1                   2                   3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+                   Reserved                    |  Inet family  +
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+                                                               +
+-                                                             -+ 
+                                                               +
+-                    Layer3 address                           -+
+                                                               +
+-                                                             -+
+                                                               +
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+     Layer 4 address (port)    |         VLAN id               +
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+                     Payload length                            +
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

The Inet family field is set to 0 to indicate the Other context.