diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 80810f2ba..54f4f7eae 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -14,7 +14,7 @@ body: attributes: label: NetBox version description: What version of NetBox are you currently running? - placeholder: v3.4.3 + placeholder: v3.4.7 validations: required: true - type: dropdown diff --git a/.github/ISSUE_TEMPLATE/feature_request.yaml b/.github/ISSUE_TEMPLATE/feature_request.yaml index 975fc025a..c9bc56ffc 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yaml +++ b/.github/ISSUE_TEMPLATE/feature_request.yaml @@ -14,7 +14,7 @@ body: attributes: label: NetBox version description: What version of NetBox are you currently running? - placeholder: v3.4.3 + placeholder: v3.4.7 validations: required: true - type: dropdown diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml index ab259af2a..3b37aae56 100644 --- a/.github/workflows/stale.yml +++ b/.github/workflows/stale.yml @@ -24,7 +24,7 @@ jobs: necessary. close-pr-message: > This PR has been automatically closed due to lack of activity. - days-before-stale: 60 + days-before-stale: 90 days-before-close: 30 exempt-issue-labels: 'status: accepted,status: blocked,status: needs milestone' operations-per-run: 100 diff --git a/README.md b/README.md index f44ce725f..e3c9611c0 100644 --- a/README.md +++ b/README.md @@ -1,107 +1,73 @@
NetBox logo + + The premiere source of truth powering network automation
+![Master branch build status](https://github.com/netbox-community/netbox/workflows/CI/badge.svg?branch=master) + NetBox is the leading solution for modeling and documenting modern networks. By combining the traditional disciplines of IP address management (IPAM) and datacenter infrastructure management (DCIM) with powerful APIs and extensions, NetBox provides the ideal "source of truth" to power network automation. -Available as open source software under the Apache 2.0 license, NetBox is -employed by thousands of organizations around the world. +Available as open source software under the Apache 2.0 license, NetBox serves +as the cornerstone for network automation in thousands of organizations. -![Master branch build status](https://github.com/netbox-community/netbox/workflows/CI/badge.svg?branch=master) - -[![Timeline graph](https://images.repography.com/29023055/netbox-community/netbox/recent-activity/31db894eee74b8a5475e3af307a81b6c_timeline.svg)](https://github.com/netbox-community/netbox/commits) -[![Issue status graph](https://images.repography.com/29023055/netbox-community/netbox/recent-activity/31db894eee74b8a5475e3af307a81b6c_issues.svg)](https://github.com/netbox-community/netbox/issues) -[![Pull request status graph](https://images.repography.com/29023055/netbox-community/netbox/recent-activity/31db894eee74b8a5475e3af307a81b6c_prs.svg)](https://github.com/netbox-community/netbox/pulls) -[![Top contributors](https://images.repography.com/29023055/netbox-community/netbox/recent-activity/31db894eee74b8a5475e3af307a81b6c_users.svg)](https://github.com/netbox-community/netbox/graphs/contributors) -
Stats via [Repography](https://repography.com) - -## About NetBox +* **Physical infrastructure:** Accurately model the physical world, from global regions down to individual racks of gear. Then connect everything - network, console, and power! +* **Modern IPAM:** All the standard IPAM functionality you expect, plus VRF import/export tracking, VLAN management, and overlay support. +* **Data circuits:** Confidently manage the delivery of critical circuits from various service providers, modeled seamlessly alongside your own infrastructure. +* **Power tracking:** Map the distribution of power from upstream sources to individual feeds and outlets. +* **Organization:** Manage tenant and contact assignments natively. +* **Powerful search:** Easily find anything you need using a single global search function. +* **Comprehensive logging:** Leverage both automatic change logging and user-submitted journal entries to track your network's growth over time. +* **Endless customization:** Custom fields, custom links, tags, export templates, custom validation, reports, scripts, and more! +* **Flexible permissions:** An advanced permissions systems enables very flexible delegation of permissions. +* **Integrations:** Easily connect NetBox to your other tooling via its REST & GraphQL APIs. +* **Plugins:** Not finding what you need in the core application? Try one of many community plugins - or build your own! ![Screenshot of NetBox UI](docs/media/screenshots/netbox-ui.png "NetBox UI") -Myriad infrastructure components can be modeled in NetBox, including: +## Getting Started -* Hierarchical regions, site groups, sites, and locations -* Racks, devices, and device components -* Cables and wireless connections -* Power distribution -* Data circuits and providers -* Virtual machines and clusters -* IP prefixes, ranges, and addresses -* VRFs and route targets -* L2VPN and overlays -* FHRP groups (VRRP, HSRP, etc.) -* AS numbers -* VLANs and scoped VLAN groups -* Organizational tenants and contacts +* Just want to explore? Check out [our public demo](https://demo.netbox.dev/) right now! +* The [official documentation](https://docs.netbox.dev) offers a comprehensive introduction. +* Choose your deployment: [self-hosted](https://github.com/netbox-community/netbox), [Docker](https://github.com/netbox-community/netbox-docker), or [NetBox Cloud](https://netboxlabs.com/netbox-cloud/). +* Check out [our wiki](https://github.com/netbox-community/netbox/wiki/Community-Contributions) for even more projects to get the most out of NetBox! -In addition to its extensive built-in models and functionality, NetBox can be -customized and extended through the use of: +## Get Involved -* Custom fields -* Custom links -* Configuration contexts -* Custom model validation rules -* Reports -* Custom scripts -* Export templates -* Conditional webhooks -* Plugins -* Single sign-on (SSO) authentication -* NAPALM integration -* Detailed change logging +* Follow [@NetBoxOfficial](https://twitter.com/NetBoxOfficial) on Twitter! +* Join the conversation on [the discussion forum](https://github.com/netbox-community/netbox/discussions) and [Slack](https://netdev.chat/)! +* Already a power user? You can [suggest a feature](https://github.com/netbox-community/netbox/issues/new?assignees=&labels=type%3A+feature&template=feature_request.yaml) or [report a bug](https://github.com/netbox-community/netbox/issues/new?assignees=&labels=type%3A+bug&template=bug_report.yaml) on GitHub. +* Contributions from the community are encouraged and appreciated! Check out our [contributing guide](CONTRIBUTING.md) to get started. -NetBox also features a complete REST API as well as a GraphQL API for easily -integrating with other tools and systems. - -The complete documentation for NetBox can be found at [docs.netbox.dev](https://docs.netbox.dev/). -A public demo instance is available at [demo.netbox.dev](https://demo.netbox.dev). - -NetBox runs as a web application atop the [Django](https://www.djangoproject.com/) -Python framework with a [PostgreSQL](https://www.postgresql.org/) database. For a -complete list of requirements, see `requirements.txt`. The code is available -[on GitHub](https://github.com/netbox-community/netbox). +## Project Stats
-

Thank you to our sponsors!

+ Timeline graph + Issues graph + Pull requests graph + Top contributors +
Stats via Repography +
+## Sponsors + +
+ + [![NetBox Labs](https://raw.githubusercontent.com/wiki/netbox-community/netbox/images/sponsors/netbox_labs.png)](https://netboxlabs.com) +            [![DigitalOcean](https://raw.githubusercontent.com/wiki/netbox-community/netbox/images/sponsors/digitalocean.png)](https://try.digitalocean.com/developer-cloud)            - [![Equinix Metal](https://raw.githubusercontent.com/wiki/netbox-community/netbox/images/sponsors/equinix.png)](https://metal.equinix.com/) -            - [![NS1](https://raw.githubusercontent.com/wiki/netbox-community/netbox/images/sponsors/ns1.png)](https://ns1.com/) + [![NS1](https://raw.githubusercontent.com/wiki/netbox-community/netbox/images/sponsors/ns1.png)](https://ns1.com)
- [![Sentry](https://raw.githubusercontent.com/wiki/netbox-community/netbox/images/sponsors/sentry.png)](https://sentry.io/) + [![Sentry](https://raw.githubusercontent.com/wiki/netbox-community/netbox/images/sponsors/sentry.png)](https://sentry.io)            - [![Stellar Technologies](https://raw.githubusercontent.com/wiki/netbox-community/netbox/images/sponsors/stellar.png)](https://stellar.tech/) + [![Equinix Metal](https://raw.githubusercontent.com/wiki/netbox-community/netbox/images/sponsors/equinix.png)](https://metal.equinix.com)
-### Discussion - -* [GitHub Discussions](https://github.com/netbox-community/netbox/discussions) - Discussion forum hosted by GitHub; ideal for Q&A and other structured discussions -* [Slack](https://netdev.chat/) - Real-time chat hosted by the NetDev Community; best for unstructured discussion or just hanging out - -### Installation - -Please see [the documentation](https://docs.netbox.dev/) for -instructions on installing NetBox. To upgrade NetBox, please download the -[latest release](https://github.com/netbox-community/netbox/releases) and -run `upgrade.sh`. - -### Providing Feedback - -The best platform for general feedback, assistance, and other discussion is our -[GitHub discussions](https://github.com/netbox-community/netbox/discussions). -To report a bug or request a specific feature, please open a GitHub issue using -the [appropriate template](https://github.com/netbox-community/netbox/issues/new/choose). - -If you are interested in contributing to the development of NetBox, please read -our [contributing guide](CONTRIBUTING.md) prior to beginning any work. - -### Screenshots +## Screenshots ![Screenshot of main page (dark mode)](docs/media/screenshots/home-dark.png "Main page (dark mode)") @@ -110,8 +76,3 @@ our [contributing guide](CONTRIBUTING.md) prior to beginning any work. ![Screenshot of prefixes hierarchy](docs/media/screenshots/prefixes-list.png "Prefixes hierarchy") ![Screenshot of cable trace](docs/media/screenshots/cable-trace.png "Cable tracing") - -### Related projects - -Please see [our wiki](https://github.com/netbox-community/netbox/wiki/Community-Contributions) -for a list of relevant community projects. diff --git a/SECURITY.md b/SECURITY.md index b389dd2b3..c434b6110 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -24,7 +24,7 @@ If you believe you've uncovered a security vulnerability and wish to report it c Please note that we **DO NOT** accept reports generated by automated tooling which merely suggest that a file or file(s) _may_ be vulnerable under certain conditions, as these are most often innocuous. -If you believe that you've found a vulnerability which meets all of these conditions, please email a brief description of the suspected bug and instructions for reproduction to **security@netbox.dev**. For any security concerns regarding NetBox deployed via Docker, please see the [netbox-docker](https://github.com/netbox-community/netbox-docker) project. +If you believe that you've found a vulnerability which meets all of these conditions, please [submit a draft security advisory](https://github.com/netbox-community/netbox/security/advisories/new) on GitHub, or email a brief description of the suspected bug and instructions for reproduction to **security@netbox.dev**. For any security concerns regarding NetBox deployed via Docker, please see the [netbox-docker](https://github.com/netbox-community/netbox-docker) project. ### Bug Bounties diff --git a/base_requirements.txt b/base_requirements.txt index 3e4811ece..f3303e6e3 100644 --- a/base_requirements.txt +++ b/base_requirements.txt @@ -1,6 +1,6 @@ # HTML sanitizer # https://github.com/mozilla/bleach -bleach +bleach<6.0 # The Python web framework on which NetBox is built # https://github.com/django/django @@ -121,7 +121,8 @@ social-auth-core # Django app for social-auth-core # https://github.com/python-social-auth/social-app-django -social-auth-app-django +# See https://github.com/python-social-auth/social-app-django/issues/429 +social-auth-app-django==5.0.0 # SVG image rendering (used for rack elevations) # https://github.com/mozman/svgwrite diff --git a/contrib/apache.conf b/contrib/apache.conf index 1804e380d..73fd45c26 100644 --- a/contrib/apache.conf +++ b/contrib/apache.conf @@ -1,3 +1,12 @@ + + # CHANGE THIS TO YOUR SERVER'S NAME + ServerName netbox.example.com + + RewriteEngine On + RewriteCond %{HTTPS} !=on + RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R,L] + + ProxyPreserveHost On diff --git a/docs/administration/housekeeping.md b/docs/administration/housekeeping.md index da1a5443b..fcc3aa04e 100644 --- a/docs/administration/housekeeping.md +++ b/docs/administration/housekeeping.md @@ -5,6 +5,7 @@ NetBox includes a `housekeeping` management command that should be run nightly. * Clearing expired authentication sessions from the database * Deleting changelog records older than the configured [retention time](../configuration/miscellaneous.md#changelog_retention) * Deleting job result records older than the configured [retention time](../configuration/miscellaneous.md#jobresult_retention) +* Check for new NetBox releases (if [`RELEASE_CHECK_URL`](../configuration/miscellaneous.md#release_check_url) is set) This command can be invoked directly, or by using the shell script provided at `/opt/netbox/contrib/netbox-housekeeping.sh`. This script can be linked from your cron scheduler's daily jobs directory (e.g. `/etc/cron.daily`) or referenced directly within the cron configuration file. diff --git a/docs/configuration/miscellaneous.md b/docs/configuration/miscellaneous.md index 4eb090554..8550564d8 100644 --- a/docs/configuration/miscellaneous.md +++ b/docs/configuration/miscellaneous.md @@ -69,6 +69,14 @@ By default, NetBox will permit users to create duplicate prefixes and IP address --- +## `FILE_UPLOAD_MAX_MEMORY_SIZE` + +Default: `2621440` (2.5 MB). + +The maximum amount (in bytes) of uploaded data that will be held in memory before being written to the filesystem. Changing this setting can be useful for example to be able to upload files bigger than 2.5MB to custom scripts for processing. + +--- + ## GRAPHQL_ENABLED !!! tip "Dynamic Configuration Parameter" diff --git a/docs/configuration/remote-authentication.md b/docs/configuration/remote-authentication.md index 07adf5c6a..1fda8d0d3 100644 --- a/docs/configuration/remote-authentication.md +++ b/docs/configuration/remote-authentication.md @@ -16,7 +16,7 @@ If true, NetBox will automatically create local accounts for users authenticated Default: `'netbox.authentication.RemoteUserBackend'` -This is the Python path to the custom [Django authentication backend](https://docs.djangoproject.com/en/stable/topics/auth/customizing/) to use for external user authentication. NetBox provides two built-in backends (listed below), though custom authentication backends may also be provided by other packages or plugins. +This is the Python path to the custom [Django authentication backend](https://docs.djangoproject.com/en/stable/topics/auth/customizing/) to use for external user authentication. NetBox provides two built-in backends (listed below), though custom authentication backends may also be provided by other packages or plugins. Provide a string for a single backend, or an iterable for multiple backends, which will be attempted in the order given. * `netbox.authentication.RemoteUserBackend` * `netbox.authentication.LDAPBackend` diff --git a/docs/configuration/system.md b/docs/configuration/system.md index 7061274f1..a6abb8b73 100644 --- a/docs/configuration/system.md +++ b/docs/configuration/system.md @@ -38,7 +38,7 @@ In order to send email, NetBox needs an email server configured. The following i * `SERVER` - Hostname or IP address of the email server (use `localhost` if running locally) * `PORT` - TCP port to use for the connection (default: `25`) * `USERNAME` - Username with which to authenticate -* `PASSSWORD` - Password with which to authenticate +* `PASSWORD` - Password with which to authenticate * `USE_SSL` - Use SSL when connecting to the server (default: `False`) * `USE_TLS` - Use TLS when connecting to the server (default: `False`) * `SSL_CERTFILE` - Path to the PEM-formatted SSL certificate file (optional) diff --git a/docs/customization/custom-scripts.md b/docs/customization/custom-scripts.md index 456bcf472..ccbe50885 100644 --- a/docs/customization/custom-scripts.md +++ b/docs/customization/custom-scripts.md @@ -79,7 +79,22 @@ A human-friendly description of what your script does. ### `field_order` -By default, script variables will be ordered in the form as they are defined in the script. `field_order` may be defined as an iterable of field names to determine the order in which variables are rendered. Any fields not included in this iterable be listed last. +By default, script variables will be ordered in the form as they are defined in the script. `field_order` may be defined as an iterable of field names to determine the order in which variables are rendered within a default "Script Data" group. Any fields not included in this iterable be listed last. If `fieldsets` is defined, `field_order` will be ignored. A fieldset group for "Script Execution Parameters" will be added to the end of the form by default for the user. + +### `fieldsets` + +`fieldsets` may be defined as an iterable of field groups and their field names to determine the order in which variables are group and rendered. Any fields not included in this iterable will not be displayed in the form. If `fieldsets` is defined, `field_order` will be ignored. A fieldset group for "Script Execution Parameters" will be added to the end of the fieldsets by default for the user. + +An example fieldset definition is provided below: + +```python +class MyScript(Script): + class Meta: + fieldsets = ( + ('First group', ('field1', 'field2', 'field3')), + ('Second group', ('field4', 'field5')), + ) +``` ### `commit_default` @@ -142,6 +157,19 @@ obj.full_clean() obj.save() ``` +## Error handling + +Sometimes things go wrong and a script will run into an `Exception`. If that happens and an uncaught exception is raised by the custom script, the execution is aborted and a full stack trace is reported. + +Although this is helpful for debugging, in some situations it might be required to cleanly abort the execution of a custom script (e.g. because of invalid input data) and thereby make sure no changes are performed on the database. In this case the script can throw an `AbortScript` exception, which will prevent the stack trace from being reported, but still terminating the script's execution and reporting a given error message. + +```python +from utilities.exceptions import AbortScript + +if some_error: + raise AbortScript("Some meaningful error message") +``` + ## Variable Reference ### Default Options @@ -289,7 +317,7 @@ Optionally `schedule_at` can be passed in the form data with a datetime string t Scripts can be run on the CLI by invoking the management command: ``` -python3 manage.py runscript [--commit] [--loglevel {debug,info,warning,error,critical}] [--data ""] .