HAProxy ALOHA Documentation 15.5

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

You manage a context using the sysfs entry:

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

Create a context

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

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

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

sysfs

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

Create a context for the IP address 1.2.3.5:

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

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

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

GUI

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

Create a context for the IP address 1.2.3.5:

myinst/contexts 10.2.3.5

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

myinst/contexts 10.2.3.5@100

Destroy a context

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

sysfs

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

Destroy the context for the IP address 1.2.3.5:

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

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

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

GUI

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

List contexts

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.

$ cat /sys/packetshield/myinst/contexts
10.2.3.5
10.2.3.5@100

Set context options

sysfs

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

Set context options using the following statement:

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

The GUI can only set options, not read them.

Options

Available options:

drop_empty_ack

default: 0, no drop

  • Ratio of empty outgoing ACKs to drop.

  • The purpose of this setting is to prevent ACK storms.

sysfs example

$ echo 100 > /sys/packetshield/myinst/Other/drop_empty_ack

GUI example

myinst/Other/drop_empty_ack 100

gateway

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

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

GUI example

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

new_cookie_threshold

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.

sysfs example

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

$ echo '10000-5000' > /sys/packetshield/myinst/Other/new_cookie_threshold

GUI example

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

myinst/Other/new_cookie_threshold 10000-5000

unmatch_drop_threshold

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.

sysfs example

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

$ echo '10000-5000' > /sys/packetshield/myinst/Other/unmatch_drop_threshold

GUI example

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

myinst/Other/unmatch_drop_threshold 10000-5000

unknown_ttlfilter_threshold

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

sysfs 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:

$ echo '10000-5000' > /sys/packetshield/myinst/Other/unknown_ttlfilter_threshold

GUI 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:

myinst/Other/unknown_ttlfilter_threshold 10000-5000

deliver_block_threshold

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

sysfs example

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

$ echo '10000-5000' > /sys/packetshield/myinst/Other/deliver_block_threshold

GUI example

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

myinst/Other/deliver_block_threshold 10000-5000

context_capture

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.

sysfs example

Enable capture of incoming packets for this context.

$ echo 1 > /sys/packetshield/myinst/Other/context_capture

GUI example

Enable capture of incoming packets for this context.

myinst/Other/context_capture 1

x_tcp_ecn

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.

sysfs example

Enable ECN support for the context.

$ echo 1 > /sys/packetshield/myinst/Other/x_tcp_ecn

GUI example

Enable ECN support for the context.

myinst/Other/x_tcp_ecn 1

x_tcp_mss

default: 1460

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

sysfs example

Set MSS to 1380.

$ echo 1380 > /sys/packetshield/myinst/Other/x_tcp_mss

GUI example

Set MSS to 1380.

myinst/Other/x_tcp_mss 1380

x_tcp_sack

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.

sysfs example

Enable SACK.

$ echo 1 > /sys/packetshield/myinst/Other/x_tcp_sack

GUI example

Enable SACK.

myinst/Other/x_tcp_sack 1

x_tcp_timestamps

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.

sysfs example

Enable timestamp support.

$ echo 1 > /sys/packetshield/myinst/Other/x_tcp_timestamps

GUI example

Enable timestamp support.

myinst/Other/x_tcp_timestamps 1

x_tcp_wscale

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).

sysfs example

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

$ echo 14 > /sys/packetshield/myinst/Other/x_tcp_wscale

GUI example

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

myinst/Other/x_tcp_wscale 14

geoip_policy

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.

sysfs example

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

$ echo allow_countries > /sys/packetshield/myinst/Other/geoip_policy

GUI example

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

myinst/Other/geoip_policy allow_countries

countries

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.

sysfs example

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

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

$ 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

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

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.

    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.

    $ cat mybase.4
    1.2.3.0    US
    1.2.3.9    CA

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

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

icmp_rate_max

default: 0, unlimited rate

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

sysfs example

Set the maximum ICMP rate to 1000/s.

$ echo 1000 > /sys/packetshield/myinst/Other/icmp_rate_max

GUI example

Set the maximum ICMP rate to 1000/s.

myinst/Other/icmp_rate_max 1000

dsr_mode

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.

sysfs example

Enable DSR mode.

$ echo 1 > /sys/packetshield/myinst/Other/dsr_mode

GUI example

Enable DSR mode.

myinst/Other/dsr_mode 1

cluster_secret

default: none

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

sysfs example

Define the shared secret ABCDEF0123456789.

$ echo 'ABCDEF0123456789' > /sys/packetshield/myinst/Other/cluster_secret

GUI example

Define the shared secret ABCDEF0123456789.

myinst/Other/cluster_secret 'ABCDEF0123456789'

Context protection togglers

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

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

sysfs example

Enable SYN flood protection for context 1.2.3.4:

$ echo '+1.2.3.4' > /sys/packetshield/myinst/Other/new_cookie_toggled

GUI example

Enable SYN flood protection for context 1.2.3.4:

myinst/Other/new_cookie_toggled 1.2.3.4

unmatch_drop_toggled

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

sysfs example

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

$ echo '+1.2.3.4' > /sys/packetshield/myinst/Other/unmatch_drop_toggled

GUI example

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

myinst/Other/unmatch_drop_toggled 1.2.3.4

unknown_ttlfilter_toggled

List contexts protected against unknown TTL value.

sysfs example

Disable unknown TTL protection in context 1.2.3.4:

$ echo '-1.2.3.4' > /sys/packetshield/myinst/Other/unknown_ttlfilter_toggled

GUI example

Disable unknown TTL protection in context 1.2.3.4 by deleting this line:

myinst/Other/unknown_ttlfilter_toggled 1.2.3.4

deliver_block_toggled

List contexts protected against packet surges.

sysfs example

Enable packet surge protection for context 1.2.3.4:

$ echo '+1.2.3.4' > /sys/packetshield/myinst/Other/deliver_block_toggled

GUI example

Enable packet surge protection for context 1.2.3.4:

myinst/Other/deliver_block_toggled 1.2.3.4

Context capture

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:

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.


Next up

Instances