Configuring SCOS Sensor

Note: this page is written with the assumption that this issue has been resolved.

Configuration of SCOS Sensor is carried out via environment variables. This page contains information about the provided defaults, how they are intended to be used, and a table containing all available settings. Additional configuration is done by populating component definition files; see the [Component Definition Files](https://github.com/NTIA/scos-sensor/wiki/Component-Definition-Files) page for more information.

The Provided env.template File

The settings in this file are configured for running in a development environment on your local system. For running in a production environment, many of the settings will need to be modified. The intended usage is for this template to serve as the basis for each SCOS Sensor installation, and for the user to tweak settings to their needs. We recommend copying the template file and working from there:

cp env.template ./env

After modifying the settings, source the environment variables:

source ./env

Some of the values, including the ENCRYPTION_KEY, POSTGRES_PASSWORD, and the Django SECRET_KEY are randomly generated in this file. Therefore, if the source command is run a second time, the old values will be lost. Make sure to hardcode and backup these environment variables to enable SCOS Sensor to decrypt the data files and access the database.

Full List of Environment Variables

The following is a table containing the full set of environment variables used by SCOS Sensor, along with their descriptions.

TODO: Explore options to organize these settings, aiming to guide the user to the most important settings first. Consider grouping options which need to be changed when using non-default signal analyzers, or when configuring a certain type of authentication. These may warrant their own wiki pages- and this page can serve as the comprehensive list of settings instead

TODO: Add documentation for supported configuration and calibration files

Table 1. Configuration Options

Variable Name	Description	Change in Production?
ADDITIONAL_USER_NAMES	Comma separated list of additional admin usernames
ADDITIONAL_USER_PASSWORD	Password for additional admin users
ADMIN_EMAIL	Email used to generate admin user	Yes
ADMIN_NAME	Username for the admin user
ADMIN_PASSWORD	Password used to generate admin user	Yes
AUTHENTICATION	Authentication method used for SCOS Sensor. Supports TOKEN or CERT
BASE_IMAGE	Base Docker image used to build the API container. These Docker images, combined with any drivers found in the signal analyzer repositories, are responsible for providing the operating system suitable for the chosen signal analyzer. By default, this is configured to use a version of ghcr.io/ntia/scos-tekrsa/tekrsa_usb, which supports a Tektronix signal analyzer
CALLBACK_AUTHENTICATION	Sets how to authenticate to the callback URL. Supports TOKEN or CERT
CALLBACK_SSL_VERIFICATION	Set to true in production. If false, SSL certificate validation is ignored when posting results to the callback URL.	Yes
CALLBACK_TIMEOUT	Timeout for posts sent to the callback URL when a scheduled action is completed (seconds)
DEBUG	Whether to enable Django debug mode. Set to false in production.	Yes
DEVICE_MODEL	Optional setting indicating the signal analyzer model. For some signal analyzers, the signal analyzer interface class will use this value to determine which actions should be loaded.
DOCKER_TAG	Always set to latest to install newest versions of Docker containers
DOMAINS	A space-separated list of domain names, used to generate Django’s ALLOWED_HOSTS
ENCRYPT_DATA_FILES	If true, .sigmf-data files will be encrypted when stored in the API container by SCOS Sensor
ENCRYPTION_KEY	Encryption key to encrypt .sigmf-data files if ENCRYPT_DATA_FILES is true; Defaults to a randomly generated value
GIT_BRANCH	Current branch of NTIA/scos-sensor being used
GUNICORN_LOG_LEVEL	Log level for Gunicorn log messages
IPS	A space-separated list of IP addresses, used to generate Django’s ALLOWED_HOSTS
FQDN	The server’s fully qualified domain name
MAX_DISK_USAGE	The maximum disk usage (as a percentage) allowed before old data will be overwritten. Defaults to 85%. Note the disk usage detected by SCOS Sensor (using the Python shutil.disk_usage function) may not match the usage reported by the Linux df command
PATH_TO_CLIENT_CERT	Path to file containing certificate and private key used as client certificate when CALLBACK_AUTHENTICATION is set to CERT
POSTGRES_PASSWORD	Sets the password for the Postgres® database, for the postgres user. Defaults to a randomly-generated value.	Yes
REPO_ROOT	Root folder of the repository. Should be correctly set by default
SCOS_SENSOR_GIT_TAG	The current branch name on NTIA/scos-sensor. Value may be used in action metadata to capture the version of the software which produced the SigMF archive.
SECRET_KEY	Used by Django to provide cryptographic signing. Change to a unique, unpredictable value. See Django’s documentation for details. Defaults to a randomly-generated value.	Yes
SIGAN_CLASS	Name of the signal analyzer class to use. By default, this is set to TekRSASigan to use a Tektronix RSA signal analyzer. Must be changed in order to use a different signal analyzer.
SIGAN_MODULE	Name of the Python module that provides the signal analyzer implementation. Defaults to scos_tekrsa.hardware.tekrsa_sigan to use a Tektronix RSA signal analyzer. Must be changed in order to use a different signal analyzer.
SIGAN_POWER_CYCLE_STATES	Optional setting to provide the name of the control_state in the SIGAN_POWER_SWITCH that will power cycle the signal analyzer
SIGAN_POWER_SWITCH	Optional setting used to indicate the name of a WebRelay that may be used to power cycle the signal analyzer if necessary. Note: specifics of power-cycling behavior are implemented within the signal analyzer plugins, or in actions.
SSL_CA_PATH	Path to a CA certificate used to verify SCOS Sensor client certificate(s) when AUTHENTICATION is set to CERT
SSL_CERT_PATH	Path to server SSL certificate. Replace the certificate in the NTIA/scos-sensor repository with a valid certificate in production.	Yes
SSL_KEY_PATH	Path to server SSL private key. Use the private key for your valid certificate in production.	Yes
USB_DEVICE	Optional string used to search for available USB devices. By default, this is set to Tektronix to search for available Tektronix RSA signal analyzers. If the specified value is not found in the output of lsusb, SCOS Sensor will attempt to restart the API container. If using a different signal analyzer, this setting should be updated or removed.