addon-vnfilter

OpenNebula addon to complete the spoofing filter rules generated by OpenNebula.

Use cases

• Alias IPv4 and IPv6 spoofing filtering when an alias is attached to an Ethernet-only NIC (VNM/post.d)
• Alias IPv4 and IPv6 spoofing filtering when an alias is detached from an Ethernet-only NIC (VNM/clean.d)
• Alias IPv4 and IPv6 spoofing filtering on alias hotplug (host hook)
• ARP filtering when FILTER_MAC_SPOOFING is enabled

Supported VN MADs: 802.1Q and fw (bridged and security groups).

Supported OpenNebula releases: 6.4 – 6.10 and 7.0+ (including current master / 7.2). The driver code adapts to upstream API differences automatically (see OpenNebula version notes).

---

Installation and verification checklist

Work through this list on the frontend and on every KVM host. All verification commands in step 7 must succeed before relying on the addon in production.

1. Install addon files on the frontend

From the addon directory on the OpenNebula frontend:

sudo bash install.sh

Or manually:

cp -a remotes/ /var/lib/one/
chown -R oneadmin:oneadmin /var/lib/one/remotes/

install.sh copies remotes/, applies version-specific patches under patches/vnm/<version>/ to /var/lib/one/remotes/, runs onehost sync (unless SKIP_HOSTS_SYNC=1), and registers the hook (unless SKIP_ONEHOOK_REGISTRATION=1).

Environment overrides: ONE_VER, ONE_LOCATION, SKIP_HOSTS_SYNC, SKIP_ONEHOOK_REGISTRATION.

2. Apply OpenNebula core patches (frontend)

Patches live in patches/vnm/. install.sh selects the directory matching ONE_VER (from /var/lib/one/remotes/VERSION) or ONE_MAJOR.ONE_MINOR.

OpenNebula version	Patch directory	Contents
5.12.x	patches/vnm/5.12/	IPv6 prefix length in security groups
6.4.x	patches/vnm/6.4/	IPv6 prefix length; SG driver error handling
6.6.x – 6.8.x	patches/vnm/6.6/ (via 6.8 → 6.6)	Same as 6.4 SG fix
6.10.x	patches/vnm/6.10/ (via 6.8)	Inherited 6.6 patches
6.99.x	patches/vnm/6.99/ → 6.10	Same as 6.10
7.0.x – 7.2+	patches/vnm/7.0/ → 6.10	Same as 6.10

If install.sh reports an unknown version, apply the matching patches manually with patch against files under /var/lib/one/remotes/vnm/, then re-run chown -R oneadmin:oneadmin /var/lib/one/remotes.

Verify: no install.sh patch errors; grep -r ipset_prefix_length /var/lib/one/remotes/vnm/security_groups_iptables.rb shows the patched logic for your version.

3. Install host prerequisites (every KVM host)

The addon and its hook use:

Component	Used for
iptables, ip6tables	IP spoofing chains (via OpenNebula fw driver)
ipset	IP/IP6 spoofing sets
ebtables, ebtables-save	ARP / MAC spoofing (ebtables nat table)
Ruby nokogiri	Host hook XML parsing
Ruby rexml	VNM scripts (via vnmmad)

Recommended — run on each host from the addon directory:

sudo HOST_INSTALL=1 bash install.sh

Manual install — AlmaLinux / Rocky / RHEL / Oracle Linux 8+

sudo dnf -y install \
    opennebula-rubygems \
    rubygem-rexml \
    iptables-nft \
    ipset

# EL8 only: ebtables is a separate package
sudo dnf -y install iptables-ebtables   # only on major version 8

Manual install — Debian / Ubuntu

sudo apt-get -y install \
    opennebula-rubygems \
    ruby-rexml \
    iptables \
    ebtables \
    ipset

Legacy CentOS 7 (if still in use)

sudo yum -y --enablerepo=epel install rubygem-nokogiri rubygem-rexml
sudo yum -y install iptables ipset ebtables

On EL9+, ebtables is typically provided via the iptables-nft stack; on EL8 install iptables-ebtables explicitly.

4. Configure sudoers on every KVM host

oneadmin must run ebtables (rule changes) and ebtables-save (read current rules) without a password.

echo 'oneadmin ALL=(ALL) NOPASSWD: /usr/sbin/ebtables-save, /usr/sbin/ebtables' | \
    sudo tee /etc/sudoers.d/vnfilter
sudo chmod 0440 /etc/sudoers.d/vnfilter

On 7.x, OpenNebula no longer defines :ebtables in VNMMAD::VNMNetwork::COMMANDS; vnfilter registers sudo -n ebtables --concurrent at runtime. The sudoers rule above is still required.

5. Sync remotes to hosts

On the frontend as oneadmin:

onehost sync --force

Confirm hook and VNM files exist on a host, for example:

ls /var/tmp/one/vnm/vnfilter.rb
ls /var/tmp/one/hooks/alias_ip/vnfilter.rb
ls /var/tmp/one/vnm/*/post.d/vnfilter_post

6. Register the host hook (frontend)

If not done by install.sh:

onehook show vnfilter || onehook create vnfilter.hooktemplate

Hook definition: vnfilter.hooktemplate — remote state hook on ACTIVE / HOTPLUG_NIC.

7. Verify host prerequisites

Run on each KVM host (as root or with sudo). Every command should succeed.

# Ruby libraries
ruby -e "require 'rexml/document'; puts 'rexml OK'"
ruby -e "require 'nokogiri'; puts 'nokogiri OK'"

# Firewall tools
iptables -V
ip6tables -V
ebtables -V
ipset -v

# Sudoers (as oneadmin)
sudo -u oneadmin sudo -n /usr/sbin/ebtables-save >/dev/null && echo 'ebtables-save OK'
sudo -u oneadmin sudo -n /usr/sbin/ebtables --concurrent -L >/dev/null && echo 'ebtables OK'

Optional — security groups bridge check (after VMs with SG are running):

./vncheck.sh    # exit 1 if physdev rules are missing (e.g. after migration)

8. Enable on existing VMs

After installation, live-migrate VMs (or restart them) so post/clean hooks and filters are applied on the destination host.

---

OpenNebula version notes

Differences that affect this addon only (upstream VNM drivers handle the rest).

Topic	OpenNebula 6.x (e.g. 6.10)	OpenNebula 7.x (7.0 – 7.2+)
Driver logging	OpenNebula.log_info / log_error via scripts_common	OpenNebula::DriverLogger.log_*
vnfilter handling	VnFilter.log_info / log_error pick backend at runtime	same
VNMMAD::VNMNetwork::COMMANDS[:ebtables]	Defined upstream (sudo -n ebtables --concurrent)	Not defined upstream
vnfilter ebtables	Uses :ebtables symbol	ensure_ebtables_command adds same default if missing
Host sudoers	ebtables-save and ebtables required	same
Core patches	See patch table	Use patches/vnm/7.0/ (or 6.99 / 6.10)

References: OpenNebula 6.10 command.rb, OpenNebula 7.2 command.rb.

---

How it works

The addon extends OpenNebula 5.10+ VN_MAD hooks and a host hook:

Component	Role
vnm/*/post.d/vnfilter_post	VM start / NIC attach — activates filters
vnm/*/clean.d/vnfilter_clean	VM stop / NIC detach — removes filters
remotes/vnm/vnfilter.rb	Main driver (iptables/ipset/ebtables rules)
hooks/alias_ip/vnfilter.rb	Hotplug add/remove of alias IPs on the host

For Ethernet-only NICs with all addresses on aliases, vnfilter patches OpenNebula-generated iptables chains using fixed offsets: 2 for IPv4, 5 for IPv6 (validated on 5.10.0 / 5.10.1; may need review on other versions).

ARP filtering uses the ebtables nat table, modelled after libvirt ARP spoofing rules.

---

Debugging

• Syslog — facility vnfilter / vnfilter_hook; all commands are logged.
• Driver stderr — VNM post/clean failures appear in the hypervisor driver log (e.g. /var/log/one/<driver>.log when ONE_MAD_DEBUG is set) and in oned.log.
• On-host state — inspect iptables / ip6tables, ipset, and ebtables -t nat -L.

---

Uninstall

Two-step procedure (allows VMs to drain rules via clean hooks):

Step 1

• onehook delete <vnfilter-hook-id>
• Remove post.d hooks on frontend: rm /var/lib/one/remotes/vnm/*/post.d/vnfilter*
• Remove post.d hooks on hosts: rm /var/tmp/one/vnm/*/post.d/vnfilter*
• Live-migrate VMs off affected hosts

Step 2

• Remove clean.d hooks on frontend and hosts: rm .../clean.d/vnfilter*
• Remove remaining files:
  • Frontend: /var/lib/one/remotes/vnm/vnfilter*, /var/lib/one/remotes/hooks/alias_ip/vnfilter*
  • Hosts: /var/tmp/one/vnm/vnfilter*, /var/tmp/one/hooks/alias_ip/vnfilter*, /etc/sudoers.d/vnfilter
• Restore patched OpenNebula files from backup if patches were applied with install.sh

---

Improvements

Not all use cases are tested; contributions are welcome.