diff --git a/CHANGELOG.md b/CHANGELOG.md index 3ef3ec303..49c487fc2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,15 +16,9 @@ This allows a device (e.g. a PDU) to calculate its total load compared to its co To improve performance, NetBox now supports caching for most object and list views. Caching is implemented using Redis, which is now a required dependency. (Previously, Redis was required only if webhooks were enabled.) -Several configuration parameters are available to control caching behavior: +A new configuration parameter is available to control the cache timeout: ``` -# Cache culling frequrency; a ratio. Example: 3 will cull one third of the cache when CACHE_MAX_ENTRIES is reached. -CACHE_CULL_FREQUENCY = 3 - -# Max number of entries (unique pages) to store in the cache at a time -CACHE_MAX_ENTRIES = 300 - # Cache timeout (in seconds) CACHE_TIMEOUT = 900 ``` @@ -68,7 +62,7 @@ single button. ### New Dependency: Redis -[Redis](https://redis.io/) is an in-memory data store similar to memcached. While Redis has been optional component of +[Redis](https://redis.io/) is an in-memory data store similar to memcached. While Redis has been an optional component of NetBox since the introduction of webhooks in version 2.4, it is now required to support NetBox's new caching functionality (as well as other planned features). @@ -80,11 +74,18 @@ REDIS = { 'PORT': 6379, 'PASSWORD': '', 'DATABASE': 0, + 'CACHE_DATABASE': 1, 'DEFAULT_TIMEOUT': 300, 'SSL': False, } ``` +Note that if you were using these settings in a prior release with webhooks, the `DATABASE` setting remains the same but +an additional `CACHE_DATABASE` setting has been added with a default value of 1 to support the caching backend. The +`DATABASE` setting will be renamed in a future release of NetBox to better relay the meaning of the setting. It is highly +recommended to keep the webhook and cache databases seperate. Using the same database number for both may result in webhook +processing data being lost in cache flushing events. + ### API Support for Specifying Related Objects by Attributes([#3077](https://github.com/digitalocean/netbox/issues/3077)) Previously, referencing a related object in an API request required knowing the primary key (integer ID) of that object. @@ -143,7 +144,7 @@ functionality provided by the front end UI. ## API Changes -* New API endpoints for power modeling: `/api/dcim/power-panels` and `/api/dcim/power-feeds/` +* New API endpoints for power modeling: `/api/dcim/power-panels/` and `/api/dcim/power-feeds/` * New API endpoint for custom field choices: `/api/extras/_custom_field_choices/` * ForeignKey fields now accept either the related object PK or a dictionary of attributes describing the related object. * Organizational objects now include child object counts. For example, the Role serializer includes `prefix_count` and `vlan_count`. diff --git a/docs/additional-features/caching.md b/docs/additional-features/caching.md new file mode 100644 index 000000000..32ac77cbf --- /dev/null +++ b/docs/additional-features/caching.md @@ -0,0 +1,21 @@ +# Caching + +To improve performance, NetBox supports caching for most object and list views. Caching is implemented using Redis, +and [django-cacheops](https://github.com/Suor/django-cacheops) + +Several management commands are avaliable for administrators to manaully invalidate cache entries in extenuating circumstances. + +To invalidate a specifc model instance (for example a Device with ID 34): +``` +python netbox/manage.py invalidate dcim.Device.34 +``` + +To invalidate all instance of a model: +``` +python netbox/manage.py invalidate dcim.Device +``` + +To flush the entire cache database: +``` +python netbox/manage.py invalidate all +``` diff --git a/docs/configuration/optional-settings.md b/docs/configuration/optional-settings.md index f6725a92e..ea550c62f 100644 --- a/docs/configuration/optional-settings.md +++ b/docs/configuration/optional-settings.md @@ -44,6 +44,14 @@ BASE_PATH = 'netbox/' --- +## CACHE_TIMEOUT + +Default: 900 + +The number of seconds to retain cache entries before automatically invalidating them. + +--- + ## CHANGELOG_RETENTION Default: 90 @@ -293,56 +301,3 @@ SHORT_TIME_FORMAT = 'H:i:s' # 13:23:00 DATETIME_FORMAT = 'N j, Y g:i a' # June 26, 2016 1:23 p.m. SHORT_DATETIME_FORMAT = 'Y-m-d H:i' # 2016-06-27 13:23 ``` - ---- - -## Redis Connection Settings - -[Redis](https://redis.io/) is a key-value store which functions as a very lightweight database. It is required when enabling NetBox [webhooks](../additional-features/webhooks/). A Redis connection is configured using a dictionary similar to the following: - -``` -REDIS = { - 'HOST': 'localhost', - 'PORT': 6379, - 'PASSWORD': '', - 'DATABASE': 0, - 'DEFAULT_TIMEOUT': 300, - 'SSL': False, -} -``` - -### DATABASE - -Default: 0 - -The Redis database ID. - -### DEFAULT_TIMEOUT - -Default: 300 - -The timeout value to use when connecting to the Redis server (in seconds). - -### HOST - -Default: localhost - -The hostname or IP address of the Redis server. - -### PORT - -Default: 6379 - -The TCP port to use when connecting to the Redis server. - -### PASSWORD - -Default: None - -The password to use when authenticating to the Redis server (optional). - -### SSL - -Default: False - -Use secure sockets layer to encrypt the connections to the Redis server. diff --git a/docs/configuration/required-settings.md b/docs/configuration/required-settings.md index fb08e643b..9c3ea4d4f 100644 --- a/docs/configuration/required-settings.md +++ b/docs/configuration/required-settings.md @@ -43,3 +43,44 @@ This is a secret cryptographic key is used to improve the security of cookies an Please note that this key is **not** used for hashing user passwords or for the encrypted storage of secret data in NetBox. `SECRET_KEY` should be at least 50 characters in length and contain a random mix of letters, digits, and symbols. The script located at `netbox/generate_secret_key.py` may be used to generate a suitable key. + +--- + +## REDIS + +[Redis](https://redis.io/) is an in-memory data store similar to memcached. While Redis has been an optional component of +NetBox since the introduction of webhooks in version 2.4, it is required starting in 2.6 to support NetBox's caching +functionality (as well as other planned features). + +Redis is configured using a configuration setting similar to `DATABASE`: + +* HOST - Name or IP address of the Redis server (use `localhost` if running locally) +* PORT - TCP port of the Redis service; leave blank for default port (6379) +* PASSWORD - Redis password (if set) +* DATABASE - Numeric database ID for webhooks +* CACHE_DATABASE - Numeric database ID for caching +* DEFAULT_TIMEOUT - Connection timeout in seconds +* SSL - Use SSL connection to Redis + +Example: + +``` +REDIS = { + 'HOST': 'localhost', + 'PORT': 6379, + 'PASSWORD': '', + 'DATABASE': 0, + 'CACHE_DATABASE': 1, + 'DEFAULT_TIMEOUT': 300, + 'SSL': False, +} +``` + +!!! note: + If you were using these settings in a prior release with webhooks, the `DATABASE` setting remains the same but + an additional `CACHE_DATABASE` setting has been added with a default value of 1 to support the caching backend. The + `DATABASE` setting will be renamed in a future release of NetBox to better relay the meaning of the setting. + +!!! warning: + It is highly recommended to keep the webhook and cache databases seperate. Using the same database number for both may result in webhook + processing data being lost in cache flushing events. diff --git a/docs/development/release-checklist.md b/docs/development/release-checklist.md index 5e1f92fcc..f841fc50a 100644 --- a/docs/development/release-checklist.md +++ b/docs/development/release-checklist.md @@ -29,6 +29,7 @@ Update the following static libraries to their most recent stable release: * Bootstrap 3 * Font Awesome 4 +* Select2 * jQuery * jQuery UI diff --git a/mkdocs.yml b/mkdocs.yml index a0185e56e..47e6e0860 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -36,6 +36,7 @@ pages: - Reports: 'additional-features/reports.md' - Webhooks: 'additional-features/webhooks.md' - Change Logging: 'additional-features/change-logging.md' + - Caching: 'additional-features/caching.md' - Administration: - Replicating NetBox: 'administration/replicating-netbox.md' - NetBox Shell: 'administration/netbox-shell.md'