Documentation
Getting Started
Static Sets

Static configuration using sets

Sets are used to manage entries for drop and ignore policies that need to persist across restarts.

Sets overview

Location

Sets are located in Couic working directory (see working_dir configuration variable).

      • bogons.couic
      • zombies.couic
      • infra.couic

    • Properties

    Set file example:

    test.couic
    # test set
# (comments and empty lines are ignored)

1.1.1.1/32
2606:4700:4700::1111/128
2.2.2.0/24

    A set has several properties:

    • File format: a text file with the .couic extension
    • Maximum size: 5MB per set file
    • Name constraints: up to 48 characters; allowed characters: [a-zA-Z0-9-_]
    • Scope: node-specific (not synchronized to other nodes via peering)
    • Expiration: entries defined in a set never expire
    • Mutability: entries defined by a set cannot be added/removed via the API
    • Loading: all sets are loaded at Couic startup
    • Tagging: entries from a set are tagged with the name of the set they come from

    Using couicctl

    command
    couicctl drop list
    output
    ┌────────┬──────────────────────────┬────────────┬────────────┐
│ Policy ┆ CIDR                     ┆ Tag        ┆ Expiration │
╞════════╪══════════════════════════╪════════════╪════════════╡
│ drop   ┆ 8.8.8.8/32               ┆            ┆ never      │
├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌┤
│ drop   ┆ 8.8.8.8/24               ┆            ┆ never      │
├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌┤
│ drop   ┆ 1.0.0.1/32               ┆ test.couic ┆ never      │
├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌┤
│ drop   ┆ 2.2.2.2/24               ┆ test       ┆ never      │
├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌┤
│ drop   ┆ 1.1.1.1/32               ┆ test.couic ┆ never      │
├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌┤
│ drop   ┆ 2606:4700:4700::1111/128 ┆ test.couic ┆ never      │
├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌┤
│ drop   ┆ 2606:4700:4700::1001/128 ┆ test.couic ┆ never      │
└────────┴──────────────────────────┴────────────┴────────────┘

    You can hot reload the sets on a node using the API or CLI with the command: couicctl sets reload. This command performs a differential update between the current entries in memory and the set files, ensuring that existing blocks remain unchanged if they are not modified.

    Hot reloading the sets allows for easy integration of Couic into scheduled tasks like crontab

    Creating Sets

    Add sets manually

    You can create persistent file-based sets by manually creating .couic files in /var/lib/couic/sets/{drop,ignore}/. These are automatically loaded at Couic startup and can be hot-reloaded with couicctl sets reload.

    Set files must be owned by the couic user and have 600 permissions (read/write for owner only) for security reasons. Couic will refuse to load files with incorrect ownership or permissions.

    Add local network to ignore policy

    command
    sudo touch /var/lib/couic/sets/ignore/lan.couic
sudo chown couic: /var/lib/couic/sets/ignore/lan.couic
sudo chmod 600 /var/lib/couic/sets/ignore/lan.couic
sudo vim /var/lib/couic/sets/ignore/lan.couic
sudo couicctl sets reload
    output
    Sets reloaded successfully

    List ignore policy entries:

    command
    couicctl ignore list
    output
    ┌────────┬────────────────┬───────────┬────────────┐
│ Policy ┆ CIDR           ┆ Tag       ┆ Expiration │
╞════════╪════════════════╪═══════════╪════════════╡
│ ignore ┆ 192.168.0.0/24 ┆ lan.couic ┆ never      │
└────────┴────────────────┴───────────┴────────────┘

    Add sets using couicctl

    Block an entire ASN using RIPE database

    The couicctl sets create command supports importing prefixes directly from an ASN via the RIPE NCC RIPEstat API:

    command
    couicctl sets create --from-asn AS200373 drop asn200373
    output
    Fetching prefixes for ASN: AS200373
Retrieved 42 prefixes from RIPE NCC RIPEstat
Set created successfully with 42 entries
Don't forget to run 'couicctl sets reload' to apply the changes
    The ASN can be specified with or without the “AS” prefix: both AS200373 and 200373 are valid.

    To apply the changes:

    command
    couicctl sets reload

    Import CIDRs from a file

    You can bulk-import CIDRs from a text file using the --from-file option:

    file.txt
    # Malicious IPs from threat intel feed
203.0.113.0/24
198.51.100.0/24
# IPv6 ranges
2001:db8::/32

# Empty lines and comments are ignored
192.0.2.0/24
    command
    couicctl sets create --from-file file.txt drop threat-intel
    output
    Reading CIDRs from file: file.txt
Loaded 4 CIDRs from file
Set created successfully with 4 entries
Don't forget to run 'couicctl sets reload' to apply the changes

    Bulk operations with xargs

    You can combine the new helpers with xargs for bulk operations:

    Batch import with reload at the end
    command
    cat cidr-list.txt | xargs couicctl sets create drop blocklist && couicctl sets reload
    Dynamic filteringAdministration