You can use the local command-line interface (CLI) to order agents and Workload Security
to perform actions. In addition, the CLI can be used to configure some settings and
display system resource usage.
You can automate many of the CLI commands using the Workload Security API. For more
information, see First Steps Toward Workload Security Automation.
dsa_control
You can use the
dsa_control
command to configure some agent
settings and to manually trigger certain actions such as activation,
anti-malware scans, and baseline rebuilds.Note the following:
-
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.
-
On macOS, when self-protection is enabled, local users cannot uninstall, modify, stop, or otherwise control the agent. They must also supply the authentication password when running CLI commands.
-
dsa_control
only supports English strings. Unicode is not supported.
To use
dsa_control
:On Windows:
- Open a Command Prompt as an Administrator.
- Change to the agent's installation directory:
cd C:\Program Files\Trend Micro\Deep Security Agent\
- Run the
dsa_control
command:dsa_control <option>
where<option>
is replaced with options described in dsa_control options.
On Linux:
-
Execute the following command:
sudo /opt/ds_agent/dsa_control <option>
where<option>
is replaced with options described in dsa_control options.
On macOS:
- Open a Terminal window as an Administrator.
- Change to the agent's installation directory:
cd "/Library/Application Support/com.trendmicro.DSAgent"
- Run the
dsa_control
command:dsa_control <option>
where<option>
is replaced with options described in dsa_control options.
dsa_control options
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 Workload
Security during activation or heartbeat...]
Parameter
|
Description
|
-a <str>, --activate=<str> |
Activate agent with manager at the specified URL in this
format:
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 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. Not supported on macOS.
|
-c <str>, --cert=<str> |
Identify the certificate file. Not supported on macOS.
|
-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=<str> |
Agent URL. Defaults to
https://localhost:<port>/ where
<port> is the manager's listening
port number. Not supported on macOS. |
-m, --heartbeat |
Force the agent to contact the manager now.
|
-p <str> or
--passwd=<str> |
Authentication password that you might have configured in
Workload Security previously. See Configure self-protection through Workload
Security 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=<str> |
Restore a quarantined file. On Windows, you can also restore
cleaned and deleted files.
|
-s <num>,
--selfprotect=<num> |
Enable agent self-protection (1: enable, 0: disable).
Self-protection prevents local end-users from uninstalling,
stopping, or otherwise controlling the agent. For details,
see Enable or disable agent self-protection.
Note that although
dsa_control lets you
enable self-protection, it does not let you configure an
associated authentication password. You need Workload
Security for that. See Configure self-protection through Workload
Security for details. Once configured, the password must be entered at the command
line using the
-p or
--passwd= option. |
-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
1 second pause between the retries. Not supported on
macOS. |
-u <user>:<password> |
Used in conjunction with the
-x option to
specify the proxy's username and password, if the proxy
requires authentication. Separate the username and password
by a colon (:). For example,
# ./dsa_control -x
dsm_proxy://<str> -u <new username>:<new
password> . To remove the username and password, type an empty string
("").
For example,
# ./dsa_control -x
dsm_proxy://<str> -u <existing
username>:"" . If you only want to update the proxy's password without
changing the proxy's username, you can use the
-u option without -x . For example,
# ./dsa_control -u <existing
username>:<new password> . Basic authentication only. Digest and NTLM are not supported.
Note that using
dsa_control -u only applies
to the agent's local configuration. No security policy is
changed on the manager as a result of running this
command. |
-w <user>:<password> |
Used in conjunction with the
-y option to
specify the proxy's user name and password, if the proxy
requires authentication. Separate the username and password
by a colon (:). For example,
# ./dsa_control -y
relay_proxy://<str> -w <new
username>:<new password> . To remove the username and password, type an empty string
("").
For example,
# ./dsa_control -y
relay_proxy://<str> -w <existing
username>:"" . If you only want to update the proxy's password without
changing the proxy's username, you can use the
-w option without -y . For example,
# ./dsa_control -w <existing
username>:<new password> . Basic authentication only. Digest and NTLM are not supported.
Note that using
dsa_control -w only applies
to the agent's local configuration. No security policy is
changed on the manager as a result of running this
command. |
-x dsm_proxy://<str>:<num> |
Configure a proxy between the agent and manager. Provide the
proxy's IPv4/IPv6 address or FQDN and port number, separated by a colon (:). Square
brackets must surround IPv6 addresses.
For example:
dsa_control -x
"dsm_proxy://[fe80::340a:7671:64e7:14cc]:808/" . To remove the address, instead of a URL, type an empty string
(""). See also the -u option. For more information, see
Connect to Workload Security via proxy.
Note that using
dsa_control -x only applies
to the agent's local configuration. No security policy is
changed on the manager as a result of running this
command. |
-y relay_proxy://<str>:<num> |
Configure a proxy between an agent and relay. Provide the
proxy's IP address or FQDN and port number, separated by a colon (:). Square
brackets must surround IPv6 addresses.
For example:
dsa_control -y
"relay_proxy://[fe80::340a:7671:64e7:14cc]:808/" . To remove the address, instead of a URL, type an empty string
(""). See also the -w option. For more information, see
Connect to relays via proxy.
Note that using
dsa_control -y only applies
to the agent's local configuration. No security policy is
changed on the manager as a result of running this
command. |
--buildBaseline |
Build the baseline for Integrity Monitoring. Not supported on
macOS.
|
--scanForChanges |
Scan for changes for Integrity Monitoring. Not supported on
macOS.
|
--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.
|
--autoDetectOSProxy |
A flag to enable/disable auto-detect OS proxy. The flag is
controlled by agent configuration in C1WS. Values are 1:
Enable, 0: Disable.
|
--osProxyResolveTimeout |
The timeout values of the proxy resolver, which can be set in
seconds, can be set by `dsa_control
--osProxyResolveTimeout=<resolveTimeout>;<connectTimeout>;<sendTimeout>;<receiveTimeout>.
Note they are separated by semicolons and each timeout value
ranges from 10 to 180.
|
--pacproxy |
Configures a Proxy Auto-Configuration (PAC)
server to resolve the corresponding proxy for the agent.
Provide the PAC server's IP address or FQDN, port number,
and path of the PAC file.
For example:
http://<Host>:<Port>/<PAC
file> To clear the PAC proxy setting, type an
empty string ("").The command must assign a certain
component type, for example:Set a PAC server for resolving proxy to communicate between
Manager
> dsa_control --pacproxy
http://pac.example/proxy.pac manager Set a PAC server for resolving proxy to communicate between
Relay
> dsa_control --pacproxy
http://pac.example/proxy.pac relay Set both of the above commands at once:
> dsa_control --pacproxy
http://pac.example/proxy.pac manager relay Clear existing settings:
> dsa_control --pacproxyunpw "" manager
relay For more information, see Connect to relays via proxy.
Note the following:
|
--pacproxyunpw |
Used in conjunction with the
--pacproxy
option. It specifies the PAC resolved proxy's user name and
password, if the proxy requires authentication. Separate the
username and password with a colon (:).To clear the username
and password, type an empty string ("").The command must
assign a certain component type, for example:Set a PAC
server for resolving proxy to communicate between
Manager> dsa_control --pacproxyunpw
<username>:<password> manager Set a
PAC server for resolving proxy to communicate between
Relay> dsa_control --pacproxyunpw
<username>:<password> relay Set both
of the above commands at once:> dsa_control
--pacproxyunpw <username>:<password> manager
relay Clear existing settings:>
dsa_control --pacproxyunpw "" manager relay To
update the proxy's password without changing the proxy's
username, use the --pacproxyunpw option
without --pacproxy :> dsa_control
--pacproxyunpw <existing username>:<new
password> .Note the following:
|
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.
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 of
dsa_control -a
dsm://<host>:<port>/
where:<host>
could be either the manager's fully qualified domain name (FQDN), IPv4 address, or IPv6 address.<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.
Similarly to activation, the heartbeat command can also send settings to the
manager during the connection.
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 the computer's description. Maximum length 2000
characters.
|
"description:Extra information about the
host" |
yes
|
yes
|
displayname |
String. Sets the display name shown in parentheses next to
the hostname on Computers. Maximum length 2000
characters.
|
"displayname:the_name" |
yes
|
yes
|
externalid |
Integer. 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. |
"externalid:123" |
yes
|
yes
|
group |
String. 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. |
"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 the manager can
use to connect to the agent.
|
"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
|
tenantID and 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 Workload Security to perform a security
update. When using the
UpdateComponent
parameter on version 12.0+ agents, make sure the relay is
also at version 12.0 or later. Learn more. |
"UpdateComponent:true" |
no
|
yes
|
RebuildBaseline |
Boolean. Rebuilds the Integrity Monitoring baseline on the
computer.
|
"RebuildBaseline:true" |
no
|
yes
|
UpdateConfiguration |
Boolean. Instructs Workload Security 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, both of which you can get from the deployment script.
Procedure
- In the top right of Workload Security, click .
- Select your platform.
- Select Activate Agent automatically after installation.
- In the deployment script, locate the strings for
tenantID
andtoken
.
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>
macOS
cd "/Library/Application Support/com.trendmicro.DSAgent/"
sudo ./dsa_control -a <manager URL> <tenant ID> <token>
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
macOS
cd "/Library/Application Support/com.trendmicro.DSAgent/"
sudo ./dsa_control -m
Initiate a manual anti-malware scan
Windows
Procedure
- Open the command prompt (cmd.exe) as an Administrator.
- Enter the following commands:
cd C:\Program Files\Trend Micro\Deep Security Agent\
dsa_control -m "AntiMalwareManualScan:true"
Linux
/opt/ds_agent/dsa_control -m "AntiMalwareManualScan:true"
macOS
Not supported.
Create a diagnostic package
If you need to troubleshoot an agent issue, your support provider might ask you
to create and send a diagnostic package from the computer. For more details, see
Create an agent diagnostic package via CLI on a protected
computer.
![]() |
NoteYou can produce a diagnostic package for an agent computer through Workload
Security but if the agent computer is configured to use Agent / Appliance Initiated communication, then the manager
cannot collect all the required logs. Therefore, when Technical Support asks
for a diagnostic package, you need to run the command directly on the agent
computer.
|
Reset the agent
This command removes 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
macOS
cd "/Library/Application Support/com.trendmicro.DSAgent/"
sudo ./dsa_control -r
dsa_query
You can use the
dsa_query
command to display agent
information.Note that this command is not supported by macOS.
dsa_query options
dsa_query [-c <str>] [-p <str>] [-r <str]
Parameter
|
Description
|
-p,--passwd <string> |
Authentication password used with the optional agent self-protection feature. Required if you
specified a password when enabling self-protection. Note
that 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, 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 <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
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.dsa_scan
If you have Administrator privileges on Windows or root access rights on Linux,
you can use the
dsa_scan
command to execute a scan task with
specified files or directories, including subdirectories.Up to ten
dsa_scan
commands can be concurrently executed on one
Deep Security Agent instance.This command ignores the agent's current scan policy on inclusions and exclusions
settings (
and ).To use
dsa_scan
:On Windows:
- Open the Command Prompt as an Administrator.
- Change to the agent's installation directory:
cd C:\Program Files\Trend Micro\Deep Security Agent\
- Run the
dsa_scan
command:dsa_scan <option>
where<option>
is one or more options described in dsa_scan options.
On Linux:
-
Execute the following command:
sudo /opt/ds_agent/dsa_scan <option>
where<option>
is one or more options described in dsa_scan options.
The
dsa_scan
command is not supported on macOS.dsa_scan options
dsa_scan [--target <str>] [--action <str>] [--log
<str>]
Parameter
|
Description
|
--target |
File paths or directories with the delimiter "`
|
--action |
Optional.Supported actions are pass, delete, quarantine.The
current agent scan actions of Manual Scan Configuration are
applied if the parameter action is not supplied.Example
command:
dsa_scan --action delete --target "c:\user
data,c:\app\config.exe" |
--log |
Optional.The absolute file path of an output log file.If this
option is not supplied, the scan result outputs to the
command-line console.Example output file:
"c:\temp\scan.log" Example command:
dsa_scan --target "c:\users\" --log
"c:\temp\scan.log" |
dsa_scan output
The following table describes the scan status labels that you would encounter
after executing the
dsa_scan
command:
Label
|
Description
|
Skipped
|
The scan file size limit was reached.
|
Infected
|
The file was detected by the scan engine and the action had
been taken.
|
Warning
|
The file was detected by the scan engine but it encountered
issues on the action taken. Check the error code.
|
The following is an example scan output:
C1WS DSA on-demand scan utility System date/time: 2023/10/12 16:04:10 trace id: 7acf6855-8547-46fc-a58f-9218d108e727 Scanning... [Skipped] Path: /home/user1/Documents/oversize.zip [Skipped] Path: /home/user1/Documents/xxx.big [Infected] Path: /home/user1/Documents/readme, Action: Passed, Malware Name: EICAR, QuarantineID: 0, Error code: 0 [Infected] Path: /home/user1/Documents/sales.doc, Action: Cleaned, Malware Name: BRAIN.A, QuarantineID: 0, Error code: 0 [Warning] Path: /home/user1/Documents/po.ppt, Action: Quarantine, Malware Name: RANSOM.A, QuarantineID: 0, Error code: 5 [Infected] Path: /home/user1/Documents/shipment.zip(po.exe), Action: Deleted, Spyware Name: BLKFRI.A, QuarantineID: 0, Error code: 0 25 files scanned, 2 skipped in 10 seconds. 4 files out of 25 were infected. End of Scan.
Scan exit codes
The
dsa_scan
command exit codes indicate either the scan success
or failure.Success exit codes
The success exit code is displayed when the
dsa_scan
utility completed the scan tasks without any issues detected or with a virus found
or having skipped some files, as per the following table:
Exit code
|
Description
|
Resolution
|
0
|
Scan completed and no malware found.
|
Scan task completed without malware found.
|
1
|
Scan completed with at least one malware found.
|
Check lines labelled as Infected and Warning in the output.
|
2
|
Scan completed, no malware found but some files skipped
|
Check lines labelled as Skipped in the output.
|
3
|
Scan completed, but at least malware found and some files skipped.
|
Check lines labelled as Infected, Warning, and Skipped in the output.
|
Fatal exit codes
If the
dsa_scan
utility encountered any fatal errors, the dsa_scan
broke the scan task and exited with an error code, as per the following table:
Exit code
|
Description
|
Resolution
|
246
|
The argument string is too long.
|
The string size limit is 2048 characters.Shorten the target parameter and try again.
|
247
|
The Security Platform is shutting down.
|
The agent is stopping.Try again later.
|
248
|
Too many instances.
|
There cannot be more than ten concurrent
dsa_scan running instances.Reduce the number of instances. |
249
|
No permission.
|
The command requires root on Linux and Administrator on Windows.Enable Allow the Agent
to Trigger or Cancel a Manual Scan on the scan policy.
|
250
|
Manual Scan Configuration is not set.
|
Configure the Manual Scan setting on the scan policy.
|
251
|
AM feature is not enabled.
|
Enable the AM feature on the scan policy.
|
252
|
The platform is not supported.
|
The
dsa_scan is not supported on the current OS platform. |
253
|
The agent is not running.
|
Deep Security Agent is not running.Enable the agent or contact the administrator.
|
254
|
Invalid parameters.
|
The input parameters are incorrect.
|
255
|
Unexpected error.
|
Try again later. If the issue persists, contact the administrator.
|