Skip to content

rpotctl CLI reference

rpotctl is the deployment tool inside the ReD-Pot image. The installer uses it to create the persona, baits, certificates and compose file. Most administrators never call it directly: use install.sh for anything that changes an install, because the installer also updates the firewall, the systemd unit, INSTALL-INFO.txt and the login banner.

Changing commands

init, baits, tls --renew, compose, add-sensor and remove-sensor rewrite parts of a deployment. On a production manager, use install.sh (add-decoy, remove-decoy, set-access, reset-token) instead. Back up /opt/redpot/manager first if you do use them.

How to run it

Commands that take -d DIR work on the manager directory, mounted into a throw-away container:

sudo docker run --rm --user 0 -v /opt/redpot/manager:/d rpot:1.0.1 ctl <command> -d /d [options]

slots and export read the live database, so they run inside the console container:

sudo docker exec redpot-console-1 python /opt/rpot/rpotctl.py <command> \
     --db /var/lib/rpot/rpot.db --config /etc/rpot/rpot.json [options]
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/python rpotctl.py <command> ...

python3 rpotctl.py --help and python3 rpotctl.py <command> --help list the options.

Commands

roles

Lists the decoy roles from the role catalog (roles/*.json).

init

Creates a new deployment in a directory: persona, baits, certificates, rpot.json. Used by the installer and the lab.

Option Meaning
-d, --dir DIR deployment directory (required)
--domain DOMAIN AD/DNS domain (required)
--profile bank, generic, government, hotel or it (default generic)
--web-theme webmail (default), helpdesk or intranet
--sensor SPEC a decoy; repeat up to 3 times. Host mode: HOSTNAME=role@IP%IFACE; bridge lab: HOSTNAME=role[@IP]
--net-mode host (production: each decoy on its interface's own IP) or bridge (isolated Docker lab, default)
--subnet, --console-ip bridge lab only: the lab network and the manager's address on it
--ui-port, --sensor-port host ports of the web UI (default 8740) and sensor API (default 8741)
--public-ip, --mgmt-ip static public IP; management interface IP (UI and sensor API are published only there)
--canary-url URL clients use to reach the console for bait-document beacons
--allow CIDR scanner allow-list entry (repeatable)
--internal CIDR extra internal network, for example your own public range (repeatable)
--site-name, --site-lat, --site-lon site location on the world map
--force overwrite an existing deployment

baits

ctl baits -d DIR plans the baits for the current decoy set. Existing honeytokens are kept; crumbs for new decoys are added. Restart the containers afterwards.

tls

ctl tls -d DIR shows the manager certificate (subject, issuer, SANs, SHA-256 fingerprint). --renew re-issues it and re-keys the local decoys. Remote sensors pin the old fingerprint and must join again with a new join string.

compose

ctl compose -d DIR [--image IMAGE] [--ui-bind IP] writes the Docker Compose file for the deployment.

show

ctl show -d DIR prints the persona, the decoys and every honeytoken in plaintext (user, password, where it is valid, where it is planted). Treat the output as secret.

add-sensor / remove-sensor

ctl add-sensor -d DIR --sensor SPEC and ctl remove-sensor -d DIR --name NAME add or remove a local decoy. The installer's add-decoy and remove-decoy call these and also handle the firewall, SSH and the self-test.

wall-url

ctl wall-url -d DIR [--base URL] [--rotate] prints the read-only kiosk link. --rotate issues a new token and invalidates old links. install.sh reset-token --wall does the same and restarts what is needed.

geoip

ctl geoip -d DIR [--city] downloads the DB-IP Lite country and ASN databases (about 18 MB). --city also fetches the city database (about 130 MB) for precise map points. Lookups are offline afterwards. install.sh geoip is the usual way.

site

ctl site -d DIR --name NAME --lat LAT --lon LON sets where decoys on private addresses are drawn on the world map. Restart the manager afterwards.

sudo docker run --rm --user 0 -v /opt/redpot/manager:/d rpot:1.0.1 ctl site -d /d --name "Yerevan HQ" --lat 40.18 --lon 44.51
sudo ls -ln /opt/redpot/manager/rpot.json     # check owner and mode, see below
sudo systemctl restart redpot

Keep rpot.json readable by the console

Commands that save rpot.json write a new file with mode 0600, owned by the user that ran them (root with --user 0). The console container runs as uid 10001 and reads rpot.json. If ls -ln shows another owner than the one the file had before (on a standard install, uid 10001), restore it, for example sudo chown 10001:10001 /opt/redpot/manager/rpot.json, before restarting.

slots

rpotctl.py slots --db DB --config CONFIG prints the decoy slot counts as one JSON line: {"max": 3, "used": ..., "local": ..., "remote": ..., "pending": ...}.

export

rpotctl.py export --db DB --config CONFIG --from YYYY-MM-DD --to YYYY-MM-DD writes the JSON export of incidents and alert records for those UTC days to standard output. Exit code 2 = bad range, 3 = too large. See Export.