NetScaler Application Delivery Management service

Configure the ADC built-in agent to manage instances

A built-in agent is available on NetScaler MPX, VPX, Gateway instances running the version and later and on NetScaler SDX instances running version 13.0 61.x and later and 12.1 58.x and later. You can initiate this agent on the ADC instance instead of installing a dedicated agent in your data center or public cloud. The built-in agent enables communication between the instance and NetScaler ADM.


Built-in agent is available only on the following NetScaler instance types:

  • NetScaler MPX
  • NetScaler VPX
  • NetScaler SDX
  • NetScaler Gateway

The built-in agent is ideal for smaller ADC standalone or HA pair deployments. If you have multiple ADC instances, use a dedicated agent for deployments. This agent ensures you have better data aggregation capabilities than the built-in agent. For more information, see Install an agent on-premises.

NetScaler ADM supports management and monitoring of NetScaler instances using built-in agents. However, the following features are not supported in the built-in agent:

  • Application dashboard
  • Web Insight
  • SSL insight
  • HDX insight
  • Gateway insight
  • Security insight
  • Advanced analytics
  • Pooled licensing

You can transition from a built-in agent to an external agent. For more information, see Transition from a built-in agent to an external agent.


Before you configure a built-in agent on the NetScaler instance, ensure the following:

  • The NetScaler (MPX, VPX, or Gateway) instance is running on the version or later. The SDX instance is running version 13.0.61.x and later.

  • A DNS name server is added on the NetScaler instance.

    For more information, see Add a name server.

  • You have a Citrix Cloud account. For more information, see Sign up for Citrix Cloud.


For all information related to ports and other system requirements, see System Requirements.

Configure the built-in agent

Perform the following tasks to configure the ADC built-in agent:

  1. Select the Built-in agent option as instructed in Getting Started.

  2. Copy the Service URL and Activation code.

    The agent uses the service URL to locate the service and the activation code to register with the service. Skip step 7 if you are an MPX or a Gateway customer.

    Copy service URL and activation code

  3. Initiate the built-in agent using an SSH client. Gateway users must skip this step.

    1. Log on to your NetScaler instance. For more information, see Access a NetScaler.

    2. Navigate to the /var/mastools/scripts directory and type the following command:

      On the SDX instance

      ./ <user_name> <service-url> <activation-code> -sdx
      • In <user_name>, enter NetScaler user name.
      ./ <device-profile-name> <service-url> <activation-code> -sdx -profile


      NetScaler ADM discovers all VPX instances running on that SDX and you don’t have to register the VPX instances individually.

      On VPX instances not running on an SDX appliance and MPX and Gateway instances:

      If the ADC image version is lower than 13.0 61.x or 12.1 57.x, you must check the mastools version by typing the command cat /var/mastools/version.txt. If the output is 0.0-0.0, it is the first time.

      Type one of the following commands given in the following, depending on the software version.

      ADC image version Is mastools_version 0.0-0.0? Command for registration with profile Command for registration without profile
      Lower than 13.0 61.xx and 12.1 57.xx Yes ./ <device_profile_name> <service_url> "MAS;<activation_code>" -profile ./ <user_name> <pwd> <service_url> "MAS;<activation_code>"
      Lower than 13.0 61.xx and 12.1 57.xx No ./ <device_profile_name> <service_url> <activation_code> -profile ./ <user_name> <pwd> <service_url> <activation_code>
      Higher than 13.0 61.x and 12.1 57.xx Not applicable ./ <device_profile_name> <service_url> <activation_code> -profile ./ <user_name> <pwd> <service_url> <activation_code>
      • In <user_name>, enter NetScaler user name.


    In an HA pair, complete the registration on the primary node. If you run the registration on the secondary node, the following message appears:

    Please run the registration command on the primary node.

  4. Return to the NetScaler ADM page and click Register Instance.

  5. In Add Instances, view the instance where you initiated the built-in agent. Ensure the instance is in the Up status and click Next.

    Add instances

  6. Click Done.

Complete built-in agent configuration

After successful built-in agent configuration, you can access the NetScaler ADM features such as:

  • Virtual server and analytics – Apply licenses to your virtual server to manage ADC instances. For more information, see Manage subscriptions.

  • Application dashboard – To view all applications in a holistic way. For more information, see Application management and dashboard.

  • Infrastructure analytics – This feature helps you to visualize the factors that resulted or might result in an issue on the instances. For more information, see Infrastructure Analytics.


You can also configure the built-in agent by navigating to the Infrastructure > Instances > Agents > Generate Activation code page. Copy and paste the URL and activation code to an ADC instance and discover that instance.

After the built-in agent is initiated, navigate to Infrastructure > Instances > NetScaler. This page displays the details about the managed instance discovered using the built-in agent.


You can check logs if registration fails or if registration succeeds but the built-in agent does not appear in the NetScaler ADM GUI.

  • If registration fails, check logs in /var/mastools/logs/
  • If registration succeeds, but the built-in agent does not appear in the NetScaler ADM GUI, check:
    • Mastools_upgrade logs in /var/mastools/logs/mastools_upgrade.log
    • Binary logs in /var/log/mastoolsd.log.
Configure the ADC built-in agent to manage instances