Skip to main content

​
About Nautobot

Nautobot is an open-source network source of truth and automation platform from Network to Code. It records network devices, their interfaces and IP addresses, circuits, and the locations they live in. Serval connects to your own Nautobot 3.x instance and reads from it. The integration never writes to Nautobot. The integration is marked Beta in the connect screen.
For a Nautobot instance on a private network, enable Run on self-hosted workers for the connection and use an up-to-date worker and proxy. API requests then run from your network. The worker must be able to reach the instance and trust its TLS certificate. Publicly reachable instances can use Serval’s cloud proxy.
Authentication: A Nautobot API token for a dedicated service user. Serval stores the token encrypted and adds it to requests server-side, so workflows never handle it. Serval sends the token only to the Nautobot hostname saved on the connection. Data sync: No background sync starts when you connect. Data access is on demand through workflows, plus three installable ingestion workflows that sync Nautobot devices, interfaces, and circuits into Serval as assets.

​
What the Nautobot integration enables

​
Prepare Nautobot

Serval needs an API token for a Nautobot user whose permissions cover the data Serval should read.
1

Create a service user

In Nautobot, create a dedicated user for Serval rather than using a person’s account. A personal token stops working when that person leaves or their access changes.
2

Grant view permissions

Create an object permission with the view action and assign it to the service user (or to a group it belongs to). Include the object types Serval reads:
  • Devices: devices, device types, manufacturers, platforms, software versions, roles, statuses, racks, and tags
  • Locations: locations and location types
  • Interfaces and IP addresses: interfaces, IP addresses, prefixes, and namespaces
  • Circuits: circuits, circuit terminations, circuit types, providers, and provider networks
  • Tenancy: tenants
Nautobot returns only the objects a user may view. A related object the user cannot view, such as a device’s manufacturer, comes back empty instead of failing the request. Add constraints to the permission if Serval should see only part of your network.
3

Create a read-only API token

Sign in as the service user, open the user’s profile, and add an API token. Clear Write enabled, because Serval only reads. Nautobot then rejects any write made with the token, whatever the user’s permissions allow. Copy the token.

​
Connect in Serval

1

Open the Nautobot connect form

Add a new Nautobot connection from your Serval integrations page.
2

Enter the Nautobot URL

Enter the hostname of your instance, optionally with a port, for example network.example.com or network.example.com:8443. Nautobot must be served over HTTPS at the root of the host. A URL starting with http://, or one with a path, is rejected when you save.
3

Paste the API token

Paste the token you created for the service user.
4

Save, then run the health checks

The token isn’t tested when you save, so run the health checks right after connecting.
To rotate the token, create the replacement token in Nautobot, edit the connection, paste only the new token, confirm the health checks pass, and then delete the old token in Nautobot. If you change the Nautobot URL on an existing connection, you must enter the token again, because Serval never sends a stored token to a different host.

​
Verifying the connection

The connection ships five health checks that make live calls to Nautobot:
  • Validate API connection: reads Nautobot’s status endpoint. On success: “Successfully connected to Nautobot [version].” It fails if the instance runs a Nautobot release other than 3.x.
  • List devices: reads one device and reports how many devices the token can see.
  • List interfaces: reads one interface and reports how many interfaces the token can see.
  • List circuits: reads one circuit and reports how many circuits the token can see.
  • Query GraphQL API: runs a one-device GraphQL query. Asset ingestion reads through GraphQL, so ingestion can’t work until this check passes.
A check can also pass with a message that starts “Connected, but no” and says none are visible to this token. That means the connection works but the service user can’t see any of that object type. If Nautobot has those objects, review the user’s object permissions.

​
Syncing Nautobot inventory into Serval

Install the ingestion workflows you need and use them as asset sync sources: Each interface record carries its parent device’s Nautobot ID, which matches the external ID of that device’s asset, so interfaces can be related to their devices.

​
Gotchas and troubleshooting

Confirm the hostname is correct and reachable from the worker or Serval deployment serving the connection. For private instances, check that Run on self-hosted workers is enabled and that your worker and proxy are up to date.
Serval sees exactly what the service user may view. Object permissions with constraints, such as a single tenant or location, hide everything outside them, both from lookups and from ingestion. Related fields that come back empty on synced assets usually mean the user lacks view permission on that related object type, such as manufacturers or tenants.
Every switch port is an interface in Nautobot, so syncing all of them would create far more assets than your devices, mostly ports with nothing a CMDB record needs. The interface workflow therefore syncs interfaces that have an IP address assigned. To sync every interface, edit the installed workflow and remove the has_ip_addresses filter.
Nautobot has no built-in field for attributes such as environment. If you track them as Nautobot custom fields, they’re included on each synced device and circuit under their custom field keys.
The API request action is typed against the Nautobot 3.2 apps a network inventory needs: DCIM, IPAM, circuits, tenancy, virtualization, and extras. Endpoints added by Nautobot apps, such as Golden Config, and the string-match filter variants (name__ic, name__nisw, and so on) aren’t part of it. Exact-match and range filters are.
Serval requests Nautobot REST API version 3.2 on every REST call, so upgrading Nautobot within 3.x doesn’t change the REST responses workflows receive.
Need help? Contact support@serval.com for assistance with your Nautobot integration.