IP-Tag Configuration Guide

[MickLesk]

📘 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

---

📁 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.

---

⚙️ 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

🔹 Example: TAG_FORMAT

TAG_FORMAT="full"
# Tags like: 192.168.1.123

TAG_FORMAT="last_octet"
# Tags like: 123

TAG_FORMAT="last_two_octets"
# Tags like: 1.123

---

🔄 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

---

🧠 Performance Tuning

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

🔧 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

🔧 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

---

🧪 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

---

📌 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

---

🚫 Disabling the Service

To fully disable the background service:

systemctl disable --now iptag

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

---

🪵 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.

---

🧩 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

---

📥 Support & Feedback

If you're using the community-scripts version of IP-Tag, please open issues or pull requests on GitHub.

You can also join the Discord server:
👉 https://discord.gg/UHrpNWGwkH

---

[lexybarton]

👋 Hi @MickLesk,
thank you for your great work and all the upmost useful scripts – including this one, the IP-Tag ♥️

I always always thought that the information about the IP shall be more readily available. I really like the way you utilize the tags feature for this!

Anyways I noticed that it takes some time and that the discovery does not work for all of my LXCs. , so I wanted to ask whether you considered using another approach to obtain the IPs, e.g. something like this ˛lxc-info -n "$lxc_id" -siH --config=lxc.uts.name --config=lxc.net.0.hwaddr, which is a way I use in my script and it is fast and seems reliable.

My whole script looks like this

#!/bin/bash

# Auto-detect node name
NODE=$(hostname)

# Print CSV header
echo "lxc_id,hostname,hwaddr,ipv4,ipv6,state"

# Process each container
for conf_file in /etc/pve/nodes/$NODE/lxc/*.conf; do
  # Skip if no conf files exist
  [[ -f "$conf_file" ]] || continue

  lxc_id=$(basename "$conf_file" .conf)
  
  # Get all info in one command
  info=$(lxc-info -n "$lxc_id" -siH --config=lxc.uts.name --config=lxc.net.0.hwaddr 2>/dev/null)
  
  # Parse the output
  state=""
  hostname=""
  hwaddr=""
  ipv4=""
  ipv6=""
  
  while IFS= read -r line; do
    case "$line" in
      "State:"*)
        state=$(echo "$line" | cut -d: -f2- | tr -d ' ')
        ;;
      "IP:"*)
        # For IP lines, everything after "IP: " is the IP address
        ip=$(echo "$line" | sed 's/^IP: *//')
        # Determine if it's IPv4 or IPv6
        if [[ "$ip" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
          ipv4="$ip"
        else
          # Anything else with colons is likely IPv6
          ipv6="$ip"
        fi
        ;;
      "lxc.uts.name = "*)
        hostname=$(echo "$line" | cut -d= -f2- | tr -d ' ')
        ;;
      "lxc.net.0.hwaddr = "*)
        hwaddr=$(echo "$line" | cut -d= -f2- | tr -d ' ')
        ;;
    esac
  done <<< "$info"
  
  # Set defaults for missing values
  [[ -z "$hostname" ]] && hostname="N/A"
  [[ -z "$hwaddr" ]] && hwaddr="N/A"
  
  # Output CSV row
  printf "%s,%s,%s,%s,%s,%s\n" "$lxc_id" "$hostname" "$hwaddr" "$ipv4" "$ipv6" "$state"
done

It used to be twice as fast before I asked Claude to include parsing of the lxc-info's output into a more friendly csv format. But it still seems very fast.

# time scripts/new_getip.sh 
lxc_id,hostname,hwaddr,ipv4,ipv6,state
101,tandoor,BC:24:11:40:5F:FD,10.10.7.60,fde3:538f:d15e:5778:be24:11ff:fe40:5ffd,RUNNING
104,unifi,72:24:95:08:05:68,10.10.7.7,fde3:538f:d15e:5778:7024:95ff:fe08:568,RUNNING
107,nginxproxymanager,96:17:7C:5E:DC:CB,10.10.7.91,fde3:538f:d15e:5778:9417:7cff:fe5e:dccb,RUNNING
110,jupyternotebook,BC:24:11:EA:7E:AA,10.10.7.176,,RUNNING
111,monica,BC:24:11:78:84:A8,10.10.7.208,fde3:538f:d15e:5778:be24:11ff:fe78:84a8,RUNNING
113,nextcloudpi,BC:24:11:A5:42:7D,10.10.7.190,fde3:538f:d15e:5778:be24:11ff:fea5:427d,RUNNING

real    0m0.089s
user    0m0.051s
sys     0m0.064s

[djhojd]

Hi 👋
Mine also stopped working a while back and I really do not know what is wrong. Debugging shows the same for all my LXCs No IP detected, tags unchanged. 🤷‍♂️
What I've been doing is adding my version of lxc-info as the first method and for me this works:

# EXTREME Method 0: lxc-info --ips (fast, direct)
if [[ -z "$ips" ]] && command -v lxc-info >/dev/null 2>&1; then
    debug_log "lxc $vmid: trying lxc-info --ips extraction"
    local lxc_ip=""
    lxc_ip=$(timeout 1s lxc-info --ips "$vmid" 2>/dev/null | grep -m1 -oE '([0-9]{1,3}\.){3}[0-9]{1,3}' | grep -v '^127\.' | head -1)
    debug_log "lxc $vmid: [LXC_INFO] lxc_ip='$lxc_ip'"
    if [[ -n "$lxc_ip" ]] && is_valid_ipv4 "$lxc_ip"; then
        ips="$lxc_ip"
        method_used="lxc_info"
    fi
fi

[GTRasH]

the new script only adds a single tag. but before the update it was able to successfully update multiple ips.
typical usecase: one local ip and one tailscale ip.
the local one will be added, but the tailscale ip will never be grabbed and compared to the cidr list. this needs to be fixed.

[MickLesk]

your are welcome to fix it, i dont use tailscale, i dont have any idea how the cidr looks like for this. By the way, this is an Guide, please dont spam it and create an correct Issue or Discussion.

[rlust]

if anyone has found a way to get tailscle ip would love to see this!

[GTRasH]

I am working on this. Depends on time for fixing a remaining bug.

[Stefinet21]

I had an issue where IP-Tag could not detect IPs for my LXC containers.
In my Proxmox setup (L2-only bridges), the fast methods (namespace/ARP) always failed, and because LXC_SKIP_SLOW_METHODS=true was set, it never ran the reliable runtime detection.

The fix was to allow slow methods and force the script to use lxc-attach/pct exec if the faster methods fail.

Key changes:

LXC_SKIP_SLOW_METHODS=false
LXC_ALLOW_FORCED_COMMANDS=true
LXC_USE_PROCESS_NS=false
LXC_DISABLE_PROCESS_NS=true
LXC_FORCE_EXEC=true
LXC_METHOD_ORDER="config,exec,arp"

With these settings, the debug log now shows:

method='lxc_attach_forced'

for LXC IP detection, and it works reliably every time.

Full working config example (including CIDR list adjustments) is attached above – might save someone else a lot of debugging time.

---

Optimized /opt/iptag/iptag.conf Example

# IPTAG CONFIGURATION – Force reliable runtime IP detection for LXC
# Fix for environments where config/namespace/ARP detection fails (e.g., Proxmox L2-only bridges)

# Allowed IPv4 CIDRs – added 172.16/12 to include VPN/Tailscale/etc. addresses
CIDR_LIST=(
  192.168.0.0/16
  10.0.0.0/8
  100.64.0.0/10
  172.16.0.0/12
)

# Tag format: full | last_octet | last_two_octets
TAG_FORMAT="full"

# Intervals (seconds)
LOOP_INTERVAL=300
VM_STATUS_CHECK_INTERVAL=600
FW_NET_INTERFACE_CHECK_INTERVAL=900
LXC_STATUS_CHECK_INTERVAL=300
FORCE_UPDATE_INTERVAL=7200

# VM cache/parallelization
VM_IP_CACHE_TTL=300
MAX_PARALLEL_VM_CHECKS=1

# LXC cache/parallelization
LXC_IP_CACHE_TTL=300
MAX_PARALLEL_LXC_CHECKS=2
LXC_BATCH_SIZE=3
LXC_STATUS_CACHE_TTL=300
LXC_AGGRESSIVE_CACHING=true

# --- LXC IP detection settings ---
# Allow slow methods so runtime `lxc-attach` / `pct exec` is used as fallback
LXC_SKIP_SLOW_METHODS=false
LXC_ALLOW_FORCED_COMMANDS=true

# Disable unreliable process namespace method and force exec early
LXC_USE_PROCESS_NS=false
LXC_DISABLE_PROCESS_NS=true
LXC_FORCE_EXEC=true
LXC_METHOD_ORDER="config,exec,arp"

# Debugging
DEBUG=true

[DAE51D]

You're doing the lord's work @Stefinet21 😋 This just solved the issue for me and thank you for your full /opt/iptag/iptag.conf file.

And also thank you @MickLesk for the amazingly useful script to begin with (and TBH should just be native and built in to Proxmox honestly but I digress...)