Related pages:

By default, the AppDynamics .NET Agent stores these credentials in the config.xml file:

  • Controller account authentication
  • Proxy server authentication

For environments where security policies require you to secure credentials stored on disk, you can run an unattended installation that encrypts the credentials for the .NET Agent and writes them to the Windows Credential Manager.

Storing credentials for the .NET Agent using the Windows Credential Manager updates the config.xml file to use a schema which the AppDynamics Agent Configuration utility does not support. If you follow these instructions, then you cannot use the configuration utility to make configuration changes afterward. If you launch the configuration utility on a server where you have stored credentials in the Windows Credential Manager, the utility prompts you to delete the configurations.

Requirements

  • You must run the AppDynamics.Agent.Coordinator service as the LocalSystem account.
  • To modify credentials after installation, you need Windows Sysinternals.

Setup Configuration File

You must generate a setup configuration file to run an unattended installation. See 'Setup Configuration File Properties' on Unattended Installation for .NET.

New Installation

For new installations, use one of these methods to create the setup configuration file:

  • Run the AppDynamics Agent Configuration utility from the command line and pass the -s parameter to specify the setup configuration file destination. For this option, you must execute the .NET Agent MSI installer package on one machine before running the configuration utility.

    %ProgramFiles%\AppDynamics\AppDynamics .NET Agent\AppDynamics.Agent.Winston.exe -s <path to setup configuration file>
  • Manually create a setup configuration file from a sample template.

Remove any plain-text authentication elements from the setup configuration file. You pass the credentials as part of the unattended installation command:

  • Controller Account element:
    <account name="myaccount" password="myaccesskey"/>

  • Proxy Authentication element: If you are using a proxy authentication, use this format in the setup configuration file.

    <proxy host="myproxy.example.com" port="3128" enabled="true">   
   <authentication enabled="true" domain="mydomain.com"/>  
</proxy>

Upgrade

If your upgrade meets the criteria for an in-place upgrade on Upgrade the .NET Agent for Windows, you can encrypt the credentials for the .NET Agent and upgrade the agent at the same time.

Copy the AppDynamics Agent element from your existing config.xml file to the setup configuration file. Remove any plain-text authentication elements from the setup configuration file. You pass the credentials as part of the unattended installation command:

  • Controller Account element:
    <account name="mycontroller.saas.appdynamics.com" password="myaccesskey"/>
  • Proxy Authentication element:
    <authentication enabled="true" user_name="my_proxy_user" password="password" domain="my_windows_domain"/>

Sample Setup Configuration File

This example shows a setup configuration file that instruments: two IIS Applications, MainBC and SampleHTTPService; a Windows service, BasicWindowsService; and a standalone application, MyStandaloneApp.exe.

<winston>
  <logFileDirectory directory="C:\ProgramData\AppDynamics\DotNetAgent\Logs" />
  <logFileFolderAccessPermissions defaultAccountsEnabled="false">
    <account name="NT AUTHORITY\LOCAL SERVICE" displayName="LOCAL SERVICE" />
    <account name="NT AUTHORITY\SYSTEM" displayName="SYSTEM" />
    <account name="NT AUTHORITY\NETWORK SERVICE" displayName="NETWORK SERVICE" />
    <account name="IIS_IUSRS" displayName="ApplicationPool Identity" />
  </logFileFolderAccessPermissions>
  <appdynamics-agent xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <controller host="mycontroller.appdyanmics.com" port="443" ssl="true">
      <application name="My Business Application" />
    </controller>
    <machine-agent />

    <app-agents>
      <IIS>
        <applications>
          <application path="/" site="MainBC">
            <tier name="Main Site" />
          </application>
          <application path="/" site="SampleHTTPService">
            <tier name="HTTP Services" />
          </application>
        </applications>
      </IIS>
      <standalone-applications>
         <standalone-application name="BasicWindowsService" args="-x">
            <tier name="Windows Service Tier"/>
         </standalone-application>
         <standalone-application executable="MyStandaloneApp.exe">
            <tier name="Standalone App" />
         </standalone-application>
      </standalone-applications>
    </app-agents>

  </appdynamics-agent>
</winston>

Install from the Command Line

To install the .NET Agent from the command line:

  1. Download the .NET Agent MSI Installer Package from the AppDynamics Download Center.

  2. Launch an elevated command prompt with full administrator privileges. See Start a Command Prompt as an Administrator.

    Logging on to Windows as a member of the Administrators group does not grant sufficient permissions to run the installer.

  3. Stop IIS and, if you are upgrading, stop instrumented Windows services and Standalone applications.

  4. Run this command to install the agent with encrypted credentials. See command line options for descriptions.

    msiexec /i <path_to_MSI_installer_package> /l log.txt /q AD_SETUPFILE=<path_to_setup_configuration_file> AD_SECURED_CREDENTIALS=true AD_CONTROLLER_ACCOUNT_NAME=<SaaS or multi-tenant account> AD_CONTROLLER_ACCOUNT_ACCESS_KEY=<access key> AD_PROXY_USERNAME=<proxy user name> AD_PROXY_PASSWORD=<proxy password>

    For example:

    msiexec /i "%USERPROFILE%\Downloads\dotNetAgentSetup.msi" /l log.txt /q AD_SETUPFILE="%USERPROFILE%\Documents\SetupConfig.xml" AD_SECURED_CREDENTIALS=true AD_CONTROLLER_ACCOUNT_NAME=MyAppDynamicsAccount AD_CONTROLLER_ACCOUNT_ACCESS_KEY=changeme AD_PROXY_USERNAME=MyProxyUser AD_PROXY_PASSWORD=ProxyPass

    The MSI installer package installs the .NET Agent and encrypts the credentials and writes them to the Windows Credential Store. It adds the Controller secure attribute to the Controller element in the config.xml file and sets the value to true:

    <controller host="mycontroller.appdyanmics.com" port="443" ssl="true" secure="true">

  5. Start IIS. Restart or start instrumented Windows services and standalone applications.

Update Credentials in the Windows Credential Manager

The .NET Agent includes a Credentials Tool for you to modify credentials stored in the Windows Credential Manager. To change credentials under the Local System account, you need to use PsExec to launch the command prompt.

  1. If you have not already, download and install Windows Sysinternals.

  2. Use PsExec to launch a command prompt as the Local System account.

    psexec -i -s cmd.exe

  3. Run the Credentials Tool and pass the updated credentials.

    "%programfiles%\AppDynamics\AppDynamics .NET Agent\AppDynamics.CredentialsTool.exe" AD_CONTROLLER_ACCOUNT_NAME=<SaaS or multi-tenant account> AD_CONTROLLER_ACCOUNT_ACCESS_KEY=<access key> AD_PROXY_USERNAME=<proxy user name> AD_PROXY_PASSWORD=<proxy password>

Command Line Options

  • AD_SECURED_CREDENTIALS: Set to true to encrypt credentials to the Windows Credential Store and configure the agent to use the encrypted credentials.
  • AD_CONTROLLER_ACCOUNT_NAME: The account name for the SaaS or multi-tenant Controller.
  • AD_CONTROLLER_ACCOUNT_ACCESS_KEY: The account access key for the SaaS or multi-tenant Controller.
  • AD_PROXY_USERNAME: The proxy server user account.
  • AD_PROXY_PASSWORD: The password for the proxy server user account.