13. Remote deployment from the console

Remote deployment installs the agent on many hosts from the console. The server logs in to each host with a stored technical account (SSH for Linux and macOS, WinRM for Windows), checks the host, and runs the same installer as the copy-paste command, with a one-time token in place of the enrolment secret.

Where: Environment > Hosts, panel Deploy agents remotely below the agent list. The Install agent > Remote deployment tab has an Open remote deployment button that scrolls to it.

Prepare the hosts first: Windows hosts (WinRM), Linux hosts (SSH, below in 13.2).

13.1 Permissions and four-eyes#

Four-eyes is the critical action Deploy agents remotely. A test and a deployment log in with the stored secret, so a second person signs them first. Deployment is part of the agents feature of the licence.

How a four-eyes action runs here: you press the button; the console says "Sent for approval"; a second administrator approves under Approvals > Waiting for me; you then open Approvals > My requests, open the request and press Execute now (within the execution window, 15 minutes by default). See chapter 15.6.

13.2 Procedure: add a credential#

Required permission: Manage deployment credentials.

1. Environment > Hosts > Deploy agents remotely > Credentials > Add credential.

2. Fill in:

   Field	What to enter
   Name	A name for the account, for example "svc-lawliet-deploy (workstations)"
   Type	SSH, password; SSH, private key; SSH, key and certificate; WinRM, password; WinRM, client certificate
   Account	Domain: DOMAIN\user or [email protected]. Local: HOST\user or .\user
   Port (optional)	Empty for the default: 22 (SSH), 5986 (WinRM HTTPS), 5985 (WinRM HTTP)
   Password	For the password types
   Private key (PEM or OpenSSH), Key passphrase (if any)	For the key types (RSA, ECDSA or Ed25519)
   OpenSSH user certificate / Client certificate (PEM)	For the certificate types
   Privilege (SSH)	Logs in as root, sudo without a password, sudo with a password
   sudo password	Shown for a key with "sudo with a password"
   WinRM connection (WinRM, password)	HTTPS 5986 (default, recommended) or HTTP 5985 (insecure)
   Login (WinRM, password)	Kerberos first, NTLM if Kerberos is not possible (default); Kerberos only (domains that restrict NTLM); NTLM only (workgroup hosts, local accounts)
   WinRM server CA (PEM, optional)	The CA that issued the hosts' WinRM certificates (your AD CS root), or the hosts' self-signed certificates. Empty: the public CA store is used

3. Click Save credential.

What you see: 'Credential "<name>" stored. Its secrets cannot be read back.' The credential appears in the table (Name, Type, Account, Privilege, Last used). Secrets are encrypted and never shown again.

If you chose HTTP 5985 (insecure): a red warning appears before you save. Saving says "Sent for approval: a credential that uses WinRM over plain HTTP (insecure) needs a second administrator." The credential shows an Insecure: HTTP chip once created.

If it fails:

Linux hosts (SSH). The account must reach root. With "sudo with a password" the password goes only to sudo's own prompt on standard input, never on a command line. Recommended: a NOPASSWD rule for a dedicated group, for example in /etc/sudoers.d/lawliet-deployers:

%lawliet-deployers ALL=(root) NOPASSWD: ALL

For Linux joined to AD with sssd/realmd, log in as [email protected] or DOMAIN\user, whichever form sssd accepts.

Procedure: change or delete a credential#

Permission: Manage deployment credentials. Four-eyes: only for the weakening changes in 13.1 (for example switching a WinRM credential to plain HTTP).

To change a WinRM credential:

1. In Deploy agents remotely > Credentials, press Edit on the row.
2. The panel "Edit <name>" offers the WinRM connection (password credentials), Port (optional) and Login. Change them and press Save changes (Cancel discards).
3. Test it again against one host (13.3). A change bumps the credential's revision, so a test approved before the change is refused and must be requested again.

The name, account and secret cannot be edited, and SSH credentials have no Edit. To change those, add a new credential (13.2) and delete the old one.

To delete a credential:

1. Press Delete on the row. It is deleted at once, without a question; the stored secret is destroyed.
2. Deployments already finished are not affected; the agents they installed keep working.

If it fails: the reason is shown above the table (for example a missing permission).

13.3 Procedure: test a credential against one host#

A test logs in and checks the host. It installs nothing.

Required permissions: Manage deployment credentials and Deploy agents remotely. Four-eyes: yes.

1. In the Credentials table, click Test on the credential.
2. In "Test against host (address or name; nothing is installed)", enter the host, for example 10.0.0.5 or ws01.corp.example.com (a DNS name for Kerberos).
3. Click Test connection. What you see: "Sent for approval. A test logs in to the host with the stored secret, so someone else signs it first. Run it from Approvals; its result is shown there."
4. A second administrator approves it under Approvals > Waiting for me.
5. Open Approvals > My requests, open the request, click Execute now.
6. The test runs in the background. The checklist fills in as each check is made. A slow Windows host can take a few minutes. Cancel test stops it at its next step.

What you see when it passes: "Connection test: ready, <os> <arch>, <privilege>. Host key ...". The checklist and verdict are kept 30 days and shown again when you reopen the request.

Rules:

• One test at a time per credential (a second one is refused with 409 and its approval stays usable), at most 4 tests at once on the server (429).
• The approval is bound to the credential as it was. If the credential is changed before the test runs, the test is refused; request it again.
• A server restart fails a running test; request it again.

The checklist#

Each check ends ok, warning or failed, with one line saying what it means and the fix. Any failed check stops that host before anything is installed.

With Kerberos, the checklist also shows Server clock in step with the domain.

SSH host keys are pinned on first contact. A host that later shows a different key is refused with both fingerprints. After checking the key on the host's own console, remove the old key with the API (DELETE /api/v1/deployment/host-keys/{key_id}) and test again.

13.4 Procedure: configure Kerberos realms#

Use this when Windows hosts must be logged in to with Kerberos (domains that restrict NTLM). The server does not join the domain; it asks the named domain controllers for tickets.

Required permission: Manage deployment credentials. Four-eyes: yes (every change).

1. In Deploy agents remotely > Kerberos realms, click Add realm (or Edit realms).

2. Fill in:

   Field	Example	Meaning
   Realm	CORP.EXAMPLE.COM	The AD DNS domain in capitals
   NetBIOS domain (as in DOMAIN\user)	CORP	How accounts are written
   KDCs (domain controllers, host or host:port)	dc1.corp.example.com, 10.0.0.11	Asked on TCP 88. Nothing is looked up in DNS
   DNS domains (optional)	corp.example.com	Host names that belong to the realm (default: the realm in lower case)

3. Click Save realms. What you see: "Sent for approval: the KDCs receive every WinRM login, so a second person signs the change. Apply it from Approvals."

4. After approval and Execute now, click Check KDCs. Each KDC shows "answers; clock in step" (or how far the domain's clock is), or "not usable: <reason>". The check uses a non-existent account; no account is touched.

If the page says "Kerberos is not available on this server: ...", the server lacks the Kerberos libraries. Docker installs include them. With Kerberos first, deployments then use NTLM; with Kerberos only, they are refused.

Login modes:

Once a KDC has answered, NTLM is never tried for that login: a wrong password is not tried a second time by another method. Anyone who can block TCP 88 between the server and the KDCs can push Kerberos first down to NTLM; where that matters, use Kerberos only.

13.5 Procedure: deploy agents#

Required permission: Deploy agents remotely. Four-eyes: yes.

Risk: logs in to every listed host as root or Administrator and installs a service. Rollback: cancel hosts not yet started; uninstall the agent on hosts already done (chapters 11 and 12).

1. Test the credential against one host first (13.3).

2. Under New deployment, fill in:

   Field	What to enter
   Credential	The stored credential. An HTTP credential shows "- Insecure: HTTP"
   Name (optional)	For example "Floor 3 workstations"
   Hosts	One per line, host or host,os (linux, macos, windows); a range as 10.0.1.0/28. At most 1024 hosts
   Address the hosts reach this server at	Filled in from the server's settings. Change it when hosts reach the server differently (NAT). A localhost address shows a red warning
   Server certificate (PEM, only when it is not publicly trusted)	The server certificate for a self-signed server (sudo ./lawliet tls --export)

3. Click Deploy agents. What you see: "Sent for approval. Once someone else signs it, run it from Approvals."

4. A second administrator approves it; you click Execute now under Approvals > My requests.

5. Watch Deployments: each row shows #, Name, Credential, Started, Hosts ("N of M enrolled, K failed") and Status. Click a row to see each host.

Per host, the State moves through: queued -> connecting -> checking -> installing -> waiting for enrolment -> enrolled (or failed, cancelled). An enrolled host links to its agent. Checks (N failed, M warnings) opens the host's checklist.

What happens on each host: connect, run the checklist, then run the installer with a one-time token (valid 2 hours, one enrolment, only its hash is stored). A server certificate given with the job is written to a root-only folder and removed afterwards. The host is done when its agent enrols.

Controls while it runs:

• Cancel what has not started stops hosts not yet begun.
• Retry on a failed or cancelled host runs it again. It is four-eyes ("Retry of <host> sent for approval; run it from Approvals once signed.").

Lockout protection. Hosts are logged in to one at a time until the credential has been accepted once, then at most two at a time (installs run 10 at a time). If the login is refused twice in one deployment, the remaining hosts are not attempted ("Not attempted: the credential was refused 2 times in this deployment..."). A wrong domain password costs two failed logons, not one per host. Fix the account, then retry those hosts.

If it fails:

13.6 Other ways into remote deployment#

• Network map: an unmanaged host's details offer Deploy an agent to this host, which opens this panel with the host filled in.
• Review queue: an unmanaged-host item offers the same link. An "Insecure WinRM in use - switch back to HTTPS" item links to the credential's editor.

13.7 Switch a credential back to HTTPS#

1. Add an HTTPS listener on the hosts (chapter 12.8).
2. Credentials > Edit on the credential. WinRM connection HTTPS 5986 (default, recommended), clear the port. Save changes.

Switching back to HTTPS needs no second signature. The review queue item resolves itself.

More detail: remote deployment reference.