Remote deployment and domain accounts

Install the agent on many hosts from the console, with a technical account the hosts already accept, such as a domain account, instead of logging in to each one. In the console: Agents > Deploy agents remotely, or Deploy an agent to this host on an unmanaged host in the network map.

Credentials

Enter the account as the hosts know it: DOMAIN\user or [email protected] for a domain account, HOST\user (or .\user) for an account local to each host.

For SSH, say how the account becomes root: it is root, it has passwordless sudo, or its sudo asks for a password (the login password, or a separate one). With "sudo with a password", the preflight first asks sudo without a password; where that works (a NOPASSWD rule) no password is sent at all. Where sudo asks, the password goes only to sudo's own prompt on standard input, never on the command line, and the command run under sudo reads nothing from that stream. On Windows the account must be an administrator.

Secrets are encrypted at rest and write-only: the console shows only whether each one is set. Creating, replacing, testing and deleting a credential are recorded in the audit trail, without their values, and failure reasons and the server log are scrubbed of the credential's secrets on every path.

Domain accounts

The Lawliet server does not need to be joined to your domain to use a domain account. It authenticates to each host directly, and the host checks the account with its domain controller.

Windows hosts (WinRM)

• Use a WinRM, password credential. The connection is HTTPS on port 5986 with NTLM, which needs no domain membership on the server side. Kerberos is not used in this release, so a domain that refuses NTLM to its servers cannot be deployed to over WinRM; use SSH (Windows OpenSSH) or Group Policy there.
• The listener's certificate is validated. If it comes from your AD Certificate Services, paste the AD CS root (and any intermediate) as WinRM server CA on the credential; for a self-signed listener certificate, paste that certificate. The certificate must name the host as you enter it.
• The account must be in the host's local Administrators group, directly or through a domain group. A local account other than the built-in Administrator loses its administrator rights over the network (UAC remote restrictions, LocalAccountTokenFilterPolicy), and the deployment says so. Use a domain account.
• Turning certificate validation off, switching to plain HTTP on 5985 (lab only) or replacing the CA of a stored credential needs a second signature, as does creating a credential that does not validate.

Linux hosts joined to a domain (SSH)

• Log in as [email protected] or DOMAIN\user, whichever form sssd is configured to accept.
• Give the deployment account's group a sudo rule. NOPASSWD is recommended: no password is then sent for sudo at all. With a password rule, choose "sudo with a password".

A least-privilege deployment account

1. Create a dedicated account, for example svc-lawliet-deploy, and a group that holds only it. Do not use a Domain Admins account.
2. Windows: with Group Policy, add that group to the local Administrators group of the target OUs only, and deny it interactive and Remote Desktop logon on those hosts.
3. Linux: a sudo rule for the group, for example %lawliet-deployers ALL=(root) NOPASSWD: ALL in /etc/sudoers.d/lawliet-deployers.
4. Give it a long random password, store it once in the credential, and disable it or remove it from the group when the rollout is done.

Where an agent already runs on a domain controller, the Active Directory module can instead link a Group Policy object that installs the agent on domain members, with no deployment credential at all.

Test before deploying

Test connects to one host and runs the preflight without changing anything. Because a test logs in with the stored secret, it is a four-eyes action like a deployment: it is sent for approval with the host and the credential's revision, and the requester runs it from Approvals, which shows its verdict. Without that, anyone allowed to manage credentials could point a test at a host of their own and receive the password. A credential changed after the request refuses the approved test.

The SSH host key is pinned on first contact. A host that later presents a different key is refused with both fingerprints shown: either it was rebuilt, or something else answers on that address.

The checklist

A test, and every host of a deployment, ends in a checklist rather than a single error: one verdict per check, ok, warning or failed, with one line saying what it means and the exact fix. A host with two problems shows both, and any failed check stops that host before anything is installed.

The checklist is shown under the test result on Deploy agents, on Approvals once an approved test has run, and per host of a deployment. The check that the host can reach this server asks for TLS 1.2 over WinRM, as the installer does, so Windows 10 hosts pass it with their default TLS settings.

Deploy

Pick a credential and list the hosts, one per line as host or host,os (linux, macos, windows). A range in CIDR form expands to its addresses. A deployment takes at most 1024 hosts.

The address hosts enrol with comes from the server's public address setting, or else the address the console was reached at; change it when hosts reach the server differently. The console warns when it is a loopback address, which no host can reach.

A deployment is a four-eyes action: it waits for a second person to approve it, with the credential, the server address and every host on the list, and the requester starts it from Approvals. A credential changed after the request refuses the deployment, so an approval cannot be spent on a different secret.

On each host the deployment connects, runs the preflight, then runs the same installer the console offers for manual installs, with a one-time token in place of the enrolment secret. The token is valid for two hours and for one enrolment. A host is done when its agent enrols. Failed hosts show the step and the reason; Retry runs one again with its own approval, and Cancel stops hosts that have not started.

Lockout protection

A wrong or expired password must not lock a domain account. Hosts are logged in to one at a time until the credential has been accepted once (with "sudo with a password", until sudo has accepted it too). After that at most two logins run at once, while installs run in parallel.

If the login is refused twice in one deployment, or sudo refuses the password twice, the hosts not yet started are not attempted. They fail with "Not attempted: the credential was refused 2 times in this deployment", so a wrong domain password costs two failed logons, not one per host. A host that cannot be reached does not count. Fix the account, then retry the hosts.

Because logins run at most two at a time (one after a refusal), unreachable or hung hosts are handled one after another: up to 15 seconds each over SSH and up to about 120 seconds each over WinRM. A large deployment with many unreachable hosts therefore takes longer, by design. A Windows host that does not answer a PowerShell command within 60 seconds is asked once more, then reported in plain words.

A refused login says what it can mean (a wrong password, or a locked, disabled or expired account) and that repeated tries lock a domain account. WinRM answers a domain account that is not an administrator on the host exactly as it answers a wrong password, so that refusal names this case too. Over SSH, an expired password is reported as expired.

Permissions

manage_deployment stores credentials, shows deployments and cancels hosts not yet started; deploy_agents starts and retries them and switches a WinRM credential to weaker host checks, each with a second signature. Testing a credential against a host needs both. Deployment is part of the agents feature of the licence.

Signing in to the console with Active Directory accounts is a separate feature: see directory sign-in.

Hosts stop at 403

On 1.5.9.s, every remote deployment to a server with an enrolment secret, which ./lawliet install always sets, stops at the installing step with HTTP 403: the agent download refused the deployment's one-time token. Upgrade to 1.5.11.s, which accepts a valid deployment token for the download; see Upgrading. Until then, install those hosts with the command from Install agent in the console or ./lawliet token, which is not affected.