Netbox Sync All Task

task api name: sync_all

The sync_all task synchronizes device data from live devices into NetBox in a fixed sequence:

1. inventory — calls sync_device_inventory
2. vlans — calls sync_vlans
3. prefixes — calls sync_device_prefixes
4. vrfs — calls sync_vrfs
5. interfaces — calls sync_device_interfaces
6. mac_addresses — calls sync_mac_addresses
7. ip_addresses — calls sync_device_ip
8. bgp_peerings — calls sync_bgp_peerings

How It Works

The sync_all task orchestrates eight subordinate sync tasks in sequence. Each task collects live device data, compares it against NetBox state, and applies reconciliation operations. When dry_run=True, all tasks preview changes without writing. When with_approval=True, each stage waits for user confirmation before applying changes.

Execution Modes

Dry-run mode (dry_run=True) previews all changes without writing to NetBox.

With Approval — Pass with_approval=True to use the interactive NFCLI workflow. Each sync stage displays its preview, and waits for review before applying that stage. Declining a stage stops sync_all at that point, returns the declined dry-run result, and skips later stages. Any earlier approved stages remain applied.

Note

When both dry-run and with_approval are True, dry-run logic ignored.

Live-run mode (dry_run=False, default) applies all changes to NetBox.

Sync Task Arguments

Use sync_kwargs to pass arguments to individual sync tasks. It accepts an inline dictionary, an nf:// URL to a YAML file containing that dictionary, or None. The dictionary keys are task API names and each value is passed to that task as keyword arguments:

sync_device_inventory:
  create_module_types: true
  create_module_bays: true
  inventory_map: nf://netbox/inventory_maps/iosxr.yaml
  message: sync all device data

sync_vlans:
  filter_by_vlan_ids:
    - 100-299

sync_device_prefixes:
  ignore_vrf: true
  ignore_site: true

sync_vrfs:
  device_custom_field: devices

sync_device_interfaces:
  process_deletions: true
  interface_map: nf://netbox/interface_map.yaml
  vlan_map: nf://netbox/vlan_map.yaml

sync_mac_addresses:
  filter_by_name: Ethernet*

sync_device_ip:
  ignore_vrf: false
  ignore_ranges:
    - 192.0.2.0/24

sync_bgp_peerings:
  process_deletions: true
  status: active
  message: sync all device data

The supported keys are sync_device_inventory, sync_vlans, sync_device_prefixes, sync_vrfs, sync_device_interfaces, sync_mac_addresses, sync_device_ip, and sync_bgp_peerings. Refer to each task's documentation for its accepted arguments. Missing keys run with the subordinate task's defaults. Set a key to false to skip that task and continue with the next stage:

sync_device_interfaces: false

Skipped tasks are omitted from each device's result categories.

Keep instance, timeout, devices, branch, dry_run, and with_approval at the sync_all level rather than repeating them inside a task dictionary.

Output

The result structure aggregates the outcomes of all eight subordinate sync tasks. When dry_run=True the same structure is returned but no changes are written to NetBox. VLAN, prefix, and VRF results describe shared NetBox objects, so the same shared result is included under each selected device.

{
    # per-device results — one entry per resolved device
    "result": {
        "ceos-spine-1": {
            "inventory": {
                "created": [ ... ],
                "updated": [ ... ],
                "deleted": [ ... ],
                "in_sync": [ ... ],
            },
            "vlans": {
                "site:DC1": {
                    "create": [ ... ],
                    "update": { ... },
                    "delete": [],
                    "in_sync": [ ... ],
                },
            },
            "prefixes": {
                "created": [ ... ],
                "updated": [ ... ],
                "in_sync": [ ... ],
            },
            "vrfs": {
                "global": {
                    "create": [ ... ],
                    "update": { ... },
                    "delete": [],
                    "in_sync": [ ... ],
                },
            },
            "interfaces": {
                "create":  { ... },
                "update":  { ... },
                "delete":  { ... },
                "in_sync": [ ... ],
            },
            "mac_addresses": {
                "created": [ ... ],
                "updated": [ ... ],
                "in_sync": [ ... ],
            },
            "ip_addresses": {
                "created": [ ... ],
                "updated": [ ... ],
                "in_sync": [ ... ],
            },
            "bgp_peerings": {
                "create":  { ... },
                "update":  { ... },
                "delete":  { ... },
                "in_sync": [ ... ],
            },
        },
        ...
    },
    "diff": {},
}

When dry_run=True the same structure is returned but no changes are written to NetBox.

Examples

CLIPython

Preview all eight sync categories:

nf#netbox sync all devices ceos-spine-1 ceos-spine-2 dry-run

Preview, prompt for review, and apply the changes:

nf#netbox sync all devices ceos-spine-1 ceos-spine-2 with-approval

Load per-task arguments from the File Sharing service:

nf#netbox sync all devices iosxr1 sync-kwargs nf://netbox/sync_all_kwargs.yaml dry-run

result = client.run_job(
    "netbox",
    "sync_all",
    workers="any",
    kwargs={
        "devices": ["iosxr1"],
        "dry_run": True,
        "sync_kwargs": {
            "sync_device_inventory": {
                "create_module_bays": True,
                "create_module_types": True,
                "inventory_map": "nf://netbox/inventory_maps/iosxr.yaml",
            },
            "sync_vlans": {"filter_by_vlan_ids": ["100-299"]},
            "sync_device_prefixes": {"ignore_vrf": True},
            "sync_vrfs": {"device_custom_field": "devices"},
            "sync_device_interfaces": {
                "interface_map": "nf://netbox/interface_map.yaml",
                "vlan_map": "nf://netbox/vlan_map.yaml",
            },
            "sync_device_ip": {"ignore_vrf": False},
            "sync_bgp_peerings": False,
        },
    },
)

The same configuration can be stored in YAML and referenced with "sync_kwargs": "nf://netbox/sync_all_kwargs.yaml".

NORFAB Netbox Sync All Command Shell Reference

NorFab shell supports these command options for Netbox sync_all task:

nf# man tree netbox.sync.all
root
└── netbox:    Netbox service
    └── sync:    Sync Netbox data
        └── all:    Sync inventory, VLANs, prefixes, VRFs, interfaces, MAC addresses, IP addresses and BGP peerings
            ├── timeout:    Job timeout
            ├── workers:    Filter worker to target, default 'any'
            ├── verbose-result:    Control output details, default 'False'
            ├── progress:    Display progress events, default 'True'
            ├── instance:    Netbox instance name to target
            ├── branch:    Branching plugin branch name to use
            ├── devices:    List of NetBox devices to sync all data for
            ├── dry-run:    Return diff without writing to NetBox, default 'False'
            ├── with-approval:    Preview each sync stage and ask for review before writing to NetBox
            ├── sync-kwargs:    Per-task sync arguments or nf:// YAML file
            ├── FO:    Filter hosts using Filter Object
            ├── FB:    Filter hosts by name using Glob Patterns
            ├── FH:    Filter hosts by hostname
            ├── FC:    Filter hosts containment of pattern in name
            ├── FR:    Filter hosts by name using Regular Expressions
            ├── FG:    Filter hosts by group
            ├── FP:    Filter hosts by hostname using IP Prefix
            ├── FL:    Filter hosts by names list
            ├── FX:    Filter hosts excluding them by name
            └── FN:    Negate the match
nf#

Python API Reference

Synchronize all device data from live devices into NetBox in sequence: inventory → VLANs → prefixes → VRFs → interfaces → MAC addresses → IP addresses → BGP peerings.

Pass dry_run=True to preview changes without writing to NetBox. Pass with_approval=True to have each sync stage run a dry-run preview, ask the interactive client for review, and only then apply that stage.

Result.result is keyed by device name, then by category::

{
    "<device>": {
        "inventory":     {"created": [...], "updated": [...], "deleted": [...], "in_sync": [...]},
        "vlans":         {"<scope>": {"created": [...], "updated": [...], "deleted": [...], "in_sync": [...]}},
        "prefixes":      {"created": [...], "updated": [...], "in_sync": [...]},
        "vrfs":          {"global": {"created": [...], "updated": [...], "deleted": [...], "in_sync": [...]}},
        "interfaces":    {"created": [...], "updated": {...}, "deleted": [...], "in_sync": [...]},
        "mac_addresses": {"created": [...], "updated": [...], "in_sync": [...]},
        "ip_addresses":  {"created": [...], "updated": [...], "in_sync": [...]},
        "bgp_peerings":  {"create": [...],  "update": {...},  "delete": [...],  "in_sync": [...]},
    }
}

Parameters:

Name	Type	Description	Default
job	Job	NorFab Job object.	required
instance	str	NetBox instance name.	None
timeout	int	Timeout in seconds for Nornir jobs. Defaults to 60.	600
devices	list	List of device names to sync.	None
branch	str	NetBox branching plugin branch name.	None
dry_run	bool	If True, preview changes without writing to NetBox. Defaults to False.	False
with_approval	bool	Preview and ask for review before applying each sync stage. Defaults to False.	False
sync_kwargs	Union[None, dict, str]	Per-task arguments keyed by sync task name, or an nf:// YAML file containing that dictionary. Set a task key to False to skip that task.	None
**kwargs	Any	Nornir host filter arguments (e.g. FL, FC, FB).	{}

Returns:

Name	Type	Description
Result	Result	Per-device sync results keyed by device name and category.

Source code in norfab\workers\netbox_worker\devices_tasks.py

@Task(
    fastapi={"methods": ["POST"], "schema": NetboxFastApiArgs.model_json_schema()},
    input=SyncAllInput,
    output=SyncAllResult,
    mcp={
        "annotations": {
            "title": "Sync All Device Data",
            "readOnlyHint": False,
            "destructiveHint": True,
            "idempotentHint": True,
            "openWorldHint": True,
        }
    },
)
def sync_all(
    self,
    job: Job,
    instance: Union[None, str] = None,
    timeout: int = 600,
    devices: Union[None, list] = None,
    branch: str = None,
    dry_run: bool = False,
    with_approval: bool = False,
    sync_kwargs: Union[None, dict, str] = None,
    **kwargs: Any,
) -> Result:
    """
    Synchronize all device data from live devices into NetBox in sequence:
    inventory → VLANs → prefixes → VRFs → interfaces → MAC addresses →
    IP addresses → BGP peerings.

    Pass ``dry_run=True`` to preview changes without writing to NetBox.
    Pass ``with_approval=True`` to have each sync stage run a dry-run preview,
    ask the interactive client for review, and only then apply that stage.

    ``Result.result`` is keyed by device name, then by category::

        {
            "<device>": {
                "inventory":     {"created": [...], "updated": [...], "deleted": [...], "in_sync": [...]},
                "vlans":         {"<scope>": {"created": [...], "updated": [...], "deleted": [...], "in_sync": [...]}},
                "prefixes":      {"created": [...], "updated": [...], "in_sync": [...]},
                "vrfs":          {"global": {"created": [...], "updated": [...], "deleted": [...], "in_sync": [...]}},
                "interfaces":    {"created": [...], "updated": {...}, "deleted": [...], "in_sync": [...]},
                "mac_addresses": {"created": [...], "updated": [...], "in_sync": [...]},
                "ip_addresses":  {"created": [...], "updated": [...], "in_sync": [...]},
                "bgp_peerings":  {"create": [...],  "update": {...},  "delete": [...],  "in_sync": [...]},
            }
        }

    Args:
        job: NorFab Job object.
        instance (str, optional): NetBox instance name.
        timeout (int): Timeout in seconds for Nornir jobs. Defaults to 60.
        devices (list, optional): List of device names to sync.
        branch (str, optional): NetBox branching plugin branch name.
        dry_run (bool): If True, preview changes without writing to NetBox. Defaults to False.
        with_approval (bool): Preview and ask for review before applying
            each sync stage. Defaults to False.
        sync_kwargs: Per-task arguments keyed by sync task name, or an
            ``nf://`` YAML file containing that dictionary. Set a task key
            to ``False`` to skip that task.
        **kwargs: Nornir host filter arguments (e.g. ``FL``, ``FC``, ``FB``).

    Returns:
        Result: Per-device sync results keyed by device name and category.
    """
    devices = devices or []
    instance = instance or self.default_instance
    if isinstance(sync_kwargs, str):
        sync_kwargs = yaml.safe_load(
            self.fetch_file(sync_kwargs, raise_on_fail=True)
        )
    sync_kwargs = sync_kwargs or {}
    ret = Result(
        task=f"{self.name}:sync_all",
        result={},
        resources=[instance],
        diff={},
        dry_run=dry_run,
    )

    # resolve devices from Nornir filters
    if kwargs:
        nornir_hosts = self.get_nornir_hosts(kwargs, timeout)
        for host in nornir_hosts:
            if host not in devices:
                devices.append(host)

    if not devices:
        ret.errors.append("no devices specified")
        ret.failed = True
        return ret

    log.info(
        f"{self.name} - Sync all for {len(devices)} device(s) in '{instance}', dry_run={dry_run}"
    )
    job.event(f"syncing all data for {len(devices)} device(s), dry_run={dry_run}")

    # initialize per-device result structure
    for device in devices:
        ret.result[device] = {}

    # --- sync device inventory ---
    if sync_kwargs.get("sync_device_inventory") is False:
        job.event("skipping device inventory sync")
    else:
        job.event("syncing device inventory")
        inventory_result = self.sync_device_inventory(
            job=job,
            instance=instance,
            dry_run=dry_run,
            timeout=timeout,
            devices=list(devices),
            branch=branch,
            with_approval=with_approval,
            **(sync_kwargs.get("sync_device_inventory") or {}),
        )
        if inventory_result.errors:
            job.event("inventory sync completed with errors", severity="WARNING")
            ret.errors.extend(inventory_result.errors)
        for device, data in inventory_result.result.items():
            ret.result.setdefault(device, {})["inventory"] = data
        if inventory_result.status == "skipped" and inventory_result.dry_run:
            ret.status = "skipped"
            ret.dry_run = True
            job.event(
                "sync all stopped because device inventory review was declined"
            )
            return ret

    # --- sync VLANs ---
    if sync_kwargs.get("sync_vlans") is False:
        job.event("skipping VLAN sync")
    else:
        job.event("syncing VLANs")
        vlan_result = self.sync_vlans(
            job=job,
            instance=instance,
            dry_run=dry_run,
            timeout=timeout,
            devices=list(devices),
            branch=branch,
            with_approval=with_approval,
            **(sync_kwargs.get("sync_vlans") or {}),
        )
        if vlan_result.errors:
            job.event("VLAN sync completed with errors", severity="WARNING")
            ret.errors.extend(vlan_result.errors)
        for device in devices:
            ret.result[device]["vlans"] = vlan_result.result
        if vlan_result.status == "skipped" and vlan_result.dry_run:
            ret.status = "skipped"
            ret.dry_run = True
            job.event("sync all stopped because VLAN review was declined")
            return ret

    # --- sync prefixes ---
    if sync_kwargs.get("sync_device_prefixes") is False:
        job.event("skipping prefix sync")
    else:
        job.event("syncing prefixes")
        prefix_result = self.sync_device_prefixes(
            job=job,
            instance=instance,
            dry_run=dry_run,
            timeout=timeout,
            devices=list(devices),
            branch=branch,
            with_approval=with_approval,
            **(sync_kwargs.get("sync_device_prefixes") or {}),
        )
        if prefix_result.errors:
            job.event("prefix sync completed with errors", severity="WARNING")
            ret.errors.extend(prefix_result.errors)
        for device in devices:
            ret.result[device]["prefixes"] = prefix_result.result
        if prefix_result.status == "skipped" and prefix_result.dry_run:
            ret.status = "skipped"
            ret.dry_run = True
            job.event("sync all stopped because prefix review was declined")
            return ret

    # --- sync VRFs ---
    if sync_kwargs.get("sync_vrfs") is False:
        job.event("skipping VRF sync")
    else:
        job.event("syncing VRFs")
        vrf_result = self.sync_vrfs(
            job=job,
            instance=instance,
            dry_run=dry_run,
            timeout=timeout,
            devices=list(devices),
            branch=branch,
            with_approval=with_approval,
            **(sync_kwargs.get("sync_vrfs") or {}),
        )
        if vrf_result.errors:
            job.event("VRF sync completed with errors", severity="WARNING")
            ret.errors.extend(vrf_result.errors)
        for device in devices:
            ret.result[device]["vrfs"] = vrf_result.result
        if vrf_result.status == "skipped" and vrf_result.dry_run:
            ret.status = "skipped"
            ret.dry_run = True
            job.event("sync all stopped because VRF review was declined")
            return ret

    # --- sync interfaces ---
    if sync_kwargs.get("sync_device_interfaces") is False:
        job.event("skipping interface sync")
    else:
        job.event("syncing interfaces")
        intf_result = self.sync_device_interfaces(
            job=job,
            instance=instance,
            dry_run=dry_run,
            timeout=timeout,
            devices=list(devices),
            branch=branch,
            with_approval=with_approval,
            **(sync_kwargs.get("sync_device_interfaces") or {}),
        )
        if intf_result.errors:
            job.event("interface sync completed with errors", severity="WARNING")
            ret.errors.extend(intf_result.errors)
        for device, data in intf_result.result.items():
            ret.result.setdefault(device, {})["interfaces"] = data
        if intf_result.status == "skipped" and intf_result.dry_run:
            ret.status = "skipped"
            ret.dry_run = True
            job.event("sync all stopped because interface review was declined")
            return ret

    # --- sync MAC addresses ---
    if sync_kwargs.get("sync_mac_addresses") is False:
        job.event("skipping MAC address sync")
    else:
        job.event("syncing MAC addresses")
        mac_result = self.sync_mac_addresses(
            job=job,
            instance=instance,
            dry_run=dry_run,
            timeout=timeout,
            devices=list(devices),
            branch=branch,
            with_approval=with_approval,
            **(sync_kwargs.get("sync_mac_addresses") or {}),
        )
        if mac_result.errors:
            job.event("MAC address sync completed with errors", severity="WARNING")
            ret.errors.extend(mac_result.errors)
        for device, data in mac_result.result.items():
            ret.result.setdefault(device, {})["mac_addresses"] = data
        if mac_result.status == "skipped" and mac_result.dry_run:
            ret.status = "skipped"
            ret.dry_run = True
            job.event("sync all stopped because MAC address review was declined")
            return ret

    # --- sync IP addresses ---
    if sync_kwargs.get("sync_device_ip") is False:
        job.event("skipping IP address sync")
    else:
        job.event("syncing IP addresses")
        ip_result = self.sync_device_ip(
            job=job,
            instance=instance,
            dry_run=dry_run,
            timeout=timeout,
            devices=list(devices),
            branch=branch,
            with_approval=with_approval,
            **(sync_kwargs.get("sync_device_ip") or {}),
        )
        if ip_result.errors:
            job.event("IP address sync completed with errors", severity="WARNING")
            ret.errors.extend(ip_result.errors)
        for device, data in ip_result.result.items():
            ret.result.setdefault(device, {})["ip_addresses"] = data
        if ip_result.status == "skipped" and ip_result.dry_run:
            ret.status = "skipped"
            ret.dry_run = True
            job.event("sync all stopped because IP address review was declined")
            return ret

    # --- sync BGP peerings ---
    if sync_kwargs.get("sync_bgp_peerings") is False:
        job.event("skipping BGP peering sync")
    else:
        job.event("syncing BGP peerings")
        bgp_result = self.sync_bgp_peerings(
            job=job,
            instance=instance,
            dry_run=dry_run,
            timeout=timeout,
            devices=list(devices),
            branch=branch,
            with_approval=with_approval,
            **(sync_kwargs.get("sync_bgp_peerings") or {}),
        )
        if bgp_result.errors:
            job.event("BGP peerings sync completed with errors", severity="WARNING")
            ret.errors.extend(bgp_result.errors)
        for device, data in bgp_result.result.items():
            ret.result.setdefault(device, {})["bgp_peerings"] = data
        if bgp_result.status == "skipped" and bgp_result.dry_run:
            ret.status = "skipped"
            ret.dry_run = True
            job.event("sync all stopped because BGP peerings review was declined")
            return ret

    log.info(f"{self.name} - Sync all complete for {len(ret.result)} device(s)")
    job.event(f"sync all complete for {len(ret.result)} device(s)")
    return ret