# netbox – NetBox inventory source

- Synopsis
- Parameters
- Examples
- Status

## Synopsis

- Get inventory hosts from NetBox

## Parameters

Parameter | Choices/Defaults | Configuration | Comments
--- | --- | --- | ---
api_endpoint - / required |  | env:NETBOX_API | Endpoint of the NetBox API
compose dictionary | Default: {} |  | List of custom ansible host vars to create from the device object fetched from NetBox
config_context boolean | Default: "no" |  | If True, it adds config-context in host vars. Config-context enables the association of arbitrary data to devices and virtual machines grouped by region, site, role, platform, and/or tenant. Please check official netbox docs for more info.

group_by
list

Choices:
- sites
- tenants
- racks
- tags
- device_roles
- device_types
- manufacturers
- platforms

Default:
[]

Keys used to create groups.

groups dictionary | Default: {} |  | Add hosts to group based on Jinja2 conditionals.
keyed_groups list | Default: [] |  | Add hosts to group based on the values of a variable.

plugin
- / required

Choices:
- netbox

token that ensures this is a source file for the 'netbox' plugin.

query_filters list | Default: [] |  | List of parameters passed to the query string (Multiple values may be separated by commas)

strict
boolean

Choices:
- no ←
- yes

If `yes` make invalid entries a fatal error, otherwise skip and continue.
Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default.

timeout integer | Default: 60 |  | Timeout for Netbox requests in seconds
token - / required |  | env:NETBOX_TOKEN env:NETBOX_API_KEY | NetBox token.
validate_certs boolean | Default: "yes" |  | Allows connection when SSL certificates are not valid. Set to `false` when certificates are not trusted.

## Examples

    # netbox_inventory.yml file in YAML format
    # Example command line: ansible-inventory -v --list -i netbox_inventory.yml

    plugin: netbox
    api_endpoint: http://localhost:8000
    validate_certs: True
    config_context: False
    group_by:
      - device_roles
    query_filters:
      - role: network-edge-router

    # Query filters are passed directly as an argument to the fetching queries.
    # You can repeat tags in the query string.

    query_filters:
      - role: server
      - tag: web
      - tag: production

    # See the NetBox documentation at https://netbox.readthedocs.io/en/latest/api/overview/
    # the query_filters work as a logical **OR**
    #
    # Prefix any custom fields with cf_ and pass the field value with the regular NetBox query string

    query_filters:
      - cf_foo: bar

    # NetBox inventory plugin also supports Constructable semantics
    # You can fill your hosts vars using the compose option:

    plugin: netbox
    compose:
      foo: last_updated
      bar: display_name
      nested_variable: rack.display_name

## Status

- This inventory is not guaranteed to have a backwards compatible interface. [preview]
- This inventory is maintained by the Ansible Community. [community]

### Authors

- Remy Leone (@sieben)
- Anthony Ruhier (@Anthony25)
- Nikhil Singh Baliyan (@nikkytub)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.