OpenParable
Skip to content
← Back to skills

Add Config Param

Development
add-config-param

Add Config Param is an Agent Skill for development published in the netbox-community/netbox repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Step-by-step guide for adding a new configuration parameter to NetBox, covering both static parameters (settings.py) and dynamic parameters (database-backed, editable via the admin UI). Use when the user asks to add a new configuration option, setting, or parameter to NetBox.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/netbox-community/netbox/blob/HEAD/.claude/skills/add-config-param/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/add-config-param, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Adding a Configuration Parameter to NetBox

NetBox has two distinct kinds of configuration parameters. Choose the right one before writing any code:

TypeWhere definedChanged byTakes effect
Staticsettings.py via getattr(configuration, ...)Editing configuration.py + restartOn WSGI restart
Dynamicconfig/parameters.py PARAMS tupleAdmin UI or configuration.pyImmediately (cached in Redis)

Use dynamic when:

  • Operators need to tune the value without a service restart
  • The parameter controls UI behavior or defaults (banners, page sizes, default values)
  • Examples: PAGINATE_COUNT, MAINTENANCE_MODE, BANNER_TOP

Use static when:

  • The value must not change at runtime (auth backends, database config, secret keys)
  • The value controls infrastructure that requires a restart anyway
  • Examples: ALLOWED_HOSTS, REMOTE_AUTH_BACKEND, LOGGING

Adding a Dynamic Configuration Parameter

Dynamic parameters are defined in netbox/netbox/config/parameters.py, stored in the ConfigRevision.data JSONField, cached in Redis, and editable via Admin > System > Configuration History.

Step 1 — Add to PARAMS

File: netbox/netbox/config/parameters.py

Add a ConfigParam entry to the PARAMS tuple, grouped logically with related parameters:

ConfigParam(
    name='MY_PARAM',
    label=_('My param'),
    default=<default_value>,
    description=_("One-sentence description of what this controls"),
    field=forms.BooleanField,   # or IntegerField, CharField, JSONField, SimpleArrayField
    # field_kwargs only when extra widget/validation config is needed:
    field_kwargs={
        'widget': forms.Textarea(attrs={'class': 'vLargeTextField'}),
    },
),

Common field choices:

FieldUse for
forms.CharField (default)Short strings
forms.BooleanFieldOn/off toggles
forms.IntegerFieldCounts, sizes, timeouts
forms.JSONFieldDicts/lists with free-form structure
SimpleArrayFieldLists of strings (add field_kwargs={'base_field': forms.CharField()})

The default value is returned whenever no ConfigRevision row exists and the parameter is not hard-coded in configuration.py.

Step 2 — Use the parameter in code

Access via get_config() (request-scoped, cached) or the ConfigItem callable (deferred):

from netbox.config import get_config

# One-time read:
value = get_config().MY_PARAM

# Deferred (evaluated later):
from netbox.config import ConfigItem
MY_PARAM = ConfigItem('MY_PARAM')

get_config() returns the Config object which tries:

  1. Hard-coded value in Django settings (set by configuration.py)
  2. Redis-cached active ConfigRevision
  3. ConfigParam.default

Step 3 — Document in the configuration docs

Add a section to the appropriate file under docs/configuration/:

FileCategory
miscellaneous.mdGeneral / doesn't fit elsewhere
default-values.mdDefault values for object fields
security.mdAuth, permissions, URL validation
data-validation.mdCUSTOM_VALIDATORS, PROTECTION_RULES
graphql-api.mdGraphQL settings
error-reporting.mdSentry, logging
remote-authentication.mdRemote auth settings
development.mdDeveloper-only flags
system.mdLow-level system settings

Template for a dynamic parameter doc section:

## MY_PARAM

!!! tip "Dynamic Configuration Parameter"

Default: `<default_value>`

One or two sentences describing what the parameter does, what values are accepted,
and any side effects.

Step 4 — Register in the dynamic params index

File: docs/configuration/index.md

Add the new parameter to the bulleted list under "Dynamic Configuration Parameters", keeping the list alphabetically ordered:

* [`MY_PARAM`](./miscellaneous.md#my_param)

Step 5 — Optionally add to the example config

If the parameter is important enough that operators should know they can hard-code it, add a commented entry to netbox/netbox/configuration_example.py:

# MY_PARAM = <default_value>

Place it near related parameters.

No migration needed

Dynamic parameters are stored in the ConfigRevision.data JSONField, which already exists. No database migration is required when adding a new ConfigParam.


Adding a Static Configuration Parameter

Static parameters live in settings.py and are read at startup from configuration.py. They take effect only after the WSGI service is restarted.

Step 1 — Add to settings.py

File: netbox/netbox/settings.py

Add a line in the "Set static config parameters" block, alphabetically within its logical group:

MY_PARAM = getattr(configuration, 'MY_PARAM', <default_value>)

For required parameters (no default), use getattr(configuration, 'MY_PARAM') with no fallback and add the parameter name to the required check near the top:

for parameter in ('ALLOWED_HOSTS', 'MY_PARAM', 'SECRET_KEY', 'REDIS'):
    if not hasattr(configuration, parameter):
        raise ImproperlyConfigured(f"Required parameter {parameter} is missing from configuration.")

Step 2 — Add validation (if needed)

If the parameter has constrained values, add an ImproperlyConfigured check immediately after the getattr line:

MY_PARAM = getattr(configuration, 'MY_PARAM', 'option_a')
if MY_PARAM not in ('option_a', 'option_b'):
    raise ImproperlyConfigured(f"MY_PARAM must be 'option_a' or 'option_b' (found {MY_PARAM})")

For complex validation (importable paths, valid URLs, etc.) follow the patterns of PROXY_ROUTERS or RELEASE_CHECK_URL in settings.py.

Step 3 — Add to the example config

File: netbox/netbox/configuration_example.py

Add a commented entry with a brief inline comment explaining the parameter:

# MY_PARAM = 'default_value'    # Short description of what this does

Step 4 — Document

Add a section to the appropriate docs/configuration/*.md file:

## MY_PARAM

Default: `<default_value>`

One or two sentences describing the parameter, accepted values, and any constraints.

---

Static parameters do not get the !!! tip "Dynamic Configuration Parameter" admonition.


Common Gotchas

  • Dynamic params don't need a migration — the value is stored in the ConfigRevision.data JSONField which already exists.
  • Hard-coding a dynamic param in configuration.py overrides the UI — the loop at the bottom of settings.py (for param in CONFIG_PARAMS: ...) sets the Django setting, which Config.__getattr__ checks first. Document this behaviour in the parameter's doc page.
  • forms.BooleanField with required=False: the ConfigFormMetaclass always adds required=False, so a BooleanField correctly represents a three-state (True / False / unset-use-default) UI. No extra field_kwargs needed for booleans.
  • SimpleArrayField needs base_field: always pass field_kwargs={'base_field': forms.CharField()}.
  • No ruff format on existing files — use ruff check only.

References

  • Dynamic param definitions: netbox/netbox/config/parameters.py
  • Config loading / Config class: netbox/netbox/config/__init__.py
  • ConfigRevision model: netbox/core/models/config.py
  • ConfigRevisionForm (metaclass): netbox/core/forms/model_forms.py
  • Static config loading: netbox/netbox/settings.py lines 67–213
  • Example config: netbox/netbox/configuration_example.py
  • Config tests: netbox/netbox/tests/test_config.py
  • Documentation: docs/configuration/