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
| Requirement | Detail |
|---|---|
| Operating system | Linux on x86-64 (amd64). The image is published for that architecture only |
| Container runtime | Docker Engine with the Compose plugin (docker compose) |
| Privileges | Administrator rights to run Docker, typically sudo |
| Network | Outbound HTTPS to the console, directly or through a proxy. See Network requirements |
| Folder | An 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:
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:
| Key | Why it is there |
|---|---|
image | The sensor build to run. Pin it, so a redeploy is a decision rather than a surprise |
container_name | A fixed name for the container, so docker commands on the host can refer to it |
restart: unless-stopped | The sensor comes back with the host and after a crash, unless you stopped it yourself |
network_mode: host | Gives 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 |
MODE | What the container does at startup. See Modes |
TOKEN | The deployment token from the previous step. Read during enrolment only |
LE_SERVER_HOST | The console the sensor reports to: your console's address, including https://. The dialog fills in the address you opened it from |
LE_SECURE | Whether the console's TLS certificate is verified. See TLS |
volumes | The 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, tmpfs | The 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_add | The 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_opt | Nothing in the container can gain further privileges |
logging | Caps 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.
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.
| Mode | Behaviour |
|---|---|
connect_and_run | Enrol with TOKEN if there is no stored token, then run. The usual choice, and what the console's compose file uses |
connect | Exchange TOKEN for an API token, store it, and exit |
run | Start the polling loop with an already-stored token. It never enrols, so a fresh install in this mode never appears in the console |
reset | Delete 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
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 container | On the host | Holds |
|---|---|---|
/root/integration-app/data | ./data | The sensor's API token (token.dat) and the working folders where task results are staged before they are uploaded. Required |
/root/integration-app/logs | ./logs | The 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.json | Your choice, mounted read-only | An optional config file. Without it the sensor runs on its defaults and the LE_ variables |
/tmp | In memory (tmpfs) | Temporary files. Cleared whenever the container restarts |
Configuration reference
The sensor builds its configuration from three layers, each overriding the one before:
- Built-in defaults.
- The config file, if there is one.
LE_environment variables, set underenvironmentin 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.
| Setting | Environment variable | Default | Meaning |
|---|---|---|---|
server.host | LE_SERVER_HOST | A built-in address that is not your console | The console this sensor reports to, with scheme and optional port, such as https://<your-organization>.velumedge.com. Always set it |
secure | LE_SECURE | true | Whether the console's TLS certificate is verified. See TLS |
proxy | LE_PROXY | null (no proxy) | The proxy for outbound calls, as a JSON object of scheme to proxy URL. See Proxy |
global.sleep_period | LE_GLOBAL_SLEEP_PERIOD | 30 | Seconds between polls of the console |
global.max_concurrent_tasks | LE_GLOBAL_MAX_CONCURRENT_TASKS | 4 | How many scans the sensor runs at once. See Concurrency |
global.request_timeout | LE_GLOBAL_REQUEST_TIMEOUT | 180 | How 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.level | LE_LOGGING_LEVEL | INFO | DEBUG, INFO, WARNING, ERROR or CRITICAL. Anything else means INFO |
logging.file | LE_LOGGING_FILE | logs/agent.log | The log file, relative to /root/integration-app. Keep it inside the logs volume |
logging.format | LE_LOGGING_FORMAT | %(asctime)s - %(levelname)s - %(filename)s:%(lineno)d - %(message)s | The layout of each log line, in Python logging format |
logging.time_format | LE_LOGGING_TIME_FORMAT | null | A strftime format for the timestamp; null keeps the standard one |
logging.create_dir_is_not_exists | LE_LOGGING_CREATE_DIR_IS_NOT_EXISTS | true | Whether the log file's folder is created if it is missing |
These variables are not settings, and keep their names:
| Variable | Meaning |
|---|---|
MODE | What the container does at startup. Required. See Modes |
TOKEN | The deployment token. Read only when the sensor enrols |
LE_CONFIG_PATH | Where 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_TYPE | Set 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,onand1are true;false,no,offand0are false. Quote them in the compose file (LE_SECURE: "true"). null,noneand~set a value tonull.- A value starting with
{or[is read as JSON, which is howLE_PROXYtakes 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.
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:
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:
{
"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.
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.
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.
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
loggingsection. Read it withsudo docker compose logs -f. - The log file,
logs/agent.login the mountedlogs/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:
{
"selftest": {
"host_cpu": {"warn_percent": 90},
"disabled": ["network.raw_sockets"]
}
}
| Check | Setting | Default |
|---|---|---|
host.cpu (CPU load, warn and fail at or above) | warn_percent, fail_percent | 80, 95 |
host.memory (memory available, warn and fail below) | warn_percent, fail_percent | 20, 10 |
host.disk.data, host.disk.logs (free space, warn and fail below) | warn_mib, fail_mib | 2048, 512 |
backend.api (round trip to the console, warn above) | warn_ms | 2000 |
backend.clock (clock drift from the console, warn and fail at or above) | warn_seconds, fail_seconds | 30, 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.
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}.
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
- Upgrade a sensor on Linux (Docker) — when a new build ships
- Sensors — what a sensor does, requirements and placement