IPFabric SSoT Integration¶

SSoT IPFabric integration providing a simple way to synchronize data between IPFabric and Nautobot. Ensure data stays consistent between the two platforms by leveraging DiffSync capabilities and allowing users to take full advantage of both platforms with up-to-date, synchronized data.

Usage¶

You can navigate to the SSoT Dashboard with the following steps:

Click the Plugins menu and select Dashboard under Single Source of Truth.

Now you should see the dashboard with information pertaining to IP Fabric.

We can see IP Fabric under Data Sources with some quick information such as the results of the latest synchronizations and the ability to launch the synchronization job.

On the right-hand side, we're provided with additional information such as the source, target, start time, status, and the type of job.

Let's go ahead and click on IP Fabric under Data Sources.

Now we can see additional details as to which IP Fabric host we're syncing from and the models that get mapped between the source and destination. We can also kick off sync job by clicking on Sync Now, but we will revisit that shortly.

Below, the sync history is provided with more details of what happened during each synchronization job.

Now back to running the job. Let's click on Sync Now.

There are several options available.

Debug: Enables more verbose logging that can be useful for troubleshooting synchronization issues.
Safe Delete Mode: Delete operations changes the object status to a predefined value (configurable via settings) and tags the object with the Safe Delete Tag, SSoT Safe Delete unless configured otherwise.
Sync Tagged Only: Only load Nautobot data into DiffSync adapters that has the synced Tag, SSoT Synced from IPFabric unless configured otherwise.
Tenant: The Tenant this IP Fabric instance belongs to. Only that Tenant's records are read, and records the sync creates are given it. See Tenant.
Namespace: The Namespace the sync's IP Addresses, Prefixes and VRFs belong to, Global when left empty. See Namespace.
Bulk Write Mode: Write objects in batches rather than one at a time. Much faster on a large sync, at the cost of change log entries, signals and per-object validation. Disabled by default; see Bulk Write Mode for what it does and does not give up.
Sync Locations: Create, update and delete Nautobot Locations from IP Fabric sites. Enabled by default. Deselect where another system owns the site list; see Choosing what to sync for what that does and does not stop.
Sync Manufacturers: Create Nautobot Manufacturers for the vendors IP Fabric reports. Enabled by default.
Sync Device Types: Create Nautobot Device Types for the models IP Fabric reports. Enabled by default.
Sync Roles: Create Nautobot Roles from the device types IP Fabric reports. Enabled by default.
Sync Platforms: Create Nautobot Platforms from the families IP Fabric reports. Enabled by default.
Sync Software Versions: Record the OS version IP Fabric reports for each Device. Disabled by default. See Software versions.
Sync Software Images: Record the image file each Device booted from. Disabled by default; requires Sync Software Versions. See Software images.
Sync Interfaces: Sync each Device's Interfaces. Enabled by default.
Sync IP Addresses: Sync the IP Address on each Interface. Enabled by default; requires Sync Interfaces.
Sync Primary IP: Assign a Device's primary IP from IP Fabric. Enabled by default; requires Sync IP Addresses. IP Fabric reports the address it logged in with, which is not necessarily the address a CMDB considers the management one.
Sync Prefixes: Create Nautobot Prefixes in the job's Namespace from the networks IP Fabric reports, and record the Locations each is seen at. Disabled by default. See Prefixes.
Sync Host Addresses: Create an IP Address for each host IP Fabric discovers, with its DNS name and MAC address. Disabled by default, and needs Sync Prefixes and Sync IP Addresses. See Host Addresses.
Sync VLANs: Sync each Location's VLANs. Enabled by default.
Sync VRFs: Create Nautobot VRFs in the job's Namespace from the routing instances IP Fabric reports. Disabled by default. See VRFs and Route Targets.
Sync Route Targets: Sync the Route Targets IP Fabric reports and record each synced VRF's import and export targets. Disabled by default; requires Sync VRFs.
Sync Device VRFs: Record which Devices carry each VRF. Disabled by default; requires Sync VRFs.
Sync Interface VRFs: Put each Interface in the VRF IP Fabric reports for it. Disabled by default; requires Sync Interfaces and Sync Device VRFs.
Sync Cables: Sync the device connections in IP Fabric's connectivity matrix to Nautobot Cables. Disabled by default; requires Sync Interfaces. See Cables.
Dry run: This will only report the difference between the source and destination without synchronization.
Site Filter: Filter the data loaded into DiffSync by a top level location of a specified Site.

Deselecting an object type keeps it out of the sync in both directions, so existing Nautobot records of that type are left untouched rather than removed as absent from IP Fabric. An object type whose requirement is not selected is skipped, and the Job log names the unmet requirement. Devices are always synced, since every other object type is either a Device or hangs off one.

Which types appear on the form, and which are pre-selected, can be set per installation. See Choosing what to sync.

If interested to see the source code, click on Source.

After a job is launched, you will be redirected to the job results page which will provide any logged messages during the synchronization.

If you're interested in more details, click SSoT Sync Details.

You can then view the details of each object.

DiffSync Models¶

Currently, this integration will provide the ability to sync the following IP Fabric models into Nautobot.

Site ➡️ Nautobot Site
Device ➡️ Nautobot Device
Part Numbers ➡️ Nautobot Manufacturer/Device Type/Platform
Interfaces ➡️ Nautobot Device Interfaces
IP Addresses ➡️ Nautobot IP Addresses (primary, secondary, IPv6 and FHRP virtual)
Managed IP Summary ➡️ Nautobot Prefixes (opt in, see Prefixes)
Managed IP VLAN IDs ➡️ the VLAN of each Nautobot Prefix (with Prefixes, see A Prefix's VLAN)
Hosts ➡️ Nautobot IP Addresses (opt in, see Host Addresses)
Stack Members ➡️ Nautobot Virtual Chassis
Connectivity Matrix ➡️ Nautobot Cables (opt in, see Cables)

IPFabric Site¶

IP Fabric (Source)	DiffSync Model	Nautobot (Destination)
siteName	Location.name	Site

IPFabric Device¶

IP Fabric (Source)	DiffSync Model	Nautobot (Destination)
hostname	Device.name	Device.name
siteName	Device.location_name	Device.site
vendor	Device.vendor	Device.manufacturer
model	Device.model	Device.device_type
sn	Device.serial_number	Device.serial
devType*	Device.role	Device.role
version	Device.software_version	Device.software_version (opt in)
image	Device.software_image	Device.software_image_files (opt in)

Note: devType is an IP Fabric field that can be used to set the Device role. This can be disabled by setting ipfabric_sync_ipf_dev_type_to_role to False in the configuration. If this is disabled, the default role will be used for adding new devices and roles will be ignored during diffsync update preventing a custom Nautobot role from being overridden.

Note: disabling ipfabric_sync_ipf_dev_type_to_role does not make the sync role-neutral. It stops the IP Fabric device type deciding the role, but a Device the sync creates still receives the role named by ipfabric_default_device_role, because Nautobot requires one. To stop the sync creating that Role, deselect Sync Roles or select Roles under Strict Objects; a Device whose role Nautobot does not already hold is then skipped.

IPFabric Interface¶

IP Fabric (Source)	DiffSync Model	Nautobot (Destination)
intName	Interface.name	Interface.name
hostname	Interface.device_name	Interface.assigned_object
mac	Interface.mac_address	Interface.mac_address
mtu	Interface.mtu	Interface.mtu
N/A	Interface.type	Interface.type
primaryIp	Interface.ip_address	IPAddress.address
N/A	Interface.subnet_mask	IPAddress.address
N/A	Interface.ip_is_primary	Device.primary_ip

Note: Interfaces only support synchronizing 1 IP Address at the moment.

IPFabric VLAN¶

IP Fabric (Source)	DiffSync Model	Nautobot (Destination)
vlanId	Vlan.vid	VLAN.vid
siteName	Vlan.location	VLAN.locations
vlanName	Vlan.name	VLAN.name
dscr	Vlan.description	VLAN.description
N/A	Vlan.status	VLAN.status

The first two rows are what identify a VLAN; see How a VLAN is identified.

IPFabric VRF¶

VRFs are built from IP Fabric's VRF detail table (tables/vrf/detail), which names every VRF and the route distinguisher each device carrying it reports, and its L3 VPN route targets table (tables/mpls/l3-vpn/vrf-targets).

IP Fabric (Source)	DiffSync Model	Nautobot (Destination)
vrf	Vrf.name	VRF.name
rd	Vrf.rd	VRF.rd
importRT	Vrf.import_targets	VRF.import_targets
exportRT	Vrf.export_targets	VRF.export_targets
N/A	Vrf.status	VRF.status
N/A	Vrf.conflict	VRF.cf.ipfabric_vrf_conflict

IPFabric Route Target¶

Route Targets carry no attributes of their own. IP Fabric reports a route target as the value and nothing else, so a target either exists or it does not; Nautobot's description and tenant are left alone, and an operator can annotate one without the sync overwriting it.

IP Fabric (Source)	DiffSync Model	Nautobot (Destination)
importRT/exportRT	RouteTarget.name	RouteTarget.name

IPFabric VRF Device Assignment¶

One record per Device per VRF, from the same VRF detail table the VRFs themselves come from. A model of its own rather than a list of VRFs on the Device, because that is the shape of the data at both ends, so a Device that picks up one more VRF reports that assignment rather than its whole set.

IP Fabric (Source)	DiffSync Model	Nautobot (Destination)
vrf	VrfDeviceAssignment.vrf_name	VRFDeviceAssignment.vrf
hostname	VrfDeviceAssignment.device_name	VRFDeviceAssignment.device

IPFabric Interface VRF¶

Read from IP Fabric's VRF interfaces table (tables/vrf/interfaces) rather than from the managed addressing the sync already reads, because an Interface can be in a VRF while carrying no address.

IP Fabric (Source)	DiffSync Model	Nautobot (Destination)
hostname	InterfaceVrf.device_name	Interface.device
intName	InterfaceVrf.interface_name	Interface.name
vrf	InterfaceVrf.vrf_name	Interface.vrf

IPFabric Prefix¶

Prefixes are built from IP Fabric's managed IP summary tables (tables/addressing/ipv4-managed-ip-summary and tables/addressing/ipv6-managed-ip-summary), which list each network once per site it is configured at.

IP Fabric (Source)	DiffSync Model	Nautobot (Destination)
net	Prefix.prefix	Prefix.prefix
N/A	Prefix.status	Prefix.status

IPFabric Prefix Location¶

One record per network per site, from the same tables. A model of its own rather than a list on the Prefix, because a Prefix has to be written before the addresses under it while its Locations may only be created later in the same run.

IP Fabric (Source)	DiffSync Model	Nautobot (Destination)
net	PrefixLocation.prefix	Prefix
siteName	PrefixLocation.location_name	Prefix.locations

IPFabric Cable¶

Cables are built from IP Fabric's connectivity matrix (tables/interfaces/connectivity-matrix), which reports links that IP Fabric has already correlated from both ends.

IP Fabric (Source)	DiffSync Model	Nautobot (Destination)
localHost/remoteHost	Cable.termination_a_device	Cable.termination_a.device
localInt/remoteInt	Cable.termination_a_name	Cable.termination_a.name
localHost/remoteHost	Cable.termination_b_device	Cable.termination_b.device
localInt/remoteInt	Cable.termination_b_name	Cable.termination_b.name
N/A	Cable.status	Cable.status

Device serial numbers¶

IP Fabric records two serials for a device, and they mean different things:

IP Fabric column	What it is
`sn`	The serial IP Fabric identifies the device by, and keys its own tables on
`snHw`	The serial on the chassis

Nautobot's Serial field on a Device is documented as the chassis serial, so that is what it gets: snHw. The serial IP Fabric keys on is recorded beside it in the IPFabric Unique Serial Number custom field, so neither is lost and each is where it belongs. Earlier releases wrote sn into the Serial field, so on the first sync after upgrading, a device reporting both will have its Serial corrected.

Where IP Fabric reports no chassis serial, no serial is reported and the one Nautobot holds is left alone. A device with no chassis, a virtual one for instance, has none to report, and an empty value would drive Nautobot's Serial to empty on every run. The job logs how many devices this applied to. The unique serial is still recorded for them, so the value an earlier release put in the Serial field stays visible, and the custom field says what IP Fabric actually keys on.

A serial longer than the 255 characters Nautobot holds is treated the same way, and refused rather than truncated: a serial is an identity, and a prefix of one names no chassis.

Each member of a stack keeps its own serial, since each member is its own chassis. The stack's snHw describes the master alone.

Software versions¶

With Sync Software Versions selected, each Device gets the OS version IP Fabric reports for it. Nautobot files a Software Version under a Platform, so the version is looked up, or created, under the Platform the sync gives the Device from IP Fabric's family. A version Nautobot already holds for that Platform is used as it is; one the sync creates is marked Active and tagged SSoT Synced from IPFabric. Software Versions are never deleted by the sync.

A Device IP Fabric reports no version for, or no family, is left with whatever version Nautobot holds. Cloud devices are the usual case: AWS and GCP report no version, and Azure reports one but no family. If a Device's Platform changes, its version is moved to the Software Version of the same name under the new Platform.

The option is off by default, for deployments where software versions are maintained elsewhere.

Software images¶

With Sync Software Images selected as well, each Device also gets the image file IP Fabric reports it booted from. IP Fabric reports the image with its location, such as flash:/c3750e-universalk9-mz.150-2.SE10a.bin; the sync keeps the file name after the last / or :, lowercased.

The image is looked up, or created, under the Device's Software Version, and set on the Device. Nautobot only allows an image on a Device when the image is mapped to the Device's Device Type, so the sync adds that mapping for each Device Type it finds running the image. An image the sync creates is marked Active and tagged SSoT Synced from IPFabric. Images are never deleted by the sync.

The image set on a Device replaces any others it names, so a Device carries the one image IP Fabric reports. A Device with no image reported, or no Software Version, is left as Nautobot holds it, except that when its version changes, any image belonging to another version is removed. Many platforms report no image at all.

Interface state¶

IP Fabric records what it found at the last discovery: the physical (L1) and data link (L2) state of each interface, and the reason it gives for the L2 one. All three are synced to custom fields on the Interface (IPFabric L1 State, IPFabric L2 State and IPFabric State Reason), so what the network was doing is visible beside the interface rather than folded into Nautobot's own fields.

Enabled is derived from the L1 state and the reason together, because Nautobot's enabled is whether an interface is meant to be up, not whether it was found up. Most platforms report a shut port as plain down and put the administrative fact in the reason, so the reason is what separates a port somebody turned off from one whose cable is out:

L1 state	Reason	Nautobot `enabled`
names the administrator (`adminDown`, `admin-down`), or is `shutdown` or `disabled`	any	unchecked
`up`	any	checked
`down`	names the administrator (`admin`, `admin-down`)	unchecked
`down`	anything else, or none	checked
anything else		left as Nautobot holds it

A down interface with no administrative reason counts as enabled on purpose: it is meant to be running and is not, which is an operational problem rather than a decision, and the operational side is already recorded in the L1 and L2 custom fields.

errDisabled is deliberately not read as disabled, in either column. The switch took that port down for a fault it found, while the configuration still asks for it to be up. States are never matched by substring for that reason, since a substring match on disabled would catch it.

A state that names neither is reported in the job log, once per distinct value rather than once per interface, and the interface's enabled is left exactly as Nautobot holds it. The interface is reported as absent by both adapters, so enabled is not diffed against a guess on every run. An address with no reported subnet mask gets the same treatment.

An interface IP Fabric reports no state for at all is left alone the same way, but is not reported, there being no reading to report. That covers the pseudo management interface the sync fabricates to carry a NAT address.

Interface type¶

The Nautobot Interface type is resolved from the media type IP Fabric reports for the port, and failing that from the interface's name: Vlan100 is virtual and Port-channel1 is a LAG whether or not a media type came with them. The media type wins where it resolves, since what the platform reports about a port is better evidence than what somebody called it.

A logical interface with no port behind it is virtual by name, since IP Fabric reports no media type for one: Junos tunnel and service interfaces numbered by slot, such as gr-0/0/0, lt-0/0/0 and sp-0/0/0; Junos pseudo-interfaces such as st0, fti0, irb, vlan, gre, ipip and lsi; Null0; and Linux tun devices. One Nautobot already holds as 1000base-t or any other type is updated to virtual, and a Cable on it is handled as for a subinterface that holds a Cable.

Where neither resolves, no type is reported and the one Nautobot holds is left alone. A configured default written in that position would be indistinguishable from a type genuinely resolved to that value, and would overwrite a type set by hand or by another source on every run. As with enabled, the interface is reported as absent by both adapters, so the type is not diffed against a guess.

The job log says what went unresolved, once per distinct cause rather than once per interface:

a media type that maps to no Nautobot interface type, named as IP Fabric reported it;
a naming scheme that matches no pattern, named by the letters its interfaces start with, so Ethernet1/1 and Ethernet49 are one line rather than two.

Both are there so the resolution can be improved: the first says which media string to map, the second which naming pattern to add. Plain Ethernet names, as used by Arista EOS and by Linux hosts, match no pattern today, so an estate using them and reporting no media type will see that line.

ipfabric_default_interface_type still applies to an interface the sync creates, because Nautobot requires a type and a new interface has no earlier value to keep. It is no longer applied to an interface Nautobot already holds.

Interfaces the inventory leaves out¶

tables/inventory/interfaces is the only table this sync reads interfaces from, and it does not always carry the virtual ones. An SVI, a loopback or a tunnel can be absent from it while the managed address table reports an address configured on that very port.

Those interfaces are synced. An interface named this way is not invented: IP Fabric states that an address is configured on it, so the port exists and only the inventory is silent about it. That is what separates it from the placeholder interface, which is a name this sync makes up and which Strict Objects exists to stop.

The record carries no media type, MAC or state, because the table reporting those is the one that left it out, so the type is read from the name. The job reports what was missing once per naming scheme rather than once per port, so you learn that your appliance omits VLAN interfaces rather than reading four hundred lines naming each one.

Subinterfaces¶

IP Fabric reports no relation between a subinterface and the port it is configured on, so the name is the evidence: a dot separates the two, on IOS (GigabitEthernet0/1.100) and on Junos (ge-0/0/0.0) alike. The part before the last dot is the port, and that is what Parent Interface is set to.

A subinterface given a parent is synced as a virtual interface. Nautobot accepts a parent on nothing else, and a subinterface has no media of its own. Expect this to be visible on Junos, where every logical unit is named this way.

Only where the port is one the same device reported. A dot in a name is not proof a port exists, so a subinterface whose port this run did not see keeps the type it had and gets no parent. The job counts those by naming scheme.

A subinterface that holds a Cable¶

Nautobot refuses a Cable on a virtual interface. Earlier releases gave an interface whose name resolved no type the configured default, 1000base-t, which a Junos tunnel unit such as st0.0 always fell to, and IP Fabric's connectivity matrix reports tunnel adjacencies as links, so such a unit may hold a Cable from an earlier sync. A tunnel is virtual and is not cabled, so that Cable is one Nautobot does not allow.

With Safe Delete Mode off, the Cable is removed when the unit is made virtual, freeing the interface at its other end as well. With it on, which is the default, nothing is removed: the unit keeps its type and gets no parent, and the job counts how many were held back this way. Run once with Safe Delete Mode off to clear them.

A link seen on subinterfaces¶

IP Fabric reports a link between the interfaces the adjacency was seen on, which for a subinterface is the logical unit: ge-0/0/0.0 at one end, ge-0/0/0.0 at the other. No Cable lands on a unit, so the link is recorded as a Cable between the ports the units are configured on, ge-0/0/0 to ge-0/0/0. Several units between one pair of ports, one per VLAN on a trunk, share that one Cable. A unit linked to an ordinary port moves only its own end.

A tunnel is the exception. st0.0 to st0.0 is a peering reached over IP rather than along a Cable, so it is not moved onto the ports beneath it and is not cabled at all. Tunnels are recognised by name: Junos secure, GRE, IP-IP, logical and virtual tunnels (st, gr, ip, lt, vt), flexible tunnels (fti), and IOS Tunnel.

Port channels¶

The members of a port channel come from Technology > Port Channels > Member Status, which reports them as one string with each member's state in brackets after it. Each member's LAG is set to the channel it belongs to.

A subinterface is never put in a port channel: Nautobot refuses one on a virtual interface, and a subinterface is virtual. Where IP Fabric reports one as a member, the membership is left off and the job names the interface, since it is a shape nothing expects.

Interface VLANs¶

Sync Interface VLANs records each switchport's 802.1Q mode and the VLANs it carries. It is off by default and needs Sync VLANs and Sync Interfaces, since Nautobot refuses an Interface a VLAN that is not available at its Device's Location.

Two IP Fabric tables feed it. Technology > Interfaces > Switchport describes the switchports:

IP Fabric reports	Nautobot 802.1Q mode	Untagged VLAN	Tagged VLANs
`access`	Access	the access VLAN	N/A
`trunk`, allowing every VLAN	Tagged (All)	the native VLAN	N/A
`trunk`	Tagged	the native VLAN	the VLANs it allows

A trunk allowing every VLAN reports 1-4094 or 1-4095 depending on the platform, and is recorded as Tagged (All) rather than as four thousand tagged VLANs, which is both what Nautobot means by the mode and what the device means. Any other trunk list is parsed the way the configuration writes it, so 110-119,999 becomes the eleven VLANs it names.

Technology > Addressing > Managed IP covers what the switchport table does not: a routed interface such as an SVI is not a switchport, and the address table is where IP Fabric names the VLAN it sits in. Such an interface is recorded as Access on that VLAN. Where both tables describe the same interface the switchport table wins, being the direct statement of the port's configuration.

What it will not do¶

A VLAN ID with no VLAN at the Interface's Location is reported in the job log and left off the Interface, because Nautobot has nothing to point it at. Under a Site Filter that is ordinary rather than a fault: the run covers one site's VLANs, and a trunk may allow another site's.

A switchport mode with no Nautobot equivalent is counted and reported, once per mode rather than once per interface, and those interfaces are left alone.

Voice VLANs are not synced. IP Fabric reports one, but Nautobot has no distinct field for it.

A VLAN the run has no row for is left off. A trunk names the VLANs the port allows, and that can include one configured at another site or one IP Fabric reports no VLAN for. An interface cannot be put in a VLAN that is not there, so those IDs are left out of what the sync asks for and reported as a count once per run. The interface is still synced with the VLANs that are there. This is ordinary under a Location filter, where the run covers one site's VLANs while a trunk may name another's.

The VLAN an addressed interface sits in is read whether or not IP Addresses are in scope. The managed address table carries both, and a routed interface such as an SVI has no switchport row, so selecting Sync Interface VLANs reads that table even with Sync IP Addresses off. No address is synced by it. Without that the sync would report nothing for an SVI while Nautobot still held one, and the difference would clear what an earlier run wrote.

An Interface that IP Fabric stops reporting as a switchport has its mode and VLANs cleared. Nothing is deleted, the Interface and the VLANs both remain, so Safe Delete Mode does not apply.

How a VLAN is identified¶

A VLAN is identified by its VLAN ID at a Location. The name is an attribute, not part of the identity, which is what makes a rename on the network read as an update to the VLAN Nautobot already holds rather than as one VLAN replacing another. The VLAN ID is the identifier that persists across a rename on the device, and it is what IP Fabric keys its per-site VLAN summary on.

What this changes on upgrade. If Nautobot already holds a VLAN with the same VLAN ID at the same Location but a different name, the first sync after upgrading renames it to what IP Fabric reports. Previously the sync created a second VLAN under the new name and removed the one under the old name, or, under Safe Delete Mode, deprecated and tagged it. So an estate that has been renaming VLANs will see a run of renames once, and stop accumulating deprecated VLANs afterwards.

A VLAN Group per Location. Nautobot enforces (vlan_group, vid) and (vlan_group, name), and enforces neither where the VLAN has no group. So a Location's VLANs are filed under a VLAN Group of its own, named after the Location, which is what makes one VLAN ID mean one VLAN there.

VLANs that predate the group are moved into it, since the constraint only covers what is actually in it. Expect that on the first sync after upgrading. Being in a group is synced as a property of the VLAN rather than applied only when one is created, so a VLAN nothing else about has changed is adopted too. A VLAN already filed under some other group keeps it, because the constraint is what this needs and re-filing would fight whatever put it there.

Two VLANs of one name at a Location. A group makes the name unique within it as well as the VLAN ID, so only one of the pair can be filed under it. The other is synced without a group, which leaves its VLAN ID unconstrained there, and is reported once. It is not reported again on later runs: both sides of the sync read the name as already taken, so the VLAN settles as ungrouped rather than being offered to the group and refused on every run. It is adopted as soon as the duplicate name is resolved in Nautobot or on the network.

A VLAN Group name is unique across Nautobot. Where a group of that name already belongs to another Location it is left alone and reported, and that Location's VLANs are synced without a group, which leaves their VLAN IDs unconstrained. Selecting VLAN Groups under Strict Objects has the sync match an existing group rather than create one, for a deployment that governs its groups elsewhere.

One consequence to know about: a group makes VLAN names unique within it as well as VLAN IDs. Two VLANs at one Location sharing a name cannot both be filed under it, so the second is reported in the job log and left unsynced. Without a group they would both be written, so this is a case the sync starts reporting rather than one it introduces.

Long names. A VLAN name longer than the 255 characters Nautobot holds is truncated, and the full value is reported in the job log. The VLAN itself is still synced, since its identity does not depend on the name.

Interface Addresses¶

An Interface carries every address IP Fabric reports for it, each synced as its own IP Address in Nautobot. Three tables are read: technology.addressing.managed_ip_ipv4 and managed_ip_ipv6 for the addresses configured on the interface, and technology.fhrp.group_state for FHRP virtual addresses, IPv4 and IPv6. So a secondary address, an HSRP or VRRP virtual address, and IPv6 alongside IPv4 all reach Nautobot, which is what lets a template render them from Nautobot data.

A prefix length is what the sync records, not a dotted netmask, which is what makes an IPv6 address expressible at all: a netmask is undefined above a length of 32. Each address is diffed on its own. An Interface gaining a third address reports that one address rather than its whole set, one IP Fabric stops reporting is removed without touching the rest, and the job log names the address that moved. An address is matched on its host within its Interface, not on its address, because the mask is the attribute IP Fabric can change for an address it keeps reporting; matching on the mask as well would report a corrected mask as one address replacing another.

Because every address on a synced Interface is now read, an address IP Fabric does not report is removed rather than being invisible to the sync, including an IPv6 address, or a second IPv4 one, that another system put there. Safe Delete Mode, which is on by default, marks and tags such an address rather than deleting it. Take an Interface out of scope, or deselect Sync IP Addresses, where another system owns the addresses on it.

Removing an address goes through Safe Delete Mode as any other object does, and with that mode disabled the address is deleted rather than only reported as deleted. Removal happens only where no other Interface holds it: one Nautobot IP Address can be assigned to several Interfaces, and deleting it for one would take it from all of them. An address on another Interface is unassigned from this one instead.

The Device's primary_ip4 and primary_ip6 are set by marking an address already synced from the Interface carrying it. IP Fabric reports loginIpv4 and loginIpv6 separately, so a dual-stack Device names one of each and Nautobot carries both; a release reporting only the older single loginIp column marks that one. Marking an address primary resolves nothing of its own; the prefix length is the one the Interface already reported for it. Sync Primary IP governs the marking alone; deselecting it still syncs the addresses themselves.

An address that stops being logged in on is unmarked, so the Device stops recording it as primary, either because the primary moved to another address or because IP Fabric reports no login address for the Device at all. The unmarking is keyed on the address the Device currently points at, so a primary that moves settles whichever of the two addresses the sync writes first.

The exception is a management address reached through NAT, which belongs to no interface and so is on none of them to mark; that is what Placeholder Interfaces covers.

FHRP virtual addresses¶

A virtual address has no subnet of its own in IP Fabric's FHRP tables, so it resolves at the third rung described under Subnet Masks: the subnet of whichever of its Interface's addresses contains it. Where none covers it, it is withheld exactly as any other address with no usable subnet is, and counted in the same summary; it is not written under a guessed mask.

The virtual addresses come from IP Fabric's FHRP group state table, which has a row for each device and Interface in a group. The primary virtual address, IPv4 or IPv6, and any secondary virtual addresses are added to the Interface on every device that is a member of the group, so the active and standby routers both carry them.

Subnet Masks¶

An address has no mask of its own in IP Fabric. The subnet comes from the managed address tables (technology.addressing.managed_ip_ipv4 and managed_ip_ipv6), which are the only place IP Fabric says what subnet an address was configured with. Four sources are tried in order, so every address resolves the same way whichever table it came from: the managed tables, then a subnet the record carries itself (only the fabricated management Interface does), then a subnet already resolved for that Interface which contains the address (only a record with none of its own, such as an FHRP virtual address, may take this), and failing all of those the fallback below.

IP Fabric describes a subnet per Device, so an address on several Devices carries whatever subnet each of them reports for it. Nautobot holds one mask per IP Address, and parents an address to the most specific Prefix containing it, so two records for one address in a Namespace cannot coexist.

Where the reports disagree, the sync takes the narrowest of them for every Interface carrying that address, which is the report that agrees with the address's parent Prefix, and logs the address it did this for. Choosing once rather than per Device is what lets the mask settle; following each Device's own report left every run rewriting what the last had written.

When no subnet mask is reported¶

With IP Addresses selected under Strict Objects, which is the default, an address the table reports no subnet mask for is reported as absent. The mask Nautobot already holds is then left alone, and an address Nautobot does not hold is not created. The job logs how many addresses this applied to; enable Debug to see which they were and on which Interface each was found.

The selection governs reading on both sides, as Sync Tagged Only does, so that an address withheld from writing is not reported as a difference on every run.

Deselecting it syncs the address as a host route instead: a /32, or a /128 for IPv6. That puts it under the wrong parent Prefix and leaves nothing to distinguish it from an address genuinely configured as a host route, so every use of the fallback is logged as a warning naming the address. Deselect it only where a host route is preferable to no change at all.

A NAT management address is unaffected by this selection. It belongs to no interface, so IP Fabric reports no subnet for it and a host route is the whole of it, the value rather than a fallback. Whether that address is carried at all is decided by the Interfaces selection instead, since it needs an Interface the device does not have; see Placeholder Interfaces.

A subnet that does not parse counts as none reported: it is logged and passed over rather than raised, since one such row would otherwise end the job while it was still reading and lose every address that was fine. Either IP version is accepted, since what the sync records is a prefix length. Whether the subnet contains the address it was reported for is not checked; that is a different kind of wrong data, and one this sync has no better answer for than the mask itself.

Prefixes¶

Prefix synchronization is opt in via the Sync Prefixes job option and is disabled by default, since many installs manage Prefixes in another IPAM.

Selected, each network in IP Fabric's managed IP summary becomes a Prefix in the job's Namespace, IPv4 and IPv6 alike, with the Locations IP Fabric sees it at. A network configured at several sites is one Prefix with several Locations, since a Namespace holds one of each network. Prefixes are written before anything else, so the addresses synced onto Interfaces are filed under them rather than under Prefixes created to accommodate each one.

A Prefix Nautobot already holds for the same network is adopted rather than duplicated: it is tagged SSoT Synced from IPFabric and its type and status are left as they are. Only Prefixes carrying that Tag are read back from Nautobot, so a Prefix the sync never tagged is never removed. One it did tag, or adopted, is removed once IP Fabric stops reporting it, through Safe Delete Mode like any other object. Nautobot will not delete a Prefix that still holds addresses, so such a Prefix stays and the job log names the refusal.

A Location is recorded on a Prefix only where this run loaded a Location of that name. A site Nautobot holds no Location for is reported once with the number of Prefixes it applied to. The Location's type is made to permit Prefixes where it did not, as it is for VLANs. Under a Site Filter, a run sees only that site's networks, so it may add Prefixes and Locations but removes neither.

A Prefix's VLAN¶

IP Fabric's managed IP tables name the VLAN each address sits in. Nautobot holds one VLAN per Prefix, so a Prefix is put in a VLAN only when every address in the network that names one names the same VLAN at the same site. Addresses that name no VLAN, such as those on routed ports, are not counted.

Where they agree, the Prefix is put in that VLAN, looked up by its ID at that site. The sync doesn't create the VLAN: if Nautobot holds no such VLAN, the Prefix is left as it is and the job reports it once, with the number of Prefixes it applied to. Sync VLANs creates the VLANs IP Fabric reports, so selecting it alongside Sync Prefixes fills this in.
Where they disagree, the Prefix is left without a VLAN, and its IPFabric Prefix VLAN Conflict custom field lists each VLAN and site reported, for example IP Fabric reports this network in VLAN 10 at site1, VLAN 20 at site2. The job reports how many Prefixes this applies to, with a few examples. A VRF's route distinguisher is handled the same way.
Where IP Fabric reports no VLAN for a network, the Prefix is taken out of its VLAN, including one set on it by hand. Neither the Prefix nor the VLAN is deleted. Only Prefixes carrying the synced Tag are read, so a Prefix the sync never tagged keeps its VLAN.

Ranges reused at unrelated sites¶

Nested Prefixes are the ordinary shape of an address plan and are synced as such. Where a network sits inside, or contains, a network IP Fabric reports only at other sites, it is more often the same range used twice, a 10.0.0.0/24 in one cloud account and a 10.0.0.0/25 in another. One Namespace cannot tell those apart, so they are synced as one hierarchy, and the job reports how many networks this applies to with a few examples. Holding them separately needs a Namespace per routing domain: an IP Fabric instance per domain, each synced with its own Namespace.

Addresses outside every Prefix¶

Without Prefixes synced, an address no Prefix covers gets one created for it, since Nautobot will not hold an address without a parent. That makes a first sync into an empty Nautobot work, but where another system owns IPAM it hides address space the IPAM doesn't know about.

Selecting Prefixes under Strict Objects stops that, and stops the sync creating a Prefix by any route. An address no Prefix in the job's Namespace covers is left unwritten, and the job reports every such address together once the sync is over, as address on device:interface. Any Prefix containing the host will do, whatever its length against the address's mask, since that is all Nautobot needs to parent it. The address is reported on every run until a Prefix covers it.

With Sync Prefixes selected as well, the networks IP Fabric reports are matched against the Prefixes Nautobot already holds rather than created. One Nautobot holds is adopted and recorded at its Locations as usual; one it does not is left out, and the job lists those networks together once the sync is over.

Sync Prefixes	Strict about Prefixes	A network IP Fabric reports	An address no Prefix covers
Off	Off	Not synced.	Gets a Prefix created for it.
Off	On	Not synced.	Is reported and left unwritten. The case for an IPAM owned elsewhere.
On	Off	Created, or adopted where Nautobot holds it.	Gets a Prefix created for it, though one of IP Fabric's networks almost always covers it already.
On	On	Adopted where Nautobot holds it, otherwise reported and not created.	Is reported and left unwritten.

Host Addresses¶

Host address synchronization is opt in via the Sync Host Addresses job option and is disabled by default. IP Fabric discovers hosts, such as servers and virtual machines, from ARP and MAC tables. For an estate of routers, switches and firewalls they are addresses nobody manages, but where addresses are handed out outside IPAM they show how much of each subnet is really in use. The option needs Sync Prefixes and Sync IP Addresses selected as well.

Selected, each host in IP Fabric's IPv4 and IPv6 host tables becomes an IP Address in the job's Namespace:

A host is reported without a mask, so it takes the length of the most specific network IP Fabric reports that covers it, which is also the Prefix it is filed under. A host no reported network covers is not synced, and the job reports how many with a few examples.
Its DNS name is written to the IP Address's DNS name, and its MAC address to the IPFabric Host MAC custom field. An address IP Fabric reports for more than one host, as the same address in two VRFs can be, is synced without either, since which host they describe is not known.
An address Nautobot already holds is adopted and given the synced Tag rather than duplicated. A host whose address is on an Interface IP Fabric reports is left to that Interface.
A host IP Fabric stops reporting is removed through Safe Delete Mode like any other object: with Safe Delete Mode selected it is marked rather than deleted, and restored if IP Fabric discovers it again. Only IP Addresses carrying the synced Tag that no Interface holds are read back, so this never touches an address the sync did not write, and an address an Interface holds is never removed as a host. An address the sync tagged that an Interface used to hold, but no longer does, is read as a host and removed if IP Fabric does not report it as one.

With Prefixes under Strict Objects, a host no Prefix Nautobot holds covers is left unwritten and reported with the other addresses outside every Prefix.

Strict Objects¶

Strict Objects is a check on the data IP Fabric reported, applied on top of what is in scope. The scope decides which object types a run covers; this decides, for the types it does cover, whether what IP Fabric said about them is taken on trust or checked first. Nothing here brings a type into scope, and selecting a type that is out of scope does nothing; the job says so rather than leaving the selection looking like the reason nothing was written.

Left unselected, the sync takes the report at face value and fills any gap itself: a site name becomes a Location, a model becomes a Device Type, a family becomes a Platform, an address with no reported subnet becomes a host route. Where the data is good that is exactly right, and it is what makes bootstrapping an empty Nautobot work. Where it is not, a typo mints a near duplicate that is indistinguishable from a curated record.

Selected, the value is checked instead. For a supporting object the check is that the name resolves to something Nautobot already holds; for an address it is that IP Fabric reported a subnet mask for it. What fails is reported, the affected record is left unwritten, and the sync carries on with the rest. Selecting a type never stops Devices syncing.

What a failed check costs differs by type:

Selected	When the reported value does not check out
Locations	The site is reported and the Devices at it are skipped.
Manufacturers	The vendor is reported, and no Device Type is filed under it.
Device Types	The model is reported and the Device is skipped, since Nautobot requires one.
Roles	The role is reported and the Device is skipped, since Nautobot requires one.
Platforms	The platform is reported and the Device is synced without one, as Platform is optional.
Statuses	The status is reported and the record that needed it is skipped.
Virtual Chassis	The stack is reported and its membership is left unrecorded.
Interfaces	No Interface is invented to hold a management address IP Fabric reports against none, so that address goes unsynced.
IP Addresses	The address is reported and left as Nautobot holds it. See Subnet Masks.
Prefixes	No Prefix is created. An address no Prefix covers is reported and left unwritten, and a network IP Fabric reports that Nautobot does not hold is reported rather than created. See Addresses outside every Prefix.

Only IP Addresses is selected by default. Whether a name may be trusted depends on who owns the object, which only you know, so every other type defaults to taking the report on trust and an existing sync does not change behaviour on upgrade. A mask the source never reported is not data whoever owns IPAM, which is why that one is checked by default. Each default can be set for the whole instance with an ipfabric_strict_<type> setting, for example ipfabric_strict_locations.

For a type the sync only ever creates (Manufacturers, Device Types, Platforms, Statuses), a failed check and a deselected Sync option leave Nautobot in the same state, since creating is all the sync would have done. They still answer different questions: deselecting Sync Manufacturers means this run does not sync vendors at all, while selecting Manufacturers here means it does sync them and reports a vendor whose Manufacturer is missing rather than inventing one.

Safe Delete Mode's own statuses are outside this control. They are the integration's vocabulary rather than anything IP Fabric reported, so there is nothing to check, and refusing to create one would leave a record neither deleted nor marked, the outcome Safe Delete Mode exists to prevent.

Placeholder Interfaces¶

Where a Device's management address matches no Interface IP Fabric reported, which happens when the address is reached through NAT, the sync invents an Interface named pseudo_mgmt to hold it. That Interface does not exist on the device, so anything reading Nautobot Interfaces as real is misled by it.

Selecting Interfaces under Strict Objects stops it being invented. The Interfaces IP Fabric did report are synced as before; only the placeholder is withheld, and the management address goes with it, since it had no Interface of its own to sit on.

The selection stops new placeholders rather than removing those an earlier run created. One already in Nautobot is left alone, since withdrawing it from only one side of the diff would read as absent from IP Fabric and delete it. The job names every one it found, so they can be dealt with deliberately.

Sync Tagged Only¶

With Sync Tagged Only selected, which is the default, the sync reads and writes only Devices carrying the SSoT Synced from IPFabric Tag. Deselecting it brings every Device in the selected Locations into scope, including Devices another process created, and the sync then updates their Interfaces as well as those of the Devices it created itself.

The option governs reading and writing together. It has to: a Device loaded from Nautobot but excluded from writing would have every difference IP Fabric reports about it reported again on every run and never applied.

Cables follow the same rule. With Sync Tagged Only selected, only Cables carrying the synced Tag are read, so a Cable another process made between two synced Devices is never removed for being absent from IP Fabric. If a link IP Fabric reports needs an Interface such a Cable occupies, the link is reported and not recorded, rather than the other Cable being removed. A Cable that already joins the same two Interfaces IP Fabric reports is adopted and tagged.

Tags the sync applies¶

The sync marks what it writes with the synced Tag, SSoT Synced from IPFabric by default, and what Safe Delete Mode sets aside with the Safe Delete Tag, SSoT Safe Delete by default. Both names can be changed with the ipfabric_synced_tag and ipfabric_safe_delete_tag settings, for example so that two IP Fabric instances syncing into one Nautobot each mark their own objects. With Sync Tagged Only selected, each sync then only reads and changes the objects carrying its own Tag.

To rename the Tag on an existing install, rename the Tag in Nautobot and change the setting together. Changing only the setting leaves every existing object on the old Tag, so with Sync Tagged Only selected none of them is in scope. The Job log warns when the configured synced Tag marks nothing while the default one still marks objects.

Tenant¶

Selecting a Tenant runs the sync on behalf of that Tenant, for an IP Fabric instance dedicated to it.

Only the Tenant's Devices, VLANs, VRFs, Route Targets and Prefixes are read from Nautobot. Interfaces, their addresses, Cables and VRF assignments follow the Devices they belong to.
Objects the sync creates are given the Tenant, including Locations, IP Addresses and the parent Prefix created for an address. An address only needs its parent Prefix to exist, so a parent Prefix Nautobot already holds keeps whatever Tenant it has.
An object IP Fabric reports that already exists with no Tenant is adopted and given the Tenant, so the next run reads it.
An object that already belongs to another Tenant is never changed. The job lists those once, by type, at the end of the run. A Prefix of another Tenant is not recorded at any Location either.
Existing Locations are not narrowed or claimed, since a site may be shared or owned by another system.

With Tenant left empty, every object is read regardless of Tenant and no Tenant is set.

Namespace¶

IP Fabric has no Namespace concept, so the sync puts every IP Address, Prefix and VRF in one Namespace per run: the Namespace chosen on the job, or Global when it is left empty. For an IP Fabric instance whose addressing overlaps another's, sync each into its own Namespace.

With a Namespace chosen:

IP Addresses, Prefixes and VRFs are read from that Namespace only, and the ones the sync creates are put in it, including the parent Prefix created for an address.
An address another Namespace holds is never reused or removed, even on an Interface the sync manages. The same address can then exist in both, which is what Namespaces are for.

Choosing a Namespace for an install that has been syncing into Global does not move what is already there. The sync no longer reads the Global objects, so it neither updates nor removes them, and creates its own in the chosen Namespace. Remove or move the Global ones in Nautobot if they are not wanted.

With no Namespace chosen, the sync writes to Global. An IP Address whose mask matches what IP Fabric reports is reused from whatever Namespace holds it, and every address on a synced Interface is read.

VRFs and Route Targets¶

VRF synchronization is opt in via the Sync VRFs job option and is disabled by default, because a network whose VRFs are modelled in another system should not have them introduced by a sync. Route targets are a second option on top of it, so a deployment that wants VRFs but governs route targets elsewhere can have one without the other.

VRFs are created in the job's Namespace, the same Namespace the sync puts Prefixes and IP Addresses in.

One value per VRF, from many devices¶

IP Fabric reports a route distinguisher per device, and route targets per device and per address family. Nautobot holds one route distinguisher and one set of targets per VRF. The sync therefore reconciles what the devices reported before writing anything:

Where every device carrying a VRF reports the same route distinguisher, that is the VRF's.
Where they disagree, the network is misconfigured. No route distinguisher is recorded, and the disagreement is written to the IPFabric VRF Conflict custom field. A VRF silently carrying one device's value would be worse than one carrying none: there would be nothing to say which device it came from, or that there was a disagreement at all.
Route targets are reconciled the same way, and independently of the route distinguisher, so a VRF whose devices agree on one but not the other still records the one they agree on.
A device's address families are combined rather than reconciled against each other, since Nautobot holds one set of targets per VRF: a device importing one target for IPv4 and another for IPv6 imports both.
A VRF that has no route distinguisher and no route targets on any device is created as it is.

Route Targets as objects¶

Route Targets are an object type of their own, synced ahead of the VRFs that name them and counted in a run's own create and delete totals. A VRF records the targets Nautobot holds; it does not create them.

A Route Target's name is unique across the whole of Nautobot, so one that another process already created is the same object this sync would have made. It is adopted and marked as synced rather than duplicated, which is what lets a first run converge against an existing estate.

Only the Route Targets this integration created are loaded back from Nautobot: those carrying the SSoT Synced from IPFabric Tag. A Route Target has no Location, no Device and no Namespace to bound a load by, so loading all of them would have the sync delete every Route Target another system owns the moment IP Fabric stopped reporting it.

Which Devices carry a VRF¶

Sync Device VRFs records the Devices each VRF is configured on, from the same table the VRFs come from. The assignment inherits the VRF's route distinguisher and name, which is what Nautobot does itself when one is created through the UI or API.

Only Devices the run covers are assigned. A Site Filter, Sync Tagged Only, or a stack member whose VRFs IP Fabric reports against its master can all leave a hostname outside the run, and those are skipped rather than assigned to a Device the sync never saw. That is also why this needs no special handling for a filtered run, unlike the VRFs themselves: an assignment belongs to a Device, and Devices are narrowed by the filter on both sides at once.

An assignment has neither a Status nor a Tag, so Safe Delete Mode has nothing to mark on one. A run with Safe Delete Mode on therefore leaves an assignment IP Fabric no longer reports in place, and reports it as a deletion it did not make; a run with Safe Delete Mode off removes it.

Which VRF an Interface is in¶

Sync Interface VRFs puts each Interface in the VRF IP Fabric reports for it. It needs Sync Device VRFs, because Nautobot refuses an Interface a VRF that is not assigned to the Interface's Device, and that assignment is what Sync Device VRFs makes.

That requirement is also why this is written last, after every Device, VRF and assignment. An Interface is created with its Device, which happens before any VRF exists, so the VRF it belongs to cannot be set at the same time.

Only Interfaces that are in a VRF are tracked, on either side. An Interface IP Fabric stops reporting a VRF for is taken out of the one it is in; nothing is deleted, so Safe Delete Mode does not apply: the Interface and the VRF both remain, and what goes is the reference between them.

What the sync will not do¶

A VRF name that the job's Namespace already holds twice is left alone entirely, and the Job log says so. Nautobot constrains a VRF to a unique route distinguisher within its Namespace but not to a unique name, so a Namespace can hold two VRFs called the same thing, and IP Fabric reports nothing that would say which of them its report describes.

With a Site Filter applied, VRFs and Route Targets are created and updated but never deleted. A filtered run sees only the VRFs configured on that site's devices, and the Route Targets those VRFs name, so everything else Nautobot holds would look absent from IP Fabric.

Cables¶

Cable synchronization is opt in via the Sync Cables job option, and is disabled by default because Nautobot allows only one Cable per Interface. Enabling it lets the sync replace connections that were recorded by hand.

A link has no stable identifier in either system: IP Fabric reports it once from each device's point of view, and Nautobot stores whichever end was cabled first as the A side. Both adapters therefore sort a link's two (device, interface) endpoints and use the lower one as the A side, so the same physical link resolves to one Cable either way.

Only links with both endpoints in scope are synced, since a Cable with one end out of scope would look absent from IP Fabric and be deleted on every run. A link is skipped when:

Either Interface was not loaded, because a Site filter excludes the far end, or because the far end is a stack member whose interfaces IP Fabric reports against the stack master.
Either Interface is virtual or wireless. Nautobot refuses to cable these types, and IP Fabric reports links over tunnel interfaces.
The entry does not name both a device and an interface on each side.
The Interface at either end is already recorded on a link kept earlier in the same run. IP Fabric describes a shared segment, such as a cloud subnet, as a link from every Interface in it to the segment, so one Interface can be reported on many links. Nautobot terminates at most one Cable on an Interface, so the lowest sorting of those links is kept and the rest are logged. The choice is by sort order rather than by whichever came first in the data, so that a re-sync keeps the same link instead of replacing the Cable the previous run recorded.

When IP Fabric reports a link that has moved, the Cable holding the Interface must be removed before the new one can be recorded. With Safe Delete Mode enabled, this does not happen; the conflict is logged as a warning and the new Cable is not created, leaving the change for an operator to review. With Safe Delete Mode disabled, the stale Cable is deleted and the new one is created.

Bulk Write Mode¶

A sync writes each object on its own: Nautobot validates it, records a change log entry, and fires the signals any app has registered. For a few hundred objects that cost is invisible. An estate of a few thousand devices carries a hundred thousand Interfaces and about as many IP Addresses, and there the per-object cost is most of the job's run time.

Bulk Write Mode writes them in batches instead. Measured over 200 Interfaces each carrying an IP address, a sync drops from 8.8 seconds to 0.5. It is disabled by default, because it gives up three things that are worth understanding before turning it on.

What it gives up¶

No change log entries. Nothing written in bulk appears in an object's Change Log tab, or in the global change log, for that run. The objects themselves are still tagged SSoT Synced from IPFabric and still carry the last_synced_from_sor custom field, so what the sync touched is still visible on the object; what is missing is the before-and-after record of the change.

No signals. Anything an app has hooked to object creation does not run for objects written in bulk. Webhooks do not fire.

No per-object validation. Nautobot's clean() is not called, so a check written in Python is not applied. Database constraints still are: a row that violates one is refused, and the batch it stopped is halved and retried until the rows at fault are isolated. Those are then written on their own with clean() applied, so each is named in the job log, and everything beside them is still written in batches rather than one at a time.

Batch size¶

A thousand rows are inserted per statement. ipfabric_bulk_write_batch_size changes that, and the value is a trade between two costs rather than a simple bigger-is-faster: a larger batch means fewer statements for the rows that are fine, and more rows to narrow through when one of them is refused. The narrowing is by halving, so the recovery cost grows with the logarithm of the batch rather than with the batch, which is what makes a thousand a reasonable default. Lower it where an estate is known to carry rows Nautobot will refuse, so that less is re-read to find them.

Two differences to expect¶

Devices created in bulk do not get the components their Device Type templates define. IP Fabric reports the interfaces a device actually has, and those are what the sync creates, so for this integration that is usually what you want, but if you rely on Device Type templates populating components, do not use this mode.

A duplicate Location name is not caught. Nautobot constrains a Location's name to be unique among its siblings, and the sites this integration creates have no parent; PostgreSQL treats those as distinct, so two sites of the same name would both be written where a per-object sync would have rejected the second. IP Fabric reports each site once, so this is a difference rather than an outcome to expect.

On Nautobot 3.2 the same applies to two Interfaces of one name on a Device. Nautobot 3.1 refuses that in the database, and 3.2 moved the check into Python, which a batched insert does not run. IP Fabric reports each interface once, so this too is a difference rather than an outcome to expect.

What it does not change¶

Cables are always written one at a time, whichever mode is selected. Creating a Cable also sets the cable, peer and path fields on both Interfaces it connects and builds Nautobot's cable paths, and all of that happens through signals a batched write does not fire. A Cable written in bulk would appear in the Cables list while showing no connection on either interface.

Route Targets are always written one at a time as well, for the opposite reason: a network has a handful of them, and the rows tying a VRF to its targets need the targets to exist already. The VRFs themselves are written in batches.

Deletions are unaffected. Safe Delete Mode governs those, and it is independent of this setting.

Objects the sync finds unchanged¶

Most of what a nightly sync sees is what it wrote the night before. Every object the sync touches records that it did, through the SSoT Synced from IPFabric tag and the last_synced_from_sor custom field, and for an object nothing else changed about, that stamp is the entire write.

It is applied with a single update of the custom field data rather than a full save. What that skips is Nautobot's validation, the signals, and a change log entry for the stamp itself. So an object IP Fabric still reports exactly as Nautobot holds it no longer gains a change log entry on every run; its last_synced_from_sor date still moves, and the Change Log tab now shows the runs that changed something rather than one entry per run. An object the sync does change is written in full, with validation and a change log entry as before.

This applies in either write mode. Bulk Write Mode is about objects the sync creates; this is about the ones it finds already correct, which on a settled estate is nearly all of them.

Safe Delete Mode¶

By design, a Nautobot SSoT app using DiffSync will Create, Update or Delete when synchronizing two data sources. However, this may not always be what we want to happen with our Source of Truth (Nautobot). A job configuration option is available and enabled by default to prevent deleting objects from the database and instead, update the Status of said object alongside assigning a default Tag, SSoT Safe Delete. For example, if an additional snapshot is created from IPFabric, synchronized with Nautobot and, it just so happens that a device was unreachable, down for maintenance, etc., This doesn't always mean that our Source of Truth should delete this object, but we may need to bring attention to this matter. We let you decide what should happen. One thing to note is that some of the objects will auto recover from the changed status if a new job shows the object is present. However, currently, IP addresses and Interfaces will not auto-update to remove the SSoT Safe Delete Tag. The user is responsible for reviewing and updating accordingly. Safe delete tagging of objects works in an idempotent way. If an object has been tagged already, the custom field defining the last update will not be updated with a new sync date from IPFabric. So, if you re-run your sync job days apart and, you'd expect the date to change, but the object has been flagged as safe to delete; you will not see an updated date on the object custom field unless the status changed, in which case the tag (depending on the object) would be removed followed by updating the last date of sync.

The default status change of an object were to be deleted by SSoT DiffSync operations, will be specified below. These are the default transitions states, unless otherwise specified in the configuration options of the integration by a user.

Device -> Offline (Auto deletes tag upon recovery)
IPAddresses -> Deprecated (Does not auto-delete tag upon recovery)
VLAN -> Deprecated (Auto deletes tag upon recovery)
Site -> Decommissioning (Auto deletes tag upon recovery)
Interfaces -> Tagged with SSoT Safe Delete (Does not auto-delete Tag upon recovery)
Cable -> Decommissioning (Auto deletes tag upon recovery)
Prefix -> Deprecated (Auto deletes tag upon recovery)

If you would like to change the default status change value, ensure you provide a valid status name available for the referenced object. Not all objects share the same Status.

An example object that's been modified by SSoT App and tagged as SSoT Safe Delete and SSoT Synced from IPFabric. Notice the Status and child object, IPAddress has also changed to Deprecated and, it's status changed and tagged as well.

During job execution, a warning will be provided to show the status change of an object.

If an object has already been updated with the tag, a warning message will be displayed and the object will not be modified (including sync date).

ChatOps¶

As part of the SSoT synchronization capabilities with IP Fabric, this integration extends the Nautobot ChatOps app by providing users with the ability to begin the sync job from a ChatOps command (Slack).

Screenshots¶

Main SSoT IPFabric Dashboard:

Sync Details: