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
- 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.
- 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
- 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
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 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
- 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
For details about the BigFix agent operating systems currently supported, see Detailed system requirements.
Troubleshooting
- 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
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. |
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.
- ActionID
- DeviceID
- InstanceID
- Results
- Date
- status represents the status of the action.
- exitCode when there is an exit code available.
- output the output of the request to the provider.
{
"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"
}
}
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