URL format for download of the agent

The Deep Security Agent software package can be downloaded from Deep Security Manager, using a well-defined URL format.

In most cases, use of the standard deployment scripts (which, by the way, also use this same URL format described in this section to download the agent software) is the quickest way to get started and will meet the majority of your deployment requirements.

Use of this URL format directly is useful if you require further customization for the download and install of agents. For example, in some cases it may be necessary to have the deployment scripts that run on each server point to a local storage location (for example, AWS S3) rather than have each server reach out to the manager to download software. You can use this URL format to build your own automation to periodically download new agent versions to your local storage location, and then point the agent deployment scripts that run on each server to your local storage location to meet this objective.

Topics:

Agent download URL format

The URL format used to download the agent is:

https://<dsm fqdn>/software/agent/<platform>/<arch>/<agent version>/<filename>

All the parameters that comprise the URL format are described below.

<dsm fqdn> parameter

The <dsm fqdn> parameter is the fully-qualified domain name of the manager, including the listening port number.

Example: 

example.com:4119

<filename> parameter

The <filename> parameter is the file name of the agent installer file. The file name is dependent on the installation process used by each platform:

Platform <filename>

Linux

Red Hat Enterprise Linux, CentOS, Oracle, CloudLinux, Amazon Linux, SUSE

agent.rpm

Linux

Debian, Ubuntu

agent.deb
Windows agent.msi
AIX agent.bff.gz
Solaris 11+ agent.p5p.gz
Solaris 10 or earlier agent.pkg.gz

The manager does not validate the file name itself; however when a file name is specified, the extension must be one of .rpm, .msi, .deb, .gz.  If any other file name is specified, the file name returned by the manager will always be one of the names provided in the table above.

<agent version> parameter

The <agent version> parameter is optional.

When this parameter is not specified, the latest agent in the manager's local inventory for the target platform is returned.

When this parameter is specified, this represents the agent version string.  For example "12.0.0.123".

Should I include the <agent version> explicitly in my scripts?

If your intent is to only use a specific version of the agent in a controlled environment, then explicitly adding the agent version to the URL will accomplish this goal.

When deploying agents at scale, it should be noted that adding the agent version in the URL (which hardcodes this agent version into every script you distribute) can create challenges for security operations teams that will be distributing scripts to many applications teams.

Consider the process that will be needed when the time arrives to use a newer version of the agent.  If the <agent version> is hardcoded in each script you distribute, this will require that each of these scripts requires an update to start using the new agent version.  If you have many internal application teams, the process to request changes to each one of these scripts in use can be significant.

Deep Security provides two options to deal with this challenge:

  • Simply use scripts that omit the <agent version> component from the path.

    If using the latest agent in the manager's local inventory meets your requirements, this is the most straightforward option to use.

  • Use agent version control

    Agent version control provides the ability for the Deep Security administrator to select on a per-platform basis exactly what agent version is returned from the manager.  More detail on agent version control and how to leverage this feature from your scripts can be found at Using agent version control to define which agent version is returned.

<platform>, <arch>, and <filename> parameters

The <platform>, <arch>, and <filename> parameters should be replaced with the strings listed in the table below.

<platform> and <arch> are case-sensitive.

Platform Distribution <platform> <arch> <filename> Example
Linux Amazon 1 amzn1 x86_64 agent.rpm /software/agent/amzn1/x86_64/agent.rpm
  Amazon 2 amzn2 x86_64 agent.rpm /software/agent/amzn2/x86_64/agent.rpm
  CloudLinux 6 CloudLinux_6 x86_64 agent.rpm /software/agent/CloudLinux_6/x86_64/agent.rpm
  CloudLinux 7 CloudLinux_7 x86_64 agent.rpm /software/agent/CloudLinux_7/x86_64/agent.rpm
  CloudLinux 8 CloudLinux_8 x86_64 agent.rpm /software/agent/CloudLinux_8/x86_64/agent.rpm
  Debian 7 Debian_7 x86_64 agent.deb /software/agent/Debian_7/x86_64/agent.deb
  Debian 8 Debian_8 x86_64 agent.deb /software/agent/Debian_8/x86_64/agent.deb
  Debian 9 Debian_9 x86_64 agent.deb /software/agent/Debian_9/x86_64/agent.deb
  Oracle Linux 6 Oracle_OL6 x86_64 agent.rpm /software/agent/Oracle_OL6/x86_64/agent.rpm
  Oracle Linux 6 Oracle_OL6 i386 agent.rpm /software/agent/Oracle_OL6/i386/agent.rpm
  Oracle Linux 7 Oracle_OL7 x86_64 agent.rpm /software/agent/Oracle_OL7/x86_64/agent.rpm
  RedHat 6 RedHat_EL6 x86_64 agent.rpm /software/agent/RedHat_EL6/x86_64/agent.rpm
  RedHat 6 RedHat_EL6 i386 agent.rpm /software/agent/RedHat_EL6/i386/agent.rpm
  RedHat 7 RedHat_EL7 x86_64 agent.rpm /software/agent/RedHat_EL7/x86_64/agent.rpm
  RedHat 8 RedHat_EL8 x86_64 agent.rpm /software/agent/RedHat_EL8/x86_64/agent.rpm
  SuSE 11 SuSE_11 x86_64 agent.rpm /software/agent/SuSE_11/x86_64/agent.rpm
  SuSE 11 SuSE_11 i386 agent.rpm /software/agent/SuSE_11/i386/agent.rpm
  SuSE 12 SuSE_12 x86_64 agent.rpm /software/agent/SuSE_12/x86_64/agent.rpm
  SuSE 15 SuSE_15 x86_64 agent.rpm /software/agent/SuSE_15/x86_64/agent.rpm
  Ubuntu 16.04 Ubuntu_16.04 x86_64 agent.deb /software/agent/Ubuntu_16.04/x86_64/agent.deb
  Ubuntu 18.04 Ubuntu_18.04 x86_64 agent.deb /software/agent/Ubuntu_18.04/x86_64/agent.deb
Windows   Windows x86_64 agent.msi /software/agent/Windows/x86_64/agent.msi
    Windows i386 agent.msi /software/agent/Windows/i386/agent.msi
Unix Solaris 10 Updates 4-6 Solaris_5.10_U5 x86_64 agent.pkg.gz /software/agent/Solaris_5.10_U5/x86_64/agent.pkg.gz
    Solaris_5.10_U5 sparc agent.pkg.gz /software/agent/Solaris_5.10_U5/sparc/agent.pkg.gz
  Solaris 10 Updates 7-11 Solaris_5.10_U7 x86_64 agent.pkg.gz /software/agent/Solaris_5.10_U7/x86_64/agent.pkg.gz
    Solaris_5.10_U7 sparc agent.pkg.gz /software/agent/Solaris_5.10_U7/sparc/agent.pkg.gz
  Solaris 11 Updates 1-3 Solaris_5.11 x86_64 agent.p5p.gz /software/agent/Solaris_5.11/x86_64/agent.p5p.gz
    Solaris_5.11 sparc agent.p5p.gz /software/agent/Solaris_5.11/sparc/agent.p5p.gz
  Solaris 11 Update 4 Solaris_5.11_U4 x86_64 agent.p5p.gz /software/agent/Solaris_5.11_U4/x86_64/agent.p5p.gz
    Solaris_5.11_U4 sparc agent.p5p.gz /software/agent/Solaris_5.11_U4/sparc/agent.p5p.gz
  AIX 5.3 (Deep Security Agent 9.0) AIX_5.3 powerpc agent.bff.gz /software/agent/AIX_5.3/powerpc/agent.bff.gz
  AIX 6.1 (Deep Security Agent 9.0) AIX_6.1 powerpc agent.bff.gz /software/agent/AIX_6.1/powerpc/agent.bff.gz
  AIX 7.1, 7.2 (Deep Security Agent 9.0) AIX_7.1 powerpc agent.bff.gz /software/agent/AIX_7.1/powerpc/agent.bff.gz
  AIX 6.1, 7.1, 7.2 (Deep Security Agent 12 and up) AIX powerpc agent.bff.gz /software/agent/AIX/powerpc/agent.bff.gz

Examples

Without <agent version>:

  • https://example.com:4119/software/agent/RedHat_EL7/x86_64/agent.rpm
  • https://example.com:4119/software/agent/Windows/x86_64/agent.msi

With <agent version>:

  • https://example.com:4119/software/agent/RedHat_EL7/x86_64/12.0.0.481/agent.rpm
  • https://example.com:4119/software/agent/Windows/x86_64/12.0.0.481/agent.msi

Exceptions for backwards compatibility

If no <filename> is provided after [...]/<platform>/<arch>/, the manager will return the agent download for that platform as described in the previous table.

If the path ends at [...]<platform>/<arch> (because both <agent version> and <filename> were not specified), the manager will return the agent download for that platform as described in the table above.

Examples:

  • https://example.come:4119/software/agent/RedHat_EL7/x86_64/
  • https://example.come:4119/software/agent/Windows/x86_64

Using agent version control to define which agent version is returned

The agent version control feature provides the ability to control what agents are returned when any URL request is made to Deep Security to download the agent.

To enable agent version control, send the following HTTP header with your URL request:

Agent-Version-Control: on

It should be noted that there are specific query parameters that are also required on each platform to use agent version control.  They are:

Platform Required query parameters Example
Windows tenantID, windowsVersion, windowsProductType /software/agent/Windows/x86_64/agent.msi?tenantID=123&windowsVersion=10.0.17134&windowsProductType=3
Linux tenantID /software/agent/RedHat_EL7/x86_64/agent.rpm?tenantID=123
Solaris tenantID /software/agent/Solaris_5.11_U4/x86_64/agent.p5p.gz?tenantID=123
AIX tenantID, aixVersion, aixRelease /software/agent/AIX/powerpc/agent.bff.gz?tenantID=123&aixVersion=7&aixRelease=1

The parameters in the table above are automatically generated by the deployment scripts.

Examples

For examples, refer to the sample deployment script generated from the manager.  By default the deployment scripts generated by the manager use agent version control and demonstrate how to acquire these parameters for each platform.

Interactions between the <agent version> parameter and agent version control

Given the intent of the agent version control feature is to provide the Deep Security administrator control over which agent version is returned, there is a natural conflict with a URL request that also includes the <agent version> parameter.

For this reason you should not specify the <agent version> as part of your request when sending the Agent-Version-Control: on HTTP header.

If we see both the Agent-Version-Control: on HTTP header and the <agent version> parameter in the request, the version of the agent returned will be determined by the value taken from the agent version control configuration. (We will ignore the <agent version> in the URL.)