12/10/2019 Command-line basics | Deep Security

Get Started > DevOps, automation, and APIs > Command-line basics

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.

p: 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 in the Deep Security Automation Center.

Below are command syntax and examples:

Deep Security Agent

e: On Windows, when self-protection is enabled, local users cannot uninstall, update, stop, or otherwise control the agent. They
must also supply the authentication password when running CLI commands.

dsa_control
You can use dsa_control to configure some agent settings, and to manually trigger it to perform some actions such
as activation, 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:

sudo /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...]

Parameter Description

https://help.deepsecurity.trendmicro.com/command-line-utilities.html 1/12
12/10/2019 Command-line basics | Deep Security

Parameter Description

-a <str>, -- Activate agent with manager at the specified URL in this format:
activate=<str>
dsm://<host>:<port>/

where:

<host> could be either the manager's fully qualified domain name (FQDN), IPv4 address,
or IPv6 address
<port> is the manager's listening port number

Optionally, after the argument, you can also specify some settings such as the description to send
during activation. See Agent-initiated heartbeat command ("dsa_control -m"). 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 that you can enter, but the key:value pairs must be separated from each other by
a space. Quotation marks around the key:value pair are required if it includes spaces or special
characters.

-b, --bundle Create an update bundle.

-c <str>, --cert= Identify the certificate file.

<str>

-d, --diag Generate an agent package. For more detailed instructions, see Create an agent diagnostic
package via CLI on a protected computer.

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

<str>
https://localhost:<port>/

where <port> is the manager's listening port number.

-m, --heartbeat Force the agent to contact the manager now.

-p <str> or -- Authentication password that you might have configured in Deep Security Manager previously.
passwd=<str> See Configure self-protection through Deep Security Manager for details. If configured, the
password must be included with all dsa_control commands except dsa_control -a ,
dsa_control -x , and dsa_control -y .

Example: dsa_control -m -p MyPa$$w0rd

If you type the password directly into the command line, it is displayed on the screen. To hide the
password with asterisks (*) while you type, enter the interactive form of the command, -p * ,
which prompts you for the password.

Example:

dsa_control -m -p *

-r, --reset Reset the agent's configuration. This will remove the activation information from the agent and
deactivate it.

-R <str>, -- Restore a quarantined file. On Windows, you can also restore cleaned and deleted files.
restore=<str>

https://help.deepsecurity.trendmicro.com/command-line-utilities.html 2/12
12/10/2019 Command-line basics | Deep Security

Parameter Description

-s <num>, -- Enable agent self-protection (1: enable, 0: disable). Self-protection prevents local end-users from
selfprotect=<num> uninstalling, stopping, or otherwise controlling the agent. For details, see Enable or disable agent
self-protection. This is a Windows-only feature.

Note: Although dsa_control lets you enable self-protection, it does not let you configure an associated
authentication password. You'll need Deep Security Manager for that. See Configure self-
protection through Deep Security Manager for details. Once configured, the password will need
to be entered at the command line using the -p or --passwd= option.

Note: In Deep Security 9.0 and earlier, this option was -H <num>, --harden=<num>

-t <num>, -- If dsa_control cannot contact the agent service to carry out accompanying instructions, this
retries=<num> parameter instructs dsa_control to retry <num> number of times. There is a 1 second pause
between retries.

-u <user>: If the agent connects through a proxy to the manager, provide the proxy user name and
<password> password, separated by a colon (:). To remove the username and password, type an empty string
( "" ). Basic authentication only. Digest and NTLM are not supported.

-w <user>: If the agent connects through a proxy to a relay for security updates and software, provide the
<password> proxy user name and password, separated by a colon (:).

-x If the agent connects through a proxy to the manager, provide the proxy's IPv4/IPv6 address or
dsm_proxy://<str>: FQDN and port number, separated by a colon (:). To remove the address, instead of a URL, type
<num> an empty string ( "" ). Square brackets must surround IPv6 addresses. For
example: dsa_control -x "dsm_proxy://[fe80::340a:7671:64e7:14cc]:808/"

-y If the agent connects through a proxy to a relay for security updates and software, provide the
relay_proxy://<str>: proxy's IP address or FQDN and port number, separated by a colon (:).
<num>

--buildBaseline Build the 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- Approximate delay in seconds between retrying activations. Valid values are 1 to 3600, inclusive.
interval The default value is 300.

Agent-initiated activation ("dsa_control -a")

Enabling agent-initiated activation (AIA) can prevent communication issues between the manager and agents, and simplify agent
deployment when used with deployment scripts.

e: For instructions on how to configure AIA and use deployments scripts to activate agents, see Activate and protect agents using
agent-initiated activation and communication.

The command takes the form

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

where:

<host> could be either the manager's fully qualified domain name (FQDN), IPv4 address, or IPv6 address.

https://help.deepsecurity.trendmicro.com/command-line-utilities.html 3/12
12/10/2019 Command-line basics | Deep Security

<port> is the agent-to-manager communication port number (443).

For example:

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

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

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

You can force the agent to immediately send a heartbeat to the manager.

Like activation, the heartbeat command can also send settings to the manager during the connection.

Parameter Description Example Use Use

during during
Activation Heartbeat

AntiMalwareCancelManualScan Boolean. "AntiMalwareCancelManualScan:true" no yes

Cancels an on-
demand
("manual") scan
that is currently
occurring on the
computer.

AntiMalwareManualScan Boolean. "AntiMalwareManualScan:true" no yes

Initiates an on-
demand
("manual") anti-
malware scan on
the computer.

description String. "description:Extra information yes yes

about the host"
Sets the computer's
description.
Maximum length
2000 characters.

displayname String. "displayname:the_name" yes yes

Sets the display

name shown in
parentheses next to
the hostname on
Computers.
Maximum length
2000 characters.

https://help.deepsecurity.trendmicro.com/command-line-utilities.html 4/12
12/10/2019 Command-line basics | Deep Security

Parameter Description Example Use Use

during during
Activation Heartbeat

externalid Integer. "externalid:123" yes yes

Sets the
externalid
value. This value
can be used to
uniquely identify an
agent. The value
can be accessed
using the legacy
SOAP web service
API.

group String. "group:Zone A web servers" yes yes

Sets which group

the computer
belongs to on
Computers.
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
(Microsoft Active
Directory), VMware
vCenters, or cloud
provider accounts.

groupid Integer. "groupid:33" yes yes

https://help.deepsecurity.trendmicro.com/command-line-utilities.html 5/12
12/10/2019 Command-line basics | Deep Security

Parameter Description Example Use Use

during during
Activation Heartbeat

hostname String. "hostname:www1" yes no

Maximum length
254 characters.

The hostname can

specify an IP
address, hostname
or FQDN that the
manager can use to
connect to the
agent.

IntegrityScan Boolean. "IntegrityScan:true" no yes

Initiates an integrity
scan on the
computer.

policy String. "policy:Policy Name" yes yes

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.

policyid Integer. "policyid:12" yes yes

https://help.deepsecurity.trendmicro.com/command-line-utilities.html 6/12
12/10/2019 Command-line basics | Deep Security

Parameter Description Example Use Use

during during
Activation Heartbeat

relaygroup String. "relaygroup:Custom Relay Group" yes yes

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.

relaygroupid Integer. "relaygroupid:123" yes yes

relayid Integer. "relayid:123" yes yes

tenantID and token String. "tenantID:12651ADC-D4D5" yes yes

If using agent- and

initiated activation "token:8601626D-56EE"
as a tenant, both
tenantID and
token are
required. The
tenantID and
token can be
obtained from the
deployment script
generation tool.

https://help.deepsecurity.trendmicro.com/command-line-utilities.html 7/12
12/10/2019 Command-line basics | Deep Security

Parameter Description Example Use Use

during during
Activation Heartbeat

RecommendationScan Boolean. "RecommendationScan:true" no yes

Initiate a
recommendation
scan on the
computer.

UpdateComponent Boolean. "UpdateComponent:true" no yes

Instructs Deep
Security Manager
to perform a
security update.

When using the

UpdateComponent
parameter on Deep
Security Agent 12.0
or later, make sure
the Deep Security
Relay is also at
version 12.0 or
later. Learn more.

RebuildBaseline Boolean. "RebuildBaseline:true" no yes

Rebuilds the
integrity monitoring
baseline on the
computer.

UpdateConfiguration Boolean. "UpdateConfiguration:true" no yes

Instructs Deep
Security Manager
to perform a "Send
Policy" operation.

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 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
https://help.deepsecurity.trendmicro.com/command-line-utilities.html 8/12
12/10/2019 Command-line basics | Deep Security

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:
https://help.deepsecurity.trendmicro.com/command-line-utilities.html 9/12
12/10/2019 Command-line basics | Deep Security

& "\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

If you need to troubleshoot a Deep Security Agent issue, your support provider might ask you to create and send a diagnostic
package from the computer. For more detailed instructions, see Create an agent diagnostic package via CLI on a protected
computer.

e: You can produce a diagnostic package for a Deep Security Agent computer through the Deep Security Manager but if the agent
computer is configured to use Agent/Appliance Initiated communication, then the manager cannot collect all the required logs.
So when Technical Support asks for a diagnostic package, you need to run the command directly on the agent computer.

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.

Usage
https://help.deepsecurity.trendmicro.com/command-line-utilities.html 10/12
12/10/2019 Command-line basics | Deep Security

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

Parameter Description

-p,--passwd Authentication password used with the optional agent self-protection feature. Required if you specified a
<string> password when enabling self-protection.

Note: For some query-commands, authentication can be bypassed directly, in such case, password is not
required.

-c,--cmd Execute query-command against the agent. The following commands are supported:
<string>
"GetHostInfo" : to query which identity is returned to the manager during a heartbeat
"GetAgentStatus" : to query which protection modules are enabled, the status of Anti-Malware or
Integrity Monitoring scans in progress, and other miscellaneous information
"GetComponentInfo" : to query version information of anti-malware patterns and engines
"GetPluginVersion" : to query version information of the agent and protection modules

-r,--raw Returns the same query-command information as "-c" but in raw data format for third party software
<string> 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

https://help.deepsecurity.trendmicro.com/command-line-utilities.html 11/12
12/10/2019 Command-line basics | Deep Security

service ds_agent restart

or

/etc/init.d/ds_agent restart

or

systemctl restart ds_agent

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.

Looking for help for other versions?

© 2019 Trend Micro Incorporated. All rights reserved.

Last Modified: December 4, 2019

https://help.deepsecurity.trendmicro.com/command-line-utilities.html 12/12