Command-line basics

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.

Agent URL. Defaults to:

https://localhost:<port>/

where <port> is the manager's listening port number.

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 *

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.

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.

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

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.

Boolean.

Cancels an on-demand ("manual") scan that is currently occurring on the computer.

Boolean.

Initiates an on-demand ("manual") anti-malware scan on the computer.

String.

Sets the computer's description. Maximum length 2000 characters.

String.

Sets the display name shown in parentheses next to the hostname on Computers. Maximum length 2000 characters.

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.

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.

Integer.

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.

Boolean.

Initiates an integrity scan on the computer.

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.

Integer.

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.

Integer.

Integer.

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.

Boolean.

Initiate a recommendation scan on the computer.

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.

Boolean.

Rebuilds the integrity monitoring baseline on the computer.

Boolean.

Instructs Deep Security Manager to perform a "Send Policy" operation.

Authentication password used with the optional agent self-protection feature. Required if you specified a password when enabling self-protection.

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": to query version information of anti-malware patterns and engines
• "GetPluginVersion": to query version information of the agent and protection modules

Wild card pattern to filter result. Optional.

Example:
dsa_query -c "GetComponentInfo" -r "au" "AM*"

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.

Create a diagnostic package for the system.

If needed, you can Increase verbose diagnostic package process memory.

Generate, import, export, or use a custom master key to encrypt the:

• database password
• keystore password
• personal data

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.

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, 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.
   Using KMS is the recommended method to provision a key because it does not rely on local files. If using the local environment variable, the LOCAL_KEY_SECRET value is a salt (a unique piece of additional data provided to the key generation process) for the purpose of generating an actual master key to encrypt the database. Without the key, someone who steals the database can't decrypt it, and without the salt, the key itself can't be recalculated. This client-managed portion of the secret is offered as an option for you to customize the key generation process with additional data of your own, that you mange. But with or without the salt, the actual key is not stored in clear text. In addition, this string is stored in a file with root read-only permissions.

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.

   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'

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

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

5. 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.
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.
7. dsm_c -action masterkey -subaction isconfigured — Check to see whether the master key was created.

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.