Logo

A powerful, easily deployable network traffic analysis tool suite for network security monitoring

Quick Start

Documentation

Components

Supported Protocols

Configuring

Arkime

Dashboards

Hedgehog Linux

Contribution Guide

Malcolm Configuration

Malcolm’s runtime settings are stored (with a few exceptions) as environment variables in configuration files ending with a .env suffix in the ./config directory. The ./scripts/configure script can help users configure and tune these settings. For an in-depth treatment of the configuration script, see the Configuration section in End-to-end Malcolm and Hedgehog Linux ISO Installation.

Environment variable files

Although the configuration script automates many of the following configuration and tuning parameters, some environment variables of particular interest are listed here for reference.

Command-line arguments

The ./scripts/configure script can also be run noninteractively which can be useful for scripting Malcolm setup. This behavior can be selected by supplying the -d or --defaults option on the command line. Running with the --help option will list the arguments accepted by the script:

usage: configure [-h] [--debug [true|false]] [--quiet] [--configure [true|false]] [--dry-run] [--log-to-file [filename]] [--skip-splash] [--tui | --dui | --gui | --non-interactive] [--compose-file <string>] [--environment-dir-input <string>] [--environment-dir-output <string>]
                 [--export-malcolm-config-file [<path>]] [--import-malcolm-config-file <path> | --load-existing-env [true|false] | --defaults] [--malcolm-file <string>] [--image-file <string>] [--extra [EXTRASETTINGS ...]]

Malcolm Installer

options:
  -h, --help            show this help message and exit

Installer Options:
  --debug, --verbose [true|false]
                        Enable debug output including tracebacks and debug utilities
  --quiet, --silent     Suppress console logging output during installation
  --configure, -c [true|false]
                        Only write configuration and ancillary files; skip installation steps
  --dry-run             Log planned actions without writing files or making system changes
  --log-to-file [filename]
                        Log output to file. If no filename provided, creates timestamped log file.
  --skip-splash         Skip the splash screen prompt on startup

Interface Mode (mutually exclusive):
  --tui                 Run in command-line text-based interface mode (default)
  --dui                 Run in python dialogs text-based user interface mode (if available - requires python dialogs)
  --gui                 Run in graphical user interface mode (if available - requires customtkinter)
  --non-interactive     Run in non-interactive mode for unattended installations (suppresses all user prompts)

Configuration File Options:
  --compose-file, --configure-file, --kube-file, -f <string>
                        Path to docker-compose.yml (for compose) or kubeconfig (for Kubernetes)

Environment Config Options:
  --environment-dir-input <string>
                        Input directory containing Malcolm's .env and .env.example files
  --environment-dir-output, -e <string>
                        Target directory for writing Malcolm's .env files
  --export-malcolm-config-file, --export-mc-file [<path>]
                        Export configuration to JSON/YAML settings file (auto-generates filename if not specified)
  --import-malcolm-config-file, --import-mc-file <path>
                        Import configuration from JSON/YAML settings file
  --load-existing-env, -l [true|false]
                        Automatically load provided config/ .env files from the input directory when present. Can be used in conjunction with --environment-dir-input
  --defaults, -d        Use built-in default configuration values and skip loading from the config directory

Installation Files:
  --malcolm-file, -m <string>
                        Malcolm .tar.gz file for installation
  --image-file, -i <string>
                        Malcolm container images .tar.xz file for installation

Additional Configuration Options:
  --extra [EXTRASETTINGS ...]
                        Extra environment variables to set (e.g., foobar.env:VARIABLE_NAME=value)
…

Once Malcolm is configured correctly, the --export-malcolm-config-file option can be used to export the configuration to a file that can be used with --import-malcolm-config-file to restore it later or transfer it to another Malcolm instance for import.

To modify Malcolm settings programmatically in scripting, a tool like jq can be used with --export-malcolm-config-file and --import-malcolm-config-file, as illustrated here:

# export the current configuration to a JSON file without modifying anything in ./config/
SETTINGS_FILE="$(mktemp --suffix=.json)"
./scripts/configure --dry-run --non-interactive --export-malcolm-config-file "${SETTINGS_FILE}"

# use JQ To set whatever options in the exported JSON configuration file you wish to change
JQ_FILE="$(mktemp --suffix=.jq)"
tee "${JQ_FILE}" >/dev/null <<EOF
  .configuration.dashboardsDarkMode = true
  | .configuration.reverseDns = true
  | .configuration.pcapNodeName = "Engineering Workstation"
EOF
jq -f "${JQ_FILE}" "${SETTINGS_FILE}" | sponge "${SETTINGS_FILE}"

# import the modified configuration
./scripts/configure --non-interactive --import-malcolm-config-file "${SETTINGS_FILE}"

# clean up
rm -f "${SETTINGS_FILE}" "${JQ_FILE}"

Similarly, authentication-related settings can also be set noninteractively by using the command-line arguments for ./scripts/auth_setup.

Managing disk usage

In instances where Malcolm is deployed with the intention of running indefinitely, eventually the question arises of what to do when the file systems used for storing Malcolm’s artifacts (e.g., PCAP files, raw logs, OpenSearch indices, extracted files, etc.). Malcolm provides options for tuning the “aging out” (deletion) of old artifacts to make room for newer data.