# netbox_prefix – Creates or removes prefixes from Netbox

New in version 2.8.

- Synopsis
- Requirements
- Parameters
- Notes
- Examples
- Return Values
- Status

## Synopsis

- Creates or removes prefixes from Netbox

## Requirements

The below requirements are needed on the host that executes this module.

- pynetbox

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
data - / required |  | Defines the prefix configuration
| custom_fields dictionary |  | Must exist in Netbox and in key/value format
| description string |  | The description of the prefix

family
integer

Choices:
- 4
- 6

Specifies which address family the prefix prefix belongs to

is_pool
boolean

Choices:
- no
- yes

All IP Addresses within this prefix are considered usable

| parent string |  | Required if state is `present` and first_available is `yes`. Will get a new available prefix in this parent prefix.
| prefix string |  | Required if state is `present` and first_available is False. Will allocate or free this prefix.
| prefix_length string |  | Required ONLY if state is `present` and first_available is `yes`. Will get a new available prefix of the given prefix_length in this parent prefix.
| role string |  | The role of the prefix
| site string |  | Site that prefix is associated with

status
string

Choices:
- Active
- Container
- Deprecated
- Reserved

The status of the prefix

| tags list |  | Any tags that the prefix may need to be associated with
| tenant string |  | The tenant that the prefix will be assigned to
| vlan dictionary |  | The VLAN the prefix will be assigned to
| vrf string |  | VRF that prefix is associated with

first_available
boolean

Choices:
- no ←
- yes

If `yes` and state `present`, if an parent is given, it will get the first available prefix of the given prefix_length inside the given parent (and vrf, if given). Unused with state `absent`.

netbox_token string / required |  | The token created within Netbox to authorize API access
netbox_url string / required |  | URL of the Netbox instance resolvable by Ansible control host

state
-

Choices:
- absent
- present ←

Use `present` or `absent` for adding or removing.

validate_certs
boolean

Choices:
- no
- yes ←

If `no`, SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates.

## Notes

Note

- Tags should be defined as a YAML list
- This should be ran with connection `local` and hosts `localhost`

## Examples

    - name: "Test Netbox prefix module"
      connection: local
      hosts: localhost
      gather_facts: False

      tasks:
        - name: Create prefix within Netbox with only required information
          netbox_prefix:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              prefix: 10.156.0.0/19
            state: present

        - name: Delete prefix within netbox
          netbox_prefix:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              prefix: 10.156.0.0/19
            state: absent

        - name: Create prefix with several specified options
          netbox_prefix:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              family: 4
              prefix: 10.156.32.0/19
              site: Test Site
              vrf: Test VRF
              tenant: Test Tenant
              vlan:
                name: Test VLAN
                site: Test Site
                tenant: Test Tenant
                vlan_group: Test Vlan Group
              status: Reserved
              role: Network of care
              description: Test description
              is_pool: true
              tags:
                - Schnozzberry
            state: present

        - name: Get a new /24 inside 10.156.0.0/19 within Netbox - Parent doesn't exist
          netbox_prefix:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              parent: 10.156.0.0/19
              prefix_length: 24
            state: present
            first_available: yes

        - name: Create prefix within Netbox with only required information
          netbox_prefix:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              prefix: 10.156.0.0/19
            state: present

        - name: Get a new /24 inside 10.156.0.0/19 within Netbox
          netbox_prefix:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              parent: 10.156.0.0/19
              prefix_length: 24
            state: present
            first_available: yes

        - name: Get a new /24 inside 10.157.0.0/19 within Netbox with additional values
          netbox_prefix:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              parent: 10.157.0.0/19
              prefix_length: 24
              vrf: Test VRF
              site: Test Site
            state: present
            first_available: yes

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Returned | Description
--- | --- | ---
msg string | always | Message indicating failure or info about what has been achieved
prefix dictionary | on creation | Serialized object as created or already existent within Netbox

## Status

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

### Authors

- Mikhail Yohman (@FragmentedPacket)
- Anthony Ruhier (@Anthony25)

Hint

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