Accessing and Configuring a Citrix NetScaler Using the XML API
The NetScaler can be configured using an external Application Programming Interface (API). The API allows you to create custom client applications to configure and monitor the state of the NetScaler. It is based on
Simple Object Access Protocol (SOAP) over HTTP. You can download the API documentation from the Downloads page of the Configuration Utility.
Configuring a Citrix NetScaler for the First Time
This section describes how to configure a new NetScaler that still has the original configuration that it was shipped with. You can configure a NetScaler from the Command Line Interface or the Configuration Utility.
Configuring a Citrix NetScaler Using the Command Line Interface
To set up a NetScaler using the CLI, connect the serial cable provided to the console port located at the right front of the unit, and connect the other end to a workstation. You access the CLI using a terminal emulator.
To configure a NetScaler from the CLI
1. Connect a workstation to the NetScaler.
A. Plug the supplied serial cable into the serial port.
B. Plug the other end of the serial cable into the workstation’s serial port.
C. Run the vt100 terminal emulation program of your choice. For example, Microsoft Windows users can use HyperTerminal, which is included with all modern versions of Windows.
D. Connect to the NetScaler.
2. At the login prompt type the user name nsroot and the password nsroot, and then press ENTER.
3. Change the root password by typing the following command at the CLI, and then press ENTER.
set system user nsroot password
4. Add a MIP by typing the following command at the CLI, and then press ENTER. add ns ip IPaddress netmask -type MIP
5. Set the default gateway by typing the following command at the CLI, and then press ENTER. add route network netmask gateway
6. Set the NSIP by typing the following command at the CLI, and then press ENTER. set ns config -IPAddress IPaddress -netmask netmask
7. Review your changes to make sure that they reflect your deployment goals.
8. Save your configuration by typing the following command at the CLI, and then press ENTER.
save ns config
9. Reboot the NetScaler by typing the following command at the CLI, and then press ENTER. reboot
10. The NetScaler prompts you to confirm the reboot. Type Y and press ENTER to confirm the reboot.
11. Log back on to the workstation as nsroot, using the new administrative password.
12. Confirm connectivity to the NetScaler by typing the following command and pressing the Enter key. ping NSIP
Configuring a Citrix NetScaler Using the Configuration Utility
To set up a NetScaler using the Configuration Utility, you need an administrative workstation or laptop on the same network as the NetScaler. If you prefer to connect the workstation directly to a NetScaler, use an Ethernet crossover cable. You also need version 1.4.2_04 or higher of the Java® runtime environment.
First-time configuration includes changing the NetScaler IP address, adding a Mapped IP address, adding a default gateway, and changing the default administrator password. The Setup Wizard in the Configuration Utility can help you configure all these entities.
A NetScaler is configured with a default IP address and associated netmask for management access. The default IP is 192.168.100.1 and the netmask is 255.255.0.0. This default IP address is used whenever a user-configured value for a NetScaler's IP address (NSIP) is absent. You need to specify at least one MIP when you configure a NetScaler for the first time. The NSIP and MIP need not belong to the same subnet.
To configure a NetScaler for the first time using Configuration Utility
1. Log on to the Configuration Utility as default administrator.
3. Follow the instructions to create an initial configuration.
4. When you are finished with the Setup Wizard, the Reboot pop up menu appears.
5. Click Yes.
Setting up a High Availability Pair
You can deploy two NetScalers in a high availability configuration, where one unit actively accepts connections and manages servers while the secondary unit monitors the first. The NetScaler that is actively accepting connections and managing the servers is called a primary unit and the other one is called a secondary unit in a high availability configuration. If there is a failure in the primary unit, the secondary unit becomes the primary and begins actively accepting connections.
Each NetScaler in a high availability pair monitors the other by sending periodic messages, called heartbeat messages or health checks, to determine the health or state of the peer node. If a health check for a primary unit fails, the secondary unit retries the connection for a specific time period. (For more information about time intervals, see the “
High Availability” chapter in the Citrix NetScaler Networking Guide.) If a retry does not succeed for the specific time period, the secondary unit takes over for the primary unit in a process called failover. The following diagram shows two high availability configurations, one with NetScalers deployed in one-arm mode and the other with NetScalers deployed in two-arm mode.
In one-arm configuration, both NS1 and NS2 and servers S1, S2, and S3 are connected to the switch.
In two-arm configuration, both NS1 and NS2 are connected to two switches. The servers S1, S2, and S3 are connected to the second switch. The traffic between client and the servers passes through either NS1 or NS2.
Configuring a High Availability Pair for the First Time
To steps to set up a high availability environment, configure one NetScaler as primary and another as secondary. Perform the following tasks on each of the NetScalers:
• Add a node.
• Disable high availability monitoring for unused interfaces.
Note: Some of the command-line instructions in this section include specific identifiers and/or settings. These values are only examples, but you can use them in your initial configuration.
Adding a Node
A node is a logical representation of a peer NetScaler. It identifies the peer unit using a unique ID and its NSIP. A NetScaler uses these parameters to communicate with the peer and track its state. When you add a node, the primary and secondary units exchange heartbeat messages asynchronously. The node ID is an integer that must not be greater than 64.
To add a node using the configuration utility
1. In the navigation pane, expand System and click High Availability. The High Availability page appears in the details pane.
2. Click the Nodes tab. The Nodes page appears in the details pane.
3. Click Add. The Add Node dialog box appears.
4. In the ID text box, type an ID, for example, 3.
5. In the IP Address text box, type an IP Address, for example, 10.102.29.170.
6. Click Create. The node you created appears in the Nodes page.
To add a node using the NetScaler command line
At a NetScaler command prompt, type: add HA node 3 10.102.29.170
Disabling High Availability Monitoring for Unused Interfaces
The high availability monitor is a virtual entity that monitors an interface. You must disable the monitor for the interfaces that are not connected or being used for traffic. When the monitor is enabled on one of the interfaces and the status of this interface is DOWN, the state of the node becomes NOT UP. In a high availability configuration, a primary node entering a NOT UP state might cause a high availability failover. An interface is marked DOWN under the following
conditions:
• The interface is not connected.
• The interface is not working properly.
• The cable connecting the interface is not working properly.
To disable the high availability monitor for an unused interface using the configuration utility
1. In the navigation pane, expand Network and click Interfaces. The Interfaces page appears in the details pane.
2. Select the interface for which the monitor must be disabled.
3. Click Open. The Modify Interface dialog box appears.
4. In HA Monitoring, select the OFF option.
To disable the high availability monitor for an unused interface using the NetScaler command line
At a NetScaler command prompt, type: set interface 1/8 haMonitor OFF