FreeBSD PF

This is an Ansible role for configuring the PF firewall on FreeBSD.

Feel free to give feedback or report problems.

Contributions are welcome.

Important Note

When you change the firewall settings, you might lose access to your system. Make sure to read the official documentation:

• https://www.freebsd.org/doc/en/books/handbook/firewalls-pf.html
• https://www.openbsd.org/faq/pf/filter.html

If you're working on a remote system, open a session and run the following command as root before enabling PF:

shell> sleep 120; pfctl -d

This command will disable PF after 2 minutes, allowing you to reconnect if there are issues.

Requirements

Collections

• community.general

Optional Dependencies

• security/sshguard. See sshguard fails to start
• security/py-fail2ban
• net/relayd

Role Variables

By default, the firewall is off:

pf_enable: False

SSH guard, blacklist, fail2ban, and relayd are all disabled by default:

pf_blacklistd_enable: False
pf_fail2ban_enable: False
pf_relayd_enable: False
pf_sshguard_enable: False

Blocked packets are not logged by default:

pf_log_all_blocked: False

Check the default values and examples in the variable files.

Steps to Follow

1. Change the shell to /bin/sh if needed:

shell> ansible srv.example.com -e 'ansible_shell_type=csh ansible_shell_executable=/bin/csh' -a 'sudo pw usermod freebsd -s /bin/sh'

2. Install the role and collections:

shell> ansible-galaxy role install vbotka.freebsd_pf

If needed, also install the collection:

shell> ansible-galaxy collection install community.general

3. Create your firewall configuration

Choose a template from *-pf.conf.j2 that fits your needs (like router, server, balancer, etc.) and check the example variable files in vars. The default configuration template default-pf.conf.j2 is tested, while others may need more testing.

You can create nested lists for configuration options.

4. Create a playbook

shell> cat freebsd-pf.yml
- hosts: srv.example.com
  roles:
    - vbotka.freebsd_pf

5. Review handlers to understand how PF starts, restarts, and reloads.

6. Install required packages:

shell> ansible-playbook -t pf_packages -e pf_install=true freebsd-pf.yml

After this, you can disable the package installation to speed up the playbook.

7. Configure the firewall

Starting or restarting the firewall can break SSH connections. To avoid this, configure the rules first:

shell> ansible-playbook -e pf_enable=false freebsd-pf.yml

Before enabling the firewall, open another SSH session on the remote host and run:

shell> sleep 120; pfctl -d

This will disable PF in case you get locked out. Now, enable the firewall:

shell> ansible-playbook -e pf_enable=true freebsd-pf.yml

Update the Firewall

Open an SSH connection to avoid being locked out. Update and check the configuration without reloading the rules:

shell> ansible-playbook -e pf_conf_only=true -e pf_conf_validate=true freebsd-pf.yml

After confirming the configuration is correct, reload the rules:

shell> ansible srv.example.com -m service -a "name=pf state=reloaded"

Troubleshooting

pf.conf Issues

To enable backup for configuration files:

pf_backup_conf: true

If the configuration fails validation, you may find an error message indicating where the issue is located. Use the following command to help find the error:

shell> ansible-playbook -e pf_conf_only=true -e pf_conf_validate=false freebsd-pf.yml

To locate the syntax error in the configuration file:

shell> pfctl -n -f /etc/pf.conf

Fix the error, then validate and reload the rules again.

relayd.conf Issues

You can troubleshoot relayd.conf in a similar way:

shell> ansible-playbook -t pf_relayd -e pf_debug=true -e pf_relayd_conf_validate=false -e pf_relayd_conf_only=true freebsd-pf.yml

Locate the syntax error in relayd.conf:

shell> relayd -n -f /usr/local/etc/relayd.conf

After fixing it, validate and reload.

Security

To prevent unvalidated configurations from being reloaded, the play will stop if both pf_conf_only=false and pf_conf_validate=false.

shell> ansible-playbook -e pf_conf_only=false -e pf_conf_validate=false freebsd-pf.yml

The same applies to relayd.

Ansible Lint

Use the configuration file .ansible-lint.local when running ansible-lint to ignore certain warnings as needed.

shell> ansible-lint -c .ansible-lint.local

References

• Book of PF
• Firewalling with OpenBSD's PF
• Beginner's Guide to Firewalling with pf
• PF Testing Your Firewall
• FreeBSD and blacklistd
• Usage of pf with Fail2Ban

License

Author

Vladimir Botka