NetBox Attachments Plugin

NetBox plugin for attaching files to any model.

Features

This plugin provides the following model:

• NetBoxAttachment: A model for attaching files to any NetBox object.

Compatibility

The following table shows the compatibility between different NetBox versions and plugin versions:

NetBox Version	Plugin Version
>= 3.3.4	0.0.0 - 0.0.5
>= 3.4.0	0.0.6 - 1.0.6
>= 3.4.3	1.0.7 - 1.1.x
>= 3.5.0	2.0.0
>= 3.6.0	3.0.0
>= 3.7.0	4.0.0
>= 4.0.0	5.x.x
>= 4.1.0	6.x.x
>= 4.2.0	7.x.x
>= 4.3.0	8.x.x
>= 4.4.0	9.x.x

Installation

The plugin is available as a Python package on PyPI and can be installed with pip:

pip install netbox-attachments

To enable the plugin, add it to the PLUGINS list in your configuration.py:

PLUGINS = ['netbox_attachments']

Next, create a directory for storing attachments and set the appropriate permissions:

mkdir -p /opt/netbox/netbox/media/netbox-attachments
chown netbox /opt/netbox/netbox/media/netbox-attachments

Run the database migrations for the plugin:

python3 manage.py migrate netbox_attachments

Restart NetBox and ensure that netbox-attachments is included in your local_requirements.txt.

For more details, see the NetBox Documentation.

NetBox 4.4 Compatibility Changes

Starting from version 9.0.0, the plugin has been updated for full NetBox 4.4 compatibility with the following changes:

Template Extension Updates

• Models Attribute: Updated template extensions to use the models list attribute instead of the deprecated model attribute for NetBox 4.x compatibility.
• Error Handling: Improved error handling for template rendering when object types are missing.
• Template Panel Rendering: Fixed AttributeError issues in render_attachment_panel function for proper template extension compatibility.

API and URL Improvements

• Bulk Action URLs: Added proper URL patterns for bulk edit and bulk delete operations.
• URL Pattern Reorganization: Improved URL pattern ordering for better routing logic.
• Default Return URLs: Enhanced navigation flow after bulk operations.

These changes ensure the plugin works seamlessly with NetBox 4.4 while maintaining all core attachment functionality and improving the user experience.

New Validation Checks

From version 7.2.0, we introduce new model-level validation that ensures attachments are only created for permitted object types. Attempting to attach to an unpermitted model will raise a ValidationError.

Configuration

Plugin Options

The plugin can be customized using the following configuration options:

• applied_scope:

  • Type: String
  • Default: "app"
  • Options: "app", "model"
  • Description: Determines how attachments are enabled. In 'app' mode, attachments are allowed for all models in the configured apps. In 'model' mode, attachments can be enabled for specific models or all models within specified apps.

• scope_filter:

  • Type: List
  • Default: ['dcim', 'ipam', 'circuits', 'tenancy', 'virtualization', 'wireless']
  • Description: List of items to filter by.
    • In 'app' mode: Should contain app labels (e.g., 'dcim', 'ipam')
    • In 'model' mode: Can contain specific model strings in the format app_label.model_name (e.g., 'dcim.device') or app labels to include all models from that app.

• display_default:

  • Type: String
  • Default: "additional_tab"
  • Options: "left_page", "right_page", "full_width_page", "additional_tab"
  • Description: Sets the default location where attachments should be displayed in the models.

• create_add_button:

  • Type: Boolean
  • Default: True
  • Description: Specific only to additional_tab display setting. If set to True, it will create an "Add Attachment" button at the top of the parent view.

• display_setting:

  • Type: Dictionary
  • Default: {}
  • Format: {<app_label.model>: <preferred_display>}
  • Example: {'dcim.devicerole': 'full_width_page', 'dcim.device': 'left_page', 'ipam.vlan': 'additional_tab'}
  • Description: Override the display settings for specific models.
  • Tip: Use the correct app_label and model names, which can be found in the API at <your_netbox_url>/api/extras/content-types/.

API Usage

Since the import functionality has been removed, you can use the NetBox API to programmatically manage attachments:

Creating Attachments via API

import requests

# Example: Upload attachment via API
url = "https://your-netbox-url/api/plugins/netbox-attachments/attachments/"
headers = {
    "Authorization": "Token your-api-token",
    "Content-Type": "application/json"
}

# For file uploads, use multipart/form-data
files = {
    'file': ('filename.pdf', open('path/to/file.pdf', 'rb'))
}
data = {
    'object_type': 'dcim.device',  # ContentType ID or app_label.model
    'object_id': 123,
    'name': 'Device Manual',
    'description': 'User manual for the device'
}

response = requests.post(url, headers=headers, files=files, data=data)

Note: The additional_tab feature will work for plugin models if you include the following in your urls.py:

from netbox.urls import get_model_urls

path(
   "MODEL/<int:pk>/",
   include(get_model_urls("plugin_name", "model_name")),
),

Note: plugin_name refers to the plugin slug used in URLs (often hyphenated), which may differ from the Python package/module name.

By doing so, the system will automatically include the Changelog, Journal, and other registered tabs (such as Attachments) when additional_tab is enabled.

Configuration Example

Here is an example of how to configure the plugin in configuration.py:

PLUGINS_CONFIG = {
    'netbox_attachments': {
        'applied_scope': "model",  # 'app' or 'model'
        'scope_filter': [
            'dcim.device', 'ipam.prefix', 'ipam.ipaddress',  # Specific models
            'tenancy',  # All models from this app
        ],
        'display_default': "right_page",
        'create_add_button': True,
        'display_setting': { # Works only for `app.model` definition
            'ipam.vlan': "left_page",
            'dcim.device': "full_width_page",
            'dcim.devicerole': "full_width_page",
            'tenancy.tenant': "additional_tab"
        }
    }
}

Enabling Attachments for Custom Plugins (Models)

To enable attachments for custom plugin models:

1. Append your plugin to the scope_filter configuration list:

   scope_filter: ['<plugin_name>']

2. Extend the detail templates of your plugin models:

   {% load plugins %}  # At the top of the template
   
   {% plugin_right_page object %}  # Under the comments section
   
   # Add left_page and full_width for future extensions

Example (Device Model)

• load
• left_page
• right_page
• full_width_page

Screenshots

• Model View:
• List View:
• Detail View: