Citrix Access Gateway Enterprise Edition Installation and Configuration Guide

Citrix Access Gateway 8.0

 CITRIX SYSTEMS, INC., 2007. ALL RIGHTS RESERVED. NO PART OF THIS DOCUMENT MAY BE REPRODUCED OR TRANSMITTED IN ANY FORM OR BY ANY MEANS OR USED TO MAKE DERIVATIVE WORK (SUCH AS TRANSLATION, TRANSFORMATION, OR ADAPTATION) WITHOUT THE EXPRESS WRITTEN PERMISSION OF CITRIX SYSTEMS, INC. ALTHOUGH THE MATERIAL PRESENTED IN THIS DOCUMENT IS BELIEVED TO BE ACCURATE, IT IS PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE ALL RESPONSIBILITY FOR THE USE OR APPLICATION OF THE PRODUCT(S) DESCRIBED IN THIS MANUAL. CITRIX SYSTEMS, INC. OR ITS SUPPLIERS DO NOT ASSUME ANY LIABILITY THAT MAY OCCUR DUE TO THE USE OR APPLICATION OF THE PRODUCT(S) DESCRIBED IN THIS DOCUMENT. INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT NOTICE. COMPANIES, NAMES, AND DATA USED IN EXAMPLES ARE FICTITIOUS UNLESS OTHERWISE NOTED. The following information is for FCC compliance of Class A devices: This equipment has been tested and found to comply with the limits for a Class A digital device, pursuant to part 15 of the FCC rules. These limits are designed to provide reasonable protection against harmful interference when the equipment is operated in a commercial environment. This equipment generates, uses, and can radiate radio-frequency energy and, if not installed and used in accordance with the instruction manual, may cause harmful interference to radio communications. Operation of this equipment in a residential area is likely to cause harmful interference, in which case users will be required to correct the interference at their own expense. Modifying the equipment without Citrix' written authorization may result in the equipment no longer complying with FCC requirements for Class A digital devices. In that event, your right to use the equipment may be limited by FCC regulations, and you may be required to correct any interference to radio or television communications at your own expense. You can determine whether your equipment is causing interference by turning it off. If the interference stops, it was probably caused by the Access Gateway Enterprise Edition equipment. If the equipment causes interference, try to correct the interference by using one or more of the following measures: Move the Access Gateway equipment to one side or the other of your equipment. Move the Access Gateway equipment farther away from your equipment. Plug the Access Gateway equipment into an outlet on a different circuit from your equipment. (Make sure the Access Gateway equipment and your equipment are on circuits controlled by different circuit breakers or fuses.) Modifications to this product not authorized by Citrix Systems, Inc., could void the FCC approval and negate your authority to operate the product. BroadCom is a registered trademark of BroadCom Corporation. Fast Ramp, NetScaler, and NetScaler Request Switch are trademarks of Citrix Systems, Inc. Linux is a registered trademark of Linus Torvalds. Internet Explorer, Microsoft, PowerPoint, Windows and Windows product names such as Windows NT are trademarks or registered trademarks of the Microsoft Corporation. NetScape is a registered trademark of Netscape Communications Corporation. Red Hat is a trademark of Red Hat, Inc. Sun and Sun Microsystems are registered trademarks of Sun Microsystems, Inc. Other brand and product names may be registered trademarks or trademarks of their respective holders. Software covered by the following third party copyrights may be included with this product and will also be subject to the software license agreement: Copyright 1998 Carnegie Mellon University. All rights reserved. Copyright David L. Mills 1993, 1994. Copyright 1992, 1993, 1994, 1997 Henry Spencer. Copyright Jean-loup Gailly and Mark Adler. Copyright 1999, 2000 by Jef Poskanzer. All rights reserved. Copyright Markus Friedl, Theo de Raadt, Niels Provos, Dug Song, Aaron Campbell, Damien Miller, Kevin Steves. All rights reserved. Copyright 1982, 1985, 1986, 1988-1991, 1993 Regents of the University of California. All rights reserved. Copyright 1995 Tatu Ylonen, Espoo, Finland. All rights reserved. Copyright UNIX System Laboratories, Inc. Copyright 2001 Mark R V Murray. Copyright 1995-1998 Eric Young. Copyright 1995,1996,1997,1998. Lars Fenneberg. Copyright 1992. Livingston Enterprises, Inc. Copyright 1992, 1993, 1994, 1995. The Regents of the University of Michigan and Merit Network, Inc. Copyright 1991-2, RSA Data Security, Inc. Created 1991. Copyright 1998 Juniper Networks, Inc. All rights reserved. Copyright 2001, 2002 Networks Associates Technology, Inc. All rights reserved. Copyright (c) 2002 Networks Associates Technology, Inc. Copyright 1999-2001 The Open LDAP Foundation. All Rights Reserved. Copyright 1999 Andrzej Bialecki. All rights reserved. Copyright 2000 The Apache Software Foundation. All rights reserved. Copyright (C) 2001-2003 Robert A. van Engelen, Genivia inc. All Rights Reserved. Copyright (c) 1997-2004 University of Cambridge. All rights reserved. Copyright (c) 1995. David Greenman. Copyright (c) 2001 Jonathan Lemon. All rights reserved. Copyright (c) 1997, 1998, 1999. Bill Paul. All rights reserved. Copyright (c) 1994-1997 Matt Thomas. All rights reserved. Copyright 2000 Jason L. Wright. Copyright 2000 Theo de Raadt. Copyright 2001 Patrik Lindergren. All rights reserved. Part No. NS-MIG-80-1206 Document Code: March 14, 2007 (MS)

C ONTENTS

Contents

Chapter 1

Introduction
How to Use This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 Getting Service and Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6 Additional Maintenance Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6 Silver Maintenance Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7 Gold Maintenance Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7 Subscription Advantage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7 Knowledge Center Watches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8 Education and Training . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8 Related Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8

Chapter 2

Upgrading the Access Gateway Enterprise Edition Software

Upgrading from Version 6.1 to Version 8.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9 Upgrading a Single Access Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9 Upgrading a High Availability Pair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10 Upgrading from Version 7.0 to Version 8.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12 Upgrading a Single Access Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12 Upgrading a High Availability Pair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

Chapter 3

Reverting the Access Gateway Software to an Earlier Version

Reverting from Version 8.0 to 7.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17 Reverting from Version 8.0 to 6.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19

Appendix A

Troubleshooting
Insufficient Space to Install the Software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23 Automatically Cleaning Up Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24 Upgrading the License File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24

Citrix Access Gateway Enterprise Edition Installation and Migration Guide

Migration Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25 Consistency in XML API Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . .25 XML API User Interface Improvements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25 XML API Improvements in API Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26

C HAPTER 1

Introduction

This chapter describes who should read the Citrix Access Gateway Enterprise Edition Installation and Migration Guide, how it is organized, and its document conventions.

How to Use This Guide

This user guide is intended for system administrators responsible for installing and configuring the Access Gateway. This document assumes that the Access Gateway is connected to an existing network and that the administrator has experience configuring that network The configuration steps in this document assume that the Access Gateway is deployed as a standalone appliance and that users connect directly to the Access Gateway.

Document Conventions
Access Gateway documentation uses the following typographic conventions for menus, commands, keyboard keys, and items in the program interface:
Convention Boldface Italics Meaning Commands, names of interface items such as text boxes, option buttons, and user input. Placeholders for information or parameters that you provide. For example, filename in a procedure means you type the actual name of a file. Italics also are used for new terms and the titles of books. The Windows system directory, which can be WTSRV, WINNT, WINDOWS, or other name you specify when you install Windows. Text displayed in a text file. A series of items, one of which is required in command statements. For example, { yes | no } means you must type yes or no. Do not type the braces themselves.

%SystemRoot% Monospace { braces }

Citrix Access Gateway Enterprise Edition Installation and Migration Guide

Convention [ brackets ]

Meaning Optional items in command statements. For example, [/ping] means that you can type /ping with the command. Do not type the brackets themselves. A separator between items in braces or brackets in command statements. For example, { /hold | /release | /delete } means you type /hold or /release or /delete. You can repeat the previous item or items in command statements. For example, /route:devicename[,] means you can type additional devicenames separated by commas.

| (vertical bar)

(ellipsis)

Getting Service and Support

Citrix provides technical support primarily through the Citrix Solution Advisors. Our Citrix Solutions Advisor partners are trained and authorized to provide a high level of support to our customers. Contact your supplier for first-line support or check for your nearest CSN partner at http://www.citrix.com/support/. In addition to the CSN channel program, Citrix offers a variety of self-service, Web-based technical support tools from its Knowledge Center at http://support.citrix.com/. Knowledge Center features include: A knowledge base containing thousands of technical solutions to support your Citrix environment An online product documentation library Interactive support forums for every Citrix product Access to the latest hotfixes and service packs Security bulletins Online problem reporting and tracking (for organizations with valid support contracts)

Another source of support, Citrix Preferred Support Services, provides a range of options that allows you to customize the level and type of support for your organizations Citrix products.

Additional Maintenance Support

In addition to the support options provided by Citrix, all Access Gateway appliances are available with Silver and Gold maintenance options. If you purchased either of these options, documentation is provided with the appropriate Citrix Technical Support numbers if you need to call.

Chapter 1

Introduction

Silver Maintenance Option

The Silver maintenance option provides unlimited Access Gateway support for one year. This option provides basic coverage hours, one assigned support account manager for non-technical relations management, four named contacts, and advanced replacement for materials. Technical support is available at the following times: North America, Latin America, and the Caribbean: 8 a.m. to 9 p.m. US Eastern time, Monday through Friday Asia (excluding Japan): 8 a.m. to 6 p.m. Hong Kong time, Monday through Friday Australia and New Zealand: 8 a.m. to 6 p.m. AEST, Monday through Friday Europe, Middle East, and Africa: 8 a.m. to 6 p.m. GMT, Monday through Friday

Gold Maintenance Option

The Gold maintenance option provides unlimited Access Gateway support for one year. Support is available 24 hours a day, 7 days a week. There is one assigned support account manager for non-technical relations management and six named contacts.

Subscription Advantage
Your product includes a one-year membership in the Subscription Advantage program. The Citrix Subscription Advantage program gives you an easy way to stay current with the latest software version and information for your Citrix products. Not only do you get automatic access to download the latest feature releases, software upgrades, and enhancements that become available during the term of your membership, you also get priority access to important Citrix technology information. You can find more information on the Citrix Web site at http://www.citrix.com/services/ (select Subscription Advantage). You can also contact your sales representative, Citrix Customer Care, or a member of the Citrix Solutions Advisors program for more information.

Citrix Access Gateway Enterprise Edition Installation and Migration Guide

Knowledge Center Watches

The Citrix Knowledge Center allows you to configure watches. A watch notifies you if the topic you are interested in was updated. Watches allow you to stay notified of updates to Knowledge Base or Forum content. You can set watches on product categories, document types, individual documents, and on Forum product categories and individual topics. To set up a watch, log on to the Citrix Support Web site at http://support.citrix.com. After you are logged on, in the upper right corner, click My Watches and follow the instructions.

Education and Training

Citrix offers a variety of instructor-led training and Web-based training solutions. Instructor-led courses are offered through Citrix Authorized Learning Centers (CALCs). CALCs provide high-quality classroom learning using professional courseware developed by Citrix. Many of these courses lead to certification. Web-based training courses are available through CALCs, resellers, and from the Citrix Web site. Information about programs and courseware for Citrix training and certification is available from http://www.citrix.com/edu/.

Related Documentation
For additional information about the Access Gateway, refer to the following guides: Citrix Access Gateway Enterprise Edition Administrators Guide Citrix Access Gateway Enterprise Edition Readme

C HAPTER 2

Upgrading the Access Gateway Enterprise Edition Software

If you have the Access Gateway Enterprise Edition appliance configured in your network, you can upgrade to the latest version of the appliance software. This chapter discusses upgrading the following: Upgrading from Version 6.1 to Version 8.0 Upgrading from Version 7.0 to Version 8.0

The Access Gateway can be upgraded for both standalone and high availability deployments.

Upgrading from Version 6.1 to Version 8.0

This section covers steps to upgrade the system software from version 6.1 to version 8.0.

Upgrading a Single Access Gateway

In this procedure, you log on to the Access Gateway using the command line interface.
To upgrade the software on an appliance

1. 2. 3. 4. 5.

At a command prompt, type the user name nsroot and the password nsroot to log onto the appliance Type shell to switch to the shell prompt. At a command prompt, type: cd /var/nsinstall to open the default installation directory. Type mkdir 8.0install to create a temporary directory named 8.0nsinstall to store the installation package. Type cd 8.0install to switch to the temporary directory.

10

Citrix Access Gateway Enterprise Edition Intallation and Migration Guide

6.

Download the installation package and the documentation bundle (ns-8.0<build number>-doc.tgz) to the temporary directory /var/nsinstall/8.0nsinstall. Type tar xzvf build_andes_XX.tgz to extract the contents of the installation package into the temporary directory. Type ./installns to run the script that installs the new version of the system software. If the disk space on the flash drive is insufficient to install the new software, an error message is displayed and the installation is aborted. For more information, see Insufficient Space to Install the Software on page 23. When the installation is complete, restart the Access Gateway. Press N if you want to upgrade the license file before restarting. Press Y if you want to upgrade the license file after restarting. For more information about the Access Gateway license file see Upgrading the License File on page 24 and the Access Gateway Enterprise Edition Administrators Guide. When the Access Gateway restarts, log on as the nsroot user.

7. 8.

9.

Upgrading a High Availability Pair

The following procedure lists the steps to upgrade the system software on both nodes of a HA pair. Machine A is the primary node and Machine B is secondary node before the upgrade.
To install the Access Gateway software on the secondary node (Machine B)

1. 2. 3. 4. 5. 6.

Type the user name nsroot with the password nsroot to log on to the system. Type shell to switch to the shell prompt. Type cd /var/nsinstall to open the default installation directory. Type mkdir 8.0install to create a temporary directory named 8.0nsinstall to store the installation package. Type cd 8.0install to access the temporary directory. Download the installation package and the documentation bundle (ns-8.0<build number>-doc.tgz) to the temporary directory /var/nsinstall/8.0nsinstall. Type tar xzvf build_andes_XX.tgz to extract the contents of the installation package into the temporary directory.

7.

Chapter 2

Upgrading the Access Gateway Enterprise Edition Software

11

8.

Type ./installns to run the script that installs the new version of the Access Gateway software. If the disk space on the flash drive is insufficient to install the software, an error message appears and the installation is aborted. For more information, see Insufficient Space to Install the Software on page 23. After the installation is completed, you are prompted to restart the Access Gateway. Press N if you want to upgrade the license file before restarting. Press Y if you want to upgrade the license file after restarting. For more information about licensing on the Access Gateway, see Upgrading the License File on page 24 and the Access Gateway Enterprise Edition Administrators Guide.

9.

10. 11.

When the Access Gateway starts, log on as the administrative user. Type show ha node to display the state of the Access Gateway. The results must show that Machine B is the secondary node (Master State: Secondary) and that synchronization is disabled (Sync State: Disabled). Node State: UP

To install the Access Gateway software on the primary node (Machine A)

1. 2. 3. 4. 5. 6.

At a command prompt, type the user name nsroot with the password nsroot to log on to the Access Gateway. Type shell to switch to the shell prompt. Type cd /var/nsinstall to open the default installation directory. Type mkdir 8.0nsintall to create a temporary directory named 8.0nsinstall to store the installation package. Type cd 8.0install to change to the temporary directory. Download the installation package and the documentation bundle (ns-8.0<build number>-doc.tgz) to the temporary directory /var/nsinstall/8.0nsinstall. Type tar xzvf build_andes_XX.tgz to extract the contents of the installation package into the temporary directory. Type ./installns to run the script that installs the new version of the Access Gateway software. If the disc space on the flash drive is insufficient to install the new software, an error message is displayed and the installation is aborted. For more information, see Insufficient Space to Install the Software on page 23.

7. 8.

12

Citrix Access Gateway Enterprise Edition Intallation and Migration Guide

9.

After the installation is complete, you are prompted to restart the system. Press N if you want to upgrade the license file before restarting. Press Y if you want to upgrade the license file after restarting. For more information about licensing, see Upgrading the License File on page 24 and the Access Gateway Enterprise Edition Administrators Guide.

To verify the node sequence on Machine B

1. 2.

Type show ha node to verify whether Machine B is the primary node. Type save ns config to save the configuration.

To verify the node sequence on Machine A

1. 2. 3.

Type the user name nsroot with the password nsroot to log on to the Access Gateway. Type show ha node to verify that Machine A is the secondary node with the node state as UP. Type show ns runningconfig to verify whether the configuration of Machine A is synchronized with that of Machine B.

Note Machine A becomes the secondary node and Machine B becomes the primary node after both of the nodes in the HA pair are upgraded.

Upgrading from Version 7.0 to Version 8.0

This section covers steps to upgrade the Access Gateway software from version 7.0 to version 8.0.

Upgrading a Single Access Gateway

This section describes the procedure for upgrading a single Access Gateway from version 7.0 to version 8.0.
To upgrade a single Access Gateway

1. 2. 3.

Type the user name nsroot with the password nsroot to log on to the appliance. Type shell to switch to the shell prompt. Type cd /var/nsinstall to switch to the default installation directory.

Chapter 2

Upgrading the Access Gateway Enterprise Edition Software

13

4. 5. 6.

Type mkdir 8.0nsinstall to create a temporary directory named 8.0nsinstall to store the installation package. Type cd 8.0nsinstall to switch to the temporary directory. Download the installation package and the documentation bundle (ns-8.0<build number>-doc.tgz) to the temporary directory /var/nsinstall/8.0nsinstall. Type tar xzvf build_andes_XX.tgz to extract the contents of the installation package into the temporary directory. Type ./installns to run the script that installs the new version of the software. If the disc space on the flash drive is insufficient to install the new software, an error message is displayed and the installation is aborted. For more information, see Insufficient Space to Install the Software on page 23 After the installation is completed, you are prompted to restart the system. Press N if you want to upgrade the license file before restarting. Press Y if you want to upgrade the license file after restarting. For more information about licensing, see Upgrading the License File on page 24 and the Access Gateway Enterprise Edition Administrators Guide. When the Access Gateway restarts, log on as the nsroot user.

7. 8.

9.

Upgrading a High Availability Pair

The following procedure lists the steps to upgrade the system software on both nodes of a HA pair. Machine A is the primary node and Machine B is secondary node before the upgrade.
To install the Access Gateway software on the secondary node (Machine B)

1. 2. 3. 4. 5.

Type the user name nsroot with the password nsroot to log on to the Access Gateway. Type shell to switch to the shell prompt. Type cd /var/nsinstall to switch to the default installation directory. Type mkdir 8.0nsinstall to create a temporary directory named 8.0nsinstall to store the installation package. Type cd 8.0nsinstall to switch to the temporary directory, /var/nsinstall/8.0nsinstall.

14

Citrix Access Gateway Enterprise Edition Intallation and Migration Guide

6. 7. 8.

Download the installation package and the documentation bundle (ns-8.0<build number>-doc.tgz) to the temporary directory. Type tar xzvf build_andes_XX.tgz to extract the contents of the installation package into the temporary directory. Type ./installns to run the script that installs the new version of the Access Gateway software. If the disc space on the flash drive is insufficient to install the new software, an error message is displayed and the installation is aborted. For more information, see Insufficient Space to Install the Software on page 23. After the installation is complete, you are prompted to restart the system. Press N if you want to upgrade the license file before restarting. Press Y if you want to upgrade the license file after restarting. For more information about licensing, see Upgrading the License File on page 24 and the Access Gateway Enterprise Edition Administrators Guide. After the Access Gateway restarts, log on as the nsroot user.

9.

10.

Type show ha node to display the state of the system. The command must indicate that Machine B is a secondary node (Master State: Secondary) and that synchronization is disabled (Sync State: AUTO Disabled).

To install the Access Gateway software on the primary node (Machine A)

1. 2. 3. 4. 5. 6. 7. 8.

Type the user name nsroot with the password nsroot to log on to the Access Gateway. Type shell command to switch to the shell prompt. Type cd /var/nsinstall to switch to the default installation directory. Type mkdir 8.0nsinstall to create a temporary directory named 8.0nsinstall to store the installation package. Type cd 8.0nsintall to switch to the temporary directory, /var/nsinstall/ 8.0nsinstall. Download the installation package and the documentation bundle (ns-8.0<build number>-doc.tgz) to the temporary directory. Type tar xzvf build_andes_XX.tgz to extract the contents of the installation package into the temporary directory. Type ./installns to run the script that installs the new version of the system software. If the disc space on the flash drive is insufficient to install the new kernel, an error message is displayed and the installation is aborted. For

Chapter 2

Upgrading the Access Gateway Enterprise Edition Software

15

more information, see Insufficient Space to Install the Software on page 23. 9. After the installation is completed, you are prompted to restart the system. Press N if you want to upgrade the license file before restarting. Press Y if you want to upgrade the license file after restarting. For more information about licensing, see Upgrading the License File on page 24 and and the Access Gateway Enterprise Edition Administrators Guide.
To verify the node on Machine B

1. 2.

Type show ha node to verify whether Machine B is the primary node. Type save ns config to save the configuration.

To verify the node on Machine A

1. 2. 3.

Type the user name nsroot with the password nsroot to log on to the system. Type show ha node to verify whether Machine A is the secondary node with the node state as UP. Type show ns runningconfig to verify whether the configuration of Machine A has been synchronized with that of Machine B.

Note Machine A becomes the secondary node and Machine B becomes the primary node after both nodes of the high availability pair are upgraded.

16

Citrix Access Gateway Enterprise Edition Intallation and Migration Guide

C HAPTER 3

Reverting the Access Gateway Software to an Earlier Version

This chapter discusses reverting the Access Gateway Version 8.0 software to an earlier version of the software. You can revert Version 8.0 to Version 7.0 and Version 6.1.

Reverting from Version 8.0 to 7.0

The following procedure lists the steps to revert the Access Gateway software on both nodes of a High Availability pair. Machine A is the primary node and Machine B is secondary node before the downgrade.
To revert the Access Gateway software on the secondary node (Machine B)

1. 2. 3. 4.

Type the user name nsroot with the password nsroot to log on to the Access Gateway. Type shell to switch to the shell prompt. Type cd /nsconfig to switch to the configuration directory. Type mv ns.conf.NS7.0 ns.conf to rename the 7.0 configuration file from ns.conf.NS7.0 to ns.conf.

Note The file ns.conf.NS7.0 is the backup configuration file that is automatically created when the Access Gateway software is upgraded from Version 7.0 to Version 8.0.
5. Rename the backup copy of the 7.0 license file (/nsconfig/ns.lic_back_x.x) file to ns.lic.

Note The backup 7.0 license file, ns.lic_back_x.x is created by the administrator when the Access Gateway is upgraded to Version 8.0.

18

Citrix Access Gateway Enterprise Edition Installation and Migration Guide

6. 7. 8. 9. 10. 11.

Type cd /var/nsinstall to switch to the installation directory. Type mkdir 7.0install to create a temporary directory named 7.0install to store the installation package. Type cd 7.0install/ to switch to the temporary directory, /var/nsinstall/7.0install. Download the installation package to the temporary directory. Type tar xzvf build_sierra_XX.tgz to extract the contents of the installation package into the temporary directory. Type ./installns to run the script that installs the new version of the Access Gateway software. If the disc space on the flash drive is insufficient to install the new software, an error message is displayed and the installation is aborted. For more information, see Insufficient Space to Install the Software on page 23. After the installation is complete, you are prompted to restart the Access Gateway. Press Y. After restarting, the Access Gateway does not change state and continues as the secondary node.

12. 13.

To revert the Access Gateway software on the primary node (Machine A)

1. 2. 3. 4.

Type the user name nsroot with the password nsroot to log on to the Access Gateway. Type shell to switch to the shell prompt. Type cd /nsconfig to switch to the configuration directory. Type mv ns.conf.NS7.0 ns.conf to rename the 7.0 configuration file (ns.conf.NS7.0) to ns.conf.

Note The file ns.conf.NS7.0 is the backup configuration file that is automatically created when the system software is upgraded from Version 7.0 to Version 8.0.
5. Rename the backup copy of the 7.0 license file (/nsconfig/ns.lic_back_x.x) file to ns.lic.

Note The backup 7.0 license file, ns.lic_back_x.x is created when the Access Gateway is upgraded from Version 7.0 to Version 8.0.
6. Type cd /var/nsinstall/ to switch to the installation directory.

Chapter 3

Reverting the Access Gateway Software to an Earlier Version

19

7. 8. 9. 10. 11.

Type mkdir 7.0install to create a temporary directory named 7.0install to store the installation package. Type cd 7.0install/ to switch to the temporary directory, /var/nsinstall/ 7.0install. Download the installation package to the temporary directory. Type tar xzvf build_sierra_XX.tgz to extract the contents of the installation package into the temporary directory. Type ./installns to run the script that installs the new version of the Access Gateway software. If the disc space on the flash drive is insufficient to install the new software, an error message is displayed and the installation is aborted. For more information, see Insufficient Space to Install the Software on page 23. After the installation is completed, you will be prompted to restart the system. Press Y. After restarting, the system becomes the secondary node.

12. 13.

Note When this procedure is complete, Machine A becomes the secondary node and Machine B becomes the primary node after both appliances in the high availability pair are reverted to the earlier version of the software.

Reverting from Version 8.0 to 6.1

The following procedure lists the steps to downgrade the system software on both nodes of a high availability pair. Machine A is the primary node and Machine B is secondary node before the downgrade.
To revert the software on the secondary node (Machine B)

1. 2. 3.

Type the user name nsroot with the password nsroot to log on to the Access Gateway. At a command prompty, type shell to switch to the shell prompt. Type cd /nsconfig to switch to the configuration directory.

20

Citrix Access Gateway Enterprise Edition Installation and Migration Guide

4.

Type mv ns.conf.NS6.1 ns.conf to rename the Version 6.1 configuration file (ns.conf.NS6.1) to ns.conf.

Note The file ns.conf.NS6.1 is the backup configuration file that is automatically created when the Access Gateway is upgraded from Version 6.1 to Version 8.0.
5. Rename the backup copy of the 6.1 license file (/nsconfig/ns.lic_back_x.x) file to ns.lic.

Caution The license file ns.lic_back_x.x is created when the Access Gateway is upgraded to Version 8.0.
6. 7. 8. 9. 10. 11. Type cd /var/nsinstall/ to switch to the installation directory. Type mkdir 6.1install to create a temporary directory named 6.1install to store the installation package. Type cd 6.1install/ to switch to the temporary directory /var/nsinstall/6.1install. Download the installation package to the temporary directory. Type tar xzvf build_k2_XX to extract the contents of the installation package into the temporary directory. Type ./installns -6 to run the script that installs the new version of the Access Gateway software. If the disc space on the flash drive is insufficient to install the new software, an error message is displayed and the installation is aborted. For more information, see Insufficient Space to Install the Software on page 23. After the installation is completed, you are prompted to restart the system. Press Y.

12.

After restarting, the Access Gateway does not change state and continues as the secondary node.
To revert the Access Gateway software on the Primary Node (Machine A)

1. 2. 3.

Type the user name nsroot with the password nsroot to log on to the system. At a command prompt, type shell to switch to the shell prompt. Type cd /nsconfig to switch to the configuration directory.

Chapter 3

Reverting the Access Gateway Software to an Earlier Version

21

4.

Type mv ns.conf.NS6.1 ns.conf to rename the 6.1 configuration file (ns.conf.NS6.1) to ns.conf.

Note The file ns.conf.NS6.1 is the backup configuration file that is automatically created when the Access Gateway is upgraded from Version 6.1 to Version 8.0.
5. Rename the backup copy of the 6.1 license file (/nsconfig/ns.lic_back_x.x) file to ns.lic.

Note The backup file ns.lic_back_x.x is created when the Access Gateway is upgraded from Version 6.1 to Version 8.0.
6. 7. 8. 9. 10. 11. Type cd /var/nsinstall/ to switch to the installation directory. Type mkdir 6.1install to create a temporary directory named 6.1install to store the installation package. Type cd 6.1install/ to access the temporary directory /var/nsinstall/ 6.1install. Download the installation package to the temporary directory. Type tar xzvf build_k2_XX.tgz to extract the contents of the installation package into the temporary directory. Type ./installns -6 to run the script that installs the new version of the Access Gateway software. If the disc space on the flash drive is insufficient to install the new software, an error message is displayed and the installation is aborted. Insufficient Space to Install the Software on page 23. After the installation is completed, you are prompted to restart the system. Press Y.

12.

After restarting, the Access Gateway becomes the secondary node. Machine A becomes the secondary node and Machine B becomes the primary node after both the nodes of the HA pair are downgraded.

22

Citrix Access Gateway Enterprise Edition Installation and Migration Guide

A PPENDIX

Troubleshooting

When you upgrade or revert the software on the Access Gateway, you might encounter problems. This chapter discusses some of the issues you might find and how to resolve them.

Insufficient Space to Install the Software

If the disk space on the flash drive is insufficient to install the new software, an error message is displayed and the installation is aborted. A sample error message is displayed as follows. Size of kernel ns-6.1-64.1.gz is 36840.093 kilobytes Available space on / filesystem is 22011 kilobytes Available space on / filesystem is insufficient to install ns-6.1-64.1.gz

Note The flash directory differs depending on the software that is being upgraded. When upgrading or reverting from 6.1 or 7.0 to 8.0, use the /flash directory.
When this message is displayed, you need to delete earlier versions of the software from the flash directory by changing flags.
To change the flags

1.

rm kernel.xx or ns-6.0-xx.gz For appliances running release 6.0 and above, delete old software from the /flash directory.

Caution Do not delete the files from the /directory kernel and kernel.GENERIC.
Return to the build installation directory and run the installation script.

24

Citrix Presentation Server Administrators Guide

Automatically Cleaning Up Files

The cleanup procedure has been simplified in Version 7.0 and Version 8.0. You do not need to manually delete kernel files from the flash drive. During the installation process, if the disk space on the flash drive is found to be insufficient, the system displays the disk cleanup" message that prompts you to initiate the cleanup process. The prompt looks like this: Detected Version >= NS6.0 Installation path for kernel will be /flash Size of kernel ns-8.0-21.7.gz is 58003.323 kilobytes Available space on /flash/ filesystem is 25075 kilobytes Available space on /flash/ filesystem is insufficient to install ns-8.0-21.7.gz Do you want Auto Cleanup [Y/N] ? To initiate the cleanup process, press Y. The following is displayed: Starting cleanup... Created backup directory... /var/nsbackup/ns_2006_11_16_1_38_2 Cleaning files... /flash/etc Cleaning file... /flash/ns-6.1-96.gz Successfully cleanup the /flash and preserved the cleanup files in /var/ nsbackup/ns_2006_11_16_1_38_2 The installation process continues after the cleanup is completed successfully.

Upgrading the License File

Version 8.0 of the Access Gateway has a new license feature. When you receive your appliance, install the user licenses that you receive from Citrix. For more information about licensing, see the Access Gateway Enterprise Edition Administrators Guide.
To upgrade the license file

1. 2.

Type cd /nsconfig to access the directory. Back up the current license file (ns.lic) by saving it under a different name (ns.lic_back_x.x).

Appendix A

Troubleshooting

25

3.

Download the new license file to the /nsconfig directory.

Note Always transfer the license key in ASCII format. If you transfer it in binary format, ^m characters are inserted, which might make the key unusable.
4. Type reboot ns to restart the Access Gateway.

Migration Issues
This section covers the various migration issues and steps to tackle them.

Consistency in XML API Naming Conventions

The use of upper and lower case while naming XML API programming constructs has been standardized. The standards are as follows: All methods are named using lower case All parameters except keywords are named using lower case All enumeration values are named using upper case All return structure members are named using lower case

XML API User Interface Improvements

The Boolean value TRUE which was passed with the 'unset' API is not required XML APIs which used the enumerated data type with numeric values had usability issues which are fixed XML APIs which had the enumerated data type whose value contained a hyphen for WSDL had usability issues which are fixed The 'stat ns' command has been deprecated and a new 'stat system' command is introduced with a smaller set of counters

26

Citrix Presentation Server Administrators Guide

XML API Improvements in API Usage

The 'getcmpaction' function returned only one action even when there is more than one configured. This issue is resolved. The 'getcsvserver' function returned only one virtual server name even when there is more than one configured. This issue has been resolved. The 'bindsslglobal_policy' and 'bindsslglobal_priority' APIs have been combined to a single API 'bindsslglobal_policy' which takes priority as an argument. The 'bindrewriteglobal_gotopriorityexpression' and 'bindrewriteglobal_priority' API is deprecated and a new API 'bindrewriteglobal_policy' is introduced which takes gotopriorityexpression and priority as a arguments. The 'getvlan()' function used to throw an exception if the value "0" was assigned to an unsignedint data type. This issue is resolved and a "no such resource" error message is returned. The 'statservice' API used to return an empty list when used. This issue is fixed. The 'unbindaaauser_urlname' API is renamed to 'unbindaaauser_url' to maintain consistency in naming. The 'bindaaagroup_urlname' API has been renamed to 'bindaaagroup_url' to maintain consistency in naming. The 'bindrewriteglobal_policy' and 'unbindrewriteglobal_policy' APIs are removed.