You can use the local command-line interface (CLI) to command both agents and Server & Workload Protection to perform many actions. The CLI can
also configure some settings, and to display system resource usage.
TipYou can also automate many of the CLI commands below using the Server & Workload Protection API. To get started with the API,
see First
Steps Toward Server & Workload Protection Automation.
|
Below are the CLI commands:
dsa_control
You can use
dsa_control
to configure some agent settings, and to
manually trigger some actions such as activation, anti-malware scans, and
baseline rebuilds.
NoteOn 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.
|
NoteOn 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.
|
NoteDsa_control only supports English strings. Unicode is not
supported. |
To use
dsa_control
:Procedure
- In Windows:
- Open a Command Prompt as Administrator.
- Change to the agent's installation directory. For example:
cd C:\Program Files\Trend Micro\Deep Security Agent\
- Run dsa_control:
dsa_control <option>
where<option>
is replaced with one of the options described in dsa_control options.
- In Linux:
-
sudo /opt/ds_agent/dsa_control <option>
where<option>
is replaced with one of the options described in dsa_control options.
-
- In macOS:
- Open a Terminal window as an Admin.
- Change to the agent's installation directory. For example:
cd /Library/Application Support/com.trendmicro.DSAgent
- Run dsa_control:
dsa_control <option>
where<option>
is replaced with one of the 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 Server & Workload Protection 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 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.
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.
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 Server & Workload Protection 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: Although dsa_control lets you enable
self-protection, it does not let you configure an associated
authentication password. You'll need Server & Workload Protection for that. See
Configure self-protection through Workload
Security for details. Once configured, the
password will need to 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 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: 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: 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 Server & Workload Protection
via proxy. Note: 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:
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.
|
||
--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> .
|
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.
NoteFor 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.<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 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 Server & Workload Protection 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 Server & Workload Protection 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.
Procedure
- In the top right corner of Server & Workload Protection, click .
- Select your platform.
- Select Activate Agent automatically after installation.
- In the deployment script, locate the strings for
tenantID
andtoken
.
What to do next
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 a command prompt (cmd.exe) as Administrator.
- 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"
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 detailed
instructions, see Create an agent diagnostic package via CLI on a protected
computer.
NoteYou can produce a diagnostic package for an agent computer through Server & Workload Protection 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
macOS
cd /Library/Application Support/com.trendmicro.DSAgent/
sudo ./dsa_control -r
dsa_query
NoteNot supported by macOS.
|
You can use the
dsa_query
command to display agent
information.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: 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.