BigFix Agent installation on cloud resources

Starting from Patch 2, you can install the BigFix Agent on the discovered cloud resources (AWS and Azure), using the cloud provider services through the corresponding BigFix cloud plugin.

BigFix Platform offers two new tasks (specific for each cloud provider) on BigFix Enterprise Suite (BES) Support so that you can deploy the agent on the discovered cloud resources.

The tasks are available from both the BigFix Console and from the WebUI. Use one of these tasks, depending on your cloud provider:

  • 4774 Install BigFix Client through Amazon Web Services
  • 4775 Install BigFix Client through Microsoft Azure

What the tasks do

The tasks go through the following actions that are completed locally on the target cloud resources:
  • Fetch the installation script from software.bigfix.com.
  • Fetch the client installer based on the version of the Plugin Portal from software.bigfix.com.
  • Fetch the deployment masthead from the non-authenticating relay that is supplied for input to the tasks.
  • Install the client and register it with the non-authenticating relay.
  • Wait for the client registration to finish.

Requirements

To use this new installation feature, the discovered cloud resources must satisfy a number of cloud provider-specific configuration requirements. A subset of these requirements is automatically checked by the relevances that are contained in the tasks. You must ascertain that your cloud resources are configured correctly.

The primary requirements for installing the Agent on discovered cloud resources are as follows:
  • Provider-specific cloud agent must be installed on the cloud resource. For details, see AWS and Azure.
  • Cloud resources must be active and running.
  • The name of a non-authenticating relay (which you supply as input while you run the tasks). For details, see Relay name as input.
  • Operating system running on the cloud resource must be supported by the BigFix Client. For details, see Supported operating systems.
  • The Plugin Portal must be at Patch 2 level at the minimum.

Important considerations

The feature does not support the following relays and settings:
  • Authenticating relays
  • Custom client settings that are set during installation

Requirements for AWS

VM requirements

  • The presence of an active and running AWS Systems Manager (SSM) agent on the VM
  • An IAM instance profile with the AmazonSSMManagedInstanceCore IAM policy that is associated with profile through an IAM Role. The IAM instance profile must be attached to the VM. This requirement enables the AWS Systems Manager to securely run commands on the VM.

IAM Identities requirements

The basic requirements IAM Identities (Users and Roles) should always met, when configured in the AWS Cloud Plugin, are the following:

  • MFA must be disabled
  • Must have programmatic access type

When installing the BigFix Agent with an IAM User associated with the Access Key ID-Secret Access Key pair that is used as credentials of the AWS Cloud Plugin, the permissions required are as follows:

  • Must have the following ec2 permissions at the minimum: the ec2:Describe* action must be allowed on the * resource.
  • Must have the following ssm permissions at the minimum: the ssm:DescribeInstanceInformation ,ssm:SendCommand, ssm:GetCommandInvocation actions must be allowed on the * resource

When installing the BigFix Agent with an IAM Role that can be assumed by an IAM user configured in the AWS Cloud Plugin, the permissions required are as follows.

For the User:

  • Must be able to perform sts:AssumeRole on the target Role

For the Role:

  • Must have the following ec2 permissions at the minimum: the ec2:Describe* action must be allowed on the * resource.
  • Must have the following ssm permissions at the minimum: the ssm:DescribeInstanceInformation ,ssm:SendCommand, ssm:GetCommandInvocation actions must be allowed on the * resource
  • The IAM User assuming the role should be a trusted identity for the Role
Note: Once AWS Roles are inserted, the AWS plugin will use them during its discovery, instead of the credential from which they derive. You must ensure that these roles include all the AWS devices that you want to discover in your cloud environment: otherwise, some machines may not be discovered.

For a complete list of prerequisites, see Systems Manager prerequisites. Amazon Linux base AMIs that are dated 2017.09 or later include the systems manager by default. On other Amazon Machine Images (AMIs) or custom AMIs, you must install Systems Manager (SSM) Agent manually if it is not present already. For details about operating systems support, see Supported operating systems for Systems Manager.

Requirements for Azure

  • The VM Agent must be present on the VM.
    Azure provides two agents that run commands, based on the platform:
  • The operator (discovery credentials) must have at least the action permission.

If the agents are not present, you can install them as specified in the preceding references, provided that the OS requirements are met. To run commands on Azure VMs, an operator must have at least the action permission: Microsoft.Compute/virtualMachines/runCommand/action. The contributor role or higher built-in roles have this permission by default. However, you can also define a specific custom role.

Relay name as input

The tasks prompt for the name of a non-authenticating relay. Enter it in one of the following formats:
  • The relay host name. For example, enter myhostname.
  • The fully qualified domain name (FQDN) for the relay. For example, enter myhostname.mydomain.com.
  • The relay IP address. For example, enter 10.10.10.10.

Supported operating systems

This feature requires that one of the following provider-specific agents is installed and active:
  • The SSM agent for AWS
  • The VM Agent for Azure

Consequently, some operating systems that are supported by the provider agent might not be supported by BigFix. This subset of operating systems might vary in the future and is subject to change.

OS supported for AWS VMs

To see on which operating system types the AWS SSM agent is currently supported, see AWS SSM supported OSes.

For details about the BigFix agent operating systems currently supported, see Detailed system requirements.

OS supported for Azure VMs

To learn on which operating system types the Azure VM agent is currently supported, refer to the following documentation:

For details about the BigFix agent operating systems currently supported, see Detailed system requirements.

Troubleshooting

You have several ways to troubleshoot the agent installation failures:
  • You can check a list of custom exit codes which is provided below.
  • You can use a troubleshooting feature which is an sqlite database, named ActionResultsStore.db. The database is available for each cloud plugin.
  • You can check the action logs. Logs can be checked manually and the default locations are described later.

Installation script exit codes

Table 1. Native agent installation exit codes
Exit code Cause How to resolve
209 Client log file not found. This might be because the installed client failed to install within the specified time. Wait for a few minutes for the client to register. If that does not work, uninstall the client manually and install it again.
210 Client registration failed. This might be because the target cannot contact the relay or the masthead is corrupted. Check whether the target instance resolves the relay FQDN, IP, or hostname and it resolves the hostname specified in the relay masthead.
211 BESClient service not found. Check the client installation log on the target at /tmp/BigFix or %TEMP%/BigFix. Uninstall the client and install it again.
212 Client already installed. An installation of the client exists on the target.
213 Missing input parameter. This might be due to a manual error. Enter a value for the input parameter when prompted and try again.
215 Incorrect value returned by checksum. The downloaded installation script is corrupted. Check if the target has network connetivity and can reach the BES Support site.
216 Curl and wget utilities not found on Linux target. Install wget or curl utilities on the Linux targets.
217 The retrieved OS data does not allow the script execution. This might be because the OS installed on the targets is not supported or the information about OS returned by the targets is insufficient. Install the client manually or by using CDT.
218 Insufficient OS data retrieved. This might be because the OS installed on targets is not supported or the information about OS returned by the targets is insufficient. Install the client manually or by using CDT.
219 Shasum and sha256sum unavailable on Linux target. Install the shasum or sha256 utility on the Linux target.
220 Installer file not found. Check whether the target can reach software.bigfix.com.
221 Masthead file not found. Check whether the target can reach the relay. In case the relay is authenticating, install the client manually or by using CDT.
Table 2. Other common installation exit codes
Exit code Cause How to resolve
6 On Linux targets, the curl error "Could not resolve host" occurs. Check if the target can reach software.bigfix.com, the relay, and BES support site.
22 On Linux targets, the curl error "Request has encontered an error greater than 400" occurs. Check if target can reach software.bigfix.com, the relay, and BES support site.

ActionResultsStore database

The ActionResultsStore database is stored inside each plugin folder and it contains the action results of the actions that have either a failed or error status.

The database consists of a table, named ACTION_RESULTS, which has the following columns:
  • ActionID
  • DeviceID
  • InstanceID
  • Results
  • Date
The primary key will be (ActionID, DeviceID).
The Results column in the database contains a JSON string. Each JSON under Results has the following keys:
  • status represents the status of the action.
  • exitCode when there is an exit code available.
  • output the output of the request to the provider.
An example table follows:
{
    "status":"Error",
    "exitCode":1,
    "output":{
       "CloudWatchOutputConfig":{
          "CloudWatchLogGroupName":"",
          "CloudWatchOutputEnabled":false
       },
       "CommandId":"461eee16-e70f-4cf9-b64c- 
  e2902e355f49",
       "Comment":"BES Plugin Shell Cmd",
       "DocumentName":"AWS-RunShellScript",
       "DocumentVersion":"",
       "ExecutionElapsedTime":"PT0.011S",
       "ExecutionEndDateTime":"2020-11 
  -20T08:08:40.693Z",
       "ExecutionStartDateTime":"2020-11-20T08:08:40.693Z",
       "InstanceId":"i- 
   04f8e15e41aaf1544",
       "PluginName":"aws:runShellScript",
       "ResponseCode":1,
       "StandardErrorContent":"mkdir: missing operand\nTry 'mkdir --help' for more 
       information.\nfailed to run commands: exit status 1",
       "StandardErrorUrl":"",
       "StandardOutputContent":"",
       "StandardOutputUrl":"",
       "Status":"Failed",
       "StatusDetails":"Failed"
    }
 }
The database can be accessed remotely with the BigFix sqlite inspectors. As an example of this, we can use the Fixlet Debugger, set the query channel feature and the ID of the BES Portal endpoint, and evaluate a query like this example:
Q: rows of statement <sql statement> of sqlite database of file "ActionResultsStore.db" 
of folder <plugin folder>

Once a day, the ActionResultsStore database will be automatically cleaned up. Every cleaning removes all entries older than a specified number of days, which can be configured by a setting that is available for each plugin, named <plugin_name>_ActionResultsStore_CleanupDays. The value, for this setting, must be larger than 0 (zero) and is specified in days.

Installer, masthead and Log file locations

The installer, masthead and log files, which are part of the installation task outcome, are stored in a folder named "BigFix" which can be found in the following directories, within each target instance:

On Windows
%LOCALAPPDATA%\BigFix
On Linux
/tmp/BigFix