BESAdmin Windows Command Line

The installation automatically downloads the BigFix Administration Tool program BESAdmin.exe, in the %PROGRAM FILES%\BigFix Enterprise\BES Server directory.

You can run the script BESAdmin.exe to perform additional operations. To run this script from the command prompt, use the following command:
.\BESAdmin.exe /service { arguments}
where service can be one of the following:
audittrailcleaner
converttoldapoperators
createwebuicredentials
findinvalidactions
findinvalidsignatures
minimumSupportedClient
minimumSupportedRelay
propagateAllOperatorSites
propertyidmapper
removecomputers
reportencryption
resetDatabaseEpoch
resignsecuritydata
revokewebuicredentials
rotateserversigningkey
securitysettings
setproxy
updatepassword
Note: The notation <path+license.pvk> used in the command syntax that is displayed across this topic stands for path_to_license_file/license.pvk.
Each service has the following arguments :
audittrailcleaner

You can run this service to remove historical data from the bfenterprise database that is stored to serve as an audit trail. This audit trail slowly increases in size over the lifetime of a BigFix deployment. The audit trail contains deleted and earlier versions of Fixlets, tasks, baselines, properties, mailbox files, actions, and analyses. The audit trail is not used by BigFix in any way and can be deleted to reduce the database size. BigFix recommends that you create a historic archive of the current database and save it to a secure location before you run this tool to preserve the audit trail, thus removing it from the product database, but not completely deleting the history.

The service can count and delete the following sets of data:

  • Older Versions of Custom Authored Content (/oldcontent): Every edit to Fixlets, Tasks, Baselines, and Analyses creates a new version, the earlier versions can be deleted.
  • Older Versions of Actions (/oldactions): Any time that you stop or start an Action, a new version is created; the earlier versions can be deleted.
  • Older Versions of relay.dat (/oldrelaydatfile): Any time that you install or uninstall a new relay, a new version is created; the earlier versions can be deleted.
  • Deleted Custom Authored Content (all versions) (/deletedcontent): When you delete a Fixlet, Task, Baseline, and Analysis using the console, the data is marked as deleted in the database and preserved. The deleted content, including all of the earlier versions, and the corresponding client reports can be deleted.
  • Deleted Actions(all versions) (/deletedactions): When you delete an action using the console, the data is marked as deleted in the database and preserved. The deleted actions, including all of the earlier versions, and the corresponding client reports can be deleted.
  • Useless Action Results (/uselessactionresults): Earlier versions of Endpoint Manager (before BigFix 7.2.4.60) might cause clients to report ActionResults that were not used in any way but would use up space in the database. These useless ActionResults can be deleted.
  • Orphaned sub-actions (/orphanedsubactions): From multiple action groups that were deleted.
  • Hidden Manual Computer Group Actions (/hiddenactions): Manual Computer Groups create hidden actions that add and remove computers to and from groups and the actions can build up over time. This option deletes actions after an expiration period (default 180 days) from when they were created.
  • Older Version of Mailbox Files (/deletedmailbox): Deleted Mailbox Files are stored in a table in the database and can be removed.
  • Synchronizing BES Consoles (/syncconsoles): The BigFix Console maintains a local cache of the database that becomes not synchronized when data is removed with this tool. To avoid such inconsistencies, the tool sets a flag in the database to force all BigFix Consoles to reload the cache when the Console is started up.
  • Removing data older than (/olderthan): Removes data earlier than a specified date.
  • Batched deletion (/batchsize): Deleting large sets of data causes the SQL transaction log to quickly increase in size, the log temporarily becomes larger than the data being removed until the database is shrunk. Batched deletion removes results in sets.
The syntax of this service changes depending on the action you specify: 
.\BESAdmin.exe /audittrailcleaner { /displaysettings | /run [delete_data_options] |  
          /schedule [delete_data_options] [scheduling options] | /preview [delete_data_options] 
           [preview options] }
.\BESAdmin.exe /audittrailcleaner /displaysettings 
.\BESAdmin.exe /audittrailcleaner /run [ /oldcontent ] [ /oldactions ]
          [ /oldrelaydatfile ] [ /deletedcontent ] [ /deletedactions ] [ /hideUI ]
          [ /uselessactionresults ] [ /orphanedsubactions ] [ /hiddenactions=<days> ] 
          [ /deletedmailbox ] [ /syncconsoles ] [ /olderthan=<days> ] [ /batchsize=<size> ]  
.\BESAdmin.exe /audittrailcleaner /sitePvkLocation=<path+license.pvk> 
      [ /sitePvkPassword=<password> ] /schedule [ [ /oldcontent ] [ /oldactions ] 
      [ /oldrelaydatfile ] [ /deletedcontent ] [ /deletedactions ] [ /uselessactionresults ]
      [ /orphanedsubactions ] [ /hiddenactions=<days> ] [ /deletedmailbox ] [ /syncconsoles ]
      [ /olderthan=<days> ] [ /batchsize=<size> ] [ /cleanstarttime=<yyyymmdd:hhmm> 
      [ /cleanperiodicinterval=<hours> ] ] | /disable ]  
.\BESAdmin.exe /audittrailcleaner /preview [ [ /oldcontent ] [ /oldactions ] [
      /oldrelaydatfile ] [ /deletedcontent ] [ /deletedactions ] [ /uselessactionresults ] [
      /orphanedsubactions ] [ /hiddenactions=<days> ] [ /deletedmailbox ] [ /olderthan=<days> ] 
      | [ /scheduled ] ]
where:
  • displaysettings shows the settings that are previously set with the schedule action.
  • run runs the tool with the specified settings. Before you use this option, check the settings that affect the database by using the preview action. Use option /hideUI to avoid pop-up windows notifying action results.
  • schedule schedules the tool to run at the specified time at each specified interval. To disable the schedule action, use the disable option.
  • preview shows the number of database rows affected by the specified settings. If no setting is passed to the preview option, the preview performs the count by setting all options to true and using the default values for dates. Use the scheduled option to preview the scheduled settings.

For more information about the cleanup tasks log files, see Logging Cleanup Tasks Activities.

converttoldapoperators
You can convert local operators to LDAP operators, so that they can log in with their LDAP credentials. Optionally you can use the mappingFile argument to specify a file, the mapping file, where each line has the name of the user to convert, followed by a tab, followed by the name of the user in LDAP/AD. Specify the name using the same format that the user will use to log into the console, domain\user, user@domain, or user. If you do not specify a mapping file, all users are converted assuming their name in LDAP/AD is the same as their local user name.
The syntax to run this service is:
.\BESAdmin.exe /convertToLDAPOperators [/mappingFile:<file>]
createwebuicredentials
Use this service to generate the certificates used as WebUI credentials. Use the following syntax to run the command:
.\BESAdmin.exe /createwebuicredentials 
/sitePvkLocation:<path+license.pvk>
/sitePvkPassword:<pwd> /webUICertDir:<path>
/webUIHostname:<WebUIHostnameOrIP>
This service generates a folder named cert_WebUIHostnameOrIP in the path specified by the webUICertDir option.
webUICertDir
Specifies the path to the parent folder of the new folder containing the certificates. This folder must exist.
webUIHostname
Specifies the hostname or IP address of the computer that will host your WebUI.
Note: If you need to generate WebUI credentials certificates, but you have no WebUI in your deployment, then set:
webUICertDir
To the BigFix server folder. For example, BigFix Enterprise\BES Server.
webUIHostname
To the BigFix server IP address or hostname.
findinvalidactions
You can check for invalid actions in the database by specifying the following parameter:
  • (Optional) -deleteInvalidActions: Deletes invalid actions.
The syntax to run this service is:
.\BESAdmin.exe /findinvalidactions [ /deleteInvalidActions ] 
/sitePvkLocation=<path+license.pvk> [ /sitePvkPassword=<pwd> ]
findinvalidsignatures
You can check the signatures of the objects in the database by specifying the following parameters:
-resignInvalidSignatures (optional)
Attempts to resign any invalid signatures that BESAdmin finds.
-deleteInvalidlySignedContent (optional)
Deletes contents with invalid signatures.
For more information about invalid signatures, see Resolving invalidly signed content problems in the console.
The syntax to run this service is:
.\BESAdmin.exe /findinvalidsignatures 
[ /resignInvalidSignatures | /deleteInvalidlySignedContent ]
minimumSupportedClient
This service defines the minimum version of the BigFix Agents that are used in your BigFix environment.
Note: Based on this setting, the BigFix components can decide when it is safe to assume the existence of newer functions across all the component in the deployment. Individual agent interactions might be rejected if the interaction does not comply with the limitations that are imposed by this setting.
The currently allowed values are:
  • 0.0 that means that no activity issued by BigFix Agents with versions earlier than V9.0, such as archive files and reports uploads, are prevented from running or limited. This behavior applies also if the minimumSupportedClient service is not set.
  • 9.0 that means that:
    • Unsigned reports, such as the reports sent by BigFix Clients earlier than V9.0, are discarded by FillDB.
    • The upload of an unsigned archive file that is generated on a BigFix Client earlier than V9.0, by an archive now command for example, fails.

If you ran a fresh installation of BigFix V9.5.6 or later using a BES Authorization file, by default all the BigFix Clients earlier than V9.0 are prevented from joining your environment because the minimumSupportedClient service is automatically set to 9.0.

The value assigned to this service, if set, remains unchanged:
  • If you upgraded to V9.5.6 or later.
  • If you installed BigFix V9.5.6 or later using an existing masthead.
In both cases, if the service did not exist before, it will not exist afterward as well.
The current value <VALUE> assigned in your environment to the minimumSupportedClient service is displayed in the line x-bes-minimum-supported-client-level: <VALUE> of the masthead file. You can see the current value by running the following query on the BigFix Server, using the Fixlet Debugger or the BigFix Query Application available on the BigFix WebUI:
Q: following text of last ": " of line whose (it starts with "x-bes-minimum-supported-client-level:" ) of masthead of site "actionsite"
The syntax to run this service is:
.\BESAdmin.exe [/sitePvkFile=<path+license.pvk>] [/sitePassword=<password>] 
/minimumSupportedClient=<version>.<release>

If you omit [/sitePvkFile=<path+license.pvk>] [/sitePassword=<password>], you will be requested to enter the site key and password in a pop-up window.

For example, if you want to state that Agents earlier than V9.0 are not supported in your BigFix environment, you can run the following command:
.\BESAdmin.exe /minimumSupportedClient=9.0
minimumSupportedRelay
You can use this service, added with BigFix V9.5.6, to enforce specific criteria that affects the BigFix Agent registration requests. If this service is enabled, V9.5.6 Agents can continue to register to the V9.5.6 BigFix environment if their registration requests are signed and sent across the Relays hierarchy using the HTTPS protocol.
Note: Based on this service, the BigFix components can decide when it is safe to enable newer functions across all the component in the deployment. Individual agent interactions might be rejected if they do not comply with the limitations that are imposed by this setting.
The currently allowed values are:
  • 0.0.0 that means that the BigFix Server accepts and manages:
    • Signed and unsigned registration requests coming from BigFix Agents.
    • Registration requests delivered from BigFix Agents that use the HTTP or the HTTPS protocols.
    This behavior applies by default when you upgrade from previous versions to BigFix V9.5.6 or later. In this case, the minimumSupportedRelay service is not added automatically to your configuration during the upgrade. Consider that this value is not displayed when you run the query to see the current value that is assigned in your environment to the minimumSupportedRelay service.
  • 9.5.6 or later, which means that:
    • The BigFix Server enforces that registration requests coming from BigFix Agents V9.5.6 or later must be properly signed.
    • The BigFix Server and the Relays V9.5.6 or later enforce the use of the HTTPS protocol when exchanging BigFix Agent registration data.
    These are side effects of enforcing this behavior:
    • BigFix Agents earlier than V9.0 cannot send registration requests to the BigFix Server because they cannot communicate using the HTTPS protocol.
    • Because BigFix Relays with versions earlier than V9.5.6 cannot handle correctly signed registration requests, any BigFix Client that uses those Relays might be prevented from continuing to register, or might fall back to a different parent Relay or directly to the Server.

If you ran a fresh installation of BigFix V9.5.6 or later using a License Authorization file, be aware that the side effects that are listed apply to your BigFix deployment because, in this particular installation scenario, the minimumSupportedRelay service is automatically set to 9.5.6 by default.

The current value <VALUE> assigned in your environment to the minimumSupportedRelay service is displayed in the line x-bes-minimum-supported-relay-level: <VALUE> of the masthead file. You can see the current value by running the following query on the BigFix Server, using the Fixlet Debugger or the BigFix Query Application available on the BigFix WebUI:
Q: following text of last ": " of line whose (it starts with 
"x-bes-minimum-supported-relay-level:" ) of masthead of site "actionsite"
This query displays a value only when <VALUE> is set to 9.5.6; if it is set to 0.0.0, it does not display a value.
The syntax to run this service is:
.\BESAdmin.exe [/sitePvkFile=<path+license.pvk>] [/sitePvkPassword=<password>] 
/minimumSupportedRelay=<version>.<release>.<modification>

If you omit [/sitePvkFile=<path+license.pvk>] [/sitePwkPassword=<password>], you must to enter the site key and password in a pop-up window.

For example, if you want that only the registration requests that are signed and carried through HTTPS are managed by your BigFix Server, you can run the following command:
.\BESAdmin.exe /minimumSupportedRelay=9.5.6
propagateAllOperatorSites
This service forces the server to propagate a new version of every operator site. This command is useful after a server migration because you can be sure that data are available for clients to gather and it prevents from failures. This is the command syntax:
.\BESAdmin.exe /propagateAllOperatorSites
propertyidmapper
This service creates, updates, and deletes a table (PropertyIDMap) in the BFEnterprise database that maps retrieved property names for the SiteID, AnalysisID, PropertyID used to reference properties in the QUESTIONRESULTS and LONGQUESTIONRESULTS tables. It creates the PropertyIDMap table if it does not exist (requires table creation permissions). This service must be run after creating or deleting a property to update the PropertyIDMap table with changes.

The general syntax of this service is the following: 

.\BESAdmin.exe /propertyidmapper  { /displaysettings | /run [property_idmapper_options] 
       |  /schedule [property_idmapper_options] [scheduling options] }

The syntax of this service changes depending on the action you specify: 

.\BESAdmin.exe /propertyidmapper /displaysettings 
.\BESAdmin.exe /propertyidmapper /run [ /createtable ] [ /removetable ] 
      [ /lookupproperty=<propertyname> ] [ /hideUI ]
.\BESAdmin.exe /propertyidmapper /schedule [ /createtable /starttime=<yyyymmdd:hhmm> 
     [ /interval=<hours> ] | /disable ]
where:
  • displaysettings shows the settings that are previously set with the schedule action.
  • run runs the tool with the specified settings. Use option /hideUI to avoid pop-up windows notifying action results.
  • schedule schedules the tool to run at the specified time at each specified interval. To disable the schedule action, use the disable option.

For more information about the cleanup tasks log files, see Logging Cleanup Tasks Activities.

removecomputers
The service runs database operations for the following sets of data:
  • Expired Computers (/deleteExpiredComputers) Marks computers as deleted if they have not reported in recently.
  • Deleted Computers (/purgeDeletedComputers): Physically deletes the computer related data from the database for computers that are already marked as deleted and have not reported in for a long time. It deletes the data related to an agent (such as the action results or the properties, and so on), not the agent itself that remains logically deleted (IsDeleted = 1) on the database. Therefore, as a consequence, if the same agent becomes active again, it is recognized and will reuse its previous computer ID.
  • Duplicate Computers (/deleteDuplicatedComputers): Marks older computers as deleted if a computer exists with the same computer name.
  • Removal of deleted Computers (/removeDeletedComputers): Physically deletes the computer information from the database for computers that are marked as deleted (IsDeleted = 1) since at least the indicated number of days (minimum 30). It deletes the information of the agent itself ( such as the computer ID, and so on). Therefore, as a consequence, if the same agent becomes active again, a totally new computer ID will be assigned to the agent.
  • Removal of uploaded Files (/removeDeletedUploads): Physically removes from the database the definition of uploaded files that are marked as deleted.
  • Removal of uploaded files of removed computers (/eraseUploadFilesForRemovedComputers): Physically removes from the BigFix server file system all files uploaded by clients whose definition has been removed from the database.
  • Removal of Computers by name (/removeComputersFile): Accepts a text file with a list of computer names that are separated by new lines and removes them from the deployment.
The general syntax of this service is: 
.\BESAdmin.exe /removecomputers  { /displaySettings | /run [remove_computers_options] 
       | /schedule [remove_computers_options] [scheduling options] 
       | /preview [remove_computers_options] [preview options] }
Depending on the action, you specify, the syntax changes as follows:
.\BESAdmin.exe /removecomputers /displaySettings 
.\BESAdmin.exe /removecomputers /run [ /deleteExpiredComputers=<days> ] 
    [ /removeDeletedComputers=<days> ] [ /removeDeletedUploads ]
    [ /eraseUploadFilesForRemovedComputers ] 
    [ /purgeDeletedComputers=<days> ] 
    [ /deleteDuplicatedComputers [ /duplicatedPropertyName=<PropertyName> ] ] 
    [ /removeComputersFile=<path> ] [ /batchSize=<batch size> ] [ /hideUI ]
.\BESAdmin.exe /removecomputers /schedule [ [ /deleteExpiredComputers=<days> ] 
    [ /removeDeletedComputers=<days> ] [ /removeDeletedUploads ]
    [ /eraseUploadFilesForRemovedComputers ] 
    [ /purgeDeletedComputers=<days> ]
    [ /deleteDuplicatedComputers [ /duplicatedPropertyName=<PropertyName> ] ] 
    [ /removeStartTime=<YYYYMMDD:HHMM> [ /removePeriodicInterval=<Hours> ] ] 
    [ /batchSize=<batch size> ] | /disable ] 
.\BESAdmin.exe /removecomputers /preview [ [ /deleteExpiredComputers=<days> ] 
    [ /removeDeletedComputers=<days> ] [ /removeDeletedUploads ]
    [ /eraseUploadFilesForRemovedComputers ] 
    [ /purgeDeletedComputers=<days> ][ /deleteDuplicatedComputers 
    [ /duplicatedPropertyName=<PropertyName> ] ] | [ /scheduled ] ]
where:
  • displaySettings shows the settings that are previously set with the schedule action.
  • run runs the tool with the specified settings. Before you use this option, check the settings that affect the database by using the preview action. Use option /hideUI to avoid pop-up windows that notify the action results.
  • schedule schedules the tool to run at the specified time at each specified interval. To disable the schedule action, use the disable option.
  • preview shows the number of database rows that are affected by the specified settings. If no setting is passed to the preview option, the preview performs the count by setting all options to true and using the default values for dates. Use the scheduled option to preview the scheduled settings.
Note: When using option /removeDeletedComputers, the number of days must be not less than 30.

For information about the cleanup tasks log files, see Logging Cleanup Tasks Activities.

reportencryption
You can generate, rotate, enable, and disable encryption for report messaging by running:
.\BESAdmin.exe /reportencryption { /status |
  /generatekey [/privateKeySize=<min|max>] 
               [/deploynow=yes | /deploynow=no /outkeypath=<path>] 
               /sitePvkLocation=<path+license.pvk> [/sitePvkPassword=<password>] |
  /rotatekey [/privateKeySize=<min|max> ] 
             [/deploynow=yes | /deploynow=no /outkeypath=<path> ] 
             /sitePvkLocation=<path+license.pvk> [/sitePvkPassword=<password>] |
  /enablekey /sitePvkLocation=<path+license.pvk> [/sitePvkPassword=<password>] |
  /disable /sitePvkLocation=<path+license.pvk> [/sitePvkPassword=<password>] }
where:
status
Shows the status of the encryption and which arguments you can use for that status.
generatekey
Allows you to generate a new encryption key.
rotatekey
Allows you to change the encryption key.
enablekey
Allows you to enable the encryption key.
disable
Allows you to put the encryption key in PENDING state. If you run again the reportencryption command with the disable argument, the encryption changes from PENDING state to DISABLED.
deploynow=yes
Deploys the report encryption key to the server for decryption.
deploynow=no -outkeypath=<path>
The encryption key is not deployed to the server but it is saved in the outkeypath path.
For more information about this command and its behavior, see Managing Client Encryption.
resetDatabaseEpoch
To clear all console cache information in BigFix Enterprise Service V7.0 or later versions. After you run this command: 
.\BESAdmin.exe /resetDatabaseEpoch
subsequent console logins reload their cache files.
resignsecuritydata
You must resign all of the users content in the database by entering the following command: 
.\BESAdmin.exe /resignSecurityData
if you get one of the following errors: 
class SignedDataVerificationFailure 
HTTP Error 18: An unknown error occurred while transferring data from the server
when trying to login to the BigFix console. This command resigns security data by using the existing key file. You can also specify the following parameter:
/mastheadLocation=<path+/actionsite.afxm>
The complete syntax to run this service is:
.\BESAdmin.exe /resignsecuritydata /sitePvkLocation=<path+license.pvk>
[ /sitePvkPassword=<password> ] /mastheadLocation=<path+/actionsite.afxm>
revokewebuicredentials
You can revoke the authentication certificate of a specified WebUI instance.
The syntax to run this service is: 
.\BESAdmin.exe /revokewebuicredentials /hostname=<host> /sitePvkLocation=<path+license.pvk> /sitePvkPassword=<pvk_password>
If an authentication certificate is issued for the specified hostname, this certificate is revoked and the WebUI instance running on that hostname can no longer connect to the root server.

After revoking the credentials for a WebUI host, it will no longer connect to the root server. You can either remove the WebUI installation, or generate new credentials for that host, and replace the old certificate files on that host.

rotateserversigningkey
You can rotate the server private key to have the key in the file system match the key in the database. The command creates a new server signing key, resigns all existing content using the new key, and revokes the old key.
The syntax to run this service is:
.\BESAdmin.exe /rotateserversigningkey /sitePvkLocation=<path+license.pvk>
[ /sitePvkPassword=<password> ]
securitysettings { /hideFromFieldFromMasthead | /showFromFieldFromMasthead }
You can specify if you want to show or hide the value displayed by the From field in the masthead which contains the email address of the license assignee. During a fresh installation the value is hidden and the option "hideFromFieldFromMasthead" is set to 1. During an upgrade the value remains unchanged.
The syntax to run this service is: 
.\BESAdmin.exe /securitysettings 
{ /hideFromFieldFromMasthead | /showFromFieldFromMasthead }
[/sitePvkLocation=<path+license.pvk>] [/sitePvkPassword=<pvk_password>]
Note: You can modify the "hideFromFieldFromMasthead" option from the BESAdmin command line only. Doing it from the BESAdmin interface is not supported because the masthead will not be regenerated when modifying the settings from the advanced settings panel of the interface.
securitysettings { /testTLSCipherList | /setTLSCipherList | /listTLSCiphers | /removeTLSCipherList }

To test if a TLS cipher list is compatible with the BigFix components, run the following command:

.\BESAdmin.exe /securitysettings /sitePvkLocation=<path+license.pvk> /sitePvkPassword=<password> 
/testTLSCipherList=<cipher_1>:<cipher_2>:..:<cipher_n>

After identifying a suitable TLS cipher list, you can set it by running the following command:

.\BESAdmin.exe /securitysettings /sitePvkLocation=<path+license.pvk> /sitePvkPassword=<password> 
/setTLSCipherList=<cipher_1>:<cipher_2>:..:<cipher_n>

To list all the TLS ciphers that are currently enabled, run the following command:

.\BESAdmin.exe /securitysettings /sitePvkLocation=<path+license.pvk> /sitePvkPassword=<password> 
/listTLSCiphers

To remove a TLS cipher list from the deployment masthead and return to the default cipher list, run the following command:

.\BESAdmin.exe /securitysettings /sitePvkLocation=<path+license.pvk> /sitePvkPassword=<password> 
/removeTLSCipherList
setproxy
If your enterprise uses a proxy to access the Internet, you must set a proxy connection to enable the BigFix server to gather content from sites and to do component-to-component communication or to download files.

For information about how to run the command and about the values to use for each argument, see Setting a proxy connection on the server.

updatepassword

You can modify the password that is used for authentication by product components in specific configurations.

The syntax to run this service is:

.\BESAdmin.exe /updatepassword /type=<server_db|dsa_db>
[/password=<password>] /sitePvkLocation=<path+license.pvk> 
[/sitePvkPassword=<pvk_password>]
where:
type=server_db
Specify this value to update the password that is used by the server to authenticate with the database.

If you modify this value, the command restarts all the BigFix server services.

type=dsa_db
Specify this value to update the password that is used in a DSA configuration by a server to authenticate with the database.
The settings /password and /sitePvkPassword are optional. If they are not specified in the command syntax, their value is requested interactively at run time. The password set by this command is obfuscated.