Netbox Sync All Task

task api name: sync_all

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

1. interfaces — calls sync_device_interfaces
2. mac_addresses — calls sync_mac_addresses
3. ip_addresses — calls sync_device_ip
4. bgp_peerings — calls sync_bgp_peerings

Each sub-task can be individually enabled or disabled. Pass dry_run=True to preview the changes that would be made without writing anything to NetBox.

Result Format

{
    # per-device results — one entry per resolved device
    "result": {
        "ceos-spine-1": {
            "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.

Sample Usage

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 all device data: 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'
            ├── process-deletions:    Process deletions for interfaces and BGP peerings, default 'False'
            ├── 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: interfaces → MAC addresses → IP addresses → BGP peerings.

Pass dry_run=True to preview changes without writing to NetBox.

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

{
    "<device>": {
        "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.	60
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
process_deletions	bool	Process deletions for interfaces and BGP peerings. Defaults to False.	False
interfaces_filter_by_name	str	Glob pattern to filter interfaces by name.	None
interfaces_filter_by_description	str	Glob pattern to filter interfaces by description.	None
interfaces_update_type	bool	Update existing NetBox interface types.	False
interfaces_vlan_group	(str, int)	VLAN group name, slug, or ID for interface VLAN resolution.	None
mac_filter_by_name	str	Glob pattern to filter MAC sync interfaces by name.	None
mac_filter_by_description	str	Glob pattern to filter MAC sync interfaces by description.	None
mac_filter_by_mac	str	Glob pattern to filter MAC addresses.	None
ip_anycast_ranges	list	IP prefixes to classify as anycast.	None
ip_ignore_ranges	list	IP prefixes to exclude from IP sync.	None
ip_create_prefixes	bool	Create missing prefixes during IP sync.	True
ip_filter_by_name	str	Glob pattern to filter IP sync interfaces by name.	None
ip_filter_by_description	str	Glob pattern to filter IP sync interfaces by description.	None
ip_filter_by_prefix	str	IP prefix to restrict synced IP addresses.	None
ip_filter_by_ip	str	Glob pattern to restrict synced IP addresses.	None
bgp_status	str	Status to set on created/updated BGP sessions.	'active'
bgp_rir	str	RIR name to use when creating new ASNs.	None
bgp_message	str	Changelog message for BGP operations.	None
bgp_name_template	str	Template string for BGP session names.	'{device}_{name}'
bgp_filter_by_remote_as	list	Only sync sessions matching remote AS numbers.	None
bgp_filter_by_peer_group	list	Only sync sessions matching peer groups.	None
bgp_filter_by_description	str	Only sync sessions matching description glob.	None
bgp_ignore_peer_ranges	list	Prefixes to ignore BGP peers.	None
bgp_vrf_custom_field	str	BGP session custom field name used to store VRF reference.	'vrf'
**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": ["PATCH"], "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 = 60,
    devices: Union[None, list] = None,
    branch: str = None,
    dry_run: bool = False,
    process_deletions: bool = False,
    interfaces_filter_by_name: Union[None, str] = None,
    interfaces_filter_by_description: Union[None, str] = None,
    interfaces_update_type: Union[None, bool] = False,
    interfaces_vlan_group: Union[None, str, int] = None,
    mac_filter_by_name: Union[None, str] = None,
    mac_filter_by_description: Union[None, str] = None,
    mac_filter_by_mac: Union[None, str] = None,
    ip_anycast_ranges: Union[None, list] = None,
    ip_ignore_ranges: Union[None, list] = None,
    ip_create_prefixes: bool = True,
    ip_filter_by_name: Union[None, str] = None,
    ip_filter_by_description: Union[None, str] = None,
    ip_filter_by_prefix: Union[None, str] = None,
    ip_filter_by_ip: Union[None, str] = None,
    bgp_status: str = "active",
    bgp_rir: Union[None, str] = None,
    bgp_message: Union[None, str] = None,
    bgp_name_template: str = "{device}_{name}",
    bgp_filter_by_remote_as: Union[None, list] = None,
    bgp_filter_by_peer_group: Union[None, list] = None,
    bgp_filter_by_description: Union[None, str] = None,
    bgp_ignore_peer_ranges: Union[None, list] = None,
    bgp_vrf_custom_field: str = "vrf",
    **kwargs: Any,
) -> Result:
    """
    Synchronize all device data from live devices into NetBox in sequence:
    interfaces → MAC addresses → IP addresses → BGP peerings.

    Pass ``dry_run=True`` to preview changes without writing to NetBox.

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

        {
            "<device>": {
                "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.
        process_deletions (bool): Process deletions for interfaces and BGP peerings. Defaults to False.
        interfaces_filter_by_name (str, optional): Glob pattern to filter interfaces by name.
        interfaces_filter_by_description (str, optional): Glob pattern to filter interfaces by description.
        interfaces_update_type (bool, optional): Update existing NetBox interface types.
        interfaces_vlan_group (str, int, optional): VLAN group name, slug, or ID for interface VLAN resolution.
        mac_filter_by_name (str, optional): Glob pattern to filter MAC sync interfaces by name.
        mac_filter_by_description (str, optional): Glob pattern to filter MAC sync interfaces by description.
        mac_filter_by_mac (str, optional): Glob pattern to filter MAC addresses.
        ip_anycast_ranges (list, optional): IP prefixes to classify as anycast.
        ip_ignore_ranges (list, optional): IP prefixes to exclude from IP sync.
        ip_create_prefixes (bool): Create missing prefixes during IP sync.
        ip_filter_by_name (str, optional): Glob pattern to filter IP sync interfaces by name.
        ip_filter_by_description (str, optional): Glob pattern to filter IP sync interfaces by description.
        ip_filter_by_prefix (str, optional): IP prefix to restrict synced IP addresses.
        ip_filter_by_ip (str, optional): Glob pattern to restrict synced IP addresses.
        bgp_status (str): Status to set on created/updated BGP sessions.
        bgp_rir (str, optional): RIR name to use when creating new ASNs.
        bgp_message (str, optional): Changelog message for BGP operations.
        bgp_name_template (str): Template string for BGP session names.
        bgp_filter_by_remote_as (list, optional): Only sync sessions matching remote AS numbers.
        bgp_filter_by_peer_group (list, optional): Only sync sessions matching peer groups.
        bgp_filter_by_description (str, optional): Only sync sessions matching description glob.
        bgp_ignore_peer_ranges (list, optional): Prefixes to ignore BGP peers.
        bgp_vrf_custom_field (str): BGP session custom field name used to store VRF reference.
        **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
    ret = Result(
        task=f"{self.name}:sync_all",
        result={},
        resources=[instance],
        diff={},
    )

    # 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 interfaces ---
    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,
        process_deletions=process_deletions,
        filter_by_name=interfaces_filter_by_name,
        filter_by_description=interfaces_filter_by_description,
        update_type=interfaces_update_type,
        vlan_group=interfaces_vlan_group,
    )
    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

    # --- sync MAC addresses ---
    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,
        filter_by_name=mac_filter_by_name,
        filter_by_description=mac_filter_by_description,
        filter_by_mac=mac_filter_by_mac,
    )
    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

    # --- sync IP addresses ---
    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,
        anycast_ranges=ip_anycast_ranges,
        ignore_ranges=ip_ignore_ranges,
        create_prefixes=ip_create_prefixes,
        filter_by_name=ip_filter_by_name,
        filter_by_description=ip_filter_by_description,
        filter_by_prefix=ip_filter_by_prefix,
        filter_by_ip=ip_filter_by_ip,
    )
    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

    # --- sync BGP peerings ---
    job.event("SYNCING BGP peerings")
    bgp_result = self.sync_bgp_peerings(
        job=job,
        instance=instance,
        status=bgp_status,
        dry_run=dry_run,
        timeout=timeout,
        devices=list(devices),
        branch=branch,
        process_deletions=process_deletions,
        rir=bgp_rir,
        message=bgp_message,
        name_template=bgp_name_template,
        filter_by_remote_as=bgp_filter_by_remote_as,
        filter_by_peer_group=bgp_filter_by_peer_group,
        filter_by_description=bgp_filter_by_description,
        ignore_peer_ranges=bgp_ignore_peer_ranges,
        vrf_custom_field=bgp_vrf_custom_field,
    )
    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

    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