NetBox
Connect NetLock RMM to NetBox: devices and virtual machines you keep in NetBox get NetLock fields, NetBox stays the source of truth.
NetBox
NetBox describes how your network should look, so NetLock does not change that description. It only adds its own fields to objects that already exist. Name, serial number, site, role, status and every other field stay as they are, and nothing is ever deleted.
Requirements
- NetBox 4 or later. The test of the connection reads the version from
/api/status/. - An API token of a user who may read tenants, custom fields, sites, device roles and device types, and read and change devices and virtual machines. Use a v2 token and enter it in full, starting with
nbt_. A v1 token still works, but NetBox deprecated it in 4.6 and removes it in 5.0, and the test says so. - The address of the instance, without
/api. - The custom fields below, or the right to add custom fields if NetLock should create them.
Custom fields
| Name | Type | Content |
|---|---|---|
netlock_device_id | Text | The id of the device in NetLock. Required |
netlock_last_seen | Text | The day of the last contact |
netlock_os | Text | Operating system |
netlock_agent_version | Text | Version of the agent |
netlock_url | Text or URL | Where the device opens in the console, if a public console address is set |
Assign them to the object types dcim | device and virtualization | virtual machine. A field that exists only on one of them is written only there. Without netlock_device_id on a type, that type is not included.
With Create missing NetLock fields on, the next run creates the fields that do not exist at all, with the group NetLock. A field that already exists is never changed, even if its type is wrong or it is assigned to only one object type; the test of the connection reports both cases. netlock_device_id stays editable, the other fields can only be changed through the API.
Setup
- In
Settings → Integrations, open the NetBox tile and chooseConnect. - Enter the
Instance addressand theAPI token.Allow unencrypted httpis for an instance on an internal network only. - The test of the connection shows the version of NetBox and lists every field that is missing or has the wrong type. It writes nothing.
- Under options, switch on
Sync devices as assets. It is off by default: without it the connection does nothing. - Map each tenant to a tenant of NetBox, or import them. Tenants without a mapping are not included.
- Activate the connection.
What goes to NetBox
The five fields above, and only those, one object at a time. A value NetLock does not know is left out. An object that already holds the same values is not written, so it does not appear in the change log of NetBox.
Every hour NetLock checks the devices that changed since the last run. The last contact is stored by day, so it changes an object at most once a day. Synchronize now starts a run immediately.
How a device finds its object
By exact match, within the mapped tenant, among devices and virtual machines. The first step that finds an object wins:
- The object of the stored link.
- The object whose
netlock_device_idis the id of the device. - The object with the same serial number. Placeholders such as
To Be Filled By O.E.M.are ignored. - The object with the same name.
Steps 3 and 4 ignore case. A prefix does not match, and a name with a domain does not match one without. If the name matches but both sides have a real serial number and the numbers differ, they are two machines and the device is skipped as ambiguous.
A device is skipped, without counting as a failure, when:
| Reason in the history | Meaning |
|---|---|
not_in_source | NetBox has no such object |
ambiguous | Several objects fit, or the name fits and the serial numbers differ. Make the serial number or name unique, or set netlock_device_id on the right one |
taken | The one object that fits belongs to another device, by a link or by its netlock_device_id. After a reinstallation a machine gets a new device id: clear netlock_device_id on the object, and the next run links it |
fields_missing | netlock_device_id does not exist |
create_incomplete | Creating is on, but a mapping or option for it is missing |
Such a device does not count as a failure and is checked again a day later, or within the hour for fields_missing and create_incomplete. Saving the settings, changing a mapping or Synchronize now ends the wait. An object that moved to another tenant in NetBox, or whose netlock_device_id names another device, is no longer written. If no new match is found, the link is removed, so the device no longer shows the object.
The External systems tab of the device links to its object.
Creating objects
Create devices that are missing is off by default and should stay off where NetBox is maintained by hand. With it on, a device without a match becomes a new device in NetBox with the status Inventory, in the mapped tenant. Creating requires:
- a device type for the device class, under
Mappings, Role of new devices,- a site, from the mapping of the location or from
Site of new devices.
NetLock always creates devices, never virtual machines.
Known limits
- An object without a tenant in NetBox is not found, because every search stays inside the mapped tenant.
- If two instances of NetLock write to the same NetBox, their device ids can collide. Use a separate tenant for each.
- Name and serial number follow NetBox: NetLock does not report differences.
- Data flows in one direction only: NetBox data does not flow into NetLock.