Roll out the service agent to many Windows servers

The appliance builds a ready-made GPO package that installs and upgrades the service agent when the servers start. The MSI file can also be installed without dialogs by SCCM, Intune or another software distribution tool.

When you need this

Your Windows servers are in an Active Directory domain, and you do not want to sign in to each one to install the agent.
New servers in a particular OU should get the agent automatically.
You already use SCCM or Intune to install software on the servers.

For a single server, the guide on Windows servers is quicker.

Registration token or install code

An install code works for one server, once. For many servers you therefore use the appliance’s Registration token from Agents › Install. It is filled into the GPO package and appears in the msiexec command.

Agents installed with the registration token are listed as installed without an install code. From version 1.3.3 of the Windows agent they move themselves over to an install code, provided they were installed without IGNORETLS=1 and have pinned the appliance’s certificate (Agents installed without an install code). After that they follow Agents › Connection. If the GPO package was downloaded with Ignore TLS certificate validation (unsafe), the agents never move.
Servers that must reach the appliance through sslbrain Cloud from their first start are each installed with their own install code (Servers outside your network).

Decide how the new servers are approved before you roll out:

If Automatic agent approval is on under Updates › Automation, every machine with the registration token is approved as soon as it checks in.
If it is off, every machine waits under Servers until an administrator approves it. At most 500 machines can wait at a time.
A machine that looks like a reinstall of a known server always waits (Approve new servers).

Silent installation with msiexec

Download the MSI file under Agents › Install (Download the MSI file), and run it with the appliance’s address and the registration token:

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

The command must run as administrator or SYSTEM.
Exit codes 0 and 3010 mean the installation succeeded. 3010 means Windows wants a restart, which /norestart postpones.
The service is called SSLBrainAgent, and the program is C:\Program Files\SSLBrain\SslBrainAgent.exe. Use either to detect whether the agent is installed.
The agent waits a random time of between 15 and 60 minutes before it checks in for the first time, so the servers do not all enrol at once.
Every property, for example SCRIPTPOLICY and CLOUD=deny, is listed under MSI properties.

In SCCM, Intune or a similar tool, create an application with the MSI file and the command above, set to run in the system context with 0 and 3010 as success codes.

If the appliance updates the agents (Keep service agents up to date), let the tool install the agent but not upgrade it. The MSI file refuses a version older than the one installed, so a rollout with an older MSI file fails on the servers the appliance has already updated.

Roll out with a GPO

The GPO package holds a startup script that installs the agent when the computer starts, and upgrades it at later startups when the appliance offers a newer version.

Open Agents › Install and choose Windows.
Check Appliance address. Every server the GPO applies to must be able to reach the address over HTTPS and trust the appliance’s certificate.
Choose the installation method Multiple servers · GPO and click Download GPO package. You get the file sslbrain-gpo.zip containing:
- Gpo-Install-SslBrainAgent.ps1, with the appliance’s address and the registration token filled in;
- Install-SslBrainAgent.ps1, which downloads and installs the MSI file;
- README.txt.
Create a GPO in Group Policy Management and link it to an OU with one test server.
Open Computer Configuration › Policies › Windows Settings › Scripts › Startup, tab PowerShell Scripts. Put both scripts in the GPO’s startup script folder, and add Gpo-Install-SslBrainAgent.ps1 without parameters.
Give read access to the two scripts only to the test server’s computer account and the administrators running the rollout. The package contains the registration token and must not sit on a share everyone can read.
Restart the test server and check it (Check that it works).
Give the remaining servers read access to the two scripts, in the same way as in step 6: either their computer accounts or a security group containing just those computers. Without read access the servers cannot run the startup script.
Extend the GPO’s scope to the same servers.

The startup script downloads the MSI file from the appliance and installs only if the file’s SHA-256 matches and the file is validly signed by FairSSL A/S. It never installs an older version over a newer one, and the agent’s enrolment and settings are kept on an upgrade. If Windows Installer is busy with another installation, the script retries up to five times, 15 seconds apart. The installation does not restart the server.

Settings that must be the same on every server, for example ScriptPolicy or CloudDeny, can be set with the GPO under HKLM\SOFTWARE\Policies\SSLBrain (The registry).

Check that it works

On the test server, Get-Service SSLBrainAgent shows status Running. If the service is not there, check with gpresult /r /scope computer that the GPO has been applied.
Within an hour of startup, the server is listed under Servers, either approved or under Venter på godkendelse.
Approve the server if it is waiting. After approval, the server’s page shows its services under Managed Endpoints.

Once the test server works, extend the GPO and keep an eye on the number of servers under Servers.

If it fails

The service is installed, but the server has not appeared after an hour: A service agent does not check in.
The script does not install because the server does not trust the appliance’s certificate: give the appliance a name with a trusted certificate (A name and certificate for the appliance), and download the GPO package again.
Many servers are waiting under Servers: automatic approval is off. Approve them, or turn on Automatic agent approval under Updates › Automation (Automation).