ripset 0.1.0

Pure Rust implementation of ipset/nftset operations via netlink
Documentation
  • Coverage
  • 57.14%
    32 out of 56 items documented16 out of 25 items with examples
  • Size
  • Source code size: 139.05 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 4.91 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 17s Average build duration of successful builds.
  • all releases: 17s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • Homepage
  • windoze/ripset
    1 1 1
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • windoze

ripset

Pure Rust library for managing Linux ipset and nftables sets via the netlink protocol.

Features

  • Zero external dependencies - No shelling out to ipset or nft commands
  • ipset support - Create, destroy, flush, list sets; add, delete, test IP addresses
  • nftables support - Create/delete tables and sets; add, delete, test, list IP addresses
  • IPv4 and IPv6 - Full support for both address families
  • Timeout support - Add entries with optional expiration times
  • Cross-platform stubs - Compiles on non-Linux platforms (returns UnsupportedPlatform error)
  • CLI tool - Optional ripset binary for command-line management

Installation

Add to your Cargo.toml:

[dependencies]
ripset = "0.1"

CLI Installation

To build the ripset CLI tool, enable the cli feature:

cargo build --features cli

Library Usage

ipset Operations

use std::net::IpAddr;
use ripset::{
    ipset_create, ipset_destroy, ipset_flush, ipset_list,
    ipset_add, ipset_del, ipset_test,
    IpSetCreateOptions, IpSetFamily, IpSetType, IpEntry,
};

// Create an ipset
let opts = IpSetCreateOptions {
    set_type: IpSetType::HashIp,
    family: IpSetFamily::Inet,
    timeout: Some(300), // optional default timeout in seconds
    ..Default::default()
};
ipset_create("myset", &opts)?;

// Add an IP address
let addr: IpAddr = "192.168.1.1".parse()?;
ipset_add("myset", addr)?;

// Add with custom timeout
let entry = IpEntry::with_timeout(addr, 60);
ipset_add("myset", entry)?;

// Test if IP exists
let exists = ipset_test("myset", addr)?;

// List all entries
let entries = ipset_list("myset")?;

// Delete an IP
ipset_del("myset", addr)?;

// Flush all entries
ipset_flush("myset")?;

// Destroy the set
ipset_destroy("myset")?;

nftables Operations

use std::net::IpAddr;
use ripset::{
    nftset_create_table, nftset_delete_table, nftset_list_tables,
    nftset_create_set, nftset_delete_set,
    nftset_add, nftset_del, nftset_test, nftset_list,
    NftSetCreateOptions, NftSetType,
};

// Create a table
nftset_create_table("inet", "mytable")?;

// List tables
let tables = nftset_list_tables("inet")?;

// Create a set
let opts = NftSetCreateOptions {
    set_type: NftSetType::Ipv4Addr,
    timeout: Some(300),
    ..Default::default()
};
nftset_create_set("inet", "mytable", "myset", &opts)?;

// Add an IP address
let addr: IpAddr = "10.0.0.1".parse()?;
nftset_add("inet", "mytable", "myset", addr)?;

// Test if IP exists
let exists = nftset_test("inet", "mytable", "myset", addr)?;

// List all entries
let entries = nftset_list("inet", "mytable", "myset")?;

// Delete an IP
nftset_del("inet", "mytable", "myset", addr)?;

// Delete the set and table
nftset_delete_set("inet", "mytable", "myset")?;
nftset_delete_table("inet", "mytable")?;

CLI Usage

The ripset CLI tool supports both ipset and nftables backends.

Global Options

  • -b, --backend <ipset|nftables> - Backend to use (default: nftables)

Entry Operations

# Add an entry to a set
ripset add <set-name> <ip-address> -t <table> [-f <family>]

# Delete an entry from a set
ripset del <set-name> <ip-address> -t <table> [-f <family>]

# List all entries in a set
ripset list <set-name> -t <table> [-f <family>]

# Flush all entries from a set
ripset flush <set-name> -t <table> [-f <family>]

Table.Set Syntax

For the nftables backend, you can use <table>.<set> syntax instead of the -t/--table flag:

# These are equivalent:
ripset add myset 192.168.1.1 -t mytable
ripset add mytable.myset 192.168.1.1

# Works with all commands
ripset list mytable.myset
ripset del mytable.myset 192.168.1.1
ripset flush mytable.myset
ripset set new mytable.myset
ripset set del mytable.myset

The explicit -t/--table flag takes precedence over the parsed table name. For the ipset backend, the table part is ignored (ipset doesn't use tables).

Set Management

# Create a new set
ripset set new <set-name> -t <table> [--type <type>] [-f <family>]

# Delete a set
ripset set del <set-name> -t <table> [-f <family>]

Table Management (nftables only)

# Create a new table
ripset table new <table-name> [-f <family>]

# Delete a table
ripset table del <table-name> [-f <family>]

Examples

# nftables backend (default) - using table.set syntax
sudo ripset table new mytable -f inet
sudo ripset set new mytable.myset --type ipv4
sudo ripset add mytable.myset 192.168.1.1
sudo ripset list mytable.myset
sudo ripset del mytable.myset 192.168.1.1
sudo ripset flush mytable.myset
sudo ripset set del mytable.myset
sudo ripset table del mytable

# nftables backend - using -t flag (equivalent)
sudo ripset set new myset -t mytable --type ipv4
sudo ripset add myset 192.168.1.1 -t mytable
sudo ripset list myset -t mytable

# ipset backend (table part ignored if using table.set syntax)
sudo ripset -b ipset set new myset --type hash-ip -f inet
sudo ripset -b ipset add myset 192.168.1.1
sudo ripset -b ipset list myset
sudo ripset -b ipset flush myset
sudo ripset -b ipset set del myset

Requirements

  • Linux kernel with netfilter support
  • Root privileges (CAP_NET_ADMIN) for all operations
  • For ipset: ip_set kernel module loaded
  • For nftables: nf_tables kernel module loaded

License

Licensed under either of

at your option.