Configure Advanced Settings for the Agent

The command line Agent setup is a standard .msi file (Aternity_Agent_xx.msi), and an accompanying batch file (Aternity_Agent_xx_Install.bat) which contains the default parameters to run the setup.

The default settings in the batch file fit most enterprises. However, for VDIs or virtual applications, or for a dedicated proxy server just for Agent connections, configure the parameters accordingly.

Configure the command line setup of the Agent with a batch file

The batch file typically contains only a single command to launch the .msi file with its parameters. For example:

msiexec /I Aternity_Agent_x.msi /QN /L*V+ logfilename.log ADDLOCAL=Agent,Recorder DEVICE_TYPE=Desktop AGGREGATION_SERVERS=hostname
Field Description

/I

/QN

/LV

Do NOT change or remove these parameters. They are standard Microsoft .msi parameters required for a successful setup and log files.

ADDLOCAL

Enter the list of Agent features to deploy on this device. For example, by default it adds:

ADDLOCAL=Agent,Recorder,ProductDiagnostics

Learn more.

DEVICE_TYPE

Enter this parameter to specify if this device is a local desktop setup, or a VDI (virtual desktop infrastructure) like VMWare vSphere, or a virtual application server (like Citrix XenApp).

Learn more

AGGREGATION_SERVERS

For Aternity on-premise deployments, set this parameter to the address of your Aternity Aggregation Server. Use https for secure connections (learn more).

To add a redundant (set of) Aggregation Servers to switch to another if one fails (failover), enter the redundant server addresses after this one (learn more).

To communicate via a proxy server, add its address as part of the Aggregation Server address.

Learn more.

ACCOUNT

Remove this parameter for Aternity on-premise deployments.

(Service Providers only) If you are a service provider with a multi-tenant deployment, use this parameter to add the customer's account key. To find the key for each tenant, select the Gear Icon > Accounts > Account Key

ENFORCE_PRIVACY

(Optional) Enter this parameter to configure the Agent to report data anonymously, by encrypting personally identifiable information (PII).

Learn more.

CHROME_WEB_STORE_URL

(Optional) Enter the address of an alternative Chrome store to download the Aternity Extension for Chrome, if your enterprise blocks access to the Google Chrome Store.

Learn more.

ENFORCE_PAC

(Optional, advanced) Add this parameter to force the setup to look for a PAC or JS file which routes to different proxy servers.

Learn more.

Procedure

  1. Step 1 Set the address of the Aternity Aggregation Server using the AGGREGATION_SERVERS parameter as follows:
    AGGREGATION_SERVERS=http://AggSrv:Agg_port1
    Important

    If your sizing requires that you deploy more than one dedicated Aternity Aggregation Server, you must deploy a third party load balancer (LB). Then configure the Aternity Agent of all devices to point to the LB's virtual IP address (learn more). Configure the LB with persistent (sticky) sessions to ensure the Agent maintains its connection with the same server. Aternity also supports sticky sessions also when the LB implements stickiness via cookies.

    You can only enter one address for the AGGREGATION_SERVERS parameter.

    To secure the connection between the Agent and your Aggregation Server, specify https:// in the address in the AGGREGATION_SERVERS parameter.

    AGGREGATION_SERVERS=https://AggSrv:Agg_port1

    You must also secure the Aggregation Server (or its load balancer) by configuring it to work with HTTPS.

    Secure the connection to an Aggregation Server with HTTPS
  2. Step 2 Choose the Agent features to deploy with the ADDLOCAL parameter.

    Combine several features by listing them separated by a comma (no space). For example, the default parameters are:

    ADDLOCAL=Agent,Recorder,ProductDiagnostics
    Field Description
    ADDLOCAL=Agent

    Installs and activates the Agent.

    ADDLOCAL=Recorder

    Adds a (disabled) Aternity Recorder to help create custom activities.

    Note

    The Recorder is a dormant component of the Agent. The device's end user must manually enable it.

    ADDLOCAL=ProductDiagnostics

    Allows this computer to automatically send diagnostic information about the Agent to Aternity, to help improve the product and support.

  3. Step 3 (Optional) To configure the Agent on a device to report data anonymously, by encrypting the details (attributes) which identify a user, use the ENFORCE_PRIVACY parameter during setup as follows:
    ENFORCE_PRIVACY=true

    The default value is false, so if your batch file does not contain this parameter, it does not encrypt any user identifying fields.

    For example, you can view the encrypted fields of a device whose Agent enabled ENFORCE_PRIVACY by viewing its Device Details dashboard.

    Example of encrypted fields when privacy is enabled on the device's Agent

    The encrypted attributes are:

    Field Description
    Active IP Address

    (Windows only) Displays one of the IP addresses on this device (including IP v6 if the device runs Agent 10 or later) whose network adapter is active, operational and non-virtual.

    The actual IP used to connect to Aternity is the IP Address field. If the device has more than one operational network adapter, the Active IP Address field may have a different value.

    AD Title

    (For all devices except mobile and Macs) Displays the job title of the current user logged in to this device. In Windows, this is the same as the AD Title.

    Client Device Name

    (For virtual deployments only) Displays the hostname of a device which is connecting to a VDI or virtual application server.

    Email Address

    (Windows only) Displays the email address associated with the current logged in user.

    Hostname

    Displays the hostname of the monitored device. View it in the Windows Control Panel > System > Computer Name, or on Apple Macs in System Preferences > Sharing > Computer Name.

    (Mobile) Displays the Device Name field. You can customize the name of personal mobile devices running your enterprise's app, so the device's name appears in the dashboards with a consistent naming policy. For example, you can dynamically assign the device name according to the enterprise username of the app.

    IP Address

    (Windows, Mac) Displays the device's internal IP address (including IP v6 if the device runs Agent 10 or later) which it uses to connect to Aternity.

    (Mobile devices) Displays the IP of the WiFi connection if the device is reporting data via WiFi.

    User Full Names

    Displays the full name of the user as defined in the corporate LDAP.

    Username

    Displays the username of the person accessing each device.

    A Power User of Aternity can configure this list by selecting the Gear Icon > Settings > Advanced Settings > privacy > privateStaticAtttributeList.

  4. Step 4 To implement failover between several Aggregation Servers, edit the AGGREGATION_SERVERS line to add a semicolon (;) and then the address of the next server.
    AGGREGATION_SERVERS=https://AggSrv1:Agg_port1;https://AggSrv2:Agg_port2;https://AggSrv3:Agg_port3

    This kind of disaster recovery (DR) works equally well when you have one Aggregation Server, or if you deployed several Aggregation Servers behind a load balancer.

    Learn more .

    Agent connects to a different Aggregation Server if one connection fails
  5. Step 5 To add an Agent on a VDI (virtual desktop infrastructure like VMWare vSphere) or a virtual application server (like Citrix XenApp), add the DEVICE_TYPE parameter.
    Types of Agent deployments
    Note

    By default, a virtual session only reports data to Aternity while a user is logged in to Windows, and stops when a user logs out. Aternity does not report boot times for virtual sessions.

    To report data even when a user is not logged in to Windows, select the Gear Icon > Settings > Advanced Settings > agent > configuration > overrideConfigurationParam > Citrix and VDI > SendMeasurementsOnUserNotLoggedOn > value and set it to True.

    Field Description
    DEVICE_TYPE=desktop

    Enter desktop to add the Agent locally to a physical Windows computer (default).

    DEVICE_TYPE=virtualdesktop

    Enter virtualdesktop for VDI deployments, to add the Agent inside the virtual machine disk image, so that each new virtual desktop includes a running Agent.

    DEVICE_TYPE=server

    Enter server to add the Agent on a virtual server which hosts remote sessions, like Citrix XenApp or Microsoft RDC.

  6. Step 6 If you block access to the Google Chrome Store, you can set the Agent to download the Aternity Extension for Chrome from Aternity's secure proprietary store.

    Add the following parameter:

    CHROME_WEB_STORE_URL=https://chromestore.aternity.com/update/crx
  7. Step 7 Proxy server settings are nearly always automatic, but there are rare cases when you need to configure them manually.

    If you configured the system user in Windows to use a proxy server, or a PAC file for conditional proxy routing, the Agent automatically connects via this proxy, with zero configuration.

    Connecting to an Aggregation Server via a dedicated proxy server

    However, if you want Agents to connect to the Aggregation Server using special proxy server settings which are different from the system user in Windows, set the AGGREGATION_SERVERS parameter:

    Field Description

    No proxy password, no encryption

    AGGREGATION_SERVERS=http://AggSrv:Agg_port,:@http://ProxySrv:Proxy_port

    For example:

    AGGREGATION_SERVERS=HTTP://1.2.3.4,:@http://11.12.13.14:3128

    No proxy password, with HTTPS encryption

    This format also supports secured HTTPS communication to the proxy server.

    AGGREGATION_SERVERS=https://AggSrv:Agg_port,:@https://ProxySrv:Proxy_port

    For example:

    AGGREGATION_SERVERS=https://1.2.3.4,:@https://11.12.13.14:3128

    With proxy password, with HTTPS encryption

    If your proxy requires credentials, enter the username before the colon (:), and the password before the at-sign (@).

    AGGREGATION_SERVERS=https://AggSrv:Agg_port,pxyuser:pswd@https://ProxySrv:Proxy_port

    For example:

    AGGREGATION_SERVERS=https://1.2.3.4,pxyuser:pswd@https://11.12.13.14:3128

    With PAC or JS file, no proxy password, with HTTPS encryption

    The system also supports a PAC or JS file for conditional proxy routing, either with HTTP or HTTPS:

    Using a PAC file to route to different proxy servers

    For PAC files, use the following syntax (works with HTTP or HTTPS):

    AGGREGATION_SERVERS=https://AggSrv:Agg_port,:@https://ProxySrv:Proxy_port/file.pac

    In the following example, the PAC file does not require a username, but the proxy server declared in it does require a username (proxyuser) and password.

    AGGREGATION_SERVERS=https://1.2.3.4,:@https://11.12.13.14:3128/file.pac

    With PAC or JS file, with proxy password, with HTTPS encryption

    To specify a secured HTTPS connection to a PAC file which points to a secured proxy server, where that proxy server needs a password, use:

    AGGREGATION_SERVERS=http://AggSrv:Agg_port,proxyuser:pswd@http://ProxySrv:Proxy_port/file.pac

    In the following example, the PAC file does not require a username, but the proxy server declared in it does require a username (proxyuser) and password.

    AGGREGATION_SERVERS=https://1.2.3.4,proxyuser:pswd@https://11.12.13.14:3128/file.pac
    Tip

    To ensure the setup uses your PAC file (for example, if the file does not have a .js or .pac suffix), add ENFORCE_PAC=True. If it cannot find the PAC, it tries the system's proxy settings, and if that fails, it tries to access the server directly.

  8. Step 8 To report more detailed information on processes launched from the command line, select the Gear Icon > Settings > Advanced Settings > agent > configuration > templates > version_x_x > handler_configuration_info.

    Set the value of ReportProcessCommandLine to the name of the command line shell you are using, like svchost.