From f43184695bc1f82bf5506888e451d2efc8492b93 Mon Sep 17 00:00:00 2001 From: Jeremy Stretch Date: Tue, 24 May 2016 11:46:55 -0400 Subject: [PATCH] Cleaned up configuration settings --- docs/configuration.md | 78 ++++++++++++++++++++++++++ netbox/netbox/configuration.example.py | 37 ++++++------ netbox/netbox/settings.py | 38 ++++++++++--- 3 files changed, 125 insertions(+), 28 deletions(-) create mode 100644 docs/configuration.md diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 000000000..30ae104e6 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,78 @@ +NetBox's local configuration is held in `netbox/netbox/configuration.py`. An example configuration is provided at `netbox/netbox/configuration.example.py`. You may copy or rename the example configuration and make changes as appropriate. NetBox will not run without a configuration file. + +# Mandatory Settings + +## DATABASE + +NetBox requires access to a PostgreSQL database service to store data. This service can run locally or on a remote system. The following parameters must be defined within the `DATABASE` dictionary: + +* NAME - Database name +* USER - PostgreSQL username +* PASSWORD - PostgreSQL password +* HOST - Name or IP address of the database server (use `localhost` if running locally) +* PORT - TCP port of the PostgreSQL service; leave blank for default port (5432) + +## SECRET_KEY + +This is a secret cryptographic key is used to improve the security of cookies and password resets. The key defined here should not be shared outside of the configuration file. `SECRET_KEY` can be changed at any time, however be aware that doing so will invalidate all existing sessions. + +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 following Python code can be used to generate a key: + +``` +import os +import random + +charset = 'abcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*(-_=+)' +random.seed = (os.urandom(2048)) +print ''.join(random.choice(charset) for c in range(50)) +``` + +## ALLOWED_HOSTS + +This is a list of valid host names by which NetBox may be reached. This list is used to defend against cross-site scripting (XSS) attacks. You must specify at least one host name. + +Example: + +``` +ALLOWED_HOSTS = ['netbox.example.com', 'netbox.internal.local'] +``` + +# Optional Settings + +## TIME_ZONE + +Default: UTC + +The time zone NetBox will use when dealing with dates and times. It is recommended to use UTC time unless you have a specific need to use a local time zone. [List of available time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). + +## LOGIN_REQUIRED + +Default: False, + +Setting this to True will permit only authenticated users to access any part of NetBox. By default, anonymous users are permitted to access most data in NetBox (excluding secrets) but not make any changes. + +## PAGINATE_COUNT + +Default: 50 + +Determine how many objects to display per page within each list of objects. + +## NETBOX_USERNAME + +## NETBOX_PASSWORD + +If provided, NetBox will use these credentials to authenticate against devices when collecting data. + +## MAINTENANCE_MODE + +Default: False + +Setting this to True will display a "maintenance mode" banner at the top of every page. + +## DEBUG + +Default: False + +This setting enables debugging. This should be done only during development or troubleshooting. Never enable debugging on a production system, as it can expose sensitive data to unauthenticated users. diff --git a/netbox/netbox/configuration.example.py b/netbox/netbox/configuration.example.py index e10a7c2b4..be3c8f230 100644 --- a/netbox/netbox/configuration.example.py +++ b/netbox/netbox/configuration.example.py @@ -4,6 +4,15 @@ # # ######################### +# PostgreSQL database configuration. +DATABASE = { + 'NAME': 'netbox', # Database name + 'USER': 'netbox', # PostgreSQL username + 'PASSWORD': '', # PostgreSQL password + 'HOST': 'localhost', # Database server + 'PORT': '', # Database port (leave blank for default) +} + # This key is used for secure generation of random numbers and strings. It must never be exposed outside of this file. # For optimal security, SECRET_KEY should be at least 50 characters in length and contain a mix of letters, numbers, and # symbols. NetBox will not run without this defined. For more information, see @@ -14,18 +23,6 @@ SECRET_KEY = '' # E.g. ALLOWED_HOSTS = ['netbox.yourdomain.com'] ALLOWED_HOSTS = [] -# PostgreSQL database configuration. -DATABASES = { - 'default': { - 'ENGINE': 'django.db.backends.postgresql', - 'NAME': 'netbox', # Database name - 'USER': 'netbox', # PostgreSQL username - 'PASSWORD': '', # PostgreSQL password - 'HOST': 'localhost', # Database server - 'PORT': '', # Database port (leave blank for default) - } -} - ######################### # # @@ -33,16 +30,11 @@ DATABASES = { # # ######################### -# Setting this to True will display a "maintenance mode" banner at the top of every page. -MAINTENANCE_MODE = False +# Time zone (default: UTC) +TIME_ZONE = 'UTC' -# If enabled, NetBox will run with debugging turned on. This should only be used for development or troubleshooting. -# -# NEVER ENABLE DEBUGGING ON A PRODUCTION SYSTEM! -DEBUG = False - -# If True, user authentication will be required for all site access. If False, unauthenticated users will be able to -# access NetBox but not make any changes. +# Setting this to True will permit only authenticated users to access any part of NetBox. By default, anonymous users +# are permitted to access most data in NetBox (excluding secrets) but not make any changes. LOGIN_REQUIRED = False # Determine how many objects to display per page within a list. (Default: 50) @@ -51,3 +43,6 @@ PAGINATE_COUNT = 50 # Credentials that NetBox will use to access live devices. NETBOX_USERNAME = '' NETBOX_PASSWORD = '' + +# Setting this to True will display a "maintenance mode" banner at the top of every page. +MAINTENANCE_MODE = False diff --git a/netbox/netbox/settings.py b/netbox/netbox/settings.py index 891a755cd..0964296ae 100644 --- a/netbox/netbox/settings.py +++ b/netbox/netbox/settings.py @@ -2,10 +2,41 @@ import os import socket from django.contrib.messages import constants as messages +from django.core.exceptions import ImproperlyConfigured + +try: + import configuration +except ImportError: + raise ImproperlyConfigured("Configuration file is not present. Please define netbox/netbox/configuration.py per " + "the documentation.") + + +# Import local configuration +for setting in ['DATABASE', 'SECRET_KEY', 'ALLOWED_HOSTS']: + try: + globals()[setting] = getattr(configuration, setting) + except AttributeError: + raise ImproperlyConfigured("Mandatory setting {} is missing from configuration.py. Please define it per the " + "documentation.".format(setting)) + +# Default configurations +TIME_ZONE = getattr(configuration, 'TIME_ZONE', 'UTC') +MAINTENANCE_MODE = getattr(configuration, 'MAINTENANCE_MODE', False) +DEBUG = getattr(configuration, 'DEBUG', False) +LOGIN_REQUIRED = getattr(configuration, 'LOGIN_REQUIRED', False) +PAGINATE_COUNT = getattr(configuration, 'PAGINATE_COUNT', 50) +NETBOX_USERNAME = getattr(configuration, 'NETBOX_USERNAME', '') +NETBOX_PASSWORD = getattr(configuration, 'NETBOX_PASSWORD', '') BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +# Database +configuration.DATABASE.update({'ENGINE': 'django.db.backends.postgresql'}) +DATABASES = { + 'default': configuration.DATABASE, +} + # Installed applications INSTALLED_APPS = ( 'django.contrib.admin', @@ -68,7 +99,6 @@ SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https') # Internationalization # https://docs.djangoproject.com/en/1.8/topics/i18n/ LANGUAGE_CODE = 'en-us' -TIME_ZONE = 'UTC' USE_I18N = True USE_TZ = True @@ -109,9 +139,3 @@ try: HOSTNAME = socket.gethostname() except: HOSTNAME = 'localhost' - -# Import local configuration -try: - from configuration import * -except ImportError: - pass