netbox-peering-manager 0.2.0__tar.gz

netbox_peering_manager-0.2.0/LICENSE

@@ -0,0 +1,177 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

netbox_peering_manager-0.2.0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include netbox_peering_manager/templates *.html

netbox_peering_manager-0.2.0/PKG-INFO

@@ -0,0 +1,383 @@
+Metadata-Version: 2.4
+Name: netbox-peering-manager
+Version: 0.2.0
+Summary: BGP related stuff
+Home-page: https://github.com/jsenecal/netbox-peering-manager
+Author: Jonathan Senecal
+Author-email: jonathan.senecal@metrooptic.com
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Framework :: Django
+Classifier: Programming Language :: Python :: 3
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx
+Requires-Dist: tenacity
+Requires-Dist: netbox-routing
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: summary
+
+# netbox-peering-manager
+
+[NetBox Peering Manager](https://github.com/jsenecal/netbox-peering-manager) is a peering management plugin for [NetBox](https://github.com/netbox-community/netbox). It provides a way to document Internet Exchange points, peering sessions, and IRR prefix list synchronization, serving as both a source of truth and a configuration management layer for external BGP sessions (transit, customers, peering, etc).
+
+Starting with v0.2.0, this plugin builds on top of [netbox-routing](https://github.com/DanSheps/netbox-routing), which provides the core BGP data models (peers, peer groups, routing policies, prefix lists, communities, BFD profiles, etc). netbox-peering-manager extends those models with peering-specific functionality rather than duplicating them.
+
+## Features
+
+This plugin provides the following on top of netbox-routing:
+
+**Peering Session Management:**
+* Peering Sessions — thin wrapper around netbox-routing's BGPPeer, adding relationship type, peering network association, and service reference tracking
+* Relationship Types — classify sessions as transit, peer, customer, IXP, etc.
+* Peer ASNs — extends NetBox ASN with peering-specific attributes (IRR AS-SET, max prefixes, PeeringDB ID)
+
+**Internet Exchange Support:**
+* Peering Fabric Types — classify fabric types (IX, cloud exchange, private LAN)
+* Peering Fabrics — represent IX or peering environments with PeeringDB integration
+* Peering Networks — IX LANs with prefix/VLAN associations
+* Peering Connections — device interface attachments to peering networks
+
+**IRR Prefix List Synchronization:**
+* IRR Sources — configure IRR query endpoints (via [fastbgpq4](https://github.com/jsenecal/fastbgpq4))
+* IRR Prefix List Configs — link netbox-routing PrefixLists to IRR sources for automatic sync
+* Background jobs for single and bulk prefix list synchronization
+
+**External Integrations:**
+* PeeringDB selective sync (IX discovery, peer discovery)
+* Configuration templating (Jinja2 with multi-vendor support via NetBox ConfigTemplates)
+
+**Provided by netbox-routing (required dependency):**
+* BGP Peers and Peer Templates (peer groups)
+* BGP Routers and Scopes
+* Routing Policies (route maps) with address family support
+* Prefix Lists and Prefix List Entries
+* Communities and Community Lists
+* AS Path Lists
+* BFD Profiles
+
+## Compatibility
+
+| NetBox Version | Plugin Version | netbox-routing Version |
+|----------------|----------------|------------------------|
+| NetBox 4.5.x   | >= 0.2.0       | 0.4.x+                |
+| NetBox 4.4.x   | 0.1.x          | N/A (standalone)       |
+
+## Prerequisites
+
+**netbox-routing** must be installed and enabled before installing netbox-peering-manager. The plugin declares `netbox_routing` as a required plugin and will not load without it.
+
+```bash
+pip install git+https://github.com/DanSheps/netbox-routing.git@14318f1c
+```
+
+Enable it in your NetBox configuration:
+
+```python
+PLUGINS = [
+    'netbox_routing',
+    'netbox_peering_manager',
+]
+```
+
+> **Important:** `netbox_routing` must appear before `netbox_peering_manager` in the `PLUGINS` list.
+
+## Installation
+
+Install the plugin (this will also pull in netbox-routing as a dependency):
+
+```bash
+pip install git+https://github.com/jsenecal/netbox-peering-manager.git
+```
+
+Enable both plugins in `/opt/netbox/netbox/netbox/configuration.py`:
+
+```python
+PLUGINS = [
+    'netbox_routing',
+    'netbox_peering_manager',
+]
+```
+
+Run database migrations:
+
+```bash
+cd /opt/netbox/netbox
+python manage.py migrate
+```
+
+Restart NetBox and add `netbox-peering-manager` to your `local_requirements.txt`.
+
+See [NetBox Documentation](https://docs.netbox.dev/en/stable/plugins/#installing-plugins) for details.
+
+## Configuration
+
+```python
+PLUGINS_CONFIG = {
+    'netbox_peering_manager': {
+        # Enable top-level navigation menu (default: True)
+        'top_level_menu': True,
+
+        # PeeringDB integration (all optional)
+        'peeringdb_url': None,           # Falls back to default PeeringDB API
+        'peeringdb_api_key': None,       # Optional, needed for contact info
+        'peeringdb_timeout': None,       # Falls back to 30s
+        'peeringdb_local_asns': [],      # Your ASN(s) for filtering
+    }
+}
+```
+
+## Model Architecture
+
+netbox-peering-manager v0.2.0 follows a layered architecture where netbox-routing provides the core BGP models and this plugin adds peering-specific extensions:
+
+```
+netbox-routing (dependency)          netbox-peering-manager (this plugin)
+─────────────────────────────        ────────────────────────────────────
+BGPPeer ◄──────────────────────────── PeeringSession (1:1)
+  ├── peer (remote IP)                 ├── relationship (FK → Relationship)
+  ├── source (local IP)                ├── peering_network (FK → PeeringNetwork)
+  ├── remote_as / local_as             └── service_reference
+  ├── peer_group (BGPPeerTemplate)
+  ├── bfd (BFDProfile)               Relationship
+  ├── address_families[]               ├── name, slug, color
+  └── enabled, status, ttl
+                                     PeerASN (1:1 → ipam.ASN)
+PrefixList ◄─────────────────────────  ├── affiliated, irr_as_set
+  ├── name, family                     ├── max prefixes (v4/v6)
+  └── entries[]                        └── peeringdb_id
+
+                                     IRRPrefixListConfig (1:1 → PrefixList)
+                                       ├── irr_source (FK → IRRSource)
+                                       ├── source_as_set
+                                       └── sync_interval
+
+                                     IRRSource
+                                       ├── name, url, sources
+                                       └── enabled, sync_interval
+
+                                     PeeringFabric / PeeringNetwork / PeeringConnection
+                                       └── IX infrastructure models
+```
+
+## External Dependencies
+
+### IRR Prefix List Synchronization (fastbgpq4)
+
+The plugin supports automatic prefix list synchronization from Internet Routing Registry (IRR) databases. This feature requires [fastbgpq4](https://github.com/jsenecal/fastbgpq4), a separate REST API service that wraps [bgpq4](https://github.com/bgp/bgpq4) for querying IRR databases like RADB, RIPE, ARIN, etc.
+
+**Why a separate service?**
+
+bgpq4 is a command-line tool, not a library. fastbgpq4 provides a REST API interface that allows netbox-peering-manager to query IRR data without requiring bgpq4 to be installed on the NetBox server itself. This also enables caching, async queries for large AS-SETs, and centralized IRR query infrastructure.
+
+**Setup:**
+
+1. Deploy fastbgpq4 (see [fastbgpq4 documentation](https://github.com/jsenecal/fastbgpq4) for installation options including Docker)
+
+2. In NetBox, create an IRR Source under *Peering Manager > IRR Sources* with:
+   - **Name**: A descriptive name (e.g., "RADB via fastbgpq4")
+   - **URL**: The fastbgpq4 API base URL (e.g., `http://fastbgpq4:8000`)
+   - **Sources** (optional): Comma-separated IRR sources to query (e.g., `RADB,RIPE,ARIN`)
+   - **Cache TTL** (optional): Cache duration for query results
+
+3. Create an IRR Prefix List Config linking a netbox-routing Prefix List to the IRR Source:
+   - **Prefix List**: Select a netbox-routing prefix list
+   - **IRR Source**: Select your configured IRR source
+   - **Source AS-SET**: The AS-SET to query (e.g., `AS-HURRICANE`)
+
+4. Use the sync action to populate the prefix list entries from IRR data
+
+**Background Jobs:**
+
+IRR synchronization runs as NetBox background jobs via the RQ worker:
+- **Sync Prefix List from IRR** — Syncs a single prefix list
+- **Sync All Prefix Lists from IRR** — Syncs all prefix lists associated with an IRR source
+
+Ensure the NetBox RQ worker is running (`make rqworker` in development, or your production worker service).
+
+## Configuration Templating
+
+netbox-peering-manager provides a configuration rendering service that builds Jinja2 template context from your BGP data. It uses NetBox's built-in `ConfigTemplate` model for template storage.
+
+### Template Context Variables
+
+The `ConfigRenderer` service provides the following context:
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `device` | dict | Device info: `name`, `platform.name`, `platform.slug`, `site.name`, `site.slug` |
+| `sessions` | list[dict] | Peering sessions (see below) |
+| `peer_groups` | list[dict] | Deduplicated peer groups: `id`, `name` |
+| `route_maps` | list[dict] | Deduplicated route maps: `id`, `name` |
+| `prefix_lists` | list[dict] | Reserved for future use |
+| `communities` | list[dict] | Reserved for future use |
+
+### Session Context
+
+Each session in `sessions` contains:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | str | BGP peer name |
+| `description` | str | Peer description |
+| `enabled` | bool | Whether the peer is enabled |
+| `status` | str | Peer status |
+| `local_asn` | int | Local AS number |
+| `peer_asn` | int | Remote AS number |
+| `local_ip` | str | Local IP address |
+| `remote_ip` | str | Remote IP address |
+| `password` | str | MD5 authentication password |
+| `ttl` | int | TTL / multihop value |
+| `relationship` | str | Relationship type name |
+| `service_reference` | str | Service ticket reference |
+| `peer_name` | str | PeerASN name (if exists) |
+| `irr_as_set` | str | IRR AS-SET from PeerASN |
+| `ipv4_max_prefixes` | int | Max IPv4 prefixes from PeerASN |
+| `ipv6_max_prefixes` | int | Max IPv6 prefixes from PeerASN |
+| `bfd_profile` | dict | BFD config: `name`, `minimum_interval`, `minimum_rx_interval`, `multiplier`, `hold` |
+| `peer_group` | dict | Peer group: `id`, `name` |
+| `peering_network` | dict | IX network: `id`, `name`, `fabric` |
+| `afi_safis` | list[str] | Address families (e.g., `["ipv4-unicast"]`) |
+| `address_families` | list[dict] | Per-AFI config with `route_map_in`, `route_map_out`, `prefix_list_in`, `prefix_list_out` |
+
+### Custom Jinja2 Filters
+
+The plugin registers custom Jinja2 filters for use in templates:
+
+| Filter | Description |
+|--------|-------------|
+| `as_path_regex` | Convert AS path to regex pattern |
+| `ip_network` | Parse IP network string |
+| `group_by` | Group objects by attribute |
+| `to_community_list` | Format community list entries |
+| `to_prefix_set` | Format prefix set entries |
+
+### Example Templates
+
+Example templates are provided in [`docs/examples/templates/`](docs/examples/templates/) for:
+- **Juniper Junos** (`junos-bgp.j2`)
+- **Cisco IOS-XR** (`ios-xr-bgp.j2`)
+- **Arista EOS** (`eos-bgp.j2`)
+- **Nokia SR OS** (`nokia-sros-bgp.j2`)
+
+### API Endpoint
+
+Render configuration via the REST API:
+
+```
+POST /api/plugins/bgp/render-config/
+```
+
+## Development
+
+This plugin uses a VS Code devcontainer for development. The devcontainer provides a complete NetBox environment with both netbox-routing and netbox-peering-manager installed in editable mode.
+
+### Prerequisites
+
+- [Docker](https://www.docker.com/get-started)
+- [Visual Studio Code](https://code.visualstudio.com/)
+- [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+
+### Getting Started
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/jsenecal/netbox-peering-manager.git
+   cd netbox-peering-manager
+   ```
+
+2. Open the project in VS Code:
+   ```bash
+   code .
+   ```
+
+3. When prompted, click "Reopen in Container" or run the command "Dev Containers: Reopen in Container" from the Command Palette (F1)
+
+4. Wait for the container to build and start. This may take a few minutes on the first run.
+
+5. Once the container is ready, NetBox will be accessible at `http://localhost:8001`
+   - Username: `admin`
+   - Password: `admin`
+
+### Development Workflow
+
+Both netbox-routing and netbox-peering-manager are installed in editable mode (`pip install -e`), so changes to the code will be reflected immediately. You may need to restart the NetBox service for some changes.
+
+#### Using Make Commands
+
+The project includes a Makefile with convenient targets for common development tasks:
+
+```bash
+# Show all available make targets with descriptions
+make help
+
+# Quick Start / Composite Commands
+make all              # Full setup: install, migrate, collect static, load demo data
+make rebuild          # Rebuild: reinstall plugin, run migrations, collect static
+make setup            # Install/reinstall the plugin in editable mode
+
+# Development Server & Shells
+make runserver        # Start NetBox development server on port 8001
+make shell            # Open Django shell
+make nbshell          # Open NetBox shell (with NetBox utilities)
+make dbshell          # Open database shell
+
+# Database Migrations
+make makemigrations   # Create new migrations for the plugin
+make migrate          # Apply database migrations
+make showmigrations   # Show migration status
+
+# Testing & Code Quality
+make test             # Run plugin tests (includes migration check)
+make test-verbose     # Run tests with verbose output
+make lint             # Run ruff linting checks
+make format           # Auto-format code with ruff
+make fix              # Run ruff with --fix for auto-fixes
+
+# NetBox Utilities
+make trace_paths      # Run NetBox trace_paths utility
+make collectstatic    # Collect static files
+make createsuperuser  # Create a superuser account
+make rqworker         # Start RQ worker for background tasks
+
+# Demo Data (NetBox Initializers)
+make initializers            # Setup and load demo data
+make example_initializers    # Copy example initializers to .devcontainer
+make load_initializers       # Load initializer data from .devcontainer/initializers
+
+# Maintenance
+make clean            # Clean build artifacts
+make reinstall        # Alias for setup
+```
+
+#### Manual Commands
+
+You can also run Django management commands directly:
+
+```bash
+# From within the devcontainer terminal
+cd /opt/netbox/netbox
+python manage.py runserver 0.0.0.0:8001
+python manage.py test netbox_peering_manager
+python manage.py makemigrations netbox_peering_manager
+python manage.py migrate
+```
+
+## Upgrading from v0.1.x
+
+v0.2.0 is a **breaking change**. All BGP routing models (BGPSession, BGPPeerGroup, BFD, RoutingPolicy, PrefixList, Community, ASPathList, and their rule models) have been removed in favor of netbox-routing.
+
+**Migration steps:**
+
+1. Install netbox-routing and run its migrations
+2. Migrate your data from the old plugin tables to netbox-routing models
+3. Update `PLUGINS` configuration to include both `netbox_routing` and `netbox_peering_manager`
+4. Upgrade netbox-peering-manager to v0.2.0 and run migrations
+5. Update any configuration templates to use the new context variables (see [Configuration Templating](#configuration-templating))