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

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 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
-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.
-c <str>, --cert=<str>	Identify the certificate file.
-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.
-m, --heartbeat	Force 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 the agent's configuration. This will remove the activation information from the agent and deactivate it.
-R <str>, --restore=<str>	Restore a quarantined file.
-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.
-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.
-u <user>:<password>	If the agent connects through a proxy to the manager, provide the proxy user name and 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>:<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 IPv4/IPv6 address or FQDN and port number, separated by a colon (:). To remove the address, instead of a URL, type an empty string (""). Square brackets must surround IPv6 addresses. For example: dsa_control -x "dsm_proxy://[fe80::340a:7671:64e7:14cc]:808/"
-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 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-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")

The agent installed on a computer must be activated before the manager can assign rules and policies to protect the computer. Activation includes the exchange of unique fingerprints between the agent and the manager to authenticate each other for encrypted channels. This ensures that only one manager (or one of the other Deep Security Manager nodes that are connected to the same database) can send instructions to and communicate with the agent.

Activation can be either manager-initiated or agent-initiated (AIA), if enabled. AIA is useful if either a firewall/NAT prevents the manager from initiating the connection to agents, or if you deploy many agents at once, and you want to write a script to automate activation.

1. On Deep Security Manager, go to Administration > System Settings > Agents.
2. Select Allow Agent-Initiated Activation.

3. In your deployment script, after you install Deep Security Agent on the computer, run the activation command, such as:

   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.)

   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

Optionally, you can also specify some settings such as the description to send during activation. See Agent-initiated heartbeat command ("dsa_control -m").

Agent-initiated activation via proxy

If agents must connect through a proxy to the manager, you can configure agent-initiated communication via a proxy.

1. On 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.
   • From the If a computer with the same name exists list, select Activate a new Computer with the same name.
3. Click Save.

4. In your deployment script, after you install Deep Security Agent on the computer but before you activate it, run the proxy configuration commands, such as:

   dsa_control -x "dsm_proxy://proxy.example.com:808/"
dsa_control -u "root:Passw0rd!"
dsa_control -a "dsm://dsm.example.com: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 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
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 Deep Security 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 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 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

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.

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:

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

Usage

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

Parameter	Description
-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 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

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.

Deep Security Manager

You can use the dsm_c command to configure some settings on the manager, and to unlock user accounts.

Usage

dsm_c -action actionname

To print help on the command, use the -h option: dsm_c -h

All of the parameters shown in brackets in the table below are mandatory.

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.

Action Name	Description	Usage
addcert	Add a trusted certificate.	dsm_c -action addcert -purpose PURPOSE -cert CERT
addregion	Add a private cloud provider region.	dsm_c -action addregion -region REGION -display DISPLAY -endpoint ENDPOINT
changesetting	Change a setting. Back up your deployment before running the command. Don't use this command unless you understand the effects of the setting. Some misconfigurations can make your service unavailable, or your data unreadable. Usually, you should only use this command if requested by your technical support provider, who will tell you which setting NAME to change. Sometimes this command is required during normal use. If so, the setting will be described in that section of the documentation, such as masterkey.	dsm_c -action changesetting -name NAME [-value VALUE | -valuefile FILENAME] [-computerid COMPUTERID] [-computername COMPUTERNAME] [-policyid POLICYID] [-policyname POLICYNAME] [-tenantname TENANTNAME | -tenantid TENANTID]
createinsertstatements	Create insert statements (for export to a different database).	dsm_c -action createinsertstatements [-file FILEPATH] [-generateDDL] [-databaseType sqlserver|oracle] [-maxresultfromdb count] [-tenantname TENANTNAME | -tenantid TENANTID]
diagnostic	Create a diagnostic package for the system. If needed, you can Increase verbose diagnostic package process memory.	dsm_c -action diagnostic [-verbose 0|1] [-tenantname TENANTNAME | -tenantid TENANTID]
fullaccess	Give an administrator the full access role.	dsm_c -action fullaccess -username USERNAME [-tenantname TENANTNAME | -tenantid TENANTID]
listcerts	List trusted certificates.	dsm_c -action listcerts [-purpose PURPOSE]
listregions	List private cloud provider regions.	dsm_c -action listregions
masterkey	Generate, import, export, or use a custom master key to encrypt the: database password keystore password personal data If a custom master key is not configured, Deep Security will use a hard-coded seed, and personal data will not be encrypted by default.	If you already configured a custom master key during a new install, the installer has completed this setup for you. If you skipped master key creation, and want to configure one now, start with the commands in step 1. Enter all commands in order. If you configured the master key during an upgrade, back up your database and properties files, and then start with the commands in step 4. dsm_c -action masterkey -subaction [generatekmskey -arn AWSARN | generatelocalkey] — Generate the master key using either the Amazon Resource Name (ARN) of a Key Management System (KMS) key, or a local environment variable named LOCAL_KEY_SECRET. If using the local environment variable on a multi-node Deep Security Manager, it must be configured on all nodes, system-level (not user-level), and not more than 64 characters. Permissions and reliable network access to KMS or LOCAL_KEY_SECRET are required by Deep Security Manager if you configure the master key. The manager uses them to encrypt and decrypt the master key during use. If they temporarily cannot be reached, Deep Security Manager will be unable to decrypt required data, and the service will be unavailable. Symptoms can include intermittent event logs and alerts for restart failures and various other errors. dsm_c -action masterkey -subaction export -file FILEPATH — Export the master key to a password-encrypted file for backup. You will be prompted for the password. Back up the master key by exporting it to a safe location. If the master key is lost or destroyed, and you do not have a backup, all encrypted data will be unreadable. If that happens, you must reinstall Deep Security Manager, all relays, and all agents/appliances. If the key is stolen, security of your Deep Security deployment is compromised. Some compliance regulations such as General Data Protection Regulation (GDPR) in Europe may require you by law to notify law enforcement of personal data breaches within 72 hours, and noncompliance can result in fines. Consult your lawyer for more information. To verify your backup for disaster recovery, you can test it by importing the master key: dsm_c -action masterkey -subaction [importkmskey -file FILEPATH -arn AWSARN | importlocalkey -file FILEPATH] — Import a backup of the master key. This can be useful either for disaster recovery of a corrupted key, or to migrate the master key to another KMS. Before you run this command, you must delete the existing master key from the primary tenant (T0) database. For example, you might enter the SQL command: delete from systemsettings where uniquekey = 'settings.configuration.keyEncryptingKey' dsm_c -action masterkey -subaction encryptproperties — Use the master key to encrypt keystore and database passwords in dsm.properties and configuration.properties. Restart Deep Security Manager for this setting to take effect. dsm_c -action masterkey -subaction encrypttenantkey -tenantid [all | TENANTNUM] — Use the master key to encrypt existing tenant key seeds (if you have a multi-tenant deployment). Tenant key seeds are used to derive sub-keys that you can use in the next step. Safe to run multiple times; it will not apply multiple layers of encryption if the seed has already been encrypted. Optionally, if you want to encrypt only for new tenants while you slowly roll out to each existing tenant, you can enter this command first: dsm_c -action changesetting -name settings.configuration.encryptTenantKeyForNewTenants -value true dsm_c -action masterkey -subaction encryptpii -tenantid [all | TENANTNUM] — Use each tenant's key to encrypt their administrators' and contacts' personal data in the database. dsm_c -action masterkey -subaction encryptdsmprivatekey -tenantid [all | TENANTNUM] — Use the master key to encrypt the private key used for activation and other agent-manager communications via SSL/TLS.
removecert	Remove a trusted certificate.	dsm_c -action removecert -id ID
removeregion	Remove a private cloud provider region.	dsm_c -action removeregion -region REGION
resetcounters	Reset counter tables to an empty state.	dsm_c -action resetcounters [-tenantname TENANTNAME | -tenantid TENANTID]
script	Perform batch processing of dsm_c commands in a script file.	dsm_c -action script -scriptfile FILEPATH [-tenantname TENANTNAME | -tenantid TENANTID]
setports	Set Deep Security Manager port(s).	dsm_c -action setports [-managerPort port] [-heartbeatPort port]
trustdirectorycert	Trust the certificate of a directory.	dsm_c -action trustdirectorycert -directoryaddress DIRECTORYADDRESS -directoryport DIRECTORYPORT [-username USERNAME] [-password PASSWORD] [-tenantname TENANTNAME | -tenantid TENANTID]
unlockout	Unlock a user account.	dsm_c -action unlockout -username USERNAME [-newpassword NEWPASSWORD] [-disablemfa][-tenantname TENANTNAME | -tenantid TENANTID]
upgradetasks	Runs the upgrade task actions which may be required as part of an in-service upgrade.	dsm_c -action upgradetasks [-listtasksets] [-listtasks -taskset UPGRADE_TASK_SET [-force]] [-tenantlist] [-tenantsummary] [-run -taskset UPGRADE_TASK_SET [-force] [-filter REGULAR_EXPRESSION]] [-showrollbackinfo -task TASKNAME] [-purgehistory [-task TASKNAME]] [-showhistory [-task TASKNAME]] [-tenantname TENANTNAME | -tenantid TENANTID] [-listtasksets]: List sets of tasks for the system as a whole or the tenant specified by -tenantname. [-listtasks -taskset UPGRADE_TASK_SET [-force]]: List the modifications to run. Include -force to list all tasks. [-tenantlist]: Shows the version of outstanding upgrade actions for the specified tenant. [-tenantsummary]: Shows a summary of the tenants that are not up to date. [-run -taskset UPGRADE_TASK_SET [-force] [-filter REGX]]: Run the upgrade actions for each tenant. Include -force to run all tasks even if they have already been done. Include -filter to limit the actions to a regular expression. [-showrollbackinfo -task TASKNAME]: Shows rollback information for the specified task. One tenant or all tenants can be shown. [-purgehistory [-task TASKNAME]]: Purge the history for the tenant specified and the task specified. If no tenant or task is specified, all items are matched. [-showhistory [-task TASKNAME]]: Show the history for the tenant specified and the task specified. If no tenant or task specified, all items are matched.
versionget	View information about the current software version, the database schema version, or both.	dsm_c -action versionget [-software] [-dbschema]
viewsetting	View a setting value.	dsm_c -action viewsetting -name NAME [-computerid COMPUTERID] [-computername COMPUTERNAME] [-policyid POLICYID] [-policyname POLICYNAME] [-tenantname TENANTNAME | -tenantid TENANTID]

Return codes

The dsm_c command returns an integer value that indicates whether the command executed successfully. The following values can be returned:

• 0: Successful execution.
• -1: Failure of an unknown nature, such as corrupt software installation.
• 1: Failure during execution, such as the database is not currently accessible.
• 2: Invalid arguments were provided.