Command-line basics

You can use the local command-line interface (CLI) to instruct Deep Security Agents and Deep Security Manager to perform actions. You can also use the CLI to configure some settings and display the system resource usage information.

You can automate various CLI commands using the Deep Security API (see First Steps Toward Deep Security Automation.

dsa_control

The dsa_control enables you to configure some of the Deep Security Agent settings and manually trigger such actions as activation, anti-malware scans, and baseline rebuilds.

Note that on Windows OS, when self-protection is enabled, a local user cannot uninstall, update, stop, or otherwise control Deep Security Agent. In addition, the authentication password must be supplied when running CLI commands.

dsa_control only supports English strings. Unicode is not supported.

To use dsa_control:

On Windows:

  1. Open a command prompt as administrator.
  2. Change to the Deep Security Agent's installation directory. For example:

    cd C:\Program Files\Trend Micro\Deep Security Agent\

  3. Execute the dsa_control command:

    dsa_control <option>

    where <option> is replaced with one of the options described in dsa_control options.

On Linux, AIX, and Solaris:

  • sudo /opt/ds_agent/dsa_control <option>

    where <option> is replaced with one of the options described in dsa_control options

Running multiple dsa_control commands can result in a more recent command overwriting an earlier one. If you want to run multiple commands, you should list the parameters side by side. For example, dsa_control -m "RecommendationScan:true" "UpdateComponent:true"

In general, it is recommended to use the Scheduled Tasks UI (Administration > Scheduled Tasks) for managing the Deep Security Agent tasks. For more information, see Schedule Deep Security to perform tasks.

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 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 details, 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> or --passwd=<str>

The 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 the agent's configuration. This removes the activation information from the agent and deactivates it.
-R <str>, --restore=<str> Restore a quarantined file. On Windows, you can also restore cleaned and deleted files.
-s <num>, --selfprotect=<num>

Enable the 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 on Windows. This is a Windows-only feature.

Although dsa_control lets you enable self-protection, it does not allow you to configure an associated authentication password. You need Deep Security Manager for that. See Configure self-protection through Deep Security Manager for details. Once configured, the password must 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 1 second pause between retries.
-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.

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 username 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 Deep Security Manager 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 Deep Security 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.
--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")

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:

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 (4120 by default).

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 is assigned.

A policy assigned by an event-based task overrides 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 is 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.

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.

"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 Deep Security 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, AIX, and Solaris

/opt/ds_agent/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, AIX, and Solaris

/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, AIX, and Solaris

/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 removes the activation information from the target agent and deactivates 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, AIX, and Solaris

/opt/ds_agent/dsa_control -r

dsa_query

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.

For some query-commands, authentication can be bypassed directly, in which 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
  • “GetProxyInfo”: to query proxy information of all proxy types

-r,--raw <string> Returns the same query-command information as "-c" but in raw data format for third party software interpretation.
pattern

  1. Wild card pattern to filter result. Optional.
  2. Example:
    dsa_query -c "GetComponentInfo" -r "au" "AM*"

  3. As an option to print more detailed content.
  4. Example:
    dsa_query -c GetProxyInfo details=true

 

Check CPU usage and RAM usage

Windows

Use the Task Manager or procmon.

Linux and Solaris

top

AIX

topas

Check that ds_agent processes or services are running

Windows

Use the Task Manager or procmon.

Linux, AIX, and Solaris

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.

Restart an agent on Solaris

svcadm restart ds_agent

Restart an agent on AIX

stop agent: stopsrc -s ds_agent

start agent: startsrc -s ds_agent

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.

dsa_scan allows for concurrent execution of up to ten Deep Security Agent instances.

This command ignores the agent's current scan policy on inclusions and exclusions settings (Policy > Anti-Malware > Inclusion > Manual and Policy > Anti-Malware > Exclusions > Manual).

To use dsa_scan:

On Windows:

  1. Open the Command Prompt as an Administrator.
  2. Change to the agent's installation directory:
    cd C:\Program Files\Trend Micro\Deep Security Agent\
  3. 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 "|" to separate the input file absolute paths and directories.

Example file path and directories: "c:\user data|c:\app\config.exe|c:\workapps"

Example command: dsa_scan --target "c:\user data|c:\app\config.exe|c:\workapps"

--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:

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 indicates the dsa_scan utility completed the scan tasks without detecting any issues or viruses or skipping 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.

dsm_c

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

Some commands may cause Deep Security Manager to restart. After executing the commands, ensure that Deep Security Manager has started again.

dsm_c options

dsm_c -action actionname

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

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. Note that all of the parameters shown in brackets in the following table are mandatory.

Action Name Description Usage
addazureendpoint

Add an Azure endpoint to the allowed endpoint list. This command requires an ENDPOINT parameter that must be specified in the format https://<fqdn>. The allowed endpoint list is used to validate endpoints that are specified when adding an Azure account to Deep Security Manager. If you do not specify any endpoints, then only the default built-in endpoints are allowed.

For more on adding an Azure account, see Add a Microsoft Azure account to Deep Security.

Related dsm_c options:

listazureendpoint and removeazureendpoint

dsm_c -action addazureendpoint -endpoint ENDPOINT
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.

You must back up your deployment before running the command. Do not use this command unless you understand the effects of the setting. Misconfigurations can make your service unavailable or your data unreadable. Usually, you only use this command if requested by your technical support provider telling you which setting NAME to change. Sometimes this command is required during regular use, in which case the setting is 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]
disablefipsmode Disable FIPS mode. dsm_c -action disablefipsmode
enablefipsmode Enable FIPS mode. dsm_c -action enablefipsmode
fullaccess Give an administrator the full access role. dsm_c -action fullaccess -username USERNAME [-tenantname TENANTNAME | -tenantid TENANTID]
listazureendpoint

List all allowed Azure endpoints.

Related dsm_c options:

addazureendpoint and removeazureendpoint

dsm_c -action listazureendpoint
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 uses a hard-coded seed.

If you already configured a 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. To generate a new master key, start with the commands in step 1 and 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.

  1. 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 at the system-level (not user-level), and must include, at a minimum:

    • a capital letter
    • a lower cased letter
    • a number
    • a special character
    • 8-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 is unable to decrypt required data and the service is unavailable. Symptoms can include intermittent event logs and alerts for restart failures and various other errors.

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

    You must 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 becomes unreadable. If that happens, you must reinstall Deep Security Manager, all relays, and all agents. 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'

  3. dsm_c -action masterkey -subaction encryptproperties — Use the master key to encrypt keystore and database passwords in dsm.properties and configuration.properties. You must restart Deep Security Manager for this setting to take effect.
  4. dsm_c -action masterkey -subaction encrypttenantkey -tenantid [all | TENANTNUM] — If you have a multi-tenant deployment, use the master key to encrypt existing tenant key seeds. Tenant key seeds derive subkeys that you can use in the next step. You can execute this command multiple times (this does not apply additional layers of encryption to an already encrypted seed).

    Optionally, to apply encryption only to new tenants while slowly rolling out to each existing tenant, you can start by executing the following command:

    dsm_c -action changesetting -name settings.configuration.encryptTenantKeyForNewTenants -value true

    If you only have one (primary) tenant in the environment, tenantid can be either all or 0.

  5. dsm_c -action masterkey -subaction encryptpii -tenantid [all | TENANTNUM] — If you have a multi-tenant deployment, use each tenant's key to encrypt their administrators' and contacts' personal data in the database. If you only have one (primary) tenant in the environment, tenantid can be either all or 0.
  6. 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. If you only have one (primary) tenant in the environment, tenantid can be either all or 0.
  7. dsm_c -action masterkey -subaction isconfigured — Check to see whether or not the master key was created.
removeazureendpoint

Remove an Azure endpoint from allowed endpoint list.

You can only remove endpoints added using the dsm_c -action addazureendpoint command. Default built-in endpoints cannot be removed.

Related dsm_c options:

addazureendpoint and listazureendpoint

dsm_c -action removeazureendpoint -endpoint ENDPOINT

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 or not the command has 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.