Firewall Management - FreshPerf/PVE4J GitHub Wiki

Firewall Management

This guide covers VM firewall configuration, rules, and IP set management in PVE4J.

Table of Contents

Firewall Options

Get Firewall Options

import fr.freshperf.pve4j.entities.nodes.node.qemu.firewall.PveQemuFirewallOptions;

try {
    PveQemuFirewallOptions options = proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getFirewall()
            .getOptions()
            .execute();
    
    System.out.println("DHCP: " + options.getDhcp());
    System.out.println("Enabled: " + options.getEnable());
    System.out.println("IPv6: " + options.getIpv6());
    System.out.println("Log Level In: " + options.getLogLevelIn());
    System.out.println("Log Level Out: " + options.getLogLevelOut());
    System.out.println("MAC Filter: " + options.getMacfilter());
    System.out.println("NDP: " + options.getNdp());
    System.out.println("Policy In: " + options.getPolicyIn());
    System.out.println("Policy Out: " + options.getPolicyOut());
    System.out.println("RADV: " + options.getRadv());
    
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Update Firewall Options

import fr.freshperf.pve4j.entities.nodes.node.qemu.firewall.PveQemuFirewallOptionsUpdate;
import fr.freshperf.pve4j.entities.PveTask;

try {
    PveQemuFirewallOptionsUpdate options = PveQemuFirewallOptionsUpdate.builder()
            .enable(true)
            .dhcp(true)
            .ipv6(true)
            .logLevelIn("info")
            .logLevelOut("info")
            .policyIn("DROP")
            .policyOut("ACCEPT")
            .build();
    
    PveTask task = proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getFirewall()
            .updateOptions(options)
            .waitForCompletion(proxmox)
            .execute();
    
    System.out.println("Firewall options updated successfully!");
    
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Enable/Disable Firewall

// Enable
try {
    PveQemuFirewallOptionsUpdate options = PveQemuFirewallOptionsUpdate.builder()
            .enable(true)
            .build();
    
    proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getFirewall()
            .updateOptions(options)
            .waitForCompletion(proxmox)
            .execute();
    
    System.out.println("Firewall enabled for VM 100");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

// Disable
try {
    PveQemuFirewallOptionsUpdate options = PveQemuFirewallOptionsUpdate.builder()
            .enable(false)
            .build();
    
    proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getFirewall()
            .updateOptions(options)
            .waitForCompletion(proxmox)
            .execute();
    
    System.out.println("Firewall disabled for VM 100");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Firewall Rules

List Rules

import fr.freshperf.pve4j.entities.nodes.node.qemu.firewall.rules.PveFirewallRule;

try {
    List<PveFirewallRule> rules = proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getFirewall()
            .getRules()
            .list()
            .execute();
    
    for (PveFirewallRule rule : rules) {
        System.out.println("Rule: " + rule);
    }
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Get a Specific Rule

try {
    PveFirewallRule rule = proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getFirewall()
            .getRules()
            .get(0)  // position
            .execute();
    
    System.out.println("Rule at position 0: " + rule);
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Create a Rule

import fr.freshperf.pve4j.entities.nodes.node.qemu.firewall.rules.PveFirewallRuleCreateOptions;

try {
    PveFirewallRuleCreateOptions options = PveFirewallRuleCreateOptions.builder()
            // Configure rule options (type, action, direction, etc.)
            .build();
    
    proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getFirewall()
            .getRules()
            .create(options)
            .execute();
    
    System.out.println("Firewall rule created!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Update a Rule

try {
    PveFirewallRuleCreateOptions options = PveFirewallRuleCreateOptions.builder()
            // Updated rule options
            .build();
    
    proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getFirewall()
            .getRules()
            .update(0, options)  // update rule at position 0
            .execute();
    
    System.out.println("Firewall rule updated!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Delete a Rule

try {
    proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getFirewall()
            .getRules()
            .delete(0)  // delete rule at position 0
            .execute();
    
    System.out.println("Firewall rule deleted!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

IP Set Management

List IP Sets

import fr.freshperf.pve4j.entities.nodes.node.qemu.firewall.ipset.PveQemuFirewallIpSetEntry;

try {
    List<PveQemuFirewallIpSetEntry> ipsets = proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getFirewall()
            .getIpSet()
            .list()
            .execute();
    
    for (PveQemuFirewallIpSetEntry ipset : ipsets) {
        System.out.println("IP Set: " + ipset);
    }
    
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Create an IP Set

import fr.freshperf.pve4j.entities.nodes.node.qemu.firewall.ipset.PveQemuFirewallIpSetCreateOptions;

try {
    PveQemuFirewallIpSetCreateOptions options = PveQemuFirewallIpSetCreateOptions.builder()
            .build();
    
    proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getFirewall()
            .getIpSet()
            .create("trusted-ips", options)
            .execute();
    
    System.out.println("IP Set 'trusted-ips' created!");
    
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Rename an IP Set

try {
    proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getFirewall()
            .getIpSet()
            .rename("old-name", "new-name", PveQemuFirewallIpSetCreateOptions.builder().build())
            .execute();
    
    System.out.println("IP Set renamed!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Delete an IP Set

try {
    proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getFirewall()
            .getIpSet()
            .delete("trusted-ips", false)
            .execute();
    
    System.out.println("IP Set deleted!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

IP Set Members

List Members

import fr.freshperf.pve4j.entities.nodes.node.qemu.firewall.ipset.PveQemuFirewallIpSetMember;

try {
    List<PveQemuFirewallIpSetMember> members = proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getFirewall()
            .getIpSet()
            .listMembers("trusted-ips")
            .execute();
    
    for (PveQemuFirewallIpSetMember member : members) {
        System.out.println("CIDR: " + member.getCidr());
        System.out.println("Comment: " + member.getComment());
        System.out.println("---");
    }
    
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Add a Member

import fr.freshperf.pve4j.entities.nodes.node.qemu.firewall.ipset.PveQemuFirewallIpSetMemberCreateOptions;

try {
    PveQemuFirewallIpSetMemberCreateOptions options = 
            PveQemuFirewallIpSetMemberCreateOptions.builder()
                    .build();
    
    proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getFirewall()
            .getIpSet()
            .addMember("trusted-ips", "192.168.1.0/24", options)
            .execute();
    
    System.out.println("IP range added to IP Set!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Get a Member

try {
    PveQemuFirewallIpSetMember member = proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getFirewall()
            .getIpSet()
            .getMember("trusted-ips", "192.168.1.0/24")
            .execute();
    
    System.out.println("Member: " + member);
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Update a Member

import fr.freshperf.pve4j.entities.nodes.node.qemu.firewall.ipset.PveQemuFirewallIpSetMemberUpdateOptions;

try {
    PveQemuFirewallIpSetMemberUpdateOptions options = 
            PveQemuFirewallIpSetMemberUpdateOptions.builder()
                    .build();
    
    proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getFirewall()
            .getIpSet()
            .updateMember("trusted-ips", "192.168.1.0/24", options)
            .execute();
    
    System.out.println("IP Set member updated!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Delete a Member

try {
    proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getFirewall()
            .getIpSet()
            .deleteMember("trusted-ips", "192.168.1.0/24", null)
            .execute();
    
    System.out.println("IP removed from IP Set!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Common Firewall Configurations

Basic Web Server

public void configureWebServerFirewall(Proxmox proxmox, String node, int vmid) {
    try {
        // Enable firewall with restrictive default policy
        PveQemuFirewallOptionsUpdate options = PveQemuFirewallOptionsUpdate.builder()
                .enable(true)
                .policyIn("DROP")
                .policyOut("ACCEPT")
                .dhcp(true)
                .build();
        
        proxmox.getNodes()
                .get(node)
                .getQemu()
                .get(vmid)
                .getFirewall()
                .updateOptions(options)
                .waitForCompletion(proxmox)
                .execute();
        
        // Create IP set for allowed management IPs
        PveQemuFirewallIpSetCreateOptions ipsetOptions = 
                PveQemuFirewallIpSetCreateOptions.builder()
                        .build();
        
        proxmox.getNodes()
                .get(node)
                .getQemu()
                .get(vmid)
                .getFirewall()
                .getIpSet()
                .create("admin-access", ipsetOptions)
                .execute();
        
        System.out.println("Web server firewall configured");
        
    } catch (ProxmoxAPIError | InterruptedException e) {
        e.printStackTrace();
    }
}

Database Server with Restricted Access

public void configureDatabaseFirewall(Proxmox proxmox, String node, int vmid, 
                                     List<String> allowedIPs) {
    try {
        // Enable firewall
        PveQemuFirewallOptionsUpdate options = PveQemuFirewallOptionsUpdate.builder()
                .enable(true)
                .policyIn("DROP")
                .policyOut("ACCEPT")
                .build();
        
        proxmox.getNodes()
                .get(node)
                .getQemu()
                .get(vmid)
                .getFirewall()
                .updateOptions(options)
                .waitForCompletion(proxmox)
                .execute();
        
        // Create IP set for database clients
        proxmox.getNodes()
                .get(node)
                .getQemu()
                .get(vmid)
                .getFirewall()
                .getIpSet()
                .create("db-clients", PveQemuFirewallIpSetCreateOptions.builder().build())
                .execute();
        
        // Add allowed IPs
        for (String ip : allowedIPs) {
            PveQemuFirewallIpSetMemberCreateOptions memberOptions = 
                    PveQemuFirewallIpSetMemberCreateOptions.builder()
                            .build();
            
            proxmox.getNodes()
                    .get(node)
                    .getQemu()
                    .get(vmid)
                    .getFirewall()
                    .getIpSet()
                    .addMember("db-clients", ip, memberOptions)
                    .execute();
        }
        
        System.out.println("Database firewall configured with " + allowedIPs.size() + " allowed IPs");
        
    } catch (ProxmoxAPIError | InterruptedException e) {
        e.printStackTrace();
    }
}

Firewall Management Helper

public class FirewallManager {
    private final Proxmox proxmox;
    private final String node;
    private final int vmid;
    
    public FirewallManager(Proxmox proxmox, String node, int vmid) {
        this.proxmox = proxmox;
        this.node = node;
        this.vmid = vmid;
    }
    
    public void enableFirewall() throws ProxmoxAPIError, InterruptedException {
        PveQemuFirewallOptionsUpdate options = PveQemuFirewallOptionsUpdate.builder()
                .enable(true)
                .build();
        
        proxmox.getNodes().get(node).getQemu().get(vmid)
                .getFirewall()
                .updateOptions(options)
                .waitForCompletion(proxmox)
                .execute();
    }
    
    public void disableFirewall() throws ProxmoxAPIError, InterruptedException {
        PveQemuFirewallOptionsUpdate options = PveQemuFirewallOptionsUpdate.builder()
                .enable(false)
                .build();
        
        proxmox.getNodes().get(node).getQemu().get(vmid)
                .getFirewall()
                .updateOptions(options)
                .waitForCompletion(proxmox)
                .execute();
    }
    
    public void createIPSet(String name) throws ProxmoxAPIError, InterruptedException {
        proxmox.getNodes().get(node).getQemu().get(vmid)
                .getFirewall()
                .getIpSet()
                .create(name, PveQemuFirewallIpSetCreateOptions.builder().build())
                .execute();
    }
    
    public void addIPToSet(String setName, String cidr) 
            throws ProxmoxAPIError, InterruptedException {
        
        proxmox.getNodes().get(node).getQemu().get(vmid)
                .getFirewall()
                .getIpSet()
                .addMember(setName, cidr, PveQemuFirewallIpSetMemberCreateOptions.builder().build())
                .execute();
    }
    
    public void removeIPFromSet(String setName, String cidr) 
            throws ProxmoxAPIError, InterruptedException {
        
        proxmox.getNodes().get(node).getQemu().get(vmid)
                .getFirewall()
                .getIpSet()
                .deleteMember(setName, cidr, null)
                .execute();
    }
}

Next Steps

⚠️ **GitHub.com Fallback** ⚠️