Skip to content

Windows Connection Manager – Command Line Installation

Cloudhouse Guardian (Guardian) provides two methods for installing the Windows Connection Manager. The following topic describes how to download, install, and register the Connection Manager via Command Line. Alternatively, you can install the Connection Manager via the default Windows installer, see Windows Connection Manager – Installer for more information.

System Requirements

To install the Windows Connection Manager, the following system requirements must be met:

Requirement Description
Microsoft Windows Virtual Machine Recommended specifications: Windows Server 2012 (or later), 8GB RAM, 4 cores.
Microsoft .NET Framework Version 4.5.2 (or above).
Microsoft Visual C++ 2015 Redistributable Package For Windows Connection Manager v4.19.0 (and above). Package download link provided on the Guardian Downloads page.
PowerShell (Windows Management Framework) Version 3 (or above). Installed on both the Connection Manager and the target nodes.
WinRM Enabled in your Guardian environment. For more information, see Enable WinRM via Group Policy.
Port 443 Must be able to reach the Guardian instance over this port.
Port 5985/5986 Must be able to reach Windows nodes over this port.
Note: This is the default port. If you are using a different port, make sure that the Connection Manager can reach the port that the administrator is using to run their WinRM server.

Note: If you do not meet any of the requirements described above, please contact your Cloudhouse Representative for assistance.

Acceptance Criteria

To install the Windows Connection Manager, the following acceptance criteria must be met:

Criteria Description
Operating System Windows.
Connection Protocol WinRM or remote PowerShell configured on all target nodes.
Windows Service User Service account set up and configured to use WinRM. The account should be a local administrator on the target nodes, or a domain administrator.
Package Distribution Tool Cloudhouse recommend using SCCM.
Connection Manager Group A Windows Connection Manager group is required to add the Connection Manager to. Specifically, using the Group API Key.

Deployment

The following procedure describes how to deploy your Windows Connection Manager. By default, this Connection Manager is distributed as an .exe file. First, you are required to download the package from the Guardian Application Downloads page, install the virtual machine, and then configure the Connection Manager service to run as a service user.

Download

  1. Access the Guardian Application Downloads page. Here, the Connection Manager is available to download as an .exe file.

  2. In the Connection Managers panel, click the Download Link for the 'Windows Connection Manager'.

    If your environment contains more than 100 nodes, you may require multiple Connection Managers, depending on the node type and region. For more information, please contact your Cloudhouse Representative and they will assist you with capacity planning.

Install

To install the Connection Manager via Command Line, Cloudhouse provide an example command that you can run in a package distribution tool of your choice.

  1. Copy the example command below.
C:\Temp\Guardian-v5.15.0.exe --mode unattended  --target_url https://example.cloudhouse.com --ignore_ssl_cert_check_boolean 1 --api_key c12b333d3ed73cd4ce0b3b7de6e695b450ff239c3af84fb4fc0b02c8b5d7f85f

  1. Next, you are required to set the correct values for the following options:

    Tip: Optionally, you can set the default log level to debug, info, or warn using the --log_level parameter, as of V5.20.0 of the Windows Agent (and above). For more information, see Log Level Configuration.

    Option Description
    target_url The URL of your Guardian appliance or hosted instance, in 'https://' format.
    ignore_ssl_cert_check_boolean If your Guardian server instance is installed with a self-signed certificate, Cloudhouse recommend that you enable this setting. By default, this setting is disabled. To enable this setting, set the value to '1'.
    api_key The Group API Key for the Connection Manager group you want to add the new Connection Manager to.
    Note: For more information on how to source the Group API Key for an existing Connection Manager group, see Group API Key. Alternatively, to add a new Connection Manager group, see Add Connection Manager Group.
    --register_node The values of the API key and target URL. When entering these values, follow with either of the following parameters: - true – add a new API key and target URL. - To enter new values, enter --api_key and --target_url, and add the API key and target URL associated with the agent. - false – use the API key and target URL from the currently installed agent.
    Note: This option is only valid when reinstalling or upgrading the Windows agent. Fore more information, see Windows Agent.

    Note: To access the complete list of configurable elements that can be set in the example command, run the following command, 'Guardian-v5.15.0.exe --help'.

    2.1. If you are adding the Connection Manager to a group that contains one or more existing Connection Managers, you are required to distribute the private key for the desired Connection Manager group using your package distribution tool.

    Note: The private key file can be found in C:\Program Files\Cloudhouse Guardian\config\ssh_Agent.priv on any existing Connection Manager within that group.

  2. Once you have set the required values for your Connection Manager, run the command in your package distribution tool to install the Connection Manager.

    3.1 By default, the 'Guardian' service runs as the 'Local System' account. Optionally, you can configure the service to run as a specific service user account. For more information, see Configure.

  3. Once the installation is complete, the private key has been copied into the configuration directory, and you have optionally configured the service account, you need to restart the 'Guardian' service to apply your changes.

If the correct values were set in the command template, the Connection Manager is installed and registered to your Guardian appliance. Optionally, you can check to see if the Connection Manager has been added to the specified Connection Manager group in your Guardian instance (Inventory > Connection Managers tab > Groups). Next, you need to confirm that the 'Guardian' service is running under the Windows service user account, see below for more information.

Configure

To begin scanning remote systems, you are required to provide the credentials for the user account that is configured to use WinRM for scanning. You can choose to provide them each time you add a node, or you can configure the Guardian service to run as a Windows service user, meaning that you only need to set them once. The following section describes how to configure the service, assuming that you already have a Windows service user configured with the correct permissions. For more information, see Acceptance Criteria.

  1. In the Windows Search box, type 'Services'. Then, click to Run as administrator.

  2. The Services dialog is displayed. Locate the 'Guardian' service and check that the Status is set to 'Running'.

    If the Status is set to 'Running', the Connection Manager has been installed successfully. If the 'Guardian' service is not displayed, the Connection Manager installation has failed, see Registration Failed for more information.

  3. Right-click on the 'Guardian' service and select Properties. The Guardian Properties dialog is displayed.

  4. In the General tab, make sure that the Startup type is set to 'Automatic'.

  5. Then, in the Log On tab, select the This account radio button to display the following fields:

    Field Description
    This account The name of the account holder.
    Password Account password.
    Confirm password Account password.

  6. Enter the correct value in each of the fields and click Browse.

  7. The Select User dialog is displayed, click Check Names to search your device for the Windows service user account.

    Note: If no results are displayed when you enter the account information, you may not have a Windows service user account set up. Cloudhouse recommend asking your Guardian Representative for more information. If you are unable to create a Windows service user account with the correct permissions, contact your Cloudhouse Representative for assistance.

  8. Select the Windows service user account and click OK to return to the Log On tab.

  9. In the Log On tab, make sure that the Password and Confirm password fields are populated correctly. Then, click to Apply and OK to close the Guardian Properties dialog.

    Finally, you need to restart the Guardian service to apply your changes. In the Services dialog, right-click on the 'Guardian' service and select Restart.

Once complete, the Connection Manager service is configured to run as a Windows service user. If the service user has the correct permissions, you are able to begin scanning nodes via the Connection Manager. For more information, see Add Nodes.

Registration Failed

After completing Step 1 - 8 of the Install procedure, if the registration fails, remediation is required to proceed with registering the Connection Manager to the Guardian appliance.

Install Log

First, Cloudhouse advise that you check the install log within the installation directory folder. By default, this is 'C:\Program Files\Cloudhouse Guardian'.

  1. In the File Explorer, locate the installation directory for the Connection Manager.

    Here, the 'install' file is displayed.

  2. Click to display the 'install' log and check what error messages are displayed. For more information on how to remediate these errors, see below.

Common Problems and Solutions

The following section describes the possible points of failure that may occur when attempting to register the Connection Manager to the Guardian appliance.

Ignore SSL Certificate Warnings

The most common failure is caused by an untrusted certificate being detected on the Guardian appliance. To resolve the issue, re-run the command and set the ignore_ssl_cert_check check to '1'.

Network and DNS

The second most common failure is caused by the network and/or DNS being configured incorrectly. Check if your Guardian instance is accessible from your browser on your Connection Manager host. If it is not accessible, check that the network and DNS is configured correctly and there are no firewall rules blocking the connection.

Group API Key

Another common failure is caused by the Group API Key being copied incorrectly from the desired Connection Manager group (Inventory > Connection Managers tab > Groups). To resolve the issue, re-run the command and provide the correct Group API Key in the api_key option.

Tip: If you do not want to re-run the command, you can install the Connection Manager via the Windows installer instead (default method). For more information, see Windows Connection Manager – Installer.

Post-Deployment

Once the Connection Manager has been deployed, if you need to update it, you can install a new version via the same process. The new version will be available to download from the Guardian Application Downloads page.

Note: Make sure that the correct service user account is signed in before restarting the 'Guardian' service.