Step 5 of 8 · Windows

Windows servers

The service agent is a Windows service that checks in with the appliance over outbound HTTPS and installs certificates on the server. Once it is approved, the server is listed under Servers, and sslbrain finds the services on it by itself.

Before you start

Windows Server 2016 or later. Windows Server 2012 and 2012 R2 need ESU. The MSI file is for x64.
An account with administrator rights on the server.
The server can reach the appliance over HTTPS, port 443 by default. The port and the address the agents are given are under Network and DNS › Network. If the server cannot reach the appliance directly, read Servers outside your network first.
Windows trusts the appliance’s certificate. It does when the appliance has the free name from step 3 (The free name).
The appliance is connected to sslbrain Cloud. Agents › Install fetches the list of agent versions from there.

Then choose how the agent enrols:

	Registration token	Install code
Where	Agents › Install	Agents › Install codes
Valid for	every server, until the token is rotated	one server, for 1 to 720 hours (72 by default)
The agent can use sslbrain Cloud	no	yes
Follows Agents › Connection	no	yes
The machine waits under	Servers	Agents › Install codes
Agent version	any	from 1.3.3 with the command on this page

An agent from version 1.3.3 that was installed with the registration token moves itself over to an install code (Agents installed without an install code).

Download the MSI file

Open Agents › Install and choose Windows.
Under installation method, choose Manual installation.
Click Download installer. The file is called sslbrain-agent-v<version>-win-x64.msi. If there are several packages, choose one under Installer package.
On the server, check the file against the SHA-256 the page shows:
Terminal window
```
Get-FileHash .\sslbrain-agent-v<version>-win-x64.msi -Algorithm SHA256
```

The file is downloaded through the appliance and requires you to be signed in. The One server method below fetches the file on the server itself, so it needs no download.

Install with the pre-filled command

The appliance fills its address and the registration token into the command.

Open Agents › Install and choose Windows.
Check Appliance address. The server must be able to reach this address. localhost on the server is not the appliance.
Check that Registration token is filled in. If the page says the key is unavailable or revoked, the vault must be unlocked, or an administrator must check the key.
Choose the installation method:
- One server: the server fetches the script and the MSI file from the appliance itself.
- Manual installation: you have put the MSI file on the server (Download the MSI file).
Click Copy command.
Open PowerShell as administrator on the server. For Manual installation, go to the folder with the MSI file. Paste the command and press Enter.

The command for Manual installation has this form and works in both PowerShell and the command prompt:

msiexec /i sslbrain-agent-v<version>-win-x64.msi /qn /norestart SERVER=<appliance-address> TOKEN=<registration-token>

Below the command is the variant Installation with SHA-256 and signature check. It installs only if the file’s SHA-256 matches and the file is validly signed by FairSSL A/S.

If Windows does not trust the appliance’s certificate, tick Ignore TLS certificate validation (unsafe). The connection is still encrypted, but the agent does not check the appliance’s identity. One server then uses curl.exe, which ships with Windows Server 2019 and later. On Windows Server 2012 R2 and 2016, use Manual installation.

Install with an install code

An install code works for one server, once. It carries the appliance’s fingerprint, so the agent trusts only your appliance, also when the messages go through sslbrain Cloud. It needs the Windows agent from version 1.3.3.

Download the MSI file and put it in a folder on the server (Download the MSI file).
Open Agents › Install codes and fill in Create an install code:
- Name: what the code is for, for example the server’s name. It is for you only; the agent does not see it.
- Valid for hours: 1 to 720. An unused code stops working by itself.
- Addresses: comma-separated, in the order the agent tries them. The word cloud means sslbrain Cloud. Recommended: the appliance’s direct address first and cloud last, for example https://sslbrain.firma.dk,cloud.
- Approve automatically: takes effect only when Automatic agent approval under Updates › Automation is also on.
Click Create code and copy the code. It is shown this once only. The appliance does not keep it.
Open PowerShell as administrator on the server and go to the folder with the MSI file.
Paste the command below as one line. Change the file name to the file you downloaded, and <addresses> to the list from the code.
When PowerShell asks for Install code, paste the code and press Enter.
Approve the machine under Agents › Install codes (Approve the server).

$d = "$env:ProgramData\SSLBrainInstallCode"; if (Test-Path -LiteralPath $d) { Remove-Item -LiteralPath $d -Recurse -Force -ErrorAction Stop }; $s = New-Object System.Security.AccessControl.DirectorySecurity; $s.SetAccessRuleProtection($true, $false); foreach ($sid in 'S-1-5-32-544', 'S-1-5-18') { $s.AddAccessRule((New-Object System.Security.AccessControl.FileSystemAccessRule((New-Object System.Security.Principal.SecurityIdentifier($sid)), 'FullControl', 'ContainerInherit,ObjectInherit', 'None', 'Allow'))) }; [void][IO.Directory]::CreateDirectory($d, $s); $a = Get-Acl -LiteralPath $d; $o = $a.GetOwner([System.Security.Principal.SecurityIdentifier]).Value; $me = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value; if (-not $a.AreAccessRulesProtected -or ($o -notin @('S-1-5-32-544', 'S-1-5-18', $me)) -or @(Get-ChildItem -LiteralPath $d -Force).Count -ne 0 -or @($a.Access | Where-Object { $_.IdentityReference.Translate([System.Security.Principal.SecurityIdentifier]).Value -notin 'S-1-5-32-544', 'S-1-5-18' }).Count -ne 0) { throw 'The folder is not locked to Administrators and SYSTEM, so no code was written' }; $c = Read-Host 'Install code'; if ($c -notmatch '^sbi1\.[A-Za-z0-9_-]{64}$') { throw 'That is not an install code, so nothing was installed' }; $f = [IO.File]::Open("$d\sbi.code", 'CreateNew', 'Write'); $b = [Text.Encoding]::ASCII.GetBytes($c + "`r`n"); $f.Write($b, 0, $b.Length); $f.Close(); $msi = (Resolve-Path -LiteralPath 'sslbrain-agent-v<version>-win-x64.msi').Path; $log = "$env:TEMP\SSLBrainAgent-install.log"; msiexec /i $msi /qn /norestart /l*v $log CODEFILE="$d\sbi.code" DESTINATIONS='<addresses>' | Out-Null; if ($LASTEXITCODE -notin 0, 3010) { throw "msiexec failed with exit code $LASTEXITCODE; its log is $log" }

The appliance shows the same command with the file name SSLBrainAgent.msi. Use the command here with the name of the file you downloaded.

The command is one line because Read-Host would otherwise take the next pasted line as the code. It creates the folder C:\ProgramData\SSLBrainInstallCode, which only Administrators and SYSTEM can read, writes the code to the file sbi.code and installs the MSI file with it. The code never appears on the command line, where other users on the machine could read it. The service moves the code into a part of the registry that only SYSTEM and Administrators can read, and deletes the file. If anyone else can read or change the file, the agent does not use it and writes the reason to its log. In that case, create a new code.

If two machines use the same code, the second is refused, and Agents › Install codes shows that the code has leaked. The first machine is not affected.

If you leave cloud out of Addresses, the agent never uses sslbrain Cloud until an administrator turns it back on from the server’s page. Ignore TLS certificate validation cannot be combined with an install code.

Silent installation and MSI properties

The MSI file installs without dialogs using /qn /norestart. A new installation needs SERVER or CODEFILE. The properties are saved in the registry (The registry).

Property	Default	Meaning
`SERVER`		The appliance’s address, for example `https://sslbrain.firma.dk`
`TOKEN`		The registration token from Agents › Install
`CODEFILE`		File holding an install code (from version 1.3.3). Use the command under Install with an install code
`DESTINATIONS`		Addresses in priority order, comma-separated, `cloud` for sslbrain Cloud (from version 1.3.1)
`CLOUD`		`deny`: the agent never contacts sslbrain Cloud, whatever the appliance sends. `allow` lifts the block (from version 1.3.1)
`IGNORETLS`	`0`	`1`: the agent does not check the appliance’s certificate. Registration token only
`CHECKININTERVAL`	`900`	Seconds between check-ins for an agent installed with the registration token
`STARTUPDELAYMIN`, `STARTUPDELAYMAX`	`900`, `3600`	Wait in seconds before first enrolment with the registration token. Random within the range
`SCRIPTPOLICY`	`15`	Which signed scripts the agent runs (Your own scripts)
`LOGLEVEL`	`info`	Log level in the agent’s log file
`NOPHONEHOME`	`0`	`1`: an agent without `SERVER` does not ask sslbrain Cloud for the appliance’s address

An upgrade with a newer MSI file keeps the address, the enrolment and the other values from the registry when they are not on the command line. The MSI file refuses a version older than the one installed. If you give a different SERVER from the installed one, the agent enrols again with that appliance.

For rollout to many servers with GPO, SCCM or Intune, see Roll out the service agent to many Windows servers.

The registry

The agent’s settings are in HKLM\SOFTWARE\SSLBrain as string values: ServerURL, Destinations, CloudDeny, IgnoreTLS, NoPhoneHome, ScriptPolicy, CheckInInterval, StartupDelayMin, StartupDelayMax, LogLevel, ToolsPath and AgentId.

The service moves the registration token and the install code to HKLM\SOFTWARE\SSLBrain\Credentials, encrypted with DPAPI and readable only by SYSTEM and Administrators.
Values under HKLM\SOFTWARE\Policies\SSLBrain take precedence over those above, so they can be set by GPO: ScriptPolicy, NoPhoneHome, IgnoreTLS, CloudDeny, CheckInInterval, ServerURL and TrustSignedBefore.
Restart the service after a change: Restart-Service SSLBrainAgent.

An agent installed with an install code takes its check-in, retry and address settings from Agents › Connection (How the agent reaches the appliance).

Approve the server

Once the agent has checked in, the machine waits for approval unless it was approved automatically. With the registration token it waits under Servers; with an install code under Agents › Install codes. For an install code, compare the Agent key on the page with the key the agent has written to its log (Log files) before you click Approve. The rules for automatic approval are under Approve new servers.

Log files

What	Where
The agent’s log, one file per day, files older than 30 days are deleted	`C:\ProgramData\SSLBrain\logs\agent-<date>.log`
Agent updates	`C:\ProgramData\SSLBrain\logs\update-msiexec-<version>-<time>.log`
Installation with an install code	`%TEMP%\SSLBrainAgent-install.log`

The service is called SSLBrainAgent (shown as SSLBrain Agent), runs as LocalSystem and starts automatically with delayed start. The program is in C:\Program Files\SSLBrain\.

Get-Service SSLBrainAgent
Get-Content "C:\ProgramData\SSLBrain\logs\agent-$(Get-Date -Format yyyy-MM-dd).log" -Tail 50

Check that it works

Get-Service SSLBrainAgent shows status Running.
The machine is listed under Servers or under Agents › Install codes, either waiting or approved.
After approval, the server’s page shows Service agent with a version and Last check-in, and the services on the server appear under Managed Endpoints.

An agent installed with the registration token waits a random time of between 15 and 60 minutes before it checks in for the first time. This spreads the enrolments when many servers start at once. For a single server you can add STARTUPDELAYMIN=0 STARTUPDELAYMAX=0 to the msiexec line. An agent installed with an install code does not wait.

If it fails

Agents › Install shows “This appliance is not connected to sslbrain Cloud.” or no package: the appliance must be connected to sslbrain Cloud. Click Fetch release list again once the connection works.
msiexec reports SSLBrain Agent needs its appliance: the command is missing SERVER or CODEFILE. Copy the command from the appliance again.
PowerShell reports “That is not an install code”: what you pasted was not the whole code. The code starts with sbi1..
PowerShell reports “The folder is not locked to Administrators and SYSTEM”: the folder C:\ProgramData\SSLBrainInstallCode has other permissions. Run the command again as administrator.
PowerShell reports “msiexec failed with exit code”: the cause is in the log the message names.
The server does not appear in sslbrain: A service agent does not check in.
The certificate is not installed on the server: Installation on the server fails.