Topics marked with * relate to HQ Enterprise-only features.
Feedback is welcome. Click Add Comment at the bottom of the page.
This table lists the command-line tools:
|agent||List the agents registered with the HQ Server.|
|alertdefinition||List, update, create, and delete resource and resource type alert definitions. An alert definition specifies the alert details and the resource or resource type to which it is assigned.|
|alert||List, acknowledge, fix, and delete fired alerts.|
|application||Create, list, and update applications configured in HQ.|
|autodiscovery||List the platforms in the autodiscovery queue and approve them for import to inventory.|
|control||List supported control actions for a resource, list control action history for a resource, and perform issue a control action to a resource.|
|dependency*||List and manage dependency relationships between network or virtual hosts and platforms.|
|escalation||List and update Escalations.|
|event||List information about events – alerts, resource control actions, log events, or configuration events – that have been logged for a resource, or for all resources.|
|group||List resource group definitions, create or update groups, and delete groups.|
|maintenance*||Specify downtime periods for a compatible group, during which alerts on group members will not fire. Supported in HQ Enterprise only.|
|metric||List and update the metric collection configuration for individual resources.|
|metricData||List the measurements for a particular metric for a particular resource.|
|metricTemplate||Output metric collection configuration for a specified resource type.|
|resource||Output resource data, create or update resources, and delete resources.|
|role||List, update, and create non-system roles.|
|serverConfig||List and update selected HQ Server configuration properties,|
|user||List, update, and create users.|
To invoke the command-line tools from shell, you run the hqapi.sh script in the /bin directory of the client download, supplying the name of the tool you want to run. All commands have the following syntax:
./bin/hqapi.sh <top-level-command> <sub-command> <options>
- <top-level-command> is the command-line tool name, for instance agent or resource.
- <sub-command> is a supported command option, for instance list, sync, or delete.
- <options> are one or more supported command qualifiers Supported options vary by command and subcommand, for example resource list supports the --prototype qualifier. See documentation for each command-line tool for supported command qualifiers.
This command returns a list of resources whose type is "MacOSX".
./bin/hqapi.sh resource list --prototype="MacOSX"
In the case of an error, the reason for the error will be printed to stderr and the process will exit with a negative return code.
A full listing of supported options can be obtained by passing the -h flag to any command.
Each command-line tool has one or more command options. The most common are described below.
list returns an XML object that describes one or more instances of the type of object you're working with - for instance, agents, resources, or roles. You can write the XML output to a file, and pipe it to the sync command to update the corresponding data in the HQ database. For example:
./bin/hqapi.sh resource list --prototype="HTTP" > http-resources.xml
sync takes a valid XML object that describes items in HQ - for instance, platforms, servers, or services - and updates the HQ database accordingly.
For some command-line tools, sync can create new items in HQ; for others, sync only updates items that already exist in HQ.
Note: When you use sync to create a new item, do not specify the id attribute for the new item.
To update an item, typically you write the XML object to a file using the list option, edit the contents as desired, and then use sync to update attributes for an existing item in HQ.
By default, sync reads the XML over stdin. For example:
cat http-resources.xml | ./bin/hqapi.sh resource sync
As desired, you can specify the location of the file with the --file command qualifier.
./bin/hqapi.sh resource sync --file=http-resources.xml
delete removes an item from the HQ database. The delete option supports only "one-at-a-time" deletions. You supply the name or ID of the item to delete.
For each command line tool there is a set of required and optional command qualifiers.
The optional qualifiers usually set the scope of a command, for example, tell it to list a single resource instead of all the resources on a platform. Scoping qualifiers vary by command and are documented in the each command's reference documentation.
The qualifiers that every command requires are the parameters that specify how to connect to the HQ Server:
|--host||HQ server hostname|
|--port||HQ server port|
|--user||user to connect as|
|--password||password for the given user|
|--secure||Flag to indicate if SSL should be used.|
The optional qualifiers that every command supports are:
|--properties||Supplies the path to a properties file that sets the values of the server connection settings listed above. Not necessary if you define the properties in the default location — ~/.hq/client.properties — as described below in Define a Connection Properties File|
To avoid specifying the connection parameters each time you run a command, you can specify them in ~/.hq/client.properties (create the directory and file if they do not already exist). Under Windows, you can create the .hq directory from a DOS shell. Use the mkdir command to create .hq under your home home directory.
|New in 3.0|
This feature was introduced in HQApi v3.0,available in HQ v4.3.
By default, the APIs look for server connection properties in ~/.hq/client.properties. If you want to put client.properties in a different location, you can do so, and then supply the path to the file on the command line, using the --properties command qualifier.
The ability to specify the location of client.properties from the command line is useful if you use HQApi to administer multiple HQ Server instances. You can create a properties file for each HQ Server instance — after than, when you run an API from the command line, you can specify the location of the file with the appropriate connection properties.
There is no un-do command for updates you make with the API command line tools. Carefully review the XML you supply to a command line tool's sync method.
When you run an HQ API command that operates on a particular resource you must identify the resource by its internal HQ ID. To obtain the ID for a resource, you can run the resource list command to find it. The resource list command returns inventory and configuration properties for one or more resources. For example, this command:
returns the results shown below; the third line defines the internal HQ ID for the resource: Resource id="27054"
You can use resource list to query by:
- resource name - regex for resource name
- platform name - to get properties for it and optionally, its child resources.
- resource type - by query by platform name and get properties for it, and optionally, the resources running on it.