Configure the built-in agent to manage instances

Last published : Sep 26, 2026
A built-in agent is available on NetScaler MPX, VPX, Gateway instances running the version 12.1.48.13 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 NetScaler 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 Console.
Note:
The 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 NetScaler standalone or HA pair deployments. If you have multiple NetScaler 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 Console built-in agent supports instance management, monitoring, and Pooled or Flexed licensing. 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 or Flexed licensing (file-based 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.
Related information

Prerequisites

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 12.1.48.13 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.
Note:
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 NetScaler 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.
  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
      Registration with NetScaler profile Registration without NetScaler profile
      Prequisite Before registering, create a NetScaler profile. For more information, see How to create a NetScaler profile.
      Run this command ./mastools_init.sh <device-profile-name> <service-url> <activation-code> -sdx -profile ./mastools_init.sh <user_name> <service-url> <activation-code> -sdx
      User credential Enter nsroot in <device_profile_name>. Alternatively, you can use a user name that has the same access privileges as nsroot. Enter nsroot in <user_name>. Alternatively, you can use a user name that has the same access privileges as nsroot.
      Note:
      NetScaler Console 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 NetScaler 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 depending on the software version.
      Note:
      Before registering with a NetScaler profile, you must create the profile. For more information, see How to create a NetScaler profile.
      NetScaler 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 ./mastools_init.sh <device_profile_name> <service_url> "MAS;<activation_code>" -profile ./mastools_init.sh <user_name> <pwd> <service_url> "MAS;<activation_code>"
      Lower than 13.0 61.xx and 12.1 57.xx No ./mastools_init.sh <device_profile_name> <service_url> <activation_code> -profile ./mastools_init.sh <user_name> <pwd> <service_url> <activation_code>
      Higher than 13.0 61.x and 12.1 57.xx Not applicable ./mastools_init.sh <device_profile_name> <service_url> <activation_code> -profile ./mastools_init.sh <user_name> <pwd> <service_url> <activation_code>
    Note:
    • In <device_profile_name> or <user_name>, enter nsroot. Alternatively, you can use a user name that has the same access privileges as nsroot.
    • In an HA pair, complete the registration on the primary node. If you run the registration commands on the secondary node, the following message appears: Please run the registration command on the primary node.
  4. Return to the NetScaler Console page and click Register Instance.
  5. In Add Instances, view the instance where you initiated the built-in agent. Ensure that the instance is in the Up status and click Next.
  6. Click Done.
After successful built-in agent configuration, you can access the NetScaler Console features such as:
  • Virtual server and analytics – Apply licenses to your virtual server to manage NetScaler 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.

Configure license server through NetScaler® built-in agent

Note:
NetScaler built-in agent cannot be assigned the LSA role.
If you have a License Server Agent (LSA) configured in one site and want to use the same LSA from other sites, you can use a NetScaler built-in agent. While using the built-in agent, you must configure the license server using the following command on the NetScaler instance.
add licenseserver 127.0.0.1 -port 27000
In this configuration, NetScaler can reach the License Server Agent (LSA) through Console service.
Note:
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 a NetScaler 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.

Troubleshooting

You can check logs if registration fails or if registration succeeds but the built-in agent does not appear in the NetScaler Console GUI.
  • If registration fails, check logs in /var/mastools/logs/mastools_reg.py.log
  • If registration succeeds, but the built-in agent does not appear in the NetScaler Console GUI, check:
    • Mastools_upgrade logs in /var/mastools/logs/mastools_upgrade.log
    • Binary logs in /var/log/mastoolsd.log.