# NetBox Attachments Plugin
[NetBox](https://github.com/netbox-community/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`:
```sh
pip install netbox-attachments
```
To enable the plugin, add it to the `PLUGINS` list in your `configuration.py`:
```python
PLUGINS = ['netbox_attachments']
```
Next, create a directory for storing attachments and set the appropriate permissions:
```sh
mkdir -p /opt/netbox/netbox/media/netbox-attachments
chown netbox /opt/netbox/netbox/media/netbox-attachments
```
Run the database migrations for the plugin:
```sh
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](https://docs.netbox.dev/en/stable/plugins/#installing-plugins).
## 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
```python
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`:
>
> ```python
> 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`:
```python
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:
```python
scope_filter: ['<plugin_name>']
```
2. Extend the detail templates of your plugin models:
```django
{% 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](https://github.com/netbox-community/netbox/blob/c1b7f09530f0293d0f053b8930539b1d174cd03b/netbox/templates/dcim/device.html#L6)
- [left_page](https://github.com/netbox-community/netbox/blob/c1b7f09530f0293d0f053b8930539b1d174cd03b/netbox/templates/dcim/device.html#L149)
- [right_page](https://github.com/netbox-community/netbox/blob/c1b7f09530f0293d0f053b8930539b1d174cd03b/netbox/templates/dcim/device.html#L288)
- [full_width_page](https://github.com/netbox-community/netbox/blob/c1b7f09530f0293d0f053b8930539b1d174cd03b/netbox/templates/dcim/device.html#L293)
## Screenshots
- **Model View:**
- **List View:**
- **Detail View:**
Raw data
{
"_id": null,
"home_page": "https://github.com/Kani999/netbox-attachments",
"name": "netbox-attachments",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "netbox, netbox-plugin",
"author": "Jan Krupa",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/08/38/bb7a999a3e12239f57d10c109386b42d22fe4fa4c413a37f15a37a8aac52/netbox_attachments-9.0.0.tar.gz",
"platform": null,
"description": "# NetBox Attachments Plugin\n\n[NetBox](https://github.com/netbox-community/netbox) plugin for attaching files to any model.\n\n## Features\n\n\nThis plugin provides the following model:\n\n- **NetBoxAttachment**: A model for attaching files to any NetBox object.\n\n## Compatibility\n\nThe following table shows the compatibility between different NetBox versions and plugin versions:\n\n| NetBox Version | Plugin Version |\n| -------------- | -------------- |\n| >= 3.3.4 | 0.0.0 - 0.0.5 |\n| >= 3.4.0 | 0.0.6 - 1.0.6 |\n| >= 3.4.3 | 1.0.7 - 1.1.x |\n| >= 3.5.0 | 2.0.0 |\n| >= 3.6.0 | 3.0.0 |\n| >= 3.7.0 | 4.0.0 |\n| >= 4.0.0 | 5.x.x |\n| >= 4.1.0 | 6.x.x |\n| >= 4.2.0 | 7.x.x |\n| >= 4.3.0 | 8.x.x |\n| >= 4.4.0 | 9.x.x |\n\n## Installation\n\nThe plugin is available as a Python package on PyPI and can be installed with `pip`:\n\n```sh\npip install netbox-attachments\n```\n\nTo enable the plugin, add it to the `PLUGINS` list in your `configuration.py`:\n\n```python\nPLUGINS = ['netbox_attachments']\n```\n\nNext, create a directory for storing attachments and set the appropriate permissions:\n\n```sh\nmkdir -p /opt/netbox/netbox/media/netbox-attachments\nchown netbox /opt/netbox/netbox/media/netbox-attachments\n```\n\nRun the database migrations for the plugin:\n\n```sh\npython3 manage.py migrate netbox_attachments\n```\n\nRestart NetBox and ensure that `netbox-attachments` is included in your `local_requirements.txt`.\n\nFor more details, see the [NetBox Documentation](https://docs.netbox.dev/en/stable/plugins/#installing-plugins).\n\n## NetBox 4.4 Compatibility Changes\n\nStarting from version 9.0.0, the plugin has been updated for full NetBox 4.4 compatibility with the following changes:\n\n### Template Extension Updates\n- **Models Attribute**: Updated template extensions to use the `models` list attribute instead of the deprecated `model` attribute for NetBox 4.x compatibility.\n- **Error Handling**: Improved error handling for template rendering when object types are missing.\n- **Template Panel Rendering**: Fixed AttributeError issues in `render_attachment_panel` function for proper template extension compatibility.\n\n### API and URL Improvements\n- **Bulk Action URLs**: Added proper URL patterns for bulk edit and bulk delete operations.\n- **URL Pattern Reorganization**: Improved URL pattern ordering for better routing logic.\n- **Default Return URLs**: Enhanced navigation flow after bulk operations.\n\nThese changes ensure the plugin works seamlessly with NetBox 4.4 while maintaining all core attachment functionality and improving the user experience.\n\n\n## New Validation Checks\n\nFrom 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.\n\n## Configuration\n\n### Plugin Options\n\nThe plugin can be customized using the following configuration options:\n\n- `applied_scope`:\n\n - **Type**: String\n - **Default**: `\"app\"`\n - **Options**: `\"app\"`, `\"model\"`\n - **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.\n\n- `scope_filter`:\n\n - **Type**: List\n - **Default**: `['dcim', 'ipam', 'circuits', 'tenancy', 'virtualization', 'wireless']`\n - **Description**: List of items to filter by.\n - In 'app' mode: Should contain app labels (e.g., 'dcim', 'ipam')\n - 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.\n\n- `display_default`:\n\n - **Type**: String\n - **Default**: `\"additional_tab\"`\n - **Options**: `\"left_page\"`, `\"right_page\"`, `\"full_width_page\"`, `\"additional_tab\"`\n - **Description**: Sets the default location where attachments should be displayed in the models.\n\n- `create_add_button`:\n\n - **Type**: Boolean\n - **Default**: `True`\n - **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.\n\n- `display_setting`:\n - **Type**: Dictionary\n - **Default**: `{}`\n - **Format**: `{<app_label.model>: <preferred_display>}`\n - **Example**: `{'dcim.devicerole': 'full_width_page', 'dcim.device': 'left_page', 'ipam.vlan': 'additional_tab'}`\n - **Description**: Override the display settings for specific models.\n - **Tip**: Use the correct `app_label` and `model` names, which can be found in the API at `<your_netbox_url>/api/extras/content-types/`.\n\n\n## API Usage\n\nSince the import functionality has been removed, you can use the NetBox API to programmatically manage attachments:\n\n### Creating Attachments via API\n\n```python\nimport requests\n\n# Example: Upload attachment via API\nurl = \"https://your-netbox-url/api/plugins/netbox-attachments/attachments/\"\nheaders = {\n \"Authorization\": \"Token your-api-token\",\n \"Content-Type\": \"application/json\"\n}\n\n# For file uploads, use multipart/form-data\nfiles = {\n 'file': ('filename.pdf', open('path/to/file.pdf', 'rb'))\n}\ndata = {\n 'object_type': 'dcim.device', # ContentType ID or app_label.model\n 'object_id': 123,\n 'name': 'Device Manual',\n 'description': 'User manual for the device'\n}\n\nresponse = requests.post(url, headers=headers, files=files, data=data)\n```\n\n> **Note**: The `additional_tab` feature will work for plugin models if you include the following in your `urls.py`:\n>\n> ```python\n> from netbox.urls import get_model_urls\n> \n> path(\n> \"MODEL/<int:pk>/\",\n> include(get_model_urls(\"plugin_name\", \"model_name\")),\n> ),\n> ```\n>\n> **Note**: `plugin_name` refers to the plugin slug used in URLs (often hyphenated), which may differ from the Python package/module name.\n>\n> By doing so, the system will automatically include the Changelog, Journal, and other registered tabs (such as Attachments) when `additional_tab` is enabled.\n\n### Configuration Example\n\nHere is an example of how to configure the plugin in `configuration.py`:\n\n```python\nPLUGINS_CONFIG = {\n 'netbox_attachments': {\n 'applied_scope': \"model\", # 'app' or 'model'\n 'scope_filter': [\n 'dcim.device', 'ipam.prefix', 'ipam.ipaddress', # Specific models\n 'tenancy', # All models from this app\n ],\n 'display_default': \"right_page\",\n 'create_add_button': True,\n 'display_setting': { # Works only for `app.model` definition\n 'ipam.vlan': \"left_page\",\n 'dcim.device': \"full_width_page\",\n 'dcim.devicerole': \"full_width_page\",\n 'tenancy.tenant': \"additional_tab\"\n }\n }\n}\n```\n\n## Enabling Attachments for Custom Plugins (Models)\n\nTo enable attachments for custom plugin models:\n\n1. Append your plugin to the `scope_filter` configuration list:\n\n ```python\n scope_filter: ['<plugin_name>']\n ```\n\n2. Extend the detail templates of your plugin models:\n\n ```django\n {% load plugins %} # At the top of the template\n\n {% plugin_right_page object %} # Under the comments section\n\n # Add left_page and full_width for future extensions\n ```\n\n### Example (Device Model)\n\n- [load](https://github.com/netbox-community/netbox/blob/c1b7f09530f0293d0f053b8930539b1d174cd03b/netbox/templates/dcim/device.html#L6)\n- [left_page](https://github.com/netbox-community/netbox/blob/c1b7f09530f0293d0f053b8930539b1d174cd03b/netbox/templates/dcim/device.html#L149)\n- [right_page](https://github.com/netbox-community/netbox/blob/c1b7f09530f0293d0f053b8930539b1d174cd03b/netbox/templates/dcim/device.html#L288)\n- [full_width_page](https://github.com/netbox-community/netbox/blob/c1b7f09530f0293d0f053b8930539b1d174cd03b/netbox/templates/dcim/device.html#L293)\n\n## Screenshots\n\n- **Model View:**\n \n- **List View:**\n \n- **Detail View:**\n \n",
"bugtrack_url": null,
"license": "Apache 2",
"summary": "Netbox plugin to manage attachments for any model",
"version": "9.0.0",
"project_urls": {
"Homepage": "https://github.com/Kani999/netbox-attachments"
},
"split_keywords": [
"netbox",
" netbox-plugin"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5ee13e0a3d77e9cb98b0318e715365e58102f93818ee7311462fb702e83b7218",
"md5": "dcc5fdc49404d463c0cc65973b2215c7",
"sha256": "887ea4ec80c41f560d3c1e86ac0edd3f3ddd3704b6dd82553de0651534853761"
},
"downloads": -1,
"filename": "netbox_attachments-9.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dcc5fdc49404d463c0cc65973b2215c7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 28977,
"upload_time": "2025-09-03T09:47:33",
"upload_time_iso_8601": "2025-09-03T09:47:33.322353Z",
"url": "https://files.pythonhosted.org/packages/5e/e1/3e0a3d77e9cb98b0318e715365e58102f93818ee7311462fb702e83b7218/netbox_attachments-9.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0838bb7a999a3e12239f57d10c109386b42d22fe4fa4c413a37f15a37a8aac52",
"md5": "3415b8d4084b2063e3af957192afd60f",
"sha256": "b29620ff9b5443ab91bb4440b26e6f06f991b3e3ee78df5bed2eb7babbab3a12"
},
"downloads": -1,
"filename": "netbox_attachments-9.0.0.tar.gz",
"has_sig": false,
"md5_digest": "3415b8d4084b2063e3af957192afd60f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 23236,
"upload_time": "2025-09-03T09:47:34",
"upload_time_iso_8601": "2025-09-03T09:47:34.539986Z",
"url": "https://files.pythonhosted.org/packages/08/38/bb7a999a3e12239f57d10c109386b42d22fe4fa4c413a37f15a37a8aac52/netbox_attachments-9.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-03 09:47:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Kani999",
"github_project": "netbox-attachments",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "netbox-attachments"
}
JSON
