All new Registrations are manually reviewed and approved, so a short delay after registration may occur before your account becomes active.
nat_manager.py - manage NAT port forwarding for Proxmox VMs and containers
The following code and its documentation were generated using ChatGPT model (o1-preview). I had considered writing this code myself some time ago but hadn’t found the time to do so. Here is the code along with an overview written by ChatGPT. I would appreciate any feedback on how it can be further improved or if there are any mistakes.
Code available at:
https://pastebin.com/cdrxhUSU
nat_manager.py Quick Start Guide
nat_manager.py is a Python script designed to manage NAT (Network Address Translation) and port forwarding rules for VMs and containers in a Proxmox environment. The script utilizes iptables to configure NAT rules and allows for easy addition, removal, listing, updating, exporting, and importing of port mappings.
This guide provides step-by-step instructions for setting up the network, using the script, and provides examples for common operations.
Network Setup in Proxmox
To use nat_manager.py effectively, you need to set up a bridge network (vmbr1) on your Proxmox server. This bridge will use a private IP range and manage the NAT and port forwarding for your VMs and containers.
1. Configure the Bridge Network (vmbr1)
Edit the /etc/network/interfaces file to configure the bridge network interface vmbr1:
sudo nano /etc/network/interfaces
Add the following configuration:
auto vmbr1
iface vmbr1 inet static
address 10.0.0.1/24
bridge-ports none
bridge-stp off
bridge-fd 0
post-up iptables -t nat -A POSTROUTING -s 10.0.0.0/24 -o <YOUR_PUBLIC_INTERFACE> -j MASQUERADE
post-down iptables -t nat -D POSTROUTING -s 10.0.0.0/24 -o <YOUR_PUBLIC_INTERFACE> -j MASQUERADE
<YOUR_PUBLIC_INTERFACE>: Replace this with your network interface that has a public IP (e.g.,enp0s3).
2. Enable IP Forwarding
To ensure IP forwarding is enabled permanently, add the following line to /etc/sysctl.conf:
net.ipv4.ip_forward = 1
Apply the changes:
sudo sysctl -p
3. Restart Networking Service
Restart the networking service to apply the changes:
sudo systemctl restart networking
4. Install Required Packages
To ensure iptables rules persist across reboots, install iptables-persistent and other required packages:
sudo apt-get update
sudo apt-get install iptables-persistent python3 python3-pip sqlite3 -y
iptables-persistent: Allowsiptablesrules to be saved and restored on boot.python3andsqlite3: Required for running thenat_manager.pyscript.
Using nat_manager.py
Run nat_manager.py using Python3. Below are the various usage instructions for managing NAT and port forwarding rules for your VMs and containers.
python3 nat_manager.py -h
usage: nat_manager.py [-h]
{add,remove,list,update,reserve,unreserve,list-reserved,export,import,backup,restore,rebuild-db}
...
NAT Manager Script
positional arguments:
{add,remove,list,update,reserve,unreserve,list-reserved,export,import,backup,restore,rebuild-db}
Available actions
add Add port mappings for a container
remove Remove port mappings for a container
list List port mappings
update Update port mappings for a container
reserve Reserve ports for the host machine
unreserve Unreserve ports
list-reserved List reserved ports
export Export port mappings to a JSON file
import Import port mappings from a JSON file
backup Backup current configuration
restore Restore configuration from backup
rebuild-db Rebuild the database from existing iptables rules
options:
-h, --help show this help message and exit
1. Add Port Mappings
To add NAT port forwarding rules for a VM or container with an internal IP address (e.g., 10.0.0.5):
sudo python3 nat_manager.py add <container_ip> --mode <automatic|manual> --num-ports <N>
- Parameters:
<container_ip>: Internal IP address of the VM/container (e.g.,10.0.0.5).--mode: Mode for adding ports,automatic(default) ormanual.--num-ports <N>: Number of ports to forward (default:6).
Examples:
Automatic Mode:
sudo python3 nat_manager.py add 10.0.0.5 --mode automatic --num-ports 4This command automatically assigns 4 external ports (starting from
50000) to forward traffic to standard internal ports (e.g.,22,80,443,8080) on10.0.0.5.Manual Mode:
sudo python3 nat_manager.py add 10.0.0.5 --mode manual --external-ports 50000 50001 --internal-ports 22 80 --protocols tcp udpThis command manually assigns external ports
50000(TCP) and50001(UDP) to forward to internal ports22(SSH) and80(HTTP) on10.0.0.5.
2. Remove Port Mappings
To remove all port forwarding rules associated with a specific container IP:
sudo python3 nat_manager.py remove <container_ip>
Example:
sudo python3 nat_manager.py remove 10.0.0.5This command removes all port mappings associated with the IP
10.0.0.5.
3. List Current Port Mappings
To list all current port mappings or those for a specific container IP:
sudo python3 nat_manager.py list [container_ip]
Examples:
- List All Mappings:
sudo python3 nat_manager.py listLists all port mappings currently configured on the Proxmox server.
- List Mappings for a Specific Container:
sudo python3 nat_manager.py list 10.0.0.5Lists the port mappings for the container with IP
10.0.0.5.
4. Update Port Mappings
To update existing port mappings for a VM or container:
sudo python3 nat_manager.py update <container_ip>
Examples:
- Interactive Mode:
sudo python3 nat_manager.py update 10.0.0.5This command will prompt you to update the internal ports or protocols for each external port currently mapped to
10.0.0.5. Leave input blank to keep the current mapping.- Non-Interactive Mode:
sudo python3 nat_manager.py update 10.0.0.5 --external-ports 50000 50001 --internal-ports 2222 8081 --protocols tcp udpThis command updates the external port
50000to forward to internal port2222(TCP) and50001to forward to8081(UDP) on10.0.0.5.
5. Export and Import Port Mappings
You can export current port mappings to a JSON file for backup purposes or import them from a JSON file.
Export Port Mappings:
sudo python3 nat_manager.py export /path/to/export.jsonThis command exports the current port mappings to
export.json.Import Port Mappings:
sudo python3 nat_manager.py import /path/to/export.jsonThis command imports port mappings from
export.json.
6. Backup and Restore Configuration
You can backup the current configuration of iptables and port mappings or restore from a backup.
Backup Current Configuration:
sudo python3 nat_manager.py backupThis creates a backup of the current
iptablesrules and port mappings database.Restore Configuration from Backup:
sudo python3 nat_manager.py restore <timestamp>Replace
<timestamp>with the desired backup timestamp (e.g.,backup_20230917123045).
7. Rebuild the Database from Existing iptables Rules
If the SQLite database is lost or out of sync with iptables rules, you can rebuild it:
sudo python3 nat_manager.py rebuild-db
This command scans existing iptables rules and reconstructs the database for consistency.
Important Notes
- IP Forwarding: Ensure IP forwarding is enabled by adding
net.ipv4.ip_forward = 1to/etc/sysctl.confand runningsudo sysctl -p. - Save
iptablesRules: To ensure the rules persist after reboot, useiptables-save > /etc/iptables/rules.v4andiptables-restore < /etc/iptables/rules.v4. Check
iptables-persistent: Ensureiptables-persistentis installed and enabled to manage rule persistence:sudo apt-get install iptables-persistent -y sudo netfilter-persistent save
Network Configuration for VM/Container in Proxmox
When creating a VM or container in Proxmox that will use NAT:
Assign an Internal IP Address:
- Assign an IP within the
vmbr1subnet, such as10.0.0.5. - This IP will be used for internal communication and NAT port forwarding.
- Assign an IP within the
Connect to
vmbr1Network Bridge:- Ensure the VM/container network interface is attached to
vmbr1to use the internal network managed by NAT. - In Proxmox, select
vmbr1as the network bridge when creating or configuring the VM/container.
- Ensure the VM/container network interface is attached to
Configure Gateway (Optional):
- Set the gateway to
10.0.0.1(thevmbr1address) to route all outbound traffic through the Proxmox host.
- Set the gateway to
This setup allows VMs/containers to communicate internally using 10.0.0.x IPs and be accessed externally via port forwarding rules defined by nat_manager.py.
Comments
Useful
This looks amazing. Thanks
Always wanted to play around with NAT. Maybe if someday I get a ZAP Hosting Lifetime Dedi it's time to create lots and lots of (free) NAT vms on it as per @Neoon suggestion a looong while ago iirc.
or ks-a
If it comes back :X
Will try this soon
Unsure how to deal with ipv6....
I hate networking...
Me too. It's different per provider.
good for people who wanna run proxmox off of just one public ip
good reference! Thanks for writing this up.
this is great. however too complicated for me when it comes to networking. is there nay easy way to run proxmox vms with just one public ip?
i got my own manual setup working, @loay does this script not need a network refresh using ifreload -a ?
No, iptables rules are independent of interface files.
AWESOME! I'm trying this. Anyone want a free low end nat box on my server to test out?
@loay Thanks for this amazing script. It does exactly what it says on the tin. However, I do have one question:
Isn't this:
To ensure the rules persist after reboot, use iptables-save > /etc/iptables/rules.v4 and iptables-restore < /etc/iptables/rules.v4.The same as this?
Thank you
Yes, they do the same thing except for the IPv6. I have actually updated this code since this post, I will review it and publish the new version. Let me know if you have any features requests or improvements
Great, thank you
I don't have any feature requests, but perhaps you could share the code via Github. That way it'll be easier to update and maintain the code 
Thanks!
I made something similar using a bash (😂😂😂) script. Yours looks good.
Cool stuff! Wish I would have had it when I was setting up proxmox and nat on my ovh box.
@loay is the new version of the script backwards compatible with the current one? I'm debating whether I should wait to set up my OVH box, as I'd prefer not to redo everything
Thanks!
No, sorry. It is not backwards compatible. Current script will work fine with only Proxmox on the server with no conflicting ports. This
subprocess.run(['iptables-save'], stdout=open('/etc/iptables/rules.v4', 'w'))dumps the entire system iptables rules including those bypve-firewall.