Skip to content
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