Vous êtes sur la page 1sur 124

Citrix NetScaler Administration Guide

Citrix NetScaler 9.1

Copyright and Trademark Notice CITRIX SYSTEMS, INC., 2009. 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 radiofrequency 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 NetScaler Request Switch 9000 Series equipment. If the NetScaler equipment causes interference, try to correct the interference by using one or more of the following measures: Move the NetScaler equipment to one side or the other of your equipment. Move the NetScaler equipment farther away from your equipment. Plug the NetScaler equipment into an outlet on a different circuit from your equipment. (Make sure the NetScaler 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, WANScaler, Citrix XenApp, 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 19992001 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. Last Updated: June 2009

C ONTENTS

Contents

Preface
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i New in This Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ii Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ii Formatting Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ii Related Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii Getting Service and Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii Knowledge Center. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iv Silver and Gold Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iv Education and Training . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .v Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .v

Chapter 1

Citrix NetScaler Authentication and Authorization


Defining Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 Defining Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4 Command Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 Resetting the Default Administrator (nsroot) Password . . . . . . . . . . . . . . . . . . . . .11 Examples of User Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

Chapter 2

SNMP
Importing MIB Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18 Defining SNMP Managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19 Configuring SNMP V1 and V2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20 Adding an SNMP Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21 Removing an SNMP Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21 Configuring SNMP Traps and Alarms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22 Configuring SNMP V3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30 Salient Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30 SNMPv3 Security Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31 Configuring SNMP V3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31

iv

Citrix NetScaler Administration Guide

Chapter 3

Audit Server Logging


Configuring the Citrix NetScaler Audit Server Log . . . . . . . . . . . . . . . . . . . . . . . .38 Configuring Global Audit Server Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . .39 Configuring Audit Server Action and Policy . . . . . . . . . . . . . . . . . . . . . . . . . . .40 Globally Binding the Audit Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41 Installing the Audit Server Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42 Installing Audit Server on the Linux Operating System . . . . . . . . . . . . . . . . . .42 Uninstalling Audit Server on the Linux Operating System . . . . . . . . . . . . . . . .43 Installing Audit Server on the FreeBSD Operating System. . . . . . . . . . . . . . . .43 Uninstalling Audit Server on the FreeBSD Operating System . . . . . . . . . . . . .44 Installing Audit Server on the Windows Operating System . . . . . . . . . . . . . . .44 Uninstalling Audit Server on the Windows Operating System . . . . . . . . . . . . .45 Audit Server Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45 Configuring Audit Server Logging on a Server system. . . . . . . . . . . . . . . . . . . . . .47 Defining Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47 Defining Log Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48 Default Settings for the Log Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50 Adding the IP Addresses of the System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51 Verifying Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52 Starting Audit Server Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52 Stopping Audit Server Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52 Sample Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52 Checklist for Configuring Audit Server Logging. . . . . . . . . . . . . . . . . . . . . . . .53 Configuring Audit Server Logging for a Commonly Used Deployment Scenario.54

Chapter 4

Web Server Logging


How Web Server Logging Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59 Configuring Web Server Logging Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . .60 Enabling or Disabling Web Server Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . .60 Modifying the Default Buffer Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60 Displaying Web Server Logging Information . . . . . . . . . . . . . . . . . . . . . . . . . .61 System Requirements for Web Server Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . .62

Contents

Installing the NSWL files on the Logging System . . . . . . . . . . . . . . . . . . . . . . . . .63 Installing NSWL on a Solaris Operating System . . . . . . . . . . . . . . . . . . . . . . . .63 Installing NSWL on a Linux Operating System. . . . . . . . . . . . . . . . . . . . . . . . .64 Installing NSWL on a FreeBSD Operating System . . . . . . . . . . . . . . . . . . . . . .64 Installing NSWL on a MAC Operating System . . . . . . . . . . . . . . . . . . . . . . . . .65 Installing NSWL on a Windows Operating System. . . . . . . . . . . . . . . . . . . . . .66 Installing NSWL on an AIX Operating System . . . . . . . . . . . . . . . . . . . . . . . . .67 NSWL Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67 Configuring Web Server Logging on the Logging System . . . . . . . . . . . . . . . . . . .68 Modifying the Web Server Log Configuration File . . . . . . . . . . . . . . . . . . . . . .69 Defining Log Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71 Adding the IP Addresses of the NetScaler . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74 Verifying the Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74 Starting Web Server Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75 Stopping Web Server Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75 Sample Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75 Log File Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78 Custom Log Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83 Apache Log Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88 Checklist for Configuring Web Server Logging . . . . . . . . . . . . . . . . . . . . . . . . . . .88

Chapter 5

Advanced Configurations
Configuring Clock Synchronization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89 Configuring Clock Synchronization Manually. . . . . . . . . . . . . . . . . . . . . . . . . .89 Configuring Clock Synchronization Using the Configuration Utility or the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91 Path Maximum Transmission Unit Discovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . .94 The NetScaler in Transparent Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94 The NetScaler in End-Point Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94 Enabling or Disabling PMTU Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95 Configuring TCP Window Scaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95 Configuring Selective Acknowledgement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97 Clearing the Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98

Chapter 6

Reporting Tool
Using the Reporting Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101 Working with Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103 Working with Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108

vi

Citrix NetScaler Administration Guide

How Data Collection Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109 Stopping and Starting the Data Collection Utility . . . . . . . . . . . . . . . . . . . . . .110 Importing Data from the newnslog File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111

P REFACE

Preface

Before you begin to manage and monitor your Citrix NetScaler, take a few minutes to review this chapter and learn about related documentation, other support options, and ways to send us feedback. In This Preface About This Guide New in This Release Audience Formatting Conventions Related Documentation Getting Service and Support Documentation Feedback

About This Guide


The Citrix NetScaler Administration Guide provides a conceptual reference and instructions for managing and monitoring the NetScaler using built-in features, such as command policies, SNMP, Audit server Logging, Web Server Logging, and NTP. This guide provides the following information: Chapter 1, Citrix NetScaler Authentication and Authorization. Configure authentication and authorization to manage access to the NetScaler and different parts of the NetScaler configuration. Chapter 2, SNMP. Learn how SNMP works with NetScaler and how to configure SNMP V1, V2, and V3 on NetScaler. Chapter 3, Audit Server Logging. Configure the NetScaler audit server log to log and monitor the NetScaler states and status information. Also, learn how to configure audit server logging on a server system and for a deployment scenario.

ii

Citrix NetScaler Administration Guide

Chapter 4, Web Server Logging. Configure web server log to maintain a history of the page requests that originate from the NetScaler. Chapter 5, Advanced Configurations. Learn how to set advanced configurations, such as NTP, PMTU, and autodetected services, on the NetScaler. Chapter 6, Reporting Tool. Learn how to use the Reporting tool to view performance statistics as reports with graphs that are based on statistics collected by the nscollect utility.

New in This Release


NetScaler 9.1 nCore Technology is a new software release that uses CPU cores for packet handling and greatly improves the performance of many NetScaler features. NetScaler 9.1 nCore supports features in this guide unless specified otherwise. For a summary of the features that are not supported in NetScaler 9.1 nCore, see the Citrix NetScaler 9.1 and NetScaler 9.1 nCore Release Notes.

Audience
This guide is intended for the following audience: system administrators network administrators

The concepts and tasks described in this guide require you to have a basic understanding of network design, operation, and terminology.

Formatting Conventions
This documentation uses the following formatting conventions. Formatting Conventions
Convention Boldface Italics Meaning Information that you type exactly as shown (user input); elements in the user interface. Placeholders for information or parameters that you provide. For example, FileName in a command means you type the actual name of a file. Also, new terms, and words referred to as words (which would otherwise be enclosed in quotation marks).

Preface

iii

Formatting Conventions
Convention
Monospace

Meaning System output or characters in a command line. User input and placeholders also are formatted using monspace text. Optional items in command statements. For example, in the following command, [-range positiveInteger] means that you have the option of entering a range, but it is not required:
add lb vserver name serviceType IPAddress port [-range positiveInteger]

[ brackets ]

Do not type the brackets themselves. | (vertical bar) A separator between options in braces or brackets in command statements. For example, the following indicates that you choose one of the following load balancing methods:
lbMethod = ( ROUNDROBIN | LEASTCONNECTION | LEASTRESPONSETIME | URLHASH | DOMAINHASH | DESTINATIONIPHASH | SOURCEIPHASH | SRCIPDESTIPHASH | LEASTBANDWIDTH | LEASTPACKETS | TOKEN | SRCIPSRCPORTHASH | LRTM | CALLIDHASH | CUSTOMLOAD )

Related Documentation
A complete set of documentation is available on the Documentation tab of your NetScaler and from http://support.citrix.com/. (Most of the documents require Adobe Reader, available at http://adobe.com/.)
To view the documentation

1. 2. 3.

From a Web browser, log on to the NetScaler. Click the Documentation tab. To view a short description of each document, hover your cursor over the title. To open a document, click the title.

Getting Service and Support


Citrix provides technical support primarily through the Citrix Solutions Network (CSN). Our CSN 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://support.citrix.com/.

iv

Citrix NetScaler Administration Guide

You can also get support from Citrix Customer Service at http://citrix.com/. On the Support menu, click Customer Service.

Knowledge Center
The Knowledge Center offers a variety of self-service, Web-based technical support tools 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 Knowledge Center Alerts that notify you when a topic is updated Note: To set up an alert, sign in at http://support.citrix.com/ and, under Products, select a specific product. In the upper-right section of the screen, under Tools, click Add to your Hotfix Alerts. To remove an alert, go to the Knowledge Center product and, under Tools, click Remove from your Hotfix Alerts. Security bulletins Online problem reporting and tracking (for organizations with valid support contracts)

Silver and Gold Maintenance


In addition to the standard support options, Silver and Gold maintenance options are available. If you purchase either of these options, you receive documentation with special Citrix Technical Support numbers you can call.

Silver Maintenance Option


The Silver maintenance option provides unlimited system support for one year. This option provides basic coverage hours, one assigned support account manager for nontechnical relations management, four named contacts, and advanced replacement for materials. Technical support is available at the following times:

Preface

North America, Latin America, and the Caribbean: 8 A.M. to 9 P.M. U.S. 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. Australian Eastern Standard Time (AEST), Monday through Friday Europe, Middle East, and Africa: 8 A.M. to 6 P.M. Coordinated Universal Time (Greenwich Mean Time), Monday through Friday

Gold Maintenance Option


The Gold maintenance option provides unlimited system support for one year. Support is available 24 hours a day, 7 days a week. There is one assigned support account manager for nontechnical relations management, and there are six named contacts. You can also contact your sales representative, Citrix Customer Care, or a member of the Citrix Solutions Advisors program for more information.

Education and Training


Citrix offers a variety of instructor-led 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 at http://www.citrixtraining.com.

Documentation Feedback
You are encouraged to provide feedback and suggestions so that we can enhance the documentation. You can send email to the following alias or aliases, as appropriate. In the subject line, specify Documentation Feedback. Be sure to include the document name, page number, and product release version. For NetScaler documentation, send email to nsdocs_feedback@citrix.com. For Command Center documentation, send email to ccdocs_feedback@citrix.com. For Access Gateway documentation, send email to agdocs_feedback@citrix.com.

vi

Citrix NetScaler Administration Guide

You can also provide feedback from the Knowledge Center at http:// support.citrix.com/.
To provide feedback from the Knowledge Center home page

1. 2.

Go to the Knowledge Center home page at http://support.citrix.com/. On the Knowledge Center home page, under Products, click NetScaler Application Delivery, and click NetScaler Application Delivery Software 9.1. On the Documentation tab, click the guide name, and then click Article Feedback. On the Documentation Feedback page, complete the form, and then click Submit.

3. 4.

C HAPTER 1

Citrix NetScaler Authentication and Authorization

NetScaler authentication and authorization functions are of two basic types.The users and groups functions allow you to define who has access to the NetScaler. Command policies allow you to define what parts of the NetScaler configuration a user or group is permitted to access and modify. In other words, command policies regulate which commands, command groups, and other elements NetScaler users and groups are permitted to use. To configure authentication and authorization, you first define the users who have access to the NetScaler. After you have defined the users, you can organize them into groups. You then configure command policies to define the types of access, and assign the policies to users and/or groups. In This Chapter Defining Users Defining Groups Command Policies Resetting the Default Administrator (nsroot) Password Examples of User Scenarios

Defining Users
Once you have changed the default password, no user can access the NetScaler until you create an account for that user. After you have defined your users by creating accounts for them, you might have to change passwords or remove user accounts.

Citrix NetScaler Administration Guide

Creating a User Account


To create a user account, you simply assign a user name and password. You use the parameters described in the following table.

Parameter User Name Password

Specifies Name that the user enters to request access. Password that the user enters to request access.

To create a user account, use either of the following procedures.


To add a user account using the configuration utility

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

In the navigation pane, expand System and click Users. On the System Users page, Click Add. In the Create System User dialog box, in the User Name text box, type a name for the user (for example, johnd). In the Password text box, type a password to assign to the user. In the Confirm Password text box, again type the password that you have typed in the Password text box. Click Create and click Close.

To add a user account using the NetScaler command line

At the NetScaler command prompt, type:


add system user userName

Example
add system user johnd

Changing a User Password


The following table describes the parameter you set to change a user password on the NetScaler.

Parameter Password

Specifies The password you assign for the user account.

Chapter 1

Citrix NetScaler Authentication and Authorization

To change a user password, use either of the following procedures.


To change the user password using the configuration utility

1. 2. 3. 4. 5.

In the navigation pane, expand System and click Users. On the System Users page, select the user account for which you want to change the password (for example, johnd) and click Change Password. In the Password text box, type the new password. In the Confirm Password text box, type the new password again. Click OK.

To change the user password using the NetScaler command line

At the NetScaler command prompt, type:


set system user userName newpassword

Example
set system user johnd johnd1

Removing User Accounts


You can remove user accounts if the policy assigned to your account allows you to do so, or if you log in to the nsroot account. The nsroot account cannot be removed. To remove a user account, use either of the following procedures.
To remove a user account using the configuration utility

1. 2. 3. 4.

In the navigation pane, expand System and click Users. On the System Users page, select the user account that you want to remove. For example, johnd. Click Remove. The Remove pop-up window appears. Click Yes.

To remove a user using the NetScaler command line

At the NetScaler command prompt, type:


rm system user userName

Example
rm system user johnd

Citrix NetScaler Administration Guide

Defining Groups
To define a group, you first create the group, then bind users to the group.

Adding Groups
The following table describes the parameter you set to create a group.

Parameter Group Name

Specifies Name for the group of NetScaler users..

Use either of the following procedures to add a group.


To add a group using the configuration utility

1. 2. 3. 4.

In the navigation pane, expand System and click Groups. On the System Groups page, click Add. In the Create System Group dialog box, in the Group Name text box, type a name for the group (for example, Managers). Click Create, and click Close.

To add a group using the NetScaler command line

At the NetScaler command prompt, type:


add system group groupName

Example
add system group

Managers

Binding a User to a Group


You can bind each user account to more than one group. Binding user accounts to multiple groups may allow more flexibility when applying command policies. The following table describes the parameter you set to bind a user to a group.

Parameter User Name

Specifies Name for the NetScaler user to be bound to the group.

To bind a user to a group, use either of the following procedures.

Chapter 1

Citrix NetScaler Authentication and Authorization

To bind a user to a group using the configuration utility

1. 2. 3.

In the navigation pane, expand System and click Groups. On the System Groups page, select a group and click Open. In the Configure System Group dialog box, under Members section, select a user you want to bind to the group, from the Available Users list and click Add.

To bind a user to a group using the NetScaler command line

At the NetScaler command prompt, type:


bind system group groupName userName

Example
bind system group Managers johnd

Removing Groups
All the users and command policies that are currently bound to the group should be unbound before removing a group.
To remove a group using the configuration utility

1. 2. 3. 4.

In the navigation pane, expand System and click Groups. On the System Groups page, select the group that you want to remove. (for example, Managers). Click Remove. In the Remove pop-up, click Yes.

To remove a group using the NetScaler command line


rm system group groupName

Example
rm system group Managers

Command Policies
Command policies regulate which commands, command groups, vservers, and other elements NetScaler users and user groups are permitted to use. The NetScaler provides a set of built-in command policies, and you can configure custom policies. To apply the policies, you bind them to user and/or groups.

Citrix NetScaler Administration Guide

Here are the key points to keep in mind when defining and applying command policies. No global command policies may be created on the NetScaler. Command policies must be bound directly to NetScaler users and groups. Users or groups with no associated command policies are subject to the default DENY -ALL command policy, and will therefore be unable to execute any commands until the proper command policies are bound their accounts. All users inherit the policies of the groups to which they belong. You must assign a priority to a command policy when you bind it to a user account or group account. This enables the NetScaler to determine which policy has priority when two or more conflicting policies apply to the same user or group. The following commands are available by default to any any user and are unaffected by any command policies you specify: help cli, show cli attribute, clear cli prompt, alias, unalias, batch, source, help, history, man, quit, exit, whoami, config, set cli mode, unset cli mode, show cli mode, set cli prompt, and show cli prompt.

Built-in Command Policies


Four default command policies are available on the NetScaler. The following table describes them.

Policy Name

Allows Read-only access to all show commands except show runningconfig, show ns.conf, and the show commands for the NetScaler command group. Read-only access and access to commands to enable and disable services and servers or place them in ACCESSDOWN mode. Full access except to NetScaler commands, the shell command, and the show ns.conf and sh runningconfig commands. Full access. Same privileges as the nsroot user.

read-only

operator network superuser

Chapter 1

Citrix NetScaler Authentication and Authorization

Creating Custom Command Policies


Regular expression support is offered for users with the resources to maintain more customized expressions and those deployments that require the flexibility that regular expressions offer. For most users, the built-in command policies should be sufficient. Users who need additional levels of control, but are unfamiliar with regular expressions, may want to use only simple expressions, such as those in the examples provided in this section, to maintain policy readability. When you use a regular expression to create a command policy, keep the following in mind. When you use regular expressions to define commands that will be affected by a command policy, you must enclose the commands in double quotes. For example, if you want to create a command policy named allowShow that includes all commands that begin with show, you should type the following:
^show .*$

If you want to create a command policy that includes all commands that being with rm, you should type the following:
DENY ^rm .*$

Regular expressions used in command policies are case insensitive.

The following table gives examples of regular expressions:

Command Specification
^rm\s+.*$

Matches these Commands All remove actions, because all remove actions begin with the rm string, followed by a space and additional parameters and flags. All show commands, because all show actions begin with the show string, followed by a space and additional parameters and flags. The shell command alone, but not combined with any other parameters or flags. All create a vserver actions, which consist of the add vserver command followed by a space and additional parameters and flags.

^show\s+.*$

^shell$ ^add\s+vserver\s+.*$

^add\s+(lb\s+vserver)\s+ All create an lb vserver actions, which consist of the add lb vserver command followed by a space and .*

additional parameters and flags.


^set\s+lb\s+.*$

All commands that configure load balancing settings at the command group level.

Citrix NetScaler Administration Guide

The following table shows the command specifications for each of the built-in command policies:

Policy Name read-only operator

Command Specification Regular Expression


(^man.*)|(^show\s+(?!system)(?!ns ns.conf)(?!ns runningConfig).*)|(^stat.*) (^man.*)|(^show\s+(?!system)(?!ns ns.conf)(?!ns runningConfig).*)|(^stat.*)|(^set.*accessdown.*)|(^(enable|disable) (server|service).*) ^(?!shell)\S+\s+(?!system)(?!ns ns.conf)(?!ns runningConfig).* .*

network superuser

The following table describes the parameters you set to create a command policy.

Parameter User Name Command Spec Action

Specifies Name of the command policy. Rule expression that the policy uses to pattern match. The action the policy need to apply when the command specification pattern matches. Possible values: ALLOW and DENY

To create a command policy, use either of the following procedures.


To create a command policy using the configuration utility

1. 2. 3. 4. 5.

In the navigation pane, expand System and click Command Policies. On the Command Policies page, click Add. In the Create Command Policy dialog box, in the Policy Name text box, type a name for the command policy (for example, read_all). In the Action list, select the action (for example, Allow). In the Command Spec text box, enter a command, such as (^show\s+(?!system)(?!ns ns.conf)(?!ns runningConfig).*)|(^stat.*) (you can use the Policy Components to expedite entry). Click Create.

6.

Chapter 1

Citrix NetScaler Authentication and Authorization

To create a command policy using the NetScaler command line

At the NetScaler command prompt, type:


add system cmdPolicy policyname action cmdspec

Example
add system cmdPolicy read_all ALLOW (^show\s+(?!system)(?!ns ns.conf)(?!ns runningConfig).*)|(^stat.*)

Binding Command Policies to Users and Groups


Once you have defined your command policies, you must bind them to the appropriate user accounts and groups. When you bind a policy, you must assign it a priority so that the NetScaler can determine which command policy to follow when two or more applicable command policies are in conflict. The order in which command policies are evaluated is: Command policies bound directly to users and the corresponding groups are evaluated based on the priority number. A command policy with a lower priority number is evaluated before one with a higher priority number. Therefore, any privileges the lower-numbered command policy explicitly grants or denies are not overridden by a higher-numbered command policy. When two command policies one bound to an user account and other bound to a group have the same priority number then the command policy bound directly to the user account is evaluated first.

Binding Command Policies to a user


The following table describes the parameters you set to bind command policies to a user.

Parameter User Name Policy Name

Specifies The user account Name of the command policy bind to the user.

To bind a policy to a user, use either of the following procedures.


To bind command policies to a user using the configuration utility

1. 2.

In the navigation pane, expand System and click Users. On the System Users page, select a user (for example, johnd)

10

Citrix NetScaler Administration Guide

3. 4.

Click Open. In the Configure System User dialog box, under Command Policies, in the Active column, select one or more check boxes for policies to bind to this user. In the Priority list box, for each active policy, enter a priority number for the policy (for example, 1), or adjust the number. Click OK.

5. 6.

To bind command policies to a user using the NetScaler command line

At the NetScaler command prompt, type:


bind system user userName policyName priority

Example
bind system user johnd johnd_pol 1

Binding Command Policies to a Group


The following table describes the parameters you set to bind a policy to a

group.
Parameter Group Name Policy Name Specifies Name of the group. Name of the command policy to bind to the user group.

To bind command policies to a group, use either of the following procedures


To bind command policies to a group using the configuration utility

1. 2. 3. 4.

In the navigation pane, expand System and click Groups. On the System Groups page, select a group (for example, Managers) Click Open. In the Configure System Group dialog box, under Command Policies, in the Active column, select one or more check boxes for policies to bind to this group. In the Priority list box, for each active policy, enter a priority number for the policy (for example, 2), or adjust the number. Click OK.

5. 6.

Chapter 1

Citrix NetScaler Authentication and Authorization

11

To bind command policies to a group using the NetScaler command line

At the NetScaler command prompt, type:


bind system group groupName -policyName policyName priority

Example
bind system group Managers -policyName Managers_pol 2

Removing Command Policies


The built-in command policies cannot be removed. If your user account is assigned the right to remove a command policy, you can use either of the following procedures to remove command policies.
To remove a command policy using the configuration utility

1. 2. 3. 4.

In the navigation pane, expand System and click Command Policies. On the Command Policies page, select the command policy to be removed (for example, Managers_pol). Click Remove. In the Remove pop-up window, click Yes.

To remove a comand policy using the NetScaler command line

At the NetScaler command prompt, type:


rm system cmdPolicy PolicyName

Example
rm system cmdPolicy Managers_pol

Resetting the Default Administrator (nsroot) Password


The nsroot account provides complete access to all features of the NetScaler. Therefore, to preserve security, the nsroot account should be used only when necessary, and only individuals whose duties require full access should know the nsroot account password. Also for security, it is advisable to change the nsroot password frequently. If you lose the password, you can reset it as described here. To reset the nsroot password, you must boot the NetScaler into single user mode, mount the file systems in read/write mode, and remove the set NetScaler user nsroot entry from the ns.conf file. This process does not actually recover your nsroot password, but it does allow you to reset it to the default setting, nsroot. You can then choose a new password. Use the following procedure.

12

Citrix NetScaler Administration Guide To reset the nsroot password

1.

Connect a computer to the NetScaler serial port and log on.

Note: You cannot log on via ssh to perform this procedure; you must connect directly to the NetScaler. As the operating system starts, it displays the following message: Hit [Enter] to boot immediately, or any other key for command prompt. Booting [kernel] in # seconds. 2. Press CTRL+C. The following message appears: Type ? for a list of commands, help for more detailed help. ok 3. Type boot -s, and press the Enter key to start the NetScaler in single user mode. After the NetScaler boots, it displays the following message: Enter full pathname of shell or RETURN for /bin/sh: 4. Press the Enter key to display the # prompt, and type the following commands to mount the file systems: fsck /dev/ad0s1a mount /dev/ad0s1a /flash Using a text editor of your choice, edit the /flash/nsconfig/ ns.conf file and remove the set system user nsroot entry. Save the file and exit the text editor. Type reboot and press the Enter key to reboot the NetScaler. When the NetScaler completes rebooting, it prompts for username and password. 8. Log on as nsroot, with the password nsroot. Once logged in to the NetScaler, you will be required to enter a new nsroot user password. 9. 10. Follow the prompts to change the password. Exit the config ns menu.

5. 6. 7.

Chapter 1

Citrix NetScaler Authentication and Authorization

13

Examples of User Scenarios


The following example shows how to create a complete set of user accounts, groups, and command policies and bind each policy to the appropriate groups and users. The company, Example Manufacturing, Inc., has three users who will access the NetScaler: John Doe. The IT manager. John needs to be able to see all parts of the NetScaler configuration but does not need to modify anything. Maria Ramirez. The lead IT administrator. Maria needs to be able to see and modify all parts of the NetScaler configuration except for NetScaler commands (which local policy dictates must be performed while logged on as nsroot). Michael Baldrock. The IT administrator in charge of load balancing. Michael needs to be able to see all parts of the NetScaler configuration, but needs to modify only the load balancing functions.

The following table shows the breakdown of network information, user account names, group names, and command policies for the sample company:

Field NetScaler hostname User accounts

Value ns01.example.net johnd mariar michaelb Managers SysOps read_all modify_lb modify_all

Note

John Doe, IT manager Maria Ramirez, IT administrator Michael Baldrock, IT administrator All managers All IT administrators Allow complete read-only access Allow modify access to load balancing Allow nearly complete modify access

Groups Command Policies

The following description walks you through the process of creating a complete set of user accounts, groups, and command policies on the NetScaler ns01.example.net. The description includes procedures for binding the appropriate user accounts and groups to one another, and binding appropriate command policies to the user accounts and groups. This example illustrates how you can use prioritization to grant precise access and privileges to each user in the IT department.

14

Citrix NetScaler Administration Guide

The example assumes that initial installation and configuration have already been performed on the NetScaler.
To create johnd, mariar, and michaelb user accounts

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

In the navigation pane, expand System and click Users. On the System Users page, Click Add. In the Create System User dialog box, in the User Name text box, type johnd. In the Password text box, type a password to assign to the user. In the Confirm Password text box, again type the password that you have typed in the Password text box. Click Create. Repeat steps 26 to create user accounts and passwords for Maria Ramirez and Michael Baldrock.

To create groups Managers and SysOps

1. 2. 3. 4. 5.

In the navigation pane, expand System and click Groups. On the System Groups page, click Add. In the Create System Group dialog box, in the Group Name text box, type Managers. Click Create, and click Close. Repeat steps 14 to create a group named SysOps.

To bind users to a group

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

In the navigation pane, expand System and click Groups. On System Groups page, select the Managers group and click Open. In the Configure System Group dialog box, under Members, select johnd in the Available Users list. Click Add to move johnd to the Configured Users list. Click OK, and click Close. Repeat steps 14 to bind users mariar and michaelb to the group SysOps.

To add command policies

1. 2.

In the navigation pane, expand System and click Command Policies. On the Command Policies page, click Add.

Chapter 1

Citrix NetScaler Authentication and Authorization

15

3. 4. 5.

In the Create Command Policy dialog box, in the Policy Name text box, type read_all. In the Action list, select Allow. In the Command Spec text box, enter (^show\s+(?!system)(?!ns ns.conf)(?!ns runningConfig).*)|(^stat.*) (you can use the Policy Components to expedite entry). Click Create. Repeat steps 16, to create a command policy named modify_lb with action as Allow and the command spec ^set\s+lb\s+.*$ Repeat steps 16, to create a command policy named modify_all with action as Allow and the command spec ^\S+\s+(?!system).*

6. 7. 8.

To bind a command policy to a group

1. 2. 3. 4.

In the navigation pane, expand System and click Groups. On the System Groups page, select the Managers group. Click Open. In the Configure System Group dialog box, under Command Policies, in the Active column, select the read_all policy and change the Priority list box to 1. Click OK. Repeat steps 15 to bind the read_all command policy to the SysOps group, also assigning it a priority of 1.

5. 6.

To bind a command policy to a user

1. 2. 3. 4.

In the navigation pane, expand System and click Users. On the System Users page, select the michaelb user account. Click Open. In the Configure System User dialog box, under Command Policies, in the Active column, select the modify_lb policy and change the Priority list box to 5. Click OK.

5.

The configuration you've just created results in the following: John Doe, the IT manager, has read-only access to the entire NetScaler, but cannot make modifications.

16

Citrix NetScaler Administration Guide

Maria Ramirez, the IT lead, has near-complete access to all areas of the NetScaler configuration, having to log on only to perform NetScaler-level commands. Michael Baldrock, the IT administrator responsible for load balancing, has read-only access to the NetScaler configuration, and can modify the configuration options for load balancing.

As mentioned earlier, the set of command policies that applies to a specific user is a combination of command policies applied directly to the user's account and command policies applied to the group(s) of which the user is a member. Each time a user enters a command, the operating system searches the command policies for that user until it finds a policy with an explicit ALLOW or DENY action that matches the command. When it finds a match, the operating system stops its command policy search and allows or denies access to the command. If the operating system finds no matching command policy, it denies the user access to the command, in accordance with the NetScalers default deny policy. Note: When placing a user into multiple groups, take care not to cause unintended user command restrictions or privileges. To avoid these conflicts, when organizing your users in groups, it's good to bear in mind the NetScaler's command policy search procedure and policy ordering rules.

C HAPTER 2

SNMP

The NetScaler supports Simple Network Management Protocol (SNMP) functionality, as illustrated in the following diagram. This diagram shows a network with a NetScaler that has SNMP enabled and configured. In the diagram, each SNMP network management application uses SNMP to communicate with the SNMP agent on the NetScaler. The SNMP agent searches its management information base ( MIB) to collect the data requested by the network management application, and provides the information to the application.

NetScaler Supporting SNMP

18

Citrix NetScaler Administration Guide

The SNMP agent on the NetScaler supports SNMP version 1 (SNMPv1), SNMP version 2 (SNMPv2), and SNMP version 3 (SNMPv3). The SNMP agent handles queries, such as SNMPv2 Get-Bulk, from the SNMP manager. The SNMP agent also sends out traps compliant with SNMPv2. It also supports SNMPv2 datatypes, such as counter64. In This Chapter Importing MIB Files Defining SNMP Managers Configuring SNMP V1 and V2 Configuring SNMP V3

Importing MIB Files


SNMPv1 managers (programs on computers that request SNMP information from the NetScaler) use the NS-MIB-smiv1.mib file when processing SNMP queries. SNMPv2 and SNMPv3 managers use the NS-MIB-smiv2.mib file. The NetScaler supports enterprise-specific MIBs. They are: A subset of standard MIB-2 groups. Provides the MIB-2 groups SYSTEM, IF, ICMP, UDP, and SNMP. A NetScaler enterprise MIB. Provides NetScaler-specific configuration and statistics.

Before you start configuring SNMP, you must import the appropriate SNMP MIB files to the network management application, as follows: If the HP OpenView SNMP manager is installed on your computer, copy the NS-MIB-smiv2.mib file from the NetScaler Product CD, /Utilities/ SNMP/HP_OpenView directory, or download it from the FTP site ftp.netscaler.com. If the WhatsUpGold SNMP manager is installed on your computer, copy the traps.txt and mib.txt files from the NetScaler Product CD, /Utilities/ SNMP/WhatsUpGold directory, or download it from the FTP site ftp.netscaler.com.

Note: For information about the user name and password used to connect to the FTP site, contact the NetScaler product support group.

Chapter 2

SNMP

19

Defining SNMP Managers


You need to configure the management application, which complies with SNMP version1, SNMP version 2, or SNMP version 3, to access the NetScaler. You can add upto a maximum of 100 SNMP manager or networks. Note: If you do not configure at least one SNMP manager, the NetScaler accepts and responds to SNMP queries from all IPs on the network. If you configure one or more SNMP managers, it accepts and responds only to SNMP queries from those specific IPs.

Adding an SNMP Manager


The following table describes the parameters you set to add an SNMP Manager:

Parameter IP Address

Specifies IP/Network address of the management station. Subnet of management stations. Used to grant access from entire subnets to the NetScaler.

Netmask

To add an SNMP manager, use either of the following procedures:


To add an SNMP manager using the configuration utility

1. 2. 3.

In the navigation pane, expand System, click SNMP, and click Managers. In the Add SNMP Manager dialog box, click Add. In the Create Manager dialog box, in the IP Address text box, type the IP address of the computer running the management application (for example, 10.102.29.5). Click Add.

4.

To add an SNMP manager using the NetScaler command line

At the NetScaler command prompt, type:


add snmp manager IPaddress

Example
add snmp manager 10.102.29.5

20

Citrix NetScaler Administration Guide

Removing SNMP Managers


When you remove a SNMP manager from the NetScaler, that manager can no longer query the NetScaler. Note: If there is no SNMP manager configured on the NetScaler, network management applications from any host computer can access the NetScaler. To remove an SNMP manager, use either of the following procedures:
To remove an SNMP manager using the configuration utility

1. 2. 3. 4.

In the navigation pane, expand System, click SNMP, and then click Managers. On the SNMP Managers page, select the manager which you want to remove. Click Remove. In the Remove dialog box, click Yes.

To remove an SNMP manager using the NetScaler command line

At the NetScaler command prompt, type:


rm snmp manager IPAddress

Example
rm snmp manager

10.102.29.5

Configuring SNMP V1 and V2


Before you can use SNMP in the NetScaler, you must configure the NetScaler to allow the appropriate SNMP managers to access it. You must also provide the SNMP manager with the required NetScaler-specific information. The configuration process consists of the following tasks: Set the SNMP community, which defines access privileges (Read operation). Set traps and alarms to send SNMP trap notifications to the SNMP manager for any asynchronous events generated by the agent to indicate the state of the NetScaler.

Chapter 2

SNMP

21

Adding an SNMP Community


You add an SNMP community string to grant access to an SNMP network management application to manage the NetScaler. The community also defines the specific management tasks that you can perform.
The following table describes the parameters you set to add an SNMP community:

Parameter

Specifies SNMP community string.

Community Name Permissions

Access privileges. Possible values: GET, GET NEXT, GET BULK, ALL.

To add an SNMP community string

1. 2. 3. 4. 5.

In the navigation pane, expand System, click SNMP, and then click Community. On the SNMP Community page, click Add. In the Add SNMP Community dialog box, in the Community String text box, type a name for the community to be added (for example, Com_All). In Permission, select the ALL option. Click Create.

Removing an SNMP Community


When you remove a community string, no SNMP managers can use this community string to manage or access the NetScaler. To remove a community string, use either of the following procedures:
To remove an SNMP community string

1. 2. 3. 4.

In the navigation pane, expand System, click SNMP, and then click Community. On the SNMP Community page, select the community that you want to remove (for example, Com_All). Click Remove. In the Remove dialog box, click Yes.

22

Citrix NetScaler Administration Guide

Configuring SNMP Traps and Alarms


In addition to providing information in response to specific requests, the NetScaler can display an alarm, or notification message, in a window on a designated computer or computers whenever a particular type of event occurs. This type of notification is called an SNMP trap, and it helps administrators monitor the NetScaler and respond promptly to any issues.s SNMP traps are asynchronous events generated by the agent to indicate the state of the NetScaler. The trap listener receives traps on the trap destination port. If this port is not configured correctly, the traps do not reach the SNMP manager. You can configure the NetScaler to send traps to the SNMP manager when specific events generate alarms at specific severity levels. There are 5 severity levels: Critical, Major, Minor, Warning, and Informational. You can configure the NetScaler to send SNMP traps with source IP other than the NSIP. You can set the source IP of an SNMP trap to either a MIP or a SNIP. The NetScaler supports four types of generic SNMP traps and 65 types of enterprise-specific traps. You can specify maximum of five IP addresses as destinations for either type. If more than 10 authentication traps messages are generated within 20 seconds, no traps messages will be generated for the next 60 seconds. The following table describes the generic traps that the NetScaler supports.

Generic trap authenticationFailure coldStart linkUp

Indicates An SNMP management application without access privileges has attempted to access the NetScaler. An SNMP entity configured as an agent has reinitialized itself. Its configuration may have been altered. The sending protocol entity recognizes that one of the communication links represented in the agent's configuration has come up. The sending protocol entity recognizes a failure in one of the communication links represented in the agent's configuration.

linkDown

The following table describes the specific SNMP traps that the NetScaler supports.

Specific trap averageCpuUtilization

Indicates Average CPU usage in the multi-processor NetScaler has exceeded the high threshold.

Chapter 2

SNMP

23

Specific trap averageCpuUtilizationNormal

Indicates Average CPU usage in the multi-processor NetScaler has come back to normal after exceeding the predefined threshold . The NetScaler has become the primary node in a High Availability configuration. The NetScaler has become the secondary node in a High Availability configuration. CPU utilization has exceeded the threshold. CPU utilization has returned to normal after exceeding the threshold and generating a cpuUtilization trap. Disk usage has exceeded the threshold. Disk usage has returned to normal. State of the interface, vserver, or physical service has changed to UP. State of the interface, vserver, or physical service has changed to DOWN. A fan speed has fallen below an alarm threshold. Note: Fan speed varies from 4000 through 6500 on all platforms. An alarm threshold of 25% of the minimum is recommended.

changeToPrimary changeToSecondary cpuUtilization cpuUtilizationNormal

diskUsageHigh diskUsageNormal entityup entitydown fanSpeedLow

fanSpeedNormal interfaceThroughputLow interfaceThroughputNormal maxClients maxClientsNormal

A fan speed has returned to normal. Interface throughput has fallen below an alarm threshold. Interface throughput has returned to normal. Number of clients for a service has reached the maximum allowed for that service. Number of clients for a service has fallen below 70% of maximum number allowed for that service, after causing a maxClient trap. Memory utilization has exceeded the predefined threshold. Memory utilization has returned to normal after a memoryUtilization trap. Response time for a monitor probe has exceeded the configured threshold.

memoryUtilization memoryUtilizationNormal monRespTimeoutAboveThresh

24

Citrix NetScaler Administration Guide

Specific trap monRespTimeoutBelowThresh

Indicates Response time for a monitor probe is below the threshold, indicating that response time has returned to normal. A user 's atempt to log in to the NetScaler has failed. Your NetScaler configuration has changed. Note: This trap is not generated when the configuration is restored from the ns.conf file.

netscalerLoginFailure NetScalerConfigChange

netScalerConfigSave serviceRequestRate serviceRequestRateNormal serviceRxBytesRate serviceRxBytesRateNormal serviceTxBytesRate serviceTxBytesRateNormal serviceSynfloodRate serviceSynfloodNormal sslCertificateExpiry svcGrpMemberRequestRate svcGrpMemberRequestRateNormal svcGrpMemberRxBytesRate svcGrpMemberRxBytesRateNormal svcGrpMemberTxBytesRate

The NetScaler configuration has been saved. Request rate on a service has exceeded the threshold. Request rate on a service has returned to normal. Request bytes/s of a service has exceeded a threshold value. Request bytes/s of a service has returned to normal. Response bytes/s of a service exceeded a threshold value. Response bytes/s of a service has returned to normal. The number of unacknowledged syns for a service has exceeded a threshold value. The number of unacknowledged syns for a service has returned to normal. A SSL certificate is due to expire. Request rate on a service group member has exceeded a threshold value. Request rate on a service group member has returned to normal. Request bytes per second of a service group has exceeded a threshold value. Request bytes per second of a service group has returned to normal. Response bytes per second of a service group has exceeded a threshold value.

Chapter 2

SNMP

25

Specific trap svcGrpMemberTxBytesRateNormal svcGrpMemberSynfloodRate svcGrpMemberSynfloodNormal svcGrpMemberMaxClients svcGrpMemberMaxClientsNormal synflood synfloodNormal temperatureHigh temperatureNormal vServerRequestRate vServerRequestRateNormal vserverRxBytesRate vserverRxBytesRateNormal vserverTxBytesRate vserverTxBytesRateNormal vserverSynfloodRate vserverSynfloodNormal voltageLow voltageNormal

Indicates Response bytes per second of a service group has returned to normal. Number of unacknowledged SYN packets for a service group has exceeded a threshold value. Number of unacknowledged SYN packets for a service group has returned to normal. Number of clients has reached the maxClients value for a service group member. Number of clients has fallen below 70% of maxClients value for a service group member. Rate at which unacknowledged SYN packets are received has exceeded the threshold. Rate at which unacknowledged SYN packets are received has returned to normal. Temperature has gone high. The temperature is measured in degree centigrade (0C). Temperature has returned to normal. Request rate on a vserver has exceeded the predefined threshold. Request rate on a vserver has returned to normal. Request bytes/s of a vserver has exceeded the threshold value. Request bytes/s of a vServer has returned to normal. Response bytes/s of a vserver has exceeded a threshold value. Response bytes/s of a vServer has returned to normal. Number of unacknowledged syns for a vserver has exceeded a threshold value. Number of unacknowledged syns for a vserver has returned to normal. A voltage has fallen below the threshold value. A voltage has returned to normal.

26

Citrix NetScaler Administration Guide

Specific trap voltageHigh

Indicates A voltage has exceeded the threshold value. Note: The three traps voltageLow, voltageNormal, and voltageHigh are based on v33main and v33stby (mV). The normal value ranges from 2970mV through 3630mV.

haVersionMismatch haSyncFailure haNoHeartbeats haBadSecState powerSupplyFailed powerSupplyNormal interfaceBWUseHigh interfaceBWUseNormal aggregateBWUseHigh aggregateBWUseNormal

OS versions of the NetScalers in a High Availability configuration do not match. Configuration synchronization has failed on secondary node. High Availability heartbeats are not received by the primary node from the secondary. State of the secondary node has changed to DOWN, UNKNOWN, or STAY SECONDARY . Power supply has failed. The power supply has returned to service. Bandwidth usage of any of the interfaces of the NetScaler has exceeded the threshold value. Bandwidth usage of any of the interfaces of the NetScaler has returned to normal Aggregate bandwidth usage of the NetScaler has exceeded the threshold value. Aggregate bandwidth usage of the NetScaler has returned to normal.

Note: SNMP manager to listen for traps with this community name. The default community name is public. The following table describes the parameters you set to add an SNMP trap:

Parameter Trap Class Version

Specifies The Trap type. Possible values: generic and specific. SNMP version of the trap PDU to be sent.

Chapter 2

SNMP

27

Parameter Destination IP Address Destination Port Source IP Address Severity

Specifies IP address of the trap destination. Destination port of the trap. Default: 162. Minimum value: 1 Source IP of the traps. Minimum severity of the alarm resulting in this trap. Default: Informational (any alarm). The community string. Default: public.

Community Name

To add an SNMP Trap, use either of the following procedures:


To add an SNMP Trap using the configuration utility

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

In the navigation pane, expand System, click SNMP, and click Traps. On the Traps page, click Add. In Version, select an SNMP Version (for example, V1). In the Destination IP Address text box, type the IP address that is to receive the trap (for example, 10.102.29.3). In the Destination Port text box, type the destination port (for example, 163). In the Source IP text box, type the source IP address of the trap (for example, 10.102.29.54). In Minimum Severity, select a severity option (for example, Major). In the Community Name text box, type the name of the SNMP string that you want to include in the trap (for example, com1). Click Add.

To add an SNMP Trap using the NetScaler command line

At the NetScaler command prompt, type:


add snmp trap trapClass trapDestination -version ( V1 | V2 ) -destPort port -communityName string -srcIP ip_addr -severity severity

Example
add snmp trap specific 10.102.29.3 -version V2 -destPort 163 -communityName com1 -srcIP 10.102.29.54 -severity Major

28

Citrix NetScaler Administration Guide

Removing an SNMP Trap


When you remove a trap, trap messages are no longer sent to the destination specified. To remove an SNMP trap, use either of the following procedures:
To remove an SNMP trap

1. 2. 3. 4.

In the navigation pane, expand System, click SNMP, and then click Traps. On the SNMP Traps page, select the trap that you want to remove. Click Remove. In the Remove dialog box, click Yes.

Configuring SNMP Alarms


The NetScaler generates traps only for SNMP alarms that are enabled. Some alarms are enabled by default, but you can disable them. You can assign severity levels to alarms.

Enabling or Disabling an SNMP Alarm


When you enable a SNMP alarm, the NetScaler will generate corresponding trap messages when some events occur. Some NetScaler alarms are enabled by default.
To enable or disable an SNMP alarm

1. 2. 3.

In the navigation pane, expand System, expand SNMP, and click Alarms. On the SNMP Alarms page, select an alarm (for example, Login-Failure). To enable a disabled alarm, click Enable, or, to disable an enabled alarm, click Disable.

Setting the Severity of SNMP Alarms


There are 5 levels of severity for alarms: Critical, Major, Minor, Warning, and Informational. A trap is sent only when the severity of the alarm matches the severity configured in the trap. The following table describes the parameter you set to configure the severity of SNMP alarm:
Parameter Severity Specifies Severity level of this alarm. Possible values: Critical, Major, Minor, Warning, Informational. Default: Informational.

Chapter 2 To set the severity of SNMP alarm

SNMP

29

1. 2. 3. 4.

In the navigation pane, expand System, expand SNMP, and click Alarms. Click Open. In the Configure SNMP Alarm dialog box, in Severity, select a severity option (for example, Major). Click Ok.

Logging of SNMP Traps


The logging of trap messages is enabled by default. For alarms that need threshold values, however, the logging state is unknown. Once thresholds are configured, logging is automatically enabled. If logging of an alarm has been disabled, you can enable it by setting the parameter in the following table.:

Parameter Logging

Specifies Enable logging of SNMP trap messages by Syslog. Possible values : ENABLED and DISABLED.

The following procedure includes examples for enabling or modifying the logging of trap messages for the alarm LOGIN-FAILURE. When this alarm is enabled, a trap message is generated and sent to the trap destination whenever there is a login failure on the NetScaler. This message is logged.
To enable or disable logging of SNMP traps using configuration utility

1. 2. 3.

In the navigation pane, expand System, expand SNMP, and then click Alarms. Click Open. In the Configure SNMP Alarm dialog box, in Logging, select ENABLED to enable the logging of SNMP trap messages generated or select DISABLED to disable logging of SNMP trap messages. Click Ok.

4.

To enable or disable logging of SNMP traps using the NetScaler command line

At the NetScaler command prompt, type:


set snmp alarm AlarmType -logging Status

30

Citrix NetScaler Administration Guide Example


set snmp alarm LOGIN-FAILURE -logging ENABLED

or
set snmp alarm LOGIN-FAILURE -logging DISABLED

Configuring SNMP V3
Simple Network Management Protocol Version 3 (SNMPv3) is based on the basic structure and architecture of SNMPv1 and SNMPv2. However, SNMPv3 enhances the basic architecture to incorporate administration and security capabilities such as authentication, access control, data integrity check, data origin verification, message timeliness check, and data confidentiality.

Salient Features
SNMPv3 provides security features such as message-level security and access control. To implement these features, SNMPv3 introduces the user-based security model (USM) and the view-based access control model (VACM).

User-based Security Model


The user-based security model (USM) provides message-level security. It enables you to configure users and security parameters at the agent and the manager to ensure: Data integrity: To protect messages from being modified during transmission through the network. Data origin verification: To authenticate the user who sent the message request. Message timeliness: To protect against message delays or replays. Data confidentiality: To protect the content of messages from being disclosed to unauthorized entities or individuals.

View-Based Access Control Model


View-based access control model (VACM) enables you to configure access rights to a specific subtree of the MIB based on various parameters, such as security level, security model, user name, and view type. It enables you to configure agents to provide different levels of access to the MIB to different managers.

Chapter 2

SNMP

31

SNMPv3 Security Entities


The Citrix NetScaler supports the following entities that enable you to implement the security features of SNMPv3: SNMP Engines SNMP Views SNMP Groups SNMP Users

SNMP Engines
SNMP engines are service providers that reside in the SNMP agent. They provide services such as sending or receiving and authenticating messages. SNMP engines are uniquely identified using engine IDs.

SNMP Views
SNMP views restrict user access to specific portions of the MIB. SNMP views are used to implement access control.

SNMP Groups
SNMP groups are logical aggregations of SNMP users.They are used to implement access control and to define the security levels. You can configure an SNMP group to set access rights for users assigned to that group, thereby restricting the users to specific views.

SNMP Users
SNMP users are the SNMP managers that the agents allow to access the MIBs. Each SNMP user is assigned to an SNMP group. These entities function together to implement the SNMPv3 security features. Views are created to allow access to subtrees of the MIB. Then, groups are created with the required security level and access to the defined views. Finally, users are created and assigned to the groups. Note: The view, group, and user configuration are synchronized and propagated to the secondary node in an HA pair. However, the engineID is neither propagated nor synchronized as it is unique to each NetScaler.

Configuring SNMP V3
To implement message authentication and access control, you need to:

32

Citrix NetScaler Administration Guide

Set the Engine ID Configure Views Configure Groups Configure Users

Setting the Engine ID


An SNMP engine ID uniquely identifies an SNMP engine. The NetScaler has an unique engineID based on the MAC address of one of its interfaces. It is not necessary to override this engineID. However, if you want to change this engine ID, you can reset it. The following table describes the parameter you set to configure the Engine ID:

Parameter EngineID

Specifies Engine ID of the SNMP agent.

To set the engine ID, use either of the following procedures.


To set the engine ID using configuration utility

1. 2. 3. 4.

In the navigation pane, expand System, expand SNMP, and click Users. On the SNMP Users page, click Configure Engine ID. In the Configure Engine ID dialog box, in the Engine ID text box, type an engine ID (for example, 8000173f0300c095f80c68). Click OK.

To set the engine ID using the NetScaler command line

At the NetScaler command prompt, type:


set snmp engineId Value

Example
set snmp engineId 8000173f0300c095f80c68

Adding an SNMP View


You can use SNMP views to implement access control.

Chapter 2

SNMP

33

The following table describes the parameters you set to add an SNMP view:

Parameter Name Subtree

Specifies Name of the SNMP view. Subtree of the MIB.

To add an SNMP view, use either of the following procedures.


To add an SNMP view using the configuration utility

1. 2. 3. 4. 5.

In the Navigation Pane, expand System, expand SNMP, and click View. On the SNMP View page, click Add. In the Add SNMP View dialog box, in the Name text box, type a name for the SNMP view you want to add (for example, View1). In the Subtree text box, type the subtree of the MIB. Click Create.

To add an SNMP view using the NetScaler command line

At the NetScaler command prompt, type:


add snmp view Value

Example
add snmp view View1

Adding an SNMP Group


You need to configure an SNMP group to set access rights for users assigned to that group. The following table describes the parameters you set to add an SNMP group:

Parameter Name Read View

Specifies Name of the SNMP view. SNMP view to be associated with this group.

To add a SNMP group, use either of the following procedures:

34

Citrix NetScaler Administration Guide To add an SNMP group using the configuration utility

1. 2. 3. 4.

In the navigation pane, expand System, expand SNMP, and click Group. On the SNMP Groups page, click Add. In the Add SNMP Group dialog box, in the Name text box, type a name for the SNMP group you want to add (for example, Group1). Click Create and click Close.

To add an SNMP group using the NetScaler command line

At the NetScaler command prompt, type:


add snmp group group name

Example
add snmp group Group1

Adding an SNMP User


You need to configure users at the agent, and assign each user to a group. The following table describes the parameters you set to add an SNMP user:

Parameter Name Read View

Specifies Name of the SNMP user. SNMP view to be associated with this user.

To add a SNMP user, use either of the following procedures:


To add an SNMP user using the configuration utility

1. 2. 3. 4. 5.

In the navigation pane, expand System, click SNMP, and then click Users. On the SNMP Users page, click Add. In the Add SNMP User dialog box, in the Name text box, type a name for the SNMP user you want to add (for example, User1). In Group Name, select the configured SNMP group that you want the user to be part of. Click Create and click Close.

To add an SNMP user using the NetScaler command line

At the NetScaler command prompt, type:

Chapter 2

SNMP

35

add snmp user user name

Example
add snmp user User1

Note: The view, group, and user configurations are synchronized and propagated to the secondary node in an HA pair. However, the engineID is neither propagated nor synchronized, because it is unique to each NetScaler.

36

Citrix NetScaler Administration Guide

C HAPTER 3

Audit Server Logging

Auditing is a methodical examination or review of a condition or situation. The Audit Server Logging feature enables you to log the Citrix NetScaler states and status information collected by various modules in the kernel and in the user-level daemons. The audit server collects and stores the events history in a chronological order, so that you can review to troubleshoot problems or errors and fix them. When you configure audit server logging, you set up a log file to capture the NetScaler status information in the form of messages. These messages typically contain the following information: The source module that generates the message A time stamp The message type The predefined log levels (Critical, Error, Notice, Warning, Informational, Debug, Alert, and Emergency) The message information

To enable audit server logging, you must configure the auditing parameters on the NetScaler, set up and install the executable files on a computer from where you want to run the audit tool, and configure the parameters in the configuration file by defining the filters and filter parameters.The filters determine the type of information in the log files and the location at which to storethe files. In This Chapter Configuring the Citrix NetScaler Audit Server Log Installing the Audit Server Files Configuring Audit Server Logging on a Server system Configuring Audit Server Logging for a Commonly Used Deployment Scenario

38

Citrix NetScaler Administration Guide

Configuring the Citrix NetScaler Audit Server Log


You can configure the log settings in the Citrix NetScaler through the Graphical User Interface (GUI) or CLI. The Citrix NetScaler can also log the following information related to TCP connections: Source port Destination port Source IP Destination IP Number of bytes transmitted and received Time period for which the connection is open

Note: You can enable TCP logging on individual load balancing vservers. You must bind the audit log policy to a specific load balancing vserver that you want to log. To configure audit server logging, you must set the following parameters:

Parameter Auditing Type IP Address Port Log Levels

Specifies Type of audit to perform. Possible values: SYSLOG and NSLOG. IP address of the auditing server. Default: 0.0.0.0. Port to use to communicate. Default: 3023. Severity levels of messages to be logged. Possible values: ALL, NONE, or one or more of the following: EMERGENCY ALERT CRITICAL ERROR WARNING NOTICE INFORMATION DEBUG

For more information about these settings, see the table, , on page 39.
Date Format Format of the date stamp. Possible Values: MMDDYYYY and DDMMYYYY.

Chapter 3

Audit Server Logging

39

Parameter Log Facility

Specifies Log facility, as defined in RFC3164. Uses numerical codes 0 to 7 to indicate the type of message originating from the Netscaler (for example, NS and VPN). Possible values: LOCAL0 to LOCAL7. Default: LOCAL0. Time zone for the time stamp. Possible values: GMT and Local. Default: Local. Enable or disable logging of TCP events.

Time Zone TCP Logging

The following table describes the severity levels that you can set to specify when logging is to occur.

Level EMERGENCY ALERT

Specifies Log errors indicating that the NetScaler is experiencing a critical problem that may make the it unusable. Log problems that are not critical to current operations but that indicate a need for immediate corrective action to prevent a critical problem. Log critical conditions, which do not restrict current operations but may escalate to a larger problem. Log messages related to failed NetScaler operations. Log issues that may result in critical errors. Log the events specified by the INFORMATION setting, but in greater detail. Log all actions taken by the NetScaler. This level is useful for troubleshooting problems. Log extensive, detailed information to help developers troubleshoot problems.

CRITICAL ERROR WARNING NOTICE INFORMATION DEBUG

Configuring Global Audit Server Parameters


The global audit server parameters provide detailed control of the information to be logged, and you can specify the location at which the messages are stored. To configure the parameters, use the following procedure.
To configure global auditing parameters

1. 2.

In the Navigation Pane, expand System, and click the Auditing node. On the Auditing page, under Settings, click global auditing parameters.

40

Citrix NetScaler Administration Guide

3. 4.

In the Configure Auditing Parameters dialog box, in the Auditing Type drop-down list, select NSLOG. In the IP Address and Port text boxes, type the IP of the server for which you want to configure logging, and the port number to use; for example, 10.102.29.1, and 3023. The default port number is 3023. Under Log Levels, either select the ALL check box or select specific loglevel check boxes. Note: Selecting NONE disables all log levels. Use this option when you want to reset log levels.

5.

6.

In the Log Facility drop-down list, select a log facility option. Note: For more information about the log facility options, see the chapter Managing the Citrix NetScaler System.

7. 8.

Select a Date Format option and a Time Zone option. Click OK.

Configuring Audit Server Action and Policy


You can configure audit server actions for different servers and for different log levels.
To configure an auditing action

1. 2.

In the Navigation Pane, expand System, expand Auditing, and click Policies. On the Auditing Policies and Servers page, select the Servers tab and click Add. The Create Auditing Server dialog box appears. For descriptions of the parameters in this dialog box, see the table, , on page 38.

3.

In the Create Auditing Server dialog box, in the Name text box, type a name for the auditing server, and in the Auditing Type drop-down list, select NSLOG. In the IP Address and Port text boxes, type the IP address and the port number of the auditing server. The default port is 3023. Under Log Levels, select the ALL check box or select specific log-level check boxes.

4. 5.

Chapter 3

Audit Server Logging

41

6. 7. 8. 9.

In the Log Facility drop-down list, select a log facility. In TCP Logging, click the NONE or ALL option. Select a Date Format option and a Time Zone option for the time stamp. Click Create and click Close.

To configure an audit server policy

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

In the Navigation Pane, expand System, expand Auditing, and select Policies. On the Policies page, select the Policies tab, and click Add. In the Create Auditing Policy dialog box, in the Name text box, type a name for the policy (for example, nspol1). In the Auditing Type drop-down list, select NSLOG. In the Server drop-down list, select the server for which the policy applies. Click Create, and click Close. The policy appears on the Policies page.

Globally Binding the Audit Policies


You must globally bind the audit log policies to enable logging of all Citrix NetScaler System events. By defining the priority level, you can set the evaluation order of the audit server logging. Priority 0 is the highest and is evaluated first. The higher the priority number, the lower is the priority of evaluation.
To globally bind the audit policy

1. 2. 3.

In the Navigation Pane, expand System, expand Auditing, and click Policies. On the Policies page, in the Policies tab, click Global Bindings. In the Bind/Unbind Auditing Global Policies dialog box, in the Active column, select the check box next to the policy that you want to bind. (To unbind a policy, clear the check box.) In the Priority list box, enter or adjust the priority (for example, click the down arrow until 0 appears). Click OK.

4. 5.

42

Citrix NetScaler Administration Guide

Installing the Audit Server Files


This section describes the steps to install the audit server logging executable files on various operating systems. Copy the installation files from the product CD or download them from the site ftp.netscaler.com. Run the installations from the root user account. The following table lists the minimum system requirements for configuring external audit server logging for Windows, Linux, and FreeBSD:

Operating System Windows

Software Requirements Windows XP Professional - Version 2002 Windows 2003 server Windows 2000/NT Red Hat Enterprise Linux AS release 4 (Nahant) - Linux version 2.6.9-5.EL Red Hat 3.4.3-9.EL4 - Linux version 2.6.9-5.ELsmp Red Hat Linux 3.2.2-5 - Linux version 2.4.20-8 FreeBSD 4.9 Hardware Requirements

Linux

FreeBSD

For Windows / Linux / FreeBSD

Processor - Intel x86 ~501MHz RAM - 512 MB Controller - SCSI

Installing Audit Server on the Linux Operating System


The following section describes the procedure to install the audit server executable and other files on a system that runs Red Hat Linux.
To install on a Linux operating system

1.

At a command prompt, type the following command to copy the NSauditserver.rpm file to a temporary directory:
cp <path_to_cd>/Utilities/auditserver/Linux/NSauditserver.rpm /tmp

2.

Type the following command to install the NSauditserver.rpm file:


rpm -i NSauditserver.rpm

This command extracts the files and installs them in: /usr/local/netscaler/etc

Chapter 3

Audit Server Logging

43

/usr/local/netscaler/bin /usr/local/netscaler/samples

Uninstalling Audit Server on the Linux Operating System


This section describes the procedure to uninstall audit server logging on a server that runs on the Linux operating system.
To uninstall audit server logging

At a command prompt, type the following command to uninstall the audit server logging feature:
rpm -e NSauditserver

For more information about the NSauditserver RPM file, use the following command:
rpm -qpi *.rpm

To view the installed audit server files use the following command:
rpm -qpl *.rpm

*.rpm: Specifies the file name.

Installing Audit Server on the FreeBSD Operating System


This section describes the procedure to install the audit server executable and other files on the FreeBSD 4.4 operating system.
To install on a FreeBSD operating system

1.

Copy the NSauditserver.tgz file to a <target directory> using the command:


cp <path_to_cd>/Utilities/auditserver/Freebsd/ NSauditserver.tgz /<target directory>

<path_to_cd>: Specifies the system path to the CD drive where the CD device is mounted. <target directory>: Specifies the path to the directory to which the file should be copied. 2. 3. Change to the <target directory>:
cd /<target directory>

Use the following command to install the package:

44

Citrix NetScaler Administration Guide

pkg_add NSauditserver.tgz

This command extracts the files and installs them in: 4. /usr/local/netscaler/etc /usr/local/netscaler/bin /usr/local/netscaler/samples

At a command prompt, type the following command to check whether the package is installed:
pkg_info | grep NSauditserver

Uninstalling Audit Server on the FreeBSD Operating System


This section describes the procedure to uninstall audit server logging on a server that runs on the FreeBSD operating system.
To uninstall audit server logging

At a command prompt, type the following command to uninstall the audit server logging package:
pkg_delete NSauditserver

Installing Audit Server on the Windows Operating System


This section describes the procedure to install the audit server executable and other files on the Windows operating system.
To install on a Windows operating system

1.

Extract the audserver.exe file from the NSauditserver.zip compressed file into a temporary directory. When the files are extracted, the following directories are created: \NS\BIN \NS\ETC \NS\SAMPLES

2.

To install audit server logging as a service, run the following command from \NS\BIN directory:
audserver -install -f <directorypath> \auditlog.conf

Chapter 3

Audit Server Logging

45

<directorypath>: Specifies the path where the auditlog.conf file is available.

Uninstalling Audit Server on the Windows Operating System


This section describes the procedure to uninstall audit server logging on a server that runs on the Windows operating system.
To uninstall audit server logging

1. 2.

At a command prompt, change to the following directory:


cd \NS\BIN

Type the following command to uninstall the audit server logging feature:
audserver -remove

Note: To uninstall the audit server logging application, uninstall the auditserver service and remove the directory.

Audit Server Options


The following table describes the options you can use with the audserver command to configure audit server options.: Audit Server Options
Audit Server Commands
audserver -help audserver -addns -f <path to configuration file>

Specifies Lists all the available Audit Server options Specifies the system that gathers the log transaction data. On execution of the command, you are prompted to enter the IP address of the system. Enter the Userid and Password of the system. Note: Userid and password must be valid.

audserver -verify -f <path to configuration file>

Checks for syntax or semantic errors in the configuration file, for example, auditlog.conf file.

46

Citrix NetScaler Administration Guide

Audit Server Options


Audit Server Commands
audserver -start -f <path to configuration file>

Specifies Starts audit server logging based on the configuration settings in the configuration file, for example, auditlog.conf file. Linux only: To start the audit server as a background process, type & at the end of the command.

audserver -stop

Linux only: Stops audit server logging when audit server is started as a background process. Alternatively, use the Ctrl+C key to stop audit server logging.

audserver -install -f <path to configuration file>

Windows Only: Installs the audit server logging client as a service on Windows.

audserver -startservice Windows Only

Starts the audit server logging service, when you enter this command at a command prompt. You can also start audit server logging from Start > Control Panel > Services option. Note: Audit server logging starts by using the configuration settings in the configuration file, for example, auditlog.conf file specified in the audit server install option.
audserver -stopservice audserver -remove

Windows Only Removes the audit server logging service from the registry.

Run the audserver command from the directory in which the audit server executable is present: On Windows: \ns\bin On Solaris and Linux: \usr\local\netscaler\bin

The audit server configuration files are present in the following directories: On Windows: \ns\etc On Linux: \usr\local\netscaler\etc

The audit server executable is started as ./auditserver in Linux and FreeBSD.

Chapter 3

Audit Server Logging

47

Configuring Audit Server Logging on a Server system


Use the following process to configure audit server logging on the server computer, which can be running Windows, Linux, or FreeBSD. 1. 2. Install audit server logging as described in Installing the Audit Server Files, on page 42. Using a text editor, make the following changes in the auditlog.conf file: A. B. C. D. 3. Add the IP address of the audit server in the MYIP field. Define the log filters and log properties. Add the IP address of the Citrix NetScaler System. Verify the configuration.

Start audit server logging.

Note: You can configure the NetScaler to log integrated cache transactions using the audit server logging feature.

Defining Filters
Define filters in the configuration file (for example, auditlog.conf) to configure each Citrix NetScaler to log web transactions handled by the logging server. Define log properties for each filter. The filter applies these log properties to the transactions that match the filter definition. Note: A transaction is not recorded if a filter definition does not exist for a log transaction.

Defining Default Filters


To define the default filter, you can either use the filter in the sample configuration auditlog.conf file or modify it. Note: For consolidated logging, if a log transaction occurs for which there is no filter definition, the default filter is used (if it is enabled.) The only way you can configure consolidated logging of all the Citrix NetScaler Systems is by defining the default filter.

48

Citrix NetScaler Administration Guide

Creating Filters
To create a filter, type the following command in the auditlog.conf file:
filter <filterName> [IP <ip>] [NETMASK <mask>] [ON | OFF]

<filterName>, specify the name of the filter. (maximum of 64 alphanumeric characters) <ip>, specify the IP addresses <mask>, specify the subnet mask to be used on a subnet. Specify ON to enable the filter to log transactions, or specify OFF to disable the filter. If no argument is specified, the filter is ON. Examples
filter F1 IP 192.168.100.151 ON

To apply the filter F2 to IP addresses 192.250.100.1 to 192.250.100.254: filter F2 IP 192.250.100.0 NETMASK 255.255.255.0 ON Note: FilterName is a required parameter if you are defining a filter with other optional parameters such as IP address, or the combination of IP address and Netmask.

Defining Log Properties


Log properties associated with the filter are applied to all the log entries present in the filter. The log property definition starts with the key word BEGIN and ends with END as illustrated in the following example:
BEGIN <filtername> logFilenameFormat ... logDirectory ... logInterval ... logFileSize .... END

Entries in the definition can include the following: LogInterval specifies the interval at which new log files are created. Use one of the following values: Hourly - every hour Daily - every day at midnight Weekly - every Sunday at midnight

Chapter 3

Audit Server Logging

49

Monthly- the first day of the month at midnight None - only once, when audit server logging starts. Size - only when the log file size limit is reached.

By default the LogInterval property is set to Hourly. Example:


LogInterval Hourly

LogFileSizeLimit specifies the maximum size (in MB) of the log file. A new file is created when the limit is reached. Note that you can override the loginterval property by assigning size as its value. The default LogFileSizeLimit is 10 MB. Example:
LogFileSizeLimit 35

LogFilenameFormat specifies the file name format of the log file. The name of the file can be of the following types: Static: A constant string that specifies the absolute path and the file name. Dynamic: An expression that includes the following format specifiers: Date (%{format}t) % creates filename with NSIP

Note: For more information, see Checklist for Configuring Audit Server Logging, on page 53. Example:
LogFileNameFormat Ex%{%m%d%y}t.log

This creates the first file name as Exmmddyy.log. New files are named: Exmmddyy.log.0, Exmmddyy.log.1, and so on. In the following example, the new files are crated when the file size reaches 100MB. Example:
LogInterval size LogFileSize 100

50

Citrix NetScaler Administration Guide

LogFileNameFormat Ex%{%m%d%y}t

Caution: The date format %t specified in the LogFilenameFormat parameter overrides the log interval property for that filter. To prevent a new file being created every day instead of when the specified log file size is reached, do not use %t in the LogFilenameFormat parameter. logDirectory specifies the directory name format of the log file. The name of the file can be either of the following: Static: Is a constant string that specifies the absolute path and filename. Dynamic: Is an expression containing the following format specifiers: Date (%{format}t) % creates directory with NSIP

The directory separator depends on the operating system. In Windows, use the directory separator \. Example:
LogDirectory dir1\dir2\dir3

In the other operating systems (Linux, FreeBsd, Mac, etc.), use the directory separator /. Example:
LogDirectory dir1/dir2/dir3

Note: For more information, see Checklist for Configuring Audit Server Logging, on page 53.

Default Settings for the Log Properties


The following is an example of the default filter with default settings for the log properties:
begin default logInterval Hourly logFileSizeLimit 10 logFilenameFormat auditlog%{%y%m%d}t.log end default

Chapter 3

Audit Server Logging

51

Following are two examples of defining the default filters: Example 1:


Filter f1 IP 192.168.10.1

This creates a log file for NSIP 192.168.10.1 with the default values of the log in effect. Example 2:
Filter f1 IP 192.168.10.1 begin f1 logFilenameFormat logfiles.log end f1

This creates a log file for NSIP 192.168.10.1. Since the log file name format is specified, the default values of the other log properties are in effect.

Adding the IP Addresses of the System


In the configuration file, add the IP addresses of the system that performs the audit server logging and the Citrix NetScaler Systems whose events must be logged.
To add the IP addresses

1.

At a command prompt, type the following command:


audserver -addns -f <directorypath>\auditlog.conf

<directorypath> specifies the path to the configuration file (for example auditlog.conf.) You are prompted to enter the information for the following parameters: specifies the IP address of the Citrix NetScaler System, for example, 10.102.29.1.
NSIP Userid

specifies the username, for example, nsroot specifies the password, for example, nsroot.

Password

If you add multiple NetScaler IP addresses (NSIP), and later you do not want to log all of Citrix NetScaler System event details, you can delete the NSIPs manually by removing the NSIP statement at the end of the auditlog.conf file. During a failover setup, you must add both primary and secondary Citrix Netscaler IPs to auditlog.conf using the audserver command. Before adding the IP address, make sure the username and password exist on the system.

52

Citrix NetScaler Administration Guide

Verifying Configuration
Check the configuration file (auditlog.conf) for syntax correctness to enable logging to start and function correctly. To verify configuration, at a command prompt, type the following command:
audserver -verify -f <directorypath>\auditlog.conf

<directorypath> specifies the path where the configuration file (auditlog.conf)resides.

Starting Audit Server Logging


To start audit server logging, enter the following command at a command prompt:
audserver -start -f directorypath\auditlog.conf

<directorypath>: Specifies the path to the configuration file (auditlog.conf.)

Stopping Audit Server Logging


To stop audit server logging that starts as a background process in FreeBSD or Linux, use the following command:
audserver -stop

To stop audit server logging that starts as a service in Windows, use the following command:
audserver -stopservice

Sample Configuration File


Following is a sample configuration file:
############################## # This is the Auditserver configuration file # Only the default filter is active # Remove leading # to activate other filters ############################## MYIP <NSAuditserverIP> MYPORT 3023 # Filter filter_nsip filter on > ON # # begin filter_nsip logInterval Hourly IP <Specify the NetScaler IP address to

Chapter 3

Audit Server Logging

53

# # # #

logFileSizeLimit 10 logDirectory logdir\%A\ logFilenameFormat nsip%{%d%m%Y}t.log end filter_nsip

Filter default begin default logInterval Hourly logFileSizeLimit 10 logFilenameFormat auditlog%{%y%m%d}t.log end default

Checklist for Configuring Audit Server Logging


Use the following checklist when you configure audit server logging, and to troubleshoot problems: 1. 2. 3. Verify that the Citrix NetScaler System username and password are valid. If there is a firewall between the NetScaler and logging machine, make sure the RPC 3010/3011 port is open. Verify that the Citrix NetScaler is accessible from the log machine by doing the following: 4. 5. Ping the Citrix NetScaler IP address. Use FTP and Telnet to access the NetScaler.

Verify that the IP address of the system is present in the configuration file (auditlog.conf). Verify that the Audit Server IP address is entered in the MYIP field in the auditlog.conf file.

54

Citrix NetScaler Administration Guide

Configuring Audit Server Logging for a Commonly Used Deployment Scenario


This section describes how to configure the audit server logging feature for a commonly used deployment scenario, which lets you log all NOTICE events of Citrix NetScaler System. The procedures describe how to create an action and a policy, and how to bind the policy globally. The following diagram illustrates a typical deployment topology for audit server logging:

Audit Server Logging Topology The following table lists the parameters that need to be set on Citrix NetScaler System to configure audit server logging. The table includes sample values. Parameters for Audit Server Logging Configuration
Parameter Name Auditing Type IP Address Port Log Level TCP Logging Date Format Log Facility Value audit1 NSLOG 10.102.1.1 3024 NOTICE ALL DDMMYYYY LOCAL0

Chapter 3

Audit Server Logging

55

Parameters for Audit Server Logging Configuration


Parameter Time Zone To create an audit server action Value Local

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

In the Navigation Pane, expand System, expand Auditing, and click Policies. On the Auditing page, select the Servers tab and click Add. In the Create Auditing Server dialog box, in the Name text box, type audit1, and in the Auditing Type drop-down list, select NSLOG. In the IP Address text box, type 10.102.1.1, and in the Port text box, type 3024. Under Log Levels, select the NOTICE check box, and select the DDMMYYYY Date format option. In the Log Facility drop-down list, select LOCAL0, in TCP Logging, select the ALL option, and in Time Zone, select the Local option. Click Create and click Close.

The following procedure explains how to create a policy for the audit server action audit1.
To configure audit server policy

1. 2. 3. 4. 5.

In the Navigation Pane, expand System, expand Auditing, and click Policies. On the Policies page, click Add. In the Create Auditing Policy dialog box, in the Name text box, type a name for the policy (for example, auditpol1). In the Auditing Type drop-down list, select NSLOG, in the Server dropdown list, select audit1. Click Create, and click Close. The policy appears on the Policies page.

In the following procedure, you globally bind the audit log policy auditpol1 and set the priority to 0.
To globally bind the audit log policy

1. 2.

In the Navigation Pane, expand System, expand Auditing, and click Policies. On the Policies page, on the Policies tab, and click Global Bindings.

56

Citrix NetScaler Administration Guide

3.

In the Bind/Unbind Auditing Global Policies dialog box, in the Active column, select the check box next to auditpol1, and in the Priority list box, set the priority as 1. Click OK.

4.

To install and configure the audit server tool on a Windows Server

1.

Extract the files from NSauditserver.zip. The following directories are created: \NS\BIN \NS\ETC \NS\SAMPLES

Note: The BIN directory contains the executable audserver.exe and the ETC directory contains the auditlog.conf file. 2. Check the version of the auditserver executable using the following command at a command prompt:
audserver -version

The output appears in the following format:


Version: Netscaler Auditing Server (audserver) NS<Release_version>:<Build_Version>, Date: <Date>, <Time>(release) [Windows NT/2000]

3.

Type the following command at a command prompt:


audserver -addns -f ../etc/auditlog.conf

The system prompts for inputs for the following parameters:


NSIP Userid Password

4.

Enter the following values:


NSIP: 10.102.10.1 Userid: nsroot Password: nsroot

5.

Edit the auditlog.conf file located at \NS\ETC by changing the values for the following parameters as shown:
MYIP 10.102.1.1

Chapter 3

Audit Server Logging

57

MYPORT 3024 Filter default begin default logInterval Hourly logFileSizeLimit 10 logFilenameFormat auditlog%{%y%m%d}t.log end default

6.

Verify the configuration using the following command at a command prompt:


audserver -verify -f ../etc/auditlog.conf

A debug file is created and the following output appears:


Debug log file is ./nsaudit.log-<ddmmyyhhmm> & Log level is 1 Configuration file is correct

7.

Start audit server by typing the following command at a command prompt:


audserver -start -f /etc/auditlog.conf

The following output appears:


Debug log file is ./nsaudit.log-<ddmmyyhhmm> & Log level is 1 Configuration file is correct

Logging starts and the information is logged in the auditlog%{%y%m%d}t.log file in the \NS\BIN directory. 8. To stop audit server, at the command prompt, press Ctrl+C. The following output appears:
NSAUDIT:quitting on 2 signal!

58

Citrix NetScaler Administration Guide

C HAPTER 4

Web Server Logging

Web server logging is the process of maintaining a history of page requests that originate from Citrix NetScaler System. In This Chapter How Web Server Logging Works Configuring Web Server Logging Parameters System Requirements for Web Server Logging Installing the NSWL files on the Logging System Configuring Web Server Logging on the Logging System Checklist for Configuring Web Server Logging

How Web Server Logging Works


With the Web server logging feature enabled, the NetScaler collects log transaction data from the servers and stores it in the system buffer. The default size of the buffer is 16 MB. Note: For more information about modifying the buffer size, see Modifying the Default Buffer Size, on page 60 in this chapter. You must configure filters to allow logging based on a domain name or a server IP address. If the server uses the load balancing, content switching, or cache redirection feature of the system, you can also configure web server logging to log transactions based on the virtual IP address. The system can store log file data in the following three formats: W3C Extended log file format NCSA Common log file standard format Custom log format

60

Citrix NetScaler Administration Guide

The log format that you can use depends on the requirements to troubleshoot a problem. Custom log formats let you define only those parameters to log that you specify.

Configuring Web Server Logging Parameters


You can set parameters to enable web server logging and to modify the size of the buffer that stores the logged information. You can display these settings at any time.

Enabling or Disabling Web Server Logging


Use either of the following procedures to enable or disable web server logging.
To enable or disable web server logging using Configuration Utility

1. 2. 3.

In the navigation pane, expand System, and click Settings. In the Settings page, click advanced features. In the Configure Advanced Features dialog box, to enable Web server logging, select the Web Logging check box. To disable Web server logging, clear the check box. Click OK. In the Enable/Disable Feature(s) dialog box, click Yes.

4. 5.

To enable or disable web server logging using NetScaler command line

At the NetScaler command prompt, type:


enable ns feature WL

or
disable ns feature WL

Modifying the Default Buffer Size


You can change the default buffer size of 16MB for Web server logging to suit your requirements. To activate your modification, you must disable and reenable Web server logging. The following table describes the parameter you set. Parameter for Modifying Buffer Size
Parameter Buffer Size Specifies Buffer size (in megabytes) allocated for log transaction data in the appliance.

Chapter 4

Web Server Logging

61

To configure the buffer size using Configuration Utitlity

1. 2. 3. 4.

In the navigation pane, expand System, and click Settings. On the Settings, under Settings, click Change global system settings. In the Configure Global Settings dialog box, in the Web Logging section, enter a value in the Buffer_Size (in MBytes) text box (for example, 32). Click OK.

To configure the buffer size using the NetScaler command line

At the NetScaler command prompt, type:


set weblogparam -b Size

Example
set weblogparam -b

32

Note: To activate the new buffer size, you must disable and reenable web server logging, as described in Enabling or Disabling Web Server Logging, on page 60.

Displaying Web Server Logging Information


To see whether web server logging is enabled or disabled using the configuration utility

In the navigation pane, expand System and click Settings. On the Settings page, under Modes and Settings, click Change advanced features. In Configure Advanced Features dialog box, check to see whether the Web Logging check box is selected.
To see whether web server logging is enabled or disabled using the NetScaler command line

At the NetScaler command prompt, type:


show ns info

To display the buffer size for log transactions using the Configuration Utility

In the navigation pane, expand System and click Settings. On the Settings page, under Settings, click Change global system settings. In Configure Global Settings dialog box, under Web Logging, the Buffer_Size (in MBytes) text box displays the buffer size.

62

Citrix NetScaler Administration Guide To display the buffer size for log transactions using the NetScaler command line

At the NetScaler command prompt, type:


show weblogparam

System Requirements for Web Server Logging


The default web server log buffer size of 16 MB can handle up to 10,000 transactions per second on the logging system that meets the requirements shown in the following table: Hardware and Software Requirements for Web Server Logging
Operating System Windows Software Requirements Windows XP Professional - Version 2002 Windows 2003 server Windows 2000/NT RELEASE_PPC Power Macintosh powerpc - Darwin Kernel Version 8.6.0 Red Hat Enterprise Linux AS release 4 (Nahant) - Linux version 2.6.9-5.EL Red Hat 3.4.3-9.EL4 - Linux version 2.6.9-5.ELsmp Red Hat Linux 3.2.2-5 - Linux version 2.4.20-8 Sun Microsystems 5.9 - sun4u Sun Ultra 5/10 UPA/PCI FreeBSD 4.9 Hardware Requirements For Windows / Linux / FreeBSD For Solaris 2.6 Processor - Intel x86 ~501MHz RAM - 512 MB Controller - SCSI Processor - UltraSPARC-IIi 400 MHz RAM - 512 MB Controller - SCSI

MAC Linux

Solaris FreeBSD

If the logging system cannot process the log transaction because a CPU limitation, the Web log buffer overruns and the logging process reinitiates. Caution: Reinitiation of logging can result in loss of log transactions. To temporarily solve a logger client bottleneck caused by a CPU limitation, you can tune the Web server logging buffer size. To solve the problem, you need a logger client that can handle the sites throughput.

Chapter 4

Web Server Logging

63

Installing the NSWL files on the Logging System


This section describes the steps to install the NetScaler Web Server Logging executable files (NSWL) on various operating systems (logging systems). Copy the installation files from the product CD or download them from ftp.netscaler.com. Run the installations from a root user account. In the procedures described in the following subsections, <path_to_cd> defines the system path to the drive where the CD device is mounted.

Installing NSWL on a Solaris Operating System


Use the following procedure to install the nswl executable and other files on a computer running the Solaris operating system.
To install NSWL on a Solaris operating system

1.

Copy the NSweblog.tar file into a temporary directory using the command:
cp <path_to_cd>/Utilities/weblog/Solaris/NSweblog.tar /tmp

2. 3.

Change to the temporary directory:


cd /tmp

Extract the files from the *.tar file with the following command:
tar xvf NSweblog.tar

A directory NSweblog is created in the temporary directory, and the files are extracted to the NSweblog directory. 4. Install the package with the following command:
pkgadd -d .

The list of available packages appears. In the following example, one NSweblog package is shown:
1 NSweblog NetScaler Weblogging (SunOS,sparc) 7.0

5.

You are prompted to select the packages. Select the package number of the NSweblog to be installed. After you select the package number and press Enter, the files are extracted and installed in the following directories. (The dot indicates the current directory.) /usr/local/netscaler/etc

/usr/local/netscaler/bin

64

Citrix NetScaler Administration Guide

6.

/usr/local/netscaler/samples

To verify that the package is installed, enter the following command:


pkginfo | grep NSweblog

Note: To uninstall web server logging, use the command: pkgrm NSweblog

Installing NSWL on a Linux Operating System


Use the following procedure to install the nswl executable and the other files on a computer running the Red Hat Linux operating system.
To install NSWL on a Linux operating system

1. 2.

Copy the NSweblog.rpm file into a temporary directory:


cp <path_to_cd>/Utilities/weblog/Linux/NSweblog.rpm /tmp

To install the nswl executable, use the following command:


rpm -i NSweblog.rpm

This command extracts the files and installs them in the following directories. (The dot indicates the current directory.) /usr/local/netscaler/etc

/usr/local/netscaler/bin /usr/local/netscaler/samples.

To uninstall web server logging, use the following command.


rpm -e NSweblog

To get more information on the NSweblog RPM file, use the following command.
rpm -qpi *.rpm.

To view the installed web server logging files, use the following command (*.rpm is the file name).
rpm -qpl *.rpm

Installing NSWL on a FreeBSD Operating System


Use the following procedure to install the nswl executable and the other files on a computer running the FreeBSD 4.4 operating system.

Chapter 4 To install NSWL on a FreeBSD operating system

Web Server Logging

65

1.

At a command prompt, copy the NSweblog.tgz file into a temporary directory:


cp <path_to_cd>/Utilities/weblog/Freebsd/NSweblog.tgz /tmp

2. 3.

Change to the temporary directory:


cd /tmp

Install the package using the following command:


pkg_add NSweblog.tgz

This command extracts the files and installs them in the following directories. (The dot indicates the current directory.) 4. /usr/local/netscaler/etc /usr/local/netscaler/bin /usr/local/netscaler/samples

To verify that the package is installed, use the following command:


pkg_info | grep NSweblog

Note: To uninstall the web server logging package, enter the command: pkg_delete NSweblog

Installing NSWL on a MAC Operating System


Use the following procedure to install the nswl executable and the other files on a computer running the MAC operating system.
To install NSWL on a MAC operating system

1.

At a command prompt, copy the NSweblog.tgz file into a temporary directory with the following command:
cp <path_to_cd>/Utilities/weblog/macos/NSweblog.tgz /tmp

2. 3.

Change to the temporary directory:


cd /tmp

To install the package, use the pkg_add command:


pkg_add NSweblog.tgz

This command extracts the files and installs them in the following directories. (The dot indicates the current directory.)

66

Citrix NetScaler Administration Guide

4.

/usr/local/netscaler/etc /usr/local/netscaler/bin /usr/local/netscaler/samples

To verify that the package is installed, use the follwoing command:


pkg_info | grep NSweblog

Note: To uninstall the web server logging package, enter the command pkg_delete NSweblog

Installing NSWL on a Windows Operating System


Use the following procedure to install the nswl executable and the other files on a computer running the Windows operating system.
To install NSWL on a Windows operating system

1. 2.

Copy the NSweblog.exe file (winzip executable) into a temporary directory. The extracted files are installed in the following directories. (The dot indicates the current directory.) \NS\BIN \NS\ETC \NS\SAMPLES

3.

To install web server logging as a service, at a command prompt, run the following command from the \NS\BIN path:
nswl -install -f <directorypath> \log.conf

<directorypath> specifies the path where the log.conf file is available. 4. To uninstall the web server logging, run the following command from the \NS\BIN folder:
nswl -remove

Note: To uninstall the web server logging, run the nswl -remove command from the \NS\BIN folder:

Chapter 4

Web Server Logging

67

Installing NSWL on an AIX Operating System


Use the following procedure to install the nswl executable and the other files on a computer running the AIX operating system.
To install NSWL on an AIX operating system

1. 2.

Copy the NSweblog.rpm file into a temporary directory:


cp <path_to_cd>/Utilities/weblog/AIX/NSweblog.rpm /tmp

To install the nswl executable, use the following command:


rpm -i NSweblog.rpm

This command extracts the files and installs them in the following directories. (The dot indicates the current directory.) /usr/local/netscaler/etc

/usr/local/netscaler/bin /usr/local/netscaler/samples.

To uninstall web server logging, use the following command.


rpm -e NSweblog

To get more information on the NSweblog RPM file, use the following command.
rpm -qpi *.rpm.

To view the installed web server logging files, use the following command (*.rpm is the file name).
rpm -qpl *.rpm

NSWL Options
The following table describes the options that you can use with the nswl executable.

nswl Command nswl -help nswl -addns -f <path to configuration file>

Specifies Display all available nswl options The system that gathers the log transaction data. You are prompted to enter the IP address of the system. Enter a valid username and password.

nswl -verify -f <path to configuration file>

Check for syntax or semantic errors in the configuration file (for example, log.conf).

68

Citrix NetScaler Administration Guide

nswl Command nswl -start -f <path to configuration file>

Specifies Start web server logging based on the settings in the configuration file (for example, log.conf). For Solaris and Linux: To start web server logging as a background process, use and at the end of the command..

nswl -stop

Solaris and Linux only Stop web server logging, if nswl was started as a background process; otherwise, use CTRL+C to stop web server logging.

nswl -install -f <path to configuration file> (Windows only) nswl -startservice (Windows only)

Installs the web server logging client as a service in Windows. Start web server logging , using the settings in the configuration file (for example, log.conf) specified in the nswl install option. Web server logging can also be started from Start > Control Panel > Services.

nswl -stopservice (Windows only) nswl -remove

Stop Web server logging. Remove the web server logging service from the registry.

Run the following commands from the directory in which the nswl executable is located: Windows: \ns\bin Solaris and Linux: \usr\local\netscaler\bin

The web server logging configuration files are located in the following directory path: Windows: \ns\etc Solaris and Linux: \usr\local\netscaler\etc

The nswl executable is started as .\nswl in Linux and Solaris.

Configuring Web Server Logging on the Logging System


Following are the steps to configure web server logging: 1. 2. 3. Install web server logging. Modify the web server log configuration file, log.conf. Define log properties

Chapter 4

Web Server Logging

69

4. 5. 6.

Add the IP addresses of the Citrix NetScaler System to the log.conf file. Verify the configuration. Start web server logging

Note: You can configure the Citrix NetScaler System to log integrated cache transactions, using the web server logging feature.

Modifying the Web Server Log Configuration File


To modify the web server logging settings, use a text editor to modify the log.conf configuration file.

Defining Filters
Log filters let you filter the host IP address, domain name, and hostname of the Web servers. You must do the following to define filters: Define filters in the configuration file (log.conf) for each server whose web transactions are logged. Define log properties for each filter. The filter applies these log properties to transactions that match the filter.

Note: If a filter does not exist for a log transaction, the transaction is not recorded unless the default filter is defined.

Defining Default Filters


You can use the default filter definition present in the sample configuration file, log.conf, or you can modify it. Note: Consolidated logging, which logs transactions for which no filter is defined, uses the default filter if it is enabled. Consolidated logging of all servers can be done by defining only the default filter.

Creating Filters
To create a filter, enter the following command in the log.conf file:
Filter <filterName> [HOST name] | [IP ip] | [IP ip 2...ip n] | [IP ip NETMASK mask] [ON | OFF]

70

Citrix NetScaler Administration Guide

or
Filter <filterName> [HOST name] | [IP6 ip[/prefix length]] [ON | OFF]

The following table lists the parameters that can be set using the filter command:

Parameter filterName HOST name IP ip

Specifies Name of the filter (maximum 64 alphanumeric characters.) Host name of the server for which the transactions are being logged. IP address of the server for which transactions are to be logged (for example, if the server has multiple domains that have one IP address.) Multiple IP addresses (for example, if the server domain has multiple IP addresses.) IPv6 address of the server for which transactions are to be logged. IP addresses and netmask combination to be used on a subnet. Enable or disable the filter to log transactions. If no argument is selected, the filter is enabled (ON).

IP ip 2...ip n: ip6 ip IP ip NETMASK mask ON | OFF

Example

In the following example, you specify an IP address of 192.168.100.0 and netmask of 255.255.255.0. The filter applies to IP addresses 192.168.100.1 through 192.168.100.254.
Filter F1 HOST www.netscaler.com ON Filter F2 HOST www.netscaler.com IP 192.168.100.151 ON Filter F3 HOST www.netscaler.com IP 192.168.100.151 192.165.100.152 ON Filter F4 IP 192.168.100.151 Filter F5 IP 192.168.100.151 HOST www.netscaler.com OFF Filter F6 HOST www.netscaler.com HOST www.xyz.com HOST www.abcxyz.com IP 192.168.100.200 ON Filter F7 IP 192.250.100.0 NETMASK 255.255.255.0 Filter F8 HOST www.xyz.com IP 192.250.100.0 NETMASK 255.255.255.0 OFF

For creating filters for servers having IPv6 addresses.


Filter F9 2002::8/112 ON Filter F10 HOST www.abcd.com IP6 2002::8 ON

Chapter 4

Web Server Logging

71

Defining Filters for Virtual Servers


If the server hosts multiple Web sites and each Web site has its own domain name, and each domain is associated with a virtual server, you can configure Web server logging to create a separate log directory for each Web site. To define a filter for a virtual server, use the following command:
Filter <filterName> <IP>

<filterName>: Specifies the name of the filter <IP>: Specifies the IP address of the virtual server

Defining Log Properties


Log properties associated with the filter are applied to all log entries associated with the filter. Log property definition begins with the keyword BEGIN and ends with END.
Example
BEGIN <filtername> logFormat ... logFilenameFormat ... logInterval ... logFileSize .... logExclude .... END

LogFormat specifies the web server logging feature that supports NCSA, W3C Extended, and custom log file formats. For more information, see Log File Formats, on page 78 in this chapter. By default, the logformat property is w3c. To override, enter custom or NCSA in the configuration file, for example:
LogFormat NCSA

Note: For the NCSA and Custom log formats, local time is used to time stamp transactions and for file rotation. LogInterval specifies the intervals at which log files are created. The default property is Daily. If the LogInterval value is specified as:

Hourly: A file is created every hour Daily: A file is created every day at midnight

72

Citrix NetScaler Administration Guide

Weekly: A file is created every Sunday at midnight Monthly: A file is created on the first day of the month at midnight None: A file is created only once, when web server logging starts

Example
LogInterval Hourly

LogFileSizeLimit specifies the maximum size of the log file in MB. It can be used with any log interval (weekly, monthly, and so on.) A file is created when the maximum file size limit is reached or when the defined log interval time elapses. To override this behavior, specify the size as the loginterval property so that a file is created only when the log file size limit is reached. The default LogFileSizeLimit is 10 MB.
Example
LogFileSizeLimit 35

LogFilenameFormat specifies the file name format of the log file. The name of the file can be of the following types: Static: Specifies a constant string that contains the absolute path and file name. Dynamic: Specifies an expression containing the following format: Server IP address (%A) Date (%{format}t) URL suffix (%x) Host name (%v)

Note: For more information, see Log File Formats, on page 78 in this chapter.

Example
LogFileNameFormat Ex%{%m%d%y}t.log

This command creates the first file name as Exmmddyy.log, then every hour creates a file with file name: Exmmddyy.log.0, Exmmddyy.log.1,..., Exmmddyy.log.n.

Chapter 4 Example
LogInterval size LogFileSize 100 LogFileNameFormat Ex%{%m%d%y}t

Web Server Logging

73

Caution: The date format %t specified in the LogFilenameFormat command overrides the log interval property for that filter. To prevent a new file being created every day instead of when the specified log file size is reached, do not use %t in the LogFilenameFormat. LogExclude prevents logging of transactions with the specified file extensions.
Example
LogExclude .html

This command creates a log file that excludes log transactions for *.html files. LogTime specifies log time as either GMT or LOCAL. The defaults are: NCSA log file format: LOCAL W3C log file format: GMT.

Default Settings for the Log Properties


The following default settings apply to the filter: LogFormat: W3C Extended LogInterval: Daily LogFileSize: 10 LogFileNameFormat: Ex%{%m%d%y}t LogTime (logTime): GMT

Example 1
Filter f1 IP 192.168.10.1

This creates a log file for server 192.168.10.1


Example 2
Filter f1 IP 192.168.10.1 begin f1

74

Citrix NetScaler Administration Guide

logFilenameFormat c:\logfiles.log end f1

This command creates a log file for server 192.168.10.1. Only the log file name format is specified, and the rest of the default values for the log properties remain same.

Adding the IP Addresses of the NetScaler


In the configuration file, add the IP addresses of the NetScaler that performs web server logging.
To add the IP addresses

1.

At a command prompt, enter the following command:


nswl -addns -f <directorypath>\log.conf

<directorypath>: Specifies the path to the configuration file (log.conf). 2. The following information appears:
NSIP: Username: Password:

Enter the following: NSIP: Specify the IP address of the system Username: Specify the username to log on Password: Specify the password

If you add multiple NetScaler IP addresses (NSIP), and later you do not want to log all of Citrix NetScaler System log details, you can delete the NSIPs manually by removing the NSIP statement at the end of the log.conf file. During a failover setup, you must add both primary and secondary Netscaler IPs to log.conf using the command. Before adding the IP address, make sure the username and password exist on the system.

Verifying the Configuration


Check the configuration file (log.conf) for syntax errors to make sure that logging works correctly. To verify the configuration, enter the following command:
nswl -verify -f <directorypath>\log.conf

Chapter 4

Web Server Logging

75

<directorypath>: Specifies the path to the configuration file (log.conf).

Starting Web Server Logging


To start web server logging, type the following command:
nswl -start -f <directorypath>\log.conf

<directorypath>: Specifies the path to the configuration file (log.conf).

Stopping Web Server Logging


To stop web server logging started as a background process in Solaris or Linux, use the following command:
nswl -stop

To stop web server logging started as a service in Windows, use the following command:
nswl -stopservice

Sample Configuration File


Following is a sample configuration file:
########## # This is the NSWL configuration file # Only the default filter is active # Remove leading # to activate other filters ########## ########## # Default filter (default on) # W3C Format logging, new file is created every hour or on reaching 10MB file size, # and the file name is Exyymmdd.log ########## Filter default begin default logFormat logInterval logFileSizeLimit logFilenameFormat W3C Hourly 10 Ex%{%y%m%d}t.log

76

Citrix NetScaler Administration Guide

end default ##########

# netscaler caches example


# CACHE_F filter covers all the transaction with HOST name www.netscaler.com and the listed server ip's ########## #Filter CACHE_F HOST www.netscaler.com IP 192.168.100.89 192.168.100.95 192.168.100.52 192.168.100.53 ON ##########

# netscaler origin server example


# Not interested in Origin server to Cache traffic transaction logging ########## #Filter ORIGIN_SERVERS IP 192.168.100.64 192.168.100.65 192.168.100.66 192.168.100.67 192.168.100.225 192.168.100.226 192.168. 100.227 192.168.100.228 OFF ##########

# netscaler image server example


# all the image server logging. ########## #Filter IMAGE_SERVER HOST www.netscaler.images.com IP 192.168.100.71 192.168.100.72 192.168.100.169 192.168.100.170 192.168.10 0.171 ON ########## # NCSA Format logging, new file is created every day midnight or on reaching 20MB file size, # and the file name is /datadisk5/netscaler/log/NS<hostname>/ Nsmmddyy.log. # Exclude objects that ends with .gif .jpg .jar. ########## #begin ORIGIN_SERVERS # # # logFormat logInterval logFileSizeLimit NCSA Daily 40 /datadisk5/ORGIN/log/%v/

# logFilenameFormat NS%{%m%d%y}t.log

Chapter 4

Web Server Logging

77

logExclude

.gif .jpg .jar

#end ORIGIN_SERVERS

########## # NCSA Format logging, new file is created every day midnight or on reaching 20MB file size, # and the file name is /datadisk5/netscaler/log/NS<hostname>/ Nsmmddyy.log with log record timestamp as GMT. ########## #begin CACHE_F # # # logFormat logInterval logFileSizeLimit NCSA Daily 20

# logFilenameFormat /datadisk5/netscaler/log/%v/ NS%{%m%d%y}t.log # logtime GMT

#end CACHE_F

########## # W3C Format logging, new file on reaching 20MB and the log file path name is # atadisk6/netscaler/log/server's ip/Exmmyydd.log with log record timestamp as LOCAL. ########## #begin IMAGE_SERVER # # # # # logFormat logInterval logFileSizeLimit W3C Size 20

logFilenameFormat /datadisk6/netscaler/log/%AEx%{%m%d%y}t logtime LOCAL

#end IMAGE_SERVER

########## # Virtual Host by Name firm, can filter out the logging based on the host name by, ##########

78

Citrix NetScaler Administration Guide

#Filter VHOST_F IP 10.101.2.151 NETMASK 255.255.255.0 #begin VHOST_F # # # logFormat logInterval logFileSizeLimit W3C Daily 10

logFilenameFormat /ns/prod/vhost/%v/Ex%{%m%d%y}t #end VHOST_F

########## END FILTER CONFIGURATION ##########

Log File Formats


The NetScaler supports the following log file formats: NCSA Common Log Format W3C Extended Log Format Custom Log Format Apache Log Format

NCSA Common Log Format


If the log file format is NCSA, the log file displays log information in the following format:
Client_IP_address User_Name [Date:Time TimeZone] Method Object HTTP_version HTTP_StatusCode BytesSent

To use the NCSA Common log format, enter NCSA in the LogFormat argument in the log.conf file. The following table describes the NCSA Common log format.

Client _IP_address User Name Date Time Time Zone Method

Specifies the IP address of the client computer Specifies the user name Specifies the date of the transaction Specifies the time when the transaction was completed Specifies the time zone (Greenwich Mean Time or local time) Specifies the request method (for example; GET, POST)

Chapter 4

Web Server Logging

79

Object HTTP_version HTTP_StatusCode Bytes Sent

Specifies the URL Specifies the version of HTTP used by the client Specifies the status code in the response Specifies the number of bytes sent from the server

W3C Extended Log Format


An extended log file contains a sequence of lines containing ASCII characters terminated by either a Line Feed (LF) or the sequence Carriage Return Line Feed (CRLF.) Log file generators must follow the line termination convention for the platform on which they are run. Log analyzers must accept either LF or CRLF form. Each line may contain either a directive or an entry. If you want to use the W3C Extended log format, enter W3C as the Log-Format argument in the log.conf file.

Customizing W3C Format


By default, the standard W3C log format is defined internally as the custom log format, shown as follows:
%{%Y-%m-%d%H:%M:%S}t %a %u %S %A %p %m %U %q %s %j %J %T %H %+{useragent}i %+{cookie} i%+{referer}i

For a description of the meaning of this each custom format, see Custom Log Format, on page 83 in this chapter. You can also change the order or remove some fields in this W3C log format. For example:
logFormat W3C %{%Y-%m-%d%H:%M:%S}t %m %U

W3C log entries are created with the following format:


#Version: 1.0 #Fields: date time cs-method cs-uri #Date: 12-Jun-2001 12:34 2001-06-12 12:34:23 GET /sports/football.html 2001-06-12 12:34:30 GET /sports/football.html

Entries
Entries consist of a sequence of fields relating to a single HTTP transaction. Fields are separated by white space; Citrix recommends the use of tab characters. If a field in a particular entry is not used, a dash - marks the omitted field.

80

Citrix NetScaler Administration Guide

Directives
Directives record information about the logging process. Lines beginning with the # character contain directives. The following table describes the directives.

Directive Version: <integer>.<integer> Fields: [<specifier>...] Software: <string> Start-Date: <date> <time> End-Date: <date> <time> Date: <date> <time> Remark: <text>

Description Displays the version of the extended log file format used. This document defines version 1.0. Identifies the fields recorded in the log. Identifies the software that generated the log. Displays the date and time at which the log was started. Displays the date and time at which logging finished. Displays the date and time when the entry was added. Displays comments. Analysis tools ignore data recorded in this field.

Note: The Version and Fields directives are required. They precede all other entries in the log file.

Example

The following sample log file shows the W3C Extended log format:
#Version: 1.0 #Fields: time cs-method cs-uri #Date: 12-Jan-1996 00:00:00 00:34:23 GET /sports/football.html 12:21:16 GET /sports/football.html 12:45:52 GET /sports/football.html 12:57:34 GET /sports/football.html

Fields
The Fields directive lists a sequence of field identifiers that specify the information recorded in each entry. Field identifiers may have one of the following forms:

Chapter 4

Web Server Logging

81

identifier: Relates to the transaction as a whole. prefix-identifier: Relates to information transfer between parties defined by the value prefix. prefix(header): Specifies the value of the HTTP header field header for transfer between parties defined by the value prefix. Fields specified in this manner always have the type <string>.

The following table describes defined prefixes.

Prefix c s

Specifies Client. Server. Remote. Client to server. Server to client. Server to remote server (prefix used by proxies). Remote server to server (prefix used by proxies). Application-specific identifier.

r
cs sc sr rs x Examples

The following examples are defined identifiers that use prefixes: cs-method : Specifies the method in the request sent by the client to the server sc(Referer): Specifies the Referer field in the reply c-ip: Specifies the IP address of the client

Identifiers
The following table describes the W3C Extended log format identifiers that do not require a prefix.

Identifier date time time-taken bytes

Description Specifies the date on which the transaction was done. Specifies the time when the transaction is done. Specifies the time taken (in seconds) for the transaction to complete. Specifies the number of bytes transferred.

82

Citrix NetScaler Administration Guide

cached

Records whether a cache hit has occurred. A zero indicates a cache miss.

The following table describes the W3C Extended log format identifiers that require a prefix.

Identifier IP dns status comment method url url-stem url-query

Description Specifies the IP address and the port number. Specifies the DNS name. Specifies the status code. Specifies the comment returned with status code. Specifies the method. Specifies the URL. Specifies the stem portion of the URL. Specifies the query portion of the URL.

The W3C Extended Log file format allows you to choose log fields. These fields are shown in the following table:

Field Date Time Client IP User Name Service Name Server IP Server Port Method Url Stem Url Query Http Status Bytes Sent

Description Specifies the date on which the transaction is done. Specifies the time when the transaction is done. Specifies the IP address of the client. Specifies the user name. Specifies the service name, which is always HTTP. Specifies the server IP address. Specifies the server port number Specifies the request method (for example; GET, POST). Specifies the URL stem. Specifies the query portion of the URL. Specifies the status code in the response. Specifies the number of bytes sent to the server (request size, including HTTP headers).

Chapter 4

Web Server Logging

83

Bytes Received Time Taken Protocol Version User Agent Cookie Referer

Specifies the number of bytes received from the server (response size, including HTTP headers). Specifies the time taken for transaction to complete, in seconds. Specifies the version number of HTTP being used by the client. Specifies the User-Agent field in the HTTP protocol. Specifies the Cookie field of the HTTP protocol. Specifies the Referer field of the HTTP protocol.

Custom Log Format


You can customize the display format of the log file data as described in the following subsections:

Using the NSWL Library to Define a Custom Log Format


Use one of the following NSWL libraries depending on whether the nswl executable has been installed on a Windows or Solaris host computer: Windows: The nswl.lib library located in \ns\bin directory on the system manager host computer. Solaris: The libnswl.a library located in /usr/local/ netscaler/bin

To define the custom log format

1.

Add the following two C functions defined by the system in a source file: ns_userDefFieldName(): This function returns the string that must be added as a custom field name in the log file. ns_userDefFieldVal(): This function implements the custom field value, then returns it as a string that must be added at the end of the log record.

2. 3. 4.

Compile the file into an object file. Link the object file with the NSWL library (and optionally, with third party libraries) to form a new nswl executable. Add a %d string at the end of the logFormat string in the log.conf file.

84

Citrix NetScaler Administration Guide Example

If you want to add a digital signature at the end of each record, follow the steps in the preceding section and define the filter in the log.conf file as described below.
########## # A new file is created every midnight or on reaching 20MB file size, # and the file name is /datadisk5/netscaler/log/NS<hostname>/ Nsmmddyy.log and create digital #signature field for each record. BEGIN CACHE_F logFormat custom "%a - "%{user-agent}i" [%d/%B/%Y %T -%g] "%x" %s %b%{referrer}i "%{user-agent}i" "%{cookie}i" %d " logInterval Daily logFileSizeLimit20 logFilenameFormat/datadisk5/netscaler/log/%v/NS%{%m%d%y}t.log END CACHE_F

Manually Defining a Custom Log Format


To customize the format in which log file data should appear, specify a character string (described in the following table) as the argument of the LogFormat log property definition. For example:
LogFormat Custom ""%a - "%{user-agent}i" %[%d/%m/%Y]t %U %s %b %T"

The string can contain the c type control characters \n and \t to represent new lines and tabs. Use the <Esc> key with literal quotes and backslashes.

The characteristics of the request are logged by placing % directives in the format string, which are replaced in the log file by the values. If the %v (Host name) or %x (URL suffix) format specifier is present in a log filename format string, the following characters in the filename are replaced by an underscore symbol in the log configuration filename: ", *, ., /, :, <, >, ? \, | Characters whose ASCII values lie in the range of 0-31 are replaced by the following: %<ASCII value of character in hexadecimal>. For example, the character with ASCII value 22 is replaced by %16.

Chapter 4

Web Server Logging

85

Caution: If the %v format specifier is present in a log filename format string, a separate file is opened for each virtual host. To ensure continuous logging, the maximum number of files that a process can have open should be sufficiently large. See your operating system documentation for a procedure to change the number of files that can be opened. The following table describes the data that you can use as the LogFormat argument string:

%a %A %a6 %A6 %B %b %d %g %h %H %{Foobar}i

Specifies the remote IPv4 address Specifies the local IPv4 address Specifies the remote IPv6 address Specifies the local IPv6 address Specifies the bytes sent, excluding the HTTP headers (response size) Specifies the bytes received, excluding the HTTP headers (request size) Specifies a user-defined field Specifies the Greenwich Mean Time offset (for example, -0800 for Pacific Standard Time) Specifies the remote host Specifies the request protocol Specifies the contents of the Foobar: header line(s) in the request sent to the server. The system supports the User-Agent, Referer and cookie headers. The + after the % in this format informs the logging client to use the + as a word separator. Specifies the bytes received, including headers (request size) Specifies the bytes sent, including headers (response size) Specifies the remote log name (from identd, if supplied) Specifies the request method Specifies the time taken to serve the request (in microseconds) Specifies the contents of Foobar: header line(s) in the reply. We support the USER-AGENT, Referer, and cookie headers. Specifies the canonical port of the server serving the request Specifies the query string [prefixed with a question mark (?) if a query string exists] Specifies the first line of the request

%j %J %l %m %M %{Foobar}o %p %q %r

86

Citrix NetScaler Administration Guide

%s %t %{format}t %T %u %U %v %V %V6

For requests that were redirected internally, this is the status of the original request Specifies the time, in common log format (standard English time format) Specifies the time, in the form given by format, must be in strftime(3) format. The next table describes what you can enter as the format. Specifies the time taken to serve the request, in seconds Specifies the remote user (from auth; may be bogus if return status (%s) is 401) Specifies the URL path requested Specifies the canonical name of the server serving the request This is the virtual server IPv4 address in the system, if load balancing, content switching, and/or cache redirection is used. This is the virtual server IPv6 address in the system, if load balancing, content switching, and/or cache redirection is used.

For example, if you define the log format as %+{user-agent}i, and if the user agent value is Citrix Netscaler system Web Client, then the information is logged as Citrix Netscaler system +Web+Client. An alternative is to use the double quote (for example, %{user-agent}i, then it logs it as Citrix Netscaler system Web Client. Do not use the <Esc> key on strings from %.. .r, %. . .i and, %. . .o. This complies with the requirements of the Common Log Format. Note that clients can insert control characters into the log. Therefore, you should take care when working with raw log files.

Time Format Definition


The following table lists the characters that you can enter as the format part of the %{format}t string (described in the table in the preceding section). Values within brackets ([ ]) show the range of values that appear. For example, [1,31] in the %d description in the following table shows %d ranges from 1 to 31.

%% %a %A %b %B %C

Specifies the same as %. Specifies the abbreviated name of the week day for the locale. Specifies the full name of the week day for the locale. Specifies the abbreviated name of the month for the locale. Specifies the full name of the month for the locale. Specifies the century number (the year divided by 100 and truncated to an integer as a decimal number [1,99]); single digits are preceded by a 0.

Chapter 4

Web Server Logging

87

%d %e %h %H %I %j %k %l %m %M %n %p %r %S %t %u

Specifies the day of month [1,31]; single digits are preceded by 0. Specifies the day of month [1,31]; single digits are preceded by a blank. Specifies the abbreviated name of the month for the locale. Specifies the hour (24-hour clock) [0,23]; single digits are preceded by a 0. Specifies the hour (12-hour clock) [1,12]; single digits are preceded by a 0. Specifies the number of the day in the year [1,366]; single digits are preceded by 0. Specifies the hour (24-hour clock) [0,23]; single digits are preceded by a blank. Specifies the hour (12-hour clock) [1,12]; single digits are preceded by a blank. Specifies the number of the month in the year [1,12]; single digits are preceded by a 0. Specifies the minute [00,59]; leading 0 is permitted but not required. Inserts a new line. Specifies the equivalent of either a.m. or p.m. for the locale. Specifies the appropriate time representation in 12-hour clock format with %p. Specifies the seconds [00,61]; the range of values is [00,61] rather than [00,59] to allow for the occasional leap second and for the double leap second. Inserts a tab. Specifies the day of the week as a decimal number [1,7]. 1 represents Sunday, 2 represents Tuesday and so on.

%U %w

Specifies the number of the week in the year as a decimal number [00,53], with Sunday as the first day of week 1. Specifies the day of the week as a decimal number [0,6]. 0 represents Sunday.

%W %y

Specifies the number of the week in the year as a decimal number [00,53]. Monday is the first day of week 1. Specifies the number of the year within the century [00,99]. For example, 5 would be the fifth year of that century.

%Y

Specifies the year, including the century (for example, 1993).

88

Citrix NetScaler Administration Guide

Note: If you specify a conversion that does not correspond to any of the ones described in the preceding table, or to any of the modified conversion specifications listed in the next paragraph, the behavior is undefined and returns 0. The difference between %U and %W (and also between modified conversions %OU and %OW) is the day considered to be the first day of the week. Week number 1 is the first week in January (starting with a Sunday for %U, or a Monday for %W). Week number 0 contains the days before the first Sunday or Monday in January for %U and %W.

Apache Log Formats


You can derive from the custom logs most of the log formats that Apache currently supports. The custom log formats that match Apache log formats are: NCSA/combined: LogFormat custom %h %l %u [%t] "%r" %s %B "%{referer}i" "%{user-agent}i" NCSA/Common: LogFormat custom %h %l %u [%t] "%r" %s %B Referer Log: LogFormat custom "%{referer}i" -> %U Useragent: LogFormat custom %{user-agent}i Similarly, you can derive the other server log formats from the custom formats.

Checklist for Configuring Web Server Logging


Use the following checklist when you configure web server logging or need to troubleshoot problems: 1. 2. Make sure that the Citrix NetScaler system user name and password are valid. Make sure that the Netscaler is accessible from the logging system by doing the following: 3. Ping the Netscaler IP address Use FTP and Telnet to access the system

Verify that the IP address of the NetScaler is present in the configuration file (log.conf)

C HAPTER 5

Advanced Configurations

You can configure network time protocol to synchronize the NetScaler's local clock with the other servers on the network. If you enable PMTU discovery, the NetScaler can use it to determine the maximum transmission unit of any Internet channel. For more efficient data transfer, you can configure TCP window scaling and selective acknowledgement. You can clear any basic or extended configuration on your NetScaler. In This Chapter Configuring Clock Synchronization Path Maximum Transmission Unit Discovery Configuring TCP Window Scaling Configuring Selective Acknowledgement Clearing the Configuration

Configuring Clock Synchronization


You can configure your NetScaler to synchronize its local clock with a Network Time Protocol (NTP) server. This ensures that its clock has the same date and time settings as the other servers on your network. You can configure clock synchronization on your NetScaler either by manually modifying the ntp.conf file and then starting the NTP daemon, or by adding NTP server entries in the ntp.conf file from the configuration utility or the NetScaler
command line.

Configuring Clock Synchronization Manually


You can configure clock synchronization manually by logging on to the NetScaler and editing the ntp.conf file.
To enable clock synchronization on your NetScaler by modifying the ntp.conf file

1.

Log on to the NetScaler command line.

90

Citrix NetScaler Administration Guide

2. 3. 4.

Switch to the shell prompt. Copy the /etc/ntp.conf file to /nsconfig/ntp.conf. Copy the ntp.conf file from the /etc directory to the /nsconfig directory. If it already exists in the /nsconfig directory, be sure to remove the following entries from the ntp.conf file: restrict localhost restrict 127.0.0.2 These entries are required only if you want to run the device as a time server, and this feature is not supported on the NetScaler.

5.

Edit /nsconfig/ntp.conf and add the IP address for the desired NTP server under the files server and restrict entries.

Note: For security reasons, it is recommended that there should be a corresponding restrict entry for each server entry. 6. 7. Create a file and name it rc.netscaler in the /nsconfig directory, if the file does not already exist in the directory. Edit /nsconfig/rc.netscaler, and add the following entry. /usr/sbin/ntpd -c /nsconfig/ntp.conf -l /var/log/ ntpd.log & This entry starts the ntpd service, checks the ntp.conf file, and logs messages in the /var/log directory. 8. Reboot the NetScaler to enable clock synchronization.

Note: If you want to start the time synchronization process but restart the NetScaler at a later time, run the following command from the shell prompt: /usr/sbin/ntpd -c /nsconfig/ntp.conf -l /var/log/ ntpd.log & This command starts the time synchronization process. If you want the process to start every time the NetScaler is restarted, add it to the rc.netscaler file, as described in step 6.

Chapter 5

Advanced Configurations

91

If you do not have a local NTP server, you can find a list of public, open access, NTP servers at the official NTP site, http://www.ntp.org, under Public Time Servers List. Before configuring your NetScaler to use a public NTP server, be sure to read the Rules of Engagement page (link included on all Public Time Servers pages).

Configuring Clock Synchronization Using the Configuration Utility or the CLI


You can configure clock synchronization on your NetScaler by adding NTP servers from the Configuration utility or from the CLI and then enabling NTP synchronization. The clock synchronization configuration does not change on restart, upgrade, or downgrade of the NetScaler. However, the configuration does not get propagated to the secondary NetScaler in a High Availability setup.

Adding NTP Server Entries


You must add NTP server entries to the ntp.conf file so that your NetScaler can synchronize the clock with the clock settings of the other servers on the network. The following table describes the parameters you need to set to add NTP servers:
Parameters NTP Server Minimum Poll Interval Specifies Name or IP address of the NTP server. Minimum number of seconds after which the NTP server must poll the NTP messages. Must be a power of 2. Minimum value: 4 (2^4=16 seconds), Default: 6 (2^6=64 seconds). Maximum value: 17 (2^17=131072 seconds). Maximum number of seconds after which the NTP server must poll the NTP messages. Must be a power of 2. Minimum value: 4 (2^4=16 seconds), Default : 10 (2^10=1024 seconds). Maximum value: 17 (2^17=131072 seconds).

Maximum Poll Interval

To add NTP servers using the Configuration Utility

1. 2. 3. 4. 5.

In the navigation pane, expand System, and then click NTP Servers. On the NTP Servers page, click Add. In the Create NTP Server dialog box, in the NTP Server text box, type either the IP address or the name of the NTP server (for example, 1.2.3.4). In the Minimum Poll text box, type the minimum time interval after which you want the NTP server to poll the NTP messages (for example, 5). In the Maximum Poll text box, type the maximum time interval after which you want the NTP server to poll the NTP messages (for example, 11).

92

Citrix NetScaler Administration Guide

6.

Click Create, and click Close.

To add NTP servers using the NetScaler command line

At the NetScaler command prompt, type:


add ntp server serverIP | serverName -minpoll positive integer -maxpoll positive integer

Example
add ntp server 1.2.3.4 -minpoll 5 -maxpoll 11

Modifying NTP Server Entries


You can modify the minimum and maximum polling intervals of the NTP servers.
To modify NTP polling using the Configuration Utility

1. 2. 3.

In the navigation pane, expand System, and then click NTP Servers. On the NTP Servers page, click the NTP server that you want to modify, and then click Open. In the Configure NTP Server dialog box, in the Minimum Poll text box, change the minimum time interval after which you want the NTP server to poll the NTP messages (for example, 7). In the Maximum Poll text box, change the maximum time interval after which you want the NTP server to poll the NTP messages (for example, 9). Click Ok.

4. 5.

To modify NTP servers using the NetScaler command line

At the NetScaler command prompt, type


set ntp server serverIP | serverName -minpoll positive integer -maxpoll positive integer

Example
set ntp server 1.2.3.4 -minpoll 7 -maxpoll 9

Removing NTP Server Entries


You can remove the NTP servers from the ntp.conf file if you do not want to use these servers.
To remove NTP servers using the Configuration Utility

1.

In the navigation pane, expand System, and then click NTP Servers.

Chapter 5

Advanced Configurations

93

2. 3.

On the NTP Servers page, click the NTP server that you want to remove, and then click Remove. In the Remove message box, click Yes.

To remove NTP servers using the NetScaler command line

At the NetScaler command prompt, type:


rm ntp server serverIP | serverName

Example
rm ntp server 1.2.3.4

Displaying NTP Server Entries


You can display the details of the NTP servers that you have added to the ntp.conf file.
To display NTP servers using the Configuration Utility

1. 2.

In the navigation pane, expand System, and then click NTP Servers. On the NTP Servers page, you can view all the NTP servers that you have added.

To view NTP servers using the NetScaler command line

At the NetScaler command prompt, type


show ntp server

Enabling or Disabling NTP Synchronization


When you enable NTP synchronization, the NetScaler uses the NTP server entries in the ntp.conf file to synchronize its local time setting. If you do not want to synchronize your NetScaler time with the other servers in the network, you can disable NTP synchronization.
To enable or disable NTP synchronization using the Configuration Utility

1. 2.

In the navigation pane, expand System, and then click NTP Servers. On the NTP Servers page, click NTP Synchronization.

To enable or disable NTP synchronization using the NetScaler command line

At the NetScaler command prompt, type:


enable ntp sync

94

Citrix NetScaler Administration Guide

or
disable ntp sync

Path Maximum Transmission Unit Discovery


Path maximum transmission unit (PMTU) discovery is a method for dynamically learning the maximum transmission unit of any Internet channel. The discovered PMTU is used by the TCP or UDP layer to create packets of an optimum size for that channel. This avoids fragmentation overhead on the routers in the path, and reassembly overhead on the receiving server. PMTU discovery is an operational mode in the NetScaler. This mode enables the NetScaler to interoperate with other routers participating in PMTU discovery. In a typical topology, the NetScaler is deployed in front of the servers it manages, and either manages connections from clients on behalf of these servers (transparent mode), or manages connections with the servers and clients independently (endpoint mode).

The NetScaler in Transparent Mode


In transparent mode, if a managed server sets the DF bit and sends a datagram, and Path MTU is smaller than the size of the datagram, the NetScaler receives an ICMP error. When the NetScaler is operating in MIP mode, it adjusts the MTU to the MIP and updates the MTU database so that the lower MTU is used for subsequent connections. All packets subsequently sent via that connection have the DF bit unset. Note: This affects all clients using that MIP, not just the client that generated the ICMP error. In USIP mode, when an ICMP error message is received, the NetScaler translates it and sends it to the managed server. The managed server updates the MTU for that destination, and subsequent datagrams are sent with the lowered MTU. The MTU value for that client is also updated in the NetScaler. All new connections then use the lowered MTU.

The NetScaler in End-Point Mode


In end-point mode, the NetScaler separately manages connections to the servers it manages and connections to the clients that contact those servers.

Chapter 5

Advanced Configurations

95

For client connections, the NetScaler uses an Maximum Segment Size (MSS) of 1460 bytes. If the network contains a router that fragments the packet into multiple datagrams because of MTU mismatches, the router sends an ICMP error to the NetScaler. The NetScaler does not pass the error to the servers it manages, but parses it and determines an MTU appropriate for that particular client. The NetScaler then updates the MTU database with the lower MTU. Thereafter, it uses the new MTU value for all new connections to that client.

Enabling or Disabling PMTU Discovery


The NetScaler does not participate in PMTU Discovery by default.
To enable or disable PMTU discovery using configuration utility

1. 2. 3.

In the Navigation Pane, expand System, and then click Settings. On the Settings page, under Modes & Features click Change modes. In the Configure Modes dialog box, select the Path MTU Discovery check box to enable this feature, or clear the check box to disable it, and click OK

To enable or disable PMTU discovery using using the NetScaler command line

At the NetScaler command prompt, type:


enable ns mode PMTUD

or
disable ns mode PMTUD

Configuring TCP Window Scaling


The TCP window scaling option increases the TCP receive window size beyond its maximum value of 65,535 bytes. This TCP option is defined in RFC 1323. The window scaling option is required for efficient transfer of data over long fat networks (LFNs). A TCP window determines the amount of outstanding (unacknowledged by the recipient) data a sender can send on a particular connection before receiving any acknowledgment from the receiver. The main purpose of the window is flow control.

96

Citrix NetScaler Administration Guide

The window size field in the TCP header is 16 bits, which limits the ability of the sender to advertise a window size larger than 65535 ( 2^16 - 1). The TCP window scale extension expands the definition of the TCP window to 30 bits by using a scale factor to carry this value in the 16 bit window field of the TCP header. In the NetScaler, the window scale expands the definition of the TCP window to 24 bits. The scale factor is carried in the new TCP window scale field. This field is sent only in a SYN packet (a segment with the SYN bit on). The new window size is calculated by the receiver. [right shifting the bits of the received window size by the scale factor value] which is equivalent to [(2^scale factor) * received window size] Before configuring window scaling, make sure that: You do not set a high value for the Scale Factor, because this could have adverse effects on the NetScaler and the network. You have enabled SACK (selective acknowledgement). You do not configure window scaling unless you clearly know why you want to change the window size. Both hosts in the TCP connection send a window scale option during connection establishment. If only one side of a connection is sets this option, windows scaling will not be used for the connection. Each connection for same session (such as TCP session between Client and NetScaler and TCP session between NetScaler and Server having the same request/response) is an independent Window Scaling session. It is possible to have window scaling between the client and a Citrix NetScaler and not the a Citrix NetScaler and a server.

By default, window scaling is not enabled. The following table describes the parameters used to configure window scaling:
Parameters Windows scaling factor Specifies Factor used to calcualte new window size . Possible values: 0 to 8. Default: 4.

To configure window scaling, use either of the following procedures:


To configure Window Scaling using the configuration utility

1. 2.

In the navigation pane, expand System and click Settings. On the Settings page, under Global Settings, click Change global system settings.

Chapter 5

Advanced Configurations

97

3. 4. 5.

In the Configure Global Settings dialog box, under TCP, select the Windows Scaling checkbox. In the Factor textbox, type a windows scaling factor (for example, 5). Click Ok.

To configure Window Scaling using the NetScaler command line

At the NetScaler command prompt, type:


set ns tcpParam -WS value -WSVal value

Example
set ns tcpParam -WS ENABLED -WSVal 5

Configuring Selective Acknowledgement


The NetScaler supports Selective Acknowledgement (SACK), as defined in RFC 2018. Using SACK, the data receiver (either a Citrix NetScaler or a client) notifies the sender about all the segments that have been received successfully. As a result, the sender (either a Citrix NetScaler or a client) needs to retransmit only those segments that were lost during transmission. This improves the performance of data transmission. SACK is important in long fat networks (LFNs). By default, SACK is disabled. Use either of the following procedures to enable it.
To enable SACK using the Configuration Utility

1. 2. 3.

In the navigation pane, expand System and click Settings. On the Settings page, under Global Settings, click Change global system settings. In the Configure Global Settings dialog box, select the Selective Acknowledgement checkbox, and click Ok.

To enable Selective Acknowledgement (SACK) using the NetScaler command line

At the NetScaler command prompt, type:


set ns tcpParam - SACK value

Example
set ns tcpParam -SACK ENABLED

98

Citrix NetScaler Administration Guide

Clearing the Configuration


This section provides instruction for clearing the configuration on your NetScaler. You can clear your NetScaler configuration in different levels as described below: Basic Configuration: Clearing your configuration at the basic level clears all settings except the following: NSIP, MIP(s), and SNIP(s) Network settings (Default Gateway, VLAN, RHI, NTP, and DNS settings) HA node definitions Feature and mode settings Default administrator password (nsroot)

Extended Configuration: Clearing your configuration at the extended level clears all settings except the following: NSIP, MIP(s), and SNIP(s) Network settings (Default Gateway, VLAN, RHI, NTP, and DNS settings) HA node definitions

Feature and mode settings revert to their default values. Full Configuration: Clearing your configuration at the full level returns all settings to their factory default values. However, the NSIP and default gateway are not changed, because changing them could cause the NetScaler to lose network connectivity. To clear a configuration, use either of the following procedures:
To clear a configuration using the configuration utility

1. 2. 3. 4.

In the Navigation Pane, expand System, and then click Diagnostics. On the Diagnostics page, under Maintenance, click Clear Configuration. In the Clear Configuration dialog box, for Configuration Level, select an option (for example, basic). Click Run.

To clear configuration using the NetScaler command line

At the NetScaler command prompt, type:


clear ns config level

Chapter 5 Example
clear ns config basic

Advanced Configurations

99

100

Citrix NetScaler Administration Guide

C HAPTER 6

Reporting Tool

The Reporting tool of Citrix NetScaler provides built-in reports that display statistics collected by the nscollect utility. You can also create custom reports. The reports use charts to display the statistics. You can modify the charts and add new charts. You can also modify the operation of the nscollect utility and stop or start its operation. In This Chapter Using the Reporting Tool How Data Collection Works

Using the Reporting Tool


The Reporting tool is a Web-based interface. Use the Reporting tool to display the performance statistics data as reports containing graphs. In addition to using the built-in reports, you can create custom reports (which you can modify at any time). Every report contains at least one chart. You can add additional charts to custom reports, and you can modify the charts.
To invoke the Reporting tool

1.

Use the Web browser of your choice to connect to the IP address of the NetScaler (for example, http://10.102.29.170/). The Web Logon screen appears. In the User Name text box, type the user name assigned to your NetScaler. In the Password text box, type the password. In the Start in drop-down box, select Reporting. Click the Login button.

2. 3. 4. 5.

After you have logged in, the reporting tool page appears as follows.

102

Citrix NetScaler Administration Guide

Reporting Tool Page

The components of the reporting tool are: Navigation Pane Details Pane Report Toolbar Chart Toolbar

Navigation Pane: The navigation pane extends down the left side of the screen. It has two sections for each type of report: Custom Reports and Built-in Reports. Under Custom Reports, you can access custom reports you create. Under Built-in Reports, a collapsible menu contains links to different categories of built-in reports. To view a report, click the report, and it appears in the right pane, which is also called the details pane. Details Pane: The details pane is the right portion of the Reporting page, which displays the report you clicked in the navigation pane. You can modify a report, create custom reports, and view reports for different time intervals using various options available in the details pane.

Chapter 6

Reporting Tool

103

Report Toolbar: You can use the options on the report toolbar in the details pane to do the following: View reports in different time intervals Create new custom reports Save built-in reports as custom reports Delete reports Change the settings of the reports and select a different data source

Chart Toolbar: Each report is a collection of charts. Beneath each chart is a chart toolbar with options for changing the chart to a different type or charting different counters. The chart toolbar also has icons for adding a new chart, deleting a chart, or moving the chart up or down within the report. For more information on charts, see Working with Charts, on page 106.

Working with Reports


Reports let you plot and monitor statistics for the various functional groups configured on the NetScaler over a specified time interval. This enables you to troubleshoot or analyze the behavior of your appliance. There are two types of reports: built-in reports and custom reports. With either type, you can use the options on the report toolbar, as described in the following table. Basic operations on reports
Basic operation Refresh Print Set as default Remove as default Action Refreshes the report to display the latest performance data. Prints the report to paper. Displays a default report whenever you log on. Removes the default setting of the current default report and sets the first custom report as default. If there is no custom report available, the first built-in report (CPU vs. Memory Usage and HTTP Requests Rate) is set as the default report.
Note: This button appears only when you click the report that is set as default.

104

Citrix NetScaler Administration Guide

Basic operations on reports


Basic operation Save as Save Action Saves a report as a new custom report. Saves the changes made in a custom report.

Using Built-in Reports


The Reporting tool provides built-in reports for frequently viewed data. Built-in reports are available for the following seven fuctional groups: System, Network, SSL, Compression, Integrated Cache, Access Gateway, and Application Firewall. By default, the built-in reports are displayed for the last hour. However, you can view the reports for the last day, last week, last month, or last year. Note: You need to save a built-in report as a custom report if you make any changes to it.

To display a built-in report

1. 2.

In the navigation pane, under Built-in Reports, expand a group (for example, System). Click a report (for example, CPU vs. Memory Usage and HTTP Requests Rate).

Creating and Modifying Custom Reports


You can create your own custom reports and save them with user-defined names for reuse. You can plot different counters for different groups based on your requirements. You can create upto 256 custom reports. You can save a built-in report as a custom report, or you can create a new report. By default, a newly created custom report contains one chart named System Overview, which displays the CPU Usage counter plotted for the last hour. You can use the report toolbar to modify the interval, and to set the data source and time zone. Within a report, you can use chart toolbars to add, modify, or delete charts, as described in Working with Charts, on page 106.

Creating a Report
Use the Create function to create a new custom report, or use the Save As function to save an existing report as a custom report.

Chapter 6 To create a custom report

Reporting Tool

105

1. 2.

In the details pane, on the report toolbar, click

Create or

Save As.

In Report Name box, type a name for the custom report, and then click OK.

Modifying the Time Interval


By default, built-in reports display data for the last hour. However, you can change the time interval and save the report as a custom report. The new interval applies to all charts in the report. The following table describes the time-interval options. Time intervals
Time interval Last hour Last day Last week Last month Last year Custom time period Displays Statistics data collected for the last hour. Statistics data collected for the last day (24 hours). Statistics data collected for the last week (7 days). Statistics data collected for the last month (31 days). Statistics data collected for the last year (365 days). Statistics data collected for a time period that you are prompted to specify.

To modify the time interval

1. 2.

In the navigation pane, click a report. In the details pane, on the report toolbar, click a time period (for example, Hour, Day, Week, Month, Year, and Custom).

Setting the Data Source and Time Zone


You can retrieve data from different data sources to display them in the reports. For information on data sources, see How Data Collection Works, on page 109. You can also define the time zone the reports must use. You can also apply the currently displayed report's time selection to all the reports, including the built-in reports.

106

Citrix NetScaler Administration Guide To set the data source and time zone

1. 2. 3.

In the details pane, on the report toolbar, click Settings. In the Settings dialog box, in Data Source, select the data source from which you want to retrieve the counter information. Select the Remember time selection for charts check box if you want to apply the time interval of the currently displayed report to all the existing reports. Select the Use Appliances time zone check box if you want the reports to use the time settings of your NetScaler appliance. Click OK.

4. 5.

Working with Charts


Use charts to plot and monitor counters or groups of counters. You can include up to four charts in one report. In each chart, you can plot up to 16 counters. The counters can use different graphical formats (for example, area and bar). You can move the charts up or down within the report. You can also delete a chart when you do not want to monitor it. In all report charts, the horizontal axis represents time and the vertical axis represents the value of the counter.

Adding a Chart
When you add a chart to a report, the System Overview chart appears with the CPU Usage counter plotted for the last one hour. To plot a different group of statistics or select a different counter, see Modifying a Chart, on page 106. Note: If you add charts in a built-in report, you must save the report as a custom report. Use the following procedure to add a chart in a report.
To add a chart

1. 2.

In the navigation pane, click a report. In the details pane, on the toolbar for the chart beneath which you want to add the new chart, click the Add icon.

Modifying a Chart
You can modify a chart by changing the functional group for which the statistics are displayed, and by selecting different counters.

Chapter 6 To modify a chart

Reporting Tool

107

1. 2. 3. 4.

In the Navigation pane, click a report. In the details pane, on the toolbar for the chart that you want to modify, click Counters. In the dialog box that appears, in the Chart Title box, type a name for the chart. Next to Plot chart for, select one of the following: System global statistics, if you want to plot counters for global counters, such as Integrated Cache and Compression. System entities statistics, if you want to plot entity counters for entity types, such as Load balancing and GSLB.

5. 6.

In the Counters area, under Available, click the counter name(s) you want to plot, and then click the > button. If you selected System entities statistics in step 4, click the Entities tab and, under Available, click the entity instance name(s) you want to plot, and then click the > button. Click OK.

7.

Viewing Different Graph Types of a Chart


You can specify the graphical formats of the plotted counters in a chart. The following graph types are supported. Graph types
Graph type Line Area Bar Stacked Area Stacked Bar Displays statistics as Line chart Area chart Bar chart Stacked area chart Stacked bar chart

108

Citrix NetScaler Administration Guide To change the graph type of a chart

1. 2.

In the navigation pane, select a report (either built-in or custom report). In the details pane, under the chart you want to view, on the chart toolbar, click a graph type, such as Area and Bar. Note: If you have selected a built-in report, you need to save this report as a custom report, or the changes will be lost.

Deleting a Chart
If you do not want to use a chart, you can remove it from the report. You can permanentely remove charts from custom reports only. If you delete a chart from a built-in report, you need to save the report as a custom report.
To delete a chart

1. 2.

In the navigation pane, select a report. In the details pane, on the toolbar for the chart that you want to delete, click the Delete icon.

Examples
To display the trend report for CPU usage and memory usage for the last one day.

1. 2. 3.

In the navigation pane, under Built-in Reports, expand System. Click report CPU vs. Memory Usage and HTTP Requests Rate. On the report tool bar, click a time period (for example, Day).

To compare bytes received rate and bytes transmitted rate between two interfaces for the last week

1. 2.

In the details pane, on the report toolbar, click

Create.

In the Report Name box, type a name for the custom report (for example, Custom_Interfaces), and then click OK. The report is created with the default System Overview chart, which displays the CPU Usage counter plotted for the last hour. In the details pane, under System Overview, on the chart toolbar, click Counters.

3.

Chapter 6

Reporting Tool

109

4. 5. 6. 7.

In the counter selection pane, in the Chart title box, type a name for the chart (for example, Interfaces_bytes_received_and_transmitted). In Plot chart for, click System entities statistics, and then in Select Group, select Interface. In Entities, click the interface name(s) you want to plot (for example, 1/1 ans 1/2), and then click the > button. In Counters, click the counter name(s) you want to plot (for example, Bytes received (Rate) and Bytes transmitted (Rate)), and then click the > button. Click OK. On the report toolbar, click a time period (for example, Week).

8. 9.

How Data Collection Works


The performance data is stored in different data sources in the NetScaler. The default data source is /var/log/db/default. You can create up to 32 data sources. The data collection utility nscollect retrieves data from the NetScaler and updates the data source. This utility runs automatically when you start the NetScaler. It creates a database for global counters at /var/log/db/ DataSourceName. The entity-specific databases are created based on the entities configured on the NetScaler. A specific folder is created for each entity type in /var/log/db/DataSourceName/EntityNameDB. Before creating a database for an entity, nscollect allocates a unique number to the entity and creates the database based on that number. It retrieves all the counters available for a group. However, there is a limit on the number of different entities that you the nscollect can retrieve, as described in the table Limits on entity numbers, on page 109. The nscollect utility retrieves n number of entity counters and creates the entity database. If the first n counters change in the subsequent fetch, the database stores more than n entries for that entity type. However, you need to delete the unused entity counters manually. Note: The Reporting tool supports only numerical counters. Limits on entity numbers
Entity Name Content Switching Virtual Servers Limit 100

110

Citrix NetScaler Administration Guide

Limits on entity numbers


Entity Name Cache Redirection Virtual Servers DOS Policies GSLB Domains GSLB Services GSLB Sites GSLB Virtual Servers Interfaces LB Virtual Servers ACLs ACL6 Priority Queuing Policies RNAT IP Addresses SureConnect Policies Services Service Groups System CPU VLAN VPN Virtual Servers Limit 50 100 100 100 32 100 8 100 100 50 100 100 100 250 100 8 25 5

By default, nscollect retrieves data at every 5-minute interval. Data is maintained in 5-minute granularity for one day, hourly for the last 30 days, and daily for three years. The nscollect utility can also import data from the newnslog file (within the same release or across releases) to the data source. For more information on importing from newnslog files, see Importing Data from the newnslog File, on page 111.

Stopping and Starting the Data Collection Utility


When you start the NetScaler, the nscollect utility automatically starts. However, if data is not updated accurately, or there is corrupted data displayed in the reports, you can stop and then restart the utility. You may also want to stop nscollect to back up the databases or if you want to create a new data source.

Chapter 6 To stop nscollect

Reporting Tool

111

At a NetScaler command prompt, type the following:


/netscaler/nscollect stop

You can start nscollect on either the local system or a remote system.
To start nscollect on the local system

At a NetScaler command prompt, type the following:


/netscaler/nscollect start

To start nscollect on the remote system

At a NetScaler command prompt, type the following:


/netscaler/nscollect start -U NS_IP:UserName:Password -ds DataSourceName

Example
/netscaler/nscollect start -U 10.102.29.170:nsroot:nsroot -ds default

Importing Data from the newnslog File


The nscollect utility can import data from the newnslog files (within the same release or across releases) to the data source. When you set nscollect to import data from a newnslog file, it by default imports the data at 5-minute intervals. However, you can set nscollect to import data from a newnslog file for a specific duration. Before importing data from the file, you can clean the data source. You must clean the data source before importing data from multiple files if you import the data in any order other than that in which the newslog files were created (that is, using the incremental method in temporal order). Use one of the following procedures to import data from newnslog files.
To import data from a file at the default time interval

At a NetScaler command prompt, type the following command:


/netscaler/nscollect import -file FileName -ds DataSourceName

Example
/netscaler/nscollect import -file newnslog.24 -ds default

To import data from a file for a specific duration

At a NetScaler command prompt, type the following command:

112

Citrix NetScaler Administration Guide

/netscaler/nscollect import -file FileName -ds DataSourceName starttime MMDDYYYYHHMM -endtime MMDDYYYYHHMM

Example
/netscaler/nscollect import -file newnslog.3 -ds default -starttime 112220080735 -endtime 112320080735

To clean the data source and import data

At a NetScaler command prompt, type the following command:


/netscaler/nscollect import -file FileName -ds DataSourceName -clean

Example
/netscaler/nscollect import -file newnslog.15 -ds default -clean