Вы находитесь на странице: 1из 126

Citrix NetScaler Administration Guide

Citrix NetScaler 9.0

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, 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
New in This Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii
Formatting Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Related Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Getting Service and Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .x
Knowledge Center. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .x
Silver and Gold Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Education and Training . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
Defining SNMP Managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
Configuring SNMP V1 and V2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
Adding an SNMP Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
Removing an SNMP Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
Configuring SNMP Traps and Alarms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
SNMP V3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
Salient Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
SNMPv3 Security Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Configuring SNMP V3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43

iv

Citrix NetScaler Administration Guide

Chapter 3

Audit Server Logging


Configuring the Citrix NetScaler Audit Server Log . . . . . . . . . . . . . . . . . . . . . . . .50
Configuring Global Audit Server Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . .51
Configuring Audit Server Action and Policy . . . . . . . . . . . . . . . . . . . . . . . . . . .52
Globally Binding the Audit Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
Installing the Audit Server Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
Installing Audit Server on the Linux Operating System . . . . . . . . . . . . . . . . . .54
Uninstalling Audit Server on the Linux Operating System . . . . . . . . . . . . . . . .55
Installing Audit Server on the FreeBSD Operating System. . . . . . . . . . . . . . . .55
Uninstalling Audit Server on the FreeBSD Operating System . . . . . . . . . . . . .56
Installing Audit Server on the Windows Operating System . . . . . . . . . . . . . . .56
Uninstalling Audit Server on the Windows Operating System . . . . . . . . . . . . .57
Audit Server Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
Configuring Audit Server Logging on a Server system. . . . . . . . . . . . . . . . . . . . . .59
Defining Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
Defining Log Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Default Settings for the Log Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
Adding the IP Addresses of the System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Verifying Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Starting Audit Server Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Stopping Audit Server Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Sample Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Checklist for Configuring Audit Server Logging. . . . . . . . . . . . . . . . . . . . . . . .65
Configuring Audit Server Logging for a Commonly Used Deployment Scenario.66

Chapter 4

Web Server Logging


How Web Server Logging Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71
Configuring Web Server Logging Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . .72
Enabling or Disabling Web Server Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . .72
Modifying the Default Buffer Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72
Displaying Web Server Logging Information . . . . . . . . . . . . . . . . . . . . . . . . . .73
System Requirements for Web Server Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . .74

Contents

Installing the NSWL files on the Logging System . . . . . . . . . . . . . . . . . . . . . . . . .75


Installing NSWL on a Solaris Operating System . . . . . . . . . . . . . . . . . . . . . . . .75
Installing NSWL on a Linux Operating System. . . . . . . . . . . . . . . . . . . . . . . . .76
Installing NSWL on a FreeBSD Operating System . . . . . . . . . . . . . . . . . . . . . .76
Installing NSWL on a MAC Operating System . . . . . . . . . . . . . . . . . . . . . . . . .77
Installing NSWL on a Windows Operating System. . . . . . . . . . . . . . . . . . . . . .78
Installing NSWL on an AIX Operating System . . . . . . . . . . . . . . . . . . . . . . . . .79
NSWL Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79
Configuring Web Server Logging on the Logging System . . . . . . . . . . . . . . . . . . .80
Modifying the Web Server Log Configuration File . . . . . . . . . . . . . . . . . . . . . .81
Defining Log Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
Adding the IP Addresses of the NetScaler . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Verifying the Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Starting Web Server Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Stopping Web Server Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Sample Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Log File Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
Custom Log Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95
Apache Log Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Checklist for Configuring Web Server Logging . . . . . . . . . . . . . . . . . . . . . . . . . .100

Chapter 5

Advanced Configurations
Configuring Clock Synchronization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
Configuring Clock Synchronization Manually. . . . . . . . . . . . . . . . . . . . . . . . .103
Configuring Clock Synchronization Using the Configuration Utility or the CLI .
105
Path Maximum Transmission Unit Discovery. . . . . . . . . . . . . . . . . . . . . . . . . . . .108
The NetScaler in Transparent Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
The NetScaler in End-Point Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
Enabling or Disabling PMTU Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
Configuring TCP Window Scaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
Configuring Selective Acknowledgement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111
Clearing the Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112

Chapter 6

Reporting Tool
Using the Reporting Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115
Working with Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
Working with Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122

vi

Citrix NetScaler Administration Guide

How Data Collection Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123


Stopping and Starting the Data Collection Utility . . . . . . . . . . . . . . . . . . . . . .124
Importing Data from the newnslog File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125

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.

viii

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


Following is a list of the new features and enhancements in the 9.0 of Citrix
NetScaler.
Note: The documentation has been reorganized. The information in this guide,
Citrix NetScaler Administration Guide, was formerly located in the now
obsolete Citrix Installation and Configuration Guide (ICG). Both Volume 1 and
Volume 2 of the ICG have been divided into eight new guides. This breakdown
into smaller guides was based on audience and task analysis and provides more
efficient access to information. For more information about documentation, see
Related Documentation, on page ix.

Use new SNMP traps and alarms. For more information, see Configuring
SNMP Traps and Alarms, on page 34.

Install the NSWL executable on the AIX platform. For more information,
see Installing NSWL on an AIX Operating System, on page 79.

Use new log format when defining log format in the NSWL. For more
information, see Manually Defining a Custom Log Format, on page 96.

Configure NTP servers and enable NTP synchronization from the GUI and
the NetScaler CLI. For more information, see Configuring Clock
Synchronization Using the Configuration Utility or the CLI, on page 105.

Audience
This guide is intended for the following audience:

system administrators

network administrators

Preface

ix

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

Meaning

Boldface

Information that you type exactly as shown (user input);


elements in the user interface.

Italics

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).

Monospace

[ brackets ]

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]

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.

From a Web browser, log on to the NetScaler.

Citrix NetScaler Administration Guide

2.

Click the Documentation tab.

3.

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/.
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)

Preface

xi

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:

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.

xii

Citrix NetScaler Administration Guide

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.

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

1.

Go to the Knowledge Center home page at http://support.citrix.com/.

2.

On the Knowledge Center home page, under Products, click NetScaler


Application Delivery, and click NetScaler Application Delivery
Software 9.0.

3.

On the Documentation tab, click the guide name, and then click Article
Feedback.

4.

On the Documentation Feedback page, complete the form, and then click
Submit.

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.
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 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

Specifies

User Name

Name that the user enters to request


access.

Password

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.

In the navigation pane, expand System and click Users.

2.

On the System Users page, Click Add.

3.

In the Create System User dialog box, in the User Name text box, type a
name for the user (for example, johnd).

4.

In the Password text box, type a password to assign to the user.

5.

In the Confirm Password text box, again type the password that you have
typed in the Password text box.

6.

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

Specifies

Password

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.

In the navigation pane, expand System and click Users.

2.

On the System Users page, select the user account for which you want to
change the password (for example, johnd) and click Change Password.

3.

In the Password text box, type the new password.

4.

In the Confirm Password text box, type the new password again.

5.

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.

In the navigation pane, expand System and click Users.

2.

On the System Users page, select the user account that you want to
remove. For example, johnd.

3.

Click Remove. The Remove pop-up window appears.

4.

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 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

Specifies

Group Name

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.

In the navigation pane, expand System and click Groups.

2.

On the System Groups page, click Add.

3.

In the Create System Group dialog box, in the Group Name text box,
type a name for the group (for example, Managers).

4.

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

Specifies

User Name

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.

In the navigation pane, expand System and click Groups.

2.

On the System Groups page, select a group and click Open.

3.

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.

In the navigation pane, expand System and click Groups.

2.

On the System Groups page, select the group that you want to remove. (for
example, Managers).

3.

Click Remove.

4.

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 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

Read-only access to all show commands except show


runningconfig, show ns.conf, and the show commands for the
NetScaler command group.

operator

Read-only access and access to commands to enable and disable


services and servers or place them in ACCESSDOWN mode.

network

Full access except to NetScaler commands, the shell command, and the
show ns.conf and sh runningconfig commands.

superuser

Full access. Same privileges as the nsroot user.

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

Matches these Commands

^rm\s+.*$

All remove actions, because all remove actions begin


with the rm string, followed by a space and
additional parameters and flags.

^show\s+.*$

All show commands, because all show actions begin


with the show string, followed by a space and
additional parameters and flags.

^shell$

The shell command alone, but not combined with


any other parameters or flags.

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

All create a vserver actions, which consist of the add


vserver command followed by a space and additional
parameters and flags.

^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 Citrix NetScaler Administration Guide

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

Policy Name

Command Specification Regular Expression

read-only

(^man.*)|(^show\s+(?!system)(?!ns ns.conf)(?!ns
runningConfig).*)|(^stat.*)

operator

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

network

^(?!shell)\S+\s+(?!system)(?!ns ns.conf)(?!ns
runningConfig).*

superuser

.*

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

Parameter

Specifies

User Name

Name of the command policy.

Command Spec

Rule expression that the policy uses to


pattern match.

Action

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.

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

2.

On the Command Policies page, click Add.

3.

In the Create Command Policy dialog box, in the Policy Name text box,
type a name for the command policy (for example, read_all).

4.

In the Action list, select the action (for example, Allow).

5.

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).

6.

Click Create.

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

Specifies

User Name

The user account

Policy Name

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.

In the navigation pane, expand System and click Users.

2.

On the System Users page, select a user (for example, johnd)

10

Citrix NetScaler Citrix NetScaler Administration Guide

3.

Click Open.

4.

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.

5.

In the Priority list box, for each active policy, enter a priority number for
the policy (for example, 1), or adjust the number.

6.

Click OK.

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

Specifies

Group Name

Name of the group.

Policy Name

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.

In the navigation pane, expand System and click Groups.

2.

On the System Groups page, select a group (for example, Managers)

3.

Click Open.

4.

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.

5.

In the Priority list box, for each active policy, enter a priority number for
the policy (for example, 2), or adjust the number.

6.

Click OK.

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.

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

2.

On the Command Policies page, select the command policy to be removed


(for example, Managers_pol).

3.

Click Remove.

4.

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 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

5.

Using a text editor of your choice, edit the /flash/nsconfig/


ns.conf file and remove the set system user nsroot entry.

6.

Save the file and exit the text editor.

7.

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.

Follow the prompts to change the password.

10.

Exit the config ns menu.

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

Value

Note

NetScaler
hostname

ns01.example.net

User accounts

johnd
mariar
michaelb

John Doe, IT manager


Maria Ramirez, IT administrator
Michael Baldrock, IT administrator

Groups

Managers
SysOps

All managers
All IT administrators

Command
Policies

read_all
modify_lb
modify_all

Allow complete read-only access


Allow modify access to load balancing
Allow nearly complete modify access

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 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.

In the navigation pane, expand System and click Users.

2.

On the System Users page, Click Add.

3.

In the Create System User dialog box, in the User Name text box, type
johnd.

4.

In the Password text box, type a password to assign to the user.

5.

In the Confirm Password text box, again type the password that you have
typed in the Password text box.

6.

Click Create.

7.

Repeat steps 26 to create user accounts and passwords for Maria


Ramirez and Michael Baldrock.

To create groups Managers and SysOps

1.

In the navigation pane, expand System and click Groups.

2.

On the System Groups page, click Add.

3.

In the Create System Group dialog box, in the Group Name text box,
type Managers.

4.

Click Create, and click Close.

5.

Repeat steps 14 to create a group named SysOps.

To bind users to a group

1.

In the navigation pane, expand System and click Groups.

2.

On System Groups page, select the Managers group and click Open.

3.

In the Configure System Group dialog box, under Members, select johnd
in the Available Users list.

4.

Click Add to move johnd to the Configured Users list.

5.

Click OK, and click Close.

6.

Repeat steps 14 to bind users mariar and michaelb to the group SysOps.

To add command policies

1.

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

2.

On the Command Policies page, click Add.

Chapter 1

Citrix NetScaler Authentication and Authorization

15

3.

In the Create Command Policy dialog box, in the Policy Name text box,
type read_all.

4.

In the Action list, select Allow.

5.

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).

6.

Click Create.

7.

Repeat steps 16, to create a command policy named modify_lb with


action as Allow and the command spec ^set\s+lb\s+.*$

8.

Repeat steps 16, to create a command policy named modify_all with


action as Allow and the command spec ^\S+\s+(?!system).*

To bind a command policy to a group

1.

In the navigation pane, expand System and click Groups.

2.

On the System Groups page, select the Managers group.

3.

Click Open.

4.

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.

5.

Click OK.

6.

Repeat steps 15 to bind the read_all command policy to the SysOps


group, also assigning it a priority of 1.

To bind a command policy to a user

1.

In the navigation pane, expand System and click Users.

2.

On the System Users page, select the michaelb user account.

3.

Click Open.

4.

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.

5.

Click OK.

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 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

30

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
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

31

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

Specifies

IP Address

IP/Network address of the management


station.

Netmask

Subnet of management stations. Used to


grant access from entire subnets to the
NetScaler.

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


To add an SNMP manager using the configuration utility

1.

In the navigation pane, expand System, click SNMP, and click Managers.

2.

In the Add SNMP Manager dialog box, click Add.

3.

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).

4.

Click Add.

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

32

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.

In the navigation pane, expand System, click SNMP, and then click
Managers.

2.

On the SNMP Managers page, select the manager which you want to
remove.

3.

Click Remove.

4.

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

33

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

Community Name

SNMP community string.

Permissions

Access privileges. Possible


values: GET, GET NEXT, GET
BULK, ALL.

To add an SNMP community string

1.

In the navigation pane, expand System, click SNMP, and then click
Community.

2.

On the SNMP Community page, click Add.

3.

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).

4.

In Permission, select the ALL option.

5.

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.

In the navigation pane, expand System, click SNMP, and then click
Community.

2.

On the SNMP Community page, select the community that you want to
remove (for example, Com_All).

3.

Click Remove.

4.

In the Remove dialog box, click Yes.

34

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

Indicates

authenticationFailure

An SNMP management application without access


privileges has attempted to access the NetScaler.

coldStart

An SNMP entity configured as an agent has reinitialized


itself. Its configuration may have been altered.

linkUp

The sending protocol entity recognizes that one of the


communication links represented in the agent's
configuration has come up.

linkDown

The sending protocol entity recognizes a failure in one of


the communication links represented in the agent's
configuration.

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

Specific trap

Indicates

averageCpuUtilization

Average CPU usage in the multi-processor


NetScaler has exceeded the high threshold.

Chapter 2

SNMP

35

Specific trap

Indicates

averageCpuUtilizationNormal

Average CPU usage in the multi-processor


NetScaler has come back to normal after
exceeding the predefined threshold .

changeToPrimary

The NetScaler has become the primary node in a


High Availability configuration.

changeToSecondary

The NetScaler has become the secondary node in


a High Availability configuration.

cpuUtilization

CPU utilization has exceeded the threshold.

cpuUtilizationNormal

CPU utilization has returned to normal after


exceeding the threshold and generating a
cpuUtilization trap.

diskUsageHigh

Disk usage has exceeded the threshold.

diskUsageNormal

Disk usage has returned to normal.

entityup

State of the interface, vserver, or physical service


has changed to UP.

entitydown

State of the interface, vserver, or physical service


has changed to DOWN.

fanSpeedLow

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.

fanSpeedNormal

A fan speed has returned to normal.

interfaceThroughputLow

Interface throughput has fallen below an alarm


threshold.

interfaceThroughputNormal

Interface throughput has returned to normal.

maxClients

Number of clients for a service has reached the


maximum allowed for that service.

maxClientsNormal

Number of clients for a service has fallen below


70% of maximum number allowed for that
service, after causing a maxClient trap.

memoryUtilization

Memory utilization has exceeded the predefined


threshold.

memoryUtilizationNormal

Memory utilization has returned to normal after a


memoryUtilization trap.

monRespTimeoutAboveThresh

Response time for a monitor probe has exceeded


the configured threshold.

36

Citrix NetScaler Administration Guide

Specific trap

Indicates

monRespTimeoutBelowThresh

Response time for a monitor probe is below the


threshold, indicating that response time has
returned to normal.

netscalerLoginFailure

A user 's atempt to log in to the NetScaler has


failed.

NetScalerConfigChange

Your NetScaler configuration has changed.


Note: This trap is not generated when the
configuration is restored from the ns.conf file.

netScalerConfigSave

The NetScaler configuration has been saved.

serviceRequestRate

Request rate on a service has exceeded the


threshold.

serviceRequestRateNormal

Request rate on a service has returned to normal.

serviceRxBytesRate

Request bytes/s of a service has exceeded a


threshold value.

serviceRxBytesRateNormal

Request bytes/s of a service has returned to


normal.

serviceTxBytesRate

Response bytes/s of a service exceeded a


threshold value.

serviceTxBytesRateNormal

Response bytes/s of a service has returned to


normal.

serviceSynfloodRate

The number of unacknowledged syns for a


service has exceeded a threshold value.

serviceSynfloodNormal

The number of unacknowledged syns for a


service has returned to normal.

sslCertificateExpiry

A SSL certificate is due to expire.

svcGrpMemberRequestRate

Request rate on a service group member has


exceeded a threshold value.

svcGrpMemberRequestRateNormal

Request rate on a service group member has


returned to normal.

svcGrpMemberRxBytesRate

Request bytes per second of a service group has


exceeded a threshold value.

svcGrpMemberRxBytesRateNormal

Request bytes per second of a service group has


returned to normal.

svcGrpMemberTxBytesRate

Response bytes per second of a service group has


exceeded a threshold value.

Chapter 2

SNMP

37

Specific trap

Indicates

svcGrpMemberTxBytesRateNormal

Response bytes per second of a service group has


returned to normal.

svcGrpMemberSynfloodRate

Number of unacknowledged SYN packets for a


service group has exceeded a threshold value.

svcGrpMemberSynfloodNormal

Number of unacknowledged SYN packets for a


service group has returned to normal.

svcGrpMemberMaxClients

Number of clients has reached the maxClients


value for a service group member.

svcGrpMemberMaxClientsNormal

Number of clients has fallen below 70% of


maxClients value for a service group member.

synflood

Rate at which unacknowledged SYN packets are


received has exceeded the threshold.

synfloodNormal

Rate at which unacknowledged SYN packets are


received has returned to normal.

temperatureHigh

Temperature has gone high. The temperature is


measured in degree centigrade (0C).

temperatureNormal

Temperature has returned to normal.

vServerRequestRate

Request rate on a vserver has exceeded the


predefined threshold.

vServerRequestRateNormal

Request rate on a vserver has returned to normal.

vserverRxBytesRate

Request bytes/s of a vserver has exceeded the


threshold value.

vserverRxBytesRateNormal

Request bytes/s of a vServer has returned to


normal.

vserverTxBytesRate

Response bytes/s of a vserver has exceeded a


threshold value.

vserverTxBytesRateNormal

Response bytes/s of a vServer has returned to


normal.

vserverSynfloodRate

Number of unacknowledged syns for a vserver


has exceeded a threshold value.

vserverSynfloodNormal

Number of unacknowledged syns for a vserver


has returned to normal.

voltageLow

A voltage has fallen below the threshold value.

voltageNormal

A voltage has returned to normal.

38

Citrix NetScaler Administration Guide

Specific trap

Indicates

voltageHigh

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

OS versions of the NetScalers in a High


Availability configuration do not match.

haSyncFailure

Configuration synchronization has failed on


secondary node.

haNoHeartbeats

High Availability heartbeats are not received by


the primary node from the secondary.

haBadSecState

State of the secondary node has changed to


DOWN, UNKNOWN, or STAY SECONDARY .

powerSupplyFailed

Power supply has failed.

powerSupplyNormal

The power supply has returned to service.

interfaceBWUseHigh

Bandwidth usage of any of the interfaces of the


NetScaler has exceeded the threshold value.

interfaceBWUseNormal

Bandwidth usage of any of the interfaces of the


NetScaler has returned to normal

aggregateBWUseHigh

Aggregate bandwidth usage of the NetScaler has


exceeded the threshold value.

aggregateBWUseNormal

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

Specifies

Trap Class

The Trap type. Possible values: generic


and specific.

Version

SNMP version of the trap PDU to be


sent.

Chapter 2

Parameter

SNMP

39

Specifies
IP address of the trap destination.

Destination IP Address
Destination Port

Destination port of the trap. Default:


162. Minimum value: 1

Source IP Address

Source IP of the traps.

Severity

Minimum severity of the alarm


resulting in this trap. Default:
Informational (any alarm).

Community Name

The community string. Default: public.

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


To add an SNMP Trap using the configuration utility

1.

In the navigation pane, expand System, click SNMP, and click Traps.

2.

On the Traps page, click Add.

3.

In Version, select an SNMP Version (for example, V1).

4.

In the Destination IP Address text box, type the IP address that is to


receive the trap (for example, 10.102.29.3).

5.

In the Destination Port text box, type the destination port (for example,
163).

6.

In the Source IP text box, type the source IP address of the trap (for
example, 10.102.29.54).

7.

In Minimum Severity, select a severity option (for example, Major).

8.

In the Community Name text box, type the name of the SNMP string that
you want to include in the trap (for example, com1).

9.

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

40

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.

In the navigation pane, expand System, click SNMP, and then click Traps.

2.

On the SNMP Traps page, select the trap that you want to remove.

3.

Click Remove.

4.

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.

In the navigation pane, expand System, expand SNMP, and click Alarms.

2.

On the SNMP Alarms page, select an alarm (for example, Login-Failure).

3.

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

Specifies

Severity

Severity level of this alarm. Possible


values: Critical, Major, Minor, Warning,
Informational. Default: Informational.

Chapter 2

SNMP

41

To set the severity of SNMP alarm

1.

In the navigation pane, expand System, expand SNMP, and click Alarms.

2.

Click Open.

3.

In the Configure SNMP Alarm dialog box, in Severity, select a severity


option (for example, Major).

4.

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

Specifies

Logging

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.

In the navigation pane, expand System, expand SNMP, and then click
Alarms.

2.

Click Open.

3.

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.

4.

Click Ok.

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

42

Citrix NetScaler Administration Guide


Example
set snmp alarm LOGIN-FAILURE -logging ENABLED

or
set snmp alarm LOGIN-FAILURE -logging DISABLED

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

43

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.

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

Set the Engine ID

Configure Views

Configure Groups

44

Citrix NetScaler Administration Guide

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

Specifies

EngineID

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.

In the navigation pane, expand System, expand SNMP, and click Users.

2.

On the SNMP Users page, click Configure Engine ID.

3.

In the Configure Engine ID dialog box, in the Engine ID text box, type an
engine ID (for example, 8000173f0300c095f80c68).

4.

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.
The following table describes the parameters you set to add an SNMP view:

Parameter

Specifies

Name

Name of the SNMP view.

Subtree

Subtree of the MIB.

Chapter 2

SNMP

45

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


To add an SNMP view using the configuration utility

1.

In the Navigation Pane, expand System, expand SNMP, and click View.

2.

On the SNMP View page, click Add.

3.

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).

4.

In the Subtree text box, type the subtree of the MIB.

5.

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

Specifies

Name

Name of the SNMP view.

Read View

SNMP view to be associated with this


group.

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


To add an SNMP group using the configuration utility

1.

In the navigation pane, expand System, expand SNMP, and click Group.

2.

On the SNMP Groups page, click Add.

3.

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).

4.

Click Create and click Close.

46

Citrix NetScaler Administration Guide


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

Specifies

Name

Name of the SNMP user.

Read View

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.

In the navigation pane, expand System, click SNMP, and then click Users.

2.

On the SNMP Users page, click Add.

3.

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).

4.

In Group Name, select the configured SNMP group that you want the user
to be part of.

5.

Click Create and click Close.

To add an SNMP user using the NetScaler command line

At the NetScaler command prompt, type:


add snmp user user name

Example
add snmp user User1

Chapter 2

SNMP

47

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.

48

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

50

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

Specifies

Auditing Type

Type of audit to perform. Possible values: SYSLOG


and NSLOG.

IP Address

IP address of the auditing server. Default: 0.0.0.0.

Port

Port to use to communicate. Default: 3023.

Log Levels

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 51.
Date Format

Format of the date stamp. Possible Values:


MMDDYYYY and DDMMYYYY.

Chapter 3

Audit Server Logging

51

Parameter

Specifies

Log Facility

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

Time zone for the time stamp. Possible values: GMT


and Local. Default: Local.

TCP Logging

Enable or disable logging of TCP events.

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

Level

Specifies

EMERGENCY

Log errors indicating that the NetScaler is experiencing a


critical problem that may make the it unusable.

ALERT

Log problems that are not critical to current operations but


that indicate a need for immediate corrective action to prevent
a critical problem.

CRITICAL

Log critical conditions, which do not restrict current


operations but may escalate to a larger problem.

ERROR

Log messages related to failed NetScaler operations.

WARNING

Log issues that may result in critical errors.

NOTICE

Log the events specified by the INFORMATION setting, but


in greater detail.

INFORMATION

Log all actions taken by the NetScaler. This level is useful for
troubleshooting problems.

DEBUG

Log extensive, detailed information to help developers


troubleshoot problems.

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.

In the Navigation Pane, expand System, and click the Auditing node.

2.

On the Auditing page, under Settings, click global auditing parameters.

52

Citrix NetScaler Administration Guide

3.

In the Configure Auditing Parameters dialog box, in the Auditing Type


drop-down list, select NSLOG.

4.

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.

5.

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.

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.

Select a Date Format option and a Time Zone option.

8.

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.

In the Navigation Pane, expand System, expand Auditing, and click


Policies.

2.

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 50.

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.

4.

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.

5.

Under Log Levels, select the ALL check box or select specific log-level
check boxes.

Chapter 3

Audit Server Logging

53

6.

In the Log Facility drop-down list, select a log facility.

7.

In TCP Logging, click the NONE or ALL option.

8.

Select a Date Format option and a Time Zone option for the time stamp.

9.

Click Create and click Close.

To configure an audit server policy

1.

In the Navigation Pane, expand System, expand Auditing, and select


Policies.

2.

On the Policies page, select the Policies tab, and click Add.

3.

In the Create Auditing Policy dialog box, in the Name text box, type a
name for the policy (for example, nspol1).

4.

In the Auditing Type drop-down list, select NSLOG.

5.

In the Server drop-down list, select the server for which the policy applies.

6.

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.

In the Navigation Pane, expand System, expand Auditing, and click


Policies.

2.

On the Policies page, in the Policies tab, click Global Bindings.

3.

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.)

4.

In the Priority list box, enter or adjust the priority (for example, click the
down arrow until 0 appears).

5.

Click OK.

54

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

Software Requirements

Windows

Windows XP Professional - Version 2002


Windows 2003 server
Windows 2000/NT

Linux

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

FreeBSD 4.9
Hardware Requirements

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

/usr/local/netscaler/bin

/usr/local/netscaler/samples

Audit Server Logging

55

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.

Change to the <target directory>:


cd /<target directory>

3.

Use the following command to install the package:

56

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.

2.

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

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

57

<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.

At a command prompt, change to the following directory:


cd \NS\BIN

2.

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

Specifies

audserver -help

Lists all the available Audit Server options

audserver -addns -f
<path to configuration
file>

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.

58

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

Windows Only

audserver -remove

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

59

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.

Install audit server logging as described in Installing the Audit Server


Files, on page 54.

2.

Using a text editor, make the following changes in the auditlog.conf file:

3.

A.

Add the IP address of the audit server in the MYIP field.

B.

Define the log filters and log properties.

C.

Add the IP address of the Citrix NetScaler System.

D.

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.

60

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

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.

61

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 65.
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

62

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 65.

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

63

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

Password

specifies the password, for example, nsroot.

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.

64

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
#
#

IP <Specify the NetScaler IP address to

begin filter_nsip
logInterval Hourly

Chapter 3

logFileSizeLimit 10

logDirectory logdir\%A\

logFilenameFormat nsip%{%d%m%Y}t.log

Audit Server Logging

65

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.

Verify that the Citrix NetScaler System username and password are valid.

2.

If there is a firewall between the NetScaler and logging machine, make sure
the RPC 3010/3011 port is open.

3.

Verify that the Citrix NetScaler is accessible from the log machine by doing
the following:

Ping the Citrix NetScaler IP address.

Use FTP and Telnet to access the NetScaler.

4.

Verify that the IP address of the system is present in the configuration file
(auditlog.conf).

5.

Verify that the Audit Server IP address is entered in the MYIP field in the
auditlog.conf file.

66

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

Value

Name

audit1

Auditing Type

NSLOG

IP Address

10.102.1.1

Port

3024

Log Level

NOTICE

TCP Logging

ALL

Date Format

DDMMYYYY

Log Facility

LOCAL0

Chapter 3

Audit Server Logging

67

Parameters for Audit Server Logging Configuration


Parameter

Value

Time Zone

Local

To create an audit server action

1.

In the Navigation Pane, expand System, expand Auditing, and click


Policies.

2.

On the Auditing page, select the Servers tab and click Add.

3.

In the Create Auditing Server dialog box, in the Name text box, type
audit1, and in the Auditing Type drop-down list, select NSLOG.

4.

In the IP Address text box, type 10.102.1.1, and in the Port text box, type
3024.

5.

Under Log Levels, select the NOTICE check box, and select the
DDMMYYYY Date format option.

6.

In the Log Facility drop-down list, select LOCAL0, in TCP Logging,


select the ALL option, and in Time Zone, select the Local option.

7.

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.

In the Navigation Pane, expand System, expand Auditing, and click


Policies.

2.

On the Policies page, click Add.

3.

In the Create Auditing Policy dialog box, in the Name text box, type a
name for the policy (for example, auditpol1).

4.

In the Auditing Type drop-down list, select NSLOG, in the Server dropdown list, select audit1.

5.

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.

In the Navigation Pane, expand System, expand Auditing, and click


Policies.

2.

On the Policies page, on the Policies tab, and click Global Bindings.

68

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.

4.

Click OK.

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

69

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!

70

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 72 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

72

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.

In the navigation pane, expand System, and click Settings.

2.

In the Settings page, click advanced features.

3.

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.

4.

Click OK.

5.

In the Enable/Disable Feature(s) dialog box, click Yes.

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

Specifies

Buffer Size

Buffer size (in megabytes) allocated for


log transaction data in the appliance.

Chapter 4

Web Server Logging

73

To configure the buffer size using Configuration Utitlity

1.

In the navigation pane, expand System, and click Settings.

2.

On the Settings, under Settings, click Change global system settings.

3.

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).

4.

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
72.

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.

74

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

MAC
Linux

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

Solaris

Sun Microsystems 5.9 - sun4u Sun Ultra 5/10 UPA/PCI

FreeBSD

FreeBSD 4.9
Hardware Requirements

For Windows / Linux /


FreeBSD

Processor - Intel x86 ~501MHz


RAM - 512 MB
Controller - SCSI

For Solaris 2.6

Processor - UltraSPARC-IIi 400 MHz


RAM - 512 MB
Controller - SCSI

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

75

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.

Change to the temporary directory:


cd /tmp

3.

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

76

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.

Copy the NSweblog.rpm file into a temporary directory:


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

2.

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

Web Server Logging

77

To install NSWL on a FreeBSD operating system

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.

Change to the temporary directory:


cd /tmp

3.

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.

Change to the temporary directory:


cd /tmp

3.

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.)

78

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.

Copy the NSweblog.exe file (winzip executable) into a temporary directory.

2.

The extracted files are installed in the following directories. (The dot
indicates the current directory.)

3.

\NS\BIN

\NS\ETC

\NS\SAMPLES

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

79

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.

Copy the NSweblog.rpm file into a temporary directory:


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

2.

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

Specifies

nswl -help

Display all available nswl options

nswl -addns -f <path to


configuration file>

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).

80

Citrix NetScaler Administration Guide

nswl Command

Specifies

nswl -start -f <path to


configuration file>

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)

Installs the web server logging client as a service in


Windows.

nswl -startservice
(Windows only)

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)

Stop Web server logging.

nswl -remove

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.

Install web server logging.

2.

Modify the web server log configuration file, log.conf.

3.

Define log properties

Chapter 4

Web Server Logging

81

4.

Add the IP addresses of the Citrix NetScaler System to the log.conf file.

5.

Verify the configuration.

6.

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]

82

Citrix NetScaler Administration Guide

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

Parameter

Specifies

filterName

Name of the filter (maximum 64 alphanumeric characters.)

HOST name

Host name of the server for which the transactions are being
logged.

IP ip

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.)

IP ip 2...ip n:

Multiple IP addresses (for example, if the server domain has


multiple IP addresses.)

IP ip NETMASK mask

IP addresses and netmask combination to be used on a subnet.

ON | OFF

Enable or disable the filter to log transactions. If no argument


is selected, the filter is enabled (ON).

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.
Example
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

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

Chapter 4

Web Server Logging

83

<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 ....
logTransactions ...
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 90 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

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

84

Citrix NetScaler Administration Guide


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 90 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.
Example
LogInterval size
LogFileSize 100
LogFileNameFormat Ex%{%m%d%y}t

Chapter 4

Web Server Logging

85

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.

LogTransactions specifies the type of transaction between client and the


server.
Transactions between the client and server are either complete or incomplete. A
complete transaction can be either the server completing the request successfully
or sending back an error code to the client. Incomplete or aborted transactions
occur for many reasons, such as the client closes the browser, network timeout,
messages dropped on NetScaler if policies or rules fail.
The LogTransactions setting has the following possible values:
All: Logs both completed and aborted trasactions
Completed: Logs only completed transactions.
Aborted: Logs only aborted or incomplete transactions.
By default, the LogTransactions value is Completed.
When the LogTransactions setting is set to Aborted, the status code field
will display a zero value for each log entry and the number of received bytes field
will display the number of bytes received from the server until the time the
transaction was aborted or failed

Default Settings for the Log Properties


The following default settings apply to the filter:

LogFormat: W3C Extended

LogInterval: Daily

86

Citrix NetScaler Administration Guide

LogFileSize: 10

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

LogTime (logTime): GMT

LogTransactions: Completed.

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
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

Chapter 4

Web Server Logging

87

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

<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
##########

88

Citrix NetScaler Administration Guide

##########
# 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

W3C

logInterval

Hourly

logFileSizeLimit

10

logFilenameFormat

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

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

Chapter 4

Web Server Logging

89

##########
# 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

NCSA

logInterval

Daily

logFileSizeLimit

40

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

/datadisk5/ORGIN/log/%v/

.gif .jpg .jar

logExclude

#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

NCSA

logInterval

Daily

logFileSizeLimit

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.
##########

90

Citrix NetScaler Administration Guide

#begin IMAGE_SERVER
#

logFormat

W3C

logInterval

Size

logFileSizeLimit

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,
##########

#Filter VHOST_F IP 10.101.2.151 NETMASK 255.255.255.0


#begin VHOST_F
#

logFormat

W3C

logInterval

Daily

logFileSizeLimit

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

Chapter 4

Web Server Logging

91

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

Specifies the IP address of the client computer

User Name

Specifies the user name

Date

Specifies the date of the transaction

Time

Specifies the time when the transaction was completed

Time Zone

Specifies the time zone (Greenwich Mean Time or local


time)

Method

Specifies the request method (for example; GET, POST)

Object

Specifies the URL

HTTP_version

Specifies the version of HTTP used by the client

HTTP_StatusCode

Specifies the status code in the response

Bytes Sent

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 95 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:

92

Citrix NetScaler Administration Guide

#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.

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

Directive

Description

Version: <integer>.<integer>

Displays the version of the extended log file format


used. This document defines version 1.0.

Fields: [<specifier>...]

Identifies the fields recorded in the log.

Software: <string>

Identifies the software that generated the log.

Start-Date: <date> <time>

Displays the date and time at which the log was


started.

End-Date: <date> <time>

Displays the date and time at which logging finished.

Date: <date> <time>

Displays the date and time when the entry was


added.

Remark: <text>

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

Chapter 4

Web Server Logging

93

#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:

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

Specifies

Client.

Server.

Remote.

cs

Client to server.

sc

Server to client.

sr

Server to remote server (prefix used by proxies).

rs

Remote server to server (prefix used by proxies).

Application-specific identifier.

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

94

Citrix NetScaler Administration Guide

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

Identifier

Description

date

Specifies the date on which the transaction was done.

time

Specifies the time when the transaction is done.

time-taken

Specifies the time taken (in seconds) for the transaction to complete.

bytes

Specifies the number of bytes transferred.

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

Description

IP

Specifies the IP address and the port number.

dns

Specifies the DNS name.

status

Specifies the status code.

comment

Specifies the comment returned with status code.

method

Specifies the method.

url

Specifies the URL.

url-stem

Specifies the stem portion of the URL.

url-query

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

Description

Date

Specifies the date on which the transaction is done.

Time

Specifies the time when the transaction is done.

Client IP

Specifies the IP address of the client.

User Name

Specifies the user name.

Service Name

Specifies the service name, which is always HTTP.

Chapter 4

Web Server Logging

Server IP

Specifies the server IP address.

Server Port

Specifies the server port number

Method

Specifies the request method (for example; GET, POST).

Url Stem

Specifies the URL stem.

Url Query

Specifies the query portion of the URL.

Http Status

Specifies the status code in the response.

Bytes Sent

Specifies the number of bytes sent to the server (request size,


including HTTP headers).

Bytes Received

Specifies the number of bytes received from the server (response


size, including HTTP headers).

Time Taken

Specifies the time taken for transaction to complete, in seconds.

Protocol Version

Specifies the version number of HTTP being used by the client.

User Agent

Specifies the User-Agent field in the HTTP protocol.

Cookie

Specifies the Cookie field of the HTTP protocol.

Referer

Specifies the Referer field of the HTTP protocol.

95

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.

96

Citrix NetScaler Administration Guide

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.

Compile the file into an object file.

3.

Link the object file with the NSWL library (and optionally, with third party
libraries) to form a new nswl executable.

4.

Add a %d string at the end of the logFormat string in the log.conf


file.

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.

Chapter 4

Web Server Logging

97

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.
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

Specifies the remote IPv4 address

%A

Specifies the local IPv4 address

%a6

Specifies the remote IPv6 address

%A6

Specifies the local IPv6 address

%B

Specifies the bytes sent, excluding the HTTP headers (response size)

%b

Specifies the bytes received, excluding the HTTP headers (request size)

%d

Specifies a user-defined field

%g

Specifies the Greenwich Mean Time offset


(for example, -0800 for Pacific Standard Time)

%h

Specifies the remote host

%H

Specifies the request protocol

%{Foobar}i

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.

%j

Specifies the bytes received, including headers (request size)

%J

Specifies the bytes sent, including headers (response size)

%l

Specifies the remote log name (from identd, if supplied)

98

Citrix NetScaler Administration Guide

%m

Specifies the request method

%M

Specifies the time taken to serve the request (in microseconds)

%{Foobar}o

Specifies the contents of Foobar: header line(s) in the reply. We support


the USER-AGENT, Referer, and cookie headers.

%p

Specifies the canonical port of the server serving the request

%q

Specifies the query string [prefixed with a question mark (?) if a query
string exists]

%r

Specifies the first line of the request

%s

For requests that were redirected internally, this is the status of the
original request

%t

Specifies the time, in common log format (standard English time


format)

%{format}t

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.

%T

Specifies the time taken to serve the request, in seconds

%u

Specifies the remote user (from auth; may be bogus if return status (%s)
is 401)

%U

Specifies the URL path requested

%v

Specifies the canonical name of the server serving the request

%V

This is the virtual server IPv4 address in the system, if load balancing,
content switching, and/or cache redirection is used.

%V6

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.

Chapter 4

Web Server Logging

99

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.

%%

Specifies the same as %.

%a

Specifies the abbreviated name of the week day for the locale.

%A

Specifies the full name of the week day for the locale.

%b

Specifies the abbreviated name of the month for the locale.

%B

Specifies the full name of the month for the locale.

%C

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.

%d

Specifies the day of month [1,31]; single digits are preceded by 0.

%e

Specifies the day of month [1,31]; single digits are preceded by a blank.

%h

Specifies the abbreviated name of the month for the locale.

%H

Specifies the hour (24-hour clock) [0,23]; single digits are preceded by a 0.

%I

Specifies the hour (12-hour clock) [1,12]; single digits are preceded by a 0.

%j

Specifies the number of the day in the year [1,366]; single digits are preceded by 0.

%k

Specifies the hour (24-hour clock) [0,23]; single digits are preceded by a blank.

%l

Specifies the hour (12-hour clock) [1,12]; single digits are preceded by a blank.

%m

Specifies the number of the month in the year [1,12]; single digits are preceded by
a 0.

%M

Specifies the minute [00,59]; leading 0 is permitted but not required.

%n

Inserts a new line.

%p

Specifies the equivalent of either a.m. or p.m. for the locale.

%r

Specifies the appropriate time representation in 12-hour clock format with %p.

%S

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.

%t

Inserts a tab.

%u

Specifies the day of the week as a decimal number [1,7].


1 represents Sunday, 2 represents Tuesday and so on.

%U

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

100

Citrix NetScaler Administration Guide

%w

Specifies the day of the week as a decimal number [0,6].


0 represents Sunday.

%W

Specifies the number of the week in the year as a decimal number [00,53].
Monday is the first day of week 1.

%y

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).

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.

Make sure that the Citrix NetScaler system user name and password are
valid.

Chapter 4

2.

3.

Web Server Logging

101

Make sure that the Netscaler is accessible from the logging system by doing
the following:

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)

102

Citrix NetScaler Administration Guide

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.

104

Citrix NetScaler Administration Guide

2.

Switch to the shell prompt.

3.

Copy the /etc/ntp.conf file to /nsconfig/ntp.conf.

4.

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.

Create a file and name it rc.netscaler in the /nsconfig directory, if


the file does not already exist in the directory.

7.

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

105

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

Specifies

NTP Server

Name or IP address of the NTP server.

Minimum Poll
Interval

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 Poll
Interval

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).

To add NTP servers using the Configuration Utility

1.

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

2.

On the NTP Servers page, click Add.

3.

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).

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).

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).

106

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.

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

2.

On the NTP Servers page, click the NTP server that you want to modify,
and then click Open.

3.

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).

4.

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).

5.

Click Ok.

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

107

2.

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

3.

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.

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

2.

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.

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

2.

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

108

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

109

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.

In the Navigation Pane, expand System, and then click Settings.

2.

On the Settings page, under Modes & Features click Change modes.

3.

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.

110

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

Specifies

Windows scaling
factor

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.

In the navigation pane, expand System and click Settings.

2.

On the Settings page, under Global Settings, click Change global system
settings.

Chapter 5

Advanced Configurations

3.

In the Configure Global Settings dialog box, under TCP, select the
Windows Scaling checkbox.

4.

In the Factor textbox, type a windows scaling factor (for example, 5).

5.

Click Ok.

111

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.

In the navigation pane, expand System and click Settings.

2.

On the Settings page, under Global Settings, click Change global system
settings.

3.

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

112

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.

In the Navigation Pane, expand System, and then click Diagnostics.

2.

On the Diagnostics page, under Maintenance, click Clear Configuration.

3.

In the Clear Configuration dialog box, for Configuration Level, select an


option (for example, basic).

4.

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

113

114

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.

2.

In the User Name text box, type the user name assigned to your NetScaler.

3.

In the Password text box, type the password.

4.

In the Start in drop-down box, select Reporting.

5.

Click the Login button.

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

116

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

117

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 120.

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

Action

Refresh

Refreshes the report to display the latest performance data.

Print

Prints the report to paper.

Set as default

Displays a default report whenever you log on.

Remove as default

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.

118

Citrix NetScaler Administration Guide

Basic operations on reports


Basic operation

Action

Save as

Saves a report as a new custom report.

Save

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.

In the navigation pane, under Built-in Reports, expand a group (for


example, System).

2.

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 120.

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

Reporting Tool

119

To create a custom report

1.

In the details pane, on the report toolbar, click

Create or

Save As.

2.

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

Displays

Last hour

Statistics data collected for the last hour.

Last day

Statistics data collected for the last day (24 hours).

Last week

Statistics data collected for the last week (7 days).

Last month

Statistics data collected for the last month (31 days).

Last year

Statistics data collected for the last year (365 days).

Custom time period

Statistics data collected for a time period that you are


prompted to specify.

To modify the time interval

1.

In the navigation pane, click a report.

2.

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 123.
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.

120

Citrix NetScaler Administration Guide


To set the data source and time zone

1.

In the details pane, on the report toolbar, click Settings.

2.

In the Settings dialog box, in Data Source, select the data source from
which you want to retrieve the counter information.

3.

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.

4.

Select the Use Appliances time zone check box if you want the reports to
use the time settings of your NetScaler appliance.

5.

Click OK.

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 120.
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.

In the navigation pane, click a report.

2.

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

Reporting Tool

121

To modify a chart

1.

In the Navigation pane, click a report.

2.

In the details pane, on the toolbar for the chart that you want to modify,
click
Counters.

3.

In the dialog box that appears, in the Chart Title box, type a name for the
chart.

4.

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.

In the Counters area, under Available, click the counter name(s) you want
to plot, and then click the > button.

6.

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.

7.

Click OK.

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

Displays statistics as

Line

Line chart

Area

Area chart

Bar

Bar chart

Stacked Area

Stacked area chart

Stacked Bar

Stacked bar chart

122

Citrix NetScaler Administration Guide


To change the graph type of a chart

1.

In the navigation pane, select a report (either built-in or custom report).

2.

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.

In the navigation pane, select a report.

2.

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.

In the navigation pane, under Built-in Reports, expand System.

2.

Click report CPU vs. Memory Usage and HTTP Requests Rate.

3.

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.

In the details pane, on the report toolbar, click

Create.

2.

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.

3.

In the details pane, under System Overview, on the chart toolbar, click
Counters.

Chapter 6

Reporting Tool

123

4.

In the counter selection pane, in the Chart title box, type a name for the
chart (for example, Interfaces_bytes_received_and_transmitted).

5.

In Plot chart for, click System entities statistics, and then in Select
Group, select Interface.

6.

In Entities, click the interface name(s) you want to plot (for example, 1/1
ans 1/2), and then click the > button.

7.

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.

8.

Click OK.

9.

On the report toolbar, click a time period (for example, Week).

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 123.
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

Limit

Content Switching Virtual Servers

100

124

Citrix NetScaler Administration Guide

Limits on entity numbers


Entity Name

Limit

Cache Redirection Virtual Servers

50

DOS Policies

100

GSLB Domains

100

GSLB Services

100

GSLB Sites

32

GSLB Virtual Servers

100

Interfaces

LB Virtual Servers

100

ACLs

100

ACL6

50

Priority Queuing Policies

100

RNAT IP Addresses

100

SureConnect Policies

100

Services

250

Service Groups

100

System CPU

VLAN

25

VPN Virtual Servers

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 125.

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

Reporting Tool

125

To stop nscollect

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:

126

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