Citrix Systems, Inc. Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Author: Scott L. Lindars Department: Worldwide Technical Readiness Issue Date: June 2007 Circulation: Citrix Employees, Partners, and Customers Document Version: 1.0 Based on: Access Gateway 8.0, Enterprise Edition Build 45.4
Table of Contents 1. Introduction... 1 1.1. General Requirements... 1 1.2. Scripts... 1 2. Upgrade Procedure... 2 2.1. Upgrade Procedure via the Command Line... 2 3. Backup Procedure... 7 3.1. Backup Procedure via the Configuration Utility... 8 3.2. Backup Procedure using the Command Line... 13 4. Restore Procedures... 16 4.1. Restore Procedure via the Command Line... 16 5. Reset Procedures... 24 5.1. Restore Procedure using the Command Line... 24 6. Scripted Procedures... 27 6.1. Backup Script (backup.sh)... 27 6.2. Restore Script (restore.sh)... 30 6.3. Reset Script (reset.sh)... 31
1. Introduction This document will explain the procedures for upgrading, backing up, restoring, and resetting Citrix Access Gateway Enterprise Edition. Whenever applicable, instructions for performing the procedures from both the Access Gateway Configuration Utility and the Command Line Interface will be included. For the purposes of this document the Access Gateway Command Line Interface may be referred to as the CLI. The procedures and screen shots in this document are from Access Gateway 8.0, Enterprise Edition build 45.4 but the general procedure and concepts will apply to earlier versions as well. This document does not cover performing the initial configuration of Access Gateway Enterprise Edition including steps such as connecting via a serial cable, configuring the system IP address, or other basic functions. Please refer to the Citrix Access Gateway Enterprise Edition Administrator s Guide for additional information if needed. 1.1. General Requirements 1. Access Gateway Enterprise Edition Appliance 2. Windows client computer 3. Putty or other SSH program 4. WinSCP or other Secure FTP program 1.2. Scripts In addition to the step by step procedures for performing the backup, restore, and reset the operation can be automated with a script. Scripts details and instructions are included in the Scripted Procedures section. Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 1
2. Upgrade Procedure This section demonstrates the procedure for upgrading the firmware version using the Access Gateway Enterprise Edition command line interpreter or CLI. 2.1. Upgrade Procedure via the Command Line This section demonstrates the procedure for upgrading the firmware version using the Access Gateway Enterprise Edition command line interpreter or CLI. Steps 12 17 are only needed if you wish to upgrade to a new set of documentation. Step Action 1 Download the desired Access Gateway Enterprise Edition firmware version from www.mycitrix.com and save the firmware to your local workstation. 2 Use a secure FTP client to connect to the appliance in order to upload the firmware package. Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 2
3 Copy the firmware package from your local computer to the /var/nsinstall directory on the appliance. 4 Open an SSH client to open an SSH connection to the appliance. 5 Connect to the shell by typing: shell 6 Change to the /var/nsinstall directory by typing cd /var/nsinstall Type ls to view the contents of the directory. Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 3
7 Unpack the firmware package by typing tar xvzf build_x_xx.tgz where build_x_xx.tgz is the firmware version you want to upgrade to. For example tar xvzf build_andes_45.4.tgz 8 Remove any old firmware files from the /flash directory in order to free up space 1) Type cd /flash to change to the flash directory 2) Type ls to view the contents of the flash directory 3) Type rm ns-x.x.gz where ns-x.x.gz represents the older firmware version(s) that are located in the flash directory. For example rm ns-8.0.-44.gz 9 Return to the /var/nsinstall directory by typing cd /var/nsinstall 10 Initiate the upgrade procedure by typing./installns The appliance must be rebooted before the new firmware version can be run. After the upgrade has completed type Y to reboot now or N to manually reboot later. Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 4
11 After the reboot has completed, reconnect to the appliance using your SSH client. Type what or show version to confirm the new firmware build is running.! Steps 12 17 are only needed if you are upgrading the documentation materials. 12 Download the desired Access Gateway Enterprise Edition documentation package from www.mycitrix.com and save the file to your local workstation. 13 Use a secure FTP client to connect to the appliance and upload the documentation package to the /var/netscaler/doc directory. 14 Open an SSH client to open an SSH connection to the appliance. Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 5
15 Connect to the shell by typing: shell 16 Unpack the documentation package by typing tar xvzf ns-x-x-doc.tgz where ns-x-x-doc.tgz is the documentation package you want to upgrade to. For example: tar xvzf ns-8.0-45-doc.tgz 17 Type exit once to exit the shell and exit a second time to end the SSH session. Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 6
3. Backup Procedure This section demonstrates the procedure for backing up an Access Gateway Enterprise Edition configuration using Access Gateway Configuration Utility and Command Line. This procedure uses a tool called the Tech Support File which saves many of the critical files into a tar file. The tar file can be saved to a remote computer for backup purposes. Note: Any custom modifications or files that have been added to the appliances configuration are not included in this procedure and should also be backed up by the appliance administrator. In addition to the Tech Support File, the log files and SSL certificates can be backed up using additional steps described below. The contents of the backup files can be manually restored to an Access Gateway Enterprise Edition appliance as described in the Restore Procedures section. The following configuration information is saved in the Tech Support file: License files: The entire contents of the /nsconfig/license directory Monitors: A collection of pearl monitors. These are not required for complete restore unless custom monitors have been created SSH keys: The SSH keys for connecting to the appliance. ns.conf files: All ns.conf files in the /nsconfig directory including the ns.conf.0-ns.conf.4 Miscellaneous configuration files: Various other files from the /nsconfig directory including: o ZebOS.conf o resolv.conf o snmpd.cong o nstrace.conf o rc.conf o rc.netscaler o localtime o nsw.conf.post o ns.conf.ns6.1 Individual user profiles: Individual user profiles for each Access Gateway Enterprise Edition user that has logged on are created and stored in the /var/vpn/bookmark folder. Each profile is a unique XML file; e.g. johnd.xml shellcmds.txt, showcmds.txt, statcmds.txt: Summary files of commands. These files are not required for a restore. Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 7
3.1. Backup Procedure via the Configuration Utility Step Action 1 Use the Configuration Utility to connect to Access Gateway. 2 Expand the System node and select Diagnostics page. Click on the Tech Support Run option. Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 8
3 After clicking Run, the Tech Support file is created. The default name is support.tgz and it is stored in /var/tmp. After the file is created click Close. The Save option is not used for uploading the files to your local computer. 4 Return to the Diagnostics page and select Download Tech Support File Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 9
5 Select the support.tgz and click Select. 6 Browse to a location on the local computer where the support.tgz file should be downloaded to and click Download. Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 10
7 To view the contents of the Support.tgz file browse to the location of the Tech Support File on the local workstation and extract the contents of the tgz file. By default the tar file will extract the contents to a folder named Support. 8 SSL certificate and log file backup: There is no Configuration Utility method for backing up the SSL certificates and log files. This procedure must be done from the command line. Steps 8 14 detail this procedure. Open an SSH client to open an SSH connection to the appliance. 9 Connect to the shell by typing: shell 10 Change to the /var/tmp directory by typing: cd /var/tmp Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 11
11 Backup the SSL certificates by creating a backup file named sslcerts.tgz which includes the contents of the /nsconfig/ssl directory by typing: tar cvf sslcerts.tgz /nsconfig/ssl/* 12 Backup the log files by creating a backup file named logs.tgz which includes the contents of the /var/log and /var/nslog/ directories by typing: tar cvf log.tgz /var/log/* /var/nslog/* Note: The screen shot above has been truncated. 13 If you wish to view the contents of either of the backup files type: tar cvf filename.tgz e.g. tar -cvf sslcerts.tgz Notice that the tar file is using relative pathnames not absolute pathnames. This means that when the tar file is extracted or restored the files will be extracted to the present working directory. Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 12
14 Use a secure FTP client to connect to the appliance in order to upload the sslcert.tgz and log.tgz file to your local workstation. 3.2. Backup Procedure using the Command Line Step Action 1 Open an SSH client to open an SSH connection to the appliance. 2 Generate a Tech Support File by typing: show techsupport Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 13
3 Connect to the shell by typing: shell 4 Change to the /var/tmp directory by typing: cd /var/tmp 5 Backup the SSL certificates by creating a backup file named sslcerts.tgz which includes the contents of the /nsconfig/ssl directory by typing: tar cvf sslcerts.tgz /nsconfig/ssl/* 6 Backup the log files by creating a backup file named logs.tgz which includes the contents of the /var/log and /var/nslog/ directories by typing: tar cvf log.tgz /var/log/* /var/nslog/* Note: The screen shot above has been truncated. Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 14
7 If you wish to view the contents of either of the backup files type: tar cvf filename.tgz e.g. tar -cvf sslcerts.tgz Notice that the tar file is using relative pathnames not absolute pathnames. This means that when the tar file is extracted or restored the files will be extracted to the present working directory. 8 Use a secure FTP client to connect to the appliance in order to upload the sslcert.tgz and log.tgz file to your local workstation. Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 15
4. Restore Procedures The process of restoring a saved configuration is done from the Command Line. There is currently no method for this procedure using the Configuration Utility however the same approach could be done using a GUI based secure FTP client. The steps outlined below assume the reader has performed the steps in the Backup Procedure section and has saved their support.tgz, sslcerts.tgz, and logs.tgz file to a Windows client computer. This section will cover a complete restore procedure and is broken down by individual components. The reader can also choose to selectively restore individual files as needed. Note: Any custom modifications or files that have been backed up are not included in this procedure and should also be restored by the appliance administrator. 4.1. Restore Procedure via the Command Line Step Action 1 Open an SSH client to open an SSH connection to the appliance. 2 Connect to the shell by typing: shell 3 Change to the /var/tmp directory by typing: cd /var/tmp 4 Create a directory in /var/tmp to copy the backup files to by typing: mkdir restore Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 16
5 Use a secure FTP client to connect to the appliance in order to download the support.tgz, sslcert.tgz and log.tgz files to the /var/tmp/restore directory. 6 Change to the restore directory and confirm the backup files have been copied to by typing: cd restore ls 7 Extract the support.tgz file Steps 7 11 demonstrate restoring the critical files from the support.tgz backup. The reader can selectively choose which files they want to restore. Extract the support.tgz file by typing: tar xvzf support.tgz Note: The screen shot above has been truncated. 8 The contents of support.tgz are extracted to /var/tmp/restore/support as shown Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 17
9 Restore the ns.conf file(s) The ns.conf file stores the appliances configuration including, but not limited to IP addresses, policies, virtual servers, and other settings. When the configuration is saved, the current version is archived as ns.conf.0 ns.conf.4. In order to restore to a saved configuration replace the active ns.conf file with a saved version of ns.conf. To restore to archived version of ns.conf (e.g. ns.conf.0) rename the file ns.conf. For example: mv ns.conf.0 ns.conf The appliance must be rebooted before the changes take effect. To copy all the ns.conf files from the /var/tmp/restore/support folder to the /nsconfig folder type: cp v support/nsconfig/ns.conf* /nsconfig If this is the only required restore step perform the following steps to reboot the appliance otherwise continue to step 10. To reboot now type: exit reboot Y Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 18
10 Restore the license files License files can be reloaded using the configuration utility or using the following command line steps The rc.conf file must be restored or recreated. See CTX113028 for additional steps The appliance must be rebooted before the license files are applied To copy the license files from /var/tmp/restore/support to the /nsconfig/license folder type: cp v support/nsconfig/license/* /nsconfig/license/ To copy rc.conf from /var/tmp/restore/support to the /nsconfig/license folder type: cp v support/nsconfig/rc.conf /nsconfig If this is the only required restore step reboot the appliance otherwise continue to step 11. Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 19
11 Restore miscellaneous files from the Tech Support file The following steps can be done to perform a complete restoration but may not be required in all cases: To restore the additional files that exist in /nsconfig from /var/tmp/restore/support type: cp -v support/nsconfig/z* support/nsconfig/localtime support/nsconfig/snmpd.conf support/nsconfig/resolv.conf support/nsconfig/rc.netscaler /nsconfig To restore the SSH keys from /var/tmp/restore to /nsconfig/ssh type: cp v support/nsconfig/ssh/* /nsconfig/ssh If this is the only required restore step reboot the appliance otherwise continue to step 12. Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 20
12 Restore the SSL Certificates The following steps can be done to restore any SSL certificates including the key file and certificate request files. SSL certificate key pairs are stored in the ns.conf and are not an actual file. The key pairs stored in ns.conf require the actual certificates and keys to be restored to the original directory in order to function To extract the sslcert.tgz file from /var/tmp/restore type: tar xvf sslcerts.tgz The files will be extracted to /var/tmp/restore/nsconfig/ssl. To restore the SSL certificates from /var/tmp/restore/nsconfig/ssl to /nsconfig/ssl type: cp v nsconfig/ssl/* /nsconfig/ssl/ If this is the only required restore step reboot the appliance otherwise continue to step 13 Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 21
13 Restore the log files The following steps can be done to restore any log files backed up into logs.tgz. The reader can selectively restore all or individual log files as needed. To extract the log.tgz file from /var/tmp/restore type: tar xvf log.tgz The files will be extracted to /var/tmp/restore/var/log and /var/tmp/restore/var/nslog. To restore all the logs from /var/tmp/restore/var/log to /var/log type: cp v var/log/*.* /var/log To restore all the logs from /var/tmp/restore/var/nslog to /var/nslog type: cp v var/nslog/* /var/nslog To restore individual log files replace cp v var/log/*.* with the actual log file name e.g. If this is the only required restore step reboot the appliance otherwise continue to step 14. Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 22
14 Restore individual user profiles Individual user profiles for each Access Gateway Enterprise Edition user that has logged on are created and stored in /var/vpn/bookmark. Each profile is a unique XML file; e.g. johnd.xml To restore all the user profiles from /var/tmp/restore/support to /var/vpn/bookmark type: cp -v support/vpn/bookmark/* /var/vpn/bookmark/ To restore individual user profile replace cp v support/vpn/bookmark/* with the actual file name e.g. If this is the only required restore step reboot the appliance. Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 23
5. Reset Procedures This section describes the procedure for resetting all of the configurations on an Access Gateway Enterprise Edition appliance. Note: Any custom modifications or files that have been added to the appliances configuration are not included in this procedure and should also be removed by the appliance administrator. The following data will be removed: 1. Ns.conf, rc.conf, ZebOS.conf 2. SSL certificates 3. Licenses 4. Logs 5. User profiles 5.1. Restore Procedure using the Command Line Step Action 1 Open an SSH client to open an SSH connection to the appliance. 2 To clear a custom command line prompt type: clear prompt 3 Connect to the shell by typing: shell Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 24
4 To remove the core configuration type the following: cd /etc for file in *; do rm /nsconfig/$file 2> /dev/null done cd /nsconfig rm ns.conf* ZebOS.conf rc.conf 5 To remove all the custom SSL certificates, keys, and CSRs type the following: cd ssl GLOBIGNORE= ns-* rm * 6 To remove all the license files type the following: cd../licens e rm * 7 To remove all user profiles type the following: cd /var/vpn/bookmark rm * 8 To remove all of the log files type the following: cd /var/log rm * cd../nslog rm * Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 25
9 Determine if there are any files in the /var/tmp directory that need to be removed. The contents of this directory may differ. cd /var/tmp ls To remove all files and folders type rm rf * To remove specific files or folders type: rm rf <filename or foldername> For example, to remove all tgz files and the restore folder 10 Exit the shell and reboot the appliance by typing: exit rebo ot Y After the appliance has rebooted it will be reset to the initial base configuration. The management IP address will be reset to 192.168.100.1. Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 26
6. Scripted Procedures This section describes the procedure for performing the backup, restore, and reset procedures that are outlined in Sections 3, 4, and 5 via a script. The reader can use these scripts as an alternate method for performing or automating any of the procedures. As with the individual procedures these scripts are dependent upon each other. For instance the restore.sh script looks for the output files of backup.sh. The attached CTX113628.zip file contains 3 scripts; backup.sh, restore.sh, and reset.sh. The scripts should be copied to the /var/tmp directory and run by typing./scriptname.sh where scriptname is the actual name. The scripts have been set to verbose and interactive mode so the user must confirm any deletions and overwrite. To modify the script permissions so it can be run as an executable type: chmod 777 scriptname.sh The scripts can be logged by piping the output to a log file using the tee /var/tmp/logname.log For example:./backup.sh tee /var/tmp/backup.log 6.1. Backup Script (backup.sh) This section will highlight the key steps involved with running the backup.sh script. The output file is backup.tgz which contains 3 other archives; support.tgz, logs.tgz, and sslcerts.tgz. Step Action 1 Use a secure FTP client to connect to the appliance in order to download backup.sh, restore.sh, and reset.sh to the /var/tmp. 2 Open an SSH client to open an SSH connection to the appliance and connect to the shell. Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 27
3 Change to the /var/tmp directory and verify the backup script has been copied by typing: cd /vat/tmp ls la 4 The scripts must have execute x permission in order to be run. To change the permissions type: chmod 777 *.sh 5 Execute the backup script by typing:./backup.sh Note: The screenshot about has been truncated Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 28
6 To verify the script has run and the backup.tgz was created type: Is la 7 Use a secure FTP client to copy backup.tgz to a local computer for a remote archive. Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 29
6.2. Restore Script (restore.sh) This section will highlight the key steps involved with running the restore.sh script. The expected input file is /var/tmp/backup.tgz. This script will ask for confirmation before overwriting any existing files. There is no prompt for copying a file that does not exist in the destination directory. Begin with steps 1-4 in Section 6.1. Step Action 1 Execute the backup script by typing:./restore.sh 2 The script begins by extracting the contents of support.tgz, log.tgz, and sslcerts.tgz into /var/tmp/restore then prompts the user to overwrite any existing files. Type Y or N to confirm any overwrites. For example: 3 After the script has been run the appliance must be rebooted before the new configuration is loaded. Type reboot or uncomment the last line of restore.sh to automate the reboot. Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 30
6.3. Reset Script (reset.sh) This section will highlight the key steps involved with running the reset.sh script. This script will ask for confirmation before deleting files. There is no prompt for copying a file that does not exist in the destination directory. To remove the prompt, edit the script and follow the included instructions. Begin with steps 1-4 in Section 6.1. The following data will be removed: 1. Ns.conf, rc.conf, ZebOS.conf 2. SSL certificates 3. Licenses 4. Logs 5. User profiles Note: Any custom modifications or files that have been added to the appliances configuration are not included in this procedure and should also be removed by the appliance administrator. Step Action 1 Execute the backup script by typing:./reset.sh 2 Type Y or N to confirm any file deletions. 3 After the script has been run the appliance must be rebooted before the new configuration is loaded. Type reboot or uncomment the last line of restore.sh to automate the reboot. After the appliance has rebooted it will be reset to the initial base configuration. The management IP address will be reset to 192.168.100.1. Upgrade, Backup, Restore, and Reset Guide for Access Gateway Enterprise Edition Page 31