nautobot 2.0.4__py3-none-any.whl → 2.1.0b1__py3-none-any.whl

nautobot/docs/user-guide/administration/guides/s3-django-storage.md

@@ -1,145 +0,0 @@
-# AWS S3 using Django-Storage Backend
-
-The backend storage engine is used for Nautobot to handle uploaded files (e.g. image attachments), as well as static files (e.g. css, js). Nautobot supports integration with the django-storages package, which provides backends for several popular file storage services. If not configured, local filesystem storage will be used; however this user-guide will demonstrate how to use AWS S3 buckets to store these files.
-
-## Installation
-
-Nautobot can use [`django-storages`](https://django-storages.readthedocs.io/en/stable/) to publish files to S3 -- see the [installation docs](../installation/nautobot.md#remote-file-storage) for more information on installing this optional dependency.
-
-TLDR:
-
-```shell
-$ echo "nautobot[remote_storage]" >> $NAUTOBOT_ROOT/local_requirements.txt
-$ pip3 install "nautobot[remote_storage]"
-```
-
-## Bucket Creation Terraform
-
-The AWS S3 bucket will be hosting Nautobot static files and needs some specific configuration to allow anonymous HTTP access.  The following is an example of Terraform configuration to create the S3 bucket appropriately, the same values can be configured manually:
-
-```terraform
-resource "aws_s3_bucket" "nautobot_static_files" {
-  bucket        = "my-bucket-name"
-  acl           = "public-read"
-
-  cors_rule {
-    allowed_headers = ["*"]
-    allowed_methods = ["GET"]
-    allowed_origins = ["http*"]
-  }
-  cors_rule {
-    allowed_methods = ["GET", "HEAD"]
-    allowed_origins = ["*"]
-  }
-
-  tags = {
-    Name = "Nautobot Static Files"
-  }
-}
-```
-
-## Configuration
-
-The [`django-storages`](https://django-storages.readthedocs.io/en/stable/) library is quite powerful, please refer to their documentation for a more detailed explanation of the individual settings or for more information.
-
-In `nautobot_config.py` define the following configuration:
-
-```python
-STORAGE_BACKEND = "storages.backends.s3boto3.S3Boto3Storage"
-
-STORAGE_CONFIG = {
-    "AWS_ACCESS_KEY_ID": "...",
-    "AWS_SECRET_ACCESS_KEY": "...",
-    "AWS_STORAGE_BUCKET_NAME": "my-bucket-name",
-    "AWS_S3_REGION_NAME": "us-west-1",
-    "AWS_DEFAULT_ACL": "public-read",
-    "AWS_QUERYSTRING_AUTH": False,
-    "AWS_LOCATION": "subfolder/name/static/"
-}
-STATICFILES_STORAGE = STORAGE_BACKEND
-```
-
-If `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` are not set, `boto3` [internally looks up IAM credentials](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html).  Using an [IAM Role for EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html?icmpid=docs_ec2_console) is highly recommended.
-
-The `STORAGE_CONFIG` has some valuable pieces of information.
-
-- Access Key and Secret Key are for authentication and authorization of the S3 bucket.
-- Storage bucket name is the S3 bucket name, within the bucket provided the aws location will be used to build the parent directory structure.
-    - In the example above the static files will be stored in `f"{AWS_STORAGE_BUCKET_NAME}.s3.amazonaws.com/{AWS_LOCATION}"`
-- Finally, region is where the s3 bucket resides.
-
-!!! info
-    The remaining options are not required, but django-storages documentation should be reviewed to understand the security requirements.
-
-By using the the settings listed above, the static files will be stored in the S3 bucket instead of on the Nautobot server's filesystem. Once the `nautobot-server collectstatic` is executed you will see the files.
-
-Here's a snippet from the S3 bucket in use.
-![initial s3](../../../media/user-guide/administration/guides/s3-django-storage/user-guide-s3-1.png)
-
-Now when an image is added to one of the core supported models like the `dcim.device-type`, a new directory will be created in the S3 bucket based on the `upload_to` attribute from the originating model. As an example we now see a new directory called `devicetype-images/`.
-
-![s3 with device types](../../../media/user-guide/administration/guides/s3-django-storage/user-guide-s3-2.png)
-
-The directory is defined in the `Devicetype` model on the front/rear images attributes. Source code snippet below:
-
-```python
-front_image = models.ImageField(upload_to="devicetype-images", blank=True)
-rear_image = models.ImageField(upload_to="devicetype-images", blank=True)
-```
-
-At a high level this takes care of everything you'd need for standard Nautobot deployment, but what if you're creating a plugin and you have a requirement for the data to be stored in an additional directory?
-
-This is where using the generic `FileField` provided by Django comes into play. For example, lets say a new plugin is being developed and storing the software images is one of the key requirements. The model might look something like the snippet below:
-
-```python
-class SoftwareFileAttachment(BaseModel):
-    """An uploaded software bin file for OS upgrades."""
-
-    file = models.FileField(upload_to="uploads/")
-    name = models.CharField(max_length=50, blank=True)
-    created = models.DateTimeField(auto_now_add=True)
-
-    def __str__(self):
-        """String value for HTML rendering."""
-        return f"{self.file}"
-```
-
-The `models.FileField` alongside the `upload_to` argument can be used to store user uploaded files into the already established S3 bucket. With the configuration settings provided earlier in this article and the `upload_to=uploads/` attribute the software attachments will be stored at `f"{AWS_STORAGE_BUCKET_NAME}.s3.amazonaws.com/{AWS_LOCATION}/uploads/"`.
-
-The nice thing about using `django-storages` is the ease of use and the ability to easily extend storage backends. One use case for extending storage backends that has been used is to store certain plugin data attachments in its own S3 bucket with different permissions. If we take this concept to the example of `SoftwareFileAttachment` we can put the software images in their own S3 bucket by creating a custom storage backend that we can pass to our `models.FileField` model field.
-
-For this example I created a simple python file called `customer_storage.py` in the root of my plugin.
-
-```python
-"""Example of a custom extension to support flexible s3 storage."""
-from storages.backends.s3boto3 import S3Boto3Storage
-
-class MediaStorage(S3Boto3Storage):
-    bucket_name = 'nautobot-sw-media'
-    location = "software_images" # store files under directory `software_images/` in bucket `nautobot-sw-media`
-```
-
-In the model you just need to pass in the `storage=` argument.
-
-```python
-from custom_config_plugin.custom_storage import MediaStorage
-
-class SoftwareFileAttachment(BaseModel):
-    """An uploaded software bin file for OS upgrades."""
-
-    file = models.FileField(upload_to="uploads/", storage=MediaStorage)
-    name = models.CharField(max_length=50, blank=True)
-    created = models.DateTimeField(auto_now_add=True)
-
-    def __str__(self):
-        """String value for HTML rendering."""
-        return f"{self.file}"
-```
-
-When a user uploads a new software image to this model it will be stored in `<AWS S3 URL>/software_images/uploads/<file>.bin`.
-
-This is valuable because you may have certain models in a plugin or other enhancements that need to have more specific granularity in the S3 bucket they belong in, also it may be crucial to have different S3 IAM requirements for certain files over the general static files the Nautobot application needs to run appropriately.
-
-## Summary
-
-Django-Storages is the backend library used to extend Nautobots backend storage flexibility. The same concepts above can be used for Azure Storage, Dropbox, GCP etc. As all of these have native support within the `django-storages` library.

nautobot/docs/user-guide/administration/installation/app-install.md

@@ -1,94 +0,0 @@
-# Installing Apps
-
-The instructions below detail the process for installing and enabling a Nautobot app.
-
-You must be **absolutely** sure to install the app within Nautobot's virtual environment.
-
-!!! note
-    If you installed Nautobot in a production environment, you'll want to sudo to the nautobot user first using `sudo -iu nautobot`.
-
-## Install the Package
-
-Download and install the app package per its installation instructions. Apps published via PyPI are typically installed using `pip3`.
-
-```no-highlight
-pip3 install <package>
-```
-
-Alternatively, if you're or installing a app from from a local source copy, you may wish to install the app manually by running `python setup.py install`.
-
-If you are developing a app and want to install it only temporarily, run `python setup.py develop` instead.
-
-## Enable the App
-
-In your `nautobot_config.py`, add the app's name to the `PLUGINS` list:
-
-```python
-PLUGINS = [
-    'app_name',
-]
-```
-
-## Configure the App
-
-If the app requires any configuration, define it in `nautobot_config.py` under the `PLUGINS_CONFIG` parameter. The available configuration parameters should be detailed in the app's README file.
-
-```python
-PLUGINS_CONFIG = {
-    'app_name': {
-        'foo': 'bar',
-        'buzz': 'bazz'
-    }
-}
-```
-
-## Run `nautobot-server post_upgrade`
-
-After installing or upgrading a app, you should always run [`nautobot-server post_upgrade`](../tools/nautobot-server.md#post_upgrade). This command will ensure that any necessary post-installation tasks are run, for example:
-
-* Migrating the database to include any new or updated data models from the app
-* Collecting any static files provided by the app
-* Etc.
-
-```no-highlight
-# nautobot-server post_upgrade
-Performing database migrations...
-Operations to perform:
-  Apply all migrations: admin, auth, circuits, contenttypes, db, dcim, extras, ipam,
-nautobot_app_example, sessions, social_django, taggit, tenancy, users, virtualization
-Running migrations:
-  No migrations to apply.
-
-Generating cable paths...
-Found no missing circuit termination paths; skipping
-Found no missing console port paths; skipping
-Found no missing console server port paths; skipping
-Found no missing interface paths; skipping
-Found no missing power feed paths; skipping
-Found no missing power outlet paths; skipping
-Found no missing power port paths; skipping
-Finished.
-
-Collecting static files...
-
-0 static files copied to '/opt/nautobot/static', 972 unmodified.
-
-Removing stale content types...
-
-Removing expired sessions...
-
-Invalidating cache...
-
-```
-
-## Restart the WSGI Service
-
-Restart the WSGI service to load the new app:
-
-```no-highlight
-# sudo systemctl restart nautobot nautobot-worker
-```
-
-## Verify that the App is Installed
-
-In the Nautobot UI, navigate to **Apps -> Installed Apps**. The newly installed app should appear in the displayed table if everything is configured correctly. You can also click on the app's name in this table to view more detailed information about this app.

nautobot/docs/user-guide/administration/installation/docker.md

@@ -1,286 +0,0 @@
-# Nautobot Docker Images
-
-Nautobot is packaged as a Docker image for use in a production environment; developer images are also provided for those working on App development and testing. The Docker image and deployment strategies are being actively developed, check back here or join the **#nautobot** channel on [Network to Code's Slack community](https://slack.networktocode.com/) for the most up to date information.
-
-## Python Versions
-
-Docker images are published for multiple supported Python versions. The default image, recommended for most users, is based on the `python:3.11-slim` image.
-
-+/- 1.6.1
-    The Python version for the image tags that do not explicitly state a Python version changed to 3.11 for Nautobot 1.6.1. From now on, these tagged images will always contain the **latest** supported Python version (e.g., when Python 3.12 support is added, these tags will change to contain Python 3.12). This is a change from Nautobot 1.6.0 and earlier, where tags that did not state a Python version would contain the **earliest** supported Python version.
-
-Currently images are pushed for the following python versions:
-
-* 3.8
-* 3.9
-* 3.10
-* 3.11
-
-+++ 1.6.0
-    Python 3.11 was added to the set of published images.
-
---- 1.6.0
-    Python 3.7 was removed from the set of published images as Python 3.7 is now end-of-life.
-
-## Platforms
-
-Nautobot docker images are currently provided for both `linux/amd64` and `linux/arm64` architectures. Please note ARM64 support is untested by our automated tests and should be considered in an alpha state.
-
-## Tags
-
-### Production Tags
-
-A set of production-ready Docker images are built for each Nautobot release and published to both [Docker Hub](https://hub.docker.com/r/networktocode/nautobot/) and the [GitHub Container Registry](https://github.com/nautobot/nautobot/pkgs/container/nautobot).
-
-To get a specific tagged image from Docker Hub or the GitHub Container Registry run:
-
-```no-highlight
-docker image pull networktocode/nautobot:${TAG}
-```
-
-or
-
-```no-highlight
-docker pull ghcr.io/nautobot/nautobot:${TAG}
-```
-
-The following tags are available on both Docker Hub and the GitHub Container Registry:
-
-| Tag                                                           | Nautobot Version      | Python Version | Example        |
-| ------------------------------------------------------------- | --------------------- | -------------- | -------------- |
-| `${NAUTOBOT_VER}`                                             | As specified          | 3.11           | `2.0.0`        |
-| `${NAUTOBOT_VER}-py${PYTHON_VER}`                             | As specified          | As specified   | `2.0.0-py3.8`  |
-| `${NAUTOBOT_MAJOR_VER}.${NAUTOBOT_MINOR_VER}`                 | As specified          | 3.11           | `2.0`          |
-| `${NAUTOBOT_MAJOR_VER}.${NAUTOBOT_MINOR_VER}-py${PYTHON_VER}` | As specified          | As specified   | `2.0-py3.8`    |
-| `stable`                                                      | Latest stable release | 3.11           | `stable`       |
-| `stable-py${PYTHON_VER}`                                      | Latest stable release | As specified   | `stable-py3.8` |
-
-### Developer Tags
-
-Additionally, GitHub Actions are used to automatically build "developer" images corresponding to each commit to the `ltm-1.6`, `develop`, and `next` branches. These images are named `networktocode/nautobot-dev:${TAG}` and `ghcr.io/nautobot/nautobot-dev:${TAG}`, and provide the development dependencies needed to build Nautobot; they can be used as a base for development to develop your own Nautobot apps but should **NOT** be used in production.
-
-In addition to all tags described in the previous section, the following additional tags are available from the GitHub Container Registry, only for the `ghcr.io/nautobot/nautobot-dev` images:
-
-| Tag                                                  | Nautobot Branch              | Python Version |
-| ---------------------------------------------------- | ---------------------------- | -------------- |
-| `latest`                                             | `develop`, the latest commit | 3.11           |
-| `latest-py${PYTHON_VER}`                             | `develop`, the latest commit | As specified   |
-| `develop`                                            | `develop`, the latest commit | 3.11           |
-| `develop-py${PYTHON_VER}`                            | `develop`, the latest commit | As specified   |
-| `ltm-1.6`                                            | `ltm-1.6`, the latest commit | 3.11           |
-| `ltm-1.6-py${PYTHON_VER}`                            | `ltm-1.6`, the latest commit | As specified   |
-| `next`                                               | `next`, the latest commit    | 3.11           |
-| `next-py${PYTHON_VER}`                               | `next`, the latest commit    | As specified   |
-
-## Getting Started
-
-Nautobot requires a MySQL or PostgreSQL database and Redis instance before it will start. Because of this the quickest and easiest way to get Nautobot running is with [Docker Compose](https://docs.docker.com/compose/), which will install and configure PostgreSQL and Redis containers for you automatically.
-
-## Configuration
-
-Most configuration parameters are available via environment variables which can be passed to the container. If you desire you can inject your own `nautobot_config.py` by overriding `/opt/nautobot/nautobot_config.py` using [docker volumes](https://docs.docker.com/storage/volumes/) by adding `-v /local/path/to/custom/nautobot_config.py:/opt/nautobot/nautobot_config.py` to your docker run command, for example:
-
-```no-highlight
-docker run \
-    -v /local/path/to/custom/nautobot_config.py:/opt/nautobot/nautobot_config.py \
-    --name nautobot networktocode/nautobot
-```
-
-Or if you are using docker compose:
-
-```yaml
-services:
-  nautobot:
-    image: "networktocode/nautobot"
-    volumes:
-      - /local/path/to/custom/nautobot_config.py:/opt/nautobot/nautobot_config.py:ro
-```
-
-### Docker only configuration
-
-The entry point for the Docker container has some additional features that can be configured via additional environment variables. The following are all optional variables:
-
-#### `NAUTOBOT_CREATE_SUPERUSER`
-
-Default: unset
-
-Enables creation of a super user specified by [`NAUTOBOT_SUPERUSER_NAME`](#nautobot_superuser_name), [`NAUTOBOT_SUPERUSER_EMAIL`](#nautobot_superuser_email), [`NAUTOBOT_SUPERUSER_PASSWORD`](#nautobot_superuser_password), and [`NAUTOBOT_SUPERUSER_API_TOKEN`](#nautobot_superuser_api_token).
-
----
-
-#### `NAUTOBOT_DOCKER_SKIP_INIT`
-
-Default: unset
-
-When starting, the container attempts to connect to the database and run database migrations and upgrade steps necessary when upgrading versions. In normal operation this is harmless to run on every startup and validates the database is operating correctly. However, in certain circumstances such as database maintenance when the database is in a read-only mode it may make sense to start Nautobot but skip these steps. Setting this variable to `true` will start Nautobot without running these initial steps.
-
-!!! note
-    Setting this value to anything other than "false" (case-insensitive) will prevent migrations from occurring.
-
----
-
-#### `NAUTOBOT_SUPERUSER_API_TOKEN`
-
-Default: unset
-
-If [`NAUTOBOT_CREATE_SUPERUSER`](#nautobot_create_superuser) is true, `NAUTOBOT_SUPERUSER_API_TOKEN` specifies the API token of the super user to be created; alternatively the `/run/secrets/superuser_api_token` file contents are read for the token. Either the variable or the file is required if `NAUTOBOT_CREATE_SUPERUSER` is true.
-
----
-
-#### `NAUTOBOT_SUPERUSER_EMAIL`
-
-Default: `admin@example.com`
-
-If [`NAUTOBOT_CREATE_SUPERUSER`](#nautobot_create_superuser) is true, `NAUTOBOT_SUPERUSER_EMAIL` specifies the email address of the super user to be created.
-
----
-
-#### `NAUTOBOT_SUPERUSER_NAME`
-
-Default: `admin`
-
-If [`NAUTOBOT_CREATE_SUPERUSER`](#nautobot_create_superuser) is true, `NAUTOBOT_SUPERUSER_NAME` specifies the username of the super user to be created.
-
----
-
-#### `NAUTOBOT_SUPERUSER_PASSWORD`
-
-Default: unset
-
-If [`NAUTOBOT_CREATE_SUPERUSER`](#nautobot_create_superuser) is true, `NAUTOBOT_SUPERUSER_PASSWORD` specifies the password of the super user to be created; alternatively the `/run/secrets/superuser_password` file contents are read for the password. Either the variable or the file is required if `NAUTOBOT_CREATE_SUPERUSER` is true.
-
----
-
-### uWSGI
-
-The docker container uses [uWSGI](https://uwsgi-docs.readthedocs.io/) to serve Nautobot. A default configuration is [provided](https://github.com/nautobot/nautobot/blob/main/docker/uwsgi.ini), and can be overridden by injecting a new `uwsgi.ini` file at `/opt/nautobot/uwsgi.ini`. There are a couple of environment variables provided to override some uWSGI defaults:
-
-#### `NAUTOBOT_UWSGI_BUFFER_SIZE`
-
-+++ 1.3.9
-
-Default: `4096`
-
-Max: `65535`
-
-The max size of non-body request payload, roughly the size of request headers for uWSGI. Request headers that might contain lengthy query parameters, for example GraphQL or Relationship filtered lookups, might go well over the default limit. Increasing this limit will have an impact on running memory usage. Please see [the uWSGI documentation](https://uwsgi-docs.readthedocs.io/en/latest/Options.html?highlight=buffer-size#buffer-size) for more information.
-
-This can also be overridden by appending `-b DESIRED_BUFFER_SIZE`, ex: `-b 8192`, to the entry command in all Nautobot containers running uWSGI if you are on a release before `1.3.9`.
-
----
-
-#### `NAUTOBOT_UWSGI_LISTEN`
-
-Default: `128`
-
-The socket listen queue size of uWSGI. In production environments it is recommended to increase this value to 1024 or higher, however depending on your platform, this may require additional kernel parameter settings, please see [the uWSGI documentation](https://uwsgi-docs.readthedocs.io/en/latest/articles/TheArtOfGracefulReloading.html#the-listen-queue) for more information.
-
-Please see the [official uWSGI documentation on `listen`](https://uwsgi-docs.readthedocs.io/en/latest/Options.html?highlight=listen#listen) for more information.
-
----
-
-#### `NAUTOBOT_UWSGI_PROCESSES`
-
-Default: `3`
-
-The number of worker processes uWSGI will spawn.
-
-Please see the [official uWSGI documentation on `processes`](https://uwsgi-docs.readthedocs.io/en/latest/Options.html?highlight=processes#processes) for more information.
-
----
-
-### SSL
-
-Self signed SSL certificates are included by default with the container. For a production deployment you should utilize your own signed certificates, these can be injected into the container at runtime using [docker volumes](https://docs.docker.com/storage/volumes/). The public certificate should be placed at `/opt/nautobot/nautobot.crt` and the private key should be at `/opt/nautobot/nautobot.key`. Using a `docker run` these can be injected using the `-v` parameter:
-
-```no-highlight
-docker run \
-    -v /local/path/to/custom/nautobot.crt:/opt/nautobot/nautobot.crt \
-    -v /local/path/to/custom/nautobot.key:/opt/nautobot/nautobot.key \
-    --name nautobot networktocode/nautobot
-```
-
-Or if you are using `docker-compose`:
-
-```yaml
-services:
-  nautobot:
-    image: "networktocode/nautobot"
-    volumes:
-      - /local/path/to/custom/nautobot.crt:/opt/nautobot/nautobot.crt:ro
-      - /local/path/to/custom/nautobot.key:/opt/nautobot/nautobot.key:ro
-```
-
-### Nautobot Plugins
-
-At this time adding Nautobot plugins to the existing Docker image is not supported, however, you can use the Nautobot image as the base within your `Dockerfile` to install your own plugins, here is an example dockerfile:
-
-```dockerfile
-FROM networktocode/nautobot
-
-RUN pip install nautobot-chatops
-
-COPY nautobot_config.py /opt/nautobot/nautobot_config.py
-```
-
-## Building the Image
-
-If you have a [development environment](../../../development/core/getting-started.md#setting-up-your-development-environment) you can use `invoke` to build the Docker image. By default `invoke build` will build the `dev` image:
-
-```no-highlight
-invoke build
-```
-
-After some output and a prompt is returned:
-
-```no-highlight
-docker images
-```
-
-Example output:
-
-```no-highlight
-REPOSITORY                                       TAG                              IMAGE ID       CREATED          SIZE
-local/nautobot-dev                               local-py3.8                      0d93eec7dfea   5 minutes ago    1.31GB
-```
-
-If you need to build or test the `final` image, you must set your `invoke.yml` to use `docker-compose.final.yml` in place of `docker-compose.dev.yml`:
-
-```yaml
----
-nautobot:
-  compose_files:
-    - "docker-compose.yml"
-    - "docker-compose.postgres.yml"
-    - "docker-compose.final.yml"
-```
-
-Then you can re-run the `invoke build` command:
-
-```no-highlight
-invoke build
-```
-
-Example output:
-
-```no-highlight
-...
-```
-
-```no-highlight
-docker images
-
-```
-
-Example output:
-
-```no-highlight
-REPOSITORY                                       TAG                              IMAGE ID       CREATED          SIZE
-local/nautobot-final                             local-py3.8                      e03e752fcc6b   27 minutes ago   629MB
-```
-
-Similarly, you can use `docker-compose.final-dev.yml` if you wish to build and test the `final-dev` image.
-
-## Docker Compose
-
-An [example library for using Docker Compose](https://github.com/nautobot/nautobot-docker-compose/) to build out all of the components for Nautobot can be found within the Nautobot community. Please see [https://github.com/nautobot/nautobot-docker-compose/](https://github.com/nautobot/nautobot-docker-compose/) for examples on the base application, LDAP integration, and using plugins.

nautobot/docs/user-guide/administration/installation/external-authentication.md

@@ -1,9 +0,0 @@
-# External Authentication
-
-This guide explains how to implement authentication using an external server. User authentication will fall back to built-in Django users in the event of a failure.
-
-## Supported External Authentication Backends
-
-- [LDAP Authentication](../configuration/authentication/ldap.md)
-- [Remote User Authentication](../configuration/authentication/remote.md)
-- [SSO Authentication](../configuration/authentication/sso.md)