Security
The appliance runs on hardware and in a network that you operate. IronFlock provides the software and its defaults; how well the appliance is protected also depends on the mode you choose, the network around it and the host it runs on. This page is the checklist for that part.
What Each Mode Protects
The appliance runs in one of three modes, described in HTTPS & Certificates. They differ in what is encrypted and verified:
| Plain HTTP (default) | HTTPS with a self-issued CA | HTTPS with your corporate certificate | |
|---|---|---|---|
| Browser to appliance | Unencrypted | HTTPS | HTTPS |
| Login cookies | Not marked secure | Secure | Secure |
Device link (port 18080) | Unencrypted | Unencrypted | HTTPS on 443 |
| App images and agent updates for devices | Unencrypted | Unencrypted | HTTPS on 443 |
| Remote-access tunnel of devices | Encrypted, server not verified | Encrypted, server not verified | Encrypted and verified |
| Passkeys and security keys | Only from the appliance itself | Yes | Yes |
Use HTTPS with your corporate certificate wherever the appliance shares a network with other systems. It is the only mode in which connected devices verify whom they talk to. The other two modes are suited to a network segment that only the appliance, its devices and its operators can reach.
What Stays Unencrypted
Even with HTTPS, some traffic is not encrypted. Plan your network around it:
- The device link on port
18080is published on every network interface in every mode. The appliance’s own device agent and the apps running on the appliance connect to it, and in plain mode and with a self-issued CA so do all connected devices. - Remote-access tunnels to the appliance (port
7000) are encrypted in plain mode and with a self-issued CA, but devices cannot check the appliance’s certificate. Someone with access to the network path could pose as the appliance’s tunnel server. Device agents log a warning when they connect this way. - Connections between the services inside the appliance, such as to its databases, are not encrypted. They do not leave the host.
- Data at rest is not encrypted by the appliance. Use the encryption of the host’s operating system or disk if the appliance stores sensitive data or may leave your premises.
Hardening Checklist
- Choose the mode that fits your network (see What Each Mode Protects).
- Restrict who can reach the appliance’s ports. The install opens nothing in your firewall, and Docker publishes the appliance’s ports past the host firewall’s usual input rules (
ufw,firewalld). Filter in theDOCKER-USERchain or at your network firewall: the install leaves a template at/opt/ironflock/docker-user-firewall.sh.example. Allow the device ports (18080,15001,15002,7000,30000–30049) only from your device networks — see Devices Connecting to the Appliance. - Keep the host’s operating system up to date and limit who has an account on it. Anyone with root access on the host can read every secret of the appliance.
- Use SSH keys instead of passwords for administrative access to the host.
- Configure time synchronization — see Time Synchronization (NTP).
- Change the admin password after the first login and set up a second factor for the admin account.
- Require a second factor for everyone once all accounts have one (see Accounts and Access).
- Protect the ironflock.com account that owns the instance with a second factor: it has admin access to the appliance from the cloud.
- Switch off the cloud connection if nobody needs to work on the appliance from ironflock.com (see Cloud Connection).
- Install only apps you trust. Apps run on the appliance and on your devices with extensive access to the host, including the appliance’s configuration files.
- Keep the appliance updated (see Updates).
- Verify
ironflockbefore the first installation (see VerifyironflockBefore the First Installation).
Accounts and Access
- Admin account: every appliance gets its own admin password at installation;
ironflock appliance installshows it once. If it is lost, set a new one as described in Local Operation — this also signs out every admin session. - New users can only sign up with an invitation from a project on the appliance. Without an invitation, sign-up is refused, also through social login.
- Second factor: users can set up an authenticator app (TOTP), passkeys or security keys, and recovery codes. Passkeys and security keys need HTTPS. The option
--2faofironflock appliance installorironflock appliance configuresets the policy, and it stays set across updates:available— users can set up a second factor, but are never asked for it.effective(default) — users who have a second factor must use it.required— every user must use a second factor. Make sure every account has one first: a user without one can no longer sign in.
- Sessions last 24 hours.
- Access from ironflock.com: the ironflock.com account that created the instance key is connected to the appliance’s admin account. Users you invite connect their own ironflock.com accounts — see Linking Accounts. A user can remove that connection at any time. To stop all access from ironflock.com, the admin switches off the cloud connection.
Secrets on the Host
ironflock appliance install generates the appliance’s secrets once, at installation, and keeps them across updates. They live under /opt/ironflock/:
| File | Contents | Access |
|---|---|---|
.env | Passwords and keys of all services, the initial admin password, proxy and SMTP credentials | Root only (0600) |
license.env | The instance key, and what the license validation stores with it | Root and the IronFlock services (0640) |
certs/ | The HTTPS certificate and key; with a self-issued CA also the CA’s key | Private keys root only (0600) |
registry-token-certs/ | The key that signs app image pull tokens | The registry service only (0600) |
.env.prev, rotation.log | The .env before the last rotation; when which secret was rotated, without values | Root only (0600) |
The install also logs Docker in to the IronFlock registry with your instance key, so root’s Docker configuration holds it as well.
Include these files in your backups and protect the backups like the appliance itself. Never delete .env or let an install generate it again: the databases and the encrypted data depend on its values. To replace a secret, rotate it.
What you can replace yourself:
- Admin password: in the profile, or with
sudo ironflock appliance reset-admin-password(see Local Operation). - HTTPS certificate: your own certificate with
sudo ironflock appliance configure --tls-cert <file> --tls-key <file>(see HTTPS & Certificates). A certificate from the appliance’s own CA renews itself: a weekly check signs a new one when fewer than 30 days remain. - Instance key: in the license section of the admin profile, or with
sudo ironflock appliance configure --license-file <file>, where the file holds the new key. The new key must open the IronFlock registry before it is written. - SMTP credentials: in
.env, then restart withsudo ironflock appliance restart. - Proxy: with
sudo ironflock appliance configure(see Behind a Corporate Proxy). - Internal service secrets:
sudo ironflock appliance rotate <NAME>, see below.
Rotating an Internal Secret
sudo ironflock appliance rotate <NAME> gives one secret of .env a new value while the appliance runs. The new value goes where the old one is held first (a database role, the agent’s device file, the registry’s token key pair), then into .env. Only the services that read the secret are recreated, and the command checks that they are healthy. The .env before the change stays as .env.prev, and rotation.log lists each rotation, never a value. ironflock appliance rotate --help lists the names it can rotate. See ironflock appliance rotate.
Run rotations over SSH or on the appliance’s console, not in the terminal of the appliance’s own device in IronFlock: a rotation that restarts the services this terminal depends on cuts it.
| Secrets | What a rotation does |
|---|---|
WAMP_SECRET_SVC_*, WAMP_SYSTEM_SECRET and the other service secrets | The services that use it restart; their connections come back within seconds. |
KRATOS_SECRETS_COOKIE | New sign-ins use the new key; sessions signed in before stay valid, because the previous key is kept until the next rotation. |
POSTGRES_PASSWORD, PGPASSWORD_*, DATASERVICE_PASSWORD | The database role gets the new password, then its services restart. Asks first; --yes answers. |
REGISTRY_TOKEN_KEY | App image pull tokens are signed with a new key; tokens signed before stay valid until the next rotation. Asks first; --yes answers. |
APPLIANCE_DEVICE_SECRET | The appliance’s own device gets a new credential; its agent restarts and is back online within a minute. Asks first; --yes answers. |
FILE_CRED_KEY | The apps keep their files; their access to the storage moves to the new key. For the apps’ direct S3 credentials, choose --keep-direct-access or --revoke-direct-access. Kept credentials go on working, for a scheduled rotation: anyone who knows the previous key can still derive them, so each app’s storage settings mark them for replacement, and sudo ironflock appliance revoke-direct-access later removes the ones left. Revoked credentials stop working and are removed at once, for example after a suspected leak. Asks first (--yes answers) and needs appliance version 1.6.23 or later. |
APPLIANCE_ADMIN_PASSWORD | A new initial admin password, the same as ironflock appliance reset-admin-password. |
Rotate FLEETDB_SECRET_KEYS, KRATOS_SECRETS_CIPHER and the two OBJECTSTORE_ADMIN_* keys only together with the IronFlock team: data stored with them depends on them. The instance key is changed in the admin profile or with ironflock appliance configure, not with rotate.
Outbound Connections and Telemetry
The destinations the appliance connects to are listed in Firewall Configuration; all of these connections are encrypted.
- License validation sends the license key, a fingerprint of the hardware and the access tokens of the appliance’s connections to the online App Store.
- The AI assistant sends prompts through IronFlock’s LLM gateway, unless you configure a gateway of your own.
- No telemetry. The appliance sends no usage analytics: neither the appliance UI nor its services report usage to IronFlock or third parties.
- From the user’s browser: map tiles are loaded from Mapbox, and voice input uses the speech recognition service Deepgram. These connections are made by the browser, not by the appliance.
Updates
- Appliance updates are started by the admin (see Maintenance) and signed by IronFlock.
ironflockchecks the list of available versions and the release manifest of the new version against the appliance release key it carries, then every file of the new version and every container image against that manifest. A changed or unsigned file, or any image other than the released one, stops the update before anything on the appliance changes. An update never moves the appliance back to an older version on its own, and if an update fails, the appliance returns to the version it ran before. - Device agent updates are signed. Every agent checks the signature before it applies an update and rolls back if the new version does not start — see Device Agent Updates.
- The host’s operating system is your responsibility, including Docker.
Verify ironflock Before the First Installation
The appliance checks every update by itself: ironflock checks each release of the appliance against the IronFlock appliance release key it carries, before it installs it. What you take on trust is the install script of ironflock, which runs as root. Check it before it runs, as described in Verify the Install Script First: gpg must report a good signature by the IronFlock Bootstrap key with the fingerprint F6C9 4D96 CE31 5377 ACA7 C8EA 4990 5433 7321 2788. The script in turn checks ironflock against that key before it installs it. Both keys are listed on Signing Keys.
Backup and Restore
To back up the whole appliance, stop it with sudo ironflock appliance stop and copy:
- the folder
/opt/ironflock/, including.env,license.env,certs/andregistry-token-certs/; - the Docker volumes of the appliance (
docker volume ls), which hold the databases, files, the local App Store and the user files.
Then start it again with sudo ironflock appliance start. Keep .env together with the volumes of the same point in time: the encrypted data in the volumes can only be read with the keys in that .env.
The secrets alone can be saved while the appliance runs:
sudo ironflock appliance backup -o /root/appliance-secrets.tar.gzThe archive holds .env, license.env, the CA, the registry token keys, the register of secrets and rotation.log; only root can read the file. A lost FLEETDB_SECRET_KEYS or FILE_CRED_KEY cannot be recovered any other way: encrypt the archive and keep it with the volume backups.
To put the secrets back on an installed appliance, restore with --force while it runs, then restart it so that every service reads the restored files:
sudo ironflock appliance restore appliance-secrets.tar.gz --force
sudo ironflock appliance restartThe appliance’s .env before the restore stays as .env.prev. On a new machine, install ironflock, run sudo ironflock appliance restore appliance-secrets.tar.gz, then install the appliance as usual, with the instance key and the options used before, such as --tls. See ironflock appliance backup and ironflock appliance restore.
Decommissioning
-
Move or release the license while the appliance is still online — see Moving Your License to New Hardware.
-
Remove the software:
sudo ironflock appliance remove --purge sudo ironflock agent removeironflock appliance remove --purgeremoves the appliance’s services, containers and network, Docker’s login to the IronFlock registry, the changes its install made on the host, and with--purgealso its data: the install directory/opt/ironflockwith.envandlicense.env, the Docker volumes and the images.ironflock agent removethen removes the appliance’s own device agent. Each command lists what it removes and asks first;--yesanswers. Docker itself stays installed, and so doesironflockin/usr/local/bin. Seeironflock appliance removeandironflock agent remove. -
If the hardware leaves your premises, erase its disk — the commands above delete files, but do not overwrite them.
Settings That Weaken Security
Some settings exist for troubleshooting only. Leave them unset in production:
AGENT_UPDATE_ALLOW_UNSIGNED— lets a device agent apply unsigned updates. It works only asuntil=<time>at most 24 hours ahead and then runs out by itself.TUNNEL_AUTHZ_ENFORCE=false— lets devices open tunnels without proving their identity.?tls.rejectUnauthorized=falseinSMTP_CONNECTION_URI— accepts any certificate from your mail server.--2fa available— second factors are never asked for.