> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Nautobot

> Connect Serval to Nautobot so workflows can look up network devices, IP addresses, and circuits, and sync Nautobot's device, interface, and circuit inventory into Serval as assets.

## 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.

<Info>
  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.
</Info>

**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

| Capability               | Description                                                                                                                                                                                                     |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nautobot REST API access | Workflows use the "Nautobot API request" action to read Nautobot's network inventory: devices, interfaces, IP addresses, prefixes, VLANs, circuits, locations, racks, virtual machines, tenants, and more.      |
| Nautobot GraphQL access  | The "Nautobot GraphQL request" action runs read-only GraphQL queries, which return an object and its related objects, such as a device with its manufacturer, location, and primary IP address, in one request. |
| Asset ingestion          | Installable workflows sync devices, interfaces that have an IP address, and circuits into Serval as external assets, each keyed by its Nautobot ID.                                                             |
| Network lookups          | Installable workflows find a device by name, serial number, or IP address, look up an IP address, and list the devices at a location.                                                                           |
| Connection health checks | Five built-in checks confirm the token works, the instance runs Nautobot 3.x, and the service user can read devices, interfaces, circuits, and GraphQL.                                                         |

## Prepare Nautobot

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Connect in Serval

<Steps>
  <Step title="Open the Nautobot connect form">
    Add a new Nautobot connection from your Serval integrations page.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Paste the API token">
    Paste the token you created for the service user.
  </Step>

  <Step title="Save, then run the health checks">
    The token isn't tested when you save, so run the health checks right after connecting.
  </Step>
</Steps>

<Tip>
  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.
</Tip>

## 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:

| Workflow                        | Synced as assets                                                                                                                                                                                                                         | Asset key             |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| Ingest Devices from Nautobot    | Every device: name, serial number, asset tag, role, manufacturer and model, platform, software version, status, location and its parent locations, rack, tenant, primary IPv4 and IPv6 addresses with DNS names, tags, and custom fields | Nautobot device ID    |
| Ingest Interfaces from Nautobot | Interfaces with at least one IP address: name, type, MAC address, status, management-only flag, the parent device's ID and name, and each IP address with its parent prefix, netmask, and DNS name                                       | Nautobot interface ID |
| Ingest Circuits from Nautobot   | Every circuit: circuit ID, type, provider, status, tenant, commit rate, install date, the location of each termination, tags, and custom fields                                                                                          | Nautobot circuit ID   |

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

<AccordionGroup>
  <Accordion title="Your Nautobot instance must be reachable from Serval">
    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.
  </Accordion>

  <Accordion title="Records are missing even though the health checks pass">
    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.
  </Accordion>

  <Accordion title="Only interfaces with IP addresses are synced">
    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.
  </Accordion>

  <Accordion title="Site-specific fields come from custom fields">
    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.
  </Accordion>

  <Accordion title="Some Nautobot endpoints are not covered by the typed API">
    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.
  </Accordion>

  <Accordion title="Serval pins the API version">
    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.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Nautobot integration.