Non-extraction usage

The Airgap command line interface can gather site information without having to access the BigFix server and can optionally download files without passing through a download cacher.

With the non-extraction usage, the Airgap tool can download the files specified in Fixlets from download sites like Windows that do not require to authenticate. When you need to download files from sites that require to authenticate with an userid and password, or to download files not specified by prefetch or download commands in Fixlets, as in the case of patch modules for AIX, CentOS, HP-UX, RedHat, Solaris or SUSE, you must use a download cacher.

To gather site information without accessing the BigFix server, complete the following steps:

1. Create a site list

Run the tool on a workstation that has access to the public Internet specifying the license serial number, the email address used to register your license, and the name of the file in which the tool lists the sites for your license. You must have writing access for the folder where the Airgap tool is located. Enter the following command:

On Windows operating systems:

BESAirgapTool.exe -serial serial_number -email 
mail_address -createSiteList site_list_filename [-proxy
[user:password@]hostname:port] [-usehttps] 
[-cacert crt_filename] [-othersites site_foldername] [-timeout timeout_seconds]

On Linux operating systems:

./Airgap.sh -serial serial_number -email 
mail_address -createSiteList site_list_filename [-proxy
[user:password@]hostname:port] [-usehttps] 
[-cacert crt_filename] [-othersites site_foldername] [-timeout timeout_seconds]

Where:

mail_address

Is the mail address that you specified in your license; if it does not match, the Airgap tool fails. Option -email can be used only together with option -createSiteList.

-proxy

Option used when the workstation that has access to the public Internet can connect only by a proxy server. In this case, after the -proxy option, specify the hostname and port of the proxy server in the form hostname:port. If the proxy is an authenticating proxy, add also the userid and password in the form userid:password@hostname:port.

-usehttps

When this option is specified, "https" is used to contact the license server. Use option -cacert to specify a path in which to put the file ca-bundle.crt if you want to use a different folder from that in which the Airgap tool runs. The file ca-bundle.crt is used to validate the server certificate when you use the -usehttps option, or when the URL in the Fixlet begins with "https".

-cacert

This option can only be used together with option -usehttps.

-othersites

Use this option if your license is entitled to AllowOtherSites, to include sites of your choice to your site list. Create a folder, copy in it all the masthead files (*.efxm files) related to your mastheads not included in your license, and specify the name of this folder with option -othersites when you create a site list.

-timeout

This option is available starting from Version 9.5.7. It specifies a http timeout interval in seconds. Values range from 30 to 3600. The default value is 30. In the event you get the error "HTTP Error 28: Timeout was reached" while using a proxy, try also to use option -usehttps as it makes proxy to work in tunneling mode and that might help avoiding timeouts.

After running the tool, a file is created with the name that you specified as site_list_filename.

Note: The site list file, once created, can be used until you change the license, or HCL adds a new site to the existing license. If you delete the site list file for any reason, you can create it again with the same command, as the history of downloaded files is maintained as long as the license serial number does not change.

2. Edit the site list file

Each line of the file created in step 1 contains three pieces of information separated by a double colon:

flag::site_name::site_url

You can edit only the flag parameter, that can have one the following values:

A

Site contents are gathered when a newer site version is available and stored in the AirgapResponse file, and used for downloading files or creating a file list.

R

Site contents are always gathered and stored in the AirgapResponse file regardless of the version of the site, and used for downloading files.

G

Site contents are gathered when a newer site version is available and stored in the AirgapResponse file, but not used for downloading files or creating a file list.

Q

Site contents are always gathered and stored in the AirgapResponse file regardless of the version of the site, but not used for downloading files or creating a file list.

D

Site contents are not gathered, but are used for downloading files or creating a file list. This flag is useful when you want to keep the current contents of a site without updating it and download files to run Fixlets at your current site. This option is valid only when the site contents have already been gathered.

N

Site is ignored, but site information is kept in the file for future reference.

Note: When you create a site list file, the default values for the BES Support and Web UI Common components are set to G. If you are not interested in the Web UI component, modify the default Web UI Common value from G to N. The default values for the other components are set to N. At the first run after installing the BigFix server, the license information, the BES Support and the Web UI Common components must be gathered. Only after moving this first Airgap response generated on the workstation that has access to the public Internet to the BigFix server, you can enable the other components that you can access from the License Overview dashboard of the console and continue with the process. Be sure to enable the required components other than default before gathering.

3. Gather site contents and create the Airgap response file

After you have edited the flags in the site list file, run the Airgap tool again to complete one of the following site operations:

a. Gather site contents

To gather site contents for sites with flag A or R or G or Q, run the following command:

On Windows operating systems:

BESAirgapTool.exe -site site_list_filename

On Linux operating systems:

./Airgap.sh -site site_list_filename

On completion, you have created the Airgapresponse file.

b. Gather site contents and download files

To gather site contents for sites with flag A or R or G or Q, and download files referenced by Fixlets on sites with flag A or R or D, run the following command:

On Windows operating systems:

BESAirgapTool.exe -site site_list_filename -download 
[-cache cache_name]

On Linux operating systems:

./Airgap.sh -site site_list_filename -download 
[-cache cache_name]

where cache_name is the folder path where to store the downloaded files. On completion, you have created the Airgapresponse file and downloaded the files to the cache_name folder.

c. Gather site contents and download files selectively

To gather site contents for sites with flag A or R or G or Q, and create a list of files referenced by Fixlets on sites with flag A or R or D, run the following command:

On Windows operating systems:

BESAirgapTool.exe -site site_list_filename 
-createFileList referenced_list

On Linux operating systems:

./Airgap.sh -site site_list_filename 
-createFileList referenced_list

On completion, you have created the Airgapresponse file and the file list with the name specified in referenced_list.

In all cases, site contents gathered for sites with flag A or R or G or Q are put in the AirgapResponse file. When you run the Airgap tool for the first time, all sites with flag A or R or G or Q are gathered. For subsequent times, the contents of sites with flag A or G are gathered only if either they have not been previously gathered or a newer site version is available. For sites with flag R or Q, contents are always gathered.

Optionally, you can also specify the following options:

-usehttps

License information and site contents are gathered using "https". For case "b. Gather site contents and download files", all urls beginning with "http" are forced to use "https". Note that some urls in Fixlets begin with "https" and some patch sites might redirect requests to urls beginning with "https".

-proxy [user:password@]hostname:port

Used when the workstation that has access to the public Internet can connect only through a proxy server. In this case, after the -proxy option, specify the host name and port of the proxy server in the format hostname:port. If the proxy is an authenticating proxy, add also the user ID and password in the format userid:password@hostname:port.

-cacert crt_filename

To specify a path in which to put the file ca-bundle.crt if you want to use a different folder from that in which the Airgap tool runs. The file ca-bundle.crt is used to validate the server certificate when you use the -usehttps option, or when the url in the Fixlet begins with "https". The option -cacert can only be used together with option -usehttps.

-timeout timeout_seconds

This option is available starting from V9.5.7. It specifies a http timeout interval in seconds. Values range from 30 to 3600. The default value is 30. In the event you get the error "HTTP Error 28: Timeout was reached" while using a proxy, try also to use option -usehttps as it makes proxy to work in tunneling mode and that might help avoiding timeouts.

For cases b and c, you can also use other options to reduce the number of files to download or to gather in the file list. These filtering options select Fixlets that refer to files, not the files themselves. For example, when you specify last 5 days, it means files referenced by Fixlets modified in the last 5 days, not files added or changed by vendors in the last 5 days. To create a list of possible values for filtering options, run the following command:

On Windows operating systems:

BESAirgapTool.exe -site site_list_filename -createfilterList 
filter_list

On Linux operating systems:

./Airgap.sh -site site_list_filename -createfilterList 
filter_list

The list of available values is limited to the following options: -fcategory, -fcve, -fproduct, -fseverity, -fsource, and -fsourceid. The following options are available for filtering:

-fcategory

Fixlet category property.

-fcve

To specify the CVE (Common Vulnerabilities and Exposures) id associated with a security patch.

-fdays

To select Fixlets whose last modified date falls within a specified number of days from the date you run the command.

-fproduct

To specify the product name to which the Fixlet is applicable, such as Win2008 or Win7. This information is not shown in the Console. This option is available only for sites related to patches for Windows operating systems.

-fseverity

To specify the severity that a vendor associates with a security patch.

-fsource

Provider of file, such as BigFix, Adobe, or Microsoft.

-fsourceid

Identification specified by the provider.

-includeCorrupt

To include Fixlets marked as Corrupted, that are excluded by default when this option is not specified.

-includeSuperseded

To include Fixlets marked as Superseded, that are excluded by default when this option is not specified.

When multiple filter conditions are specified, only Fixlets that satisfy all conditions are selected. For options -fsource, -fsourceid, -fcve, -fcategory, and -fseverity, you can specify multiple comma-separated values, for example: -fseverity "Critical, Important". When you use commas to separate values, or values contain spaces, enclose parameters in double quotes, as in the previous example. Note that values are case sensitive.

4. Edit the file list

Applicable only to case c. Gather site contents and download files selectively of step 3.

With -createFileList option, you create a file that contains a list of files. Each line of the list contains pieces of information separated by a double colon:

flag::site_name::Fixlet_id::site_url::
size::hash_value::hash algorithm

For example:

N::site=site_name::fixletid=fixlet_id::
url=url_address::size=file_size::hash=hash_value::
hashtype=hash_type

You can edit only the flag value, changing it to Y to download the file, or to N to not download the file.

5. Run the tool on the Internet facing workstation to download files

Applicable only to case c. Gather site contents and download files selectively of step 3.

After editing the file list in step 4, to download only the files with flag Y in the file list, run the Airgap tool by issuing the following command:

On Windows operating systems:

BESAirgapTool.exe -file file_list_filename -download 
-cache cache_foldername 
[-proxy [user:password@]hostname:port] [-usehttps] 
[-cacert crt_filename]

On Linux operating systems:

./Airgap.sh -file file_list_filename -download 
-cache cache_foldername 
[-proxy [user:password@]hostname:port] [-usehttps] 
[-cacert crt_filename]

where cache_foldername is the folder path where to store the downloaded files. The files already in the cache folder are not downloaded again.

6. Move the Airgap response file to the BigFix server and run the Airgap tool on the BigFix server

Copy in a portable drive the AirgapResponse file, and the file list that you have created in step 3 or the downloaded files that you collected in step 5, and transfer them to the BigFix server computer. Make sure that the AirgapResponse file is in the same folder as the Airgap tool, and run it by issuing the following command:

On Windows operating systems:

BESAirgapTool.exe -run [-temp temp_folder]

On Linux operating systems:

./Airgap.sh -run [-temp temp_folder]

This imports the response file with the Fixlet content and license updates into your deployment.

Note: The Airgap tool passes site contents in the response file to the GatherDB component of your BigFix server, and the GatherDB component imports site contents. For sites other than WebUI sites, you can monitor the import progress in the DebugOut of the GatherDB component (default name GatherDB.log).

Copy the downloaded files also into the BigFix server cache folder. The cache folder default location is:

On Windows operating systems:

%PROGRAM FILES%\BigFix Enterprise\BES Server\wwwrootbes\bfmirror\downloads\sha1

On Linux operating systems:

/var/opt/BESServer/wwwrootbes/bfmirror/downloads/sha1

Repeat these steps periodically to keep updated the Fixlet content in the main BigFix server. Join the new Fixlet mailing list to receive notifications when Fixlets are updated. Always make sure that the Airgap tool version is compatible with the version of the BigFix server installed.

Optional actions:

Check if all required files have been downloaded

To check if you have downloaded all the files required for the Fixlet you are planning to apply, use option -checkfixlet when you run the Airgap tool. For example:

On Windows operating systems:

BESAirgapTool.exe -site site_list.txt -checkfixlet 
-fdays 100 -fseverity Critical -cache MyCache

On Linux operating systems:

./Airgap.sh -site site_list.txt -checkfixlet 
-fdays 100 -fseverity Critical -cache MyCache

For Fixlets satisfying the specified filtering conditions, the tool checks the downloaded history and contents of destination folder, and if there are still files to download, Fixlet names and urls are displayed.

Files to be downloaded manually

Some files referenced by Fixlets might not be downloaded because they can be obtained only by contacting the vendor support center, or because the download site requires that you explicitly accept the license terms and this action cannot be automated for legal reasons. In these cases, the involved files have the download url containing the string MANUAL_BES_CACHING_REQUIRED and must be downloaded manually. To create a list of these files, use option -createmanuallist as in the following example:

On Windows operating systems:

BESAirgapTool.exe -site site_list.txt -createmanuallist 
manual_list -fseverity Critical

On Linux operating systems:

./Airgap.sh -site site_list.txt -createmanuallist 
manual_list -fseverity Critical

You can also use the -checkmanual option to check if your destination folder contains all the files that must be manually downloaded, as in the following example:

On Windows operating systems:

BESAirgapTool.exe -site site_list.txt -checkmanual 
-fseverity Critical 
-fdays 30 -cache MyCache

On Linux operating systems:

./Airgap.sh -site site_list.txt -checkmanual 
-fseverity Critical 
-fdays 30 -cache MyCache

Reset history

The Airgap tool keeps a history of downloaded files. Even if you move all the downloaded files from your public Internet facing workstation to the BigFix server, this history is maintained and files previously downloaded are not downloaded again to save time and disk space. If you deleted part or all of your previously downloaded files and you need them again, you can use the -resync option. This option clears the download history and checks the files in the folder specified with -cache option. Note that the newly-created download history is based only on the files contained in the folder specified with the -cache option.

Changing license

If you want to manage another license, you must erase the history of gathered sites and downloaded files. To complete this action, use the -force option as in the following example:

On Windows operating systems:

BESAirgapTool.exe -serial serial_number -email 
mail_addess -createSiteList site_list_filename -force

On Linux operating systems:

./Airgap.sh -serial serial_number -email 
mail_addess -createSiteList site_list_filename -force

Miscellaneous options

By default, the Airgap tool simultaneously downloads two files. You can change the number of files to download concurrently by specifying a number after the -download option . This number can range from 1 to 8. For example, to download 3 files at the same time, specify -download 3. Note that you need a larger band width when downloading more than 2 files simultaneously.

When the url specified in a Fixlet begins with "https", or if you specify the -useHttps option, the Airgap tool tries to verify that the server specified in the url has an appropriate SSL Server Certificate. If, for any reason, you want to skip this check and avoid a download failure when the Airgap tool cannot verify the server certificate, use the -noverify option. With this option, the Airgap tool does not verify the authenticity of the server certificate while it verifies that the server certificate is for the server specified in the URL you operate against. You must check that your workstation translates correctly host names by checking your DNS.

To have the Airgap tool to print more information than usual, use the -verbose option.

Working with multiple BigFix servers

If you want to use the same public Internet facing workstation for several BigFix servers, like a test server and a production server, create a folder for each server, copy the Airgap tool in each folder, and work with each folder separately. You can share the same site list among the different folders, but each server keeps its own history in its folder. When using multiple Airgap tools with different servers, you can also share a cache folder to download only once files that are common to different servers, but you must ensure to run only one instance of the Airgap tool at the same time.

In case you need to gather set of sites, load them to your test server, then perform tests with the gathered sites and load the tested sites, not the latest ones, to your production server, you can load one AirgapResponse file to multiple BigFix servers when they are licensed for the same products (like BigFix Lifecycle, BigFix Compliance, etc.). When you intend to load one AirgapResponse file to multiple BigFix servers, it is recommended to gather only sites enabled on all of your BigFix servers.

Note: At the first run after installing the BigFix server, the license information, the BES Support, and the Web UI Common components must be gathered for each installation. For this step, an AirgapResponse file must be created for each BigFix server because license information is unique to each serial number.

If you want to update the license information of a particular BigFix server without changing version on any site, you can create an AirgapResponse file that contains only license information by running the Airgap tool with a site file containing no lines or with site files where all sites have the flag N. Run the following command:

On Windows operating systems:

BESAirgapTool.exe -site empty_site_list_filename 
-allowemptysite

On Linux operating systems:

./Airgap.sh -site empty_site_list_filename 
-allowemptysite

Enabling WebUI in air-gapped environments

To install the WebUI in air-gapped environments, perform the following steps:

1. Gather the latest BES Support and WebUI Common sites, and download the required files to install the WebUI Service. Load them to your BigFix server.
2. Install the WebUI Service by using the task "Install HCL BigFix WebUI Service" in BES Support site.
3. After the installation completes, wait for the activation of a WebUI Service (on Windows operating systems) or process (on Linux operating systems) on the WebUI targeting system. The WebUI initialization has started; wait for its completion. Initialization usually completes in few minutes, but it is suggested to wait 30 minutes or more before proceeding with step 4.
4. Gather all the latest WebUI sites and load them to your BigFix server. You can gather WebUI sites before running the task to install the WebUI service, but you can load them only after the WebUI initialization has completed.