Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jalmargyyk/netbox-ripe-updater/llms.txt

Use this file to discover all available pages before exploring further.

The updater handles the common path — creating, updating, and deleting INETNUM and INET6NUM objects — reliably. A handful of edge cases exist, however, where the RIPE database model or the webhook-driven architecture makes it impossible for the updater to act correctly without some manual intervention. Each limitation below describes exactly when it occurs, why it cannot be handled automatically, and what you need to do to work around it.
What happensIf you enable ripe_report on a parent prefix (for example 203.0.113.0/24) and also on one of its child prefixes (for example 203.0.113.0/27), the updater will attempt to register both as separate INETNUM objects in RIPE DB.RIPE DB only allows one level of more-specific prefixes beneath an aggregate. When the updater tries to push the child, RIPE rejects it because the parent INETNUM already occupies that address space as a registered object, and the child would create a second level of nesting.The /update endpoint returns 500 and logs the RIPE error message.WorkaroundDecide which level should be authoritative in RIPE:
  • If you want the parent in RIPE, set ripe_report = false on all child prefixes.
  • If you want the child prefixes in RIPE, set ripe_report = false on the parent.
You cannot have both levels registered simultaneously.
What happensWhen you resize a prefix in NetBox — for example extending 203.0.113.0/27 to 203.0.113.0/26 — NetBox sends a single updated event with the new prefix string in data.prefix. From the updater’s perspective this looks like a brand-new prefix: it will attempt to create a /26 INETNUM in RIPE DB while the old /27 INETNUM still exists.Because there is no deterministic way to detect that a resize occurred (the old prefix string is not included in the webhook payload), the updater cannot automatically delete the stale /27 object first. The create call for the /26 will usually fail with a RIPE overlap error, leaving the /27 orphaned in RIPE DB.WorkaroundFollow this sequence when resizing a prefix:
  1. Set ripe_report = false on the prefix in NetBox and save. The updater will delete the existing INETNUM from RIPE DB.
  2. Change the prefix size in NetBox and save.
  3. Set ripe_report = true on the prefix in NetBox and save. The updater will create the new INETNUM with the correct size.
Skipping step 1 leaves a stale INETNUM in RIPE DB that you will need to delete manually via the RIPE web interface or the REST API.
What happensRIPE imposes a maximum TTL of 12 months on API keys. After expiry, every call to the RIPE REST API returns an authentication error, and all /update requests will respond with 500 until the credentials are rotated.The updater does not detect or warn about upcoming key expiry — it only fails at the point of use.WorkaroundRotate the credentials before they expire using the provided helper script:
./update-ripe-key.sh
The script backs up .env.updater, prompts you for the new RIPE_API_USER and RIPE_API_PASS values, writes them to the file, and restarts the containers. Schedule this at least once a year, or set a calendar reminder slightly ahead of the key creation date.
You can find the creation date of your current API key in the RIPE NCC Access portal. Use this date to set your annual rotation reminder.
What happensThe updater enforces minimum prefix size limits to avoid registering host routes or other very small prefixes in RIPE DB:
  • IPv4 prefixes with a mask length greater than SMALLEST_PREFIX_V4 (default /31) are skipped.
  • IPv6 prefixes with a mask length greater than SMALLEST_PREFIX_V6 (default /127) are skipped.
When a prefix falls below the limit, the updater raises an ErrorSmallPrefix exception internally and returns 200 OK with the body ErrorSmallPrefix, skipping request. No RIPE write is attempted, and no error is logged at the ERROR level.Because the response is 200, NetBox marks the webhook delivery as successful — there is no visible failure in the NetBox webhook log.WorkaroundIf you need to register smaller prefixes, raise the limits in .env.updater:
SMALLEST_PREFIX_V4=32
SMALLEST_PREFIX_V6=128
Set the value to the longest prefix length you want the updater to handle. Be aware that RIPE DB may have its own restrictions on very small allocations depending on your LIR agreement.

API endpoints

Full reference for all HTTP endpoints, including response codes

FAQ

Answers to common configuration and operational questions

Build docs developers (and LLMs) love

Get started for freeTalk to us