Netbox Sync Device Prefixes Task¤
task api name:
sync_device_prefixes
The task derives IPv4 and IPv6 networks from live device interface addresses
and reconciles those prefixes with NetBox. It is independent from
sync_device_ip: it does not require NetBox interfaces and does not create or
update IP address records.
How It Works¤
- Resolve the selected devices and validate that they exist in NetBox.
- Run Nornir
parse_ttpwithget="interfaces"for the selected devices. - Apply interface, prefix, and ignore-range filters.
- Convert each address to its canonical network, for example
10.0.0.1/31to10.0.0.0/31. - Deduplicate observations, compare them with NetBox, and create missing or update out-of-sync prefixes.
NetBox interface presence is never checked. A prefix can therefore be synchronized before its source interface exists in NetBox.
Output¤
Results are keyed by device. Shared prefixes appear under each reporting device:
{
"ceos-spine-1": {
"created": ["10.0.0.0/31"],
"updated": ["10.0.1.0/31"],
"deleted": [],
"in_sync": ["2001:db8::1/128"]
}
}
The top-level diff field contains a reconciliation plan per device:
{
"ceos-spine-1": {
"create": [],
"update": {},
"delete": [],
"in_sync": ["2001:db8::1/128"]
}
}
The task does not delete prefixes, so delete is always empty.
Dry-run returns the same structure without writing to NetBox. With
with_approval=True, the prepared result is shown for approval before any
prefixes are written.
VRF Handling¤
ignore_vrf=True is the default:
- Prefixes are matched by canonical prefix alone.
- Existing VRF associations are preserved.
- New prefixes are created without a VRF.
With ignore_vrf=False:
- The live interface VRF is resolved by name; a missing VRF is created.
- Prefixes are matched by canonical prefix and VRF.
- If the same prefix exists in another VRF, that object is preserved and a new prefix is created in the live VRF.
globalanddefaultinterface VRFs are treated as the global table.
Site Handling¤
ignore_site=True is the default:
- Device sites are not written to prefixes.
- Existing prefix scope/site associations are preserved.
With ignore_site=False:
- New prefixes are associated with the reporting device's site.
- Existing matching prefixes are updated when their site differs.
- When several devices report the same prefix identity, the site from the alphabetically first device name is authoritative.
Prefix identity is the prefix alone when VRFs are ignored, otherwise it is the prefix and resolved VRF together.
Filtering¤
Interface filters are applied to live data before prefix derivation. Prefix filters are applied to the derived canonical prefixes:
filter_by_name— interface-name glob, such asLoopback*.filter_by_description— interface-description glob.filter_by_prefix— include prefixes contained within one IPv4 or IPv6 network.ignore_ranges— exclude derived prefixes fully contained within any supplied IPv4 or IPv6 network. A narrower ignored network does not exclude a broader live prefix containing it.
The default ignored ranges are:
127.0.0.0/8
224.0.0.0/24
fe80::/10
ff02::/16
::ffff:0:0/96
::1/128
Filters combine using intersection.
For example, ignore_ranges="10.3.15.33/32" does not exclude the live prefix
10.3.15.32/30, while ignore_ranges="10.3.15.0/24" does.
Deletion Behavior¤
The task never deletes prefixes. A prefix absent from the selected live device data is left unchanged in NetBox.
Branching Support¤
Pass branch=<name> to create or update prefixes in a NetBox Branching Plugin
branch. The task creates the branch when it does not already exist.
Bulk Request Batching¤
List-based NetBox writes are sent as sequential requests containing at most
batch_size objects. The default is 1000; set any integer greater than zero to
tune the request size. Each batch emits matching progress event and log messages. If
a request fails, the task stops and returns the results recorded for earlier
successful batches.
Examples¤
Synchronize prefixes from one device:
nf#netbox sync prefixes devices ceos-spine-1
Preview prefixes derived from loopbacks:
nf#netbox sync prefixes devices ceos-spine-1 filter-by-name "Loopback*" dry-run
Associate prefixes with live VRFs and device sites:
nf#netbox sync prefixes devices ceos-spine-1 ignore-vrf false ignore-site false
Select devices with a Nornir filter:
nf#netbox sync prefixes FC spine
result = client.run_job(
"netbox",
"sync_device_prefixes",
workers="any",
kwargs={
"devices": ["ceos-spine-1", "ceos-spine-2"],
"dry_run": True,
},
)
result = client.run_job(
"netbox",
"sync_device_prefixes",
workers="any",
kwargs={
"devices": ["ceos-spine-1"],
"ignore_vrf": False,
"ignore_site": False,
"filter_by_prefix": "10.0.0.0/8",
},
)
NORFAB Netbox Sync Device Prefixes Command Shell Reference¤
nf# man tree netbox.sync.prefixes
root
└── netbox
└── sync
└── prefixes
├── timeout
├── workers
├── verbose-result
├── progress
├── instance
├── dry-run
├── with-approval
├── devices
├── ignore-ranges
├── ignore-vrf
├── ignore-site
├── filter-by-name
├── filter-by-description
├── filter-by-prefix
├── branch
└── Nornir host filters
Python API Reference¤
Synchronize prefixes derived from live interface addresses into NetBox.
Prefixes are collected from the Nornir TTP interfaces getter without
requiring corresponding NetBox interfaces. Existing prefixes are matched
by prefix alone when ignore_vrf=True and by prefix plus VRF otherwise.
Site association is left unchanged by default. When ignore_site=False,
the site of the alphabetically first device reporting a prefix is used.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
job
|
Job
|
NorFab Job object containing relevant metadata. |
required |
instance
|
Union[None, str]
|
NetBox instance name. |
None
|
dry_run
|
bool
|
Return the reconciliation plan without writing to NetBox. |
False
|
with_approval
|
bool
|
Preview changes and ask for review before applying them. |
False
|
timeout
|
int
|
Timeout in seconds for Nornir parsing and host resolution. |
600
|
devices
|
Union[None, list]
|
Explicit device names to collect prefixes from. |
None
|
branch
|
str
|
NetBox Branching plugin branch name. |
None
|
ignore_ranges
|
Union[None, str, list]
|
Exclude derived prefixes fully contained in these ranges. |
None
|
ignore_vrf
|
bool
|
Ignore live VRFs and preserve existing prefix VRFs. |
True
|
ignore_site
|
bool
|
Ignore device sites and preserve existing prefix scopes. |
True
|
filter_by_name
|
Union[None, str]
|
Interface-name glob filter. |
None
|
filter_by_description
|
Union[None, str]
|
Interface-description glob filter. |
None
|
filter_by_prefix
|
Union[None, str]
|
Include prefixes within this network only. |
None
|
**kwargs
|
Any
|
Nornir host filter arguments. |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
Result |
Result
|
Per-device |
Source code in norfab\workers\netbox_worker\ip_tasks.py
1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 | |