path: root/net-mgmt/netbox/files/pkg-message.in

[
{ type: install
  message: <<EOD
Please note that NetBox requires a PostgreSQL database server, which uses its
built-in network address datatypes. Thus NetBox won't work with other RDBMS's,
e.g. MySQL, MariaDB, etc.

For installation instructions please refer to the related wiki page:

- https://wiki.freebsd.org/Ports/net-mgmt/netbox
EOD
}
{ type: upgrade
  message: <<EOD
As always it is strongly encouraged to make a backup of the database before the
database migrations will be executed.

The following steps are required to finish the upgrade: 

1. Run database migrations, trace any missing cable paths, build the embedded
   documentation, collect static files, remove stale content files, delete any
   expired user sessions and clear the cache.

# cd %%DATADIR%%
# python%%PYTHON_VER%% manage.py migrate
# python%%PYTHON_VER%% manage.py trace_paths --no-input
# mkdocs build
# python%%PYTHON_VER%% manage.py collectstatic --no-input
# python%%PYTHON_VER%% manage.py remove_stale_contenttypes --no-input
# python%%PYTHON_VER%% manage.py reindex --lazy
# python%%PYTHON_VER%% manage.py clearsessions
# python%%PYTHON_VER%% manage.py clearcache

2. Restart WSGI/httpd environment (supervisord/apache/nginx/etc.)
EOD
}
{ type: upgrade
  maximum_version: 3.0.4
  message: <<EOD
/!\ WARNING /!\

The NetBox 3.0 release contains major changes, so at least items 1.), 2.) and
3.) must be checked before proceeding with the upgrade!

/!\ WARNING /!\

1. Please ensure that your local installation of net-mgmt/netbox is at
   the 2.11 release before attemping to upgrade to NetBox 3.0 or later.

2. Please also note that the previously deprecated secrets functionality has
   been removed with NetBox 3.0.  This means, all of the secrets still remain
   in the database once upgraded, only the secrets functionality on the part of
   NetBox is no longer given.

   In order to continue to be able to access the stored secrets as usual (and
   then possibly migrate them to another solution, e.g. security/vault), please
   install the security/py-netbox-secretstore port once NetBox has been
   upgraded to 3.x and follow its installation instructions how to enable the
   plugin.

3. If plugins are used, they should be temporarily deactivated to avoid
   disruptions during the upgrade process.

4. Following items should be checked as well:

   * The default CSV export format for all objects now includes all available
     data from the object list.  Additionally, the CSV headers now use human-
     friendly titles rather than raw field names.  If backward compatibility
     with the old format is desired, export templates can be written to
     reproduce it.

   * The "invalidate" management command (which clears cached database queries)
     is no longer needed and has been removed.

   * Support for queryset caching configuration (caching_config) has been
     removed from the plugins API.

   * The cacheops_* metrics have been removed from the Prometheus exporter.

   * The "display_field" keyword argument has been removed from custom script
     "ObjectVar" and "MultiObjectVar" fields.  These widgets will use the
     display value provided by the REST API.

   * The deprecated "display_name" field has been removed from all REST API
     serializers.  (API clients should reference the display field instead.)

   * The redundant REST API endpoints for console, power, and interface
     connections have been removed.  The same data can be retrieved by querying
     the respective model endpoints with the ?connected=True filter applied.

   * Several changes to the REST API were made as well.  Please check the
     changelogs for further details.

5. There's a new sample script for NetBox housekeeping tasks, which should run
   once a day.  If the EXAMPLES option is enabled (which is the default) it can
   be found in the following directory:

   %%EXAMPLESDIR%%/850.netbox-housekeeping.sample

   Please run following commands to enable the new script:

   # cp %%EXAMPLESDIR%%/850.netbox-housekeeping.sample %%LOCALBASE%%/etc/periodic/daily/850.netbox-housekeeping
   # chmod 555 %%LOCALBASE%%/etc/periodic/daily/850.netbox-housekeeping
   # sysrc -f /etc/periodic.conf daily_netbox_housekeeping_enable="YES"
EOD
}
{ type: upgrade
  maximum_version: 3.0.12_1
  message: <<EOD
Please run the following command to make the online help available that was
previously missing:

# cd %%DATADIR%%
# python%%PYTHON_VER%% manage.py collectstatic --no-input
EOD
}
{ type: upgrade
  maximum_version: 3.1.6
  message: <<EOD

1. Please make sure that the PostgreSQL server for the NetBox instance is
   running version 10 or higher.  This is because PostgreSQL 9.6 is End-of-Life
   since November 2021 and NetBox 3.1 makes use of the "macaddr8" field which
   was introduced with PostgreSQL 10.


2. Following items should be checked as well:

    * The tenant and tenant_id filters for the Cable model now filter on the
      tenant assigned directly to each cable, rather than on the parent object
      of either termination.

    * The cable_peer and cable_peer_type attributes of cable termination models
      have been renamed to link_peer and link_peer_type, respectively, to
      accommodate wireless links between interfaces.

    * Exported webhooks and custom fields now reference associated content
      types by raw string value (e.g. "dcim.site") rather than by
      human-friendly name.

    * The 128GFC interface type has been corrected from 128gfc-sfp28 to
      128gfc-qsfp28.

    * Several changes to the REST API were made as well.  Please check the
      changelogs for further details.
EOD
}
{ type: upgrade
  maximum_version: 3.2.4
  message: <<EOD
/!\ WARNING /!\

The NetBox 3.2 release contains major changes, so at least items 1.), 2.) and
3.) must be checked before proceeding with the upgrade!

/!\ WARNING /!\

1. This release includes a database migration that will remove the "asn",
   "contact_name", "contact_phone", and "contact_email" fields from the site
   model.  (These fields have been superseded by the ASN and contact models
   introduced in NetBox v3.1.)

   To protect against the accidental destruction of data, the upgrade process
   will fail if any sites still have data in any of these fields.  To bypass
   this safeguard, set the NETBOX_DELETE_LEGACY_DATA environment variable when
   running the upgrade script, which will permit the destruction of legacy
   data.

   A set of migration scripts is available to assist with the migration of
   legacy site data:

   https://github.com/netbox-community/migration-scripts


2. NetBox v3.2 requires Python 3.8 or later.


3. If the NetBox Plugin "net-mgmt/py-netbox-plugin-extension" is used, please
   disable it before the migrations are applied.  This can be done by removing
   the entry "netbox_plugin_extensions" from the "PLUGINS" section in the
   NetBox configuration.

   Once the upgrade is done, this port/package can be safely removed as it's no
   longer required.


4. Following items should be checked as well:

    * The embedded documentation now needs to be built locally as the procedure
      requires a running instance of NetBox:

      # cd %%DATADIR%%
      # mkdocs build

      Please also refer to the general updating instructions as this needs to
      be done with every future update of NetBox.

    * Automatic redirection of legacy slug-based URL paths has been removed.
      URL-based slugs were changed to use numeric IDs in v2.11.0.

    * The "asn" query filter for sites now matches against the AS number of
      assigned ASN objects.

    * The "created" field of all change-logged models now conveys a full
      datetime object, rather than only a date.  (Previous date-only values
      will receive a timestamp of 00:00.)  While this change is largely
      unconcerning, strictly-typed API consumers may need to be updated.

    * A "pre_run()" method has been added to the base Report class.  Although
      unlikely to affect most installations, you may need to alter any reports
      which already use this name for a method.

    * Webhook URLs now support Jinja2 templating.  Although this is unlikely to
      introduce any issues, it's possible that an unusual URL might trigger a
      Jinja2 rendering error, in which case the URL would need to be properly
      escaped.

    * Several changes to the REST API were made as well.  Please check the
      changelogs for further details.
EOD
}
{ type: upgrade
  maximum_version: 3.2.5
  message: <<EOD
Please note that the general update instructions got another command that needs
to be issued after each update:

# python%%PYTHON_VER%% manage.py clearcache
EOD
}
{ type: upgrade
  maximum_version: 3.3.4
  message: <<EOD
The NetBox 3.3 release contains some breaking API changes, so please check the
following items before running the database migrations:

* Device position, device type height, and rack unit values are now reported
  as decimals (e.g. 1.0 or 1.5) to support modeling half-height rack units.

* The "nat_outside" relation on the IP address model now returns a list of zero
  or more related IP addresses, rather than a single instance (or None).

* Several fields on the cable API serializers have been altered or removed to
  support multiple-object cable terminations:

+------------------------------+------+-------------------------------+------+
| Old Name                     | Type | New Name                      | Type |
+------------------------------+------+-------------------------------+------+
| termination_a_type           | str  | Removed                       | -    |
| termination_b_type           | str  | Removed                       | -    |
| termination_a_id             | int  | Removed                       | -    |
| termination_b_id             | int  | Removed                       | -    |
| termination_a                | obj  | a_terminations                | list |
| termination_b                | obj  | b_terminations                | list |
+------------------------------+------+-------------------------------+------+

* As with the cable model, several API fields on all objects to which cables
  can be connected (interfaces, circuit terminations, etc.) have been changed:

+------------------------------+------+-------------------------------+------+
| Old Name                     | Type | New Name                      | Type |
+------------------------------+------+-------------------------------+------+
| link_peer                    | obj  | link_peers                    | list |
| link_peer_type               | str  | link_peers_type               | str  |
| connected_endpoint           | obj  | connected_endpoints           | list |
| connected_endpoint_type      | str  | connected_endpoints_type      | str  |
| connected_endpoint_reachable | bool | connected_endpoints_reachable | bool |
+------------------------------+------+-------------------------------+------+

* The cable path serialization returned by the "/paths/" endpoint for
  pass-through ports has been simplified, and the following fields removed:

  "origin_type", "origin", "destination_type", "destination". (Additionally,
  "is_complete" has been added.)

* Several changes to the REST API were made as well.  Please check the
  changelogs for further details.

* The netbox sample rc script got a new "upgrade" directive that also
  simplifies the upgrade process (database migrations, building the embedded
  documentation, etc.).
EOD
}
{ type: upgrade
  maximum_version: 3.4.5
  message: <<EOD
1. Please make sure that the PostgreSQL server for the NetBox instance is
   running version 11 or higher.  This is because PostgreSQL 10 is End-of-Life
   since November 2022 and Django 4.1 requires PostgreSQL 11 as a minimum.

2. The NetBox 3.4 release contains some breaking changes, so the following
   items should be checked as well:

   * Device and virtual machine names are no longer case-sensitive.  Attempting
     to create e.g. "device1" and "DEVICE1" within the same site will raise a
     validation error.

   * The "asn", "noc_contact", "admin_contact", and "portal_url" fields have
     been removed from the provider model.  Please replicate any data remaining
     in these fields to the ASN and contact models introduced in NetBox v3.1
     prior to upgrading.

   * The "content_type" fields on the CustomLink and ExportTemplate models have
     been renamed to "content_types" and now support the assignment of multiple
     content types per object.

   * Within the Python API, the "cf" property on an object with custom fields
     now returns deserialized values.  For example, a custom field referencing
     an object will return the object instance rather than its numeric ID.

     To access the raw serialized values, reference the object's
     "custom_field_data" attribute instead.

   * The "NetBoxModelCSVForm" class has been renamed to
     "NetBoxModelImportForm".  Backward compatability with the previous name
     has been retained for this release, but will be dropped in NetBox v3.5.


3. Please note that the general update instructions got another command that
   needs to be issued after each update:

# python%%PYTHON_VER%% manage.py reindex --lazy

   The netbox sample rc script has also been adapted accordingly for this
   purpose.
EOD
}
{ type: upgrade
  maximum_version: 3.5.2
  message: <<EOD
1. If the plugin security/py-netbox-secretstore is used, which is no longer
   maintained by upstream, the following steps must be done before upgrading to
   NetBox 3.5:

   * Migrate from security/py-netbox-secretstore (= 1.4.2_2) to
     security/py-netbox-secrets (= 1.7.6) with a NetBox 3.4.x instance.

     It is very important that the versions of py-netbox-secretstore and
     py-netbox-secrets match as specified otherwise the migration will not
     be successful.

     The reason for this is that py-netbox-secrets 1.8.x is not backwards
     compatible with Netbox 3.4.  For further details please see the updating
     instructions of py-netbox-secretstore or the UPDATING entry of 2023-05-11.

2. The NetBox 3.5 release contains some breaking changes, so the following
   items should be checked as well:

   * The "account: field has been removed from the provider model.
     This information is now tracked using the new provider account model.
     Multiple accounts can be assigned per provider.

   * A minimum length of 50 characters is now enforced for the SECRET_KEY
     configuration parameter.

   * The JobResult model has been moved from the "extras" app to "core" and
     renamed to Job. Accordingly, its REST API endpoint has been moved from
     "/api/extras/job-results/" to "/api/core/jobs/".

   * The "obj_type" field on the Job model (previously JobResult) has been
     renamed to "object_type" for consistency with other models.

   * The JOBRESULT_RETENTION configuration parameter has been renamed
     to JOB_RETENTION.

   * The "obj" context variable is no longer passed when rendering custom
     links: Use "object" instead.

   * The REST API schema is now generated using the OpenAPI 3.0 spec

   * The URLs for the REST API schema documentation have changed:
       - "/api/docs/" is now "/api/schema/swagger-ui/"
       - "/api/redoc/" is now "/api/schema/redoc/"
EOD
}
{ type: upgrade
  maximum_version: 3.5.4
  message: <<EOD
If a separate configuration file is used that does not have an ".py" extension,
the following message may appear when the netbox rc script is started:

!!!
!!! WARNING: configuration file should have a valid Python extension.
!!!

In this case, the existing configuration file should be provided with a ".py"
extension and if set, the rc variable "netbox_config" should also point to the
configuration file with the new file extension.

The netbox sample rc script, which is provided via the EXAMPLES option, has
been adjusted accordingly.  This also includes a fix for the default path of
the configuration if the rc variable "netbox_config" is not set.
EOD
}
]