NetScaler Console service

Install a NetScaler agent on Amazon Web Services (AWS)

September 4, 2024

Contributed by:

The NetScaler agent works as an intermediary between the NetScaler Console and the discovered instances in the data center or on the cloud.

Prerequisites

To launch a NetScaler agent AMI within an Amazon Web Services (AWS) Virtual Private Cloud (VPC) by using the Amazon GUI, you need:

An AWS account
An AWS virtual private cloud (VPC)
An IAM account
A Service URL and Activation code for the agent to connect to NetScaler Console service. In NetScaler Console service GUI, navigate to Infrastructure > Instances > Agents and click Generate Activation Code to generate your Service URL and Activation code.

Note

Before you provision a NetScaler agent virtual machine, Citrix recommends creating security group, virtual private network, key pair, subnet, and other entities. So, the network information is available during provisioning.

For a NetScaler agent to communicate with the NetScaler Console, and the NetScaler instances, ensure that the recommended ports are open. For complete details about the port requirements for a NetScaler agent, see Ports.

To install the NetScaler agent on AWS:

Log on to the AWS marketplace by using your AWS credentials.
In the search field, type NetScaler agent to search for the NetScaler agent AMI, and click Go.
On the search result page, click the NetScaler Console External agent AMI from the available list.
On the NetScaler Console External Agent AMI page, click Continue to Subscribe.
After the subscription is successful, click Continue to Configuration.
On the Configure this software page:
1. Select the AMI from the Fulfillment option list.
2. Select the latest NetScaler agent version from the Software Version list.
3. Select your region from the Region list.
4. Click Continue to Launch
On the Launch this software page, you have two options to register the NetScaler agent:
1. Launch from Website
2. Launch with EC2

Launch from a Website

To launch from a Website, select:

An EC2 instance type from the EC2 Instance Type list
A VPC from the VPC Settings list. Click Create a VPC in EC2 to create a VPC for your software.
A Subnet from the Subnet Settings list. Click Create a subnet in EC2 to create a subnet after you selected the VPC.
A security group for the firewall from the Security Group Settings list. Click Create New Based On Seller Settings to create a security group.
A key pair to ensure access security from the Key Pair Settings list. Click Create a key pair in EC2 to create a key pair for your software.
Click Launch
The launch from a Website is successful.

Note

The deployment process might take approximately 10–15 minutes. After the deployment is successfully completed, you can view your NetScaler agent virtual machine on your AWS account.
Once the agent is deployed, assign a name for your NetScaler agent.
Once the agent is up and running, assign an elastic IP address for your NetScaler agent.

Note

Elastic IP address enables NetScaler agent to communicate with NetScaler Console. But, an elastic IP address might not be required if you have configured NAT Gateway to route the traffic to the Internet.
Using an SSH client, log on to your NetScaler agent.
Note

You can log on to the NetScaler agent using one of the following ways:
- Use nsrecover as the user name and AWS instance ID as the password.
- Use nsroot as the user name and a valid keypair as the password.
Enter the following command to invoke the deployment screen: deployment_type.py
Enter the Service-URL and the Activation code that you had copied and saved from the Set Up Agents page in NetScaler Console as instructed in Getting Started. The agent uses the service URL to locate the service and the activation code to register with the service.

After agent registration is successful, the agent restarts to complete the installation process.

After the agent has restarted, access NetScaler Console and on the Set Up Agent page, under Discovered Agents, verify the status of the agent.

Launch with EC2

To launch with EC2, select Launch through EC2 from the Choose Action list, and then click Launch.

On the Choose an Instance Type page, select the instance, and click Next: Configure Instance Details.

On the Configure Instance Details page, specify the required parameters.

Under the Advanced Details section, you can enable a zero-touch agent by specifying authentication details or a script in the User data field.

Authentication details - Specify the Service-URL and Activation code that you copied from the Set Up Agents page in NetScaler Console as instructed in Getting Started. Enter the details in the following format.
```
 registeragent -serviceurl <apigatewayurl> -activationcode <activationcodevalue>
 
```
Agent uses this information to auto-register with the NetScaler Console during boot-up.

Script - Specify an agent auto-registration script as user data. The following is an example script:

 #!/var/python/bin/python2.7
 import os
 import requests
 import json
 import time
 import re
 import logging
 import logging.handlers
 import boto3

 '''
 Overview of the Script:
 The script helps to register a NetScaler agent with NetScaler Console. Pass it in userdata to make NetScaler agent in AWS to autoregister on bootup. The workflow is as follows
 1)  Fetch the NetScaler Console API credentials (ID and secret) from AWS secret store (NOTE: you have to assign IAM role to the NetScaler agent that will give permission to fetch secrets from AWS secret store)
 2)  Login to NetScaler Console with credentials fetched in step 1
 3)  Call NetScaler Console to fetch credentials (serviceURL and token) for agent registration
 4)  Calls registration by using the credentials fetched in step 3
 '''

 '''
 These are the placeholders which you need to replace according to your setup configurations
 aws_secret_id: Id of the AWS secret where you have stored NetScaler Console Credentials
 The secrets value should be in the following json format
 { "adm_user_id_key": "YOUR_ID", " adm_user_secret_key": "YOUR_SECRET"}
 '''

 aws_secret_id = "<AWS_secret_id>"
 adm_ip_or_hostname = "<YOUR_ADM_POP>.adm.cloud.com"

 '''
 Set up a specific logger with your desired output level and log file name
 '''
 log_file_name_local = os.path.basename(__file__)
 LOG_FILENAME = '/var/log/' + 'bootstrap' + '.log'
 LOG_MAX_BYTE = 50*1024*1024
 LOG_BACKUP_COUNT = 20

 logger = logging.getLogger(__name__)
 logger.setLevel(logging.DEBUG)
 logger_handler = logging.handlers.RotatingFileHandler(LOG_FILENAME, maxBytes=LOG_MAX_BYTE, backupCount=LOG_BACKUP_COUNT)
 logger_fortmater = logging.Formatter(fmt='%(asctime)-2s:%(funcName)30s:%(lineno)4d: [%(levelname)s] %(message)s', datefmt="%Y-%m-%d %H:%M:%S")
 logger_handler.setFormatter(logger_fortmater)
 logger.addHandler(logger_handler)

 class APIHandlerException(Exception):
     def __init__(self, error_code, message):
         self.error_code = error_code
         self.message = message

     def __str__(self):
         return self.message + ". Error code '" + str(self.error_code) + "'"

 def parse_response(response, url, print_response=True):
     if not response.ok:
         if "reboot" in url:
             logger.debug('No response for url: reboot')
             resp = {"errorcode": "500", "message": "Error while reading response."}
             return resp

         if print_response:
             logger.debug('Response text for %s is %s' % (url, response.text))

         response = json.loads(response.text)
         logger.debug("ErrorCode - " + str(response['errorcode']) + ". Message -" + str(response['message']))
         raise APIHandlerException(response['errorcode'], str(response['message']))
     elif response.text:
         if print_response:
             logger.debug('Response text for %s is %s' % (url, response.text))

         result = json.loads(response.text)
         if 'errorcode' in result and result['errorcode'] > 0:
             raise APIHandlerException(result['errorcode'], str(result['message']))
         return result

 def _request(method, url, data=None, headers=None, retry=3, print_response=True):
     try:
         response = requests.request(method, url, data=data, headers=headers)
         result = parse_response(response, url, print_response=print_response)
         return result
     except [requests.exceptions.ConnectionError, requests.exceptions.ConnectTimeout]:
         if retry > 0:
             return _request(method, url, data, headers, retry-1, print_response=print_response)
         else:
             raise APIHandlerException(503, 'ConnectionError')
     except requests.exceptions.RequestException as e:
         logger.debug(str(e))
         raise APIHandlerException(500, str(e))
     except APIHandlerException as e:
         logger.debug("URL: %s, Error: %s, Message: %s" % (url, e.error_code, e.message))
         raise e
     except Exception as e:
         raise APIHandlerException(500, str(e))

 try:
     '''Get the AWS Region'''
     client = boto3.client('s3')
     my_region = client.meta.region_name
     logger.debug("The rgion is %s" % (my_region))

     '''Creating a Boto cleint session'''
     session = boto3.session.Session()
     client = session.client(
         service_name='secretsmanager',
         region_name=my_region
     )

     '''Getting the values stored in the secret with id: <aws_secret_id>'''
     get_id_value_response = client.get_secret_value(
         SecretId = aws_secret_id
     )
     adm_user_id = json.loads(get_id_value_response["SecretString"])["adm_user_id_key"]
     adm_user_secret = json.loads(get_id_value_response["SecretString"])["adm_user_secret_key"]

 except Exception as e:
     logger.debug("Fetching of NetScaler Console credentials from AWS secret failed with error: %s" % (str(e)))
     raise e

 '''
 Initializing common NetScaler Console API handlers
 '''
 mas_common_headers = {
     'Content-Type': "application/json",
     'Accept-type': "application/json",
     'Connection': "keep-alive",
     'isCloud': "true"
 }

 '''
 API to login to the NetScaler Console and fetch the Session ID and Tenant ID
 '''
 url = "https://" + str(adm_ip_or_hostname) + "/nitro/v1/config/login"
 payload = 'object={"login":{"ID":"' + adm_user_id + '","Secret":"' + adm_user_secret + '"}}'
 try:
     response = _request("POST", url, data=payload, headers=mas_common_headers)
     sessionid = response["login"][0]["sessionid"]
     tenant_id = response["login"][0]["tenant_name"]
 except Exception as e:
     logger.debug("Login call to the NetScaler Console failed with error: %s" % (str(e)))
     raise e

 '''
 API to fetch the service URL and Token to be used for registering the agent with the NetScaler Console
 '''
 mas_common_headers['Cookie'] = 'SESSID=' + str(sessionid)
 url = "https://" + str(adm_ip_or_hostname) + "/nitro/v1/config/trust_preauthtoken/" + tenant_id +"?customer="+ tenant_id
 logger.debug("Fetching Service URL and Token.")
 try:
     response = _request("GET", url, data=None, headers=mas_common_headers)
     service_name  = response["trust_preauthtoken"][0]["service_name"]
     token = response["trust_preauthtoken"][0]["token"]
     api_gateway_url = response["trust_preauthtoken"][0]["api_gateway_url"]
 except Exception as e:
     logger.debug("Fetching of the Service URL Passed with error. %s" % (str(e)))
     raise e

 '''
 Running the register agent command using the values we retrieved earlier
 '''
 try:
     registeragent_command = "registeragent -serviceurl "+api_gateway_url+" -activationcode "+service_name+"\;"+token
     file_run_command = "/var/python/bin/python2.7 /mps/register_agent_cloud.py "+registeragent_command
     logger.debug("Executing registeragent command: %s" % (file_run_command))
     os.system(file_run_command)
 except Exception as e:
     logger.debug("Agent Registeration failed with error: %s" % (str(e)))
         raise e
 <!--NeedCopy-->

This script fetches the authentication details from the AWS secrets manager and runs the deployment.py script to register the agent with the NetScaler Console.

Configure instance details

Note

While you can auto-assign public IP address, you can also assign elastic IP address. Assigning an elastic IP address is required when NAT Gateway is not configured.

If the elastic IP address is not set in this step, you can still do it on the EC2 console. You can create a new elastic IP address and associate that with the NetScaler agent using the instance ID or ENI-ID.

Click Add Storage.

On the Add Storage page, configure the storage device settings for the instance, and click Next: Add Tags.
On the Add Tags page, define the tag for the instance, and click Next: Configure Security Group.
On the Configure Security Group page, add rules to allow specific traffic to your instance and click Review and Launch.
On the Review Instance Launch page, review the instance settings and click Launch.
In the Select an existing key pair or create a new key pair dialog box, create a key pair. You can also select from the existing key pairs.

Accept the acknowledgment and click Launch Instances.

The deployment process might take approximately 10–15 minutes. After the deployment is successfully completed, you can view your NetScaler agent virtual machine on your AWS account.

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Install a NetScaler agent on Amazon Web Services (AWS)

September 4, 2024

Contributed by:

September 4, 2024

Contributed by:

Install a NetScaler agent on Amazon Web Services (AWS)

Prerequisites

Launch from a Website

Launch with EC2

In this article