Forge Home


An agent that manipulates a specific single chain with iptables and ip6tables


4,334 latest version

3.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 4.0.2 (latest)
  • 4.0.1
  • 4.0.0
  • 3.0.2
released Dec 20th 2021
This version is compatible with:
  • Puppet Enterprise 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x
  • Puppet >= 6.0.0

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'choria-mcollective_agent_iptables', '4.0.2'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add choria-mcollective_agent_iptables
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install choria-mcollective_agent_iptables --version 4.0.2

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.



choria/mcollective_agent_iptables — version 4.0.2 Dec 20th 2021

Choria IPTables Agent

This agent manages a specific chain in iptables or ip6tables, you can use it to add, remove, query or list entries of the chain.

The basic use case is to maintain a blacklist chain from an IDS, Log monitoring tool like fail2ban or any other system that needs to manipulate remote IP chains.

It is limited to managing one configured chain to which has to exist before the agent will activate.


This agent provides the following actions, for details about each please run mco plugin doc agent/iptables

  • block - Block an IP
  • isblocked - Check if an IP is blocked
  • listblocked - Returns list of blocked ips
  • unblock - Unblock an IP

Agent Installtion

Add the agent and client:

  - mcollective_agent_nettest


The chain you configure has to exist before MCollective start else this agent will not activate, you can create the chain using your systems RC scripts which generally runs before the network come up and so also before MCollective start.

 % iptables -N junk_filter
 % ip6tables -N junk_filter

In other chains you can reference the junk_filter chain to do allow/deny based on its contents.

 % iptables -I INPUT -p tcp --dport 22 -j junk_filter
 % iptables -I INPUT -p tcp --dport 22 --syn -j ACCEPT

This will drop all port 22 traffic for hosts listed in the junk_filter chain while allowing connections to port 22 from everywhere else.

You then configure the agent via hiera to use the junk_filter chain:

  chain: junk_filter
  target: DROP

These will instruct the agent to add entries to the junk_filter chain with the DROP target.

You can also adjust the paths to some commands if your system does not use standard locations for these:

  iptables: /usr/local/bin/iptables
  ip6tables: /usr/local/bin/ip6tables
  logger: /usr/local/bin/logger


The agent include a utility application that simplifies the command line interaction, the examples show that but you can of course also use normal RPC application commands.

All of the mco iptables commands below also takes a -s argument that will return quicker and not wait for or show any results. This is ideal for using in scripts.

Blocking a host

% mco iptables block

 * [ ============================================================> ] 3 / 3

Summary of Blocked:

   true = 3

Finished processing 3 / 3 hosts in 675.95 ms

The equivelant rpc command is mco rpc iptables block ipaddr=

Checking if a host is blocked

% mco iptables isblocked

 * [ ============================================================> ] 3 / 3


Summary of Blocked:

   true = 3

Finished processing 3 / 3 hosts in 337.20 ms

The equivelant rpc command is mco rpc iptables isblocked ipaddr=

Unblocking a host

% mco iptables unblock

 * [ ============================================================> ] 3 / 3

Summary of Blocked:

   false = 3

Finished processing 3 / 3 hosts in 670.75 ms

The equivelant rpc command is mco rpc iptables unblock ipaddr=

Listing all the blocked IP addresses

The agent can return a list of all blocked IPs on all hosts, this is mostly not going to be useful on the command line due to the amount of information it provides. You can use the mco rpc iptables listblocked command to see that on the CLI.