# netbox_interface – Creates or removes interfaces from Netbox

New in version 2.8.

- Synopsis

- Requirements

- Parameters

- Notes

- Examples

- Return Values

- Status

## Synopsis

- Creates or removes interfaces 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
| description string |  | The description of the prefix
| device string / required |  | Name of the device the interface will be associated with (case-sensitive)

enabled
boolean

Choices:
- no
- yes

Sets whether interface shows enabled or disabled

| form_factor string |  | Form factor of the interface: ex. 1000Base-T (1GE), Virtual, 10GBASE-T (10GE) This has to be specified exactly as what is found within UI
| lag dictionary |  | Parent LAG interface will be a member of
| mac_address string |  | The MAC address of the interface

mgmt_only
boolean

Choices:
- no
- yes

This interface is used only for out-of-band management

mode
string

Choices:
- Access
- Tagged
- Tagged All

The mode of the interface

| mtu string |  | The MTU of the interface
| name string / required |  | Name of the interface to be created
| tagged_vlans list |  | A list of tagged VLANS to be assigned to interface. Mode must be set to either `Tagged` or `Tagged All`
| tags list |  | Any tags that the prefix may need to be associated with
| untagged_vlan dictionary |  | The untagged VLAN to be assigned to interface
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
string

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 interface module"
      connection: local
      hosts: localhost
      gather_facts: False
      tasks:
        - name: Create interface within Netbox with only required information
          netbox_interface:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              device: test100
              name: GigabitEthernet1
            state: present
        - name: Delete interface within netbox
          netbox_interface:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              device: test100
              name: GigabitEthernet1
            state: absent
        - name: Create LAG with several specified options
          netbox_interface:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              device: test100
              name: port-channel1
              form_factor: Link Aggregation Group (LAG)
              mtu: 1600
              mgmt_only: false
              mode: Access
            state: present
        - name: Create interface and assign it to parent LAG
          netbox_interface:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              device: test100
              name: GigabitEthernet1
              enabled: false
              form_factor: 1000Base-t (1GE)
              lag:
                name: port-channel1
              mtu: 1600
              mgmt_only: false
              mode: Access
            state: present
        - name: Create interface as a trunk port
          netbox_interface:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              device: test100
              name: GigabitEthernet25
              enabled: false
              form_factor: 1000Base-t (1GE)
              untagged_vlan:
                name: Wireless
                site: Test Site
              tagged_vlans:
                - name: Data
                  site: Test Site
                - name: VoIP
                  site: Test Site
              mtu: 1600
              mgmt_only: true
              mode: Tagged
            state: present

## Return Values

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

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

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

Hint

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