Skip to main content
Version: 0.10

Install a sensor on Linux (Docker)

The supported deployment path today. The sensor is distributed as a container image and run with Compose on any Linux host that can reach the console.

Before you start, check the system and network requirements and decide where the sensor needs to sit. Placement is what decides which integrations it can run.

What the host needs​

RequirementDetail
Operating systemLinux on x86-64 (amd64). The image is published for that architecture only
Container runtimeDocker Engine with the Compose plugin (docker compose)
PrivilegesAdministrator rights to run Docker, typically sudo
NetworkOutbound HTTPS to the console, directly or through a proxy. See Network requirements
FolderAn empty folder for the compose file. The sensor's data/ and logs/ folders are created beside it

Get a deployment token​

In the console, open Settings → Sensors → Add sensor and reveal or copy the tenant's deployment token, the same token described under Enrolling a sensor. The dialog states that it is valid for 60 minutes, so fetch it when you are ready to install rather than in advance.

Write the compose file​

The Add sensor dialog builds this file for you: step 3 shows it with your console's address and, once you have revealed or copied it, the deployment token already filled in. Copy it or use Download docker-compose.yml, and save it as docker-compose.yml in an empty folder on the host. It looks like this:

docker-compose.yml
services:
velumedge-agent:
image: ghcr.io/davydovvn/velumedge-agent:v0.9.0
container_name: velumedge-agent
restart: unless-stopped
# Host networking: nmap needs the host's interfaces for raw-socket scans and OS detection.
network_mode: host
environment:
# Enrol on first start (needs TOKEN), then run. Later starts reuse the token stored in ./data.
MODE: connect_and_run
# Deployment token from "Add sensor". Valid for 60 minutes and read only during enrolment,
# so you can delete this line once the sensor shows up in the console.
TOKEN: "<DEPLOYMENT_TOKEN>"
# The console this sensor reports to.
LE_SERVER_HOST: "https://<your-organization>.velumedge.com"
# Verify the console's TLS certificate. Keep "true" outside a lab.
LE_SECURE: "true"
# Optional - more options in the agent documentation (https://docs.velumedge.com/agent):
# LE_PROXY: '{"http": "http://proxy:3128", "https": "http://proxy:3128"}'
# LE_GLOBAL_MAX_CONCURRENT_TASKS: "4"
# LE_LOGGING_LEVEL: INFO
volumes:
# ./data holds the sensor's API token, which is its identity. Keep it on the host and treat it
# as a secret: if it is lost, the container has to enrol again.
- ./data:/root/integration-app/data
- ./logs:/root/integration-app/logs
# Hardening: the agent only needs raw sockets for nmap and nothing else from root.
read_only: true
tmpfs:
- /tmp
cap_drop:
- ALL
cap_add:
- NET_RAW
- NET_ADMIN
security_opt:
- no-new-privileges:true
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"

Everything in it matters:

KeyWhy it is there
imageThe sensor build to run. Pin it, so a redeploy is a decision rather than a surprise
container_nameA fixed name for the container, so docker commands on the host can refer to it
restart: unless-stoppedThe sensor comes back with the host and after a crash, unless you stopped it yourself
network_mode: hostGives the container the host's interfaces: needed for the raw sockets active scanning uses, for OS detection, and so the sensor reports the host's own name and addresses. A sensor that will only ever run API integrations does not need it
MODEWhat the container does at startup. See Modes
TOKENThe deployment token from the previous step. Read during enrolment only
LE_SERVER_HOSTThe console the sensor reports to: your console's address, including https://. The dialog fills in the address you opened it from
LE_SECUREWhether the console's TLS certificate is verified. See TLS
volumesThe data directory (which holds the sensor's own API token) and the log directory. These have to live on the host, or replacing the container means enrolling again. See Volumes
read_only, tmpfsThe container cannot change its own files: it writes only to the two mounted directories and to /tmp, which is held in memory
cap_drop, cap_addThe sensor runs as root only so that scanning can open raw sockets. Every other capability is dropped; NET_RAW and NET_ADMIN are what active scanning, OS detection included, needs
security_optNothing in the container can gain further privileges
loggingCaps what Docker keeps of the container's console output at three files of 10 MB

Any other setting from the configuration reference can be added under environment as an LE_ variable.

Bounding the container

The compose file the console hands out sets no resource limits. To cap what the sensor can take from the host, add pids_limit: 512 and mem_limit: 2g to the service. Size mem_limit for the work you assign: see System requirements.

Modes​

MODE is required: the container does not start without it.

ModeBehaviour
connect_and_runEnrol with TOKEN if there is no stored token, then run. The usual choice, and what the console's compose file uses
connectExchange TOKEN for an API token, store it, and exit
runStart the polling loop with an already-stored token. It never enrols, so a fresh install in this mode never appears in the console
resetDelete the stored token, so the host can be enrolled again, and exit. It fails if there is no stored token

connect and reset exit when they are done, and the restart policy would start them again. Run them as one-off containers instead of changing the compose file:

sudo docker compose run --rm -e MODE=reset velumedge-agent
A reset gives the host a new identity

After a reset the host enrols as a new sensor. The old entry stays in the console holding its integration assignments, which have to be moved by hand. See What not to do.

Volumes​

Path in the containerOn the hostHolds
/root/integration-app/data./dataThe sensor's API token (token.dat) and the working folders where task results are staged before they are uploaded. Required
/root/integration-app/logs./logsThe sensor's log file. Required: the root filesystem is read-only, so the sensor has nowhere else to write it
/root/integration-app/config/config.jsonYour choice, mounted read-onlyAn optional config file. Without it the sensor runs on its defaults and the LE_ variables
/tmpIn memory (tmpfs)Temporary files. Cleared whenever the container restarts

Configuration reference​

The sensor builds its configuration from three layers, each overriding the one before:

  1. Built-in defaults.
  2. The config file, if there is one.
  3. LE_ environment variables, set under environment in the compose file.

Every setting has an environment variable: LE_ followed by its dotted name in upper case, with dots replaced by underscores. global.max_concurrent_tasks becomes LE_GLOBAL_MAX_CONCURRENT_TASKS.

SettingEnvironment variableDefaultMeaning
server.hostLE_SERVER_HOSTA built-in address that is not your consoleThe console this sensor reports to, with scheme and optional port, such as https://<your-organization>.velumedge.com. Always set it
secureLE_SECUREtrueWhether the console's TLS certificate is verified. See TLS
proxyLE_PROXYnull (no proxy)The proxy for outbound calls, as a JSON object of scheme to proxy URL. See Proxy
global.sleep_periodLE_GLOBAL_SLEEP_PERIOD30Seconds between polls of the console
global.max_concurrent_tasksLE_GLOBAL_MAX_CONCURRENT_TASKS4How many scans the sensor runs at once. See Concurrency
global.request_timeoutLE_GLOBAL_REQUEST_TIMEOUT180How long, in seconds, the sensor waits on a system it collects from (LDAP, CrowdStrike, Elastic, Microsoft Graph and so on), to connect and then for each read of the answer, before giving up. A system that accepts the connection and never answers would otherwise hold a scan slot until the sensor restarts. A value below 1, or one that is not a whole number, means 180
logging.levelLE_LOGGING_LEVELINFODEBUG, INFO, WARNING, ERROR or CRITICAL. Anything else means INFO
logging.fileLE_LOGGING_FILElogs/agent.logThe log file, relative to /root/integration-app. Keep it inside the logs volume
logging.formatLE_LOGGING_FORMAT%(asctime)s - %(levelname)s - %(filename)s:%(lineno)d - %(message)sThe layout of each log line, in Python logging format
logging.time_formatLE_LOGGING_TIME_FORMATnullA strftime format for the timestamp; null keeps the standard one
logging.create_dir_is_not_existsLE_LOGGING_CREATE_DIR_IS_NOT_EXISTStrueWhether the log file's folder is created if it is missing

These variables are not settings, and keep their names:

VariableMeaning
MODEWhat the container does at startup. Required. See Modes
TOKENThe deployment token. Read only when the sensor enrols
LE_CONFIG_PATHWhere the config file is read from. CONFIG_PATH is also accepted. Default config/config.json, that is /root/integration-app/config/config.json
LUMENEDGE_INSTALL_TYPESet by the image to docker, and reported to the console as the sensor's Installation. Do not override it: the console's Update agent action relies on it

How environment values are read:

  • Numbers and booleans are converted to the type the setting expects. true, yes, on and 1 are true; false, no, off and 0 are false. Quote them in the compose file (LE_SECURE: "true").
  • null, none and ~ set a value to null.
  • A value starting with { or [ is read as JSON, which is how LE_PROXY takes a whole object.
  • A variable that names a setting the sensor does not have, or holds a value of the wrong type, is ignored with a warning at startup.
The sensor prints its effective configuration at startup

Before anything else, the sensor writes every setting it ended up with, and which layer each came from (default, config file or environment), to its console output. Read it with sudo docker compose logs velumedge-agent. Values of settings whose names mark them as secret are masked. The same warnings show up in the Configuration item of the self-test.

The config file​

A config file is optional, and the image ships without one. Use it when you would rather keep settings in a file than in the compose file, or for the self-test thresholds, which have no environment variable of their own. Mount it read-only:

docker-compose.yml (excerpt)
volumes:
- ./data:/root/integration-app/data
- ./logs:/root/integration-app/logs
- ./config.json:/root/integration-app/config/config.json:ro

It is a JSON object with the same structure as the table above. List only the settings you want to change; the rest keep their defaults:

config.json
{
"server": {"host": "https://<your-organization>.velumedge.com"},
"secure": true,
"proxy": null,
"global": {"sleep_period": 30, "max_concurrent_tasks": 4, "request_timeout": 180},
"logging": {"file": "logs/agent.log", "level": "INFO"}
}

LE_ variables still win over the file. If the file is missing, is not valid JSON or is not a JSON object, the sensor warns and carries on with its defaults and the environment.

Environment variables reach the settings the sensor already knows

A variable is matched against the settings in the defaults and in the config file. A nested key that exists in neither, such as LE_PROXY_HTTPS when proxy is null, is ignored with a warning. Set the whole object with LE_PROXY, or put the structure in the config file.

Proxy​

Set proxy to a JSON object of scheme to proxy URL. In the compose file:

LE_PROXY: '{"http": "http://proxy.northwind.example:3128", "https": "http://proxy.northwind.example:3128"}'

The console traffic always goes through it, and so do some integrations. Many integrations instead use a proxy field of their own on the integration instance, and ignore this setting, so check each integration's page.

TODO

List which integrations use the sensor's proxy setting and which use their own proxy field.

A proxy URL can carry credentials. The self-test reports only whether a proxy is set, never its address.

TLS​

secure controls whether the sensor verifies the console's certificate. Leave it true outside a lab: with it off, anything that can intercept the connection can impersonate the console. The setting covers the connection to the console only; integrations have their own Ignore SSL option. Either way, the sensor logs once per host that verification is off.

TODO

Document how to make the sensor trust a TLS-inspecting proxy's CA. The sensor verifies certificates against the CA bundle in its image, so a CA installed on the host does not reach it.

Logging​

The sensor logs to two places at once:

  • Its console output, which Docker keeps according to the compose file's logging section. Read it with sudo docker compose logs -f.
  • The log file, logs/agent.log in the mounted logs/ folder. It is rotated at 10 MB, and five earlier files are kept.

Raise LE_LOGGING_LEVEL to DEBUG only while investigating; it is verbose.

Concurrency​

global.max_concurrent_tasks is how many scans the sensor runs at once. Further scans wait as Queued in the console until one finishes, and are picked up on a later poll. Connection tests have one extra slot of their own, so they never wait behind a long scan, and a self-test runs outside the slots altogether. A value below 1 means 1; one that is not a whole number means the default, 4.

Raise it on a sensor with spare CPU and memory that runs many short integrations; lower it on a small host, or one whose active scans load the network.

Self-test thresholds​

The self-test grades some of its checks against thresholds. Change them in the config file, under selftest, using the check's id with dots replaced by underscores. List a check's id under selftest.disabled to skip it:

config.json
{
"selftest": {
"host_cpu": {"warn_percent": 90},
"disabled": ["network.raw_sockets"]
}
}
CheckSettingDefault
host.cpu (CPU load, warn and fail at or above)warn_percent, fail_percent80, 95
host.memory (memory available, warn and fail below)warn_percent, fail_percent20, 10
host.disk.data, host.disk.logs (free space, warn and fail below)warn_mib, fail_mib2048, 512
backend.api (round trip to the console, warn above)warn_ms2000
backend.clock (clock drift from the console, warn and fail at or above)warn_seconds, fail_seconds30, 300

Start it​

From the folder with docker-compose.yml:

sudo docker compose up -d

On its first start the sensor enrols with the token and then appears in Settings → Sensors. If you left the Add sensor dialog open, it tells you when the sensor has enrolled and offers to connect an integration through it.

If the sensor does not appear, read its output with sudo docker compose logs -f. The effective configuration printed at startup shows which console it is talking to, and a rejected token and an unreachable console fail differently there. A tenant that has reached its sensor limit also refuses the registration.

Remove the token once the sensor has enrolled

TOKEN is only read during enrolment. Once the sensor has registered and stored its own API token in the mounted data directory, delete the TOKEN line: the sensor keeps running and restarting without it, and a stale deployment token stops sitting in a file that tends to end up in version control.

If you would rather keep it out of the compose file from the start, put it in a .env file beside it and reference it as TOKEN: ${TOKEN}.

The stored API token is the sensor's identity

It is long-lived by design, so anyone who copies it can act as that sensor until the token is revoked. Treat the data directory as secret. If a host is compromised, or a copy of the token may have leaked, use Revoke token on the sensor's detail view; delete the sensor from the console when a host is decommissioned.

After the first check-in​

Rename the sensor from its detail view. Registration names it Sensor-<hostname>, and something that says where it sits is what you will want when you start assigning integrations to it. Run a self-test to confirm the host has what the sensor needs. Then assign the integrations it is meant to run; see Integrations.

See also​