Proxmox LXC Tag

Proxmox VE Proxmox VE Tools
, ,
1

icon
icon256×256 6.44 KB

This script automatically adds IP address as tags to LXC containers or VM's using a systemd service. The service also updates the tags if a LXC/VM IP address is changed.

To use the PVE LXC Tag script, run the command below only in the Proxmox VE Shell. This script is intended for managing or enhancing the host system directly.

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/tools/pve/add-iptag.sh)"
  • Configuration: nano /opt/iptag/iptag.conf. iptag Service must be restarted after change.
  • The Proxmox Node must contain ipcalc and net-tools. apt-get install -y ipcalc net-tools
  • You can execute the ip tool manually with iptag-run
IP-Tag Configuration Guide

The IP-Tag script automatically applies IP-based tags to LXC containers and VMs in Proxmox VE. This allows you to quickly identify machines by IP (or partial IP) directly in the Proxmox web UI.

This guide explains:

  • What the config values mean
  • How to adjust them to lower CPU usage
  • How to manually run the script on demand

:file_folder: Configuration File

The config file is located at:

/opt/iptag/iptag.conf

It contains all runtime settings and can be edited at any time. After editing, run:

systemctl restart iptag

to apply the changes.

:gear: General Settings

Variable Description Default
TAG_FORMAT Format for tags created from IPs last_two_octets
CIDR_LIST Allowed IP ranges for tagging (others are ignored) See below
LOOP_INTERVAL Time (in seconds) between script executions (when running as a service) 300
FORCE_UPDATE_INTERVAL Maximum time between forced re-checks (even without changes) 7200

:small_blue_diamond: Example: TAG_FORMAT

TAG_FORMAT="full"

  • Output format: Full IP address
  • Example:
    If IP = 192.168.1.123 → Tag = 192.168.1.123

TAG_FORMAT="last_octet"

  • Output format: Only the last octet of the IP
  • Example:
    If IP = 192.168.1.123 → Tag = 123

TAG_FORMAT="last_two_octets"

  • Output format: Last two octets of the IP
  • Example:
    If IP = 192.168.1.123 → Tag = 1.123

:counterclockwise_arrows_button: Update Intervals

Variable What it checks Default (seconds)
VM_STATUS_CHECK_INTERVAL Checks if VM state changed 600
LXC_STATUS_CHECK_INTERVAL Checks if LXC state changed 300
FW_NET_INTERFACE_CHECK_INTERVAL Detects bridge/interface changes 900

:brain: Performance Tuning

These values control how aggressively and in parallel the script scans containers/VMs. Lower values = lower CPU.

:wrench: VM Performance

Variable Description Suggested for Homelab
VM_IP_CACHE_TTL How long (in sec) to cache found IPs 300
MAX_PARALLEL_VM_CHECKS Max VMs to process in parallel 2–4

:wrench: LXC Performance

Variable Description Suggested for Homelab
LXC_IP_CACHE_TTL Time (in sec) to cache LXC IPs 300
LXC_STATUS_CACHE_TTL Cache status (running/stopped) of LXC 300
LXC_BATCH_SIZE How many LXCs to process at once in a batch 3–5
MAX_PARALLEL_LXC_CHECKS How many containers to check at the same time 2–3
LXC_AGGRESSIVE_CACHING Enables smart caching logic true
LXC_SKIP_SLOW_METHODS Disables pct exec and lxc-attach fallback (less accurate) true

:test_tube: Example: Optimized Config for Homelab

# Use simplified IP format
TAG_FORMAT="last_octet"

# Only tag private subnets
CIDR_LIST=(
  192.168.0.0/16
  10.0.0.0/8
)

# Lower background frequency
LOOP_INTERVAL=600
FORCE_UPDATE_INTERVAL=7200

# Reduce VM scan load
VM_IP_CACHE_TTL=300
MAX_PARALLEL_VM_CHECKS=2

# Reduce LXC scan load
LXC_IP_CACHE_TTL=300
LXC_STATUS_CACHE_TTL=300
LXC_BATCH_SIZE=3
MAX_PARALLEL_LXC_CHECKS=2
LXC_AGGRESSIVE_CACHING=true
LXC_SKIP_SLOW_METHODS=true

:pushpin: Manual Execution (no systemd required)

If you don’t want to run iptag as a service, you can run it manually at any time:

iptag-run

This command executes the tag update logic once and exits.
It does not stay running in the background.

The script is installed to:

/usr/local/bin/iptag-run

:prohibited: Disabling the Service

To fully disable the background service:

systemctl disable --now iptag

Then use iptag-run whenever you want to apply tags.

:wood: Log Output & Debugging

To avoid log spam, the service outputs minimal info. You can enable verbose logs for debugging:

DEBUG=true

Then run manually or restart the service.

:puzzle_piece: Troubleshooting

Problem Solution
High CPU load Lower LXC_BATCH_SIZE, MAX_PARALLEL_*, increase TTL values
Tags get removed unexpectedly Check TAG_FORMAT, CIDR_LIST and IP detection logic
Systemd restarts the service too often Ensure loop is internal, not via Restart=always
2

Awesome idea, thanks!

1 Like