NetBox Maintenance Device Plugin

A comprehensive NetBox plugin for managing device preventive and corrective maintenance with enhanced visual indicators, scheduling capabilities, and multi-language support.

Features

• Maintenance Plans: Create and manage maintenance plans for devices and virtual machines with configurable frequency
• Cycle Start Date: Use the actual installation or cycle start date when registering existing equipment, retaining overdue cycles instead of starting over at plan creation (#26)
• Virtual Machine Support: Plans can target either a dcim.Device or a virtualization.VirtualMachine, with the same UX on both detail pages (#14)
• Calendar-based Scheduling: Schedule every N days / weeks / months / quarters / years, with an optional calendar anchor to avoid drift — e.g. "1st day of every month" or "start of each quarter" stays aligned with the calendar regardless of when previous executions happened (#15)
• Maintenance Executions: Record and track maintenance executions with status monitoring
• Device & VM Integration: View maintenance history directly on device and VM pages with dedicated tabs
• Quick Actions: Schedule and complete maintenance directly from the interface
• Upcoming & Overdue Dashboard: Filter by status (Overdue / Due Soon / Upcoming / On Track), maintenance type, and target type (Device / VM)
• REST API: Complete REST API for external integrations and automation
• Advanced Filtering: Powerful filtering and search capabilities
• Custom Actions: Schedule, complete, and cancel maintenance via API
• Statistics: Get maintenance statistics and overdue/upcoming reports

Compatibility

Note: Version 1.4.5 supports NetBox 4.4–4.7. See the NetBox 4.7 compatibility analysis for upstream changes, upgrade validation, and test coverage. The configured version range remains bounded to 4.4.0–4.7.99.

Python Requirements: This plugin requires Python 3.12 or later, including on NetBox 4.4. Use the Django and Python versions supported by your NetBox release; NetBox 4.7.3 pins Django 6.1.2.

Installation

Method 1: PyPI Installation (Recommended)

Now officially available on PyPI!

# Install the latest version
pip install netbox-maintenance-device

# Or install a specific version
pip install netbox-maintenance-device==1.4.5

For Docker deployments, add to your plugin_requirements.txt:

echo "netbox-maintenance-device>=1.4.5" >> plugin_requirements.txt

Method 2: GitHub Installation

# Install from GitHub (development version)
pip install git+https://github.com/diegogodoy06/netbox-maintenance-device.git

Method 3: Docker Installation

For Docker-based NetBox installations using netbox-docker:

📋 For detailed Docker installation instructions in English and Portuguese, see DOCKER_INSTALL.md

Configuration

Basic Configuration

Add the plugin to your NetBox configuration.py:

# configuration.py

PLUGINS = [
    'netbox_maintenance_device',
    # ... other plugins
]

# Optional: Plugin-specific settings
PLUGINS_CONFIG = {
    'netbox_maintenance_device': {
        # Future configuration options will be added here
        # Currently, the plugin uses default settings
    }
}

Language Configuration (Optional)

To enable Portuguese-BR by default:

# configuration.py

# Enable internationalization
USE_I18N = True
USE_L10N = True

# Set default language
LANGUAGE_CODE = 'pt-br'
TIME_ZONE = 'America/Sao_Paulo'

# Available languages
LANGUAGES = [
    ('en', 'English'),
    ('pt-br', 'Português (Brasil)'),
]

Restart Services

Restart your NetBox services:

# For systemd
sudo systemctl restart netbox netbox-rq

# For Docker
docker compose restart netbox netbox-worker

Usage

For detailed usage instructions, please refer to the USAGE.md guide, which includes:

• Creating and managing maintenance plans
• Scheduling and completing maintenance
• Monitoring maintenance status
• Using the REST API
• Troubleshooting common issues

Quick Start:

1. Create maintenance plans for your devices
2. View upcoming/overdue maintenance in the dashboard
3. Use quick action buttons to schedule or complete maintenance
4. Monitor device-specific maintenance on device pages

Screenshots

Device Maintenance Section

View maintenance plans and status directly on device pages

Upcoming Maintenance Dashboard

Monitor all upcoming and overdue maintenance across your infrastructure

Maintenance Plan Management

Create and manage maintenance plans with flexible scheduling

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

🙏 Acknowledgments

• NetBox community for the excellent platform
• Contributors and users providing feedback