Configure Agent for Windows (Advanced Settings)

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 app servers, 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 DEVICE_TYPE=Desktop AGGREGATION_SERVERS=hostname ACCOUNT=abc123
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

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). For example:
DEVICE_TYPE=Server

Learn more

APP_RESPONSE_URL
Enter the URL of the AppResponse host server to connect to their console:
APP_RESPONSE_URL=http://127.0.0.1
This is an example of IP, use the correct host IP address.
AGGREGATION_SERVERS

In Aternity SaaS deployments, this address is already set to the Aternity SaaS server.

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

Learn more.

ACCOUNT

(Aternity SaaS only) This value is the account ID for your company, which you received from Customer Services.

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.

TARGETDIR

(Optional, advanced) You can customize the directory pathname where you want to store the files of the Agent, by adding TARGETDIR=e:\anydir\anyotherdir.

ACTION_EXECUTION_POLICY
Install the Agent as Trusted to run scripts in a secure network.
ACTION_EXECUTION_POLICY="Trusted"
POWER_SHELL_MONITOR_POLICY

Run only secured Powershell scripts (POWER_SHELL_MONITOR_POLICY="Trusted").

It is possible to change the default parameter of the POWER_SHELL_MONITOR_POLICY in the Agent's batch file only during its installation. There are three possible options to alter:
  • Trusted - The default policy that automatically applies during Aternity Agent mass deployment.

  • Unrestricted - Aternity Agent runs any script, both signed and not signed.

  • Blocked - Aternity Agent blocks any script, either signed or not.

Changing these options is supported only for mass installation batch file by entering one of the following parameters: POWER_SHELL_MONITOR_POLICY=Unrestricted or POWER_SHELL_MONITOR_POLICY=Blocked

If the certificate you use for signing is not listed in the Trusted Publishers store, you have an option to explicitly specify in the Agent's batch file what certificate the Agent should trust. You can define up to two certificates during Agent's mass deployment: TRUSTED_CERTIFICATE_SUBJECT1= and TRUSTED_CERTIFICATE_SUBJECT2=. Enter the value to specify the subject of the certificate.

Procedure

  1. Step 1 Choose the Agent features to deploy with the ADDLOCAL parameter.

    Combine several features by listing them separated by a comma (no space). For example:

    ADDLOCAL=Agent,Recorder
    Field Description
    ADDLOCAL=Agent

    Sets up and activates the Agent.

    ADDLOCAL=Recorder

    (Optional) Insert this parameter to add a (disabled) Aternity Recorder into your Agent deployment, if you intend to use this computer when creating custom activities.

    Note

    The Recorder is a dormant component of the Agent. The device's end user must manually enable it. Enable it by updating the parameters in the Agent setup file (learn more)

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

    (Windows only) Displays the hostname of the monitored device. View it in the Windows Control Panel > System > Computer Name.

    (Mobile) Displays the Device Name field. You can customize the hostname of iOS or Android devices running your enterprise's app, so device names appear 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 only) 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 Name

    (Windows only) Displays the full name of the person accessing the device as defined in the corporate LDAP (not the username).

    Username

    Displays the username signed in to the device's operating system.

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

    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.

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

    For Aternity SaaS deployments, the Aggregation Server address is set to the Aternity SaaS server.

    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

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