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, collect static
   files, remove stale content files and delete any expired user sessions

# cd %%DATADIR%%
# python%%PYTHON_VER%% manage.py migrate
# python%%PYTHON_VER%% manage.py trace_paths --no-input
# python%%PYTHON_VER%% manage.py collectstatic --no-input
# python%%PYTHON_VER%% manage.py remove_stale_contenttypes --no-input
# python%%PYTHON_VER%% manage.py clearsessions

2. Restart WSGI/httpd environment (supervisord/apache/nginx/etc.)
EOD
}
{ type: upgrade
  maximum_version: 2.7.7
  message: <<EOD
1. Removal of the Topology Maps feature

The deprecated topology maps feature has been removed.  Please replicate any
required data to another source before upgrading NetBox to v2.7.7, as any
existing topology maps will be deleted.


2. Changed REDIS database configuration settings

The REDIS database configuration parameters were splitted up in two discrete
subsections named "webhooks" and "caching".  This requires modification of the
REDIS parameter in configuration.py as follows: 

Old Redis sample configuration:

REDIS = {
    'HOST': 'localhost',
    'PORT': 6379,
    'PASSWORD': '',
    'DATABASE': 0,
    'CACHE_DATABASE': 1,
    'DEFAULT_TIMEOUT': 300,
    'SSL': False,
}

New Redis sample configuration:

REDIS = {
    'webhooks': {
        'HOST': 'redis.example.com',
        'PORT': 1234,
        'PASSWORD': 'foobar',
        'DATABASE': 0,
        'DEFAULT_TIMEOUT': 300,
        'SSL': False,
    },
    'caching': {
        'HOST': 'localhost',
        'PORT': 6379,
        'PASSWORD': '',
        'DATABASE': 1,
        'DEFAULT_TIMEOUT': 300,
        'SSL': False,
    }
}

Note that the CACHE_DATABASE parameter has been removed and the connection
settings have been duplicated for both "webhooks" and "caching".  This allows
one to make use of separate Redis instances if desired.  It is fine to use the
same Redis service for both functions, although the database identifiers should
be different.


3. Removal of the WEBHOOKS_ENABLED configuration parameter

As django-rq is now a required library, NetBox assumes that the RQ worker
process is running and the WEBHOOKS_ENABLED configuration parameter is no
longer used.  Please ensure that both the NetBox WSGI service and the RQ worker
process are running on all production installations.


4. Fixed natural orderding of interfaces

The 2.7.7 release contains a bug fix regarding the natural ordering of
interfaces.  If any interfaces appear unordered, run the following management
command to recalculate their naturalized values after the usual upgrading steps
(database migrations, collect static files, etc.) were issued:

# cd %%DATADIR%%
# python%%PYTHON_VER%% manage.py renaturalize dcim.Interface

EOD
}
{ type: upgrade
  maximum_version: 2.7.9
  message: <<EOD
Please note that two additional steps (remove stale content & clear cached
files) are now required after each update of NetBox.

These were added to the existing update instructions which are displayed with
each update.
EOD
}
{ type: upgrade
  maximum_version: 2.7.10
  message: <<EOD
Please note that another additional step (delete expired user sessions) is now
required after each update of NetBox.

That step was added to the existing update instructions which are displayed
with each update.
EOD
}
{ type: upgrade
  maximum_version: 2.7.11
  message: <<EOD
The "webhooks" REDIS configuration section has been renamed to "tasks".  Please
update your configuration as support for the old name will be removed in a
future release.

Also the sample rc script got some new default values and improvements, e.g.
the possibility to add extra arguments or to use a configuration file instead
of using rc variables.
EOD
}
{ type: upgrade
  maximum_version: 2.9.8
  message: <<EOD
Changes related to the NetBox configuration:

1. If in use, LDAP authentication must be enabled by setting
   REMOTE_AUTH_BACKEND to 'netbox.authentication.LDAPBackend'.  (The LDAP
   configuration parameters in ldap_config.py remain unchanged.)

2. REMOTE_AUTH_DEFAULT_PERMISSIONS now takes a dictionary rather than a list.
   This is a mapping of permission names to a dictionary of constraining
   attributes, or None.

   For example, ['dcim.add_site', 'dcim.change_site'] would become
   {'dcim.add_site': None, 'dcim.change_site': None}.

3. Support for the DEFAULT_TIMEOUT parameter under REDIS database configuration
   was removed.  Set RQ_DEFAULT_TIMEOUT as a global configuration parameter
   instead.


Changes related to permissions:

1. Any permissions referencing the legacy ReportResult model (e.g.
   'extras.view_reportresult') should be updated to reference the Report model.

2. The 'secrets.activate_userkey' permission no longer exists.  Instead,
   'secrets.change_userkey' is checked to determine whether a user has the
   ability to activate a UserKey.

3. The 'users.delete_token permission' is no longer enforced.  All users are
   permitted to delete their own API tokens.


Changes to the REST API:

Numerous changes have been made to the REST API. Please check the changelogs
for more details.


Workaround for issues with invalid nested data:

Users that are experiencing invalid nested data with regions, rack groups, or
tenant groups can perform a one-time operation using the NetBox shell to
rebuild the correct nested relationships after upgrading:

# cd %%DATADIR%%
# python%%PYTHON_VER%% manage.py nbshell
### NetBox interactive shell (localhost)
### Python 3.x.x | Django 3.1.x | NetBox 2.9.x
### lsmodels() will show available models. Use help(<model>) for more info.
>>> Region.objects.rebuild()
>>> RackGroup.objects.rebuild()
>>> TenantGroup.objects.rebuild()
EOD
}
{ type: upgrade
  maximum_version: 2.9.9
  message: <<EOD
An new sample rc script has been added to manage the RQ-worker service.  If the
EXAMPLES option is enabled (which is the default) it can be found in the
following directory:

%%EXAMPLESDIR%%/netbox_rq.sample
EOD
}
{ type: upgrade
  maximum_version: 2.10.3
  message: <<EOD
The Django templating language (DTL) is no longer supported for export
templates.  Please ensure that all export templates use Jinja2 before
upgrading.

Also the support for embedded graphs was completely removed and several changes
to the REST API were made.  Please check the changelogs for further details.
EOD
}
{ type: upgrade
  maximum_version: 2.11.9
  message: <<EOD
* All objects now use numeric IDs in their UI view URLs instead of slugs.  You
  may need to update external references to NetBox objects.  (Note that this
  does _not_ affect the REST API.)

* The UI now uses numeric IDs when filtering object lists.  You may need to
  update external links to filtered object lists.  (Note that the slug- and
  name-based filters will continue to work, however the filter selection fields
  within the UI will not be automatically populated.)

* The RackGroup model has been renamed to "Location".  Its REST API endpoint
  has changed from /api/dcim/rack-groups/ to /api/dcim/locations/.

* The foreign key field "group" on dcim.Rack has been renamed to "location".

* The foreign key field "site" on ipam.VLANGroup has been replaced with the
  "scope" generic foreign key.

* Custom script ObjectVars no longer support the "queryset" parameter:
  Use "model" instead.

Several changes to the REST API were made as well.  Please check the changelogs
for further details.
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
}
]