Configuration

Configuring NSoT

This section describes how to get started with configuring the NSoT server.

Initializing the Configuration

You may generate an initial configuration by executing nsot-server init. By default the file will be created at ~/.nsot/nsot.conf.py. You may specify a different location for the configuration as the argument to init:

nsot-server init /etc/nsot.conf.py

Specifying your Configuration

If you do not wish to utilize the default location, you must provide the --config argument when executing nsot-server so that it knows where to find it. For example, to start the server with the configuration in an alternate location:

nsot-server --config=/etc/nsot.conf.py start

You may also set the NSOT_CONF enviroment variable to the location of your configuration file so that you don’t have to provide the --config argument:

$ export NSOT_CONF=/etc/nsot.conf.py
$ nsot-server start

Sample Configuration

Below is a sample configuration file that covers the primary settings you may care about, and their default values.

"""
This configuration file is just Python code. You may override any global
defaults by specifying them here.

For more information on this file, see
https://docs.djangoproject.com/en/1.8/topics/settings/

For the full list of settings and their values, see
https://docs.djangoproject.com/en/1.8/ref/settings/
"""


from nsot.conf.settings import *
import os.path


# Path where the config is found.
CONF_ROOT = os.path.dirname(__file__)

# A boolean that turns on/off debug mode. Never deploy a site into production
# with DEBUG turned on.
# Default: False
DEBUG = False

############
# Database #
############
# https://docs.djangoproject.com/en/dev/ref/settings/#databases
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': os.path.join(CONF_ROOT, 'nsot.sqlite3'),
        'USER': 'nsot',
        'PASSWORD': '',
        'HOST': '',
        'PORT': '',
    }
}

###############
# Application #
###############

# The address on which the application will listen.
# Default: localhost
NSOT_HOST = 'localhost'

# The port on which the application will be accessed.
# Default: 8990
NSOT_PORT = 8990

# The number of gunicorn worker processes for handling requests.
# Default: 4
NSOT_NUM_WORKERS = 4

# Timeout in seconds before gunicorn workers are killed/restarted.
# Default: 30
NSOT_WORKER_TIMEOUT = 30

# If True, serve static files directly from the app.
# Default: True
SERVE_STATIC_FILES = True

############
# Security #
############

# A URL-safe base64-encoded 32-byte key. This must be kept secret. Anyone with
# this key is able to create and read messages. This key is used for
# encryption/decryption of sessions and auth tokens. A unique key is randomly
# generated for you when you utilize ``nsot-server init``
# https://cryptography.io/en/latest/fernet/#cryptography.fernet.Fernet.generate_key
SECRET_KEY = u'fMK68NKgazLCjjTXjDtthhoRUS8IV4lwD-9G7iVd2Xs='

# Header to check for Authenticated Email. This is intended for use behind an
# authenticating reverse proxy.
USER_AUTH_HEADER = 'X-NSoT-Email'

# The age, in seconds, until an AuthToken granted by the API will expire.
# Default: 600
AUTH_TOKEN_EXPIRY = 600  # 10 minutes

# A list of strings representing the host/domain names that this Django site can
# serve. This is a security measure to prevent an attacker from poisoning caches
# and triggering password reset emails with links to malicious hosts by
# submitting requests with a fake HTTP Host header, which is possible even under
# many seemingly-safe web server configurations.
# https://docs.djangoproject.com/en/1.8/ref/settings/#allowed-hosts
ALLOWED_HOSTS = ['*']

##############
# Interfaces #
##############

# The default format for displaying MAC addresses. This defaults to
# ":"-separated and expanded (e.g. '00:00:00:00:00:00')
MACADDRESS_DEFAULT_DIALECT = 'macaddress.mac_linux'

# The default speed in Mbps for newly device interfaces if not otherwise
# specified.
INTERFACE_DEFAULT_SPEED = 1000  # In Mbps (e.g. 1Gbps)

# Whether to compress IPv6 for display purposes, for example:
# - Default: 2620:0100:6000:0000:0000:0000:0000:0000/40
# - Compressed: 2620:100:6000::/40
# Default: True
NSOT_COMPRESS_IPV6 = True

# Temp debug logging
if os.getenv('NSOT_DEBUG'):
    DEBUG = True
    LOGGING['loggers']['nsot']['level'] = 'DEBUG'
    LOGGING['loggers']['django.db.backends'] = {
        'handlers': ['console'],
        'level': 'DEBUG'
    }

Advanced Configuration

This section covers additional configuration options available to the NSoT server and advanced configuration topics.

Database

NSoT defaults to utilizing SQLite as a database backend, but supports any database backend supported by Django. The default backends available are SQLite, MySQL, PostgreSQL, and Oracle.

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': 'nsot.sqlite3',
    }
}

For more information on configuring the database, please see the official Django database documentation.

Caching

Note: At this time only Interface objects are cached if caching is enabled!

NSoT includes built-in support for caching of API results. The default is to use to the “dummy” cache that doesn’t actually cache – it just implements the cache interface without doing anything.

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.dummy.DummyCache',
    }
}

The cache is invalidated on any update or delete of an object. Caching can dramatically perform read operations of databases with a large amount of network Interface objects.

If you need caching, see the official Django caching documentation on how to set it up.