๐ Certificates for Bumper¶
Bumper serves TLS for the app, robots, and its web UI. The certificates are self-signed: clients must trust Bumper's CA, and the server certificate must cover the Ecovacs hostnames clients connect to.
๐ฆ Files¶
Both creation methods produce the same files:
| File | Created by | Purpose |
|---|---|---|
ca.key |
scripts/certs/create-cert.sh or bumper/utils/certs.py |
Root CA private key |
ca.crt |
scripts/certs/create-cert.sh or bumper/utils/certs.py |
Root CA certificate - install/trust this on app and clients |
bumper.key |
scripts/certs/create-cert.sh or bumper/utils/certs.py |
Server private key |
bumper.crt |
scripts/certs/create-cert.sh or bumper/utils/certs.py |
Server certificate signed by the CA |
ca.pem |
scripts/certs/create-cert.sh or bumper/utils/certs.py |
Server key + server certificate + CA certificate (for mitmproxy) |
Default key type is EC. Use RSA when a robot requires it: --rsa with the
script, or CERT_KEY_TYPE=rsa with startup generation. The SAN list is defined
by each implementation (scripts/certs/create-cert.sh and
bumper/utils/certs.py).
๐งฐ Option 1 - Create certificates with the host script¶
The script uses OpenSSL on the host and writes files to $PWD/certs:
Behavior (idempotent):
- if
ca.crtorca.keyis missing, it creates a new CA and a new server certificate; - if the CA exists but
bumper.crtorbumper.keyis missing, it creates a new server certificate and keeps the existing CA (clients that already trust the CA keep working); ca.pemis rebuilt if it is missing.
Use this when you want to create or rotate certificates yourself before starting Bumper.
๐ Option 2 - Let Bumper generate certificates at startup¶
bumper.utils.certs.generate_certificates() runs during Bumper startup, before
services listen. It writes the same five files to BUMPER_CERTS (default
$PWD/certs / /bumper/certs in containers) when the directory is writable.
Behavior:
- if
ca.crt,bumper.crt, andbumper.keyall exist, generation is skipped (existing certificates are kept); ca.keyis not part of that existence check, so removing onlyca.keydoes not trigger a new CA;- if only
ca.pemis missing, it is rebuilt from the existing key and certificates; - changing
CERT_KEY_TYPElater does not convert an existing certificate set.
Startup generation requires a writable certificates directory owned by (or
writable for) the Bumper process (uid/gid 1000 in the container image). The
checked-in Docker image starts as root, repairs ownership of /bumper/data and
/bumper/certs when it can (CAP_CHOWN), then drops to bumper.
Generation settings¶
| Variable | Default | Effect |
|---|---|---|
BUMPER_CERTS |
./certs |
Directory for generated files |
CERT_KEY_TYPE |
ec |
ec (ECDSA P-256) or rsa |
CERT_RSA_KEY_SIZE |
2048 |
RSA key size when CERT_KEY_TYPE=rsa (2048-4096) |
BUMPER_CA_VALID_DAYS |
6669 |
CA validity in days |
BUMPER_VALID_DAYS |
666 |
Server certificate validity in days |
Individual paths can be overridden with BUMPER_CA_CERT, BUMPER_CA_KEY,
BUMPER_CA_PEM, BUMPER_CERT, and BUMPER_KEY.
๐ณ Checked-in Docker/Compose behavior¶
The checked-in docker-compose.yaml and docker-compose-traefik.yaml load
ca.crt, bumper.crt, and bumper.key as Docker configs from $PWD/certs/*
and mount them read-only at /bumper/certs. The source files must exist before
deployment:
After creating them, install certs/ca.crt on devices/clients that need to
trust Bumper.
Bumper's startup generation needs a writable /bumper/certs
directory, so it does not run with these read-only config mounts. For a custom
deployment where you want Bumper to generate certificates, mount a writable
directory/volume at /bumper/certs instead of read-only config files. In
Docker Swarm, host bind mounts are node-local; ensure the directory exists and
is writable on the node that runs the task, or pre-create certificates with the
host script (recommended for the checked-in Swarm files).
๐ Custom certificates¶
To use your own CA and server certificate, place files in the certificates directory before starting Bumper:
ca.crt,bumper.key,bumper.crtfor Bumperca.pemfor mitmproxy (optional)
The server certificate must include the Ecovacs hostnames and local addresses
clients use. ca.pem contains the server private key; treat it as a secret and
use it only for local tooling such as mitmproxy.
๐งช mitmproxy¶
Mount ca.pem into mitmproxy:
docker run --rm -it \
-v $PWD/certs/ca.pem:/home/mitm/ca.pem:ro \
mitmproxy/mitmproxy mitmweb \
--certs '*=/home/mitm/ca.pem'
ca.pem is only needed by mitmproxy; Bumper uses the individual CRT/KEY files.