Command-line basics

You can use the local command-line interface (CLI) to command both Deep Security Agents and the Deep Security Manager to perform many actions. The CLI can also configure some settings, and to display system resource usage.

You can also automate many of the CLI commands below using the Deep Security API. To get started with the API, see the First Steps Toward Deep Security Automation guide.

Below are command syntax and examples.

Deep Security Agent

dsa_control

You can use dsa_control to configure some agent settings, and to manually trigger it to perform some actions such as an anti-malware scan or baseline rebuild.

In Windows:

• Open a Command Prompt as Administrator
• cd C:\Program Files\Trend Micro\Deep Security Agent\
• dsa_control -m "AntiMalwareManualScan:true"

In Linux:

• /opt/ds_agent/dsa_control -m "AntiMalwareManualScan:true"

Usage

dsa_control [-a <str>] [-b] [-c <str>] [-d] [-g <str>] [-s <num>] [-m] [-p <str>] [-r] [-R <str>] [-t <num>] [-u <str>:<str>] [-w <str>:<str>] [-x dsm_proxy://<str>] [-y relay_proxy://<str>] [--buildBaseline] [--scanForChanges] [Additional keyword:value data to send to Manager during activation or heartbeat...]

• -a <str>, --activate=<str> Activate agent with Manager at specified URL. URL format must be:

  dsm://<host or IP>:<port>/

  where port is the manager's discovery and heartbeat port number.

• -b, --bundle Create update bundle.
• -c <str>, --cert=<str> Identify the certificate file.
• -d, --diag Generate an agent diagnostic package.

• -g <str>, --agent=<str> Agent URL. Defaults to:

  https://localhost:<port>/

  where port is the Manager's listening port number.

• -m, --heartbeat Ask the Agent to contact the Manager now.

• -p <str>, --passwd=<str> Authentication password. If you type the password directly into the command line, it will be displayed on screen. To hide the password with asterisks (*) while you type, enter the interactive form of the command, which will prompt you for the password:

  dsa_control -p *

• -r, --reset Reset agent configuration.
• -R <str>, --restore=<str> Restore quarantined file. (Deep Security)
• -s <num>, --selfprotect=<num> enable self-protection on the Agent by preventing local end-users from uninstalling, stopping, or otherwise controlling the Agent. Command-line instructions must include the authentication password when self-protection is enabled. (1: enable, 0: disable). This is a Windows-only feature.
  In Deep Security 9.0 and earlier, this option was -H <num>, --harden=<num>
• -t <num>, --retries=<num> If dsa_control cannot contact the Agent service to carry out accompanying instructions, this parameter instructs dsa_control to retry <num> number of times. There is a one second pause between retries.
• -u <user>:<password> If the agent connects through a proxy to the manager, provide the proxy user name and password, separated by a colon (:).
• -w <user>:<password> If the agent connects through a proxy to a relay for security updates and software, provide the proxy user name and password, separated by a colon (:).
• -x dsm_proxy://<str>:<num> If the agent connects through a proxy to the manager, provide the proxy's IP address or FQDN and port number, separated by a colon (:).
• -y relay_proxy://<str>:<num> If the agent connects through a proxy to a relay for security updates and software, provide the proxy's IP address or FQDN and port number, separated by a colon (:).
• --buildBaseline Build baseline for Integrity Monitoring
• --scanForChanges Scan for changes for Integrity Monitoring
• --max-dsm-retries Number of times to retry an activation. Valid values are 0 to 100, inclusive. The default value is 30.
• --dsm-retry-interval Approximate delay in seconds between retrying activations. Valid values are 1 to 3600, inclusive. The default value is 300.

Agent-initiated activation ("dsa_control -a")

An Agent installed on a computer needs to be activated before the Manager can assign Rules and Policies to protect the computer. The activation process includes the exchange of unique fingerprints between the Agent and the Manager. This ensures that only one Manager (or one of its Manager Nodes) can send instructions to and communicate with the Agent.

You can manually activate an Agent from the Manager by right-clicking on the computer in the Computers screen and selecting Actions > Activate/Reactivate.

Agents can initiate the activation process using a locally-run command-line tool. This is useful when a large number of computers will be added to an installation and you want to write a script to automate the activation process. To enabled agent-initiated activation, go to Administration > System Settings > Agents and select Allow Agent-Initiated Activation.

The minimum activation instruction contains the activation command and the Manager's URL (including the port number):

dsa_control -a dsm://<host>:<port>/

where:

• -a is the command to activate the Agent, and
• dsm://<host>:<port>/ is the parameter that points the Agent to the Manager. (<host> could be the Manager's fully qualified domain name (FQDN), IPv4 address, or IPv6 address, and <port> is the Agent-to-Manager communication port number.) For example:

  dsa_control -a dsm://fe80::ad4a:af37:17cf:8937:4120

The host name is the only required parameter. Additional parameters are also available (see the table of available parameters below). They must be entered as key:value pairs (with a colon as a separator). There is no limit to the number of key:value pairs you can enter but the key:value pairs must be separated from each other by a space. For example:

dsa_control -a dsm://dsm-example-com:4120/ hostname:www12 "description:Long Description With Spaces"

(Quotation marks are only required if your value includes spaces or special characters.)

Agent-initiated activation over a private network via proxy

Agents on a private network can perform agent-initiated communication with a manager through a proxy server.

1. In Deep Security Manager, go to Administration > System Settings > Agents.
2. In the Agent-Initiated Activation area:
   • Select Allow Agent-Initiated Activation.
   • Select Allow Agent to specify hostname.
   • In the If a computer with the same name exists list, select "Activate a new Computer with the same name".
3. Click Save.
   
   

Use the following command-line options to instruct the Agent to communicate with the Manager through a proxy server:

Syntax	Notes
dsa_control -x "dsm_proxy://<host or IP>/"	Sets the address of the proxy server which the Agent uses to communicate with the Manager.
dsa_control -x ""	Clears the proxy server address.
dsa_control -u "<username:password>"	Sets the proxy user name and password.
dsa_control -u ""	Clears the proxy user name and password.
Examples
dsa_control -x "dsm_proxy://172.21.3.184:808/"	Proxy IPv4 address.
dsa_control -x "dsm_proxy://squid:808/"	Proxy host name.
dsa_control -x "dsm_proxy://[fe80::340a:7671:64e7:14cc]:808/"	Proxy IPv6 address.
dsa_control -u "root:Passw0rd!"	Proxy authentication is "root" and password is "Passw0rd!" (basic authentication only, digest and NTLM are not supported).

When used in the context of agent-initiated activation, the proxy commands must be issued first, followed by the agent-initiated activation commands. The following example shows a complete sequence for setting a proxy address, setting proxy credentials, and activating the Agent:

dsa_control -x "dsm_proxy://172.21.3.184:808/"
dsa_control -u "root:Passw0rd!"
dsa_control -a "dsm://dsm.example.com:4120/"
Required Setting in Deep Security Manager

Agent-initiated heartbeat command ("dsa_control -m")

The agent-initiated heartbeat command will instruct the agent to perform an immediate heartbeat operation to the manager. Although this may be useful on its own, like the activation command above, the heartbeat command can be used to pass along a further set of parameters to the manager.

The following table lists the parameters that are available to the activation and heartbeat commands. Note that some parameters can only be used either during activation, or after activation during heartbeat exclusively.

Parameter	Description	Example	Use during Activation	Use during Heartbeat
AntiMalwareCancelManualScan	Boolean. Cancels an on-demand ("manual") scan that is currently occurring on the computer.	"AntiMalwareCancelManualScan:true"	no	yes
AntiMalwareManualScan	Boolean. Initiates an on-demand ("manual") anti-malware scan on the computer.	"AntiMalwareManualScan:true"	no	yes
description	String. Sets description value. Maximum length 2000 characters.	"description:Extra information about the host"	yes	yes
displayname	String. Sets displayname value. (Shown in parentheses next to the hostname.) Maximum length 2000 characters.	"displayname:the_name"	yes	yes
externalid	Integer. Sets the externalid value. This value can used to uniquely identify an Agent. The value can be accessed using the SOAP Web Service API.	"externalid:123"	yes	yes
group	String. Sets the computers page Group the computer belongs in. Maximum length 254 characters per group name per hierarchy level. The forward slash ("/") indicates a group hierarchy. The group parameter can read or create a hierarchy of groups. This parameter can only be used to add computers to standard groups under the main "Computers" root branch. It cannot be used to add computers to groups belonging to Directories (MS Active Directory), VMware vCenters, or Cloud Provider accounts.	"group:Zone A web servers"	yes	yes
groupid	Integer.	"groupid:33"	yes	yes
hostname	String. Maximum length 254 characters. The hostname can specify an IP address, hostname or FQDN that is best used to contact the computer in the Computers list in the Manager.	"hostname:www1"	yes	no
IntegrityScan	Boolean. Initiates an integrity scan on the computer.	"IntegrityScan:true"	no	yes
policy	String. Maximum length 254 characters. The policy name is a case-insensitive match to the policy list. If the policy is not found, no policy will be assigned. A policy assigned by an event-based task will override a policy assigned during agent-initiated activation.	"policy:Policy Name"	yes	yes
policyid	Integer.	"policyid:12"	yes	yes
relaygroup	String. Links the computer to a specific relay group. Maximum length 254 characters. The relay group name is a case-insensitive match to existing relay group names. If the relay group is not found the default relay group will be used. This does not affect relay groups assigned during event-based tasks. Use either this option or event-based tasks, not both.	"relaygroup:Custom Relay Group"	yes	yes
relaygroupid	Integer.	"relaygroupid:123"	yes	yes
relayid	Integer.	"relayid:123"	yes	yes
tenantIDand token	String. If using agent-initiated activation as a tenant, both tenantID and token are required. The tenantID and token can be obtained from the deployment script generation tool.	"tenantID:12651ADC-D4D5" and "token:8601626D-56EE"	yes	yes
RecommendationScan	Boolean. Initiate a recommendation scan on the computer.	"RecommendationScan:true"	no	yes
UpdateComponent	Boolean. Instructs the Manager to perform a security update.	"UpdateComponent:true"	no	yes
RebuildBaseline	Boolean. Rebuilds the integrity monitoring baseline on the computer.	"RebuildBaseline:true"	no	yes
UpdateConfiguration	Boolean. Instructs the Deep Security Manager to perform a "Send Policy" operation.	"UpdateConfiguration:true"	no	yes

Activate an agent

To activate an agent from the command line, you need to know the tenant ID and password. You can get them from the deployment script.

1. In the top right-hand corner of Deep Security Manager, click Support > Deployment Scripts.
2. Select your platform.
3. Select Activate Agent automatically after installation.
4. In the deployment script, locate the strings for tenantID and token.
   
   

Windows

In PowerShell:

& $Env:ProgramFiles"\Trend Micro\Deep Security Agent\dsa_control" -a <manager URL> <tenant ID> <token>

In cmd.exe:

C:\Windows\system32>"\Program Files\Trend Micro\Deep Security Agent\dsa_control" -a <manager URL> <tenant ID> <token>

Linux

/opt/ds_agent/dsa_control -a <manager URL> <tenant ID> <token>

Configure a proxy for anti-malware and rule updates

If the agent must connect to its relay through a proxy, you must configure the proxy connection.

Windows

1. Open a command prompt (cmd.exe) as Administrator.

2. Enter these commands:

   cd C:\Program Files\Trend Micro\Deep Security Agent\

   dsa_control -w myUserName:MTPassw0rd

   dsa_control -y relay_proxy://squid.example.com:443

Linux

/opt/ds_agent/dsa_control -w myUserName:MTPassw0rd

/opt/ds_agent/dsa_control -y relay_proxy://squid.example.com:443

Configure a proxy for connections to the manager

If the agent must connect to its manager through a proxy, you must configure the proxy connection.

Windows

1. Open a command prompt (cmd.exe) as Administrator.

2. Enter these commands:

   cd C:\Program Files\Trend Micro\Deep Security Agent\

   dsa_control -u myUserName:MTPassw0rd

   dsa_control -x dsm_proxy://squid.example.com:443

Linux

/opt/ds_agent/dsa_control -u myUserName:MTPassw0rd

/opt/ds_agent/dsa_control -x dsm_proxy://squid.example.com:443

Force the agent to contact the manager

Windows

In PowerShell:

& "\Program Files\Trend Micro\Deep Security Agent\dsa_control" -m

In cmd.exe:

C:\Windows\system32>"\Program Files\Trend Micro\Deep Security Agent\dsa_control" -m

Linux

/opt/ds_agent/dsa_control -m

Initiate a manual anti-malware scan

Windows

1. Open a command prompt (cmd.exe) as Administrator.

2. Enter these commands:

   cd C:\Program Files\Trend Micro\Deep Security Agent\

   dsa_control -m "AntiMalwareManualScan:true"

Linux

/opt/ds_agent/dsa_control -m "AntiMalwareManualScan:true"

Create a diagnostic package

Deep Security Technical Support might ask you to create a diagnostic package to help them troubleshoot and diagnose your issue. The diagnostic package is created in a zip file which is downloaded locally on the endpoint in operation. From there you can send it to Technical Support. For more detailed instructions, see Create a diagnostic package and logs.

You can produce a diagnostic package for a managed computer through the Deep Security Manager but if the computer is in agent-initiated activation (AIA) mode it cannot collect all of the required logs. So when Technical Support asks for a diagnostic package you need to run the command directly on the managed computer.

Windows

In PowerShell:

& "\Program Files\Trend Micro\Deep Security Agent\dsa_control" -d

In cmd.exe:

C:\Windows\system32>"\Program Files\Trend Micro\Deep Security Agent\dsa_control" -d

Linux

/opt/ds_agent/dsa_control -d

Reset the agent

This command will remove the activation information from the target agent and deactivate it.

Windows

In PowerShell:

& "\Program Files\Trend Micro\Deep Security Agent\dsa_control" -r

In cmd.exe:

C:\Windows\system32>"\Program Files\Trend Micro\Deep Security Agent\dsa_control" -r

Linux

/opt/ds_agent/dsa_control -r

dsa_query

You can use the dsa_query command to display agent information:

• License-status of each component
• Scan progress
• Version information of security update components

Usage

dsa_query [-c <str>] [-p <str>] [-r <str]

• -p,--passwd <string>: authentication password. Required when agent self-protection is enabled.
  For some query-commands, authentication can be bypassed directly, in such case, password is not required.
• -c,--cmd <string>: execute query-command against the agent. The following commands are supported:
  • GetHostInfo: to query which identity is returned to the Manager during a heartbeat
  • GetAgentStatus: to query which protection modules are enabled and other miscellaneous information
  • GetComponentInfo: to query version information of anti-malware patterns and engines
  • GetPluginVersion: to query version information about the agent and protection modules
• -r,--raw <string>: returns the same query-command information as "-c" but in raw data format for third party software interpretation.

pattern: Wild card pattern to filter result. Optional.

Example:
dsa_query -c "GetComponentInfo" -r "au" "AM*"

Check CPU usage and RAM usage

Windows

Use the Task Manager or procmon.

Linux

top

Check that ds_agent processes or services are running

Windows

Use the Task Manager or procmon.

Linux

ps -ef|grep ds_agent

Restart an agent on Linux

service ds_agent restart

or

/etc/init.d/ds_agent restart

Some actions require either a -tenantname parameter or a -tenantid parameter. If execution problems occur when you use the tenant name, try the command using the associated tenant ID.