Configuration¶

Customize NetBox SSL to fit your organization's needs.

Plugin Configuration¶

Add settings to your configuration.py:

PLUGINS = [
    "netbox_ssl",
]

PLUGINS_CONFIG = {
    "netbox_ssl": {
        "expiry_warning_days": 30,
        "expiry_critical_days": 14,
    },
}

Available Options¶

Expiry Thresholds¶

Control when certificates show warning/critical status:

Example: Alert earlier for production certificates:

PLUGINS_CONFIG = {
    "netbox_ssl": {
        "expiry_warning_days": 60,   # 2 months warning
        "expiry_critical_days": 30,  # 1 month critical
    },
}

Email Notifications¶

Send email alerts when certificates are expiring. Requires Django EMAIL_* settings to be configured on your NetBox server.

PLUGINS_CONFIG = {
    "netbox_ssl": {
        "notification_email_enabled": True,
        "notification_email_recipients": [
            "infra-team@example.com",
            "security@example.com",
        ],
        "notification_email_subject_prefix": "[NetBox SSL]",
    },
}

The email notification is triggered by the Certificate Expiry Notification script (see Scripts). When notification_email_enabled is True, the script automatically sends an HTML + plain-text email report after each run.

Prerequisites: Django's email backend must be configured. At minimum, set EMAIL_HOST, EMAIL_PORT, and DEFAULT_FROM_EMAIL in your NetBox configuration.py.

Bulk Import¶

Control the batch size limit for CSV/JSON bulk imports:

PLUGINS_CONFIG = {
    "netbox_ssl": {
        "bulk_import_max_batch_size": 200,  # Allow up to 200 certificates per import
    },
}

Custom Fields¶

Extend certificates with your own metadata via NetBox Custom Fields:

1. Navigate to Admin > Customization > Custom Fields
2. Click + Add
3. Configure the field:
4. Content Types: Select netbox_ssl | certificate
5. Name: e.g., cost_center
6. Type: Select appropriate type

Common custom field ideas: - cost_center — For billing/chargeback - environment — Production, Staging, Development - certificate_authority — Let's Encrypt, DigiCert, Internal CA - auto_renew — Boolean for automation tracking

Permissions¶

NetBox SSL uses NetBox's built-in permission system. Configure access via Admin > Users & Groups.

Certificate Permissions¶

Assignment Permissions¶

Example: Read-only auditor role: - Grant only view_certificate and view_certificateassignment

Example: Certificate manager role: - Grant all certificate permissions - Grant all assignment permissions

Dashboard Widget¶

Add the SSL Certificate Status widget to monitor certificate health:

1. Go to the NetBox Dashboard
2. Click + Add Widget (bottom of page)
3. Select SSL Certificate Status
4. Drag to position
5. Click Save

The widget displays: - All healthy — No action needed - Critical count — Certificates expiring within critical threshold - Warning count — Certificates expiring within warning threshold - Orphan count — Certificates without any assignments

Tags¶

Organize certificates with NetBox tags:

1. Create tags at Organization > Tags
2. Apply tags when creating/editing certificates
3. Filter by tags in list views

Suggested tag structure: - production / staging / development - internal-ca / public-ca - auto-renew / manual-renew - team:platform / team:security

Integration Tips¶

Webhooks¶

Trigger external actions on certificate events:

1. Navigate to Admin > Webhooks
2. Create a webhook with:
3. Content types: netbox_ssl | certificate
4. Events: Created, Updated, Deleted
5. URL: Your automation endpoint

Use cases: - Notify Slack/Teams when certificates are created - Trigger renewal automation when status changes to "Replaced" - Update CMDB on certificate changes

Custom Scripts¶

Use NetBox Custom Scripts to automate certificate operations:

from extras.scripts import Script
from netbox_ssl.models import Certificate

class ExpiringCertificatesReport(Script):
    class Meta:
        name = "Expiring Certificates Report"

    def run(self, data, commit):
        certs = Certificate.objects.filter(
            status='active'
        ).order_by('valid_to')[:10]

        for cert in certs:
            self.log_info(f"{cert.common_name}: {cert.days_remaining} days")

Next: Tutorial — Your First Certificate Import — Learn the import and renewal workflows