Deep Security Manager 10 has reached end of support. Use the version selector (above) to see more recent versions of the Help Center.
Command-line utilities
You can command Deep Security Agents and the Deep Security Manager to perform a number of actions from the local command line interface (CLI).
For examples of basic command-line task instructions, see Command-line basics for agent tasks.
In this topic:
Deep Security Agent
dsa_control examples
You can use dsa_control -m to initiate a manual anti-malware scan. The following commands will force an immediate heartbeat and let the Manager know to initiate the scan.
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 that you might have configured in Deep Security Manager previously. 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 agent configuration.
- -R <str>, --restore=<str> Restore quarantined file. (Deep Security)
- -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. This is a Windows-only feature.
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.
-
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.
To allow Agent-Initiated Activation over a private network using a proxy server:
- In Deep Security Manager, go Administration > System Settings > Agents.
- 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".
- 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 with either the activation or heartbeat exclusively.
Key | Description | Examples | Can be performed during Activation | Can be performed after activation during Heartbeat | Value Format | Notes |
AntiMalwareCancelManualScan |
Cancels a manual or scheduled Anti-Malware scan currently occurring on the computer. For more information, see Malware Scan Configurations. |
"AntiMalwareCancelManualScan:true" | no | yes | Boolean |
|
AntiMalwareManualScan |
Initiates a manual or scheduled Anti-Malware scan on the computer. For more information, see Malware Scan Configurations. |
"AntiMalwareManualScan:true" | no | yes | Boolean |
|
description | Sets description value. | "description:Extra information about the host" | yes | yes | string | Maximum length 2000 characters. |
displayname | Sets displayname value. (Shown in parentheses next to the hostname.) | "displayname:the_name" | yes | yes | string | Maximum length 2000 characters. |
externalid | Sets the externalid value | "externalid:123" | yes | yes | integer | This value can used to uniquely identify an Agent. The value can be accessed using the SOAP Web Service API. |
group | Sets the computers page Group the computer belongs in. | "group:Zone A web servers" | yes | yes | string | 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. |
groupid |
|
"groupid:33" | yes | yes | integer |
|
hostname |
|
"hostname:www1" | yes | no | 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. |
IntegrityScan | Initiates an integrity scan on the computer. | "IntegrityScan:true" | no | yes | Boolean |
|
policy |
|
"policy:Policy Name"
|
yes | yes | 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. |
policyid |
|
"policyid:12" | yes | yes | integer |
|
relaygroup | Links the computer to a specific relay group. | "relaygroup:Custom Relay Group"
|
yes | yes | string | 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 |
|
"relaygroupid:123" | yes | yes | integer |
|
relayid |
|
"relayid:123" | yes | yes | integer |
|
tenantID and token |
|
"tenantID:12651ADC-D4D5"
and "token:8601626D-56EE" |
yes | yes | 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.
|
RecommendationScan | Initiate a recommendation scan on the computer. | "RecommendationScan:true" | no | yes | Boolean |
|
UpdateComponent | Instructs the Manager to perform a security update. | "UpdateComponent:true" | no | yes | Boolean |
|
RebuildBaseline | Rebuilds the integrity monitoring baseline on the computer. | "RebuildBaseline:true" | no | yes | Boolean |
|
UpdateConfiguration | Instructs the Deep Security Manager to perform a "Send Policy" operation. | "UpdateConfiguration:true" | no | yes | Boolean |
|
dsa_query
The dsa_query command provides agent information.
Usage
dsa_query [-c <str>] [-p <str>] [-r <str]
- -p,--passwd <string>: Authentication password used with the optional agent self-protection feature. Required if you specified a password when enabling self-protection.
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 and integrity monitoring scans in progress, and other miscellaneous information
- "GetComponentInfo": query version information of anti-malware patterns and engines
- -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*"
Deep Security Manager
Applies to on-premise Deep Security software installations only
dsm_c
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 your tenant ID.Action Name | Description | Usage |
---|---|---|
addcert | Add a trusted certificate | dsm_c -action addcert -purpose PURPOSE -cert CERT PURPOSE refers to the type of connections the certificate will be used for. |
addregion | Add a private cloud provider region | dsm_c -action addregion -region REGION -display DISPLAY -endpoint ENDPOINT |
changesetting | Change a setting | dsm_c -action changesetting -name NAME -value VALUE [-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] |
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] PURPOSE refers to the type of connections the certificate will be used for. |
listregions | List private cloud provider regions | dsm_c -action listregions |
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 (resets back to an empty state | dsm_c -action resetcounters [-tenantname TENANTNAME | -tenantid TENANTID] |
resetevents | Reset the events tables (resets back to an empty state) | dsm_c -action resetevents -type all|am|wrs|fw|dpi|im|li[-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] |
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, for example corrupt software installation.
- 1: Failure during execution, for example the database is not accessible.
- 2: Invalid arguments were provided.