Sync with NetBox

SZ-MCP can keep NetBox and its own inventory in step, hourly by default. In (on by default), NetBox’s sites, locations and racks become inventory locations. An AP or switch NetBox knows by serial number is placed where NetBox says. Out (off by default), the controller’s APs and switches become NetBox devices tagged sz-mcp, with a switch’s ports as interfaces. Set it up under Configure › Integrations (admins only). The rules every integration follows apply here too.

How do I set it up?

1. In NetBox, create an API token. A read-only token is enough for In. Out needs write permission.
2. In SZ-MCP, open Configure › Integrations, click Add an integration, and choose NetBox (inventory).
3. Enter a Name, the NetBox URL (for example https://netbox.example.com) and the API token.
4. Tick In, Out or both, set Sync every (minutes), and click Save.
5. Click Sync now to run the first sync.

Tokens that start with nbt_ (NetBox 4.5 v2 tokens) are sent as Bearer. Others are sent as Token.

What do the fields do?

Field	Default	Effect
In: sites, locations and racks, and where NetBox puts each AP and switch	On	Pull (below)
Out: APs and switches as NetBox devices, switch ports as interfaces	Off	Push (below)
Site for new devices not placed in a NetBox location here	none	A NetBox site slug. Without one, a new device waits until it is placed
Adopt devices NetBox already has by serial number	Off	Take over existing devices (below)
Sync every (minutes)	60	1–60

At least one direction is required: Save stays disabled until In, Out or both is ticked. The interval is counted from the last attempt, not the last success, so a NetBox that is down isn’t asked every minute.

What does In do?

• Locations. Each site becomes location:<site>. Nested locations and racks go under it (location:<site>/<location…>/<rack>), with ids from NetBox slugs, so a rename keeps the id. A location you made by hand with the same id is adopted. Locations NetBox no longer has are removed, unless you hung your own locations under them.
• Placement. An AP or switch that NetBox knows by serial is placed at its rack, or else its location, or else its site. It gets the tags netbox.role and netbox.tenant.
• Your placements win. A device you placed yourself stays where you put it, even inside a NetBox location. Placing a device by hand takes it out of the sync’s control.

What does Out do?

• Devices. APs and switches with a serial number become NetBox devices tagged sz-mcp: manufacturer Ruckus, role Wireless AP or Access switch, and a device type per model. Anything missing is created. Devices without a serial are skipped.
• Matching. An existing NetBox device is found by serial number first, so nothing is duplicated. A device that exists without the sz-mcp tag belongs to someone else and is left alone, unless Adopt is on. Adopting adds the tag.
• Keeping in step. For devices tagged sz-mcp, the name, status (active, or offline when the controller says so) and description follow the controller.
• NetBox owns placement. A new device goes where the inventory places it in a NetBox location, or else to the default site. An existing device is never moved from SZ-MCP.
• Interfaces. A managed switch’s ports become interfaces (1/1/1 …), typed from the port’s speed. They are created or updated, never deleted.

What limits apply?

Limit per run	What happens
200 device creates	The rest are created on later runs
2,000 interface creates	The rest on later runs
1,000 updates	The rest on later runs
50,000 objects in one NetBox list	The run fails with NetBox <path>: more than 50000 objects

Each run is a reconciliation, so whatever a cap or an error stopped is still a difference on the next one.

What errors can I get?

Errors show on the integration and under Recent deliveries as netbox:<name>:

Message	What to check
NetBox … HTTP 403 … (check the token and its write permission)	The token, or write permission for Out
NetBox … (a redirect: check the URL, including https)	The URL
NetBox …: not a JSON reply (is this the NetBox URL?)	The URL points at something other than NetBox

Next steps

Inventory Locations, placements and tags the sync writes to.

ServiceNow incidents Incidents for unhandled HARD problems.

Nagios and Icinga The rules every integration follows.