Skip to main content

Agent Command Line Utility

Introduction​

The Xshield agent service is installed on application servers and endpoints to publish information about operating systems and network events to the Xshield platform.

Along with the Xshield agent application, another utility application called the Xshield agent command tool is packaged. This tool can be used to perform certain service level operations to keep the Xshield agent running in the proper state.

The Xshield agent command tool works directly with the operating system to manage the Xshield agent lifecycle, such as installation, uninstallation, upgrades, and more. It also supports additional operations like diagnostics collection, system tag configuration, and proxy settings.

The tool is invoked with appropriate command-line arguments and may require administrative privileges for specific operations. It functions independently of the Xshield agent software and interacts directly with the operating system to perform tasks. Administrators can use the tool to resolve issues with Xshield agent operations under extreme circumstances. Some of the operations will also require the agent tampering protection password to perform the operation.

Xshield agent command Operations​

Usage​

Usage: [command] [--option <value>]

commands​

install​

Installs the Xshield agent software. The installation file can be local or specified via a URL.

install --file <local file> | --fileUrl <url> | [--force]

upgrade​

Upgrades the Xshield agent software. Requires the software to be already installed. The newer version can be on a local disk or specified via a URL.

upgrade --file <local file> | --fileUrl <url>

uninstall​

Uninstalls the Xshield agent service and removes the software. If Agent Tampering Protection is enabled, a password may be required.

uninstall [--password <password>]

precheck​

Lists prerequisites for running the Xshield agent service and ensures communication with the Xshield platform.

precheck --domain <domain>

setproxy​

Configures the proxy service for the Xshield agent to communicate with the Xshield platform.

setproxy --proxyUrl <proxy-url:port> --proxyUser <username> --proxyPassword <password>

register​

Registers the Xshield agent with the Xshield platform. Requires domain, deployment key, and agent type. Optional parameters include proxy configuration.

register --domain <domain name> --deploymentKey <deployment key> \
         --agentType <Server|User|Gateway> \
         [--conflictAction <abort|continue> --proxyUrl <proxyURL> \
         --proxyPassword <password> --proxyUser <proxyuser> --upgrade]

deregister​

Unregisters the Xshield agent from the Xshield platform and optionally purges associated data.

deregister [--purgeData]

start​

Starts the Xshield agent service after installation and registration.

start

stop​

Stops the Xshield agent service. If Agent Tampering Protection is enabled, a password may be required.

stop [--password <password>]

restart​

Restarts the Xshield agent service. Requires a password if Agent Tampering Protection is enabled.

restart [--password <password>]

resetrules​

Clears host firewall rules programmed by the Xshield agent. Requires a One-Time Password (OTP) provided by the tenant administrator.

resetrules --name <rulename1,rulename2...> | --filterid <filterid1,filterid2...> | --otp <otp_value>

disable​

Stops the Xshield agent and clears host firewall rules. Moves the service to a disabled state, preventing restarts until manually enabled. Requires a password if tamper protection is enabled.

disable [--password <password>] --startupTypeManual

diagnose​

Collects diagnostic information, including operating system data, server information, and Xshield agent logs. Optionally uploads diagnostics to a specified destination.

diagnose [--upload]

gettagnames​

Lists tag names associated with the Xshield agent. Optional argument returns data in JSON format.

gettagnames [--json]

gettags​

Returns key-value pairs of tag names and values for the asset. Optional argument retrieves data in JSON format.

gettags [--json]

settags​

Allows operators to specify custom tags for the asset, which are sent to the Xshield platform.

settags --tags "tagName1":"tagValue1" "tagName2":"tagValue2"

help​

Displays help information.

help

Summary​

The Xshield agent command tool is a powerful utility for managing Xshield agent lifecycle operations and troubleshooting. Administrators must use it carefully to avoid disrupting Xshield agent services. Proper usage ensures smooth functionality and system security.