From 8f704768881d2cb59cf1fbbff475cae0b522ff5c Mon Sep 17 00:00:00 2001
From: Bryan Joshua Pedini <bryan@pedini.dev>
Date: Tue, 25 Aug 2026 14:53:24 +0200
Subject: [PATCH] docs: ip_version option documentation

---
 README.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/README.md b/README.md
index 22cfd6f..5a8126d 100644
--- a/README.md
+++ b/README.md
@@ -15,6 +15,8 @@ in a config file, overridable per-run through environment variables.
   machines** (`virtualization/virtual-machines`)
 - Filter by tenant name, VRF name, cluster name, site name, hostname domain,
   or restrict IP addresses to the ones that have a DNS name (deduplicated)
+- Restrict either source to one IP family (`ip_version: v4` or `v6`),
+  combinable with any filter
 - Name-based filters are resolved server-side (name → id) so NetBox does the
   narrowing, not the script
 - Hosts land in a single `netbox` group with host variables delivered through
@@ -72,6 +74,7 @@ inventory:
 | `inventory.source` | `ip-addresses` | `ip-addresses` or `virtual-machines` |
 | `inventory.filter` | none | Filter option, see the table below |
 | `inventory.filter_value` | none | Value for the filter option |
+| `inventory.ip_version` | `both` | `both`, `v4` or `v6`; on IP addresses only that family is fetched, on virtual machines it selects which primary IP becomes `ansible_host` |
 
 Every relevant key can be overridden through the environment, which is how you
 run several differently-filtered inventories off one config file:
@@ -84,6 +87,7 @@ run several differently-filtered inventories off one config file:
 | `NETBOX_INVENTORY_SOURCE` | `inventory.source` |
 | `NETBOX_INVENTORY_FILTER` | `inventory.filter` |
 | `NETBOX_INVENTORY_FILTER_VALUE` | `inventory.filter_value` |
+| `NETBOX_INVENTORY_IP_VERSION` | `inventory.ip_version` |
 
 ## Filters
 
@@ -129,6 +133,11 @@ NETBOX_INVENTORY_FILTER=domain NETBOX_INVENTORY_FILTER_VALUE=example.com \
   is set to the primary IP when the VM has one, otherwise Ansible falls back
   to resolving the name. Host variables: `netbox_status`, `netbox_cluster`,
   `netbox_site`, `netbox_tenant`.
+- **IP version**: with `ip_version: both` (the default) virtual machines use
+  NetBox's combined primary IP, which **prefers IPv6** when a VM has both
+  (NetBox's `PREFER_IPV4` setting); set `v4` or `v6` to pin the family. On the
+  IP address source the family is filtered server-side, and a VM without a
+  primary IP of the requested family simply gets no `ansible_host`.
 - Duplicate inventory names (two IPs sharing a DNS name, outside the `named`
   filter) keep both hosts: the second one falls back to its bare address as
   the inventory name.