In Citrix Application Delivery Management service
In All products
Product documentation
In Citrix Application Delivery Management service
In All products
Citrix Application Delivery Management service
View PDF

Configure the ADC built-in agent to manage instances

February 17, 2021
Contributed by: 
S R R

A built-in agent is available on Citrix ADC MPX, VPX, Gateway instances running the version 12.1.48.13 and later and on Citrix ADC 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 Citrix ADM service.

Note

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

  • Citrix ADC MPX
  • Citrix ADC VPX
  • Citrix ADC SDX
  • Citrix 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.

Citrix ADM service supports management and monitoring of Citrix ADC 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.

Prerequisites

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

  • The Citrix ADC (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 Citrix ADC 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 ADC built-in agent:

  1. Sign in to Citrix Cloud.

  2. On the Application Delivery Management tile, click Manage. Then, select the region that suits your business need. For more information, see Manage Citrix ADM with Express account

    Citrix ADM Express account

  3. Click Get Started.

    Get started

  4. Select On Premises as the ADC deployment type.

    Select On-Premises ADC deployment type

  5. Select Built-in Agent.

    Important

    To use the built-in agent, your Citrix ADC instance must be on version 12.1 build 48.13 and higher.

    Select Built-in agent

    A service URL and an activation code are generated and displayed on the GUI.

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

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

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

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

      On the SDX instance

      ./mastool_int.sh <user-name> <service-url> <activation-code> -sdx

      or

      ./mastool_init.sh <device-profile-name> <service-url> <activation-code> -sdx -profile

      Note

      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 ADM 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.conf. 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 ./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>

      • In <username>, enter Citrix ADC user name.

      • In <password>, enter the ADC password.

      • In <service_url>, paste the URL that you have copied in the previous step.

      • In <activation_code>, paste the activation code that you have copied in the previous step.

      CLI initiates built-in agent

    For MPX, VPX, and Gateway instances, after the initialization using the mastools command is complete, communication between the agent and ADM service is established. The agent automatically upgrades whenever a latest software version is available. However, from versions ADC 12.1 57.18 and higher and ADC 13.0 61.48 and higher, the built-in agent communicates with ADM service without initialization and auto-upgrades itself to the latest software version regularly. For SDX instances, the agent comes with the auto-upgrade feature in all supported versions, which is 13.0 61.x and later and 12.1 58.x and later.

    Note

    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.

  8. Return to the ADM service page and click Register Instance.

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

  10. Click Done.

Complete built-in agent configuration

After successful built-in agent configuration, you can access the 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.

Note

You can also configure the built-in agent by navigating to the Networks > 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 Networks > Instances > Citrix ADC. 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 ADM 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 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
February 17, 2021
Contributed by: 
S R R
February 17, 2021
Contributed by: 
S R R

In this article

Site feedback | Privacy and legal terms | Cookie preferences | Consent settings
© 1999- Citrix Systems, Inc. All rights reserved.