HTTPS & Certificates

When an app on a connected device exposes a web interface, the appliance makes it reachable through its built-in tunnel. You choose how browsers reach the appliance — there are three modes, from zero setup to fully corporate-signed. Pick one and follow its steps.

Not the same as Behind a Corporate Proxy. That page is about the appliance trusting your corporate CA for outbound traffic (appliance → cloud, through a TLS-intercepting proxy). This page is the opposite direction — inbound traffic from browsers on your network reaching the appliance. The two are independent.

Mode 1 — Plain HTTP (default)

What you get. Everything over plain HTTP on the appliance’s address:

Each app UI is published on its own automatically-assigned port; the IronFlock UI shows the exact link for each one. App UIs stay behind the appliance login — opening one redirects to the login unless you’re signed in and authorized for that device (a port can be marked public per app where you want it open).

What you need to do. Nothing. This is the default — just use the appliance’s IP or hostname on your local network. No DNS, no certificate, no involvement from corporate IT.

When to use it. An appliance on a trusted, segmented network — a control cabinet on a machine/OT VLAN — where plain HTTP is the norm and access is controlled by network segmentation and physical security.

Mode 2 — HTTPS with a self-issued CA

What you get. The appliance turns on its built-in HTTPS ingress and serves everything over HTTPS under your domain — using a certificate it generates itself. There’s no reverse proxy to run and no URLs to rewire; the installer wires it all up.

What you need to do.

1. Choose a domain that resolves to the appliance for every browser and device that will use it, and set both APPLIANCE_HOST and APPLIANCE_DOMAIN to it. Because the appliance issues the certificate itself, any name works — the only requirement is that it resolves. For anything beyond a quick test use an internal domain you control (e.g. appliance.corp.example.com) with a wildcard record in your own DNS: an isolated or DNS-restricted appliance network usually can’t reach the public nip.io service that the default <host-ip>.nip.io name relies on. (That default does work where the network can reach the internet — which is why it works on a dev machine.)

2. Add wildcard DNS for the domain, both records pointing at the appliance host IP:

   • *.<APPLIANCE_DOMAIN> — covers the app UIs and every service subdomain.
   • <APPLIANCE_DOMAIN> (apex) — the main UI by name.

   (A wildcard-DNS service like nip.io already resolves these automatically, so there are no records to add — but it depends on that external service being reachable.)

3. Install with --tls:

   curl -fsSL https://instance-registry.ironflock.com/dl/appliance/install_ironflock.sh \
     | sudo bash -s -- <your-instance-key> --interactive --tls

   --interactive prompts for APPLIANCE_HOST / APPLIANCE_DOMAIN (or set IRONFLOCK_APPLIANCE_HOST / IRONFLOCK_APPLIANCE_DOMAIN for an unattended install). The appliance generates a local CA at /opt/ironflock/certs/ca/rootCA.crt and a wildcard certificate signed by it.

4. Distribute the CA root to client machines. Push rootCA.crt via your MDM, or add it to each machine’s OS/browser trust store. Until a machine trusts it, its browser warns.

5. Renew within a year. The server certificate is capped at ~1 year — browsers reject longer-lived ones. To renew, delete tls.crt/tls.key in the certificate directory and re-run the installer; it re-signs a fresh certificate against the same CA, so the trust you distributed keeps working.

Devices stay on the plain IP path. Only the browser side moves to HTTPS. Connected devices keep reaching the appliance over its IP, so you don’t have to install the CA on every device.

When to use it. You want HTTPS on a shared network but don’t have (or don’t want to wait for) a certificate from corporate IT, and you can push a root CA to the machines that will open the UI.

Mode 3 — HTTPS with your corporate certificate

What you get. The same full-appliance HTTPS as Mode 2 — but the certificate comes from your organization’s CA, whose root is already trusted on every managed machine. No browser warnings, nothing to distribute. Devices move onto the domain too.

What you need to do.

1. Choose an internal domain you control and set APPLIANCE_HOST and APPLIANCE_DOMAIN to it (e.g. appliance.corp.example.com). Here it must be your own domain — a CA only issues certificates for domains you own, so a nip.io name won’t work in this mode.
2. Add wildcard DNS — *.<APPLIANCE_DOMAIN> and the apex, pointing at the appliance host IP — as in Mode 2, step 2.
3. Get a wildcard certificate for *.<APPLIANCE_DOMAIN> from your internal CA, as two PEM files: tls.crt (ideally full-chain) and an unencrypted tls.key.
4. Install with your certificate:

   curl -fsSL https://instance-registry.ironflock.com/dl/appliance/install_ironflock.sh \
     | sudo bash -s -- <your-instance-key> --interactive \
         --tls-cert /path/to/wildcard.crt \
         --tls-key  /path/to/wildcard.key

   --tls-cert implies --tls. Equivalent env vars: IRONFLOCK_TLS_CERT / IRONFLOCK_TLS_KEY.
5. Rotate on your CA’s schedule. Drop the new PEM files into the certificate directory and restart:

   sudo cp wildcard.crt /opt/ironflock/certs/tls.crt
   sudo cp wildcard.key /opt/ironflock/certs/tls.key
   sudo chmod 0600 /opt/ironflock/certs/tls.key
   sudo systemctl restart ironflock.service

   The appliance reloads the certificate automatically when the file changes; the restart just applies it immediately. Re-running the installer never overwrites an existing certificate unless you pass --tls-cert.

Devices move to the domain too. Because the certificate is trusted fleet-wide, device traffic — the device link and container-image pulls — also runs over the domain via TLS, and the insecure-registries workaround is no longer needed.

When to use it. The standard corporate on-prem path: your organization already runs an internal CA, so a wildcard certificate is issued once and trusted everywhere with zero per-machine setup.

Troubleshooting

An app UI link doesn’t open / connection refused. In plain mode app UIs are at http://<host>:<port> — make sure you’re using the exact link shown in the IronFlock UI (the port is assigned per app), and that nothing on the network blocks that port.

Browser warns the certificate is not trusted (after --tls). The client doesn’t yet trust the certificate’s CA. In Mode 2, deploy the appliance-generated CA (/opt/ironflock/certs/ca/rootCA.crt) to the client. In Mode 3, make sure the client trusts your internal CA root.

Certificate expired (self-issued). A self-issued server certificate is valid for about a year (browsers reject longer-lived ones). Renew it: delete tls.crt/tls.key in the certificate directory and re-run the installer to re-sign against the same, still-trusted CA — or switch to a --tls-cert from your own CA.

Certificate name mismatch. The certificate isn’t a wildcard for the domain in use. It must cover *.<APPLIANCE_DOMAIN>, and the URL’s domain must match APPLIANCE_DOMAIN.

A subdomain doesn’t resolve (after --tls). Wildcard DNS is missing. Add a *.<APPLIANCE_DOMAIN> A record pointing at the appliance host — it covers the app UIs and every service subdomain.