IPTunnel Documentation
Back Home
SlowDNS

Activation Lifecycle

What happens from the moment you generate a code to the moment the install is confirmed, including the precheck step and failure recovery path.

The five steps

Every SlowDNS installation goes through five license-server interactions:

  1. Issue — You click Generate Code in the panel. The server creates a single-use IPT-SD-... code with a 5-minute TTL and returns it.
  2. Precheck — The installer sends only the code plus machine identity (machine-id and SSH host fingerprint). The server validates the code without consuming it and returns a signed 15-minute precheck token.
  3. Activate — After the operator confirms hostname and public IP, the installer sends the code, precheck token, machine identity, hostname, and IP. The server marks the code as consumed, increments its activation counter, and returns a signed 10-minute install token bound to that machine and configuration.
  4. Confirm — After all services are verified active, the installer sends the install token back. The server marks it as used. The install is complete.
  5. Release (on failure only) — If the installer exits before reaching confirm, its EXIT trap calls release. If the install token has not been used and has not expired, the code is restored to issued and the activation counter is rolled back so the operator can retry.

About the signed tokens

The license flow uses two signed tokens:

  • Precheck token — issued after code validation. It contains the code, hashed machine identity, requested product, installer version, and a 15-minute expiry. The installer cannot activate without it.
  • Install token — issued after activation. It contains the activation ID, hashed machine identity, hostname, public IP, installer version, requested Git ref, and a 10-minute expiry.

The install token is an HMAC-SHA256 signed structure (similar in shape to a JWT) that contains:

  • The activation ID (sub)
  • SHA-256 hashes of the machine-id and SSH fingerprint (mid, ssh)
  • The public IP and hostname sent at activation time
  • The installer version and requested Git ref
  • Issue time (iat), expiry time (exp), and a unique nonce (jti)

The install token expires 10 minutes after activation. It can only be confirmed once — a second confirm attempt returns token_used.

Install code states

State Meaning
issued Generated, not yet used, not yet expired. Ready for precheck or activate.
consumed Activate was called. The install is in progress or already confirmed. The code cannot be reused while in this state.
expired The 5-minute window elapsed without activation. The code is permanently unusable.

Precheck does not change the code state. A consumed code returns to issued only if the release endpoint is called, the install token was never used, and the install token has not expired. The activation counter is rolled back at the same time.

Maximum activation attempts

Each install code has a hard limit of 5 activation attempts. This prevents an attacker from activating and releasing the same code in a loop to probe the system. Failed installs that properly release the code have their counter rolled back, so a legitimate operator retrying after a genuine failure will not hit this limit in normal use.

Once the limit is reached, generate a new code.