NetScaler 12.

Citrix Product Documentation | docs.citrix.com June 7, 2019

NetScaler 12.0

Contents

NetScaler Release Notes 3

Getting started with NetScaler 3

Understanding the NetScaler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Switching features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Security and protection features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Optimization features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Understanding policies and expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Processing order of features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Where does a NetScaler appliance fit in the network? 6

Physical deployment modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
NetScaler as an L2 device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
NetScaler as a packet forwarding device . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

How a NetScaler appliance communicates with clients and servers 7

Understanding NetScaler-owned IP addresses . . . . . . . . . . . . . . . . . . . . . . . . . 8
How Traffic flows are managed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Traffic management building blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
A simple load balancing configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Understanding virtual servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Understanding services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Introduction to the NetScaler product line 12

NetScaler Hardware Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
NetScaler Editions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Supported releases on NetScaler hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Supported browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Install the hardware 14

Access a NetScaler 15
Command line interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
NetScaler GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Configure the ADC for the first time 19

NITRO API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Configure high availability 20

Add a Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2

NetScaler 12.0

Disable high availability monitoring for unused interfaces . . . . . . . . . . . . . . . . . . . 22

Configure a FIPS appliance for the first time 23

Configure secure HTTPS by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Configure secure HTTPS by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Configure secure RPC by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Configure secure RPC by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Common network topologies 27

Set up a common two-arm topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Set up common one-arm topologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

System management settings 29

System settings 30

Packet forwarding modes 32

Enable and disable layer 2 mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Enable and disable layer 3 mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Enable and disable MAC based forwarding mode . . . . . . . . . . . . . . . . . . . . . . . . 35

Network interfaces 37
Virtual LANs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Link aggregate channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Clock synchronization 39

DNS configuration 40
Add a name server by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Add a name server by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

SNMP configuration 41
Add SNMP managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Add SNMP traps listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Configure SNMP alarms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Verify configuration 46
Configuration checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Topology configuration checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Server configuration checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Software features configuration checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Access checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Firewall checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

© 1999-2018 Citrix Systems, Inc. All rights reserved. 3

NetScaler 12.0

Load balance traffic on a NetScaler appliance 49

Load balancing 50
Enable load balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Configure services and a virtual server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Persistence settings 52
Configure persistence based on cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Configure persistence based on server IDs in URLs . . . . . . . . . . . . . . . . . . . . . . . 56

Configure features to protect the load balancing configuration 58

Configure URL redirection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Configure backup virtual servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

A typical load balancing scenario 61

Accelerate load balanced traffic by using compression 63

Compression configuration task sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Enable compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Configure services to compress data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Bind a compression policy to a virtual server . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Secure load balanced traffic by using SSL 70

SSL configuration task sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Enable SSL offload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Create HTTP services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Add an SSL based virtual server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Bind services to the SSL virtual server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Add a certificate key pair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Bind an SSL certificate key pair to the virtual server . . . . . . . . . . . . . . . . . . . . . . 81
Configure support for Outlook web access . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Create an SSL action to enable OWA support . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Create SSL policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Bind the SSL policy to the SSL virtual server . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Features at a glance 87

Application switching and traffic management features 88

SSL Offloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Access Control Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Traffic Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

© 1999-2018 Citrix Systems, Inc. All rights reserved. 4

NetScaler 12.0

Network Address Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Multipath TCP Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Content Switching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Global Server Load Balancing (GSLB) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Dynamic Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Link Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
TCP Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
CloudBridge Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
DataStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Application acceleration features 93

Application security and firewall features 94

Denial of service (DoS) attack defense . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Content Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Rewrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Priority Queuing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Surge Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Citrix Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Application Firewall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Application visibility feature 97

FAQs 98
This section provides the frequently asked questions on the following NetScaler features . . 99

AppFlow 99

Call Home 101

Clustering 104

Connection Management 104

Content Switching 109

Debugging 113

Hardware 114

High Availability 114

© 1999-2018 Citrix Systems, Inc. All rights reserved. 5

NetScaler 12.0

Integrated Caching 117

Content Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Cache policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Memory Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Verification commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Flushing Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Flash Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Default Behaviour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Interoperability with other features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Install, upgrade, and downgrade 126

Install and upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Downgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Install and upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Downgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Load Balancing 135

NetScaler GUI 137

SSL 139

Solutions for Telecom Service Providers 140

Large Scale NAT 141

LSN Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
LSN Features Supported on NetScaler appliance . . . . . . . . . . . . . . . . . . . . . . . . 142

Points to Consider before Configuring LSN 145

Configuration Steps for LSN 147

Configuration Using the Command Line Interface . . . . . . . . . . . . . . . . . . . . . . . 150
Configuration Using the Configuration Utility . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Parameter Descriptions (of commands listed in the CLI procedure) . . . . . . . . . . . . . . 153
Parameter Descriptions (of commands listed in the CLI procedure) . . . . . . . . . . . . . . 153
Parameter Descriptions (of commands listed in the CLI procedure) . . . . . . . . . . . . . . 154
Parameter Descriptions (of commands listed in the CLI procedure) . . . . . . . . . . . . . . 156
Parameter Descriptions (of commands listed in the CLI procedure) . . . . . . . . . . . . . . 156
Parameter Descriptions (of commands listed in the CLI procedure) . . . . . . . . . . . . . . 159
Parameter Descriptions (of commands listed in the CLI procedure) . . . . . . . . . . . . . . 161
Parameter Descriptions (of commands listed in the CLI procedure) . . . . . . . . . . . . . . 162

© 1999-2018 Citrix Systems, Inc. All rights reserved. 6

NetScaler 12.0

Parameter Descriptions (of commands listed in the CLI procedure) . . . . . . . . . . . . . . 165

Sample LSN Configurations 166

Configuring Static LSN Maps 176

To create a static LSN mapping by using the command line interface . . . . . . . . . . . . . 176
To create a static LSN mapping by using the configuration utility . . . . . . . . . . . . . . . 176
Parameter Descriptions (of commands listed in the CLI procedure) . . . . . . . . . . . . . . 177
Wildcard Port Static Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Configuring the NetScaler appliance to Provide Access to All Ports of an IPv4 Subscriber . . 178

Configuring Application Layer Gateways 179

Application Layer Gateway for FTP, ICMP, and TFTP Protocols 180

Application Layer Gateway for PPTP Protocol 182

Configuring PPTP ALG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Application Layer Gateway for SIP Protocol 184

How SIP ALG Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Application Layer Gateway for RTSP Protocol 194

Limitations of RTSP ALG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
RTSP and LSN scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Configuring RTSP ALG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

Application Layer Gateway for IPSec Protocol 198

How IPSec ALG Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
IPSec ALG Timeouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Points to Consider before Configuring IPSec ALG . . . . . . . . . . . . . . . . . . . . . . . . 199
Configuration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Sample Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Logging and Monitoring LSN 202

Logging LSN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Minimal Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

STUN Timeout 228

TCP SYN Idle Timeout 230

Overriding LSN configuration with Load Balancing Configuration 231

To enable override lsn in a net profile by using the CLI . . . . . . . . . . . . . . . . . . . . . 232

© 1999-2018 Citrix Systems, Inc. All rights reserved. 7

NetScaler 12.0

Clearing LSN Sessions 233

To clear all LSN sessions by using the command line interface . . . . . . . . . . . . . . . . . 233
To clear selective LSN sessions by using the command line interface . . . . . . . . . . . . . 233
To clear all LSN sessions by using the configuration utility . . . . . . . . . . . . . . . . . . . 234
Parameter Descriptions (of commands listed in the CLI procedure) . . . . . . . . . . . . . . 234

Load Balancing SYSLOG Servers 235

Load balancing of SYSLOG servers using the configuration utility . . . . . . . . . . . . . . . 236

Port Control Protocol 238

Configuration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

Dual-Stack Lite 241

Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Points to Consider before Configuring DS-Lite 245

Configuring DS-Lite 246

Configuration by Using the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Configuration by Using the Configuration Utility . . . . . . . . . . . . . . . . . . . . . . . . 250
Logging and Monitoring DS-Lite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Displaying Current DS-Lite Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Clearing DS-Lite Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

Configuring DS-Lite Static Maps 255

To create a DS-Lite static LSN mapping by using the command line . . . . . . . . . . . . . . 256
To create a DS-Lite static LSN mapping by using the configuration utility . . . . . . . . . . . 257

Configuring Deterministic NAT Allocation for DS-Lite 257

Example: Deterministic DS-Lite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Configuration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

Configuring Application Layer Gateways for DS-Lite 260

Application Layer Gateway for FTP, ICMP, and TFTP Protocols 261

Application Layer Gateway for SIP Protocol 261

Limitations of SIP ALG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Configuring SIP ALG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

Application Layer Gateway for RTSP Protocol 264

Limitations of RTSP ALG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

© 1999-2018 Citrix Systems, Inc. All rights reserved. 8

NetScaler 12.0

Configuring RTSP ALG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Logging and Monitoring DS-Lite 266

Displaying Current DS-Lite Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Clearing DS-Lite Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Logging HTTP Header Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
IPFIX Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Port Control Protocol for DS-Lite 275

Configuration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

Large Scale NAT64 277

Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Example: Traffic Flow of NAT64 and DNS64 Deployment . . . . . . . . . . . . . . . . . . . . 279
Large Scale NAT64 features Supported on NetScaler appliances . . . . . . . . . . . . . . . . 281

Points to Consider for Configuring Large Scale NAT64 282

Configuring DNS64 283

To create a service of type DNS by using the command line interface . . . . . . . . . . . . . 283
To create a DNS64 action by using the command line interface . . . . . . . . . . . . . . . . 283
To create a DNS64 policy by using the command line interface . . . . . . . . . . . . . . . . 284
To create a DNS load balancing virtual server by using the command line interface . . . . . 284
To bind the DNS services and the DNS64 policy to the DNS load balancing virtual server by
using the command line interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

Configuring Large Scaler NAT64 285

Configuration Using the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Sample Large Scale NAT64 Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

Configuring Application Layer Gateways for Large Scale NAT64 291

Application Layer Gateway for FTP, ICMP, and TFTP Protocols 291

Application Layer Gateway for SIP Protocol 292

Limitations of SIP ALG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Configuring SIP ALG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

Application Layer Gateway for RTSP Protocol 295

Limitations of RTSP ALG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Configuring RTSP ALG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

© 1999-2018 Citrix Systems, Inc. All rights reserved. 9

NetScaler 12.0

Configuring Static Large Scale NAT64 Maps 297

To create a Large Scale NAT64 mapping by using the command line . . . . . . . . . . . . . 297
Wildcard Port Static Large Scale NAT64 Maps . . . . . . . . . . . . . . . . . . . . . . . . . . 298

Logging and Monitoring Large Scale NAT64 299

Logging Large Scale NAT64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Logging MSISDN Information for Large Scale NAT64 . . . . . . . . . . . . . . . . . . . . . . 303
Compact Logging for Large Scale NAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Logging HTTP Header Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Displaying Current Large Scale NAT64 Sessions . . . . . . . . . . . . . . . . . . . . . . . . . 308
Displaying Large Scale NAT64 Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Clearing Large Scale NAT64 Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
IPFIX Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

Port Control Protocol for Large Scale NAT64 312

Configuration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

Mapping Address and Port using Translation 315

Configuring MAP-T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

Telco subscriber management 318

Allocating memory for the subscriber session store module . . . . . . . . . . . . . . . . . . 319
Configure an interface for dynamic subscribers . . . . . . . . . . . . . . . . . . . . . . . . . 319
Configure static subscribers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Default subscriber profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
View and clear subscriber sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Subscriber policy enforcement & management system . . . . . . . . . . . . . . . . . . . . 330
IPv6 prefix based subscriber sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Idle session management of subscriber sessions in a Telco network . . . . . . . . . . . . . 332
Subscriber session event logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Subscriber aware LSN session termination . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

Subscriber aware traffic steering 335

To configure traffic steering for the above deployment by using the CLI . . . . . . . . . . . . 336
To configure traffic steering on the appliance by using the GUI . . . . . . . . . . . . . . . . 339
To configure service chaining on the appliance by using the GUI . . . . . . . . . . . . . . . 340

Subscriber aware service chaining 341

To configure service chaining for the above deployment by using the CLI . . . . . . . . . . . 342
To configure service chaining on the appliance by using the GUI . . . . . . . . . . . . . . . 347

© 1999-2018 Citrix Systems, Inc. All rights reserved. 10

NetScaler 12.0

Policy based TCP profile selection 348

Load Balance Control-Plane Traffic that is based on Diameter, SIP, and SMPP Protocols 349
SIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
SMPP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Diameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

Provide DNS Infrastructure/Traffic Services, such as, Load Balancing, Caching, and Log-
ging for Telecom Service Providers 350

Provide Subscriber Load Distribution Using GSLB Across Core-Networks of a Telecom Ser-
vice Provider 351

Bandwidth Utilization Using Cache Redirection Functionality 352

NetScaler TCP Optimization 353

Getting Started 354

Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
Initial Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
SSH Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

Management Network 356

Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

Licensing 357

High Availability 358

Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

Gi-LAN Integration 359

Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
HA Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

TCP Optimization Configuration 365

TCP Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
TCP Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Silently Dropping Idle Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

Analytics and Reporting 371

Real-time Statistics 371

© 1999-2018 Citrix Systems, Inc. All rights reserved. 11

NetScaler 12.0

SNMP 373
Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Packet Engine CPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
Throughput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Optimized/Bypass connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

Technical Recipes 376

Per-user Connection Limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Smooth Insertion/Deletion of Vserver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
Policy-Based TCP Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377

Scalability 379
Topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
Configuring TCP Optimization in a NetScaler T1000 Cluster . . . . . . . . . . . . . . . . . . 380
Setting Up the Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Distributing Traffic Across Cluster Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Configuring VLAN and IP Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Configuring TCP Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
Configuring Dynamic Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

Optimizing TCP Performance using TCP Nile 385

Congestion Control Strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
NILE Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
Proportional Rate Recovery (PRR) Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . 387
TCP Fast Open (TFO) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
TCP Hystart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
Optimization Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
Policy based TCP Profile Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
SACK Block Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Client Reneging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Memory checks for marking end_point on PCB is not considering total available memory . . 394
Unnecessary retransmissions due to missing SACK blocks . . . . . . . . . . . . . . . . . . . 394
SNMP for number of connections bypassed optimization because of overload . . . . . . . . 394

CQA and Adaptive TCP Optimization 395

Connection Quality Analytics (CQA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Adaptive TCP Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Analytics and Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409

© 1999-2018 Citrix Systems, Inc. All rights reserved. 12

NetScaler 12.0

Troubleshooting Guidelines 410

Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Trace Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
Connection Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411

Frequently Asked Questions 411

Timeouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
Maximum Segment Size Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
Memory Overload Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Support for Happy Eyeballs Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415

NetScaler Video Optimization 416

Getting Started 416

How NetScaler Video Optimization Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
Dynamic Burst Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
Random Sampling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418

Licensing 419

Configuring Video Optimization over TCP 420

Configuring Video Optimization over TCP by using the CLI . . . . . . . . . . . . . . . . . . . 421
Creating Virtual Servers for HTTP and HTTPS Video Traffic . . . . . . . . . . . . . . . . . . . 422
Binding Built-In Detection Policies to an HTTP Load Balancing Virtual Server . . . . . . . . . 422
Binding the HTTP Body Content Detection Policy to Load Balancing Virtual Server . . . . . 424
Binding Built-In Detection Policies to an SSL-Bridge Load Balancing Virtual Server . . . . . . 424
Adding Optimization Policies for Pacing ABR traffic . . . . . . . . . . . . . . . . . . . . . . . 425
Binding Optimization Policies to an HTTP Load Balancing Virtual Server . . . . . . . . . . . 425
Binding Optimization Policies to SSL-bridge Virtual Servers . . . . . . . . . . . . . . . . . . 426
Setting video optimization pacing parameters . . . . . . . . . . . . . . . . . . . . . . . . . 426
Configuring Video Optimization over TCP by using the GUI . . . . . . . . . . . . . . . . . . . 427

Configuring Video Optimization over UDP 431

Configuring video optimization for QUIC by using the CLI . . . . . . . . . . . . . . . . . . . 431
Configuring video optimization for QUIC by using the GUI . . . . . . . . . . . . . . . . . . . 434

NetScaler URL Filtering 437

URL List 438

URL List Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
URL List Policy Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439

© 1999-2018 Citrix Systems, Inc. All rights reserved. 13

NetScaler 12.0

URL List Policy Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
DNS Server for DNS Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
Configuring a URL List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
Importing a custom URL list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
Setting up IWF URL List Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
Configuring a URL List for HTTP traffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
Configuring URL List for HTTPS traffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
Configuring a URL List by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
Configuring Audit Log Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
URL List Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448

URL Categorization 449

How URL Categorization Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
URL Categorization Policy Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
URL Categorization Policy Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
Configuring URL Categorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
Setting up URL Categorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
Configuring URL categorization for HTTP traffic . . . . . . . . . . . . . . . . . . . . . . . . . 454
Configuring URL categorization for HTTPS traffic . . . . . . . . . . . . . . . . . . . . . . . . 455
Configuring URL Categorization by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . 456
Configuring Audit Log Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
Storing Failure Errors Using SYSLOG Messaging . . . . . . . . . . . . . . . . . . . . . . . . . 460
URL Reputation Score . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461

NetScaler Solutions 462

This section includes the following solutions . . . . . . . . . . . . . . . . . . . . . . . . . . 462

Setting Up NetScaler appliance for XenApp/XenDesktop 462

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463

Global Server Load Balancing (GSLB) Powered Zone Preference 464

NetScaler appliance in a Private Cloud Managed by Microsoft Windows Azure Pack and
Cisco ACI 465
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

Creating a NetScaler appliance Load Balancer in a Plan in the Service Management Portal
(Admin Portal) 466

© 1999-2018 Citrix Systems, Inc. All rights reserved. 14

NetScaler 12.0

Configuring a NetScaler appliance Load Balancer by Using the Service Management Portal
(Tenant Portal) 467

Deleting a NetScaler appliance Load Balancer from the Network 469

Deploy a NetScaler VPX instance 469

NetScaler Management and Analytics for NetScaler VPX instances . . . . . . . . . . . . . . 470

Support matrix and usage guidelines 470

Install a NetScaler VPX instance on XenServer 473

Prerequisites for installing a NetScaler VPX instance on XenServer . . . . . . . . . . . . . . 474
Install NetScaler VPX instances on XenServer by using XenCenter . . . . . . . . . . . . . . . 475

Configure VPX instances to use single root I/O virtualization (SR-IOV) network interfaces 476
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
Assign SR-IOV VFs to the VPX instance by using the XenServer host . . . . . . . . . . . . . . 477
Unassign SR-IOV VFs to the VPX instance by using the XenServer host . . . . . . . . . . . . . 478
Configuring VLAN on the SR-IOV Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
Configure VLAN on the SR-IOV interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479

Install a NetScaler VPX instance on VMware ESX 479

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
Install a NetScaler VPX instance on VMware ESX . . . . . . . . . . . . . . . . . . . . . . . . 483

Configure a NetScaler VPX instance to use VMXNET3 network interface 484

Configure a NetScaler VPX instance to use SR-IOV network interface 487

Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487

Migrating the NetScaler VPX from E1000 to SR-IOV or VMXNET3 Network Interfaces 491

Configure a NetScaler VPX instance to use PCI passthrough network interface 492
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
Configure passthrough devices on a host . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
Configure passthrough devices on a NetScaler VPX instance . . . . . . . . . . . . . . . . . . 493

Install a NetScaler VPX instance on Microsoft Hyper-V server 493

Prerequisites for installing NetScaler VPX instance on Microsoft servers . . . . . . . . . . . . 494
Install the NetScaler VPX instance on Microsoft servers . . . . . . . . . . . . . . . . . . . . . 495
Auto-provision a NetScaler VPX instance on Hyper-V . . . . . . . . . . . . . . . . . . . . . . 496

© 1999-2018 Citrix Systems, Inc. All rights reserved. 15

NetScaler 12.0

Install a NetScaler VPX instance on Linux-KVM platform 498

Limitations and usage guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498

Prerequisites for installing a NetScaler VPX instance on Linux-KVM platform 499

Software requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
Guest VM hardware requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
Networking requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
Properties of source interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
Module required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503

Provision the NetScaler VPX instance by using OpenStack 504

Userdata file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504
Network configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
Customer script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
SSH key pair authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
Provisioning the VPX instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508

Provision the NetScaler VPX instance by using the Virtual Machine Manager 510
Check prerequisites for auto-provisioning a NetScaler VPX instance . . . . . . . . . . . . . . 511
Provision the NetScaler VPX instance by using a RAW image . . . . . . . . . . . . . . . . . . 512
Provision the NetScaler VPX instance by using a QCOW2 image . . . . . . . . . . . . . . . . 513
Enable auto-provisioning by attaching a CDROM drive . . . . . . . . . . . . . . . . . . . . . 513
Add additional interfaces to the NetScaler VPX instance by using Virtual Machine Manager . 513

Configure a NetScaler VPX instance to use SR-IOV network interfaces 515

Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
Configure a NetScaler VPX instance to use SR-IOV network interface . . . . . . . . . . . . . 517
Configure static LA/LACP on the SR-IOV interface . . . . . . . . . . . . . . . . . . . . . . . . 518
Configuring VLAN on the SR-IOV Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518

Configure a NetScaler VPX instance to use PCI passthrough network interfaces 519
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519

Provision the NetScaler VPX instance by using the virsh program 520
Add additional interfaces to NetScaler VPX instance using virsh program . . . . . . . . . . . 522

Manage the NetScaler VPX guest VMs 524

Manage the VPX guest VMs by using Virtual Machine Manager . . . . . . . . . . . . . . . . . 524
Manage the NetScaler VPX guest VMs using the virsh program . . . . . . . . . . . . . . . . . 525

© 1999-2018 Citrix Systems, Inc. All rights reserved. 16

NetScaler 12.0

Provision the NetScaler VPX instance with SR-IOV, on OpenStack 526

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
Enable SR-IOV VFs on the host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527
Configure and make the VFs available to OpenStack . . . . . . . . . . . . . . . . . . . . . . 527
Provision the NetScaler VPX instance on OpenStack . . . . . . . . . . . . . . . . . . . . . . 527

Configure a NetScaler VPX instance on KVM to use OVS DPDK-based host interfaces 530
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
Install DPDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
Build and install OVS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
Create an OVS bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
Attach physical interface to the OVS bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
Attach vhost-user ports to the OVS data path . . . . . . . . . . . . . . . . . . . . . . . . . . 532
Provision a KVM-VPX with OVS-DPDK-based vhost-user ports . . . . . . . . . . . . . . . . . 533
Points to note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539

Deploy a NetScaler VPX instance on AWS 540

AWS terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
How a NetScaler VPX instance on AWS works . . . . . . . . . . . . . . . . . . . . . . . . . . 543
Supported instance type, ENI, and IP addresses . . . . . . . . . . . . . . . . . . . . . . . . 543

Limitations and usage guidelines 544

Prerequisites 545

Deploy a NetScaler VPX standalone instance on AWS 546

Deploy a NetScaler VPX instance on AWS by using the AWS web console . . . . . . . . . . . 547
Configure a NetScaler VPX instance by using the Citrix CloudFormation template . . . . . . 550
Configure a NetScaler VPX instance by using the AWS CLI . . . . . . . . . . . . . . . . . . . 551

Download a NetScaler VPX license 551

Load balancing servers in different availability zones 552

Deploy a high availability pair on AWS 553

Points to note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554
Deploy a high availability pair by using the Citrix CloudFormation template . . . . . . . . . 554
Configuring SR-IOV on a high availability setup . . . . . . . . . . . . . . . . . . . . . . . . . 556

Add back-end AWS Auto Scaling service 557

Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558
Add the AWS Auto Scaling service to a NetScaler VPX instance . . . . . . . . . . . . . . . . . 558

© 1999-2018 Citrix Systems, Inc. All rights reserved. 17

NetScaler 12.0

Configure a NetScaler VPX instance to use SR-IOV network interface 560

Change the interface type to SR-IOV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561
Configure SR-IOV on a high availability setup . . . . . . . . . . . . . . . . . . . . . . . . . . 562

Upgrade a NetScaler VPX instance on AWS 563

Change the EC2 instance type of a NetScaler VPX instance on AWS . . . . . . . . . . . . . . 563
Upgrade the throughput or software edition of a NetScaler VPX instance on AWS . . . . . . 563
Upgrade the system software of a NetScaler VPX instance on AWS . . . . . . . . . . . . . . . 564
Upgrade to a new NetScaler AMI instance by using a NetScaler high availability configuration 564
Prerequisites and points to consider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565

Troubleshoot a VPX instance on AWS 568

Deploy a NetScaler VPX instance on Microsoft Azure 568

Network architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569
How a NetScaler VPX instance works on Azure . . . . . . . . . . . . . . . . . . . . . . . . . 570
Traffic flow through port address translation . . . . . . . . . . . . . . . . . . . . . . . . . . 571
Traffic flow through network address translation . . . . . . . . . . . . . . . . . . . . . . . . 571
Port usage guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572
NetScaler VPX licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574

Configure a NetScaler VPX standalone instance 575

Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
Summary of configuration steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
Configure a resource group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
Configure a network security group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
Configure a virtual network and subnets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
Configure a storage account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
Configure an availability set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
Configure a NetScaler VPX instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578

Configure multiple IP addresses for a NetScaler VPX standalone instance 580

Use case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580
Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581

Configure a high-availability setup with multiple IP addresses and NICs 582

Configure HA-INC nodes by using the Citrix high availability template . . . . . . . . . . . . . 583

Configure a high-availability setup with multiple IP addresses and NICs by using Power-
Shell commands 584
Configure HA-INC nodes by using PowerShell Ccmmands . . . . . . . . . . . . . . . . . . . 585

© 1999-2018 Citrix Systems, Inc. All rights reserved. 18

NetScaler 12.0

Parameter settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586

Configure a high-availability setup with a single IP address and a single NIC 597
Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598
Summary of steps to configure a NetScaler VPX instance in a high-availability Mode . . . . . 598
Configure internal and external load balancers . . . . . . . . . . . . . . . . . . . . . . . . . 598
Configure a health probe on the load balancer . . . . . . . . . . . . . . . . . . . . . . . . . 599
Configure a backend pool on the load balancer . . . . . . . . . . . . . . . . . . . . . . . . . 600
Configure a NAT rule on the load balancer . . . . . . . . . . . . . . . . . . . . . . . . . . . 600
Configure a load balancing rule on the load balancer . . . . . . . . . . . . . . . . . . . . . . 601
Configure NetScaler VPX high availability with the Azure external load balancer . . . . . . . 601
Configure NetScaler VPX high availability with the Azure internal load balancer . . . . . . . 601
Access the NetScaler VPX instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602

Configure GSLB on NetScaler VPX instances 603

Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603
Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604
Create a VM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605
IP configuration details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
Configure GSLB sites and other settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610

Configure GSLB on an active-standby high-availability setup 612

Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612
Parameter Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613
Configure ALB with the front-end IP address and rules to allow GSLB and DNS traffic . . . . 613
Enable GSLB on each high availability pair . . . . . . . . . . . . . . . . . . . . . . . . . . . 614

Configure address pools (IIP) for a Citrix Gateway appliance 616

Register a private IP address in the Azure portal . . . . . . . . . . . . . . . . . . . . . . . . 616
Configure address pools in the Citrix Gateway appliance . . . . . . . . . . . . . . . . . . . . 617

Configure multiple IP addresses for a NetScaler VPX instance in standalone mode by using
PowerShell commands 617
Use case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617
Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 618

Configure multiple Azure VIPs for a standalone or high availability VPX instance 624
Deploy a NetScaler VPX in standalone mode . . . . . . . . . . . . . . . . . . . . . . . . . . 624
Deploying NetScaler VPX in High Availability Mode . . . . . . . . . . . . . . . . . . . . . . . 631
Azure ARM components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639

© 1999-2018 Citrix Systems, Inc. All rights reserved. 19

NetScaler 12.0

Additional PowerShell scripts for Azure deployment 640

Provision a NetScaler VPX standalone instance . . . . . . . . . . . . . . . . . . . . . . . . . 641
Provision a NetScaler VPX pair in a high availabilty setup with an Azure external load balancer645
Provision a NetScaler VPX pair in a high availability setup with Azure internal load balancer . 652

Azure terminology 657

Jumbo frames on NetScaler VPX instances 659

Configure jumbo frames for a VPX instance running on VMware ESX . . . . . . . . . . . . . . 660
Configure jumbo frames for a VPX instance running on Linux-KVM server . . . . . . . . . . . 660
Configure jumbo frames for a VPX instance running on Citrix XenServer . . . . . . . . . . . 661
Configure jumbo frames for a VPX instance running on AWS . . . . . . . . . . . . . . . . . . 661

Licensing 661

NetScaler licensing overview 662

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662
Allocate a license by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662
Install a license . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664
Verify licensed features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665
Enable or disable a feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665
NetScaler VPX Express license . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667

Citrix Gateway Universal License 668

Obtaining the Universal License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668
Installing the Universal License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
Verifying Installation of the Universal License . . . . . . . . . . . . . . . . . . . . . . . . . . 669

NetScaler Pooled Capacity 670

Upgrade and downgrade a NetScaler appliance 670

Before you begin 671

Upgrade a Citrix NetScaler standalone appliance 672

Upgrade a Citrix NetScaler standalone appliance by using the GUI . . . . . . . . . . . . . . 672
Upgrade a Citrix NetScaler standalone appliance by using the CLI . . . . . . . . . . . . . . . 673
Upgrade a Citrix NetScaler standalone appliance by using NITRO API . . . . . . . . . . . . . 676
Directory locations of script files for user monitors . . . . . . . . . . . . . . . . . . . . . . . 676
Check and install Citrix NetScaler 12.0 software update . . . . . . . . . . . . . . . . . . . . 677

Downgrade a Citrix NetScaler standalone appliance 677

Procedure to downgrade a standalone Citrix NetScaler . . . . . . . . . . . . . . . . . . . . 677

© 1999-2018 Citrix Systems, Inc. All rights reserved. 20

NetScaler 12.0

Upgrade a high availability pair 680

Points to note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680
Upgrade a high availability pair by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . 681
Upgrade a high availability pair by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . 685

Downgrade a high availability pair 685

Troubleshooting 686
Resources for troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686
Troubleshooting issues related to the installation, upgrade, and downgrade processes . . . 686

FAQs 690

New and deprecated commands, parameters, and SNMP OIDs 690

New commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691
New parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691
New SNMP OIDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697

Deprecated features and functionalities 697

Deprecated features and Its alternatives in NetScaler 12.0 . . . . . . . . . . . . . . . . . . . 698
Using NSPEPI conversion tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698
AppQoE Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698

AAA application traffic 699

How AAA works 700

Enabling AAA 703

To enable AAA by using the command line interface . . . . . . . . . . . . . . . . . . . . . . 703
To enable AAA by using the configuration utility . . . . . . . . . . . . . . . . . . . . . . . . 703

Setting up an authentication virtual server 704

To set up an authentication virtual server by using the CLI . . . . . . . . . . . . . . . . . . . 704
To set up an authentication virtual server by using the GUI . . . . . . . . . . . . . . . . . . 705

Configuring the authentication virtual server 706

To configure an authentication virtual server by using the command line interface . . . . . 706
To configure an authentication virtual server by using the configuration utility . . . . . . . . 707

Configuring a traffic management virtual server 709

To configure a TM virtual server for AAA by using the command line interface . . . . . . . . 710
To configure a TM virtual server for AAA by using the configuration utility . . . . . . . . . . . 710
Simplified login protocol support for AAA . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711

© 1999-2018 Citrix Systems, Inc. All rights reserved. 21

NetScaler 12.0

Configuring DNS 711

Verifying your setup for AAA 712

To verify authentication virtual server setup by using the command line interface . . . . . . 712
To verify your AAA virtual server setup by using the configuration utility . . . . . . . . . . . 712

Creating an authentication profile 713

To configure an authentication profile by using the CLI . . . . . . . . . . . . . . . . . . . . 713
To configure an authentication profile by using the GUI . . . . . . . . . . . . . . . . . . . . 713

Configuring users and groups 714

To create a local AAA user account by using the command line interface . . . . . . . . . . . 714
To change the password for an existing AAA local user account by using the command line
interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715
To configure AAA local users by using the configuration utility . . . . . . . . . . . . . . . . . 715
To create AAA local groups and add users to them by using the command line interface . . . 715
To remove users from an AAA group by using the command line interface . . . . . . . . . . 716
To remove an AAA group by using the command line interface . . . . . . . . . . . . . . . . . 716
To configure AAA local groups and add users to them by using the configuration utility . . . 717

Configuring AAA policies 717

Authentication policies 718

To add an authentication action by using the command line interface . . . . . . . . . . . . 720
To configure an authentication action by using the command line interface . . . . . . . . . 720
To remove an authentication action by using the command line interface . . . . . . . . . . 720
To configure an authentication server by using the configuration utility . . . . . . . . . . . 721
To create and bind an authentication policy by using the command line interface . . . . . . 721
To modify an existing authentication policy by using the command line interface . . . . . . 722
To remove an authentication policy by using the command line interface . . . . . . . . . . 722
To configure and bind authentication policies by using the configuration utility . . . . . . . 722

LDAP authentication policies 723

To enable LDAP referral support by using the command line interface . . . . . . . . . . . . 724
To enable LDAP referral support by using the configuration utility . . . . . . . . . . . . . . . 725
Key-based authentication support for LDAP users . . . . . . . . . . . . . . . . . . . . . . . 725

Negotiate authentication policies 726

To configure AAA to extract user information from a keytab file by using the command line
interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
To configure AAA to extract user information from a keytab file by using the configuration
utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727

© 1999-2018 Citrix Systems, Inc. All rights reserved. 22

NetScaler 12.0

RADIUS authentication policies 727

To add an authentication action for a RADIUS server by using the command line interface . 728
To configure an authentication action for an external RADIUS server by using the command
line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
To remove an authentication action for an external RADIUS server by using the command
line interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
To configure a RADIUS server by using the configuration utility . . . . . . . . . . . . . . . . 730

SAML authentication policies 731

Web authentication policies 731

To configure a Web authentication action by using the command line interface . . . . . . . 732
To configure a Web authentication action by using the configuration utility . . . . . . . . . 732

Configuring advanced authentication policies 733

To configure an advanced authentication policy by using the configuration utility . . . . . . 734

Authorizing user access to application resources 734

To configure authorization by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . 735
To configure authorization by using the GUI (Configuration tab) . . . . . . . . . . . . . . . . 735

Auditing authenticated sessions 736

To configure syslog auditing by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . 737
To configure syslog auditing by using the GUI (Configuration tab) . . . . . . . . . . . . . . . 737

Session settings 738

Session profiles 739

To create a session profile by using the command line interface . . . . . . . . . . . . . . . . 739
To modify a session profile by using the command line interface . . . . . . . . . . . . . . . 740
To remove a session profile by using the command line interface . . . . . . . . . . . . . . . 740
To configure session profiles by using the configuration utility . . . . . . . . . . . . . . . . 740

Session policies 741

To create a session policy by using the command line interface . . . . . . . . . . . . . . . . 741
To modify a session policy by using the command line interface . . . . . . . . . . . . . . . . 742
To globally bind a session policy by using the command line interface . . . . . . . . . . . . 742
To bind a session policy to an authentication virtual server by using the command line interface 743
To unbind a session policy from an authentication virtual server by using the command line
interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743
To unbind a globally bound session policy by using the command line interface . . . . . . . 743
To remove a session policy by using the command line interface . . . . . . . . . . . . . . . 743

© 1999-2018 Citrix Systems, Inc. All rights reserved. 23

NetScaler 12.0

To configure and bind session policies by using the configuration utility . . . . . . . . . . . 744

Global session settings 745

To configure the session settings by using the command line interface . . . . . . . . . . . . 745
To configure the session settings by using the configuration utility . . . . . . . . . . . . . . 745

Traffic Settings 746

Traffic profiles 747

To create a traffic profile by using the command line interface . . . . . . . . . . . . . . . . . 747
To modify a session profile by using the command line interface . . . . . . . . . . . . . . . 747
To remove a session profile by using the command line interface . . . . . . . . . . . . . . . 748
To configure traffic profiles by using the configuration utility . . . . . . . . . . . . . . . . . 748

Traffic policies 748

To create a traffic policy by using the command line interface . . . . . . . . . . . . . . . . . 749
To modify a traffic policy by using the command line interface . . . . . . . . . . . . . . . . 749
To globally bind a traffic policy by using the command line interface . . . . . . . . . . . . . 749
To bind a traffic policy to a load balancing or content switching virtual server by using the
command line interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750
To unbind a globally bound traffic policy by using the command line interface . . . . . . . . 750
To unbind a traffic policy from a load balancing or content switching virtual server by using
the command line interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750
To remove a traffic policy by using the command line interface . . . . . . . . . . . . . . . . 751
To configure and bind traffic policies by using the configuration utility . . . . . . . . . . . . 751

Form SSO profiles 751

To create a form SSO profile by using the command line interface . . . . . . . . . . . . . . . 752
To modify a form SSO by using the command line interface . . . . . . . . . . . . . . . . . . 752
To remove a form SSO profile by using the command line interface . . . . . . . . . . . . . . 753
To configure form SSO profiles by using the configuration utility . . . . . . . . . . . . . . . 753

SAML SSO profiles 754

To create a SAML SSO profile by using the command line interface . . . . . . . . . . . . . . 754
To modify a SAML SSO by using the command line interface . . . . . . . . . . . . . . . . . . 754
To remove a SAML SSO profile by using the command line interface . . . . . . . . . . . . . 755
To configure a SAML SSO profile by using the configuration utility . . . . . . . . . . . . . . . 755

Session timeout for OWA 2010 755

To force OWA 2010 to timeout after a specified period by using the command line interface . 756

© 1999-2018 Citrix Systems, Inc. All rights reserved. 24

NetScaler 12.0

Authenticating with client certificates 757

To configure the AAA client certificate parameters by using the command line interface . . . 757
To configure the AAA client certificate parameters by using the configuration utility . . . . . 758
Support to notify number of unsuccessful login attempts . . . . . . . . . . . . . . . . . . . 759

Client certificate pass-through 759

To create and configure client certificate pass-through by using the command line interface 760

Configuring AAA with commonly used protocols 761

Handling authentication, authorization and auditing with Kerberos/NTLM 762

Optimizing Kerberos authentication on AAA . . . . . . . . . . . . . . . . . . . . . . . . . . 763

How NetScaler appliance implements Kerberos for client authentication 763

Key Distribution Center (KDC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764
Authentication service and protocol negotiation . . . . . . . . . . . . . . . . . . . . . . . . 764

Configuring kerberos authentication on the NetScaler appliance 766

Configuring Kerberos authentication on the CLI . . . . . . . . . . . . . . . . . . . . . . . . 767
Configuring Kerberos authentication on the GUI . . . . . . . . . . . . . . . . . . . . . . . . 768

Configuring kerberos authentication on a client 769

To configure Internet Explorer for Kerberos authentication . . . . . . . . . . . . . . . . . . 769
To configure Mozilla Firefox for Kerberos authentication . . . . . . . . . . . . . . . . . . . . 770

Offloading Kerberos authentication from physical servers 770

To configure Kerberos authentication on the NetScaler appliance . . . . . . . . . . . . . . . 771
To configure Internet Explorer for Kerberos authentication . . . . . . . . . . . . . . . . . . 772
To configure Mozilla Firefox for Kerberos authentication . . . . . . . . . . . . . . . . . . . . 773

NetScaler appliance kerberos single sign-on 773

An overview of NetScaler appliance kerberos SSO 774

Integration of NetScaler appliance Kerberos SSO with authentication methods . . . . . . . 775

Setting up NetScaler appliance SSO 776

Prerequisites 777
To create a server and service by using the command line . . . . . . . . . . . . . . . . . . . 777
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778
To create a traffic management virtual server by using the command line . . . . . . . . . . 778
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
To create an authentication virtual server by using the command line . . . . . . . . . . . . 779

© 1999-2018 Citrix Systems, Inc. All rights reserved. 25

NetScaler 12.0

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
To configure a traffic management virtual server to use an authentication profile . . . . . . 780
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 781

Configuring SSO 781

Enabling integrated authentication on the web application server 782

To configure Microsoft IIS to use integrated authentication . . . . . . . . . . . . . . . . . . 782

Setting up SSO by impersonation 783

To create the KCD account for SSO by impersonation with a password . . . . . . . . . . . . 783

Configuring SSO by delegation 784

Installing the client CA certificate on the NetScaler appliance . . . . . . . . . . . . . . . . . 784
Creating the KCD account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 786
Setting up Active Directory for NetScaler appliance SSO . . . . . . . . . . . . . . . . . . . . 789

Generating the KCD keytab script 790

To generate the KCD keytab script by using the configuration utility . . . . . . . . . . . . . . 790

SAML authentication 791

Why SAML? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791

NetScaler appliance as a SAML SP 793

To configure the NetScaler appliance as a SAML SP by using the command line interface . . 795
To configure a NetScaler appliance as a SAML SP by using the graphical user interface . . . 795

NetScaler appliance as a SAML IdP 796

To configure a NetScaler appliance as a SAML IdP by using the command line interface . . . 797
To configure a NetScaler appliance as a SAML IdP by using the graphical user interface . . . 798

Configuring SAML single sign-on 798

Configuring SAML single sign-on by using the command line interface . . . . . . . . . . . . 799
Configuring SAML single sign-on by using the graphical user interface . . . . . . . . . . . . 799

OAuth authentication 800

Multi-Factor (nFactor) authentication 802

How to configure nFactor authentication 803

How nFactor authentication works 805

Configuring nFactor authentication 806

© 1999-2018 Citrix Systems, Inc. All rights reserved. 26

NetScaler 12.0

Configuring the OpenID connect protocol 807

Advantages of having the OpenID connect support . . . . . . . . . . . . . . . . . . . . . . . 807

Admin Partitioning 810

User access and roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812

Supported NetScaler configurations 816

Case 1 (global configurations) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817
Case 2 (partition-specific configurations) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817
Case 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817

Configure admin partitions 821

Tip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 822
Configure an admin partition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823
Command Policies for a Partition Users and Partition User Groups in Administrative Partition 827
Configure an LACP ethernet channel on the default admin partition . . . . . . . . . . . . . 827

VLAN configuration for admin partitions 829

Dedicated VLANs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 830
Shared VLAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831
Shared VLAN with admin partition on Citrix ADC SDX appliance . . . . . . . . . . . . . . . . 833

VXLAN support for admin partitions 834

Points to remember before configuring a VXLAN . . . . . . . . . . . . . . . . . . . . . . . . 834
Supportable VXLAN configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 834

SNMP support for admin partitions 835

SNMP traps for admin partition rate limiting . . . . . . . . . . . . . . . . . . . . . . . . . . 836
Configuring PARTITION-RATE-LIMIT alarm . . . . . . . . . . . . . . . . . . . . . . . . . . . 836
SNMP monitoring for partition resource utilization . . . . . . . . . . . . . . . . . . . . . . . 837

Audit log support for admin partitions 838

Points to remember . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 839
Configuring audit logging in partitioned NetScaler appliance . . . . . . . . . . . . . . . . . 839
Configuring audit-log by using the NetScaler GUI . . . . . . . . . . . . . . . . . . . . . . . . 840

AppExpert 841

Action analytics 842

Configure a selector 843

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844

© 1999-2018 Citrix Systems, Inc. All rights reserved. 27

NetScaler 12.0

Configure a stream identifier 846

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 847

View statistics 847

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 849

Grouping records on attribute values 850

To group the records on the values of selector expressions by using the command line interface850
To group the records on the values of selector expressions by using the GUI . . . . . . . . . 853

Clearing a stream session 853

To clear a stream session by using the command line interface . . . . . . . . . . . . . . . . 853
To clear a stream session by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . 854

Configure policy for optimizing traffic 854

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855

How to limit bandwidth consumption per user or client device 856

AppExpert applications and templates 859

AppExpert application terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 860

How AppExpert Application Works 861

Get started with AppExpert 862

Downloading an Application Template 863

Importing an Application Template 863

Verifying and Testing Application Configuration 865

Customizing the configuration 866

Configure public endpoints 867

Configure services and service groups for an application unit 868

Create application units 869

Configuring application unit rules 870

Configuring policies for application units 870

Configuring compression policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 871
Configuring Caching Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872

© 1999-2018 Citrix Systems, Inc. All rights reserved. 28

NetScaler 12.0

Configuring Rewrite policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 873

Configuring Responder policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874
Configuring Application Firewall policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874

Configuring Application Units 876

Configuring public endpoints for an application 877

Specifying the Order of Evaluation of Application Units 878

Configuring Persistency Groups for Application Units 879

Viewing AppExpert Applications and Configuring Entities by Using the Application Visualizer880

Configuring User Authentication, Authorization, and Auditing 880

Monitoring a NetScaler Application 881

Viewing Application Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 882
Monitoring an Application by Using the Application Visualizer . . . . . . . . . . . . . . . . . 882
Viewing Hits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 882

Deleting an Application 883

Configure application authentication, authorization, and auditing 883

Configure application authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884
Configure application auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885
Disabling AAA for an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886

Setting Up a Custom NetScaler Application 886

Creating an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887
Creating Application Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887
Configuring Public Endpoints for an AppExpert Application . . . . . . . . . . . . . . . . . . 887
Configuring Public Endpoints for an Application Unit . . . . . . . . . . . . . . . . . . . . . 888
Configuring Services and Service Groups for an AppExpert Application . . . . . . . . . . . . 888
Configuring services and service groups for an application Unit . . . . . . . . . . . . . . . . 889
Configuring Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890

Creating and managing template files 890

Exporting an appExpert application to a template file 891

Exporting a Content Switching Virtual Server Configuration to a Template File 892

Creating Variables in Application Templates 893

© 1999-2018 Citrix Systems, Inc. All rights reserved. 29

NetScaler 12.0

Uploading and downloading template files 895

Understanding NetScaler application templates and deployment files 896

Example of a NetScaler Application Template . . . . . . . . . . . . . . . . . . . . . . . . . . 897
Example of a deployment file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 900

Deleting a Template File 901

NetScaler Gateway Applications 902

How an NetScaler Gateway Application Works . . . . . . . . . . . . . . . . . . . . . . . . . 902
How a NetScaler Configuration for a File Share Works . . . . . . . . . . . . . . . . . . . . . 903
How a NetScaler Configuration for an Intranet Subnet Works . . . . . . . . . . . . . . . . . 903
How the Other Resources Category Works . . . . . . . . . . . . . . . . . . . . . . . . . . . 903
Entity Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 904

Adding Intranet Subnets 904

Adding Other Resources 905

Configuring Authorization Policies 906

Configuring Traffic Policies 906

Configuring Clientless Access Policies 907

Configuring TCP Compression Policies 908

Configuring Bookmarks 910

Customizing the configuration 910

Configure public endpoints 911

Configuring Endpoints for an Application Unit 912

Configure services and service groups for an application unit 913

Configuring services, service groups, and load balancing Parameters for an application unit 914

Create application units 915

Configuring application unit rules 916

Configuring policies for application units 916

Configuring compression policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 917

© 1999-2018 Citrix Systems, Inc. All rights reserved. 30

NetScaler 12.0

Configuring Caching Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918

Configuring Rewrite policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919
Configuring Responder policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 920
Configuring Application Firewall policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . 921

Create application units 922

Configuring public endpoints for an application 923

Specifying the Order of Evaluation of Application Units 924

Configuring Persistency Groups for Application Units 924

Viewing AppExpert Applications and Configuring Entities by Using the Application Visualizer925

AppQoE 926

Enabling AppQoE 927

To enable AppQoE by using the command line . . . . . . . . . . . . . . . . . . . . . . . . . 928
To enable AppQoE by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 928

AppQOE actions 928

To configure an AppQoE action by using the command line . . . . . . . . . . . . . . . . . . 929
To modify an existing AppQoE action by using the command line . . . . . . . . . . . . . . . 930
To remove an AppQoE action by using the command line . . . . . . . . . . . . . . . . . . . 930
Parameters for configuring an AppQoE action . . . . . . . . . . . . . . . . . . . . . . . . . 930
To configure an AppQoE action by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . 932

AppQoE parameters 933

To configure the AppQoE parameter settings by using the command line . . . . . . . . . . . 933
Parameters for configuring the AppQoE parameters . . . . . . . . . . . . . . . . . . . . . . 934
To configure the AppQoE parameter settings by using the GUI . . . . . . . . . . . . . . . . . 934

AppQoE Policies 935

To configure an AppQoE policy by using the command line . . . . . . . . . . . . . . . . . . 935
Parameters for configuring an AppQoE policy . . . . . . . . . . . . . . . . . . . . . . . . . . 935
To configure an AppQoE policy by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . 936

Entity templates 937

Configuring an entity template 938

Configuring variables in load balancing virtual server templates 939

To configure variables in a load balancing virtual server template . . . . . . . . . . . . . . . 940

© 1999-2018 Citrix Systems, Inc. All rights reserved. 31

NetScaler 12.0

Modifying an entity template 941

To modify an entity template by using the AppExpert feature node . . . . . . . . . . . . . . 942
To modify an entity template by using its corresponding feature node . . . . . . . . . . . . 942

Deleting an entity template 942

To delete an entity template by using the AppExpert feature node . . . . . . . . . . . . . . 943
To delete an entity template by using its corresponding feature node . . . . . . . . . . . . . 943

Creating an entity from a template 943

To create an entity from a template by using the AppExpert feature node . . . . . . . . . . . 944
To create an entity from a template by using its corresponding feature node . . . . . . . . . 944
To create a load balancing virtual server by using a load balancing virtual server template . 944

Managing entity template folders 945

To organize load balancing virtual server template folders . . . . . . . . . . . . . . . . . . . 945

Uploading and downloading entity templates 946

To upload an entity template to the NetScaler appliance . . . . . . . . . . . . . . . . . . . . 946
To download an entity template from the NetScaler appliance . . . . . . . . . . . . . . . . 946

Understanding load balancing entity templates and deployment files 947

Example of a load balancing virtual server template . . . . . . . . . . . . . . . . . . . . . . 947
Example of a deployment file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 949

HTTP callouts 950

How an HTTP callout works 951

Notes on the format of HTTP requests and responses 952

Format of an HTTP request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 952
Format of an HTTP Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 953

Configuring an HTTP callout 953

To configure an HTTP callout by using the command line interface . . . . . . . . . . . . . . 955
To configure an HTTP callout by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . 956

Verifying the Configuration 956

To view the hits counter for an HTTP callout . . . . . . . . . . . . . . . . . . . . . . . . . . 957

Invoking an HTTP Callout 958

Avoiding HTTP callout recursion 960

© 1999-2018 Citrix Systems, Inc. All rights reserved. 32

NetScaler 12.0

Caching HTTP Callout Responses 962

To set the cache duration by using the command line interface . . . . . . . . . . . . . . . . 962
To set the cache duration by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . 962

Use Case: Filtering Clients by Using an IP Blacklist 963

Enabling Responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 963
Creating an HTTP Callout on the NetScaler Appliance . . . . . . . . . . . . . . . . . . . . . 964
Configuring a Responder Policy and Binding it Globally . . . . . . . . . . . . . . . . . . . . 964
Creating an HTTP Callout Agent on the Remote Server . . . . . . . . . . . . . . . . . . . . . 964

Use Case: ESI Support for Fetching and Updating Content Dynamically 966
Enabling Rewrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 966
Creating an HTTP Callout on the NetScaler Appliance . . . . . . . . . . . . . . . . . . . . . 966
Configuring the rewrite action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 967
Creating the rewrite policy and binding it globally . . . . . . . . . . . . . . . . . . . . . . . 967

Use Case: Access control and authentication 968

Enabling responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 969
Creating an HTTP Callout on the NetScaler Appliance . . . . . . . . . . . . . . . . . . . . . 969
Creating a Responder policy to analyze the response . . . . . . . . . . . . . . . . . . . . . . 971
Creating an HTTP Callout agent on the remote server . . . . . . . . . . . . . . . . . . . . . 972

Use Case: OWA-Based Spam Filtering 972

Enabling Responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 973
Creating an HTTP Callout on the NetScaler Appliance . . . . . . . . . . . . . . . . . . . . . 973
Creating a Responder Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 973
Creating a Responder Policy to Invoke the HTTP Callout . . . . . . . . . . . . . . . . . . . . 974
Creating an HTTP Callout Agent on the Remote Server . . . . . . . . . . . . . . . . . . . . . 975

Use Case: Dynamic Content Switching 976

Pattern sets and data sets 977

How string matching works with pattern sets and data sets 978

Configuring a Pattern Set 979

To configure a pattern set by using the command line interface . . . . . . . . . . . . . . . . 980
To configure a pattern set by using the configuration utility . . . . . . . . . . . . . . . . . . 980

Configuring a data set 981

To configure a data set by using the command line interface . . . . . . . . . . . . . . . . . . 981
To configure a data set by using the configuration utility . . . . . . . . . . . . . . . . . . . . 982

© 1999-2018 Citrix Systems, Inc. All rights reserved. 33

NetScaler 12.0

Using pattern sets and data sets 982

Sample usage 983

Variables 984
Variables Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985

Configuring and using Variables 985

To configure variables by using the command line interface . . . . . . . . . . . . . . . . . . 986
Use Case to insert HTTP header in the response side . . . . . . . . . . . . . . . . . . . . . . 987
To configure variables by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 988

Use Case: Caching User Privileges 988

To achieve this use case, perform the following operations . . . . . . . . . . . . . . . . . . 988

Use Case: Limiting the Number of Sessions 990

Policies and expressions 992

Introduction to policies and expressions 994

Classic and advanced policies 994

Benefits of using advanced policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995
Basic components of an advanced policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995
How different NetScaler features use policies . . . . . . . . . . . . . . . . . . . . . . . . . . 996
About actions and profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000
About policy bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1002
About evaluation order of policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003
Order of evaluation based on traffic flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004

Classic and advanced policy expressions 1004

About classic expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005
About advanced policy expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005

Converting policy expressions using NSPEPI tool 1006

About the conversion process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1007
Convert expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
Convert a NetScaler configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
Conversion warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1010

Before you proceed 1010

Configure advanced policy infrastructure 1011

© 1999-2018 Citrix Systems, Inc. All rights reserved. 34

NetScaler 12.0

Rules for names in identifiers used in policies 1012

Create or modify a policy 1013

Create a policy by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1013
Create or modify a policy by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014

Policy configuration examples 1015

Bind policies using advanced policy 1016

Feature-specific differences in policy bindings . . . . . . . . . . . . . . . . . . . . . . . . . 1016
Bind points and order of evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1019
Policy evaluation across features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1020
Entries in a policy bank . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1020
Evaluation order within a policy bank . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1021
How policy evaluation ends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1023
How features use actions after policy evaluation . . . . . . . . . . . . . . . . . . . . . . . . 1024

Bind a policy globally 1024

Bind an integrated caching policy globally by using the CLI . . . . . . . . . . . . . . . . . . 1024
Bind a rewrite policy globally by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . 1025
Bind a compression policy globally by using the CLI . . . . . . . . . . . . . . . . . . . . . . 1025
Bind a responder policy globally by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . 1026
Bind a DNS policy globally by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026
Bind an integrated caching, responder, rewrite, or compression policy globally by using the
GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027
Bind a DNS policy globally by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027

Bind a policy to a virtual server 1028

Bind a policy to a load balancing or content switching virtual server by using the CLI . . . . 1028
Bind a policy to an SSL offload virtual server by using the CLI . . . . . . . . . . . . . . . . . 1029
Bind a policy to a virtual server by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . 1029

Display policy bindings 1030

Display policy bindings by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1030
Display global policy bindings for integrated caching, rewrite, or responder by using the GUI 1030
Display global policy bindings for DNS or clientless access in the NetScaler Gateway by using
the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1031
Display global policy bindings for content switching by using the GUI . . . . . . . . . . . . . 1031

Unbind a policy 1031

Unbind an integrated caching, rewrite, or compression advanced policy globally by using
the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1031

© 1999-2018 Citrix Systems, Inc. All rights reserved. 35

NetScaler 12.0

Unbind a responder policy globally by using the CLI . . . . . . . . . . . . . . . . . . . . . . 1032

Unbind a DNS policy globally by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . 1032
Unbind an advanced policy from a virtual server by using the CLI . . . . . . . . . . . . . . . 1033
Unbind an integrated caching, responder, rewrite, or compression Advanced policy globally
by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1034
Unbind a DNS policy globally by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . 1034
Unbind an advanced policy from a load balancing or content switching virtual server by us-
ing the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1034

Create policy labels 1034

Create a caching policy label by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . 1035
Create a content switching policy label by using the CLI . . . . . . . . . . . . . . . . . . . . 1036
Create a rewrite policy label by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . 1036
Create a responder policy label by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . 1037
Create a policy label by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1037
Bind a policy to a policy label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1038

Configure a policy label or virtual server policy bank 1039

Configure a policy label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1039
Configure a policy bank for a virtual server . . . . . . . . . . . . . . . . . . . . . . . . . . . 1043

Invoke or remove a policy label or virtual server policy bank 1045

Invoke a rewrite or integrated caching policy label by using the CLI . . . . . . . . . . . . . . 1046
Invoke a responder policy label by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . 1046
Invoke a virtual server policy bank by using the CLI . . . . . . . . . . . . . . . . . . . . . . 1047
Remove a rewrite or integrated caching policy label by using the CLI . . . . . . . . . . . . . 1048
Remove a responder policy label by using the CLI . . . . . . . . . . . . . . . . . . . . . . . 1048
Remove a virtual server policy label by using the CLI . . . . . . . . . . . . . . . . . . . . . . 1049
Invoke a policy label or virtual server policy bank by using the GUI . . . . . . . . . . . . . . 1050
Remove a policy label invocation by using the GUI . . . . . . . . . . . . . . . . . . . . . . . 1050

Configure and bind policies with the policy manager 1050

Configure policy bindings by using the policy manager . . . . . . . . . . . . . . . . . . . . 1051
Remove unused policies by using the policy manager . . . . . . . . . . . . . . . . . . . . . 1053

Configuring advanced policy expression: getting started 1053

Basic elements of an advanced policy expression 1054

Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055
Single-element expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1057
Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1057

© 1999-2018 Citrix Systems, Inc. All rights reserved. 36

NetScaler 12.0

Basic operations on expression prefixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1058

Compound advanced policy expressions 1059

Booleans in compound expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1060
Parentheses in compound expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1060
Compound operations for strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1061
Compound operations for numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1064

Specify the character set in expressions 1072

Compound expressions with different character sets . . . . . . . . . . . . . . . . . . . . . . 1073
Specify the character set based on the character set of traffic . . . . . . . . . . . . . . . . . 1074
Character and string literals in expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . 1074
Values in hexadecimal and octal formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075
Functions that return UTF-8 strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075
Terminal connection settings for UTF-8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075

Classic expressions in advanced policy expressions 1076

Configure advanced policy expressions in a policy 1077

Configure an Advanced policy syntax rule by using the CLI . . . . . . . . . . . . . . . . . . . 1078
Configure a default syntax policy expression by using the GUI . . . . . . . . . . . . . . . . . 1079
Test a default syntax expression by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . 1080

Configure named advanced policy expressions 1080

Example 1: Simple Named Expression as a Prefix . . . . . . . . . . . . . . . . . . . . . . . . 1081
Example 2: Compound named expression as a prefix . . . . . . . . . . . . . . . . . . . . . . 1081
Configure a named default syntax expression by using the CLI . . . . . . . . . . . . . . . . . 1082
Configure a named expression by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . 1082

Configure advanced policy expressions outside the context of a policy 1082

Configure an advanced policy expression outside a policy by using the CLI (cache selector
example) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1083

Advanced policy expressions: evaluating text 1084

About text expressions 1085

About operations on text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1085
Compounding and precedence in text expressions . . . . . . . . . . . . . . . . . . . . . . . 1086
Categories of text expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1086
Guidelines for text expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1087

Expression prefixes for text in HTTP requests and responses 1088

© 1999-2018 Citrix Systems, Inc. All rights reserved. 37

NetScaler 12.0

Expression prefixes for VPNs and clientless VPNs 1088

Basic operations on text 1089

String comparison functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1089
Calculate the length of a string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091
Consider, ignore, and change text case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091
Strip specific characters from a string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1092
Append a string to another string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1093

Complex operations on text 1094

Operations on the length of a string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1094
Operations on a portion of a string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1095
Operations for comparing the alphanumeric order of two strings . . . . . . . . . . . . . . . 1095
Extract an integer from a string of bytes that represent text . . . . . . . . . . . . . . . . . . 1095
Convert text to a hash value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1096
Encode and decode text by applying the Base64 encoding algorithm . . . . . . . . . . . . . 1096
Refine the search in a rewrite action by using the EXTEND function . . . . . . . . . . . . . . 1096
Convert text to hexadecimal format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1097
Encrypt and decrypt text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1097
Configure encryption key for third-party encryption . . . . . . . . . . . . . . . . . . . . . . 1099
Configure HMAC keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1106
Show an HMAC key by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1107

Advanced policy expressions: working with dates, times, and numbers 1108

Format of dates and times in an expression 1109

Expressions for the NetScaler system time 1110

Expressions for SSL certificate dates 1114

Expressions for HTTP request and response dates 1122

Generate the day of the week, as a string, in short and long formats 1124

Expression prefixes for numeric data other than date and time 1125

Converting numbers to text 1125

Virtual server based expressions 1127

Advanced policy expressions: Parsing HTTP, TCP, and UDP data 1128

About evaluating HTTP and TCP payload 1129

© 1999-2018 Citrix Systems, Inc. All rights reserved. 38

NetScaler 12.0

Expressions for identifying the protocol in an incoming IP packet 1130

Arguments to the PROTOCOL function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1131
Use case scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1132

Expressions for HTTP and cache-control headers 1132

Prefixes for HTTP headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1133
Operations for HTTP headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1148
Prefixes for cache-control headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1149
Operations for cache-control headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1149

Expressions for extracting segments of URLs 1152

Expressions for HTTP status codes and numeric HTTP payload data other than dates 1153

SIP expressions 1154

SIP reference tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1155

Operations for HTTP, HTML, and XML encoding and “safe” characters 1167

Expressions for TCP, UDP, and VLAN data 1170

Expressions for evaluating a DNS message and identifying its carrier protocol 1174

XPath and HTML, XML, or JSON expressions 1177

Encrypt and decrypt XML payloads 1180

Use the XML_ENCRYPT() and XML_DECRYPT() functions in expressions . . . . . . . . . . . . 1181

Advanced policy expressions: parsing SSL 1183

Parse SSL certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1183
Prefixes for text-based SSL and certificate data . . . . . . . . . . . . . . . . . . . . . . . . . 1184
Prefixes for numeric data in SSL certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . 1184
Expressions for SSL certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1185

Advanced policy expressions: IP and MAC addresses, throughput, VLAN IDs 1187
Expressions for IP Addresses and IP Subnets . . . . . . . . . . . . . . . . . . . . . . . . . . 1187
Expressions for MAC addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1192
Expressions for Numeric Client and Server Data . . . . . . . . . . . . . . . . . . . . . . . . 1193

Advanced policy expressions: stream analytics functions 1194

Advanced policy expressions: DataStream 1195

Expressions for the MySQL protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1196
Expressions for evaluating Microsoft SQL server connections . . . . . . . . . . . . . . . . . 1204

© 1999-2018 Citrix Systems, Inc. All rights reserved. 39

NetScaler 12.0

Typecasting data 1208

Regular Expressions 1209

Basic characteristics of regular expressions 1210

Operations for regular expressions 1211

Configuring classic policies and expressions 1214

Configure a classic policy 1214

Create a classic policy by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1214
Create a policy with classic expressions by using the GUI . . . . . . . . . . . . . . . . . . . 1215

Configure a classic expression 1216

Create a classic policy expression by using the CLI . . . . . . . . . . . . . . . . . . . . . . . 1217
Add an expression for a classic policy by using the GUI . . . . . . . . . . . . . . . . . . . . . 1218

Bind a classic policy 1220

Bind a classic policy globally by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . 1220
Bind a classic policy to a virtual server by using the CLI . . . . . . . . . . . . . . . . . . . . 1220
Bind a classic policy globally by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . 1222
Bind a classic policy to a virtual server by using the GUI . . . . . . . . . . . . . . . . . . . . 1222

View classic policies 1223

View a classic policy and its binding information by using the CLI . . . . . . . . . . . . . . . 1223
View classic policies and policy bindings by using the GUI . . . . . . . . . . . . . . . . . . . 1224

Create named classic expressions 1224

Create a named classic expression by using the CLI . . . . . . . . . . . . . . . . . . . . . . . 1225
Create a named classic expression by using the GUI . . . . . . . . . . . . . . . . . . . . . . 1225

Expressions reference-advanced policy expressions 1226

Expressions reference-classic expressions 1227

Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1227
General expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1228
Client security expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1230
Network-based expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1231
Date/time expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1232
File system expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1233
Built-in named expressions (General) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1233
Built-in named expressions (Anti-Virus) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1236

© 1999-2018 Citrix Systems, Inc. All rights reserved. 40

NetScaler 12.0

Built-in named expressions (Personal Firewall) . . . . . . . . . . . . . . . . . . . . . . . . . 1237

Built-in named expressions (Client Security) . . . . . . . . . . . . . . . . . . . . . . . . . . 1237

Summary examples of default syntax expressions and policies 1238

Tutorial examples of default syntax policies for rewrite 1245

Redirecting an external URL to an internal URL . . . . . . . . . . . . . . . . . . . . . . . . . 1245
Redirecting a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1246
Rewriting HTTP to HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1247
Removing Unwanted Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1248
Reducing Web Server Redirects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1249
Masking the Server Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1249

Tutorial Examples of Classic Policies 1250

NetScaler Gateway Policy to Check for a Valid Client Certificate . . . . . . . . . . . . . . . . 1251
Application firewall policy to protect a shopping cart application . . . . . . . . . . . . . . . 1251
Application firewall policy to protect scripted web pages . . . . . . . . . . . . . . . . . . . 1254
DNS Policy to drop packets from specific IPs . . . . . . . . . . . . . . . . . . . . . . . . . . 1255
SSL policy to require valid client certificates . . . . . . . . . . . . . . . . . . . . . . . . . . 1256

Migration of Apache mod_rewrite rules to the default syntax 1257

Converting URL variations into canonical URLs . . . . . . . . . . . . . . . . . . . . . . . . . 1257
Apache mod_rewrite solution for converting a URL . . . . . . . . . . . . . . . . . . . . . . . 1257
NetScaler solution for converting a URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1257
Converting host name variations to canonical host names . . . . . . . . . . . . . . . . . . . 1257
Apache mod_rewrite solution for enforcing a particular host name for sites running on a
port other than 80 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1258
Apache mod_rewrite solution for enforcing a particular host name for sites running on port
80 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1258
NetScaler solution for enforcing a particular host name for sites running on a port other than
80 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1258
NetScaler solution for enforcing a particular host name for sites running on port 80 . . . . . 1258
Moving a document root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1259
Apache mod_rewrite solution for moving the document root . . . . . . . . . . . . . . . . . 1259
NetScaler solution for moving the document root . . . . . . . . . . . . . . . . . . . . . . . 1259
NetScaler solution for moving the document root and appending path information to the
request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1259
Moving home directories to a new web server . . . . . . . . . . . . . . . . . . . . . . . . . 1260
Apache mod_rewrite solution for redirecting to another Web server . . . . . . . . . . . . . 1260
NetScaler solution for redirecting to another Web server (method 1) . . . . . . . . . . . . . 1260
NetScaler solution for redirecting to another Web server (method 2) . . . . . . . . . . . . . 1260

© 1999-2018 Citrix Systems, Inc. All rights reserved. 41

NetScaler 12.0

Working with structured home directories . . . . . . . . . . . . . . . . . . . . . . . . . . . 1260

Apache mod_rewrite solution for structured home directories . . . . . . . . . . . . . . . . 1261
NetScaler solution for structured home directories . . . . . . . . . . . . . . . . . . . . . . . 1261
Redirecting invalid URLs to other web servers . . . . . . . . . . . . . . . . . . . . . . . . . 1261
Apache mod_rewrite solution for redirection if a URL is wrong . . . . . . . . . . . . . . . . 1261
NetScaler solution for redirection if a URL is wrong (method 1) . . . . . . . . . . . . . . . . 1261
NetScaler solution for redirection if a URL is wrong (method 2) . . . . . . . . . . . . . . . . 1262
Rewriting a URL based on time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1262
Apache mod_rewrite solution for rewriting a URL based on the time . . . . . . . . . . . . . 1262
NetScaler solution for rewriting a URL based on the time . . . . . . . . . . . . . . . . . . . 1263
Redirecting to a new file name (Invisible to the User) . . . . . . . . . . . . . . . . . . . . . . 1263
Apache mod_rewrite solution for managing a file name change in a fixed location . . . . . . 1263
NetScaler solution for managing a file name change in a fixed location . . . . . . . . . . . . 1263
NetScaler solution for managing a file name change regardless of the base directory or query
strings in the URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1264
Redirecting to new file name (user-visible URL) . . . . . . . . . . . . . . . . . . . . . . . . . 1264
Apache mod_rewrite solution for changing the file name and the URL displayed in the browser1264
NetScaler solution for changing the file name and the URL displayed in the browser . . . . 1264
NetScaler solution for changing the file name and the URL displayed in the browser regard-
less of the base directory or query strings in the URL . . . . . . . . . . . . . . . . . . . 1264
Accommodating browser dependent content . . . . . . . . . . . . . . . . . . . . . . . . . . 1265
Apache mod_rewrite solution for browser-specific settings . . . . . . . . . . . . . . . . . . 1265
Blocking access by robots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1266
Apache mod_rewrite solution for blocking a path and a User-Agent header . . . . . . . . . 1266
NetScaler solution for blocking a path and a User-Agent header . . . . . . . . . . . . . . . . 1266
Blocking access to inline images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1266
Apache mod_rewrite solution for blocking access to an inline image . . . . . . . . . . . . . 1267
NetScaler solution for blocking access to an inline image . . . . . . . . . . . . . . . . . . . 1267
Creating extensionless links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1267
Apache mod_rewrite solution for adding a .php extension to all requests . . . . . . . . . . . 1268
NetScaler policy for adding a .php extension to all requests . . . . . . . . . . . . . . . . . . 1268
Apache mod_rewrite solution for adding either .html or .php extensions to requests . . . . 1268
NetScaler policy for adding either .html or .php extensions to requests . . . . . . . . . . . . 1268
Redirecting a Working URI to a New Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 1269
Apache mod_rewrite solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1269
Ensuring That a Secure Server Is Used for Selected Pages . . . . . . . . . . . . . . . . . . . 1270
Apache mod_rewrite solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1270
NetScaler solution using regular expressions . . . . . . . . . . . . . . . . . . . . . . . . . . 1270
NetScaler solution using pattern sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1270

© 1999-2018 Citrix Systems, Inc. All rights reserved. 42

NetScaler 12.0

Rate limiting 1271

Configuring a Stream Selector 1272

To configure a traffic stream selector by using the command line interface . . . . . . . . . . 1273
To configure a stream selector by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . 1273

Viewing the Traffic Rate 1273

To view the traffic rate by using the command line interface . . . . . . . . . . . . . . . . . . 1274
To view the traffic rate by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1274

Testing a Rate-Based Policy 1274

Task overview: Testing a rate-based policy . . . . . . . . . . . . . . . . . . . . . . . . . . . 1274

Viewing the Traffic Rate 1276

To view the traffic rate by using the command line interface . . . . . . . . . . . . . . . . . . 1276
To view the traffic rate by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1276

Testing a Rate-Based Policy 1277

Task overview: Testing a rate-based policy . . . . . . . . . . . . . . . . . . . . . . . . . . . 1277

Examples of Rate-Based Policies 1278

Sample Use Cases for Rate-Based Policies 1278

Redirecting Traffic on the Basis of Traffic Rate . . . . . . . . . . . . . . . . . . . . . . . . . . 1279
Dropping DNS Requests on the Basis of Traffic Rate . . . . . . . . . . . . . . . . . . . . . . 1279

Rate Limiting for Traffic Domains 1281

Configure rate limit at packet level 1283

Responder 1284
Comparison between Rewrite and Responder options . . . . . . . . . . . . . . . . . . . . . 1285

Enabling the Responder Feature 1285

Configuring a Responder Action 1286

Configuring the Global HTTP Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1290

Configuring a Responder Policy 1291

Binding a Responder Policy 1293

Setting the default action for a responder policy 1295

© 1999-2018 Citrix Systems, Inc. All rights reserved. 43

NetScaler 12.0

Responder action and policy examples 1297

Example: Blocking access from specified IP addresses . . . . . . . . . . . . . . . . . . . . . 1297
Example: Redirecting a client to a new URL . . . . . . . . . . . . . . . . . . . . . . . . . . . 1298

Diameter Support for Responder 1300

RADIUS Support for Responder 1301

Configuring Responder Policies for RADIUS . . . . . . . . . . . . . . . . . . . . . . . . . . . 1302
RADIUS Expressions for Responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1302
Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1305

DNS Support for the Responder Feature 1306

Configuring Responder Policies for DNS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1306

Troubleshooting 1307
Resources for Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1308
Troubleshooting Responder Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1308

Rewrite 1309
Comparison between Rewrite and Responder options . . . . . . . . . . . . . . . . . . . . . 1310

How rewrite works 1311

Policy Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1312
Rewrite Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1313

Enabling the rewrite feature 1314

To enable the rewrite feature by using the command line interface . . . . . . . . . . . . . . 1314
To enable the rewrite feature by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . 1314

Configuring a Rewrite Action 1315

To create a new rewrite action by using the command line interface . . . . . . . . . . . . . 1316
To modify an existing rewrite action by using the command line interface . . . . . . . . . . 1317
To remove a rewrite action by using the command line interface . . . . . . . . . . . . . . . 1317
To configure a rewrite action by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . 1317
To add an expression by using the Add Expression dialog box . . . . . . . . . . . . . . . . . 1318
To evaluate a rewrite action by using the Rewrite Action Evaluator dialog box . . . . . . . . 1319

Configuring a Rewrite Policy 1320

To add a new rewrite policy by using the command line interface . . . . . . . . . . . . . . . 1320
To modify an existing rewrite policy by using the command line interface . . . . . . . . . . 1321
To remove a rewrite policy by using the command line interface . . . . . . . . . . . . . . . 1322
To configure a rewrite policy by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . 1322

© 1999-2018 Citrix Systems, Inc. All rights reserved. 44

NetScaler 12.0

Binding a Rewrite Policy 1323

To globally bind a rewrite policy by using the command line interface . . . . . . . . . . . . 1324
To bind rewrite policy to a specific virtual server by using the command line interface . . . . 1324
To bind a rewrite policy to a bind point by using the GUI . . . . . . . . . . . . . . . . . . . . 1325
To bind a rewrite policy to a specific virtual server by using the GUI . . . . . . . . . . . . . . 1326

Configuring Rewrite Policy Labels 1327

To configure a rewrite policy label by using the command line interface . . . . . . . . . . . 1327
To configure a rewrite policy label by using the GUI . . . . . . . . . . . . . . . . . . . . . . 1328

Configuring the Default Rewrite Action 1329

To configure the default action by using the command line interface . . . . . . . . . . . . . 1329
To configure the default action by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . 1330

Bypassing the Safety Check 1330

To bypass the safety check by using the command line interface . . . . . . . . . . . . . . . 1331
To bypass safety check by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1331

Rewrite Action and Policy Examples 1332

Example 1: Delete Old X-Forwarded-For and Client-IP Headers 1333

To delete old X-Forwarded and Client-IP headers from a request by using the command line
interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1334
To delete old X-Forwarded and Client-IP headers from a request by using the GUI . . . . . . 1334

Example 2: Adding a Local Client-IP Header 1335

To add a local Client-IP header by using the command line interface . . . . . . . . . . . . . 1335
To add a local Client-IP header by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . 1335

Example 3: Tagging Secure and Insecure Connections 1336

Example 4: Mask the HTTP Server Type 1337

Example 5: Redirect an external URL to an internal URL 1338

Example 6: Migrating Apache Rewrite Module Rules 1340

Example 7: Marketing Keyword Redirection 1341

Example 8: Redirect Queries to the Queried Server 1342

Example 9: Home Page Redirection 1343

© 1999-2018 Citrix Systems, Inc. All rights reserved. 45

NetScaler 12.0

Example 10: Policy-based RSA Encryption 1345

Policy-based RSA encryption by using NetScaler command interface . . . . . . . . . . . . . 1345
Policy-based RSA encryption by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . 1348

Example 11: Policy-based RSA encryption with no padding operation 1349

Policy-based RSA encryption by using Citrix ADC command interface . . . . . . . . . . . . . 1350
Policy-based RSA encryption with no padding option by using the GUI . . . . . . . . . . . . 1350

URL Transformation 1351

Configuring URL Transformation Profiles 1352

To create a URL transformation profile by using the NetScaler command line . . . . . . . . 1352
To modify an existing URL transformation profile or action by using the NetScaler command
line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1353
To remove a URL transformation profile and actions by using the NetScaler command line . 1354
To create a URL transformation profile by using the GUI . . . . . . . . . . . . . . . . . . . . 1354
To configure a URL transformation profile and actions by using the GUI . . . . . . . . . . . . 1355

Configuring URL Transformation Policies 1356

To configure a URL transformation policy by using the NetScaler command line . . . . . . . 1356
To remove a URL transformation policy by using the NetScaler command line . . . . . . . . 1357
To configure a URL transformation policy by using the GUI . . . . . . . . . . . . . . . . . . . 1357
To add an expression by using the Add Expression dialog box . . . . . . . . . . . . . . . . . 1358

Globally Binding URL Transformation Policies 1360

To bind a URL transformation policy by using the NetScaler command line . . . . . . . . . . 1360
To bind a URL transformation policy by using the GUI . . . . . . . . . . . . . . . . . . . . . 1361

Globally Binding URL Transformation Policies 1362

To bind a URL transformation policy by using the NetScaler command line . . . . . . . . . . 1362
To bind a URL transformation policy by using the GUI . . . . . . . . . . . . . . . . . . . . . 1363

Diameter Support for Rewrite 1364

To configure Rewrite to modify a Diameter request . . . . . . . . . . . . . . . . . . . . . . . 1364

DNS Support for the Rewrite Feature 1365

DNS Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1366
DNS Bind Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1366
Rewrite Action Types for DNS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1366
Configuring Rewrite Policies for DNS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1366

© 1999-2018 Citrix Systems, Inc. All rights reserved. 46

NetScaler 12.0

String maps 1368

How String Maps Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1369
Configuring a String Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1369
Example: responder policy with a redirect action . . . . . . . . . . . . . . . . . . . . . . . . 1370

URL Sets 1371

Getting Started 1371

Use Case for Safe Internet Access Policies for ISPs/Telcos . . . . . . . . . . . . . . . . . . . 1372

Advanced Policy Expressions for URL Evaluation 1372

Configuring URL Set 1373

To import a URL set with meta by using the command line interface . . . . . . . . . . . . . 1375
To show URL set by using the command line interface . . . . . . . . . . . . . . . . . . . . . 1375
To export an URL set by using the command line interface . . . . . . . . . . . . . . . . . . . 1375
To add an URL set by using the command line interface . . . . . . . . . . . . . . . . . . . . 1376
To update an URL set by using the command line interface . . . . . . . . . . . . . . . . . . 1376
To remove a URL set command by using the command line interface . . . . . . . . . . . . . 1376
To import a URL set by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1377
To add a URL set by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1377
To edit a URL set by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1377
To Update a URL set by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1377
To Export a URL set by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1377

URL Pattern Semantics 1377

URL Categories 1378

AppFlow 1385
How AppFlow Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1385

Configuring the AppFlow Feature 1389

Enabling AppFlow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1390
Specifying a Collector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1390
Configuring an AppFlow Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1391
Configuring an AppFlow Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1392
Binding an AppFlow Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1393
Enabling AppFlow for Virtual Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1394
Enabling AppFlow for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1395
Setting the AppFlow Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1395
Example: Configuring AppFlow for DataStream . . . . . . . . . . . . . . . . . . . . . . . . . 1396

© 1999-2018 Citrix Systems, Inc. All rights reserved. 47

NetScaler 12.0

Exporting performance data of web pages to AppFlow collector 1397

Prerequisites for Exporting Performance Data of Web Pages to AppFlow Collectors . . . . . 1398
Associating an AppFlow Action with the EdgeSight Monitoring Responder Policy . . . . . . 1398

Session reliability on NetScaler high availability pair 1399

Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1401
Session Reconnect Sematics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1401

Application Firewall 1402

Highlights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1405

FAQs and Deployment Guide 1406

Q: Why is NetScaler App Firewall the preferred choice for securing applications? . . . . . . . 1406
Q: What do I need to do to configure App Firewall? . . . . . . . . . . . . . . . . . . . . . . . 1409
Q: How do I know what profile type to choose? . . . . . . . . . . . . . . . . . . . . . . . . . 1409
Q: What is the difference between basic and advanced profiles? How do I decide which one
I need? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1409
Q: What is a policy? How do I select the bind point and set the priority? . . . . . . . . . . . 1410
Q: How do I go about configuring the rules to secure my application? . . . . . . . . . . . . . 1411
Q: What are signatures? How do I know which signatures to use? . . . . . . . . . . . . . . . 1411
Q: Does the App Firewall work with other NetScaler features? . . . . . . . . . . . . . . . . . 1412
Q: How is the payload processed by the App Firewall and the other NetScaler features? . . . 1412
Q: What is the recommended workflow for App Firewall deployment? . . . . . . . . . . . . 1412

Introduction 1415

Web application security 1415

Known web attacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1417
Unknown web attacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1418

How App Firewall works 1420

App Firewall features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1421

The App Firewall configuration interfaces 1422

Configuring the App Firewall 1423

The App Firewall wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1424
NetScaler app interface appExpert template . . . . . . . . . . . . . . . . . . . . . . . . . . 1425
The NetScaler GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1426
The NetScaler command line interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1426

© 1999-2018 Citrix Systems, Inc. All rights reserved. 48

NetScaler 12.0

Enabling App Firewall 1426

To enable the App Firewall by using the command line interface . . . . . . . . . . . . . . . 1427
To enable the App Firewall by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . 1427

The App Firewall wizard 1428

Opening the Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1428
The Wizard screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1428
Create a New Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1432
Modify an Existing Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1432
Create a New Configuration without Signatures . . . . . . . . . . . . . . . . . . . . . . . . 1433
Configure a Custom Policy Expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1433

Manual configuration 1434

Replicating configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1434

Manual configuration by using the GUI 1435

To create and configure a signatures object . . . . . . . . . . . . . . . . . . . . . . . . . . . 1435
To create an App Firewall profile by using the GUI . . . . . . . . . . . . . . . . . . . . . . . 1436
To configure an App Firewall profile by using the GUI . . . . . . . . . . . . . . . . . . . . . . 1436
Configuring an App Firewall rule or relaxation . . . . . . . . . . . . . . . . . . . . . . . . . 1438
To configure the Learning feature by using the GUI . . . . . . . . . . . . . . . . . . . . . . . 1440
To create and configure a policy by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . 1442
To create or configure an App Firewall rule (expression) . . . . . . . . . . . . . . . . . . . . 1442
To add a firewall rule (expression) by using the Add Expression dialog box . . . . . . . . . . 1444
To bind an App Firewall policy by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . 1445

Manual configuration By using the command line interface 1447

To create a profile by using the command line interface . . . . . . . . . . . . . . . . . . . . 1447
To configure a profile by using the command line interface . . . . . . . . . . . . . . . . . . 1448
To create and configure a policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1448
To bind an App Firewall policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1449
To configure session limit per PE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1449

Signatures 1450
Protection options for your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1451
Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1452
Highlights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1452

Manually configuring the signatures feature 1453

Adding or removing a signatures object 1454

To create a signatures object from a template . . . . . . . . . . . . . . . . . . . . . . . . . 1454

© 1999-2018 Citrix Systems, Inc. All rights reserved. 49

NetScaler 12.0

To create a signatures object by importing a file . . . . . . . . . . . . . . . . . . . . . . . . 1455

To create a signatures object by importing a file by using the command line . . . . . . . . . 1455
To remove a signatures object by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . 1456
To remove a signatures object by using the command line . . . . . . . . . . . . . . . . . . . 1456

Configuring or modifying a signatures object 1456

To configure or modify a signatures object . . . . . . . . . . . . . . . . . . . . . . . . . . . 1456

Protecting JSON applications using signatures 1460

Using the NetScaler App Firewall signatures to protect JSON applications . . . . . . . . . . 1460
To add or remove JSON content-type by using the command line interface . . . . . . . . . . 1461
To managing JSON content types by using the GUI . . . . . . . . . . . . . . . . . . . . . . . 1461
Configuring signature protection to detect attacks in JSON payload . . . . . . . . . . . . . 1461
Example of a signature to detect XSS in JSON payload . . . . . . . . . . . . . . . . . . . . . 1462
Example of the payload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1463
Example of the log message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1463
Highlights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1464

Updating a signatures object 1464

To update the App Firewall signatures from the source by using the command line . . . . . 1465
Updating a signatures object from a Citrix format file . . . . . . . . . . . . . . . . . . . . . 1465
Updating a signatures object from a supported vulnerability scanning tool . . . . . . . . . . 1466

Exporting a signatures object to a file 1467

To export a signatures object to a file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1467

The Signatures editor 1468

To add or modify a local signature rule by using the Signatures Editor . . . . . . . . . . . . 1468

To add a signature rule category 1470

Signature rule patterns 1471

To configure a signature rule pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1472

Import and merge signature rules 1476

Signature updates in high availability deployment and build upgrades 1477

Connecting to Amazon AWS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1478
Signature updates during version upgrades . . . . . . . . . . . . . . . . . . . . . . . . . . . 1478

Overview of security checks 1479

Top level protections 1480

© 1999-2018 Citrix Systems, Inc. All rights reserved. 50

NetScaler 12.0

HTML cross-site scripting check 1482

XSS Fine grained Relaxations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1484
Using the Command Line to Configure the HTML Cross-Site Scripting check . . . . . . . . . 1485
Using the GUI to configure the HTML Cross-Site scripting check . . . . . . . . . . . . . . . . 1486
Using the Learn Feature with the HTML Cross-Site Scripting Check . . . . . . . . . . . . . . 1488
Using the Log Feature with the HTML Cross-Site Scripting Check . . . . . . . . . . . . . . . 1489
Statistics for the HTML Cross-Site Scripting violations . . . . . . . . . . . . . . . . . . . . . 1491
Highlights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1492

HTML SQL injection check 1493

SQL fine grained relaxations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1497
Using the command line to configure the SQL injection check . . . . . . . . . . . . . . . . . 1498
Using the GUI to configure the SQL injection security check . . . . . . . . . . . . . . . . . . 1499
Using the Learn feature with the SQL injection check . . . . . . . . . . . . . . . . . . . . . . 1502
Using the log feature with the SQL injection check . . . . . . . . . . . . . . . . . . . . . . . 1503
Statistics for the SQL Injection violations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1505
Highlights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1506

Buffer overflow check 1507

Using the command line to configure the Buffer Overflow security check . . . . . . . . . . . 1508
Using the GUI to Configure the Buffer Overflow Security Check . . . . . . . . . . . . . . . . 1508
Using the Log Feature with the Buffer Overflow Security Check . . . . . . . . . . . . . . . . 1508
Statistics for the Buffer Overflow violations . . . . . . . . . . . . . . . . . . . . . . . . . . . 1511
Highlights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1512

Cookie consistency check 1513

App Firewall support for Google web toolkit 1516

What is GWT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1517
How a GWT request works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1517
App Firewall protection for GWT applications . . . . . . . . . . . . . . . . . . . . . . . . . . 1519

Data leak prevention checks 1522

Credit card check 1522

Using the command line to configure the credit card check . . . . . . . . . . . . . . . . . . 1523
Using the GUI to configure the credit card check . . . . . . . . . . . . . . . . . . . . . . . . 1524
Using the learn feature with the credit card check . . . . . . . . . . . . . . . . . . . . . . . 1525
Using the log feature with the credit card check . . . . . . . . . . . . . . . . . . . . . . . . 1526
Statistics for the credit card violations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1528
Highlights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1529

© 1999-2018 Citrix Systems, Inc. All rights reserved. 51

NetScaler 12.0

Safe object check 1530

Advanced form protection checks 1533

Field formats check 1533

Using the command line to configure the field format check . . . . . . . . . . . . . . . . . . 1537
Using the GUI to Configure the field formats security check . . . . . . . . . . . . . . . . . . 1539
Using the learn feature with the Field Formats Check . . . . . . . . . . . . . . . . . . . . . . 1540
Using the log feature with the field formats check . . . . . . . . . . . . . . . . . . . . . . . 1543
Statistics for the field formats violations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1544
Deployment tip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1544
Highlights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1545

Form field consistency check 1546

CSRF form tagging check 1549

Managing CSRF form tagging check relaxations 1552

To configure a CSRF form tagging check relaxation by using the GUI . . . . . . . . . . . . . 1552

URL protection checks 1553

Start URL check 1554

Deny URL check 1558

XML protection checks 1559

XML format check 1560

XML denial-of-service check 1561

XML cross-site scripting check 1564

Action Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1564
Relaxation Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1565
Using the command line to configure the XML cross-site scripting check . . . . . . . . . . . 1566
Using the GUI to configure the XML cross-site scripting check . . . . . . . . . . . . . . . . . 1567
Using the log feature with the XML cross-site scripting check . . . . . . . . . . . . . . . . . 1569
Statistics for the XML cross-site scripting violations . . . . . . . . . . . . . . . . . . . . . . . 1570

XML SQL injection check 1571

Action options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1572
XML SQL parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1572
Relaxation rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1574

© 1999-2018 Citrix Systems, Inc. All rights reserved. 52

NetScaler 12.0

Using the command line to configure the XML SQL Injection Check . . . . . . . . . . . . . . 1576
Using the GUI to configure the XMLSQL injection security check . . . . . . . . . . . . . . . . 1577
Using the log feature with the XML SQL injection check . . . . . . . . . . . . . . . . . . . . 1579
Statistics for the XML SQL injection violations . . . . . . . . . . . . . . . . . . . . . . . . . . 1580

XML attachment check 1580

Web services interoperability check 1581

XML message validation check 1586

XML SOAP fault filtering check 1587

Managing content types 1588

To set the default request content type by using the command line interface . . . . . . . . . 1589
To remove the user-defined default request content type by using the command line interface1589
To set the default response content type by using the command line interface . . . . . . . . 1590
To remove the user-defined default response content type by using the command line in-
terface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1590
To add a content type to the allowed content types list by using the command line interface 1590
To remove a content type from the allowed content types list by using the command line
interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1591
To manage the default and allowed content types by using the GUI . . . . . . . . . . . . . . 1591

Profiles 1592
Built-in profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1593
User-defined profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1593

Creating App Firewall profiles 1594

To create an App Firewall profile by using the command line interface . . . . . . . . . . . . 1595
To create an App Firewall profile by using the GUI . . . . . . . . . . . . . . . . . . . . . . . 1596

Configuring App Firewall profiles 1596

To configure an App Firewall profile by using the command line . . . . . . . . . . . . . . . . 1597
To configure an App Firewall profile by using the GUI . . . . . . . . . . . . . . . . . . . . . . 1597

Changing an App Firewall profile type 1599

To change an App Firewall profile type by using the command line interface . . . . . . . . . 1599
To change an App Firewall profile type by using the GUI . . . . . . . . . . . . . . . . . . . . 1599

Exporting and importing an App Firewall profile 1600

Exporting App Firewall profiles with the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . 1600
Importing App Firewall profiles with the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . 1602

© 1999-2018 Citrix Systems, Inc. All rights reserved. 53

NetScaler 12.0

Exporting and importing App Firewall profiles with the GUI . . . . . . . . . . . . . . . . . . 1603
Highlights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1604
Debugging tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1604

Configuring and using the Learning feature 1605

To configure the learning settings by using the command line interface . . . . . . . . . . . . 1606
To reset learning settings to their defaults by using the command line interface . . . . . . . 1607
To display the learning settings for a profile by using the command line interface . . . . . . 1608
To display unreviewed learned rules or relaxations for a profile by using the command line
interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1608
To remove specific unreviewed learned rules or relaxations from the learning database by
using the command line interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1608
To remove all unreviewed learned data by using the command line interface . . . . . . . . . 1608
To export learning data by using the command line interface . . . . . . . . . . . . . . . . . 1609
To configure the Learning feature by using the GUI . . . . . . . . . . . . . . . . . . . . . . . 1609
To review learned rules or relaxations by using the GUI . . . . . . . . . . . . . . . . . . . . 1610

Supplemental Information about profiles 1611

Configuration variable support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1611
PCRE character encoding format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1612
Inverted PCRE Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1615
Disallowed names for App Firewall profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . 1615

Policy labels 1617

To create an App Firewall policy label by using the command line . . . . . . . . . . . . . . . 1618
To bind a policy to a policy label by using the command line . . . . . . . . . . . . . . . . . 1618
To configure an App Firewall policy label by using the GUI . . . . . . . . . . . . . . . . . . . 1618

Policies 1619

App Firewall Policies 1620

Creating and configuring App Firewall policies 1622

To create and configure a policy by using the command line interface . . . . . . . . . . . . 1623
To create and configure a policy by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . 1623
To create or configure an App Firewall rule . . . . . . . . . . . . . . . . . . . . . . . . . . . 1624
To add a firewall rule (expression) by using the Add Expression dialog box . . . . . . . . . . 1626

Binding App Firewall policies 1627

To bind an App Firewall policy by using the command line interface . . . . . . . . . . . . . 1628
To bind an App Firewall policy by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . 1628

© 1999-2018 Citrix Systems, Inc. All rights reserved. 54

NetScaler 12.0

Viewing a policy bindings 1629

To view bindings for an App Firewall policy . . . . . . . . . . . . . . . . . . . . . . . . . . . 1629

Supplemental information about App Firewall policies 1630

Correct but unexpected behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1630

Auditing policies 1631

To create an auditing server by using the command line interface . . . . . . . . . . . . . . . 1631
To modify or remove an auditing server by using the command line interface . . . . . . . . 1632
To create or configure an auditing server by using the GUI . . . . . . . . . . . . . . . . . . . 1632
To create an auditing policy by using the command line interface . . . . . . . . . . . . . . . 1633
To configure an auditing policy by using the command line interface . . . . . . . . . . . . . 1633
To configure an auditing policy by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . 1633

Imports 1634
HTML error object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1634
XML error object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1636
XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1636
WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1637

Importing and exporting files 1637

To import a file by using the command line interface . . . . . . . . . . . . . . . . . . . . . . 1637
To import a file by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1638
To export a file by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1638
To edit an HTML or XML Error Object in the GUI . . . . . . . . . . . . . . . . . . . . . . . . . 1639

Global configuration 1639

Engine settings 1640

To configure engine settings by using the command line interface . . . . . . . . . . . . . . 1642
To configure engine settings by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . 1642

Confidential fields 1643

To add a confidential field by using the command line interface . . . . . . . . . . . . . . . . 1644
To modify a confidential field by using the command line interface . . . . . . . . . . . . . . 1644
To remove a confidential field by using the command line interface . . . . . . . . . . . . . . 1645
To configure a confidential field by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . 1645

Field types 1647

To add a field type by using the command line interface . . . . . . . . . . . . . . . . . . . . 1648
To modify a field type by using the command line interface . . . . . . . . . . . . . . . . . . 1648
To remove a field type by using the command line interface . . . . . . . . . . . . . . . . . . 1649

© 1999-2018 Citrix Systems, Inc. All rights reserved. 55

NetScaler 12.0

To configure a field type by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1649

XML content types 1650

To add an XML content type pattern by using the command line interface . . . . . . . . . . 1651
To remove an XML content type pattern by using the command line interface . . . . . . . . 1651
To configure the XML content type list by using the GUI . . . . . . . . . . . . . . . . . . . . 1651

JSON content types 1652

To add a JSON content type pattern by using the command line interface . . . . . . . . . . 1652
To configure the JSON content type list by using the GUI . . . . . . . . . . . . . . . . . . . . 1653

Statistics and reports 1653

The App Firewall statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1653
The App Firewall reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1654

App Firewall logs 1656

NetScaler (Native) format logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1656
Common Event Format (CEF) Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1657
Logging geolocation in the App Firewall violation messages . . . . . . . . . . . . . . . . . . 1659
Using the command line to configure the log action and other log parameters . . . . . . . . 1660
Configuring Syslog policy to segregate App Firewall logs . . . . . . . . . . . . . . . . . . . . 1662
Viewing the App Firewall logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1663
Highlights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1665

Appendices 1666

PCRE character encoding format 1667

Whitehat WASC signature types for WAF use 1669

WASC 1.0 signature types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1669
WASC 2.0 signature types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1670
Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1670

Streaming support for request processing 1671

Trace HTML requests with security logs 1675

App Firewall support for cluster configurations 1677

Highlights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1678

Debugging and troubleshooting 1679

High CPU 1679

© 1999-2018 Citrix Systems, Inc. All rights reserved. 56

NetScaler 12.0

Memory 1681
Checking allocated and used memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1683

Large file upload failure 1683

Learning 1684

Signatures 1686
Getting started with signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1686
Tips for using signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1686
Best practices for using signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1687

Trace Log 1687

Miscellaneous 1688

References 1689

Cache Redirection 1690

Cache redirection policies 1691

Built-in cache redirection policies 1692

Built-in classic cache redirection policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1692
Built-in default syntax cache redirection policies . . . . . . . . . . . . . . . . . . . . . . . . 1693
Display the built-in cache redirection policies . . . . . . . . . . . . . . . . . . . . . . . . . . 1694

Configure a cache redirection policy 1695

Add a cache redirection policy by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . 1696
Add a default syntax cache redirection policy by using the CLI . . . . . . . . . . . . . . . . . 1697
Modify or remove a cache redirection policy by using the CLI . . . . . . . . . . . . . . . . . 1698
Configure a cache redirection policy with a simple expression by using the GUI . . . . . . . 1698
Configure a cache redirection policy with a compound expression by using the GUI . . . . . 1699

Cache redirection configurations 1703

Configure transparent redirection 1704

Enable cache redirection and load balancing 1704

Enable cache redirection and load balancing by using the CLI . . . . . . . . . . . . . . . . . 1705
Enable cache redirection and load balancing by using the GUI . . . . . . . . . . . . . . . . . 1705

Configure edge mode 1706

Enable edge mode by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1706

© 1999-2018 Citrix Systems, Inc. All rights reserved. 57

NetScaler 12.0

Enable edge mode by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1707

Configure a cache redirection virtual server 1707

add a cache redirection virtual server in transparent mode by using the cli . . . . . . . . . . 1708
Modify or remove a cache redirection virtual server by using the CLI . . . . . . . . . . . . . 1708
Add a cache redirection virtual server in transparent mode by using the GUI . . . . . . . . . 1708

Bind policies to the cache redirection virtual server 1709

Bind policies to a cache redirection virtual server by using the CLI . . . . . . . . . . . . . . 1709
Bind a user-defined policy to a cache redirection virtual server by using the GUI . . . . . . . 1710

Unbind a policy from a cache redirection virtual server 1710

Unbind a policy from a cache redirection virtual server by using the command CLI . . . . . 1711
Unbind a user-defined policy from a cache redirection virtual server by using the GUI . . . . 1711

Create a load balancing virtual server 1712

Create a load balancing virtual server by using the CLI . . . . . . . . . . . . . . . . . . . . . 1712
Create a load balancing virtual server by using the GUI . . . . . . . . . . . . . . . . . . . . . 1713

Configure an HTTP service 1713

Configure an HTTP service by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . 1714
Modify or remove a service by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . 1715
Add an HTTP service by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1715

Bind/unbind a service to/from a load balancing virtual server 1715

Bind a service to a load balancing virtual server by using the CLI . . . . . . . . . . . . . . . 1715
Unbind a service from a load balancing virtual server by using the CLI . . . . . . . . . . . . 1716
Bind/unbind a service from a load balancing virtual server by using the GUI . . . . . . . . . 1716

Disable the use the proxy port setting for transparent caching 1717

Assign a port range to the NetScaler appliance 1717

Assign a source port range to a NetScaler appliance by using the CLI . . . . . . . . . . . . . 1718
Assign a source port range to a NetScaler appliance by using the appliance GUI . . . . . . . 1718

Enable load balancing virtual servers to redirect requests to cache 1718

Enable load balancing virtual servers to redirect requests to the cache by using the CLI . . . 1719
Turn off caching for a load balancing virtual server by using the CLI . . . . . . . . . . . . . . 1719
Enable or disable load balancing virtual servers to redirect requests to the cache by using
the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1720

Configure forward proxy redirection 1720

© 1999-2018 Citrix Systems, Inc. All rights reserved. 58

NetScaler 12.0

Create a DNS service 1721

Create a DNS service by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1721
Add a DNS service by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1722

Create a DNS load balancing virtual server 1723

Create a DNS load balancing virtual server by using the CLI . . . . . . . . . . . . . . . . . . 1723
Create a DNS load balancing virtual server by using the GUI . . . . . . . . . . . . . . . . . . 1724

Bind the DNS service to the virtual server 1724

Bind the DNS service to the load balancing virtual server by using the CLI . . . . . . . . . . 1724
Unbind a DNS service from the load balancing virtual server by using the CLI . . . . . . . . 1725
Bind/Unbind a DNS service to/from a load balancing virtual server by using the GUI . . . . . 1725

Configure a client web browser to use a forward proxy 1726

Configure reverse proxy redirection 1726

Configure mapping policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1727

Selective cache redirection 1730

Enable content switching 1732

Enable content switching by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . 1732
Enable cache redirection and load balancing by using the GUI . . . . . . . . . . . . . . . . . 1732

Configure a load balancing virtual server for the cache 1733

Configure a cache redirection policy for a specific type of content . . . . . . . . . . . . . . . 1733

Configure policies for content switching 1734

Create a content switching policy by using the command CLI . . . . . . . . . . . . . . . . . 1734
Create a URL-based content switching policy by using the GUI . . . . . . . . . . . . . . . . . 1735
Create a rule-based content switching policy by using the GUI . . . . . . . . . . . . . . . . . 1736
Bind the content switching policy to a cache redirection virtual server by using the CLI . . . 1736
Bind the content switching policy to a cache redirection virtual server by using the GUI . . . 1737

Configure precedence for policy evaluation 1738

Configure precedence for policy evaluation by using the CLI . . . . . . . . . . . . . . . . . . 1738
Configure precedence for policy evaluation by using the GUI . . . . . . . . . . . . . . . . . 1739

Administer a cache redirection virtual server 1739

View cache redirection virtual server statistics 1739

View statistics for a cache redirection virtual server by using the CLI . . . . . . . . . . . . . 1740
View statistics for a cache redirection virtual server by using the GUI . . . . . . . . . . . . . 1740

© 1999-2018 Citrix Systems, Inc. All rights reserved. 59

NetScaler 12.0

View the statistics of a cache redirection virtual server by using the monitoring and dash-
board utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1741

Enable or disable a cache redirection virtual server 1741

Enable or disable a cache redirection virtual server by using the CLI . . . . . . . . . . . . . 1741
Enable or disable a cache redirection virtual server by using the GUI . . . . . . . . . . . . . 1743

Direct policy hits to the cache instead of the origin 1743

Change the destination for a policy hit to the origin or the cache by using the CLI . . . . . . 1744
Change the destination for a policy hit to the origin or the cache by using the GUI . . . . . . 1744

Back up a cache redirection virtual server 1745

Specify a backup cache redirection virtual server by using the CLI . . . . . . . . . . . . . . . 1745
Specify a backup cache redirection virtual server by using the GUI . . . . . . . . . . . . . . 1746

Manage client connections for a virtual server 1746

Configure client timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1747
Insert Via headers in the requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1748
Reuse TCP connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1749
Configure delayed connection cleanup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1750

N-Tier cache redirection 1751

How N-tier cache redirection Is implemented . . . . . . . . . . . . . . . . . . . . . . . . . . 1752
Setup necessary for configuring N-Tier CRD . . . . . . . . . . . . . . . . . . . . . . . . . . . 1753
How N-tier cache redirection works during a cache hit . . . . . . . . . . . . . . . . . . . . . 1753
How N-tier cache redirection works during a cache bypass . . . . . . . . . . . . . . . . . . 1754
How N-tier cache redirection works during a cache miss . . . . . . . . . . . . . . . . . . . . 1755

Configure the upper-tier NetScaler appliances 1755

Configure an upper-tier appliance for n-tier cache redirection by using the command CLI . . 1756
Configure an upper-tier appliance for n-tier cache redirection by using the GUI . . . . . . . 1756

Configure the lower-tier NetScaler appliances 1757

Configure a lower-tier appliance for n-tier cache redirection by using the CLI . . . . . . . . . 1757
Configure a lower-tier appliance for n-tier cache redirection by using the GUI . . . . . . . . 1758

Clustering 1759

NetScaler appliance configuration support in a cluster 1760

NetScaler appliance configurations supported from NetScaler 10 onwards . . . . . . . . . . 1767

Prerequisites for cluster nodes 1767

© 1999-2018 Citrix Systems, Inc. All rights reserved. 60

NetScaler 12.0

Cluster overview 1768

Synchronization across cluster nodes 1769

Striped, partially striped, and spotted configurations 1770

Communication in a cluster setup 1773

Traffic distribution in a cluster setup 1774

Cluster nodegroups 1775

Cluster and node states 1776

Routing in a cluster 1777

IP addressing for a cluster 1778

Configuring layer 3 clustering 1780

Understanding L3 Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1780
Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1780
Configuring L3 Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1782
Spotted, partially striped configurations on L3 cluster . . . . . . . . . . . . . . . . . . . . . 1785

Setting up a NetScaler cluster 1787

Setting up inter-node communication 1788

To set up the cluster backplane, do the following for every node . . . . . . . . . . . . . . . 1788

Creating a NetScaler cluster 1790

To create a cluster by using the command line interface . . . . . . . . . . . . . . . . . . . . 1791
To create a cluster by using the configuration utility . . . . . . . . . . . . . . . . . . . . . . 1792

Adding a node to the cluster 1793

To add a node to the cluster by using the command line interface . . . . . . . . . . . . . . . 1794
To add a node to the cluster by using the configuration utility . . . . . . . . . . . . . . . . . 1795
To join a previously added node to the cluster by using the configuration utility . . . . . . . 1795

Viewing the details of a cluster 1796

To view details of a cluster instance by using the command line interface . . . . . . . . . . . 1796
To view details of a cluster node by using the command line interface . . . . . . . . . . . . 1796
To view details of a cluster instance by using the configuration utility . . . . . . . . . . . . . 1796
To view details of a cluster node by using the configuration utility . . . . . . . . . . . . . . . 1797

© 1999-2018 Citrix Systems, Inc. All rights reserved. 61

NetScaler 12.0

Distributing traffic across cluster nodes 1797

Using Equal Cost Multiple Path (ECMP) 1797

To configure ECMP on the cluster by using the command line interface . . . . . . . . . . . . 1798

Use Case: ECMP with BGP routing 1801

Using cluster link aggregation 1802

Static cluster link aggregation 1803

To configure a static cluster LA channel by using the command line interface . . . . . . . . . 1804

Dynamic cluster link aggregation 1805

To configure a dynamic cluster LA channel by using the command line interface . . . . . . . 1806

Link redundancy in a cluster with LACP 1807

Managing the NetScaler cluster 1808

Configuring linksets 1808

To configure a linkset by using the command line interface . . . . . . . . . . . . . . . . . . 1809
To configure a linkset by using the configuration utility . . . . . . . . . . . . . . . . . . . . 1810

Nodegroups for spotted and partially-striped configurations 1810

Behavior of nodegroups 1811

General behavior of a cluster nodegroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1812
Backing up nodes in a nodegroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1812

Configuring nodegroups for spotted and partially-striped configurations 1813

To configure a nodegroup by using the command line interface . . . . . . . . . . . . . . . . 1814
To configure a nodegroup by using the configuration utility . . . . . . . . . . . . . . . . . . 1815

Configuring redundancy for nodegroups 1815

Configuring redundancy for nodegroups . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1816

Disabling steering on the cluster backplane 1817

Synchronizing cluster configurations 1818

To synchronize cluster configurations by using the command line interface . . . . . . . . . 1819
To synchronize cluster configurations by using the configuration utility . . . . . . . . . . . . 1819

Synchronizing time across cluster nodes 1819

To enable/disable PTP by using the command line interface . . . . . . . . . . . . . . . . . . 1820

© 1999-2018 Citrix Systems, Inc. All rights reserved. 62

NetScaler 12.0

To enable/disable PTP by using the configuration utility . . . . . . . . . . . . . . . . . . . . 1820

Synchronizing cluster files 1820

To synchronize cluster files by using the command line interface . . . . . . . . . . . . . . . 1821
To synchronize cluster files by using the configuration utility . . . . . . . . . . . . . . . . . 1821

Viewing the statistics of a cluster 1822

To view the statistics of a cluster instance by using the command line interface . . . . . . . 1822
To view the statistics of a cluster node by using the command line interface . . . . . . . . . 1822
To view the statistics of a cluster instance by using the configuration utility . . . . . . . . . . 1822
To view the statistics of a cluster node by using the configuration utility . . . . . . . . . . . 1823

Discovering NetScaler appliances 1823

To discover appliances by using the configuration utility . . . . . . . . . . . . . . . . . . . . 1823

Disabling a cluster node 1824

To disable a cluster node by using the command line interface . . . . . . . . . . . . . . . . 1824
To disable a cluster node by using the configuration utility . . . . . . . . . . . . . . . . . . 1825

Removing a cluster node 1825

To remove a cluster node by using the command line interface . . . . . . . . . . . . . . . . 1826
To remove a cluster node by using the configuration utility . . . . . . . . . . . . . . . . . . 1826

Removing a node from a cluster deployed using cluster link aggregation 1827
To remove a node from a cluster that uses cluster link aggregation as the traffic distribution
mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1827

Detecting jumbo probe on a cluster 1827

Route monitoring for dynamic routes in cluster 1829

To bind a cluster node using the command line interface . . . . . . . . . . . . . . . . . . . 1829

Monitoring cluster setup using SNMP MIB with SNMP link 1830
Configuring SNMP MIB on CLIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1830

Monitoring command propagation failures in a cluster deployment 1831

Graceful shutdown of nodes 1832

Graceful handling of Nodes in cluster upgrade . . . . . . . . . . . . . . . . . . . . . . . . . 1832
Graceful handling of nodes during a new node addition . . . . . . . . . . . . . . . . . . . . 1833
Configuring graceful shutdown of nodes in a cluster . . . . . . . . . . . . . . . . . . . . . . 1834

© 1999-2018 Citrix Systems, Inc. All rights reserved. 63

NetScaler 12.0

IPv6 ready logo support for clusters 1836

Supportable configurations for testing IPv6 core protocols . . . . . . . . . . . . . . . . . . 1836
Additional IPv6 cluster configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1839

Managing cluster heartbeat messages 1841

To manage heartbeat messages on a node interface by using the NetScaler CLI . . . . . . . 1842

Configuring owner node response status 1842

To set owner node response status by using the NetScaler CLI . . . . . . . . . . . . . . . . . 1842
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1842
To set owner node response status by using the NetScaler GUI . . . . . . . . . . . . . . . . 1843
To edit owner node response status by using the NetScaler GUI . . . . . . . . . . . . . . . . 1843

Monitor static route (MSR) support for inactive nodes in a spotted cluster configuration 1843

VRRP interface binding in a single node active cluster 1843

Cluster setup and usage scenarios 1845

Creating a two-node cluster 1845

Migrating an HA setup to a cluster setup 1846

To convert a HA setup to cluster setup (without any downtime) by using the command line
interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1847

Transitioning between a L2 and L3 Cluster 1850

Transitioning a cluster from L2 to L3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1850
Transitioning a cluster from L3 to L2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1850

Setting up GSLB in a cluster 1851

Using cache redirection in a cluster 1853

Using L2 mode in a cluster setup 1854

Using cluster LA channel with linksets 1854

To configure cluster LA channel and linksets by using the NetScaler appliance command line 1855

Backplane on LA channel 1855

To deploy a cluster with the backplane interfaces as LA channels . . . . . . . . . . . . . . . 1855

Common interfaces for client and server and dedicated interfaces for backplane 1856

Common switch for client, server, and backplane 1858

© 1999-2018 Citrix Systems, Inc. All rights reserved. 64

NetScaler 12.0

Common switch for client and server and dedicated switch for backplane 1860

Different switch for every node 1862

Sample cluster configurations 1862

Using VRRP in a cluster setup 1866

Interface based VRRP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1866
Configuring Interface based VRRP for IPv4 . . . . . . . . . . . . . . . . . . . . . . . . . . . 1867
Configuring interface based VRRP for IPv6 . . . . . . . . . . . . . . . . . . . . . . . . . . . 1868
Configuring IP based VRRP for IPv4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1869
Configuring IP based VRRP for IPv6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1870

Upgrading or downgrading the NetScaler cluster 1871

Points to note before upgrading or downgrading the cluster . . . . . . . . . . . . . . . . . . 1871
To upgrade or downgrade the software of the cluster nodes . . . . . . . . . . . . . . . . . . 1872

Operations supported on individual cluster nodes 1873

Support for heterogeneous cluster 1874

Limitations of using heterogeneous cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . 1875

FAQs 1875

Troubleshooting the NetScaler cluster 1883

Tracing the packets of a NetScaler cluster 1884

To trace packets of a standalone appliance . . . . . . . . . . . . . . . . . . . . . . . . . . . 1884
To trace packets of a cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1884
Merge multiple trace files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1885
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1885
Capturing SSL Session Keys During a Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . 1886

Troubleshooting common issues 1888

Content Switching 1891

How Content Switching Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1892

Configuring basic content switching 1893

Enabling content switching 1894

To enable content switching by using the command line interface . . . . . . . . . . . . . . 1895
To enable content switching by using the configuration utility . . . . . . . . . . . . . . . . . 1895

© 1999-2018 Citrix Systems, Inc. All rights reserved. 65

NetScaler 12.0

Creating content switching virtual servers 1896

To create a virtual server by using the command line interface . . . . . . . . . . . . . . . . 1896
To add a content switching virtual server by using the configuration utility . . . . . . . . . . 1896

Configuring a load balancing setup for content switching 1896

Configuring a content switching action 1897

Configuring an Action that Specifies the Name of the Target Load Balancing Virtual Server . 1898
Configuring an Action that Specifies an Expression for Selecting the Target at Run Time . . . 1899

Configuring content switching policies 1900

To create a content switching policy by using the command line interface . . . . . . . . . . 1901
To rename a content switching policy by using the command line interface . . . . . . . . . 1902
To rename a content switching policy by using the configuration utility . . . . . . . . . . . . 1902
To create a content switching policy by using the configuration utility . . . . . . . . . . . . 1902

Configuring content switching policy labels 1902

To create a content switching policy label by using the command line interface . . . . . . . 1903
To rename a content switching policy label by using the command line interface . . . . . . 1903
To rename a content switching policy label by using the configuration utility . . . . . . . . . 1904
To bind a policy to a content switching policy label by using the command line interface . . 1904
To unbind a policy from a policy label by using the command line interface . . . . . . . . . 1905
To remove a policy label by using the command line interface . . . . . . . . . . . . . . . . . 1905
To manage a content switching policy label by using the configuration utility . . . . . . . . 1905

Binding policies to a content switching virtual server 1905

To bind a policy to a content switching virtual server and select a target load balancing vir-
tual server by using the command line interface . . . . . . . . . . . . . . . . . . . . . 1906
To bind a policy to a content switching virtual server and select a target load balancing vir-
tual server by using the configuration utility . . . . . . . . . . . . . . . . . . . . . . . 1907

Configuring policy based logging for content switching 1907

To configure policy based logging for a content switching policy by using the command line
interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1908
To configure policy based logging for a content switching policy by using the configuration
utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1908

Verifying the configuration 1908

Viewing the Properties of Content Switching Virtual Servers . . . . . . . . . . . . . . . . . . 1909
Viewing Content Switching Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1911
Viewing a Content Switching Virtual Server Configuration by Using the Visualizer . . . . . . 1912

© 1999-2018 Citrix Systems, Inc. All rights reserved. 66

NetScaler 12.0

Customizing the basic content switching configuration 1913

Configuring case sensitivity for policy evaluation . . . . . . . . . . . . . . . . . . . . . . . . 1914
Setting the precedence for policy evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . 1914
Support for multiple ports for HTTP and SSL type content switching virtual servers . . . . . 1916
Configuring per-VLAN Wildcarded virtual servers . . . . . . . . . . . . . . . . . . . . . . . . 1917
Configuring the Microsoft SQL server version setting . . . . . . . . . . . . . . . . . . . . . . 1918

Content switching for diameter protocol 1919

Sample Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1919

Protecting the content switching setup against failure 1920

Configuring a Backup Virtual Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1920
Diverting Excess Traffic to a Backup Virtual Server . . . . . . . . . . . . . . . . . . . . . . . 1921
Configuring a Redirection URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1922
Configuring the State Update Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1923
Flushing the Surge Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1924

Managing a content switching setup 1926

Unbinding Policies from the Content Switching Virtual Server . . . . . . . . . . . . . . . . . 1927
Removing Content Switching Virtual Servers . . . . . . . . . . . . . . . . . . . . . . . . . . 1927
Disabling and Re-Enabling Content Switching Virtual Servers . . . . . . . . . . . . . . . . . 1928
Renaming Content Switching Virtual Servers . . . . . . . . . . . . . . . . . . . . . . . . . . 1929
Managing Content Switching Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1929

Managing client connections 1930

Redirecting Client Requests to a Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1931
Enabling Delayed Cleanup of Virtual Server Connections . . . . . . . . . . . . . . . . . . . 1931
Rewriting Ports and Protocols for Redirection . . . . . . . . . . . . . . . . . . . . . . . . . . 1932
Inserting the IP Address and Port of a Virtual Server in the Request Header . . . . . . . . . . 1933
Setting a Time-out Value for Idle Client Connections . . . . . . . . . . . . . . . . . . . . . . 1933
Identifying Connections with the 4-tuple and Layer 2 Connection Parameters . . . . . . . . 1934

Troubleshooting 1935
Resources for Troubleshooting Content Switching . . . . . . . . . . . . . . . . . . . . . . . 1935
Troubleshooting Content Switching Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . 1936

DataStream 1937
How DataStream Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1938

Configuring Database Users 1939

To add a database user by using the command line interface . . . . . . . . . . . . . . . . . 1939
To add a database user by using the configuration utility . . . . . . . . . . . . . . . . . . . 1939

© 1999-2018 Citrix Systems, Inc. All rights reserved. 67

NetScaler 12.0

To reset the password of a database user by using the command line interface . . . . . . . . 1939
To reset the password of database users by using the configuration utility . . . . . . . . . . 1940
To remove a database user by using the configuration utility . . . . . . . . . . . . . . . 1940

Configuring a Database Profile 1940

To create a database profile by using the command line interface . . . . . . . . . . . . . . . 1941
To create a database profile by using the configuration utility . . . . . . . . . . . . . . . . . 1941
To bind a database profile to a load balancing or content switching virtual server by using
the command line interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1941
To bind a database profile to a load balancing or content switching virtual server by using
the configuration utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1942

Configuring Load Balancing for DataStream 1942

Parameter values specific to DataStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1942

Configuring Content Switching for DataStream 1944

Parameter values specific to DataStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1944

Configuring Monitors for DataStream 1945

Use Case 1: Configuring DataStream for a Master/Slave Database Architecture 1947

To configure DataStream for a master/slave database setup by using the command line in-
terface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1948

Use Case 2: Configuring the Token Method of Load Balancing for DataStream 1949
To configure this example by using the command line interface . . . . . . . . . . . . . . . . 1950
To configure this example by using the configuration utility . . . . . . . . . . . . . . . . . . 1950

Use Case 3: Logging MSSQL Transactions in Transparent Mode 1951

Summary of Configuration Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1951
Configuring Transparent Mode by Using a Wildcard Virtual Server . . . . . . . . . . . . . . . 1952
Configuring Transparent Mode by Using MSSQL Services . . . . . . . . . . . . . . . . . . . 1953

Use Case 4: Database Specific Load Balancing 1954

How Database Specific Load Balancing Works . . . . . . . . . . . . . . . . . . . . . . . . . 1955
Enabling Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1956
Configuring a Load Balancing Virtual Server for Database Specific Load Balancing . . . . . . 1956
To configure a load balancing virtual server for database specific load balancing . . . . . . 1957
Configuring Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1957
Configuring Database Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1957
Configuring a Monitor to Retrieve the Names of Active Databases . . . . . . . . . . . . . . . 1959
Availability Groups Deployment Support for MSSQL . . . . . . . . . . . . . . . . . . . . . . 1960

© 1999-2018 Citrix Systems, Inc. All rights reserved. 68

NetScaler 12.0

Configuration examples for MSSQL virtual server . . . . . . . . . . . . . . . . . . . . . . . . 1962

Configuration examples for MySQL virtual server . . . . . . . . . . . . . . . . . . . . . . . . 1963

DataStream Reference 1964

Supported Database Versions, Protocols, and Authentication Methods . . . . . . . . . . . . 1965
Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1965
Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1966
Special Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1966
Audit Log Message Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1967

Domain Name System 1968

How DNS Works on the NetScaler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1968
Round Robin DNS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1970

Configure DNS resource records 1971

Create SRV records for a service 1972

Add an SRV record by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1973
Modify or remove an SRV record by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . 1973
Configure an SRV record by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1973

Creating AAAA Records for a Domain Name 1974

Add an AAAA record by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1974
Add an AAAA record by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1974

Creating address records for a Domain Name 1975

Add an Address record by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1975
Add an Address record by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1975

Create MX records for a mail exchange server 1976

Add an MX record by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1976
Modify or remove an MX record by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . 1977
Add an MX record by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1977

Create NS Records for an authoritative server 1977

Create an NS record by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1977
Create an NS record by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1978

Create CNAME records for a subdomain 1978

Add a CNAME record by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1978
Add a CNAME record by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1979
Cache CNAME records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1979

© 1999-2018 Citrix Systems, Inc. All rights reserved. 69

NetScaler 12.0

Create NAPTR records for telecommunications domain 1979

Create a NAPTR record by using CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1980
Remove a NAPTR record by using CLU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1980
Configure a NAPTR record using GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1980

Create PTR records for IPv4 and IPv6 addresses 1980

Add a PTR record by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1981
Add a PTR record by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1981

Create SOA records for authoritative information 1982

Create an SOA record by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1982
Modify or remove an SOA record by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . 1982
Configure an SOA record by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1983

Create TXT records for holding descriptive text 1983

Create a TXT resource record by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . 1983
Remove a TXT resource record by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . 1984
Configure a TXT record by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1985

Viewing DNS statistics 1985

View DNS records statistics by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . 1985
View DNS records statistics by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . 1986

Configure a DNS zone 1986

Create a DNS zone on the NetScaler appliance by using the CLI . . . . . . . . . . . . . . . . 1987
Modify or remove a DNS zone by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . 1988
Configure a DNS zone by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1988

Configure the NetScaler as an ADNS server 1988

Create an ADNS service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1989
Configure the ADNS setup to use TCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1989
Add DNS resource records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1990
Remove ADNS services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1990
Configure domain delegation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1990

Configure the NetScaler appliance as a DNS proxy server 1991

Create a load balancing virtual server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1993
Create DNS services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1993
Bind a load balancing virtual server to DNS services . . . . . . . . . . . . . . . . . . . . . . 1993
Configure the DNS proxy setup to use TCP . . . . . . . . . . . . . . . . . . . . . . . . . . . 1993
Configure time-to-live values for DNS entries . . . . . . . . . . . . . . . . . . . . . . . . . . 1994
Flush DNS records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1995

© 1999-2018 Citrix Systems, Inc. All rights reserved. 70

NetScaler 12.0

Add DNS resource records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1995

Remove a load balancing DNS virtual server . . . . . . . . . . . . . . . . . . . . . . . . . . 1995
Limit the number of concurrent DNS requests on a client connection . . . . . . . . . . . . . 1995

Configure the NetScaler as an end resolver 1997

Enable recursive resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1997
Set the Number of Retries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1998

Configure the NetScaler appliance as a forwarder 1999

Add a name server 2000

Add a name server (when the NetScaler appliance acts as a forwarder) by using the CLI . . . 2000
Add a name server (when the NetScaler appliance acts as a resolver) by using the CLI . . . . 2000

Set DNS lookup priority 2001

Set the lookup priority to DNS by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . 2001
Set lookup priority to DNS by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . 2002

Disable and enable name servers 2002

Enable or disable a name server by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . 2002
Enable or disable a name server by using the GUI . . . . . . . . . . . . . . . . . . . . . . . 2003

Configure DNS logging 2003

DNS profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2004
Understand the NetScaler syslog log message format . . . . . . . . . . . . . . . . . . . . . 2005
Understand the record logging format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2009
Limitations of DNS logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2010
Configuring DNS logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2011
Sample DNS logging configuration for NetScaler appliance configured as DNS proxy . . . . 2013
Sample DNS logging configuration for NetScaler appliance configured as ADNS . . . . . . . 2013
Sample DNS logging configuration for NetScaler appliance configured as a forwarder . . . . 2014
Sample DNS logging configuration for NetScaler appliance configured as a sesolver . . . . . 2014
Configure policy based logging for DNS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2015

Configuring DNS suffixes 2017

Create DNS suffixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2017

DNS ANY query 2018

Behavior in ADNS mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2018
Behavior in DNS proxy mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2018
Behavior for GSLB domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 71

NetScaler 12.0

Configure negative caching of DNS records 2019

Enable or disable negative caching by using the CLI . . . . . . . . . . . . . . . . . . . . . . 2020
Specify service or virtual server level DNS parameters by using the CLI . . . . . . . . . . . . 2020
Specify service or virtual server level DNS parameters by using the GUI . . . . . . . . . . . . 2021

Cache EDNS0 client subnet data when the NetScaler appliance is in proxy mode 2021
Enable caching of ECS responses by using the CLI . . . . . . . . . . . . . . . . . . . . . . . 2022
Limit the number of subnets that can be cached per domain by using the CLI . . . . . . . . 2022

Domain name system security extensions 2022

Configure DNSSEC 2023

Enable and disable DNSSEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2023
Create DNS keys for a zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2024
Publish a DNS key in a zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2026
Configure a DNS key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2027
Sign and unsign a DNS zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2028
View the NSEC records for a given record in a zone . . . . . . . . . . . . . . . . . . . . . . . 2030
Remove a DNS key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2031

Configure DNSSEC when the NetScaler is authoritative for a zone 2032

Configure DNSSEC for a zone for which the NetScaler is a DNS proxy server 2032
Configure DNSSEC for a zone-less DNS proxy server configuration . . . . . . . . . . . . . . 2033
Configure DNSSEC for a partial zone ownership configuration . . . . . . . . . . . . . . . . . 2033

Configure DNSSEC for GSLB domain names 2034

Zone Maintenance 2035

Re-sign an updated zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2035
Roll over DNSSEC keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2035

Offload DNSSEC operations to the NetScaler 2039

Enable DNSSEC offloading for a zone by using the CLI . . . . . . . . . . . . . . . . . . . . . 2040
Enable DNSSEC offloading for a zone by using the GUI . . . . . . . . . . . . . . . . . . . . . 2040

Admin partition support for DNSSEC 2040

Supporting wildcard DNS domains 2041

Example configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2042

Mitigate DNS DDoS attacks 2043

Flush negative records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2043

© 1999-2018 Citrix Systems, Inc. All rights reserved. 72

NetScaler 12.0

Protection against random subdomain and NXDOMAIN attacks . . . . . . . . . . . . . . . . 2044

Retain DNS records in the cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2045
Enable DNS cache bypass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2046
Prevent the Slowloris attack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2046
Collect statistics of the DNS responses served from the cache . . . . . . . . . . . . . . . . . 2047

Firewall Load Balancing 2048

Firewall Load Balancing Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2049
Firewall Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2049
Firewall Server Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2049

Sandwich Environment 2049

Configuring the External NetScaler in a Sandwich Environment . . . . . . . . . . . . . . . . 2050
Configuring the Internal NetScaler in a Sandwich Environment . . . . . . . . . . . . . . . . 2055
Monitoring a Firewall Load Balancing Setup in a Sandwich Environment . . . . . . . . . . . 2064

Enterprise Environment 2065

Configuring the NetScaler in an Enterprise Environment . . . . . . . . . . . . . . . . . . . . 2066
Monitoring a Firewall Load Balancing Setup in an Enterprise Environment . . . . . . . . . . 2074

Multiple-Firewall Environment 2076

Configuring the NetScaler in a Multiple-Firewall Environment . . . . . . . . . . . . . . . . . 2077
Monitoring a Firewall Load Balancing Setup in a Multiple-Firewall Environment . . . . . . . 2084

Global Server Load Balancing 2085

GSLB deployment types 2086

Active-active site deployment 2087

GSLB active-active datacenter topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2088

Active-passive site deployment 2088

GSLB active-passive datacenter topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2089

Parent-child topology deployment using the MEP protocol 2090

Basic parent-child topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2091
Setting up a parent-child configuration for GSLB . . . . . . . . . . . . . . . . . . . . . . . . 2091
Backing up a parent site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2093
To configure a backup parent site by using the command line interface . . . . . . . . . . . . 2094
To configure a backup parent site by using the GUI . . . . . . . . . . . . . . . . . . . . . . . 2094

GSLB configuration entities 2095

GSLB Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2095

© 1999-2018 Citrix Systems, Inc. All rights reserved. 73

NetScaler 12.0

GSLB Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2096

GSLB Virtual Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2096
Load Balancing or Content Switching Virtual Servers . . . . . . . . . . . . . . . . . . . . . . 2097
ADNS Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2097
DNS VIPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2097

GSLB methods 2097

Specifying a GSLB method other than static proximity or dynamic RTT . . . . . . . . . . . . 2098

GSLB algorithms 2099

Static proximity 2100

Dynamic round trip time method 2101

Configure a GSLB virtual server for dynamic RTT . . . . . . . . . . . . . . . . . . . . . . . . 2102
Set the probing interval of local DNS servers . . . . . . . . . . . . . . . . . . . . . . . . . . 2102

Configure static proximity 2103

Add a location file to create a static proximity database 2104

To add a static location file by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . 2105
To add a static location file by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . 2106
To view a static location file by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . 2106
To convert a location file into the NetScaler format . . . . . . . . . . . . . . . . . . . . . . . 2106

Add custom entries to a static proximity database 2106

To add custom entries by using the command line interface . . . . . . . . . . . . . . . . . . 2107
Parameters for adding custom entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2107
To add custom entries by using the configuration utility . . . . . . . . . . . . . . . . . . . . 2108

Set location qualifiers 2108

To set the location qualifiers by using the command line interface . . . . . . . . . . . . . . 2109
To set the location qualifiers by using the configuration utility . . . . . . . . . . . . . . . . . 2109

Specify proximity method 2110

To specify static proximity by using the command line interface . . . . . . . . . . . . . . . . 2110
To specify static proximity by using the configuration utility . . . . . . . . . . . . . . . . . . 2110

Synchronize GSLB static proximity database 2110

Configure site-to-site communication 2111

Changing the password of an RPC node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2112
Encrypt the exchange of site metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2113

© 1999-2018 Citrix Systems, Inc. All rights reserved. 74

NetScaler 12.0

Configure source IP address for an RPC node . . . . . . . . . . . . . . . . . . . . . . . . . . 2114

Configure metrics exchange protocol 2115

Enable site metrics exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2116
Enable network metric exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2117
Configuring a time delay for the GSLB services to be marked as DOWN when a MEP connec-
tion goes DOWN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2117
Enable persistence information exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2118

Configure GSLB by using a wizard 2119

Configure active-active site 2120

To configure an active-active site by using the wizard . . . . . . . . . . . . . . . . . . . . . 2120

Configure active-passive site 2122

To configure an active-passive site by using the wizard . . . . . . . . . . . . . . . . . . . . . 2123

Configure parent-child topology 2125

To configure a parent-child deployment by using the wizard . . . . . . . . . . . . . . . . . . 2126

Configure GSLB entities individually 2128

Configuring a Standard Load Balancing Setup . . . . . . . . . . . . . . . . . . . . . . . . . 2129

Configure an authoritative DNS service 2129

To create an ADNS service by using the command line interface . . . . . . . . . . . . . . . . 2130
To modify an ADNS service by using the command line interface . . . . . . . . . . . . . . . 2130
To remove an ADNS service by using the command line interface . . . . . . . . . . . . . . . 2130
To configure an ADNS service by using the configuration utility . . . . . . . . . . . . . . . . 2131

Configure a basic GSLB site 2131

To create a GSLB site by using the command line interface . . . . . . . . . . . . . . . . . . . 2131
To modify or remove a GSLB Site by using the command line interface . . . . . . . . . . . . 2132
To configure a basic GSLB site by using the configuration utility . . . . . . . . . . . . . . . . 2132
To view the statistics of a GSLB site by using the command line interface . . . . . . . . . . . 2132
To view the statistics of a GSLB site by using the configuration utility . . . . . . . . . . . . . 2132

Configure a GSLB service 2132

To create a GSLB service by using the command line interface . . . . . . . . . . . . . . . . . 2133

Configure a GSLB service group 2135

GSLB domain name based autoscale service groups . . . . . . . . . . . . . . . . . . . . . . 2135

© 1999-2018 Citrix Systems, Inc. All rights reserved. 75

NetScaler 12.0

Configure a GSLB virtual server 2141

To create a GSLB virtual server by using the command line interface . . . . . . . . . . . . . 2141
Clearing the GSLB virtual server or service statistics . . . . . . . . . . . . . . . . . . . . . . 2143
Enabling and Disabling GSLB Virtual Servers . . . . . . . . . . . . . . . . . . . . . . . . . . 2144

Bind GSLB services to a GSLB virtual server 2145

To bind a GSLB service to a GSLB virtual server by using the command line interface . . . . 2145
To unbind a GSLB service from a GSLB virtual server by using the command line interface . 2145
To bind GSLB services by using the configuration utility . . . . . . . . . . . . . . . . . . . . 2145

Bind a domain to a GSLB virtual server 2146

To bind a domain to a GSLB virtual server by using the command line interface . . . . . . . 2146
To unbind a GSLB domain from a GSLB virtual server by using the command line interface . 2146
To bind a domain to a GSLB virtual server by using the configuration utility . . . . . . . . . 2146
To view the statistics of a domain by using the command line interface . . . . . . . . . . . . 2147
To view the statistics of a domain by using the configuration utility . . . . . . . . . . . . . . 2147
To view the configuration details of the entities bound to a GSLB domain using the command
line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2147
To view the configuration details of the entities bound to a GSLB domain by using the con-
figuration utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2149

Example of a GSLB setup and configuration 2149

To configure the GSLB setup with NetScaler appliances by using the CLI commands . . . . . 2150

Synchronize the configuration in a GSLB setup 2151

Manual synchronization between sites participating in GSLB 2154

Previewing GSLB synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2155

Real-time synchronization between sites participating in GSLB 2156

Best practices for using the real-time synchronization feature . . . . . . . . . . . . . . . . . 2157
To enable real-time synchronization by using the CLI . . . . . . . . . . . . . . . . . . . . . . 2157
To enable real-time synchronization by using the GUI . . . . . . . . . . . . . . . . . . . . . 2157

GSLB dashboard 2158

Monitor GSLB services 2158

Configure monitor trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2159
Add or remove monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2159
Bind monitors to a GSLB service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2160

© 1999-2018 Citrix Systems, Inc. All rights reserved. 76

NetScaler 12.0

Use case: Deployment of domain name based autoscale service group 2161
Deployment scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2162

Use case: Deployment of IP address based autoscale service group 2163

Deployment scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2164

How-to articles 2165

Customize your GSLB configuration 2166

Modify maximum connections or maximum bandwidth for a GSLB service . . . . . . . . . . 2166
Create CNAME-based GSLB services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2167
Configure transition Out-Of-Service State (TROFS) in GSLB . . . . . . . . . . . . . . . . . . 2168
Configure dynamic weights for services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2169

Configure persistent connections 2170

Configure persistence based on source IP address . . . . . . . . . . . . . . . . . . . . . . . 2171
Configure persistence based on HTTP cookies . . . . . . . . . . . . . . . . . . . . . . . . . 2172

Manage client connections 2174

Enable delayed cleanup of virtual server connections . . . . . . . . . . . . . . . . . . . . . 2175
Manage local DNS traffic by using DNS policies . . . . . . . . . . . . . . . . . . . . . . . . . 2175
Adding DNS Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2183

Configure GSLB for proximity 2184

Configure dynamic round trip time (RTT) method . . . . . . . . . . . . . . . . . . . . . . . 2184
Configure static proximity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2185
Configure static proximity and dynamic RTT . . . . . . . . . . . . . . . . . . . . . . . . . . 2185

Protect the GSLB setup against failure 2186

Configure a backup GSLB virtual server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2186
Configure a GSLB setup to respond with multiple IP addresses . . . . . . . . . . . . . . . . 2187
Configuring a GSLB Virtual Server to Respond with an Empty Address Record When DOWN . 2188
Configure a backup IP address for a GSLB domain . . . . . . . . . . . . . . . . . . . . . . . 2188
Divert excess traffic to a backup virtual server . . . . . . . . . . . . . . . . . . . . . . . . . 2189

Configure GSLB for disaster recovery 2191

Configure GSLB for disaster recovery in an active-standby data center setup . . . . . . . . . 2192
Configure for disaster recovery in an active-active data center setup . . . . . . . . . . . . . 2193
Configuring for Disaster Recovery with Weighted Round Robin . . . . . . . . . . . . . . . . 2193
Configuring for Disaster Recovery with Data Center Persistence . . . . . . . . . . . . . . . . 2195

© 1999-2018 Citrix Systems, Inc. All rights reserved. 77

NetScaler 12.0

Override static proximity behavior by configuring preferred locations 2196

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2198

Configure GSLB service selection using content switching 2199

Sample Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2200

Configure GSLB for DNS queries with NAPTR records 2202

NAPTR Record Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2202
Configuration procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2203
Sample configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2204

Use the EDNS0 client subnet option for GSLB 2205

Address validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2206

Example of a complete parent-child configuration using the metrics exchange protocol 2208
site1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2209
site1_child1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2210
site1_child2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2210
site2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2211
site2_child1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2212
site2_child2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2212

Link load balancing 2213

Configuring a Basic LLB Setup 2214

Configure services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2214
Configure an LLB virtual server and bind a service . . . . . . . . . . . . . . . . . . . . . . . 2216
Configure the LLB method and persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . 2217
Configure an LLB route . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2218
Create and bind a transparent monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2220

Configuring RNAT with LLB 2223

To add SNIPs for ISP routers by using the command line interface . . . . . . . . . . . . . . . 2223
To configure RNAT by using the command line interface . . . . . . . . . . . . . . . . . . . . 2224
To configure RNAT by using the configuration utility . . . . . . . . . . . . . . . . . . . . . . 2224
To enable Use Subnet IP mode by using the command line interface . . . . . . . . . . . . . 2224
To enable Use Subnet IP mode by using the configuration utility . . . . . . . . . . . . . . . 2225

Configuring a Backup Route 2225

To set the secondary virtual server as the backup virtual server by using the command line
interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2226

© 1999-2018 Citrix Systems, Inc. All rights reserved. 78

NetScaler 12.0

To set the secondary virtual server as the backup virtual server by using the configuration
utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2226

Resilient LLB Deployment Scenario 2227

Monitoring an LLB Setup 2227

Viewing the Statistics of a Virtual Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2228
Viewing the Statistics of a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2229

Load Balancing 2229

How load balancing works 2230

Load balancing basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2230
Understanding the topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2232
Use of wildcards instead of IP addresses and ports . . . . . . . . . . . . . . . . . . . . . . . 2232
Configuring global HTTP ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2237

Set up basic load balancing 2239

Enabling Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2239
Configuring a Server Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2240
Configuring Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2241
Creating a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2241
Creating a Virtual Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2245
Binding Services to the Virtual Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2246
Verifying the Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2247

Load balance virtual server and service states 2251

Support for load balancing profile 2253

To create an LB profile by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2253
To create an LB profile by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2254
To associate an LB profile with an LB virtual server by using the CLI . . . . . . . . . . . . . . 2254
To associate an LB profile with an LB virtual server by using the GUI . . . . . . . . . . . . . 2255

Load balancing algorithms 2255

To set the startup round-robin factor by using the CLI . . . . . . . . . . . . . . . . . . . . . 2258
To set the startup round-robin factor by using the GUI . . . . . . . . . . . . . . . . . . . . . 2258

Least connection method 2258

Round robin method 2263

© 1999-2018 Citrix Systems, Inc. All rights reserved. 79

NetScaler 12.0

Least response time method 2264

Selection of services when weights are assigned . . . . . . . . . . . . . . . . . . . . . . . . 2266

LRTM method 2268

Selection of services when weights are assigned . . . . . . . . . . . . . . . . . . . . . . . . 2271

Hashing methods 2273

The URL Hash Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2275
The Domain Hash Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2276
The Destination IP Hash Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2276
The Source IP Hash Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2276
The Source IP Destination IP Hash Method . . . . . . . . . . . . . . . . . . . . . . . . . . . 2277
The Source IP Source Port Hash Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2277
The Call ID Hash Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2277

Least bandwidth method 2278

Least packets method 2282

Custom load method 2285

Static proximity method 2288

Specifying the Proximity Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2289

Token method 2289

To configure the Token load balancing method by using the command line interface . . . . 2290
To configure the token load balancing method by using the configuration utility . . . . . . . 2291

Configure a load balancing method that does not include a policy 2291
To set the load balancing method by using the command line interface . . . . . . . . . . . . 2291
To set the load balancing method by using the configuration utility . . . . . . . . . . . . . . 2292

Persistence and persistent connections 2292

About Persistence 2293

Source IP address persistence 2295

HTTP cookie persistence 2296

To change the httponly flag setting by using the command line interface . . . . . . . . . . . 2297
To change the httponly flag setting by using the configuration utility . . . . . . . . . . . . . 2298
Encrypting the Cookie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2298

© 1999-2018 Citrix Systems, Inc. All rights reserved. 80

NetScaler 12.0

SSL session ID persistence 2299

Backup Persistence Support for SSL session ID . . . . . . . . . . . . . . . . . . . . . . . . . 2299

Diameter AVP number persistence 2300

To configure Diameter-based persistence on a virtual server by using the command line in-
terface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2300

Custom server ID persistence 2301

To configure custom server ID persistence by using the configuration utility . . . . . . . . . 2302

IP address persistence 2302

Persistence Based on Destination IP Addresses . . . . . . . . . . . . . . . . . . . . . . . . . 2302
Persistence Based on Source and Destination IP Addresses . . . . . . . . . . . . . . . . . . 2303

SIP Call ID persistence 2303

RTSP session ID persistence 2304

Configure URL passive persistence 2304

To configure URL passive persistence by using the CLI . . . . . . . . . . . . . . . . . . . . . 2305
To configure persistence on a virtual server by using the GUI . . . . . . . . . . . . . . . . . 2306

Configure persistence based on user-defined rules 2306

To configure persistence based on user-defined rules by using the CLI . . . . . . . . . . . . 2307
To configure persistence based on user-defined rules by using the GUI . . . . . . . . . . . . 2307

Configure persistence types that do not require a rule 2308

To configure persistence on a virtual server by using the CLI . . . . . . . . . . . . . . . . . . 2309
To configure persistence on a virtual server by using the GUI . . . . . . . . . . . . . . . . . 2309

Configure backup persistence 2310

To set backup persistence for a virtual server by using the command line interface . . . . . 2311
To set backup persistence for a virtual server by using the configuration utility . . . . . . . . 2311

Configure persistence groups 2312

To create a virtual server persistency group by using the command line interface . . . . . . 2312
To modify a virtual server group by using the configuration utility . . . . . . . . . . . . . . . 2313
To modify a virtual server group by using the command line interface . . . . . . . . . . . . 2313

Share persistent sessions between virtual servers 2313

Configuring Sharing of Persistent Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . 2314
To enable the useVserverPersistency parameter by using the command line interface . . . . 2314
To enable the useVserverPersistency parameter by using the GUI . . . . . . . . . . . . . . . 2314

© 1999-2018 Citrix Systems, Inc. All rights reserved. 81

NetScaler 12.0

To designate a vserver as a master vserver by using the command line interface . . . . . . . 2315
To designate a vserver as a master vserver by using the GUI . . . . . . . . . . . . . . . . . . 2315
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2315

Configure RADIUS load balancing with persistence 2317

Enabling the Load Balancing or Content Switching Feature . . . . . . . . . . . . . . . . . . 2318
Configuring Virtual Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2318
Configuring Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2319
Binding Virtual Servers to Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2320
Configuring a Persistency Group for Radius . . . . . . . . . . . . . . . . . . . . . . . . . . . 2320
Configuring RADIUS Shared Secret . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2320

View persistence sessions 2322

To view a persistence session by using the command line interface . . . . . . . . . . . . . . 2322
To view persistence sessions by using the configuration utility . . . . . . . . . . . . . . . . 2323

Clear persistence sessions 2323

To clear a persistence session by using the command line interface . . . . . . . . . . . . . . 2323
To clear persistence sessions by using the configuration utility . . . . . . . . . . . . . . . . 2324

Override persistence settings for overloaded services 2324

To override persistence settings for overloaded services by using the command line interface 2325
To override persistence settings for overloaded services by using the configuration utility . . 2326

Troubleshooting 2326

Customize a load balancing configuration 2328

Customize the hash algorithm for persistence across virtual servers 2329
To change the use-port-number global setting by using the CLI . . . . . . . . . . . . . . . . 2330
To change the use-port-number global setting by using the GUI . . . . . . . . . . . . . . . . 2330
To create a new service and specify a hash identifier for a service by using the CLI . . . . . . 2330
To specify a hash identifier for an existing service by using the CLI . . . . . . . . . . . . . . 2331
To specify a hash identifier while adding a service group member . . . . . . . . . . . . . . . 2331
To specify a hash identifier for a service by using the GUI . . . . . . . . . . . . . . . . . . . 2332
To specify a hash identifier for an already configured service group member by using the GUI 2332

Configure the redirection mode 2332

To configure the redirection mode by using the CLI . . . . . . . . . . . . . . . . . . . . . . . 2333
To configure the redirection mode by using the GUI . . . . . . . . . . . . . . . . . . . . . . 2333

© 1999-2018 Citrix Systems, Inc. All rights reserved. 82

NetScaler 12.0

Configure per-VLAN wildcarded virtual servers 2333

To configure a wildcarded virtual server that listens to a specific VLAN by using the CLI . . . 2334
To configure a wildcarded virtual server that listens to a specific VLAN by using the GUI . . . 2334

Assign weights to services 2334

To configure a virtual server to assign weights to services by using the CLI . . . . . . . . . . 2336
To configure a virtual server to assign weights to services by using the GUI . . . . . . . . . . 2336

Configure the MySQL and Microsoft SQL server version setting 2336
To set the Microsoft SQL server version parameter by using the CLI . . . . . . . . . . . . . . 2336
To set the MySQL server version parameter by using the CLI . . . . . . . . . . . . . . . . . . 2337
To set the MySQL or Microsoft SQL server version parameter by using the GUI . . . . . . . . 2337

Configure diameter load balancing 2338

How diameter load balancing works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2339
Load balancing diameter traffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2339
Disconnect a session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2340
Configure load balancing for diameter traffic . . . . . . . . . . . . . . . . . . . . . . . . . . 2340

Configure FIX load balancing 2343

How FIX load balancing works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2343
Configure and monitor load balancing for FIX traffic . . . . . . . . . . . . . . . . . . . . . . 2343
To display FIX persistent sessions by using the command line interface . . . . . . . . . . . . 2346
To configure FIX load balancing virtual server by using the GUI . . . . . . . . . . . . . . . . 2346
To edit a FIX load balancing virtual server by using the GUI . . . . . . . . . . . . . . . . . . 2347
To delete a FIX load balancing virtual server by using the GUI . . . . . . . . . . . . . . . . . 2347
To configure FIX Load Balancing Virtual Service by using the GUI . . . . . . . . . . . . . . . 2347
To display FIX load balancing server statistics . . . . . . . . . . . . . . . . . . . . . . . . . . 2348
To display Persistent sessions for a FIX server by using the GUI . . . . . . . . . . . . . . . . 2348
To clear Persistent sessions for a FIX server by using the GUI . . . . . . . . . . . . . . . . . . 2348

Protect a load balancing configuration against failure 2348

Redirect client requests to an alternate URL 2349

To configure a virtual server to redirect the client request to a URL by using the CLI . . . . . 2349
To configure a virtual server to redirect the client request to a URL by using the GUI . . . . . 2349

Configure a backup load balancing virtual server 2350

To set a backup virtual server by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . 2350
To set a backup virtual server by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . 2351

© 1999-2018 Citrix Systems, Inc. All rights reserved. 83

NetScaler 12.0

Configure spillover 2351

Configure a predefined spillover method . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2352
Configure policy based spillover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2353

Connection failover 2358

How connection failover works on NetScaler appliances . . . . . . . . . . . . . . . . . . . . 2359
Supported setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2359
Features affected by connection failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2360

Flush the surge queue 2362

To flush a surge queue by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2363
To flush a surge queue by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2364

Manage a load balancing setup 2364

Manage server objects 2365

To enable a server by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2365
To enable or disable a server object by using the GUI . . . . . . . . . . . . . . . . . . . . . . 2365
To disable a server object by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . 2365
To remove a server object by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . 2366
To remove a server object by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . 2366

Manage services 2366

To enable or disable a service by using the command line interface . . . . . . . . . . . . . . 2367
To enable or disable a service by using the configuration utility . . . . . . . . . . . . . . . . 2367

Manage a load balancing virtual server 2367

To enable or disable a virtual server by using the command line interface . . . . . . . . . . 2368
To enable or disable a virtual server by using the configuration utility . . . . . . . . . . . . 2368
To unbind a service from a virtual server by using the command line interface . . . . . . . . 2368
To unbind a service from a virtual server by using the configuration utility . . . . . . . . . . 2368

Load balancing visualizer 2369

To view load balancing virtual server properties by using the Visualizer . . . . . . . . . . . . 2369
To view configuration details for services, service groups, and monitors by using the Visualizer2370
To view configuration details for policies and policy labels by using the Visualizer in the con-
figuration utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2370
To modify a resource in a load balancing configuration by using the Visualizer . . . . . . . . 2370
To add a load balancing configuration by using the Visualizer . . . . . . . . . . . . . . . . . 2370

Manage client traffic 2370

© 1999-2018 Citrix Systems, Inc. All rights reserved. 84

NetScaler 12.0

Configure sessionless load balancing virtual servers 2372

Supported setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2372
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2373
To add a sessionless virtual server by using the CLI . . . . . . . . . . . . . . . . . . . . . . . 2373
To configure a sessionless virtual server by using the GUI . . . . . . . . . . . . . . . . . . . 2374

Redirect HTTP requests to a cache 2375

To configure cache redirection on a virtual server by using the CLI . . . . . . . . . . . . . . 2375
To configure cache redirection on a virtual server by using the GUI . . . . . . . . . . . . . . 2375

Direct requests according to priority 2375

To configure priority queuing on a virtual server by using the CLI . . . . . . . . . . . . . . . 2376
To configure priority queuing on a virtual server by using the GUI . . . . . . . . . . . . . . . 2376

Direct requests to a custom web page 2376

To enable SureConnect on a virtual server by using the CLI . . . . . . . . . . . . . . . . . . 2377
To enable SureConnect on a virtual server by using the GUI . . . . . . . . . . . . . . . . . . 2377

Enable cleanup of virtual server connections 2377

To configure the down state flush setting on a virtual server by using the CLI . . . . . . . . . 2379
To configure the down state flush setting on a virtual server by using the GUI . . . . . . . . 2379

Rewrite ports and protocols for HTTP redirection 2380

To configure HTTP redirection on a virtual server by using the CLI . . . . . . . . . . . . . . . 2384
To configure HTTP redirection on a virtual server by using the GUI . . . . . . . . . . . . . . 2384
To configure SSL Redirect on an SSL virtual server or service by using the CLI . . . . . . . . 2384
To configure SSL redirection and SSL port rewrite on an SSL virtual server or service by using
the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2384

Insert IP address and port of a virtual server in the request header 2385
To insert the IP address and port of the virtual server in the client requests by using the CLI 2385
To insert the IP address and port of the virtual server in the client requests by using the GUI 2385

Use a specified source IP for backend communication 2386

Usage of a net profile for sending traffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2387
Manage net profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2388
Create an IP set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2388
Create a net profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2390
Bind a net profile to a NetScaler entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2390

Set a time-out value for idle client connections 2393

To set a time-out value for idle client connections by using the CLI . . . . . . . . . . . . . . 2393

© 1999-2018 Citrix Systems, Inc. All rights reserved. 85

NetScaler 12.0

To set a time-out value for idle client connections by using the GUI . . . . . . . . . . . . . . 2393

Manage RTSP connections 2393

To configure RTSP NAT by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2394
To configure RTSP NAT by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2394

Manage client traffic on the basis of traffic rate 2394

Identify a connection with layer 2 parameters 2395

To configure the L2 connection option by using the CLI . . . . . . . . . . . . . . . . . . . . 2396
To configure the L2 connection option by using the GUI . . . . . . . . . . . . . . . . . . . . 2396

Configure the prefer direct route option 2396

To set the prefer direct route option by using the CLI . . . . . . . . . . . . . . . . . . . . . . 2397
To set the prefer direct route option by using the GUI . . . . . . . . . . . . . . . . . . . . . 2397

Use a source port from a specified port range for backend communication 2397
To specify a source port range or ranges by using the CLI . . . . . . . . . . . . . . . . . . . . 2398
To specify a source port range or ranges by using the GUI . . . . . . . . . . . . . . . . . . . 2398

Configure source IP persistency for backend communication 2399

To enable source IP persistency in a net profile by using the CLI . . . . . . . . . . . . . . . . 2399
To enable source IP persistency in a net profile by using the GUI . . . . . . . . . . . . . . . . 2399
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2400

Use IPv6 link local addresses on server side of a load balancing setup 2400

Advanced load balancing settings 2401

Gradually stepping up the load on a new service with virtual server–level slow start 2402
Manual slow start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2403
Automated slow start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2405
Set the slow start parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2407

The no-monitor option for services 2409

To set the no-monitor option for a new service by using the CLI . . . . . . . . . . . . . . . . 2409
To set the no-monitor option for an existing service by using the CLI . . . . . . . . . . . . . 2410
To set the no-monitor option for a service by using the GUI . . . . . . . . . . . . . . . . . . 2411

Protect applications on protected servers against traffic surges 2412

To set surge protection on the service by using the CLI . . . . . . . . . . . . . . . . . . . . . 2412
To set surge protection on the service by using the GUI . . . . . . . . . . . . . . . . . . . . 2412

© 1999-2018 Citrix Systems, Inc. All rights reserved. 86

NetScaler 12.0

Enable cleanup of virtual server and service connections 2412

To set down state flush on the service by using the CLI . . . . . . . . . . . . . . . . . . . . . 2414
To set down state flush on the service by using the GUI . . . . . . . . . . . . . . . . . . . . 2414
To set down state flush on the virtual server by using the CLI . . . . . . . . . . . . . . . . . 2415
To set down state flush on the virtual server by using the GUI . . . . . . . . . . . . . . . . . 2415

Graceful shutdown of services 2415

Adding a TROFS Code or String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2416
Disabling a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2417
To configure graceful shutdown for a service by using the command line interface . . . . . . 2418
To configure graceful shutdown for a service by using the configuration utility . . . . . . . . 2419

Enable or disable persistence session on TROFS services 2419

To set the trofsPersistence flag by using the command line interface . . . . . . . . . . . . . 2420

Direct requests to a custom web page 2420

To set SureConnect on the service by using the CLI . . . . . . . . . . . . . . . . . . . . . . . 2421
To set SureConnect on the service by using the GUI . . . . . . . . . . . . . . . . . . . . . . 2421

Enable access to services when down 2421

To enable access down on a service by using the CLI . . . . . . . . . . . . . . . . . . . . . . 2421
To enable access down on a service by using the GUI . . . . . . . . . . . . . . . . . . . . . . 2422

Enable TCP buffering of responses 2422

To enable TCP Buffering on a service by using the CLI . . . . . . . . . . . . . . . . . . . . . 2422
To enable TCP Buffering on a service by using the GUI . . . . . . . . . . . . . . . . . . . . . 2423

Enable compression 2423

To enable compression on a service by using the CLI . . . . . . . . . . . . . . . . . . . . . . 2423
To enable compression on a service by using the GUI . . . . . . . . . . . . . . . . . . . . . 2423

Maintain client connection for multiple client requests 2424

To enable client keep-alive on a service by using the CLI . . . . . . . . . . . . . . . . . . . . 2424
To enable client keep-alive on a service by using the GUI . . . . . . . . . . . . . . . . . . . . 2424

Insert the IP address of the client in the request header 2425

To insert client IP address in the client request by using the CLI . . . . . . . . . . . . . . . . 2425
To insert client IP address in the client request by using the GUI . . . . . . . . . . . . . . . . 2425

Use source IP address of the client when connecting to the server 2426
To enable USIP mode for a service by using the CLI . . . . . . . . . . . . . . . . . . . . . . . 2426
To enable USIP mode for a service by using the GUI . . . . . . . . . . . . . . . . . . . . . . 2426

© 1999-2018 Citrix Systems, Inc. All rights reserved. 87

NetScaler 12.0

Configure the source port for server-side connections 2426

Configure the use proxy port setting on a service . . . . . . . . . . . . . . . . . . . . . . . . 2427
Configure the use proxy port setting globally . . . . . . . . . . . . . . . . . . . . . . . . . . 2428

Set a limit on the number of client connections 2429

To set a limit to the number of client connections by using the CLI . . . . . . . . . . . . . . 2429
To set a limit to the number of client connections by using the GUI . . . . . . . . . . . . . . 2430

Set a limit on number of requests per connection to the server 2430

To limit the number of client requests per connection by using the CLI . . . . . . . . . . . . 2430
To limit the number of client requests per connection by using the GUI . . . . . . . . . . . . 2430

Set a threshold value for the monitors bound to a service 2431

To set the monitor threshold value on a service by using the CLI . . . . . . . . . . . . . . . . 2431
To set the monitor threshold value on a service by using the GUI . . . . . . . . . . . . . . . 2431

Set a timeout value for idle client connections 2432

To set a timeout value for idle client connections by using the CLI . . . . . . . . . . . . . . . 2432
To set a timeout value for idle client connections by using the GUI . . . . . . . . . . . . . . 2432

Set a timeout value for idle server connections 2432

To set a timeout value for idle server connections by using the CLI . . . . . . . . . . . . . . 2433
To set a timeout value for idle server connections by using the GUI . . . . . . . . . . . . . . 2433

Set a limit on the bandwidth usage by clients 2433

To set a maximum bandwidth limit on a service by using the CLI . . . . . . . . . . . . . . . 2434
To set a maximum bandwidth limit on a service by using the GUI . . . . . . . . . . . . . . . 2434

Redirect client requests to a cache 2434

To set cache redirection on a service by using the CLI . . . . . . . . . . . . . . . . . . . . . 2434
To set cache redirection on a service by using the GUI . . . . . . . . . . . . . . . . . . . . . 2435

Retain the VLAN identifier for VLAN transparency 2435

To configure a load balancing virtual server to retain the client VLAN ID by using the CLI . . 2435
To configure a load balancing virtual server to retain the client VLAN ID by using the GUI . . 2435

Configure automatic state transition based on percentage health of bound services 2436
To configure percentage based automatic state transition by using the CLI . . . . . . . . . . 2436
To configure percentage based automatic state transition by using the GUI . . . . . . . . . . 2436
To enable the ENTITY-STATE alarm by using the CLI . . . . . . . . . . . . . . . . . . . . . . 2436
To enable the ENTITY-STATE alarm by using the GUI . . . . . . . . . . . . . . . . . . . . . . 2437

Built-in monitors 2437

© 1999-2018 Citrix Systems, Inc. All rights reserved. 88

NetScaler 12.0

TCP-based application monitoring 2437

SSL service monitoring 2440

FTP service monitoring 2441

To send secure FTP probes to FTP services by using the CLI . . . . . . . . . . . . . . . . . . 2442
To send secure FTP probes to FTP services by using the GUI . . . . . . . . . . . . . . . . . . 2442

Secure monitoring of servers by using SFTP 2443

To configure secure monitoring using SFTP by using the CLI . . . . . . . . . . . . . . . . . . 2443
To configure secure monitoring using SFTP by using the GUI . . . . . . . . . . . . . . . . . 2443

Set SSL parameters on a secure monitor 2443

Monitor Types that Support SSL Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2444

SIP service monitoring 2445

RADIUS service monitoring 2446

Monitor accounting information delivery from a RADIUS server 2447

To configure a RADIUS accounting monitor by using the CLI . . . . . . . . . . . . . . . . . . 2448

DNS and DNS-TCP service monitoring 2448

LDAP service monitoring 2449

MySQL service monitoring 2450

SNMP service monitoring 2451

NNTP service monitoring 2452

POP3 service monitoring 2452

SMTP service monitoring 2453

RTSP service monitoring 2454

XML broker service monitoring 2456

ARP request monitoring 2457

XenDesktop Delivery Controller service monitoring 2458

To add an XD-DDC monitor with the validate credentials option by using the command line
interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2459

© 1999-2018 Citrix Systems, Inc. All rights reserved. 89

NetScaler 12.0

To specify the validate credentials option on an XD-DDC monitor by using the command line
interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2459
To configure an XD-DDC monitor with the validate credentials option by using the configu-
ration utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2460

Web interface service monitoring 2460

To add a WI monitor by using the command line interface . . . . . . . . . . . . . . . . . . . 2461
To add a WI monitor by using the configuration utility . . . . . . . . . . . . . . . . . . . . . 2462

Citrix StoreFront stores monitoring 2462

To create a StoreFront monitor by using the command line interface . . . . . . . . . . . . . 2463
To create a StoreFront monitor by using the configuration utility . . . . . . . . . . . . . . . 2463

Custom monitors 2464

Configure HTTP-inline monitors 2464

Understand user monitors 2465

How to use a user monitor to check web sites 2470

Understand the internal dispatcher 2472

Configure a custom user monitor 2472

To configure a user monitor by using the command line interface . . . . . . . . . . . . . . . 2473

Understand load monitors 2473

Configure load monitors 2475

To create a metric table by using the command line interface . . . . . . . . . . . . . . . . . 2475
To create a metric table and bind metrics to it by using the configuration utility . . . . . . . 2475

Unbind metrics from a metrics table 2475

To unbind metrics from a metric table by using the command line interface . . . . . . . . . 2476
To unbind metrics from a metric table by using the configuration utility . . . . . . . . . . . 2476

Configure reverse monitoring for a service 2476

Configuring HTTP Reverse Monitoring for a Service . . . . . . . . . . . . . . . . . . . . . . . 2477
Configuring ICMP Reverse Monitoring for a Service . . . . . . . . . . . . . . . . . . . . . . . 2477
Configuring TCP Reverse Monitoring for a Service . . . . . . . . . . . . . . . . . . . . . . . 2478

Configure monitors in a load balancing setup 2479

© 1999-2018 Citrix Systems, Inc. All rights reserved. 90

NetScaler 12.0

Create monitors 2479

To create a monitor by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2479
To create a monitor by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2480

Configure monitor parameters to determine the service health 2480

Retries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2480
failureRetries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2481
alertRetries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2481

Bind monitors to services 2482

To bind a monitor to a service by using the command line interface . . . . . . . . . . . . . . 2482
To bind a monitor to a service by using the configuration utility . . . . . . . . . . . . . . . . 2483

Modify monitors 2483

To modify an existing monitor by using the command line interface . . . . . . . . . . . . . . 2483
To modify an existing monitor by using the configuration utility . . . . . . . . . . . . . . . . 2483

Enable and disable monitors 2484

To enable a monitor by using the command line interface . . . . . . . . . . . . . . . . . . . 2484
To enable a monitor by using the configuration utility . . . . . . . . . . . . . . . . . . . . . 2484
To disable a monitor by using the command line interface . . . . . . . . . . . . . . . . . . . 2484

Unbind monitors 2485

To unbind a monitor from a service by using the command line interface . . . . . . . . . . . 2485
To unbind a monitor from a service by using the configuration utility . . . . . . . . . . . . . 2485

Remove monitors 2485

To remove a monitor by using the command line interface . . . . . . . . . . . . . . . . . . . 2486
To remove a monitor by using the configuration utility . . . . . . . . . . . . . . . . . . . . . 2486

View monitors 2486

To view monitor bindings by using the command line interface . . . . . . . . . . . . . . . . 2487
To view monitor bindings by using the configuration utility . . . . . . . . . . . . . . . . . . 2487
To view monitors by using the command line interface . . . . . . . . . . . . . . . . . . . . . 2487
To view monitors by using the configuration utility . . . . . . . . . . . . . . . . . . . . . . . 2487

Close monitor connections 2487

Closing Monitor Connections at the Service or Service Group Level . . . . . . . . . . . . . . 2488

Ignore the upper limit on client connections for monitor probes 2489
To set the Skip MaxClients for Monitor Connections option by using the command line interface2490
To set the Skip MaxClients for Monitor Connections option by using the configuration utility 2490

© 1999-2018 Citrix Systems, Inc. All rights reserved. 91

NetScaler 12.0

Manage a large scale deployment 2490

Ranges of virtual servers and services 2491

Creating a range of virtual servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2491
Creating a range of services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2493

Configure service groups 2493

Create service groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2494
Bind a service group to a virtual server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2494
Bind a member to a service group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2495
Bind a monitor to a service group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2496
Retain the original state of a service group member after disabling and enabling a virtual
server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2497

Manage service groups 2497

Modify a service group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2497
Remove a service group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2498
Unbind a member from a service group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2499
Unbind a service group from a virtual server . . . . . . . . . . . . . . . . . . . . . . . . . . 2499
Unbind monitors from service groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2500
Enable or Disable a service group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2500
View the status of service groups members . . . . . . . . . . . . . . . . . . . . . . . . . . . 2501
Viewing the properties of a service group . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2502
Viewing service group statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2502
Load balancing virtual servers bound to a service group . . . . . . . . . . . . . . . . . . . . 2503

Configure automatic domain based service group scaling 2504

To configure a service group to scale automatically by using the command line interface . . 2505
To configure a service group to scale automatically by using the configuration utility . . . . 2506

Translate the IP address of a domain-based server 2507

To configure a translation IP address for a server by using the command line interface . . . 2508
To configure a translation IP address for a server by using the configuration utility . . . . . . 2508

Mask a virtual server IP address 2508

To configure a virtual server IP address mask by using the command line interface . . . . . 2509
To configure a virtual server IP address mask by using the configuration utility . . . . . . . . 2510

Configure load balancing for commonly used protocols 2510

Load balance a group of FTP servers 2511

To create FTP monitors by using the command line interface . . . . . . . . . . . . . . . . . 2512

© 1999-2018 Citrix Systems, Inc. All rights reserved. 92

NetScaler 12.0

To create FTP monitors by using the configuration utility . . . . . . . . . . . . . . . . . . . 2512

Load balance DNS servers 2512

To configure DNS monitors by using the command line interface . . . . . . . . . . . . . . . 2513
To configure DNS monitors by using the configuration utility . . . . . . . . . . . . . . . . . 2514

Load balance domain-name based services 2514

To add a name server by using the command line interface . . . . . . . . . . . . . . . . . . 2516
To add a name server by using the configuration utility . . . . . . . . . . . . . . . . . . . . 2516

Load balance a group of SIP servers 2516

Server Initiated Traffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2517
Support for Policies and Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2518
Configuring Load Balancing for SIP Signaling Traffic over TCP or UDP . . . . . . . . . . . . . 2518
To configure a basic load balancing setup for SIP traffic by using the command line interface 2519
Sample Configuration for load balancing the SIP traffic over UDP . . . . . . . . . . . . . . . 2521
Sample Configuration for load balancing the SIP traffic over TCP . . . . . . . . . . . . . . . 2522
Sample Configuration for load balancing and securing SIP traffic over TCP . . . . . . . . . . 2523
To configure a basic load balancing setup for SIP traffic by using the configuration utility . . 2524
SIP Expression and Policy Example: Compression Enabled in Client Requests . . . . . . . . 2525

Load balance RTSP servers 2525

To configure RTSP monitors by using the command line interface . . . . . . . . . . . . . . . 2526
To configure RTSP monitors by using the configuration utility . . . . . . . . . . . . . . . . . 2526

Load balance remote desktop protocol (RDP) servers 2527

To configure RDP load balancing services by using the command line interface . . . . . . . 2528
To configure RDP load balancing services by using the configuration utility . . . . . . . . . . 2529
To configure an RDP load balancing virtual server by using the command line interface . . . 2529
To configure an RDP load balancing virtual server by using the configuration utility . . . . . 2530
To configure a scripting monitor for RDP services by using the command line interface . . . 2530
To configure a scripting monitor for RDP services by using the configuration utility . . . . . 2531

Use case 1: SMPP load balancing 2531

Introduction to SMPP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2531
Architecture Overview of the Different SMPP Entities in a Mobile Network . . . . . . . . . . 2532
How SMPP Load Balancing Works on the NetScaler . . . . . . . . . . . . . . . . . . . . . . 2533
Messages Originating from the ESMEs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2533
Messages Originating from a Message Center . . . . . . . . . . . . . . . . . . . . . . . . . . 2533
Health Monitoring of Message Centers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2534
Content Switching on Message Centers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2535

© 1999-2018 Citrix Systems, Inc. All rights reserved. 93

NetScaler 12.0

Concatenated Message Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2535

Limitation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2536
Configuring SMPP Load Balancing on the NetScaler . . . . . . . . . . . . . . . . . . . . . . 2536

Use case 2: Configure rule based persistence based on a name-value pair in a TCP byte stream2537

Use case 3: Configure load balancing in direct server return mode 2540
To configure the load balancing method and redirection mode for a sessionless virtual
server by using the command line interface . . . . . . . . . . . . . . . . . . . . . . . . 2541
To configure the load balancing method and redirection mode for a sessionless virtual
server by using the configuration utility . . . . . . . . . . . . . . . . . . . . . . . . . . 2542
To configure a service to use source IP address by using the command line interface . . . . 2542
To configure a service to use source IP address by using the configuration utility . . . . . . . 2542

Use case 4: Configure LINUX servers in DSR mode 2543

To configure LINUX server in DSR mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2543

Use case 5: Configure DSR mode when using TOS 2543

To configure the redirection mode for the virtual server by using the command line interface 2545
To configure the redirection mode for the virtual server by using the configuration utility . . 2545
To configure the transparent monitor for TOS by using the command line interface . . . . . 2545
To create the transparent monitor for TOS by using the configuration utility . . . . . . . . . 2545
Wildcard TOS Monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2545

Use case 6: Configure load balancing in DSR mode for IPv6 networks by using the TOS field 2549
To configure load balancing in DSR Mode using TOS, perform the following steps on the ap-
pliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2550
To configure load balancing in DSR Mode using TOS by using the command line interface . . 2550
To enable USIP mode by using the configuration utility . . . . . . . . . . . . . . . . . . . . 2551
To create services by using the configuration utility . . . . . . . . . . . . . . . . . . . . . . 2551
To create a load balancing virtual server and bind services by using the configuration utility 2551

Use case 7: Configure load balancing in DSR mode by using IP Over IP 2551
Configure a load balancing virtual server . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2552
Configure services for IP over IP DSR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2553
Using the Client IP address in the Outer Header of Tunnel Packets . . . . . . . . . . . . . . 2554
Decapsulator configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2555

Use case 8: Configure load balancing in one-arm mode 2557

Use case 9: Configure load balancing in the inline mode 2557

© 1999-2018 Citrix Systems, Inc. All rights reserved. 94

NetScaler 12.0

Use case 10: Load balancing of intrusion detection system servers 2558
To enable MAC-based forwarding by using the command line interface . . . . . . . . . . . . 2559
To enable MAC-based forwarding by using the configuration utility . . . . . . . . . . . . . . 2560
To configure LB method and redirection mode for a sessionless virtual server by using the
command line interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2560
To configure LB method and redirection mode for a sessionless virtual server by using the
configuration utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2560
To set a service to use source IP address by using the command line interface . . . . . . . . 2560
To set a service to use source IP address by using the configuration utility . . . . . . . . . . 2561

Use case 11: Isolating network traffic using listen policies 2561
How network paths are isolated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2562
Configuration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2563

Use case 12: Configure XenDesktop for load balancing 2566

To configure load balancing for XenDesktop by using the GUI . . . . . . . . . . . . . . . . . 2567
To configure load balancing for XenDesktop by using the command line interface . . . . . . 2568

Use case 13: Configure XenApp for load balancing 2568

To configure load balancing for XenApp by using the GUI . . . . . . . . . . . . . . . . . . . 2569
To configure load balancing for XenApp by using the command line interface . . . . . . . . 2570

Use case 14: ShareFile wizard for load balancing Citrix ShareFile 2570
To configure a NetScaler appliance for load balancing Citrix ShareFile . . . . . . . . . . . . 2571

Troubleshooting 2572
Resources for Troubleshooting Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . 2572
Troubleshooting Load Balancing Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2573

Load balancing FAQs 2578

What are the various load balancing policies I can create on the NetScaler appliance . . . . 2578
Can I achieve the Web farm security by implementing load balancing using the NetScaler
appliance? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2579
What are various devices that I can use to load balance with a NetScaler appliance? . . . . . 2579
Why should I implement the load balancing feature for the website? . . . . . . . . . . . . . 2579
Why do I need to disable the Mac Based Forwarding (MBF) option for Link Load Balancing
(LLB)? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2580

Networking 2580

IP Addressing 2581

© 1999-2018 Citrix Systems, Inc. All rights reserved. 95

NetScaler 12.0

Configuring NetScaler-Owned IP Addresses 2582

Configuring the NetScaler IP Address (NSIP) 2582

Command Line Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2583
GUI Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2583
Sample configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2584

Configuring and Managing Virtual IP (VIP) Addresses 2585

Detecting a NetScaler Appliance in a UDP Load Balancing Setup through TTL Updates . . . 2587
Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2588
Configuration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2588

Configuring ARP response Suppression for Virtual IP addresses (VIPs) 2590

Configuring Subnet IP Addresses (SNIPs) 2592

Using SNIPs for a Directly Connected Server Subnet . . . . . . . . . . . . . . . . . . . . . . 2594
Using SNIPs for Server Subnets Connected through a Router . . . . . . . . . . . . . . . . . 2595
Using SNIPs for Multiple Server Subnets (VLANs) on an L2 Switch . . . . . . . . . . . . . . . 2596

Configuring GSLB Site IP Addresses (GSLBIP) 2597

Removing a NetScaler-Owned IP Address 2597

Configuring Application Access Controls 2598

How the NetScaler Proxies Connections 2601

How the Destination IP Address Is Selected . . . . . . . . . . . . . . . . . . . . . . . . . . . 2601
How the Source IP Address Is Selected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2601

Enable Use Source IP Mode 2602

Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2603
Configuration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2604

Configuring Network Address Translation 2605

INAT 2605
Configure INAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2606

Coexistence of INAT and Virtual Servers 2607

Stateless NAT46 2609

Limitations of Stateless NAT46 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2612
Configure Stateless NAT46 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2612
Setting Global Parameters for Stateless NAT46 . . . . . . . . . . . . . . . . . . . . . . . . . 2613

© 1999-2018 Citrix Systems, Inc. All rights reserved. 96

NetScaler 12.0

DNS64 2614
Points to Consider for a DNS64 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 2616
Configuration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2617

Stateful NAT64 Translation 2620

Limitations of Statelful NAT64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2621
Configuring Stateful NAT64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2622

RNAT 2624
Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2625
Configure RNAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2625
Monitor RNAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2627
Configure RNAT6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2628
Monitor RNAT6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2629
Log Start Time and Connection Closure Reasons in RNAT Log Entries . . . . . . . . . . . . . 2630
Stateful Connection Failover for RNAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2631
Removing RNAT Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2632

Configuring Prefix-Based IPv6-IPv4 Translation 2633

IP Prefix NAT 2635

Use Case: Zonification of Clients for a Deployment of a NetScaler appliance and an Opti-
mization Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2635
Configuration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2636
Sample configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2636

Static ARP 2637

Specify a VLAN in a Static ARP Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2637

Set the Timeout for Dynamic ARP Entries 2638

Neighbor Discovery 2639

Configuration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2640

IP Tunnels 2642
Configure IP Tunnels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2643
Customizing IP Tunnels Globally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2643
GRE Payload Options in a GRE IP Tunnel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2645
IPv6 Traffic through GRE IPV4 Tunnels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2646
Send Response Traffic Through an IP-IP Tunnel . . . . . . . . . . . . . . . . . . . . . . . . . 2647

Interfaces 2649

© 1999-2018 Citrix Systems, Inc. All rights reserved. 97

NetScaler 12.0

Configuring MAC-Based Forwarding 2649

Configuring Network Interfaces 2651

Setting the Network Interface Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2651
Enabling and Disabling Network Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . 2652
Resetting Network Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2653
Monitoring a Network Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2653

Configuring Forwarding Session Rules 2654

Assigning an ACL rule to an Existing Forwarding Session Rule . . . . . . . . . . . . . . . . . 2656
Disabling Steering for Forwarding Sessions on a Cluster Setup . . . . . . . . . . . . . . . . 2657

Understanding VLANs 2659

Applying Rules to Classify Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2660
VLANs and Packet Forwarding on the NetScaler . . . . . . . . . . . . . . . . . . . . . . . . 2661

Configuring a VLAN 2661

Configuring VLANs in an HA Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2662
Creating or Modifying a VLAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2663
Monitoring VLANs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2664

Configuring VLANs on a Single Subnet 2664

Configuring VLANs on Multiple Subnets 2665

Configuring Multiple Untagged VLANs across Multiple Subnets 2666

Configuring Multiple VLANs with 802.1q Tagging 2666

Configuring NSVLAN 2667

Setting the MTU on the NSVLAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2668

Configuring Allowed VLAN List 2669

Points to Consider before Configuring Allowed VLAN List . . . . . . . . . . . . . . . . . . . 2670
Configuring Allowed VLAN List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2670

Configuring Bridge Groups 2671

Configuring VMACs 2672

Configuring Link Aggregation 2673

Configuring Link Aggregation Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2674
Configuring Link Aggregation by Using the Link Aggregation Control Protocol . . . . . . . . 2675
Link Redundancy using LACP channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2678

© 1999-2018 Citrix Systems, Inc. All rights reserved. 98

NetScaler 12.0

Redundant Interface Set 2680

How Redundant Interface Set Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2681
Points to Consider for Configuring Redundant Interface Sets . . . . . . . . . . . . . . . . . 2682
Configuration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2682

Binding an SNIP address to an Interface 2686

Monitor the Bridge Table and Changing the Aging time 2689

NetScaler Appliances in Active-Active Mode Using VRRP 2690

Health Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2692
Preemption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2692
Sharing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2692

Configuring Active-Active Mode 2693

Configuring IPv4 Active-Active Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2693
Configuring IPv6 Active-Active Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2695

Configuring Send to Master 2696

Configuring VRRP Communication Intervals 2697

Example 1: Nodes with the Same VRRP Dead Intervals . . . . . . . . . . . . . . . . . . . . . 2698
Example 2: Nodes with Different VRRP Dead Intervals . . . . . . . . . . . . . . . . . . . . . 2699
Example 3: Nodes with Different Dead Intervals and Preemption Enabled . . . . . . . . . . 2699

Configuring Health Tracking based on Interface State 2700

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2700
Configuration Steps for IPv4 Active-Active Mode . . . . . . . . . . . . . . . . . . . . . . . . 2701
Configuration Steps for IPv6 Active-Active Mode . . . . . . . . . . . . . . . . . . . . . . . . 2701

Delaying Preemption 2702

Example: Delaying Preemption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2703
Configuring Delay Preemption for IPv4 Active-Active Mode . . . . . . . . . . . . . . . . . . 2704
Configuring Delay Preemption for IPv6 Active-Active Mode . . . . . . . . . . . . . . . . . . 2705

Keeping a VIP Address in the Backup State 2706

Network Visualizer 2706

Configuring Link Layer Discovery Protocol 2707

Configuration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2709
LLDP Support in a Cluster Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2710

© 1999-2018 Citrix Systems, Inc. All rights reserved. 99

NetScaler 12.0

Jumbo Frames 2711

Configuring Jumbo Frames Support on a NetScaler Appliance 2712

NetScaler command line procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2713
NetScaler GUI procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2714

Use Case 1 – Jumbo to Jumbo Setup 2714

Configuration Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2716

Use Case 2 – Non-Jumbo to Jumbo Setup 2717

Configuration Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2720

Use Case 3 – Coexistence of Jumbo and Non-Jumbo flows on the Same Set of Interfaces 2721
Configuration Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2724

NetScaler Support for Microsoft Direct Access Deployment 2724

Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2724
Configuring the Internal NetScaler Appliance in a Microsoft Direct Access Deployment . . . 2725
Displaying the Source Route Cache Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2726
Clearing the Source Route Cache Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2726

Access Control Lists 2726

Nomenclature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2727
ACL Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2727

Simple ACLs and Simple ACL6s 2728

Configuring Simple ACLs and Simple ACL6s . . . . . . . . . . . . . . . . . . . . . . . . . . . 2728
Displaying Simple ACL and Simple ACL6 Statistics . . . . . . . . . . . . . . . . . . . . . . . 2730
Terminating Established Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2731

Extended ACLs and Extended ACL6s 2733

Configuring Extended ACLs and Extended ACL6s . . . . . . . . . . . . . . . . . . . . . . . . 2734
Sample Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2736
Logging Extended ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2737
Displaying Extended ACL and Extended ACL6s Statistics . . . . . . . . . . . . . . . . . . . . 2738
Stateful ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2739

MAC Address Wildcard Mask for ACLs 2742

Blocking Traffic on Internal Ports 2744

IP Routing 2745

© 1999-2018 Citrix Systems, Inc. All rights reserved. 100

NetScaler 12.0

Configuring Dynamic Routes 2745

Routing Tables in NetScaler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2746
Dynamic Routing in a High Availability Setup . . . . . . . . . . . . . . . . . . . . . . . . . . 2747
Interfaces for Configuring Dynamic Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . 2748
Dynamic Routing Protocol Command Reference Guides and Unsupported Commands . . . 2748

Configuring RIP 2749

Enabling and Disabling RIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2749
Advertising Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2749
Limiting RIP Propagations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2750
Verifying the RIP Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2751

Configuring OSPF 2751

Enabling and Disabling OSPF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2752
Advertising OSPF Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2752
Limiting OSPF Propagations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2753
Verifying the OSPF Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2754

Configuring BGP 2756

Prerequisites for IPv6 BGP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2756
Enabling and Disabling BGP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2757
Advertising IPv4 Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2757
Advertising IPv6 BGP Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2758
Verifying the BGP Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2759
As-Override Support in Border Gateway Protocol . . . . . . . . . . . . . . . . . . . . . . . . 2759
Graceful Restart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2763

Configuring IPv6 RIP 2766

Prerequisites for IPv6 RIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2767
Advertising IPv6 RIP Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2767
Limiting IPv6 RIP Propagations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2767
Verifying the IPv6 RIP Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2768

Configuring IPv6 OSPF 2769

Prerequisites for IPv6 OSPF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2769
Advertising IPv6 Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2769
Limiting IPv6 OSPF Propagations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2770
Verifying the IPv6 OSPF Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2771
OSPFv3 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2771
Configuring Graceful Restart for IPv6 OSPF . . . . . . . . . . . . . . . . . . . . . . . . . . . 2772

© 1999-2018 Citrix Systems, Inc. All rights reserved. 101

NetScaler 12.0

Configuring ISIS 2774

Prerequisites for configuring ISIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2774
Enabling ISIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2775
Creating an ISIS Routing Process and Starting It on a VLAN . . . . . . . . . . . . . . . . . . . 2775
Advertising Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2776
Limiting ISIS Propagations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2777
Verifying the ISIS Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2778

Install Routes to the NetScaler Routing Table 2779

Advertisement of SNIP and VIP Routes to Selective Areas 2780

Advertise SNIP Routes to Selective Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2781
Advertise VIP Routes to Selective Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2781

Configuring Static Routes 2782

Configuring IPv4 Static Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2783
Configuring IPv6 Static Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2785

Route Health Injection Based on Virtual Server Settings 2786

Configuring Policy-Based Routes 2788

Policy-Based Routes (PBR) for IPv4 Traffic 2789

Creating or Modifying a PBR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2789
Applying a PBR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2791
Enabling or Disabling PBRs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2792
Renumbering PBRs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2793
Use Case - PBR with Multiple Hops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2793

Policy-Based Routes (PBR6) for IPv6 Traffic 2796

Creating or Modifying a PBR6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2796
Applying PBR6s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2797
Enabling or Disabling a PBR6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2798
Renumbering PBR6s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2798

MAC Address Wildcard Mask for PBRs 2799

Using NULL Policy Based Routes to Drop Outgoing Packets 2800

Configuring NULL PBRs for IPv4 Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2801

Troubleshooting Routing Issues 2801

Generic Routing FAQs 2802

© 1999-2018 Citrix Systems, Inc. All rights reserved. 102

NetScaler 12.0

Troubleshooting OSPF-Specific Issues 2804

Internet Protocol version 6 (IPv6) 2805

Implementing IPv6 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2806
VLAN Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2807
Simple Deployment Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2807
Host Header Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2809
VIP Insertion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2810

Traffic Domains 2811

Benefits of using Traffic Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2812
Default Traffic Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2812
How Traffic Domains Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2812
Supported NetScaler Features in Traffic Domains . . . . . . . . . . . . . . . . . . . . . . . . 2815
Configuring Traffic Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2816

Inter Traffic Domain Entity Bindings 2818

VMAC Based Traffic Domains 2819

Before you Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2820
Configuration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2820

VXLAN 2824
How VXLANs Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2824
VXLAN Use Case: Load Balancing across Datacenters . . . . . . . . . . . . . . . . . . . . . . 2825
Points to Consider for Configuring VXLANs . . . . . . . . . . . . . . . . . . . . . . . . . . . 2828
Configuration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2828
Support of IPv6 Dynamic Routing Protocols on VXLANs . . . . . . . . . . . . . . . . . . . . 2830
Extending VLANs from Multiple Enterprises to a Cloud using VXLAN-VLAN Maps . . . . . . . 2831

NetScaler Extensions 2834

NetScaler extensions - language overview 2834

Simple types 2835

Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2836
Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2836
Boolean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2837
Nil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2837
Other types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2837

© 1999-2018 Citrix Systems, Inc. All rights reserved. 103

NetScaler 12.0

Variables 2837
Global variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2838
Local variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2838

Expressions 2838
Arithmetic operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2839
Relational operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2839
Logical operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2840
Concatenation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2840
Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2841
Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2841

Assignment 2842

Tables 2842
Table constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2843
Table usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2843
Table as arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2844
Tables as records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2844

Control structures 2845

If Then Else . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2845
While Do and Repeat Until . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2846
Numeric For . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2847
Break . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2848
Goto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2848

Functions 2849
Protocol behavior callback functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2849
Policy extension functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2850
Local function definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2851
Function body and return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2851
Function calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2852
Iterator functions and generic for loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2852

NetScaler extensions - library reference 2853

Basic library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2854
String library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2855
Regular expression patterns - character classes . . . . . . . . . . . . . . . . . . . . . . . . . 2856
Regular expression patterns - pattern items . . . . . . . . . . . . . . . . . . . . . . . . . . . 2857
Table library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2858

© 1999-2018 Citrix Systems, Inc. All rights reserved. 104

NetScaler 12.0

Math library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2858

Bitwise library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2860
Operating system library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2861
NetScaler library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2861

NetScaler extensions API reference 2862

TCP client behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2862
TCP server behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2862
TCP client context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2862
TCP server context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2863
Vserver context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2863
NetScaler libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2864

Protocol extensions 2865

Protocol extensions - architecture 2865

Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2866

Protocol extensions - traffic pipeline for user defined TCP client and server behaviors 2867
Add a custom protocol by using protocol extensions . . . . . . . . . . . . . . . . . . . . . . 2867

Protocol extensions - use cases 2868

Message based load balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2868
Streaming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2870
Token based load balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2870
Load balancing persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2871
TCP connection based load balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2872
SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2873

Tutorial – Add MQTT protocol to the NetScaler appliance by using protocol extensions 2873

Code listing for mqtt.lua 2874

Configure MQTT by using protocol extensions 2879

Configuring SSL offloading for MQTT 2880

Configuring SSL offloading with end-to-end encryption for MQTT 2881

Tutorial - load balancing syslog messages by using protocol extensions 2882

Code for parsing syslog message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2882

Configuring syslog protocol by using protocol extensions 2885

© 1999-2018 Citrix Systems, Inc. All rights reserved. 105

NetScaler 12.0

Protocol extensions command reference 2886

Troubleshooting protocol extensions 2891

Custom logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2891

Policy extensions 2892

Prerequisites for using policy extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2893
How do policy extensions work? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2893

Configuring policy extensions 2894

Configure policy extensions by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . 2894

Policy extensions - use cases 2897

Case 1: Custom hash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2897
Case 2: Collapse double slashes in URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2899
Case 3: Combine headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2900

Troubleshooting policy extensions 2904

Extension tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2905
Custom logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2908

Optimization 2908

Client Keep-Alive 2909

Configure client keep-alive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2910

HTTP compression 2912

How HTTP compression works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2913
Configure HTTP compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2914
Configuring a compression action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2914
Configuring a compression policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2915
Binding a compression policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2916
Evaluate compression configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2919
Offloading HTTP compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2920

Integrated caching 2921

How integration cache works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2922
How dynamic cache works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2923
Configure integrated cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2925

Configure selectors and basic content groups 2928

Advantages of selectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2928
Configure a selector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2930

© 1999-2018 Citrix Systems, Inc. All rights reserved. 106

NetScaler 12.0

Content groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2931

Configure policies for caching and invalidation 2939

Actions to associate with integrated caching policies . . . . . . . . . . . . . . . . . . . . . . 2940
Bind points for a policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2943
Order of policy evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2944
Configure a policy in the integrated cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2945
Globally binding an integrated caching policy . . . . . . . . . . . . . . . . . . . . . . . . . 2946
Bind an integrated caching policy to a virtual server . . . . . . . . . . . . . . . . . . . . . . 2947
How to cache compressed and uncompressed versions of a file . . . . . . . . . . . . . . . . 2948
Configure a policy bank for caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2949
Configure a policy label in an integrated cache . . . . . . . . . . . . . . . . . . . . . . . . . 2952
Unbind and delete an integrated caching policy and policy label . . . . . . . . . . . . . . . 2952

Cache support for database protocols 2953

Configure expressions for caching policies and selectors 2955

Expression syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2956
Configure an expression in a caching policy or a selector . . . . . . . . . . . . . . . . . . . . 2957
Display cached objects and cache statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . 2959

Display cached objects and cache statistics 2972

View cached objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2973
Find particular cached responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2977
View cache statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2978
Viewing cache statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2979

Improve cache performance 2985

Reduce flash crowds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2985
Refresh a response before expiration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2985
Queue requests to the cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2986
Cache a response after a client halts a download . . . . . . . . . . . . . . . . . . . . . . . . 2987
Requiring a minimum number of server hits before caching . . . . . . . . . . . . . . . . . . 2987
Example for performance optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2988

Configure cookies, headers, and polling 2988

Divergence of cache behavior from the standards . . . . . . . . . . . . . . . . . . . . . . . 2989
Remove cookies from a response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2990
Inserting HTTP headers at response time . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2990
Insert an age, via, or ETag header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2991
Insert a cache-control header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2992

© 1999-2018 Citrix Systems, Inc. All rights reserved. 107

NetScaler 12.0

Ignoring cache-control and pragma headers in requests . . . . . . . . . . . . . . . . . . . . 2992

Polling the origin server every time a request is received . . . . . . . . . . . . . . . . . . . . 2994
PET and client-specific content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2995
PET and authentication, authorization, and auditing . . . . . . . . . . . . . . . . . . . . . . 2996

Configure integrated cache as a forward proxy 2996

Default settings for the integrated cache 2997

Default caching policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2997
View default policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2998
Default request policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2998
Default response policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2998
Restrictions on default policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3000
Initial settings for the default content group . . . . . . . . . . . . . . . . . . . . . . . . . . 3000

Troubleshooting 3001
Resources for troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3001

Front end optimization 3001

Optimizations performed by the FEO feature . . . . . . . . . . . . . . . . . . . . . . . . . . 3002
How front end optimization works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3005
Configure front end optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3005
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3006
Verify front end optimization configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 3007

Content accelerator 3008

How content accelerator works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3009
Configure content accelerator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3009

Media classification 3012

Enable media classification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3015
Verify media classification statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3016

Reputation 3016

IP reputation 3017
Using the Command Line to Configure the IP Reputation Feature . . . . . . . . . . . . . . . 3020
Using the GUI to Configure the IP Reputation Feature . . . . . . . . . . . . . . . . . . . . . 3022
Highlights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3023
Debugging Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3023

SSL offload and acceleration 3024

© 1999-2018 Citrix Systems, Inc. All rights reserved. 108

NetScaler 12.0

SSL offloading configuration 3025

Enable SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3025
Configure services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3026
SSL virtual server configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3028
Configure an SSL-based virtual server by using the GUI . . . . . . . . . . . . . . . . . . . . 3030
Bind services to the SSL virtual server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3030
Configure an SNI virtual server for secure hosting of multiple sites . . . . . . . . . . . . . . 3033
Bind multiple server certificates to a single SSL virtual server by using the GUI . . . . . . . . 3034
Support for SNI on the back-end service . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3034
Configure SNI on the back-end service by using the CLI . . . . . . . . . . . . . . . . . . . . 3035
Add or update a certificate-key pair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3036
Bind the certificate-key pair to the SSL virtual server . . . . . . . . . . . . . . . . . . . . . . 3039
SSL virtual server parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3042
Global SSL parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3050

How-to articles 3057

SSL certificates 3058

Create a certificate 3059

Create a private key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3059
Support for SHA 256 digest algorithm in a certificate signing request . . . . . . . . . . . . . 3060
Support for subject alternative name in a certificate signing request . . . . . . . . . . . . . 3061
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3063
Submitting the CSR to the CA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3063
Generate a test certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3063
Create a certificate by using a wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3064
Create an end-user certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3065

Install, link, and update certificates 3066

Link certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3066
Add and link a certificate set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3066
Create a chain of certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3078
Update an existing server certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3079
Update an existing CA certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3081
Disable domain checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3081
Enable the expiry monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3082
Update an intermediate certificate without breaking the links . . . . . . . . . . . . . . . . . 3083
Display a certificate chain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3083

© 1999-2018 Citrix Systems, Inc. All rights reserved. 109

NetScaler 12.0

Generate a server test certificate 3086

Generate a server test certificate by using the GUI . . . . . . . . . . . . . . . . . . . . . . . 3087

Import and convert SSL files 3087

Import a certificate file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3087
Import PKCS#8 and PKCS#12 certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3089
Convert SSL certificates for import or export . . . . . . . . . . . . . . . . . . . . . . . . . . 3091

SSL profiles 3092

Differences between the old and the new SSL profile infrastructure . . . . . . . . . . . . . . 3092

SSL profile infrastructure 3093

Points to note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3094
Enable the default profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3095
Use case 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3096
Use Case 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3097
SSL profile parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3098
Load an old configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3107

Appendix A: Sample migration of the SSL configuration after upgrade 3108

Appendix B: Default front-end and back-end SSL profile settings 3116

Legacy SSL profile 3119

Enable stricter control on client certificate validation . . . . . . . . . . . . . . . . . . . . . 3121

Certificate revocation lists 3122

Create a CRL on the ADC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3123
Add an existing CRL to the ADC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3124
Configure CRL refresh parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3125
Synchronize CRLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3127
Perform client authentication by using a certificate revocation list . . . . . . . . . . . . . . 3127

Monitor certificate status with OCSP 3130

OCSP implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3130
OCSP request batching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3130
OCSP response caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3131
OCSP responder configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3131

OCSP stapling 3134

OCSP stapling solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3134
OCSP response caching of server certificates . . . . . . . . . . . . . . . . . . . . . . . . . . 3135

© 1999-2018 Citrix Systems, Inc. All rights reserved. 110

NetScaler 12.0

OCSP stapling configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3135

Ciphers available on the NetScaler appliances 3140

ECDHE ciphers 3141

Unbind and bind ECC curves to an SSL virtual server by using the CLI . . . . . . . . . . . . . 3142

Diffie-Hellman (DH) parameters generation and achieving PFS with DHE 3143
Generate DH parameters by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3143
Generate DH parameters by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3144
Achieve perfect forward secrecy with DHE . . . . . . . . . . . . . . . . . . . . . . . . . . . 3144
Optimize DH parameters generation by using the CLI . . . . . . . . . . . . . . . . . . . . . . 3144
Optimize DH parameters generation by using the GUI . . . . . . . . . . . . . . . . . . . . . 3144

Cipher redirection 3145

Configure cipher redirection by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . 3145
Configure cipher redirection by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . 3146

Leverage hardware and software to improve ECDHE cipher performance 3147

Enable the hybrid model by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3147
Enable the hybrid model by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . 3149

ECDSA cipher suites support 3149

ECDSA/RSA cipher and certificate selection . . . . . . . . . . . . . . . . . . . . . . . . . . . 3153
Client authentication by using an ECDSA or an RSA certificate . . . . . . . . . . . . . . . . . 3153

Configure user-defined cipher groups on the ADC appliance 3153

Configure a user-defined cipher group by using the CLI . . . . . . . . . . . . . . . . . . . . 3154
Unbind ciphers from a cipher group by using the CLI . . . . . . . . . . . . . . . . . . . . . . 3157
Remove a cipher group by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3157
Configure a user-defined cipher group by using the GUI . . . . . . . . . . . . . . . . . . . . 3158

Server certificate support matrix on the ADC appliance 3158

Client authentication 3160

Provide the client certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3161
Enable client-certificate based authentication . . . . . . . . . . . . . . . . . . . . . . . . . 3162
Bind CA certificates to the virtual server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3164
Stricter control on client certificate validation . . . . . . . . . . . . . . . . . . . . . . . . . 3164

Server authentication 3165

Enable (or disable) server certificate authentication . . . . . . . . . . . . . . . . . . . . . . 3166
Configure a common name for server certificate authentication . . . . . . . . . . . . . . . . 3168

© 1999-2018 Citrix Systems, Inc. All rights reserved. 111

NetScaler 12.0

SSL actions and policies 3170

SSL policies 3171

SSL default syntax policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3171
SSL policy configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3172

SSL built-in actions and user-defined actions 3172

Examples of built-in actions in a policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3173
User-defined SSL actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3174

SSL policy binding 3175

Bind an SSL policy globally by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . 3175
Bind an SSL policy globally by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . 3176
Bind or unbind an SSL policy to a virtual server by using the CLI . . . . . . . . . . . . . . . . 3176
Bind an SSL policy to a virtual server by using the GUI . . . . . . . . . . . . . . . . . . . . . 3178

SSL policy labels 3178

Create an SSL policy label and bind policies to the label by using the CLI . . . . . . . . . . . 3178
Configure an SSL policy label and bind policies to the label by using the GUI . . . . . . . . . 3179

Support for DTLS protocol 3179

DTLS configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3180
Features not supported by a DTLS virtual server . . . . . . . . . . . . . . . . . . . . . . . . 3180
Parameters not used by a DTLS virtual server . . . . . . . . . . . . . . . . . . . . . . . . . . 3181
Features not supported by a DTLS service . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3181
Parameters not used by a DTLS service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3181
DTLS profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3182
Example for an end-to-end DTLS configuration . . . . . . . . . . . . . . . . . . . . . . . . . 3183
DTLS cipher support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3190
DTLS cipher support on NetScaler VPX, MPX/SDX (N2 and N3 based) appliances . . . . . . . 3190

Support for Intel Coleto SSL chip based platforms 3191

MPX 9700/10500/12500/15500 FIPS appliances 3192

HSM configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3193
Create and transfer FIPS keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3197

Configure FIPS appliances in a high availability setup 3202

Configure FIPS appliances in a high availability setup by using the CLI . . . . . . . . . . . . 3203
Configure FIPS appliances in a high availability setup by using the GUI . . . . . . . . . . . . 3204

© 1999-2018 Citrix Systems, Inc. All rights reserved. 112

NetScaler 12.0

Update the firmware to version 2.2 on a FIPS card 3205

Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3205
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3206
Update the FIPS firmware to version 2.2 on a standalone appliance . . . . . . . . . . . . . . 3206
Update the FIPS firmware to version 2.2 on appliances in a high availability pair . . . . . . . 3208
Update the FIPS firmware to version 1.1 on a standalone appliance . . . . . . . . . . . . . . 3208

Reset a locked HSM 3208

Reset a locked HSM by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3209
Reset a locked HSM by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3210

MPX 14000 FIPS appliances 3210

Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3211
Configure the HSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3211
Create FIPS keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3213
Import a FIPS key by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3214
Create a certificate signing request by using the CLI . . . . . . . . . . . . . . . . . . . . . . 3214
Create a server certificate by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . 3215
Add a certificate-key pair by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3215
Support for hybrid FIPS mode on the MPX 14000 FIPS and SDX 14000 FIPS platforms . . . . 3216

SDX 14000 FIPS appliances 3218

Limitations 3220

Terminology 3220

Initialize the HSM 3221

Zeroize the HSM by using the Management Service . . . . . . . . . . . . . . . . . . . . . . . 3221
Initialize the HSM by using the Management Service . . . . . . . . . . . . . . . . . . . . . . 3221

Create partitions 3222

Create a partition by using the Management Service . . . . . . . . . . . . . . . . . . . . . . 3222

Provision a new instance or modify an existing instance and assign a partition 3222
Provision a new instance or modify an existing instance . . . . . . . . . . . . . . . . . . . . 3223

Configure the HSM for an instance on an SDX 14030/14060/14080 FIPS appliance 3223
Initialize the FIPS card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3224
Initialize the FIPS card by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3224

Create a FIPS key for an instance on an SDX 14030/14060/14080 FIPS appliance 3226
Create a FIPS key by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3227

© 1999-2018 Citrix Systems, Inc. All rights reserved. 113

NetScaler 12.0

Import a FIPS key by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3227

Create a certificate signing request by using the CLI . . . . . . . . . . . . . . . . . . . . . . 3228
Create a server certificate by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . 3228
Add a certificate-key pair by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3229

Upgrade the FIPS firmware 3229

Upgrade the FIPS firmware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3230

Support for Thales nShield® HSM 3230

Supported versions matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3231

Architecture overview 3231

Prerequisites 3232

Configure the ADC-Thales integration 3233

Configure the Thales HSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3234
Enable remote configuration push on the HSM . . . . . . . . . . . . . . . . . . . . . . . . . 3234
Configure the ADC to use the Thales HSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3234
Create an HSM RSA Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3238
Configure the Entities on the ADC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3241

Limitations 3248

Appendix 3249

Support for Gemalto SafeNet Network hardware security module 3251

Supported versions matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3252

Prerequisites 3252

Configure a SafeNet client on the ADC 3253

Configure Safenet HSMs in a high availability setup on the ADC 3256

Additional ADC configuration 3260

NetScaler appliances in a high availability setup 3261

Limitations 3262

Appendix 3263
Run the script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3263
Create a certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3263

© 1999-2018 Citrix Systems, Inc. All rights reserved. 114

NetScaler 12.0

Copy the cetificate to the HSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3264

Copy the certificate and key from the HSM to the NetScaler appliance . . . . . . . . . . . . 3264
Use SSH to connect to the SafeNet HSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3264
Register the NetScaler on the SafeNet HSM . . . . . . . . . . . . . . . . . . . . . . . . . . . 3265
Assign the client a partition from the partition list . . . . . . . . . . . . . . . . . . . . . . . 3265
Register the HSM with its certificate on the NetScaler . . . . . . . . . . . . . . . . . . . . . 3265
Verify the network trust links (NTLs) connectivity between the ADC and HSM . . . . . . . . . 3265
Save the configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3266
Configure automatic start of the gateway daemon at boot time . . . . . . . . . . . . . . . . 3266

FAQ 3266

Troubleshooting 3266
Resources for troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3267
Troubleshooting SSL issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3267
Decrypting TLS1.3 traffic from packet trace . . . . . . . . . . . . . . . . . . . . . . . . . . . 3267

SSL FAQs 3268

Basic questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3268
Certificates and Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3271
Thales nShield® HSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3273
Ciphers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3273
Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3274
OpenSSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3282
System Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3283

Global site certificates 3286

How global site certificates work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3286
Import a global site certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3287

Security 3288

Content filtering 3289

Enabling content filtering 3290

Enable content filtering by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3291
Enable content by filtering by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . 3291

Configure a content filtering action 3292

Configure a content filtering action by using the CLI . . . . . . . . . . . . . . . . . . . . . . 3292
Configure a content filtering action by using the GUI . . . . . . . . . . . . . . . . . . . . . . 3293

© 1999-2018 Citrix Systems, Inc. All rights reserved. 115

NetScaler 12.0

Configure a content filtering policy 3293

Configure a content filtering policy by using the CLI . . . . . . . . . . . . . . . . . . . . . . 3294
Configure a content filtering policy by using the GUI . . . . . . . . . . . . . . . . . . . . . . 3295

Binding a content filtering policy 3298

Bind a policy to a virtual server by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . 3298
Globally bind a policy by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3299
Bind a policy to a virtual server by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . 3299
Globally bind a policy by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3300

Configuring content filtering for a commonly used deployment scenario 3300

Enable content filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3300
Configure the content filtering policy filter-CF-nimda . . . . . . . . . . . . . . . . . . . . . 3301
Globally bind the content filtering policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3301
Bind the content filtering policy to a virtual server . . . . . . . . . . . . . . . . . . . . . . . 3301
Verify the content filtering configuration by using the command line interface . . . . . . . . 3302
Verify the content filtering configuration by using the GUI . . . . . . . . . . . . . . . . . . . 3302

Troubleshooting 3303
Resources for troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3303
Troubleshooting content filtering issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3303

HTTP denial-of-service protection 3304

Layer 3-4 SYN Denial-of-Service protection 3306

Disable SYN Cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3307

Enable HTTP DoS protection 3308

Enable HTTP DoS protection by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . 3308
Enable HTTP DoS protection by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . 3308

Define an HTTP DoS policy 3309

Configure a HTTP DoS policy by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . 3309
Configure an HTTP DoS policy by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . 3310

Configuring an HTTP DoS service 3310

Configure an HTTP DoS service by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . 3310
Configure an HTTP DoS service by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . 3312

Bind an HTTP DoS monitor and policy 3312

Bind the monitor to the service by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . 3313
Bind the policy to the service by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . 3313

© 1999-2018 Citrix Systems, Inc. All rights reserved. 116

NetScaler 12.0

Bind the monitor and policy to the service by using the GUI . . . . . . . . . . . . . . . . . . 3315

Tuning the client detection/JavaScript challenger response rate 3315

Guidelines for HTTP DoS protection deployment 3316

Priority queuing 3317

Enable priority queuing 3319

Enable priority queuing by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3319
Enable priority queuing by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3319

Configure a priority queuing policy 3320

Configure a priority queuing policy by using the CLI . . . . . . . . . . . . . . . . . . . . . . 3320
Configure a priority queuing policy by using the GUI . . . . . . . . . . . . . . . . . . . . . . 3321

Bind a priority queuing policy 3322

Bind a priority queuing policy by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . 3322
Bind a priority queuing policy by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . 3323

Set up weighted queuing 3324

SureConnect 3324

Installing SureConnect 3326

Installing on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3327
Installing on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3327

Configure SureConnect 3328

Configure the response for alternate server failure . . . . . . . . . . . . . . . . . . . . . . . 3328
Configure the SureConnect policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3332
Customize the alternate content file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3334
Configure SureConnect for NetScaler features . . . . . . . . . . . . . . . . . . . . . . . . . 3335

Activating SureConnect 3336

SureConnect environments 3337

Primary and alternate servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3337
Configuration checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3338
Example configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3340

Surge protection 3343

© 1999-2018 Citrix Systems, Inc. All rights reserved. 117

NetScaler 12.0

Disable and reenable surge protection 3345

Disable or reenable surge protection by using the CLI . . . . . . . . . . . . . . . . . . . . . 3345
Disable or reenable surge protection by using the GUI . . . . . . . . . . . . . . . . . . . . . 3346
Disable or reenable surge protection for a particular service by using the GUI . . . . . . . . 3346

Set thresholds for surge protection 3347

Set the threshold for surge protection by using the GUI . . . . . . . . . . . . . . . . . . . . 3347

Flush the surge queue 3348

Flush a surge queue by using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3349
Flush a surge queue by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3350

DNS security options 3351

Cache poisoning protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3351
DNS DDoS protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3352
Manage exceptions – whitelist/blacklist servers . . . . . . . . . . . . . . . . . . . . . . . . . 3352
Prevent random subdomain attacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3353
Bypassing the cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3354
Enforce DNS transactions over TCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3354
Provide root details in the DNS response . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3355

System 3355

Basic operations 3356

View and save configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3356
Clear configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3357

Clock synchronization 3358

Set clock synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3359
Start NTP daemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3359
Configure clock synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3360

Session timeout 3361

System date and time 3363

To view the system date and time by using the command line interface . . . . . . . . . . . . 3363
To view the system date and time by using the GUI . . . . . . . . . . . . . . . . . . . . . . . 3363

Backup and restore 3364

Back up a NetScaler appliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3364
Restore a NetScaler appliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3365

Restart or shut down 3367

© 1999-2018 Citrix Systems, Inc. All rights reserved. 118

NetScaler 12.0

Generate technical support bundle 3368

Extra management CPU 3370

Allocate or deallocate an extra management CPU by using the NetScaler CLI . . . . . . . . . 3371
Allocate an extra management CPU by using the GUI . . . . . . . . . . . . . . . . . . . . . . 3372
Configure an extra management CPU by using the NITRO API . . . . . . . . . . . . . . . . . 3372
Statistics and monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3373

Authentication and authorization 3376

Configuring users, user groups, and command policies 3377

Configuring user accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3378
Configuring user groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3379
Configuring command policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3380

Resetting the default administrator (nsroot) password 3384

To reset the nsroot password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3385

Example of a user scenario 3387

Configuration steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3388

Configuring external user authentication 3389

Configuring LDAP authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3390
Configuring RADIUS authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3393
Configuring TACACS+ authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3395
Binding authentication policies to the system global entity . . . . . . . . . . . . . . . . . . 3395

SSH Key-based authentication for NetScaler administrators 3396

Configuring SSH key-based authentication for local system users . . . . . . . . . . . . . . . 3397

TCP Configurations 3398

Supported TCP configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3398
Setting Global TCP Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3401
Built-in TCP Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3404
Sample TCP configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3405

HTTP configurations 3410

Setting global HTTP parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3411
Setting Service or Virtual Server Specific HTTP Parameters . . . . . . . . . . . . . . . . . . 3412
Built-in HTTP Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3413
Sample HTTP Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3414

© 1999-2018 Citrix Systems, Inc. All rights reserved. 119

NetScaler 12.0

Configuring HTTP/2 on the NetScaler appliance 3414

How HTTP/2 works on a NetScaler appliance . . . . . . . . . . . . . . . . . . . . . . . . . . 3417
HTTP/2 for HTTPS (SSL) load balancing configuration . . . . . . . . . . . . . . . . . . . . . 3417
HTTP/2 for HTTP load balancing configuration . . . . . . . . . . . . . . . . . . . . . . . . . 3418
Before you Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3418
Configuring HTTP/2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3419
Sample configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3421

SNMP 3421

Configuring the NetScaler to generate SNMP traps 3423

Enabling an SNMP alarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3423
Configuring alarms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3424
Configuring SNMPv1 or SNMPv2 traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3425
Configuring SNMPv3 traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3426
SNMP trap logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3427

Configuring NetScaler for SNMP v1 and v2 queries 3428

Specifying an SNMP manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3428
Specifying an SNMP community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3430

Configuring NetScaler for SNMPv3 queries 3431

Setting the engine ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3432
Configure a view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3433
Configure a group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3434
Configuring a user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3435

Configuring SNMP Alarms for rate limiting 3435

Configuring an SNMP alarm for throughput or PPS . . . . . . . . . . . . . . . . . . . . . . . 3436
Configuring SNMP alarm for dropped packets . . . . . . . . . . . . . . . . . . . . . . . . . 3437

Configuring SNMP in FIPS mode 3438

Audit logging 3439

Configuring NetScaler appliance for audit logging 3441

Configuring audit-log policies in a Classic policy expression . . . . . . . . . . . . . . . . . . 3441
Configuring audit-log policies using advanced policy expression . . . . . . . . . . . . . . . 3443
Configuring policy-based logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3445

Installing and configuring the NSLOG server 3446

Installing NSLOG server on the Linux operating system . . . . . . . . . . . . . . . . . . . . . 3447

© 1999-2018 Citrix Systems, Inc. All rights reserved. 120

NetScaler 12.0

Installing NSLOG server on the FreeBSD operating system . . . . . . . . . . . . . . . . . . . 3448

Installing NSLOG Server Files on the Windows Operating System . . . . . . . . . . . . . . . 3450
NSLOG Server Command Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3451
Adding the NetScaler Appliance IP Addresses on the NSLOG Server . . . . . . . . . . . . . . 3451
Verifying the NSLOG Server Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . 3452

Running the NSLOG server 3452

To start audit server logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3453
To stop audit server logging that starts as a background process in FreeBSD or Linux . . . . 3453
To stop audit server logging that starts as a service in Windows . . . . . . . . . . . . . . . . 3453

Customizing logging on the NSLOG server 3453

Creating filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3454
Specifying log properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3454

SYSLOG Over TCP 3456

How Syslog over TCP works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3457
SNIP support for Syslog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3457
FQDN Support for audit Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3458

Load balancing SYSLOG servers 3461

Default settings for the log properties 3463

Sample configuration file (audit.conf) 3464

Web server logging 3465

Configuring the NetScaler for web server logging 3465

To configure web server logging by using the command line interface . . . . . . . . . . . . 3466
To configure web server logging by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . 3467

Installing the NetScaler web logging (NSWL) client 3467

Downloading the NSWL client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3468
Installing the NSWL client on a Solaris system . . . . . . . . . . . . . . . . . . . . . . . . . 3469
Installing the NSWL Client on a Linux System . . . . . . . . . . . . . . . . . . . . . . . . . . 3470
Installing the NSWL client on a FreeBSD system . . . . . . . . . . . . . . . . . . . . . . . . . 3470
Installing the NSWL Client on a Mac System . . . . . . . . . . . . . . . . . . . . . . . . . . . 3471
Installing the NSWL client on a Windows system . . . . . . . . . . . . . . . . . . . . . . . . 3472
Installing the NSWL client on a AIX system . . . . . . . . . . . . . . . . . . . . . . . . . . . 3472

Configure NSWL client 3473

Add the IP addresses of the NetScaler appliance . . . . . . . . . . . . . . . . . . . . . . . . 3475

© 1999-2018 Citrix Systems, Inc. All rights reserved. 121

NetScaler 12.0

Verify the NSWL configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3475

Running the NSWL Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3475

Customize logging on the NSWL client system 3476

Sample configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3476
Creating filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3479
Specifying log properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3481
Understanding NCSA and W3C log formats . . . . . . . . . . . . . . . . . . . . . . . . . . . 3483
Creating a custom log format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3487
Arguments for defining a custom log format . . . . . . . . . . . . . . . . . . . . . . . . . . 3490
Time format definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3490
Displaying Server Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3490

Call Home 3491

Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3491
Platform support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3491
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3492
How Call Home Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3492
Configuring Call Home . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3494
Citrix Service Provider (CSP) deployment support . . . . . . . . . . . . . . . . . . . . . . . 3499

Reporting tool 3499

Using the reporting tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3499
Working with reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3500
Working with charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3503
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3508
Stopping and starting the data collection utility . . . . . . . . . . . . . . . . . . . . . . . . 3508

CloudBridge Connector 3509

Understanding CloudBridge Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3510

Monitoring CloudBridge Connector tunnels 3512

Configuring a CloudBridge Connector tunnel between two datacenters 3514

Points to consider for configuring CloudBridge Connector tunnel . . . . . . . . . . . . . . . 3515
Configuration procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3516
Monitoring the CloudBridge Connector Tunnel . . . . . . . . . . . . . . . . . . . . . . . . . 3519

Configuring CloudBridge Connector between datacenter and AWS cloud 3519

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3522
Configuration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3522
Monitoring the CloudBridge Connector tunnel . . . . . . . . . . . . . . . . . . . . . . . . . 3526

© 1999-2018 Citrix Systems, Inc. All rights reserved. 122

NetScaler 12.0

Configuring a CloudBridge Connector tunnel between a NetScaler appliance and virtual

private gateway on AWS 3527
Example of CloudBridge Connector tunnel configuration and data flow . . . . . . . . . . . . 3527
Points to consider for a CloudBridge Connector tunnel configuration . . . . . . . . . . . . . 3529
Configuring Amazon AWS for the CloudBridge Connector tunnel . . . . . . . . . . . . . . . 3530
Configuring the NetScaler appliance for the CloudBridge Connector tunnel . . . . . . . . . 3533
Monitoring the CloudBridge Connector tunnel . . . . . . . . . . . . . . . . . . . . . . . . . 3536

Configuring a CloudBridge Connector tunnel between a datacenter and Azure cloud 3536
How CloudBridge Connector tunnel works . . . . . . . . . . . . . . . . . . . . . . . . . . . 3536
Example of CloudBridge Connector tunnel configuration and data flow . . . . . . . . . . . . 3537
Points to consider for a CloudBridge Connector tunnel configuration . . . . . . . . . . . . . 3538
Configuring the CloudBridge Connector tunnel . . . . . . . . . . . . . . . . . . . . . . . . . 3539
Monitoring the CloudBridge Connector tunnel . . . . . . . . . . . . . . . . . . . . . . . . . 3545

Configuring CloudBridge Connector tunnel between datacenter and softlayer enterprise

cloud 3546
To configure a CloudBridge Connector tunnel by using the GUI . . . . . . . . . . . . . . . . 3546
Monitoring the CloudBridge Connector tunnel . . . . . . . . . . . . . . . . . . . . . . . . . 3547

Configuring a CloudBridge Connector tunnel between a NetScaler appliance and Cisco IOS
device 3547
Example of CloudBridge Connector tunnel configuration and data flow . . . . . . . . . . . . 3547
Points to Consider for a CloudBridge Connector tunnel configuration . . . . . . . . . . . . . 3548
Configuring Cisco IOS device for the CloudBridge Connector tunnel . . . . . . . . . . . . . . 3549
Configuring the NetScaler appliance for the CloudBridge Connector tunnel . . . . . . . . . 3554
Monitoring the CloudBridge Connector Tunnel . . . . . . . . . . . . . . . . . . . . . . . . . 3557

Configuring a CloudBridge Connector tunnel between a NetScaler appliance and fortinet

fortiGate appliance 3557
Example of a CloudBridge Connector Tunnel Configuration . . . . . . . . . . . . . . . . . . 3557
Points to consider for a CloudBridge Connector tunnel configuration . . . . . . . . . . . . . 3558
Configuring FortiGate appliance for the CloudBridge Connector tunnel . . . . . . . . . . . . 3559
Configuring the NetScaler appliance for the CloudBridge Connector tunnel . . . . . . . . . 3562
Monitoring the CloudBridge Connector tunnel . . . . . . . . . . . . . . . . . . . . . . . . . 3564

CloudBridge Connector tunnel diagnostics and troubleshooting 3565

Troubleshooting a CloudBridge Connector tunnel . . . . . . . . . . . . . . . . . . . . . . . 3565
Checklist before contacting Citrix technical Support . . . . . . . . . . . . . . . . . . . . . . 3567

© 1999-2018 Citrix Systems, Inc. All rights reserved. 123

NetScaler 12.0

CloudBridge Connector interoperability – StrongSwan 3567

Example of a CloudBridge Connector tunnel configuration . . . . . . . . . . . . . . . . . . 3568
Points to consider for a CloudBridge Connector tunnel configuration . . . . . . . . . . . . . 3569
Configure StrongSwan for the CloudBridge Connector tunnel . . . . . . . . . . . . . . . . . 3570
Configuring the NetScaler appliance for the CloudBridge Connector tunnel . . . . . . . . . 3571
Monitoring the CloudBridge Connector tunnel . . . . . . . . . . . . . . . . . . . . . . . . . 3573

CloudBridge Connector interoperability – F5 BIG-IP 3574

Example of a CloudBridge Connector tunnel configuration . . . . . . . . . . . . . . . . . . 3574
Points to consider for a CloudBridge Connector tunnel configuration . . . . . . . . . . . . . 3574
Configuring F5 BIG-IP for the CloudBridge Connector tunnel . . . . . . . . . . . . . . . . . 3575
Configuring the NetScaler appliance for the CloudBridge Connector tunnel . . . . . . . . . 3577
Monitoring the CloudBridge Connector tunnel . . . . . . . . . . . . . . . . . . . . . . . . . 3579

CloudBridge Connector interoperability – Cisco ASA 3580

Example of a CloudBridge Connector tunnel configuration . . . . . . . . . . . . . . . . . . 3580
Points to consider for a CloudBridge Connector tunnel configuration . . . . . . . . . . . . . 3580
Configuring Cisco ASA for the CloudBridge Connector tunnel . . . . . . . . . . . . . . . . . 3581
Configuring the NetScaler appliance for the CloudBridge Connector tunnel . . . . . . . . . 3586
Monitoring the CloudBridge Connector Tunnel . . . . . . . . . . . . . . . . . . . . . . . . . 3588

High Availability 3588

Points to consider for a high availability setup 3589

Configuring high availability 3591

Adding a remote node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3591
Disabling or Enabling a Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3592
Removing a Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3593

Configuring the communication intervals 3593

To set the hello and dead intervals by using the command line interface . . . . . . . . . . . 3594
To set the hello and dead intervals by using the GUI . . . . . . . . . . . . . . . . . . . . . . 3594

Configuring synchronization 3594

Disabling or enabling synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3595
Forcing the secondary node to synchronize with the primary node . . . . . . . . . . . . . . 3595

Synchronizing configuration files in a high availability setup 3596

To synchronize files in a high availability setup by using the command line interface . . . . 3596
To synchronize files in a high availability setup by using the GUI . . . . . . . . . . . . . . . . 3597

© 1999-2018 Citrix Systems, Inc. All rights reserved. 124

NetScaler 12.0

Configuring command propagation 3597

To disable or enable command propagation by using the command line interface . . . . . . 3598
To disable or enable command propagation by using the GUI . . . . . . . . . . . . . . . . . 3598

Restricting high availability synchronization traffic to a VLAN 3598

Points to consider before Configuring an HA SYNC VLAN . . . . . . . . . . . . . . . . . . . . 3599

Configuring fail-safe mode 3600

To enable fail-safe mode by using the command line interface . . . . . . . . . . . . . . . . 3601
To enable fail-safe mode by using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3602

Configuring Virtual MAC Addresses 3602

Configuring IPv4 VMACs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3603
Configuring IPv6 VMAC6s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3604

Configuring high availability nodes in different subnets 3605

Adding a Remote Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3607
Removing a Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3608

Configuring route monitors 3608

Adding a route monitor to a high availability node . . . . . . . . . . . . . . . . . . . . . . . 3610
Removing route monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3610

Limiting failovers caused by route monitors in non-INC mode 3611

SNMP Alarm for Sticky Primary State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3613
Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3613

Configuring failover interface set 3614

Creating or Modifying an FIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3614
Removing an FIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3615

Understanding the causes of failover 3615

Forcing a node to fail over 3617

Forcing the secondary node to stay secondary 3618

To force the secondary node to stay secondary by using the command line interface . . . . 3619
To force the secondary node to stay secondary by using the GUI . . . . . . . . . . . . . . . 3619

Forcing the primary node to stay primary 3619

To force the primary node to stay primary by using the command line interface . . . . . . . 3619
To force the primary node to stay primary by using the GUI . . . . . . . . . . . . . . . . . . 3620

© 1999-2018 Citrix Systems, Inc. All rights reserved. 125

NetScaler 12.0

Understanding the high availability health check computation 3620

High availability FAQ 3621

Troubleshooting high availability issues 3624

Managing high availability heartbeat messages on a NetScaler appliance 3626

TCP optimization 3627

Congestion Control Strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3628
Proportional Rate Recovery (PRR) Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . 3628
TCP Fast Open (TFO) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3628
TCP Hystart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3630
TCP burst rate control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3631
Protection against wrapped sequence (PAWS) algorithm . . . . . . . . . . . . . . . . . . . . 3634
To enable or disable TCP timestamp by using the command line interface . . . . . . . . . . 3635
Optimization Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3635
Policy based TCP Profile Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3635
To enable AppQoE by using the command line interface . . . . . . . . . . . . . . . . . . . . 3636
SACK block generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3638
Client reneging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3639
Memory checks for marking end_point on PCB is not considering total available memory . . 3639
Unnecessary retransmissions due to missing SACK blocks . . . . . . . . . . . . . . . . . . . 3639
SNMP for number of connections bypassed optimization because of overload . . . . . . . . 3639
Dynamic Receive Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3639

Reference Material 3640

© 1999-2018 Citrix Systems, Inc. All rights reserved. 126

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0

NetScaler Release Notes

May 29, 2019

Contributed by:
C

Release notes describe how the software has changed in a particular build, and the issues known to
exist in that build.

The release notes document includes all or some of the following sections:

• What’s New: The enhancements and other changes released in the build.
• Fixed Issues: The issues that are fixed in the build.
• Known Issues: The issues that exist in the build.
• Points to Note: The important aspects to keep in mind while using the build.
• Limitations: The limitations that exist in the build.
Note

• The [# XXXXXX] labels under the issue descriptions are internal tracking IDs used by the
NetScaler team.
• These release notes do not document security related fixes. For a list of security related
fixes and advisories, see the Citrix security bulletin.

To view the latest release notes document, click this link.

1.
2. Citrix ADC
3. NetScaler 12.0

Getting started with NetScaler

January 6, 2019

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 127

NetScaler 12.0

Intended for system and network administrators who install and configure complex networking equip-
ment, this section of the library describes initial set-up and basic configuration of the NetScaler.

Understanding the NetScaler

The NetScaler product is an application switch that performs application-specific traffic analysis to
intelligently distribute, optimize, and secure Layer 4-Layer 7 (L4–L7) network traffic for web applica-
tions. For example, a NetScaler bases load balancing decisions on individual HTTP requests instead
of on long-lived TCP connections, so that the failure or slowdown of a server is managed much more
quickly and with less disruption to clients. The ADC feature set can be broadly categorized as consist-
ing of switching features, security and protection features, and server-farm optimization features.

Switching features

When deployed in front of application servers, a NetScaler ensures optimal distribution of traffic by
the way in which it directs client requests. Administrators can segment application traffic according
to information in the body of an HTTP or TCP request, and on the basis of L4–L7 header information
such as URL, application data type, or cookie. Numerous load balancing algorithms and extensive
server health checks improve application availability by ensuring that client requests are directed to
the appropriate servers.

Security and protection features

The NetScaler security and protection features protect web applications from Application Layer
attacks. An ADC appliance allows legitimate client requests and can block malicious requests.
It provides built-in defenses against denial-of-service (DoS) attacks and supports features that
protect against legitimate surges in application traffic that would otherwise overwhelm the servers.
An available built-in firewall protects web applications from Application Layer attacks, including
buffer overflow exploits, SQL injection attempts, cross-site scripting attacks, and more. In addition,
the firewall provides identity theft protection by securing confidential corporate information and
sensitive customer data.

Optimization features

Optimization features offload resource-intensive operations, such as Secure Sockets Layer (SSL) pro-
cessing, data compression, client keep-alive, TCP buffering, and the caching of static and dynamic
content from servers. This improves the performance of the servers in the server farm and therefore
speeds up applications. An ADC appliance supports several transparent TCP optimizations, which

© 1999-2018 Citrix Systems, Inc. All rights reserved. 128

NetScaler 12.0

mitigate problems caused by high latency and congested network links, accelerating the delivery of
applications while requiring no configuration changes to clients or servers.

Understanding policies and expressions

A policy defines specific details of traffic filtering and management on a NetScaler. It consists of two
parts: the expression and the action. The expression defines the types of requests that the policy
matches. The action tells the ADC appliance what to do when a request matches the expression. As an
example, the expression might be to match a specific URL pattern to a type of security attack, with the
action being to drop or reset the connection. Each policy has a priority, and the priorities determine
the order in which the policies are evaluated.

When an ADC appliance receives traffic, the appropriate policy list determines how to process the
traffic. Each policy on the list contains one or more expressions, which together define the criteria
that a connection must meet to match the policy.

For all policy types except Rewrite policies, a NetScaler apppliance implements only the first policy
that a request matches, not any additional policies that it might also match. For Rewrite policies,
the ADC appliance evaluates the policies in order and, in the case of multiple matches, performs the
associated actions in that order. Policy priority is important for getting the results you want.

Processing order of features

Depending on requirements, you can choose to configure multiple features. For example, you might
choose to configure both compression and SSL offload. As a result, an outgoing packet might be com-
pressed and then encrypted before being sent to the client.

The following figure shows the DataStream packet flow in the NetScaler appliance. DataStream is
supported for MySQL and MS SQL databases.

The following figure shows the DataStream packet flow in the NetScaler appliance. DataStream is sup-
ported for MySQL and MS SQL databases. For information about the DataStream feature, see DataS-
tream.

Figure 2. DataStream Packet Flow Diagram

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 129

NetScaler 12.0

Where does a NetScaler appliance fit in the network?

January 6, 2019

Contributed by:
C

A NetScaler appliance resides between the clients and the servers, so that client requests and server
responses pass through it. In a typical installation, virtual servers configured on the appliance provide
connection points that clients use to access the applications behind the appliance. In this case, the
appliance owns public IP addresses that are associated with its virtual servers, while the real servers
are isolated in a private network. It is also possible to operate the appliance in a transparent mode as
an L2 bridge or L3 router, or even to combine aspects of these and other modes.

Physical deployment modes

A NetScaler appliance logically residing between clients and servers can be deployed in either of two
physical modes: inline and one-arm. In inline mode, multiple network interfaces are connected to
different Ethernet segments, and the appliance is placed between the clients and the servers. The
appliance has a separate network interface to each client network and a separate network interface
to each server network. The appliance and the servers can exist on different subnets in this configura-
tion. It is possible for the servers to be in a public network and the clients to directly access the servers
through the appliance, with the appliance transparently applying the L4-L7 features. Usually, virtual
servers (described later) are configured to provide an abstraction of the real servers. The following
figure shows a typical inline deployment.

Figure 1. Inline Deployment

In one-arm mode, only one network interface of the appliance is connected to an Ethernet segment.
The appliance in this case does not isolate the client and server sides of the network, but provides ac-
cess to applications through configured virtual servers. One-arm mode can simplify network changes
needed for NetScaler installation in some environments.

For examples of inline (two-arm) and one-arm deployment, see Understanding Common Network
Topologies.

NetScaler as an L2 device

A NetScaler appliance functioning as an L2 device is said to operate in L2 mode. In L2 mode, the ADC
appliance forwards packets between network interfaces when all of the following conditions are met:

• The packets are destined to another device’s media access control (MAC) address.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 130

NetScaler 12.0

• The destination MAC address is on a different network interface.

• The network interface is a member of the same virtual LAN (VLAN).

By default, all network interfaces are members of a pre-defined VLAN, VLAN 1. Address Resolution
Protocol (ARP) requests and responses are forwarded to all network interfaces that are members of
the same VLAN. To avoid bridging loops, L2 mode must be disabled if another L2 device is working in
parallel with the NetScaler appliance.

For information about how the L2 and L3 modes interact, see Packet forwarding modes.

For information about configuring L2 mode, see the “Enable and disable layer 2 mode” section in
Packet forwarding modes.

NetScaler as a packet forwarding device

A NetScaler appliance can function as a packet forwarding device, and this mode of operation is
called L3 mode. With L3 mode enabled, the appliance forwards any received unicast packets that are
destined for an IP address that does not belong to the appliance, if there is a route to the destination.
The appliance can also route packets between VLANs.

In both modes of operation, L2 and L3, the appliance generally drops packets that are in:

• Multicast frames
• Unknown protocol frames destined for an appliance’s MAC address (non-IP and non-ARP)
• Spanning Tree protocol (unless BridgeBPDUs is ON)

For information about how the L2 and L3 modes interact, see Packet forwarding modes.

For information about configuring the L3 mode, see Packet forwarding modes.

1.
2. Citrix ADC
3. NetScaler 12.0

How a NetScaler appliance communicates with clients and servers

January 6, 2019

Contributed by:
C

A NetScaler appliance is usually deployed in front of a server farm and functions as a transparent TCP
proxy between clients and servers, without requiring any client-side configuration. This basic mode of
operation is called Request Switching technology and is the core of NetScaler functionality. Request

© 1999-2018 Citrix Systems, Inc. All rights reserved. 131

NetScaler 12.0

Switching enables an appliance to multiplex and offload the TCP connections, maintain persistent
connections, and manage traffic at the request (application layer) level. This is possible because the
appliance can separate the HTTP request from the TCP connection on which the request is delivered.

Depending on the configuration, an appliance might process the traffic before forwarding the request
to a server. For example, if the client attempts to access a secure application on the server, the appli-
ance might perform the necessary SSL processing before sending traffic to the server.

To facilitate efficient and secure access to server resources, an appliance uses a set of IP addresses
collectively known as NetScaler-owned IP addresses. To manage your network traffic, you assign
NetScaler-owned IP addresses to virtual entities that become the building blocks of your configura-
tion. For example, to configure load balancing, you create virtual servers to receive client requests
and distribute them to services, which are entities representing the applications on your servers.

Understanding NetScaler-owned IP addresses

To function as a proxy, a NetScaler appliance uses a variety of IP addresses. The key NetScaler-owned
IP addresses are:

• NetScaler IP (NSIP) address

The NSIP address is the IP address for management and general system access to the appliance
itself, and for communication between appliances in a high availability configuration.

• Virtual server IP (VIP) address

A VIP address is the IP address associated with a virtual server. It is the public IP address to which
clients connect. An appliance managing a wide range of traffic may have many VIPs configured.

• Subnet IP (SNIP) address

A SNIP address is used in connection management and server monitoring. You can specify mul-
tiple SNIP addresses for each subnet. SNIP addresses can be bound to a VLAN.

• IP Set

An IP set is a set of IP addresses, which are configured on the appliance as SNIP . An IP set is iden-
tified with a meaningful name that helps in identifying the usage of the IP addresses contained
in it.

• Net Profile

A net profile (or network profile) contains an IP address or an IP set. A net profile can be bound to
load balancing or content switching virtual servers, services, service groups, or monitors. Dur-
ing communication with physical servers or peers, the appliance uses the addresses specified
in the profile as source IP addresses.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 132

NetScaler 12.0

How Traffic flows are managed

Because a NetScaler appliance functions as a TCP proxy, it translates IP addresses before sending
packets to a server. When you configure a virtual server, clients connect to a VIP address on the
NetScaler appliance instead of directly connecting to a server. As determined by the settings on the
virtual server, the appliance selects an appropriate server and sends the client’s request to that server.
By default, the appliance uses a SNIP address to establish connections with the server, as shown in
the following figure.

Figure 1. Virtual Server Based Connections

In the absence of a virtual server, when an appliance receives a request, it transparently forwards the
request to the server. This is called the transparent mode of operation. When operating in transparent
mode, an appliance translates the source IP addresses of incoming client requests to the SNIP address
but does not change the destination IP address. For this mode to work, L2 or L3 mode has to be
configured appropriately.

For cases in which the servers need the actual client IP address, the appliance can be configured to
modify the HTTP header by inserting the client IP address as an additional field, or configured to use
the client IP address instead of a SNIP address for connections to the servers.

Traffic management building blocks

The configuration of a NetScaler appliance is typically built up with a series of virtual entities that serve
as building blocks for traffic management. The building block approach helps separate traffic flows.
Virtual entities are abstractions, typically representing IP addresses, ports, and protocol handlers for
processing traffic. Clients access applications and resources through these virtual entities. The most
commonly used entities are virtual servers and services. Virtual servers represent groups of servers
in a server farm or remote network, and services represent specific applications on each server.

Most features and traffic settings are enabled through virtual entities. For example, you can configure
an appliance to compress all server responses to a client that is connected to the server farm through
a particular virtual server. To configure the appliance for a particular environment, you need to iden-
tify the appropriate features and then choose the right mix of virtual entities to deliver them. Most
features are delivered through a cascade of virtual entities that are bound to each other. In this case,
the virtual entities are like blocks being assembled into the final structure of a delivered application.
You can add, remove, modify, bind, enable, and disable the virtual entities to configure the features.
The following figure shows the concepts covered in this section.

Figure 2. How traffic management building blocks work

© 1999-2018 Citrix Systems, Inc. All rights reserved. 133

NetScaler 12.0

A simple load balancing configuration

In the example shown in the following figure, the NetScaler appliance is configured to function as a
load balancer. For this configuration, you need to configure virtual entities specific to load balancing
and bind them in a specific order. As a load balancer, an appliance distributes client requests across
several servers and thus optimizes the utilization of resources.

The basic building blocks of a typical load balancing configuration are services and load balancing
virtual servers. The services represent the applications on the servers. The virtual servers abstract the
servers by providing a single IP address to which the clients connect. To ensure that client requests
are sent to a server, you need to bind each service to a virtual server. That is, you must create services
for every server and bind the services to a virtual server. Clients use the VIP address to connect to
a NetScaler appliance. When the appliance receives client requests sent to the VIP address, it sends
them to a server determined by the load balancing algorithm. Load balancing uses a virtual entity
called a monitor to track whether a specific configured service (server plus application) is available to
receive requests.

Figure 3. Load balancing virtual server, services, and monitors

In addition to configuring the load balancing algorithm, you can configure several parameters that af-
fect the behavior and performance of the load balancing configuration. For example, you can config-
ure the virtual server to maintain persistence based on source IP address. The appliance then directs
all requests from any specific IP address to the same server.

Understanding virtual servers

A virtual server is a named NetScaler entity that external clients can use to access applications hosted
on the servers. It is represented by an alphanumeric name, virtual IP (VIP) address, port, and protocol.
The name of the virtual server is of only local significance and is designed to make the virtual server
easier to identify. When a client attempts to access applications on a server, it sends a request to the
VIP instead of the IP address of the physical server. When the appliance receives a request at the VIP
address, it terminates the connection at the virtual server and uses its own connection with the server
on behalf of the client. The port and protocol settings of the virtual server determine the applications
that the virtual server represents. For example, a web server can be represented by a virtual server
and a service whose port and protocol are set to 80 and HTTP, respectively. Multiple virtual servers
can use the same VIP address but different protocols and ports.

Virtual servers are points for delivering features. Most features, like compression, caching, and SSL
offload, are normally enabled on a virtual server. When the appliance receives a request at a VIP ad-
dress, it chooses the appropriate virtual server by the port on which the request was received and its
protocol. The appliance then processes the request as appropriate for the features configured on the
virtual server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 134

NetScaler 12.0

In most cases, virtual servers work in tandem with services. You can bind multiple services to a vir-
tual server. These services represent the applications running on physical servers in a server farm.
After the appliance processes requests received at a VIP address, it forwards them to the servers as
determined by the load balancing algorithm configured on the virtual server. The following figure
illustrates these concepts.
Figure 4. Multiple Virtual Servers with a Single VIP Address
The preceding figure shows a configuration consisting of two virtual servers with a common VIP ad-
dress but different ports and protocols. Each of the virtual servers has two services bound to it. The
services s1 and s2 are bound to VS_HTTP and represent the HTTP applications on Server 1 and Server
2. The services s3 and s4 are bound to VS_SSL and represent the SSL applications on Server 2 and
Server 3 (Server 2 provides both HTTP and SSL applications). When the appliance receives an HTTP
request at the VIP address, it processes the request as specified by the settings of VS_HTTP and sends
it to either Server 1 or Server 2. Similarly, when the appliance receives an HTTPS request at the VIP
address, it processes it as specified by the settings of VS_SSL and it sends it to either Server 2 or Server
3.
Virtual servers are not always represented by specific IP addresses, port numbers, or protocols. They
can be represented by wildcards, in which case they are known as wildcard virtual servers. For ex-
ample, when you configure a virtual server with a wildcard instead of a VIP, but with a specific port
number, the appliance intercepts and processes all traffic conforming to that protocol and destined
for the predefined port. For virtual servers with wildcards instead of VIPs and port numbers, the ap-
pliance intercepts and processes all traffic conforming to the protocol.
Virtual servers can be grouped into the following categories:
• Load balancing virtual server
Receives and redirects requests to an appropriate server. Choice of the appropriate server is
based on which of the various load balancing methods the user configures.
• Cache redirection virtual server
Redirects client requests for dynamic content to origin servers, and requests for static content to
cache servers. Cache redirection virtual servers often work in conjunction with load balancing
virtual servers.
• Content switching virtual server
Directs traffic to a server on the basis of the content that the client has requested. For example,
you can create a content switching virtual server that directs all client requests for images to a
server that serves images only. Content switching virtual servers often work in conjunction with
load balancing virtual servers.
• Virtual private network (VPN) virtual server
Decrypts tunneled traffic and sends it to intranet applications.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 135

NetScaler 12.0

• SSL virtual server

Receives and decrypts SSL traffic, and then redirects to an appropriate server. Choosing the
appropriate server is similar to choosing a load balancing virtual server.

Understanding services

Services represent applications on a server. While services are normally combined with virtual
servers, in the absence of a virtual server, a service can still manage application-specific traffic.
For example, you can create an HTTP service on a NetScaler appliance to represent a web server
application. When the client attempts to access a web site hosted on the web server, the appliance
intercepts the HTTP requests and creates a transparent connection with the web server.

In service-only mode, an appliance functions as a proxy. It terminates client connections, uses a SNIP
address to establish a connection to the server, and translates the source IP addresses of incoming
client requests to a SNIP address. Although the clients send requests directly to the IP address of
the server, the server sees them as coming from the SNIP address. The appliance translates the IP
addresses, port numbers, and sequence numbers.

A service is also a point for applying features. Consider the example of SSL acceleration. To use this
feature, you must create an SSL service and bind an SSL certificate to the service. When the appliance
receives an HTTPS request, it decrypts the traffic and sends it, in clear text, to the server. Only a limited
set of features can be configured in the service-only case.

Services use entities called monitors to track the health of applications. Every service has a default
monitor, which is based on the service type, bound to it. As specified by the settings configured on
the monitor, the appliance sends probes to the application at regular intervals to determine its state.
If the probes fail, the appliance marks the service as down. In such cases, the appliance responds
to client requests with an appropriate error message or re-routes the request as determined by the
configured load balancing policies.

1.
2. Citrix ADC
3. NetScaler 12.0

Introduction to the NetScaler product line

January 3, 2019

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 136

NetScaler 12.0

The NetScaler product line optimizes delivery of applications over the internet and private networks,
combining application-level security, optimization, and traffic management into a single, integrated
appliance. You can install a NetScaler appliance in your server room and route all connections to your
managed servers through it. The NetScaler features that you enable and the policies you set are then
applied to incoming and outgoing traffic.

A NetScaler appliance can be integrated into any network as a complement to existing load balancers,
servers, caches, and firewalls. It requires no additional client or server side software, and can be con-
figured using the NetScaler web-based GUI and CLI configuration utilities.

NetScaler Hardware Platforms

NetScaler hardware is available in a variety of platforms that have a range of hardware specifications:

NetScaler MPX hardware platform

NetScaler SDX hardware platform

NetScaler Editions

The NetScaler operating system is available in three editions:

• Standard
• Enterprise
• Platinum

The Standard and Advanced editions have limited features available. Feature licenses are required for
all editions.

For more information about NetScaler software editions, see the NetScaler Editions datasheet.

For information about how to obtain and install licenses, see Licensing.

Supported releases on NetScaler hardware

See the following compatibility matrix tables for all NetScaler hardware platforms and the software
releases supported on these platforms:

NetScaler MPX Hardware-Software Compatibility Matrix

NetScaler SDX Hardware-Software Compatibility Matrix

© 1999-2018 Citrix Systems, Inc. All rights reserved. 137

NetScaler 12.0

Supported browsers

To access the NetScaler GUI, your workstation must have a supported web browser.

Operating system: Windows 7

Brower and versions:

• Internet Explorer; versions 9, 10, and 11

• Mozilla Firefox; versions 3.6.25 and above
• Google Chrome; latest version

Operating system: Windows 64 bit

Brower and versions:

• Internet Explorer; versions 8, 9, 10, and 11

• Google Chrome; latest version

Operating system: MAC

Brower and versions:

• Mozilla Firefox; versions 3.6.25 and above

• Safari; versions 5.1.3 and above
• Google Chrome; latest version

1.
2. Citrix ADC
3. NetScaler 12.0

Install the hardware

September 24, 2018

Contributed by:
C

Before installing a NetScaler appliance, review the pre-installation checklist.

To use the SDX appliance, you must complete the following tasks by following the instructions given
in the resources provided in table. Complete the tasks in the sequence given.

Task

Description

1. Read safety, cautions, warnings, and other information

Read the caution and danger information you need to know, before installing the product.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 138

NetScaler 12.0

2. Prepare for installation

Unpack your appliance and ensure all parts were delivered, prepare the site and rack, and follow basic
electrical safety precautions before you install your new appliance.

3. Install the hardware

Rack mount the appliance, install transceivers (if available), and connect the appliance to the network
and a power source.

4. Configure the appliance.

Configure the initial settings of the NetScaler appliance by using the GUI or the serial console.

Follow the steps given in the following documentations to complete these tasks:

• NetScaler MPX hardware documentation

• NetScaler SDX hardware documentation

1.
2. Citrix ADC
3. NetScaler 12.0

Access a NetScaler

April 12, 2019

Contributed by:
C

A NetScaler appliance has both a command line interface (CLI) and a graphical user interface (GUI).
The GUI includes a configuration utility for configuring the appliance and a statistical utility, called
Dashboard. For initial access, all appliances ship with the default NetScaler IP address (NSIP) of
192.168.100.1 and default subnet mask of 255.255.0.0. You can assign a new NSIP and an associated
subnet mask during initial configuration.

If you encounter an IP address conflict when deploying multiple NetScaler units, check for the follow-
ing possible causes:

• Did you select an NSIP that is an IP address already assigned to another device on your network?
• Did you assign the same NSIP to multiple NetScaler appliances?
• The NSIP is reachable on all physical ports. The ports on a NetScaler are host ports, not switch
ports.

The following table summarizes the available access methods.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 139

NetScaler 12.0

Default IP Address Required?

Access Method Port (Y/N)

CLI Console N
CLI and GUI Ethernet Y

Command line interface

You can access the CLI either locally, by connecting a workstation to the console port, or remotely, by
connecting through secure shell (SSH) from any workstation on the same network.

Log on to the Command Line Interface through the Console Port

The appliance has a console port for connecting to a computer workstation. To log on to the appliance,
you need a serial crossover cable and a workstation with a terminal emulation program.

To log on to the CLI through the console port, follow these steps:

1. Connect the console port to a serial port on the workstation. For more information, see Connect
the console cable.
2. On the workstation, start HyperTerminal or any other terminal emulation program. If the lo-
gon prompt does not appear, you may need to press ENTER one or more times to display it.
3. Log on by using the administrator credentials. The command prompt (>) appears on the work-
station monitor.

Log on to the Command Line Interface by using SSH

The SSH protocol is the preferred remote access method for accessing an appliance remotely from any
workstation on the same network. You can use either SSH version 1 (SSH1) or SSH version 2 (SSH2.)

If you do not have a working SSH client, you can download and install any of the following SSH client
programs:

• PuTTY

Open Source software supported on multiple platforms. Available at:

“http://www.chiark.greenend.org.uk/~sgtatham/putty/”

• Vandyke Software SecureCRT

Commercial software supported on the Windows platform. Available at:

“http://www.vandyke.com/products/securecrt/”

© 1999-2018 Citrix Systems, Inc. All rights reserved. 140

NetScaler 12.0

These programs have been tested by the Citrix NetScaler team, which has verified that they work cor-
rectly with a NetScaler appliance. Other programs may also work correctly, but have not been tested.

To verify that the SSH client is installed properly, use it to connect to any device on your network that
accepts SSH connections.

To log on to a NetScaler appliance by using an SSH client, follow these steps:

1. On your workstation, start the SSH client.

2. For initial configuration, use the default IP address (NSIP), which is 192.168.100.1. For subse-
quent access, use the NSIP that was assigned during initial configuration. Select either SSH1 or
SSH2 as the protocol.
3. Log on by using the administrator credentials. For example.

1 login as: nsroot
2
3
4 Using keyboard-interactive authentication.
5
6
7 Password:
8
9
10 Last login: Tue Jun 16 10:37:28 2009 from 10.102.29.9
11
12
13
14
15
16 Done
17
18
19 >

NetScaler GUI
Important

A certificate-key pair is required for HTTPS access to the Citric ADC GUI. On the ADC, a certificate-
key pair is automatically bound to the internal services. On an MPX or SDX appliance, the default
key size is 1024 bytes, and on a VPX instance, the default key size is 512 bytes. However, most
browsers today do not accept a key that is less than 1024 bytes. As a result, HTTPS access to the
VPX configuration utility is blocked.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 141

NetScaler 12.0

Additionally, if a license is not present on an MPX appliance when it starts, and you add a license later
and restart the appliance, you might lose the certificate binding.

Citrix recommends that you install a certificate-key pair of at least 1024 bytes on a NetScaler for HTTPS
access to the GUI, and that you install an appropriate license before starting the ADC.

The graphical user interface includes a configuration utility and a statistical utility, called Dashboard,
either of which you access through a workstation connected to an Ethernet port on the appliance.

The system requirements for the workstation running the GUI are as follows:

• For Windows-based workstations, a Pentium 166 MHz or faster processor.

• For Linux-based workstations, a Pentium platform running Linux kernel v2.2.12 or above,
and glibc version 2.12-11 or later. A minimum of 32 MB RAM is required, and 48 MB RAM is
recommended. The workstation should support 16-bit color mode, KDE and KWM window
managers used in conjunction, with displays set to local hosts.
• For Solaris-based workstations, a Sun running either Solaris 2.6, Solaris 7, or Solaris 8.

Your workstation must have a supported web browser to access the configuration utility and Dash-
board.

The following browsers are supported.

Operating System:
Windows 7

Browser: Internet Explorer (version 9, 10, and 11), Mozilla Firefox (version 3.6.25 and above), Google
Chrome (latest).

Operating System:
Windows 64 bit

Browser: Internet Explorer (version 8, 9, 10, and 11), Google Chrome (version latest)

Operating System:
MAC
Browser: Mozilla Firefox (version 3.6.25 and above), Safari (version 5.1.3 and above), Google Chrome
(version latest)

Use the NetScaler GUI

Once you log on to the configuration utility, you can configure the appliance through a graphical in-
terface that includes context-sensitive help.

To log on to the GUI, follow these steps:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 142

NetScaler 12.0

1. Open your web browser and enter the NetScaler IP (NSIP) as an HTTP address. If you have not
yet set up the initial configuration, enter the default NSIP (http://192.168.100.1). The Citrix Lo-
gon page appears.

Note: If you have two NetScaler appliances in a high availability setup, make sure that you do
not access the GUI by entering the IP address of the secondary NetScaler appliance. If you do
so and use the GUI to configure the secondary appliance, your configuration changes will not
be applied to the primary NetScaler appliance.

2. In the User Name text box, type nsroot.

3. In the Password text box, type the administrative password you assigned to the nsroot account
during initial configuration and click Login. The Configuration Utility page appears.

If you need to access the online help, select Help from the Help menu at the top right corner.

Use the Statistical Utility

Dashboard, the statistical utility, is a browser-based application that displays charts and tables on
which you can monitor the performance of a NetScaler appliance.

To log on to Dashboard, follow these steps:

1. Open your web browser and enter the NSIP as an HTTP address. The Citrix Logon page appears.
2. In the User Name text box, type nsroot.
3. In the Password text box, type the administrative password you assigned to the nsroot account
during initial configuration.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure the ADC for the first time

November 2, 2018

Contributed by:
C

For initial configuration of a NetScaler MPX appliance, see Initial Configuration of a Citrix MPX appli-
ance.

For initial configuration of a Citrix SDX appliance, see Initial Configuration of a Citrix SDX appliance.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 143

NetScaler 12.0

NITRO API

You can use the NITRO API to configure the NetScaler appliance. NITRO exposes its functionality
through Representational State Transfer (REST) interfaces. Therefore, NITRO applications can be de-
veloped in any programming language. Additionally, for applications that must be developed in Java
or .NET or Python, NITRO APIs are exposed through relevant libraries that are packaged as separate
Software Development Kits (SDKs). For more information, see NITRO API.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure high availability

January 6, 2019

Contributed by:
C

You can deploy two NetScaler appliances in a high availability configuration, where one unit actively
accepts connections and manages servers while the secondary unit monitors the first. The NetScaler
appliance that is actively accepting connections and managing the servers is called a primary unit and
the other one is called a secondary unit in a high availability configuration. If there is a failure in the
primary unit, the secondary unit becomes the primary and begins actively accepting connections.

Each NetScaler appliance in a high availability pair monitors the other by sending periodic messages,
called heartbeat messages or health checks, to determine the health or state of the peer node. If
a health check for a primary unit fails, the secondary unit retries the connection for a specific time
period. For more information about high availability, see High Availability. If a retry does not succeed
by the end of the specified time period, the secondary unit takes over for the primary unit in a process
called failover. The following figure shows two high availability configurations, one in one-arm mode
and the other in two-arm mode.

Figure 1. High availability in one-arm mode

Figure 2. High availability in two-arm mode

In one-arm configuration, both NS1 and NS2 and servers S1, S2, and S3 are connected to the switch.

In two-arm configuration, both NS1 and NS2 are connected to two switches. The servers S1, S2, and S3
are connected to the second switch. The traffic between client and the servers passes through either
NS1 or NS2.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 144

NetScaler 12.0

To set up a high availability environment, configure one ADC appliance as primary and another as
secondary. Perform the following tasks on each of the ADC appliances:

• Add a node.
• Disable high availability monitoring for unused interfaces.

Add a Node

A node is a logical representation of a peer NetScaler appliance. It identifies the peer unit by ID and
NSIP. An appliance uses these parameters to communicate with the peer and track its state. When
you add a node, the primary and secondary units exchange heartbeat messages asynchronously. The
node ID is an integer that must not be greater than 64.

Through CLI

To add a node by using the command line interface, follow these steps:

At the command prompt, type the following commands to add a node and verify that the node has
been added:

• add HA node <id> <IPAddress>

• show HA node <id>

Example

1 add HA node 0 10.102.29.170

2 Done
3 > show HA node 0
4 1) Node ID: 0
5 IP: 10.102.29.200 (NS200)
6 Node State: UP
7 Master State: Primary
8 SSL Card Status: UP
9 Hello Interval: 200 msecs
10 Dead Interval: 3 secs
11 Node in this Master State for: 1:0:41:50 (days:hrs:min:
sec)

Through GUI

To add a node by using the GUI, follow these steps:

1. Navigate to System > High Availability.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 145

NetScaler 12.0

2. Click Add on the Nodes tab.

3. On the Create HA Node page, in the Remote Node IP Address text box, type the NSIP Address
(for example, 10.102.29.170) of the remote node.
4. Ensure that the Configure remote system to participate in High Availability setup check box
is selected. Provide the login credentials of the remote node in the text boxes under Remote
System Login Credentials.
5. Select the Turn off HA monitor on interfaces/channels that are down check box to disable
the HA monitor on interfaces that are down.

Verify that the node you added appears in the list of nodes in the Nodes tab.

Disable high availability monitoring for unused interfaces

The high availability monitor is a virtual entity that monitors an interface. You must disable the moni-
tor for interfaces that are not connected or being used for traffic. When the monitor is enabled on an
interface whose status is DOWN, the state of the node becomes NOT UP. In a high availability configu-
ration, a primary node entering a NOT UP state might cause a high availability failover. An interface is
marked DOWN under the following conditions:

• The interface is not connected

• The interface is not working properly
• The cable connecting the interface is not working properly

Through CLI

To disable the high availability monitor for an unused interface by using the command line interface,
follow these steps:

At the command prompt, type the following commands to disable the high availability monitor for an
unused interface and verify that it is disabled:

• set interface <id> -haMonitor OFF

• show interface <id>

Example

1 > set interface 1/8 -haMonitor OFF

2 Done
3 > show interface 1/8
4 Interface 1/8 (Gig Ethernet 10/100/1000 MBits) #2
5 flags=0x4000 <ENABLED, DOWN, down, autoneg, 802.1q>
6 MTU=1514, native vlan=1, MAC=00:d0:68:15:fd:3d, downtime
238h55m44s

© 1999-2018 Citrix Systems, Inc. All rights reserved. 146

NetScaler 12.0

7 Requested: media AUTO, speed AUTO, duplex AUTO, fctl OFF,

8 throughput 0
9
10 RX: Pkts(0) Bytes(0) Errs(0) Drops(0) Stalls(0)
11 TX: Pkts(0) Bytes(0) Errs(0) Drops(0) Stalls(0)
12 NIC: InDisc(0) OutDisc(0) Fctls(0) Stalls(0) Hangs(0)
Muted(0)
13 Bandwidth thresholds are not set.

When the high availability monitor is disabled for an unused interface, the output of the show
interface command for that interface does not include “HAMON.”

Through GUI

To disable the high availability monitor for unused interfaces by using the GUI, follow these steps:

1. Navigate to System > Network > Interfaces.

2. Select the interface for which the monitor must be disabled.
3. Click Open. The Modify Interface dialog box appears.
4. In HA Monitoring, select the OFF option.
5. Click OK.
6. Verify that, when the interface is selected, “HA Monitoring: OFF” appears in the details at the
bottom of the page.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure a FIPS appliance for the first time

December 28, 2018

Contributed by:
C

A certificate-key pair is required for HTTPS access to the configuration utility and for secure remote
procedure calls. RPC nodes are internal system entities used for system-to-system communication of
configuration and session information. One RPC node exists on each appliance. This node stores the
password, which is checked against the one provided by the contacting appliance. To communicate

© 1999-2018 Citrix Systems, Inc. All rights reserved. 147

NetScaler 12.0

with other NetScaler appliances, each appliance requires knowledge of the other appliances, includ-
ing how to authenticate on the other appliance. RPC nodes maintain this information, which includes
the IP addresses of the other NetScaler appliances and the passwords used to authenticate on each.

On a NetScaler MPX appliance virtual appliance, a certificate-key pair is automatically bound to the
internal services. On a FIPS appliance, a certificate-key pair must be imported into the hardware secu-
rity module (HSM) of a FIPS card. To do so, you must configure the FIPS card, create a certificate-key
pair, and bind it to the internal services.

Configure secure HTTPS by using the CLI

To configure secure HTTPS by using the CLI, follow these steps

1. Initialize the hardware security module (HSM) on the FIPS card of the appliance. For information
about initializing the HSM, see Configure the HSM.

2. If the appliance is part of a high availability setup, enable the SIM. For information about en-
abling the SIM on the primary and secondary appliances, see “Configure FIPS appliances in a
high availability setup.

3. Import the FIPS key into the HSM of the FIPS card of the appliance. At the command prompt,
type:

import ssl fipskey serverkey -key ns-server.key -inform PEM

4. Add a certificate-key pair. At the command prompt, type:

add certkey server -cert ns-server.cert -fipskey serverkey

5. Bind the certificate-key created in the previous step to the following internal services. At the
command prompt, type:

bind ssl service nshttps-127.0.0.1-443 -certkeyname server

bind ssl service nshttps-::11-443 -certkeyname server

Configure secure HTTPS by using the GUI

To configure secure HTTPS by using the GUI, follow these steps:

1. Initialize the hardware security module (HSM) on the FIPS card of the appliance. For information
about initializing the HSM, see Configure the HSM.

2. If the appliance is part of a high availability setup, enable the secure information system (SIM).
For information about enabling the SIM on the primary and secondary appliances, see Config-
ure FIPS appliances in a high availability setup.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 148

NetScaler 12.0

3. Import the FIPS key into the HSM of the FIPS card of the appliance. For more information about
importing a FIPS key, see the Import an existing FIPS key section.

4. Navigate to Traffic Management > SSL > Certificates.

5. <In the details pane, click Install.

6. In the Install Certificate dialog box, type the certificate details.

7. Click Create, and then click Close.

8. Navigate to Traffic Management > Load Balancing > Services.

9. In the details pane, on the Action tab, click Internal Services.

10. Select nshttps-127.0.0.1-443 from the list, and then click Open.

11. On the SSL Settings tab, in the Available pane, select the certificate created in step 7, click Add,
and then click OK.

12. Select nshttps-::11-443 from the list, and then click Open.

13. On the SSL Settings tab, in the Available pane, select the certificate created in step 7, click Add,
and then click OK.

14. Click OK.

Configure secure RPC by using the CLI

To configure secure RPC by using the CLI, follow these steps:

1. Initialize the hardware security module (HSM) on the FIPS card of the appliance. For information
about initializing the HSM, see Configure the HSM.

2. Enable the secure information system (SIM). For information about enabling the SIM on the pri-
mary and secondary appliances, see Csee Configure FIPS appliances in a high availability setup.

3. Import the FIPS key into the HSM of the FIPS card of the appliance. At the command prompt,
type:

import ssl fipskey serverkey -key ns-server.key -inform PEM

4. Add a certificate-key pair. At the command prompt, type:

add certkey server -cert ns-server.cert -fipskey serverkey

5. Bind the certificate-key pair to the following internal services. At the command prompt, type:

bind ssl service nsrpcs-127.0.0.1-3008 -certkeyname server

bind ssl service nskrpcs-127.0.0.1-3009 -certkeyname server

bind ssl service nsrpcs-::1l-3008 -certkeyname server

© 1999-2018 Citrix Systems, Inc. All rights reserved. 149

NetScaler 12.0

6. Enable secure RPC mode. At the command prompt, type:

set ns rpcnode <IP address> -secure YES

Configure secure RPC by using the GUI

To configure secure RPC by using the GUI, follow these steps:

1. Initialize the hardware security module (HSM) on the FIPS card of the appliance. For information
about initializing the HSM, see Configure the HSM.
2. Enable the secure information system (SIM). For information about enabling the SIM on the pri-
mary and secondary appliances, Configure FIPS appliances in a high availability setup.
3. Import the FIPS key into the HSM of the FIPS card of the appliance. For more information about
importing a FIPS key, the Import an existing FIPS key section.
4. Navigate to Traffic Management > SSL > Certificates.
5. In the details pane, click Install.
6. In the Install Certificate dialog box, type the certificate details.
7. Click Create, and then click Close.
8. Navigate to Traffic Management > Load Balancing > Services.
9. In the details pane, on the Action tab, click Internal Services.
10. Select nsrpcs-127.0.0.1-3008 from the list, and then click Open.
11. On the SSL Settings tab, in the Available pane, select the certificate created in step 7, click Add,
and then click OK.
12. Select nskrpcs-127.0.0.1-3009 from the list, and then click Open.
13. On the SSL Settings tab, in the Available pane, select the certificate created in step 7, click Add,
and then click OK.
14. Select nsrpcs-::11-3008 from the list, and then click Open.
15. On the SSL Settings tab, in the Available pane, select the certificate created in step 7, click Add,
and then click OK.
16. Click OK.
17. Navigate to System > Network > RPC.
18. In the details pane, select the IP address, and click Open.
19. In the Configure RPC Node dialog box, select Secure.
20. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 150

NetScaler 12.0

Common network topologies

January 6, 2019

Contributed by:
C

As described in the “Physical deployment mode” section in Where does a NetScaler appliance fit in the
network?, you can deploy the NetScaler appliance either inline between the clients and servers or in
one-arm mode. Inline mode uses a two-arm topology, which is the most common type of deployment.

Set up a common two-arm topology

In a two-arm topology, one network interface is connected to the client network and another network
interface is connected to the server network, ensuring that all traffic flows through the appliance. This
topology might require you to reconnect your hardware and also might result in a momentary down-
time. The basic variations of two-arm topology are multiple subnets, typically with the appliance on
a public subnet and the servers on a private subnet, and transparent mode, with both the appliance
and the servers on the public network.

Set up a simple two-arm multiple subnet topology

One of the most commonly used topologies has the NetScaler appliance inline between the clients
and the servers, with a virtual server configured to handle the client requests. This configuration is
used when the clients and servers reside on different subnets. In most cases, the clients and servers
reside on public and private subnets, respectively.

For example, consider an appliance deployed in two-arm mode for managing servers S1, S2, and S3,
with a virtual server of type HTTP configured on the appliance, and with HTTP services running on the
servers. The servers are on a private subnet and a SNIP is configured on the appliance to communicate
with the servers. The Use SNIP (USNIP) option must be enabled on the appliance so that it uses the
SNIP instead of the MIP.

As shown in the following figure, the VIP is on public subnet 217.60.10.0, and the NSIP, the servers, and
the SNIP are on private subnet 192.168.100.0/24.

Figure 1. Topology Diagram for Two-Arm Mode, Multiple Subnets

To deploy a NetScaler appliance in two-arm mode with multiple subnets, follow these steps:

1. Configure the NSIP and default gateway, as described in Configuring the NetScaler IP Address
(NSIP).

© 1999-2018 Citrix Systems, Inc. All rights reserved. 151

NetScaler 12.0

2. Configure the SNIP, as described in Configuring Subnet IP Addresses.

3. Enable the USNIP option, as described in To enable or disable USNIP mode section.
4. Configure the virtual server and the services, as described in Creating a Virtual Server section
and Configuring Services section.
5. Connect one of the network interfaces to a private subnet and the other interface to a public
subnet.

Set up a simple two-arm transparent topology

Use transparent mode if the clients need to access the servers directly, with no intervening virtual
server. The server IP addresses must be public because the clients need to be able to access them.
In the example shown in the following figure, a NetScaler appliance is placed between the client and
the server, so the traffic must pass through the appliance. You must enable L2 mode for bridging the
packets. The NSIP and MIP are on the same public subnet, 217.60.10.0/24.

Figure 2. Topology Diagram for Two-Arm, Transparent Mode

To deploy a NetScaler appliance in two-arm, transparent mode, follow these steps

1. Configure the NSIP and default gateway, as described in Configuring the NetScaler IP Address
(NSIP).
2. Enable L2 mode, as described in Enabling and Disabling Layer 2 Mode.
3. Configure the default gateway of the managed servers as the MIP.
4. Connect the network interfaces to the appropriate ports on the switch.

Set up common one-arm topologies

The two basic variations of one-arm topology are with a single subnet and with multiple subnets.

Set up a simple one-arm single subnet topology

You can use a one-arm topology with a single subnet when the clients and servers reside on the same
subnet. For example, consider a NetScaler appliance deployed in one-arm mode for managing servers
S1, S2, and S3. A virtual server of type HTTP is configured on an ADC appliance, and HTTP services are
running on the servers. As shown in the following figure, the NetScaler IP address (NSIP), the Mapped
IP address (MIP), and the server IP addresses are on the same public subnet, 217.60.10.0/24.

Figure 3. Topology Diagram for One-Arm Mode, Single Subnet

To deploy a NetScaler appliance in one-arm mode with a single subnet, follow these steps:

1. Configure the NSIP and the default gateway, as described in, as described in Configuring the
NetScaler IP Address (NSIP).

© 1999-2018 Citrix Systems, Inc. All rights reserved. 152

NetScaler 12.0

2. Configure the virtual server and the services, as described in Creating a Virtual Server section
and Configuring Services section.

3. Connect one of the network interfaces to the switch.

Set up a simple one-arm multiple subnet topology

You can use a one-arm topology with multiple subnets when the clients and servers reside on the dif-
ferent subnets. For example, consider a NetScaler appliance deployed in one-arm mode for managing
servers S1, S2, and S3, with the servers connected to switch SW1 on the network. A virtual server of
type HTTP is configured on the appliance, and HTTP services are running on the servers. These three
servers are on the private subnet, so a subnet IP address (SNIP) is configured to communicate with
them. The Use Subnet IP address (USNIP) option must be enabled so that the appliance uses the
SNIP instead of a MIP. As shown in the following figure, the virtual IP address (VIP) is on public subnet
217.60.10.0/24; the NSIP, SNIP, and the server IP addresses are on private subnet 192.168.100.0/24.

Figure 4. Topology Diagram for One-Arm Mode, Multiple Subnets

To deploy a NetScaler appliance in one-arm mode with multiple subnets, follow these steps:

1. Configure the NSIP and the default gateway, as described in Configuring the NetScaler IP Ad-
dress (NSIP).

2. Configure the SNIP and enable the USNIP option, as described in Configuring Subnet IP Ad-
dresses.

3. Configure the virtual server and the services, as described in Creating a Virtual Server section
and Configuring Services section.

4. Connect one of the network interfaces to the switch.

1.
2. Citrix ADC
3. NetScaler 12.0

System management settings

September 24, 2018

Contributed by:
C

Once your initial configuration is in place, you can configure settings to define the behavior of the
NetScaler appliance and facilitate connection management. You have a number of options for han-

© 1999-2018 Citrix Systems, Inc. All rights reserved. 153

NetScaler 12.0

dling HTTP requests and responses. Routing, bridging, and MAC based forwarding modes are avail-
able for handling packets not addressed to the NetScaler appliance. You can define the characteristics
of your network interfaces and can aggregate the interfaces. To prevent timing problems, you can syn-
chronize the Citrix clock with a Network Time Protocol (NTP) server. The NetScaler appliance can op-
erate in various DNS modes, including as an authoritative domain name server (ADNS). You can set up
SNMP for system management and customize syslog logging of system events. Before deployment,
verify that your configuration is complete and correct.

1.
2. Citrix ADC
3. NetScaler 12.0

System settings

September 24, 2018

Contributed by:
C

Configuration of system settings includes basic tasks such as configuring HTTP ports to enable con-
nection keep-alive and server offload, setting the maximum number of connections for each server,
and setting the maximum number of requests per connection. You can enable client IP address inser-
tion for situations in which a proxy IP address is not suitable, and you can change the HTTP cookie
version.

You can also configure a NetScaler appliance to open FTP connections on a controlled range of ports
instead of ephemeral ports for data connections. This improves security, because opening all ports
on the firewall is insecure. You can set the range anywhere from 1,024 to 64,000.

Before deployment, go through the verification checklists to verify your configuration. To configure
HTTP parameters and the FTP port range, use the NetScaler GUI.

You can modify the types of HTTP parameters described in the following table.

Parameter Type: HTTP Port Information

Specifies: The web server HTTP ports used by your managed servers. If you specify the ports, the
appliance performs request switching for any client request that has a destination port matching a
specified port.

Note: If an incoming client request is not destined for a service or a virtual server that is specif-
ically configured on the appliance, the destination port in the request must match one of the
globally configured HTTP ports. This allows the appliance to perform connection keep-alive and

© 1999-2018 Citrix Systems, Inc. All rights reserved. 154

NetScaler 12.0

server off-load.
Parameter Type: Limits

Specifies: The maximum number of connections to each managed server, and the maximum num-
ber of requests sent over each connection. For example, if you set Max Connections to 500, and the
appliance is managing three servers, it can open a maximum of 500 connections to each of the three
servers. By default, the appliance can create an unlimited number of connections to any of the servers
it manages. To specify an unlimited number of requests per connection, set Max Requests to 0.

Note: If you are using the Apache HTTP server, you must set Max Connections equal to the value
of the MaxClients parameter in the Apache httpd.conf file. Setting this parameter is optional for
other web servers.

Parameter Type: Client IP Insertion

Specifies: Enable/disable insertion of the client’s IP address into the HTTP request header. You can
specify a name for the header field in the adjacent text box. When a web server managed by an ap-
pliance receives a mapped IP address or a subnet IP address, the server identifies it as the client’s
IP address. Some applications need the client’s IP address for logging purposes or to dynamically
determine the content to be served by the web server.

You can enable insertion of the actual client IP address into the HTTP header request sent from the
client to one, some, or all servers managed by the appliance. You can then access the inserted ad-
dress through a minor modification to the server (using an Apache module, ISAPI interface, or NSAPI
interface).

Parameter Type: Cookie Version

Specifies: The HTTP cookie version to use when COOKIEINSERT persistence is configured on a virtual
server. The default, version 0, is the most common type on the Internet. Alternatively, you can specify
version 1.

Parameter Type: Requests/Responses

Specifies: Options for handling certain types of requests, and enable/disable logging of HTTP error
responses.

Parameter Type: Server Header Insertion

Specifies: Insert a server header in NetScaler-generated HTTP responses.

To configure HTTP parameters by using the GUI, follow these steps:

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

2. In the details pane, under Settings, click Change HTTP parameters.
3. In the Configure HTTP parameters dialog box, specify values for some or all of the parameters
that appear under the headings listed in the table above.
4. Click OK.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 155

NetScaler 12.0

To set the FTP port range by using the GUI, follow these steps:

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

2. In the details pane, under Settings, click Change global system settings.
3. Under FTP Port Range, in the Start Port and End Port text boxes, type the lowest and highest
port numbers, respectively, for the range you want to specify (for example, 5000 and 6000).
4. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0

Packet forwarding modes

January 6, 2019

Contributed by:
C

The NetScaler appliance can either route or bridge packets that are not destined for an IP address
owned by the appliance (that is, the IP address is not the NSIP, a MIP, a SNIP, a configured service,
or a configured virtual server). By default, L3 mode (routing) is enabled and L2 mode (bridging) is
disabled, but you can change the configuration. The following flow chart shows how the appliance
evaluates packets and either processes, routes, bridges, or drops them.

Figure 1. Interaction between Layer 2 and Layer 3 Modes

An appliance can use the following modes to forward the packets it receives:

• Layer 2 (L2) Mode

• Layer 3 (L3) Mode
• MAC-Based Forwarding Mode

Enable and disable layer 2 mode

Layer 2 mode controls the Layer 2 forwarding (bridging) function. You can use this mode to configure
a NetScaler appliance to behave as a Layer 2 device and bridge the packets that are not destined for
it. When this mode is enabled, packets are not forwarded to any of the MAC addresses, because the
packets can arrive on any interface of the appliance and each interface has its own MAC address.

With Layer 2 mode disabled (which is the default), the appliance drops packets that are not destined
for one of its MAC address. If another Layer 2 device is installed in parallel with the appliance, Layer

© 1999-2018 Citrix Systems, Inc. All rights reserved. 156

NetScaler 12.0

2 mode must be disabled to prevent bridging (Layer 2) loops. You can use the configuration utility or
the command line to enable Layer 2 mode.
Note: The appliance does not support spanning tree protocol. To avoid loops, if you enable L2 mode,
do not connect two interfaces on the appliance to the same broadcast domain.

To enable or disable Layer 2 mode by using the CLI

At the command prompt, type the following commands to enable/disable Layer 2 mode and verify
that it has been enabled/disabled:
• enable ns mode <Mode>
• disable ns mode <Mode>
• show ns mode
Examples
> enable ns mode l2
Done
> show ns mode
Mode Acronym Status
——- ——- ——
1) Fast Ramp FR ON
2) Layer 2 mode L2 ON
.
.
.
Done
>
> disable ns mode l2
Done
> show ns mode
Mode Acronym Status
——- ——- ——
1) Fast Ramp FR ON
2) Layer 2 mode L2 OFF
.
.
.
Done
>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 157

NetScaler 12.0

To enable or disable Layer 2 mode by using the GUI

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

2. In the details pane, under Modes and Features, click Configure modes.
3. In the Configure Modes dialog box, to enable Layer 2 mode, select the** Layer 2 Mode** check
box. To disable Layer 2 mode, clear the check box.
4. Click OK. The Enable/Disable Mode(s)? message appears in the details pane.
5. Click Yes.

Enable and disable layer 3 mode

Layer 3 mode controls the Layer 3 forwarding function. You can use this mode to configure a NetScaler
appliance to look at its routing table and forward packets that are not destined for it. With Layer 3
mode enabled (which is the default), the appliance performs route table lookups and forwards all
packets that are not destined for any appliance-owned IP address. If you disable Layer 3 mode, the
appliance drops these packets.

To enable or disable Layer 3 mode by using the CLI

At the command prompt, type the following commands to enable/disable Layer 3 mode and verify
that it has been enabled/disabled:

• enable ns mode <Mode>

• disable ns mode <Mode>

• show ns mode

Examples

> enable ns mode l3

Done
> show ns mode

Mode Acronym Status

——- ——- ——
1) Fast Ramp FR ON
2) Layer 2 mode L2 OFF
.
.
.
9) Layer 3 mode (ip forwarding) L3 ON
.
.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 158

NetScaler 12.0

.
Done
>

> disable ns mode l3

Done
> show ns mode

Mode Acronym Status

——- ——- ——
1) Fast Ramp FR ON
2) Layer 2 mode L2 OFF
.
.
.
9) Layer 3 mode (ip forwarding) L3 OFF
.
.
.
Done
>

To enable or disable Layer 3 mode by using the GUI

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

2. In the details pane, under Modes and Features, click Configure modes.
3. In the Configure Modes dialog box, to enable Layer 3 mode, select the Layer 3 Mode (IP Forward-
ing) check box. To disable Layer 3 mode, clear the check box.
4. Click OK. The Enable/Disable Mode(s)? message appears in the details pane.
5. Click Yes.

Enable and disable MAC based forwarding mode

You can use MAC-based forwarding to process traffic more efficiently and avoid multiple-route or ARP
lookups when forwarding packets, because the NetScaler appliance remembers the MAC address of
the source. To avoid multiple lookups, the appliance caches the source MAC address of every connec-
tion for which it performs an ARP lookup, and it returns the data to the same MAC address.

MAC-based forwarding is useful when you use VPN devices because the appliance ensures that all
traffic flowing through a particular VPN passes through the same VPN device.

The following figure shows the process of MAC-based forwarding.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 159

NetScaler 12.0

Figure 2. MAC-Based Forwarding Process

When MAC-based forwarding is enabled, the appliance caches the MAC address of:
• <The source (a transmitting device such as router, firewall, or VPN device) of the inbound con-
nection.
• <The server that responds to the requests.
When a server responds through an appliance, the appliance sets the destination MAC address of the
response packet to the cached address, ensuring that the traffic flows in a symmetric manner, and
then forwards the response to the client. The process bypasses the route table lookup and ARP lookup
functions. However, when an appliance initiates a connection, it uses the route and ARP tables for the
lookup function. To enable MAC-based forwarding, use the configuration utility or the command line.
Some deployments require the incoming and outgoing paths to flow through different routers. In
these situations, MAC-based forwarding breaks the topology design. For a global server load balanc-
ing (GSLB) site that requires the incoming and outgoing paths to flow through different routers, you
must disable MAC-based forwarding and use the appliance’s default router as the outgoing router.
With MAC-based forwarding disabled and Layer 2 or Layer 3 connectivity enabled, a route table can
specify separate routers for outgoing and incoming connections. To disable MAC-based forwarding,
use the configuration utility or the command line.

To enable or disable MAC-based forwarding by using the CLI

At the command prompt, type the following commands to enable/disable MAC-based forwarding
mode and verify that it has been enabled/disabled:
• <enable ns mode <Mode>
• <disable ns mode <Mode>
• <show ns mode
Example
“‘ pre codeblock

enable ns mode mbf

Done
show ns mode

1 Mode Acronym Status

2 ------- ------- ------ 1) Fast
Ramp FR ON 2) Layer 2
mode L2 OFF . . . 6)
MAC-based forwarding MBF ON . . .
Done >

© 1999-2018 Citrix Systems, Inc. All rights reserved. 160

NetScaler 12.0

disable ns mode mbf

Done
show ns mode

1 Mode Acronym Status

2 ------- ------- ------ 1) Fast
Ramp FR ON 2) Layer 2
mode L2 OFF . . . 6)
MAC-based forwarding MBF OFF . . .
Done > ‘‘‘

To enable or disable MAC-based forwarding by using the GUI

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

2. In the details pane, under Modes and Features group, click Configure modes.
3. In the** Configure Modes** dialog box, to enable MAC-based forwarding mode, select the** MAC
Based Forwarding **check box. To disable MAC-based forwarding mode, clear the check box.
4. Click OK. The Enable/Disable Mode(s)? message appears in the details pane.
5. Click Yes.

1.
2. Citrix ADC
3. NetScaler 12.0

Network interfaces

December 28, 2018

Contributed by:
C

The NetScaler interfaces are numbered in slot/port notation. In addition to modifying the characteris-
tics of individual interfaces, you can configure virtual LANs to restrict traffic to specific groups of hosts.
You can also aggregate links into high-speed channels.

Virtual LANs

The NetScaler appliance supports (Layer 2) port and IEEE802.1Q tagged virtual LANs (VLANs). VLAN
configurations are useful when you need to restrict traffic to certain groups of stations. You can con-
figure a network interface to belong to multiple VLANs by using IEEE 802.1q tagging.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 161

NetScaler 12.0

You can bind your configured VLANs to IP subnets. The ADC appliance (if it is configured as the default
router for the hosts on the subnets) then performs IP forwarding between these VLANs.
The NetScaler appliance supports the following types of VLANs.
• Default VLAN
By default, the network interfaces on a NetScaler appliance are included in a single, port-based
VLAN as untagged network interfaces. This default VLAN has a VID of 1 and exists permanently.
It cannot be deleted, and its VID cannot be changed.
• Port-Based VLANs
A set of network interfaces that share a common, exclusive, Layer 2 broadcast domain define
the membership of a port-based VLAN. You can configure multiple port-based VLANs. When
you add an interface to a new VLAN as an untagged member, it is automatically removed from
the default VLAN.
• Tagged VLAN
A network interface can be a tagged or untagged member of a VLAN. Each network interface is an
untagged member of only one VLAN (its native VLAN). The untagged network interface forwards
the frames for the native VLAN as untagged frames. A tagged network interface can be a part
of more than one VLAN. When you configure tagging, be sure that both ends of the link have
matching VLAN settings. You can use the configuration utility to define a tagged VLAN (nsvlan)
that can have any ports bound as tagged members of the VLAN. Configuring this VLAN requires
a reboot of the ADC appliance and therefore must be done during initial network configuration.

Link aggregate channels

Link aggregation combines incoming data from multiple ports into a single high speed link. Configur-
ing the link aggregate channel increases the capacity and availability of the communication channel
between a NetScaler appliance and other connected devices. An aggregated link is also referred to as
a channel.
When a network interface is bound to a channel, the channel parameters have precedence over the
network interface parameters. A network interface can be bound to only one channel. Binding a net-
work interface to a link aggregate channel changes the VLAN configuration. That is, binding network
interfaces to a channel removes them from the VLANs that they originally belonged to and adds them
to the default VLAN. However, you can bind the channel back to the old VLAN, or to a new one. For
example, if you have bound network interfaces 1/2 and 1/3 to a VLAN with ID 2, and then you bind
them to link aggregate channel LA/1, the network interfaces are moved to the default VLAN, but you
can bind them to VLAN 2.
Note: You can also use Link Aggregation Control Protocol (LACP) to configure link aggregation. For
more information, see Configuring Link Aggregation by Using the Link Aggregation Control Protocol.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 162

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0

Clock synchronization

September 24, 2018

Contributed by:
C

You can configure your NetScaler appliance to synchronize its local clock with a Network Time Proto-
col (NTP) server. This ensures that its clock has the same date and time settings as the other servers
on your network. NTP uses User Datagram Protocol (UDP) port 123 as its transport layer. You have
to add NTP servers in the NTP configuration file so that the appliance periodically gets updates from
these servers.

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 at http://www.ntp.org.

To configure clock synchronization on your appliance, follow these steps:

1. Log on to the command line and enter the shell command.

2. At the shell prompt, copy the ntp.conf file from the /etc directory to the /nsconfig directory. If
the file already exists in the /nsconfig directory, make sure that you 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. However, this
feature is not supported on the NetScaler appliance.

3. Edit /nsconfig/ntp.conf by typing the IP address for the desired NTP server under the file’s server
and restrict entries.

4. Create a file named rc.netscaler in the /nsconfig directory, if the file does not already exist in the
directory.

5. Edit /nsconfig/rc.netscaler by adding 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.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 163

NetScaler 12.0

Note: If the time difference between the NetScaler appliance and the time server is more than
1000 sec, the ntpd service terminates with a message to the ADC log. To avoid this, you need to
start ntpd with the
-g option, which forcibly syncs the time. Add the following entry in
/nsconfig/rc.netscaler:

/usr/sbin/ntpd -g -c /nsconfig/ntp.conf -l /var/log/ntpd.log &

If you do not want to forcibly sync the time when there is a large difference, you can set the date
manually and then start ntpd again. You can check the time difference between the appliance
and the time server by running the following command in the shell:

1 ntpdate -q <IP address or domain name of the NTP server>

6. Reboot the appliance to enable clock synchronization.

Note: If you want to start time synchronization before you restart the appliance, enter the fol-
lowing command (which you added to the rc.netscaler file in step 5) at the shell prompt:

1 /usr/sbin/ntpd -c /nsconfig/ntp.conf -l /var/log/ ntpd.log &

1.
2. Citrix ADC
3. NetScaler 12.0

DNS configuration

September 24, 2018

Contributed by:
C

You can configure a NetScaler appliance to function as an Authoritative Domain Name Server (ADNS),
DNS proxy server, End Resolver, or Forwarder. You can add DNS resource records such as SRV Records,
AAAA Records, A Records, MX Records, NS Records, CNAME Records, PTR Records, and SOA Records.
Also, the appliance can balance the load on external DNS servers.

A common practice is to configure an appliance as a forwarder. For this configuration, you need to
add external name servers. After you have added the external servers, you should verify that your
configuration is correct.

You can add, remove, enable, and disable external name servers. You can create a name server by
specifying its IP address, or you can configure an existing virtual server as the name server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 164

NetScaler 12.0

When adding name servers, you can specify IP addresses or virtual IP addresses (VIPs). If you use
IP addresses, the appliance load balances requests to the configured name servers in a round robin
manner. If you use VIPs, you can specify any load balancing method.

Add a name server by using the CLI

At the command prompt, type the following commands to add a name server and verify the configu-
ration:

• <add dns nameServer <IP>

• <show dns nameServer <IP>

Example

“‘ pre codeblock

add dns nameServer 10.102.29.10

Done
show dns nameServer 10.102.29.10
1) 10.102.29.10 - State: DOWN
Done

“‘

Add a name server by using the GUI

1. Navigate to Traffic Management > DNS > Name Servers.

2. In the details pane, click Add.
3. In the Create Name Server dialog box, select IP Address.
4. In the IP Address text box, type the IP address of the name server (for example, 10.102.29.10). If
you are adding an external name server, clear the Local check box.
5. Click Create, and then click Close.
6. Verify that the name server you added appears in the Name Servers pane.

1.
2. Citrix ADC
3. NetScaler 12.0

SNMP configuration

January 6, 2019

© 1999-2018 Citrix Systems, Inc. All rights reserved. 165

NetScaler 12.0

Contributed by:
C

The Simple Network Management Protocol (SNMP) network management application, running on
an external computer, queries the SNMP agent on the NetScaler appliance. The agent searches the
management information base (MIB) for data requested by the network management application and
sends the data to the application.

SNMP monitoring uses traps messages and alarms. SNMP traps messages are asynchronous events
that the agent generates to signal abnormal conditions, which are indicated by alarms. For example,
if you want to be informed when CPU utilization is above 90 percent, you can set up an alarm for that
condition. The following figure shows a network with a NetScaler appliance that has SNMP enabled
and configured.

Figure 1. SNMP on the NetScaler appliance

The SNMP agent on a NetScaler appliance supports SNMP version 1 (SNMPv1), SNMP version 2 (SN-
MPv2), and SNMP version 3 (SNMPv3). Because it operates in bilingual mode, the agent can handle
SNMPv2 queries, such as Get-Bulk, and SNMPv1 queries. The SNMP agent also sends traps compliant
with SNMPv2 and supports SNMPv2 data types, such as counter64. SNMPv1 managers (programs on
other servers that request SNMP information from the ADC appliance) use the NS-MIB-smiv1.mib file
when processing SNMP queries. SNMPv2 managers use the NS-MIB-smiv2.mib file.

The NetScaler appliance supports the following enterprise-specific MIBs:

• A subset of standard MIB-2 groups

Provides MIB-2 groups SYSTEM, IF, ICMP, UDP, and SNMP.

• A system enterprise MIB

Provides system-specific configuration and statistics.

To configure SNMP, you specify which managers can query the SNMP agent, add SNMP trap listeners
that will receive the SNMP trap messages, and configure SNMP Alarms.

Add SNMP managers

You can configure a workstation running a management application that complies with SNMP version
1, 2, or 3 to access an appliance. Such a workstation is called an SNMP manager. If you do not specify
an SNMP manager on the appliance, the appliance accepts and responds to SNMP queries from all IP
addresses on the network. If you configure one or more SNMP managers, the appliance accepts and
responds to SNMP queries from only those specific IP addresses. When specifying the IP address of
an SNMP manager, you can use the netmask parameter to grant access from entire subnets. You can
add a maximum of 100 SNMP managers or networks. To add an SNMP manager by using the CLI

© 1999-2018 Citrix Systems, Inc. All rights reserved. 166

NetScaler 12.0

At the command prompt, type the following commands to add an SNMP manager and verify the con-
figuration:

**add snmp manager <IPAddress> … [-netmask <netmask>] **

s**how snmp manager** <IPAddress>

Example:

> add snmp manager 10.102.29.5 -netmask 255.255.255.255

Done

> show snmp manager 10.102.29.5

1) 10.102.29.5 255.255.255.255

Done

>

To add an SNMP manager by using the GUI:

1. In the navigation pane, expand System, expand SNMP, and then click Managers.
2. In the details pane, click Add.
3. In the Add SNMP Manager dialog box, in the IP Address text box, type the IP address of the
workstation running the management application (for example, 10.102.29.5).
4. Click Create, and then click Close.
5. Verify that the SNMP manager you added appears in the Details section at the bottom of the
pane.

Add SNMP traps listeners

After configuring the alarms, you need to specify the trap listener to which the appliance will send the
trap messages. Apart from specifying parameters like IP address and the destination port of the trap
listener, you can specify the type of trap (either generic or specific) and the SNMP version.

You can configure a maximum of 20 trap listeners for receiving either generic or specific traps.

To add an SNMP trap listener by using the CLI

At the command prompt, type the following command to add an SNMP trap and verify that it has been
added:

• add snmp trap specific <IP>

• show snmp trap

Example

© 1999-2018 Citrix Systems, Inc. All rights reserved. 167

NetScaler 12.0

> add snmp trap specific 10.102.29.3

Done
> show snmp trap
Type DestinationIP DestinationPort Version SourceIP Min-Severity Community
—- ————- ————— ——- ——– ———— ———
generic 10.102.29.9 162 V2 NetScaler IP N/A public
generic 10.102.29.5 162 V2 NetScaler IP N/A public
generic 10.102.120.101 162 V2 NetScaler IP N/A public
.
.
.
specific 10.102.29.3 162 V2 NetScaler IP - public
Done
>

To add an SNMP trap listener by using the GUI

1. In the navigation pane, expand System, expand SNMP, and then click Traps.
2. In the details pane, click Add.
3. In the Create SNMP Trap Destination dialog box, in the Destination IP Address text box, type the
IP address (for example, 10.102.29.3).
4. Click Create and then click Close.
5. Verify that the SNMP trap you added appears in the Details section at the bottom of the pane.

Configure SNMP alarms

You configure alarms so that the appliance generates a trap message when an event corresponding to
one of the alarms occurs. Configuring an alarm consists of enabling the alarm and setting the severity
level at which a trap is generated. There are five severity levels: Critical, Major, Minor, Warning, and
Informational. A trap is sent only when the severity of the alarm matches the severity specified for the
trap.
Some alarms are enabled by default. If you disable an SNMP alarm, the appliance will not generate
trap messages when corresponding events occur. For example, if you disable the Login-Failure SNMP
alarm, the appliance will not generate a trap message when a login failure occurs.

To enable or disable an alarm by using the CLI

At the command prompt, type the following commands to enable or disable an alarm and verify that
it has been enabled or disabled:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 168

NetScaler 12.0

set snmp alarm <trapName> [-state ENABLED DISABLED ]

• show snmp alarm <trapName>

Example

> set snmp alarm LOGIN-FAILURE -state ENABLED

Done
> show snmp alarm LOGIN-FAILURE
Alarm Alarm Threshold Normal Threshold Time State Severity Logging
—– ————— —————- —- ——– ——— ——–
1) LOGIN-FAILURE N/A N/A N/A ENABLED - ENABLED
Done
>

To set the severity of the alarm by using the CLI

At the command prompt, type the following commands to set the severity of the alarm and verify that
the severity has been set correctly:

• set snmp alarm <trapName> [-severity <severity>]

• show snmp alarm <trapName>

Example

> set snmp alarm LOGIN-FAILURE -severity Major

Done
> show snmp alarm LOGIN-FAILURE
Alarm Alarm Threshold Normal Threshold Time State Severity Logging
—– ————— —————- —- ——– ——— ——–
1) LOGIN-FAILURE N/A N/A N/A ENABLED Major ENABLED
Done
>

To configure alarms by using the GUI

1. In the navigation pane, expand System, expand SNMP, and then click Alarms.
2. In the details pane, select an alarm (for example, LOGIN-FAILURE), and then click Open.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 169

NetScaler 12.0

3. In the Configure SNMP Alarm dialog box, to enable the alarm, select Enabled in the State drop-
down list. To disable the alarm, select Disabled.
4. In the Severity drop-down list, select a severity option (for example, Major).
5. Click OK, and then click Close.
6. Verify that the parameters for the SNMP alarm you configured are correctly configured by view-
ing the Details section at the bottom of the pane.

1.
2. Citrix ADC
3. NetScaler 12.0

Verify configuration

September 24, 2018

Contributed by:
C

After you’ve finished configuring your system, complete the following checklists to verify your config-
uration.

Configuration checklist

• The build running is:

• There are no incompatibility issues. (Incompatibility issues are documented in the build’s re-
lease notes.)
• The port settings (speed, duplex, flow control, monitoring) are the same as the switch’s port.
• Enough mapped IP addresses have been configured to support all server-side connections dur-
ing peak times.
– The number of configured mapped IP addresses is:____
– The expected number of simultaneous server connections is:
[ ] 62,000 [ ] 124,000 [ ] Other____

Topology configuration checklist

The routes have been used to resolve servers on other subnets.

The routes entered are:

_________________________________________

© 1999-2018 Citrix Systems, Inc. All rights reserved. 170

NetScaler 12.0

• If the NetScaler appliance is in a public-private topology, reverse NAT has been configured.

• The failover (high availability) settings configured on the ADC appliance resolve in a one arm or
two-arm configuration. All unused network interfaces have been disabled:

_________________________________________

• If the ADC appliance is placed behind an external load balancer, then the load balancing policy
on the external load balancer is not “least connection.”

The load balancing policy configured on the external load balancer is:

_________________________________________

• If the ADC appliance is placed in front of a firewall, the session time-out on the firewall is set to
a value greater than or equal to 300 seconds.

Note: The TCP idle connection timeout on a NetScaler appliance is 360 seconds. If the timeout
on the firewall is also set to 300 seconds or more, then the appliance can perform TCP connec-
tion multiplexing effectively because connections will not be closed earlier.

The value configured for the session time-out is: ___________________

Server configuration checklist

• “Keep-alive” has been enabled on all the servers.

The value configured for the keep-alive time-out is: ___________________

• The default gateway has been set to the correct value. (The default gateway should either be a
NetScaler appliance or upstream router.) The default gateway is:

_________________________________________

• The server port settings (speed, duplex, flow control, monitoring) are the same as the switch
port settings.

_________________________________________

• If the Microsoft® Internet Information Server is used, buffering is enabled on the server.

• If an Apache Server is used, the MaxConn (maximum number of connections) parameter is con-
figured on the server and on the NetScaler appliance.

The MaxConn (maximum number of connections) value that has been set is:

_________________________________________

• If a Netscape Enterprise Server is used, the maximum requests per connection parameter is set
on the NetScaler appliance. The maximum requests per connection value that has been set is:

_________________________________________

© 1999-2018 Citrix Systems, Inc. All rights reserved. 171

NetScaler 12.0

Software features configuration checklist

• Does the Layer 2 mode feature need to be disabled? (Disable if another Layer 2 device is working
in parallel with a NetScaler appliance.)

Reason for enabling or disabling:

_________________________________________

• Does the MAC-based forwarding feature need to be disabled? (If the MAC address used by return
traffic is different, it should be disabled.)

Reason for enabling or disabling:

_________________________________________

• <Does host-based reuse need to be disabled? (Is there virtual hosting on the servers?)

Reason for enabling or disabling:

_________________________________________

• Do the default settings of the surge protection feature need to be changed?

Reason for changing or not changing:

_________________________________________

Access checklist

• The system IPs can be pinged from the client-side network.

• The system IPs can be pinged from the server-side network.
• The managed server(s) can be pinged through the NetScaler.
• Internet hosts can be pinged from the managed servers.
• The managed server(s) can be accessed through the browser.
• The Internet can be accessed from managed server(s) using the browser.
• The system can be accessed using SSH.
• Admin access to all managed server(s) is working.

Note: When you are using the ping utility, ensure that the pinged server has ICMP ECHO enabled,
or your ping will not succeed.

Firewall checklist

The following firewall requirements have been met:

• UDP 161 (SNMP)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 172

NetScaler 12.0

• UDP 162 (SNMP trap)

• TCP/UDP 3010 (GUI)
• HTTP 80 (GUI)
• TCP 22 (SSH)

1.
2. Citrix ADC
3. NetScaler 12.0

Load balance traffic on a NetScaler appliance

January 6, 2019

Contributed by:
C

The load balancing feature distributes client requests across multiple servers to optimize resource
utilization. In a real-world scenario with a limited number of servers providing service to a large num-
ber of clients, a server can become overloaded and degrade the performance of the server farm. A
NetScaler appliance uses load balancing criteria to prevent bottlenecks by forwarding each client re-
quest to the server best suited to handle the request when it arrives.

To configure load balancing, you define a virtual server to proxy multiple servers in a server farm and
balance the load among them.

When a client initiates a connection to the server, a virtual server terminates the client connection and
initiates a new connection with the selected server, or reuses an existing connection with the server,
to perform load balancing. The load balancing feature provides traffic management from Layer 4 (TCP
and UDP) through Layer 7 (FTP, HTTP, and HTTPS).

The NetScaler appliance uses a number of algorithms, called load balancing methods, to determine
how to distribute the load among the servers. The default load balancing method is the Least Connec-
tions method.

A typical load balancing deployment consists of the entities described in the following figure.

Figure 1. Load Balancing Architecture

The entities function as follows:

• Virtual server. An entity that is represented by an IP address, a port, and a protocol. The virtual
server IP address (VIP) is usually a public IP address. The client sends connection requests to
this IP address. The virtual server represents a bank of servers.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 173

NetScaler 12.0

• Service. A logical representation of a server or an application running on a server. Identifies

the server’s IP address, a port, and a protocol. The services are bound to the virtual servers.
• Server object. An entity that is represented by an IP address. The server object is created when
you create a service. The IP address of the service is taken as the name of the server object. You
can also create a server object and then create services by using the server object.
• Monitor. An entity that tracks the health of the services. The appliance periodically probes the
servers using the monitor bound to each service. If a server does not respond within a specified
response timeout, and the specified number of probes fails, the service is marked DOWN. The
appliance then performs load balancing among the remaining services.

1.
2. Citrix ADC
3. NetScaler 12.0

Load balancing

January 6, 2019

Contributed by:
C

To configure load balancing, you must first create services. Then, you create virtual servers and bind
the services to the virtual servers. By default, the NetScaler appliance binds a monitor to each service.
After binding the services, verify your configuration by making sure that all of the settings are correct.

Note: After you deploy the configuration, you can display statistics that show how the entities in
the configuration are performing. Use the statistical utility or the
stat lb vserver <vserverName> command.

Optionally, you can assign weights to a service. The load balancing method then uses the assigned
weight to select a service. For getting started, however, you can limit optional tasks to configuring
some basic persistence settings, for sessions that must maintain a connection to a particular server,
and some basic configuration-protection settings.

The following flow chart illustrates the sequence of the configuration tasks.

Figure 1. Sequence of Tasks to Configure Load Balancing

Enable load balancing

Before configuring load balancing, make sure that the load balancing feature is enabled.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 174

NetScaler 12.0

To enable load balancing by using the CLI

At the command prompt, type the following commands to enable load balancing and verify that it is
enabled:

• enable feature lb

• show feature

Example

“‘ pre codeblock

enable feature lb
Done
show feature

1 Feature Acronym Status

2 ------- ------- ------ 1) Web
Logging WL OFF 2) Surge
Protection SP OFF 3) Load Balancing
LB ON . . . 9) SSL
Offloading SSL ON . . . Done
‘‘‘

To enable load balancing by using the GUI

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

2. In the details pane, under Modes and Features, click Change basic features.
3. In the Configure Basic Features dialog box, select the Load Balancing check box, and then click
OK.
4. In the Enable/Disable Feature(s)? message, click Yes.

Configure services and a virtual server

When you have identified the services you want to load balance, you can implement your initial load
balancing configuration by creating the service objects, creating a load balancing virtual server, and
binding the service objects to the virtual server.

To implement the initial load balancing configuration by using the CLI

At the command prompt, type the following commands to implement and verify the initial configura-
tion:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 175

NetScaler 12.0

• <add service <name> <IPaddress> <serviceType> <port>

• <add lb vserver <vServerName> <serviceType> [<IPaddress> <port>]

• <bind lb vserver <name> <serviceName>

• <show service bindings <serviceName>

Example

1 > add service service-HTTP-1 10.102.29.5 HTTP 80

2 Done
3 > add lb vserver vserver-LB-1 HTTP 10.102.29.60 80
4 Done
5 > bind lb vserver vserver-LB-1 service-HTTP-1
6 Done
7 > show service bindings service-HTTP-1
8 service-HTTP-1 (10.102.29.5:80) - State : DOWN
9
10 1) vserver-LB-1 (10.102.29.60:80) - State : DOWN
11 Done

To implement the initial load balancing configuration by using the GUI

1. Navigate to Traffic Management > Load Balancing.

2. In the details pane, under Getting Started, click Load Balancing wizard, and follow the instruc-
tions to create a basic load balancing setup.
3. Return to the navigation pane, expand Load Balancing, and then click Virtual Servers.
4. Select the virtual server that you configured and verify that the parameters displayed at the
bottom of the page are correctly configured.
5. Click Open.
6. Verify that each service is bound to the virtual server by confirming that the Active check box is
selected for each service on the Services tab.

1.
2. Citrix ADC
3. NetScaler 12.0

Persistence settings

November 14, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 176

NetScaler 12.0

Contributed by:
C

You must configure persistence on a virtual server if you want to maintain the states of connections
on the servers represented by that virtual server (for example, connections used in e-commerce). The
appliance then uses the configured load balancing method for the initial selection of a server, but
forwards to that same server all subsequent requests from the same client.

If persistence is configured, it overrides the load balancing methods once the server has been selected.
If the configured persistence applies to a service that is down, the appliance uses the load balancing
methods to select a new service, and the new service becomes persistent for subsequent requests
from the client. If the selected service is in an Out Of Service state, it continues to serve the outstand-
ing requests but does not accept new requests or connections. After the shutdown period elapses,
the existing connections are closed. The following table lists the types of persistence that you can
configure.

Persistence Type Persistent Connections

Source IP, SSL Session ID, Rule, DESTIP, 250K

SRCIPDESTIP
CookieInsert, URL passive, Custom Server ID Memory limit. In case of CookieInsert, if time
out is not 0, any number of connections is
allowed until limited by memory.

Table 1. Limitations on Number of Simultaneous Persistent Connections

If the configured persistence cannot be maintained because of a lack of resources on an appliance,

the load balancing methods are used for server selection. Persistence is maintained for a configured
period of time, depending on the persistence type. Some persistence types are specific to certain
virtual servers. The following table shows the relationship.

Persistence
TypeHeader
1 HTTP HTTPS TCP UDP/IP SSL_Bridge

Source IP YES YES YES YES YES

CookieInsert YES YES NO NO NO
SSL Session NO YES NO NO YES
ID
URL Passive YES YES NO NO NO

© 1999-2018 Citrix Systems, Inc. All rights reserved. 177

NetScaler 12.0

Persistence
TypeHeader
1 HTTP HTTPS TCP UDP/IP SSL_Bridge

Custom YES YES NO NO NO

Server ID
Rule YES YES NO NO NO
SRCIPDESTIP N/A N/A YES YES N/A
DESTIP N/A N/A YES YES N/A

Table 2. Persistence Types Available for Each Type of Virtual Server

You can also specify persistence for a group of virtual servers. When you enable persistence on the
group, the client requests are directed to the same selected server regardless of which virtual server
in the group receives the client request. When the configured time for persistence elapses, any virtual
server in the group can be selected for incoming client requests.
Two commonly used persistence types are persistence based on cookies and persistence based on
server IDs in URLs.

Configure persistence based on cookies

When you enable persistence based on cookies, the the NetScaler appliance adds an HTTP cookie
into the Set-Cookie header field of the HTTP response. The cookie contains information about the
service to which the HTTP requests must be sent. The client stores the cookie and includes it in all
subsequent requests, and the ADC uses it to select the service for those requests. You can use this
type of persistence on virtual servers of type HTTP or HTTPS.
The NetScaler appliance inserts the cookie <NSC_XXXX>= <ServiceIP> <ServicePort>
where:
• <<NSC_XXXX> is the virtual server ID that is derived from the virtual server name.
• <<ServiceIP> is the hexadecimal value of the IP address of the service.
• <<ServicePort> is the hexadecimal value of the port of the service.
The ADC encrypts ServiceIP and ServicePort when it inserts a cookie, and decrypts them when it re-
ceives a cookie.
Note: If the client is not allowed to store the HTTP cookie, the subsequent requests do not have the
HTTP cookie, and persistence is not honored.
By default, the ADC appliance sends HTTP cookie version 0, in compliance with the Netscape specifi-
cation. It can also send version 1, in compliance with RFC 2109.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 178

NetScaler 12.0

You can configure a timeout value for persistence that is based on HTTP cookies. Note the following:

• If HTTP cookie version 0 is used, the NetScaler appliance inserts the absolute Coordinated Uni-
versal Time (GMT) of the cookie’s expiration (the expires attribute of the HTTP cookie), calcu-
lated as the sum of the current GMT time on an ADC appliance, and the timeout value.
• If an HTTP cookie version 1 is used, the ADC appliance inserts a relative expiration time (Max-Age
attribute of the HTTP cookie). In this case, the client software calculates the actual expiration
time.

Note: Most client software currently installed (Microsoft Internet Explorer and Netscape browsers)
understand HTTP cookie version 0; however, some HTTP proxies understand HTTP cookie version 1.

If you set the timeout value to 0, the ADC appliance does not specify the expiration time, regardless
of the HTTP cookie version used. The expiration time then depends on the client software, and such
cookies are not valid if that software is shut down. This persistence type does not consume any system
resources. Therefore, it can accommodate an unlimited number of persistent clients.

An administrator can change the HTTP cookie version.

To change the HTTP cookie version by using the CLI

At the command prompt, type;

1 set ns param [-cookieversion ( 0 | 1 )]

Example:

1 set ns param -cookieversion 1

To change the HTTP cookie version by using the GUI

1. Navigate to System > Settings.

2. <In the details pane, click Change HTTP Parameters.
3. <In the Configure HTTP Parameters dialog box, under Cookie, select Version 0 or Version 1.

Note: For information about the parameters, see

Configuring Persistence Based on Cookies.

To configure persistence based on cookies by using the CLI

At the command prompt, type the following commands to configure persistence based on cookies
and verify the configuration:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 179

NetScaler 12.0

1 set lb vserver <name> -persistenceType COOKIEINSERT

2
3 show lb vserver <name>

Example:

1 set lb vserver vserver-LB-1 -persistenceType COOKIEINSERT

2 Done
3 show lb vserver vserver-LB-1
4 vserver-LB-1 (10.102.29.60:80) - HTTP Type: ADDRESS
5 .
6 .
7 .
8 Persistence: COOKIEINSERT (version 0)
9 Persistence Timeout: 2 min
10 .
11 .
12 .
13 Done

To configure persistence based on cookies by using the GUI

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.

2. In the details pane, select the virtual server for which you want to configure persistence (for
example, vserver-LB-1), and then click Open.
3. In the Configure Virtual Server (Load Balancing) dialog box, on the Method and Persistence tab,
in the Persistence list, select COOKIEINSERT.
4. In the Time-out (min) text box, type the time-out value (for example, 2).
5. Click OK.
6. Verify that the virtual server for which you configured persistence is correctly configured by se-
lecting the virtual server and viewing the Details section at the bottom of the pane.

Configure persistence based on server IDs in URLs

The NetScaler appliance can maintain persistence based on the server IDs in the URLs. In a technique
called URL passive persistence, the ADC extracts the server ID from the server response and embeds
it in the URL query of the client request. The server ID is an IP address and port specified as a hexadec-
imal number. The ADC extracts the server ID from subsequent client requests and uses it to select the
server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 180

NetScaler 12.0

URL passive persistence requires configuring either a payload expression or a policy infrastructure
expression specifying the location of the server ID in the client requests. For more information about
expressions, see “Policy Configuration and Reference.”
Note: If the server ID cannot be extracted from the client requests, server selection is based on the
load balancing method.
Example: Payload Expression
The expression, URLQUERY contains sid= configures the system to extract the server ID from
the URL query of a client request, after matching token sid=. Thus, a request with the URL
http://www.citrix.com/index.asp?\&sid;=c0a864100050 is directed to the server with the IP ad-
dress10.102.29.10 and port 80.
The timeout value does not affect this type of persistence, which is maintained as long as the server
ID can be extracted from the client requests. This persistence type does not consume any system
resources, so it can accommodate an unlimited number of persistent clients.

Note: For information about the parameters, see

Load Balancing.

To configure persistence based on server IDs in URLs by using the CLI

At the command prompt, type the following commands to configure persistence based on server IDs
in URLs and verify the configuration:

1 set lb vserver <name> -persistenceType URLPASSIVE

2
3 show lb vserver <name>

Example:

1 set lb vserver vserver-LB-1 -persistenceType URLPASSIVE

2 Done
3 show lb vserver vserver-LB-1
4 vserver-LB-1 (10.102.29.60:80) - HTTP Type: ADDRESS
5 .
6 .
7 .
8 Persistence: URLPASSIVE
9 Persistence Timeout: 2 min
10 .
11 .
12 .
13 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 181

NetScaler 12.0

To configure persistence based on server IDs in URLs by using the GUI

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.

2. In the details pane, select the virtual server for which you want to configure persistence (for
example, vserver-LB-1), and then click Open.
3. In the Configure Virtual Server (Load Balancing) dialog box, on the Method and Persistence tab,
in the Persistence list, select URLPASSIVE.
4. In the Time-out (min) text box, type the time-out value (for example, 2).
5. In the Rule text box, enter a valid expression. Alternatively, click Configure next to the Rule text
box and use the Create Expression dialog box to create an expression.
6. Click OK.
7. Verify that the virtual server for which you configured persistence is correctly configured by se-
lecting the virtual server and viewing the Details section at the bottom of the pane.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure features to protect the load balancing configuration

September 24, 2018

Contributed by:
C

You can configure URL redirection to provide notifications of virtual server malfunctions, and you can
configure backup virtual servers to take over if a primary virtual server becomes unavailable.

Configure URL redirection

You can configure a redirect URL to communicate the status of the appliance in the event that a vir-
tual server of type HTTP or HTTPS is down or disabled. This URL can be a local or remote link. The
appliance uses HTTP 302 redirect.

Redirects can be absolute URLs or relative URLs. If the configured redirect URL contains an absolute
URL, the HTTP redirect is sent to the configured location, regardless of the URL specified in the incom-
ing HTTP request. If the configured redirect URL contains only the domain name (relative URL), the
HTTP redirect is sent to a location after appending the incoming URL to the domain configured in the
redirect URL.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 182

NetScaler 12.0

Note: If a load balancing virtual server is configured with both a backup virtual server and a redirect
URL, the backup virtual server takes precedence over the redirect URL. In this case, a redirect is used
when both the primary and backup virtual servers are down.

To configure a virtual server to redirect client requests to a URL by using the CLI

At the command prompt, type the following commands to configure a virtual server to redirect client
requests to a URL and verify the configuration:

• <set lb vserver <name> -redirectURL <URL>

• <show lb vserver <name>

Example

“‘ pre codeblock

set lb vserver vserver-LB-1 -redirectURL http://www.newdomain.com/mysite/maintenance

Done
show lb vserver vserver-LB-1
vserver-LB-1 (10.102.29.60:80) - HTTP Type: ADDRESS
State: DOWN
Last state change was at Wed Jun 17 08:56:34 2009 (+666 ms)
.
.
.
Redirect URL: http://www.newdomain.com/mysite/maintenance
.
.
.
Done

“‘

To configure a virtual server to redirect client requests to a URL by using the GUI

1. <Navigate to Traffic Management > Load Balancing > Virtual Servers.

2. <In the details pane, select the virtual server for which you want to configure URL redirection
(for example, vserver-LB-1), and then click Open.
3. <In the Configure Virtual Server (Load Balancing) dialog box, on the Advanced tab, in the
Redirect URL text box, type the URL (for example, http://www.newdomain.com/mysite/
maintenance), and then click OK.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 183

NetScaler 12.0

4. <Verify that the redirect URL you configured for the server appears in the Details section at the
bottom of the pane.

Configure backup virtual servers

If the primary virtual server is down or disabled, the appliance can direct the connections or client
requests to a backup virtual server that forwards the client traffic to the services. The appliance can
also send a notification message to the client regarding the site outage or maintenance. The backup
virtual server is a proxy and is transparent to the client.

You can configure a backup virtual server when you create a virtual server or when you change the
optional parameters of an existing virtual server. You can also configure a backup virtual server for an
existing backup virtual server, thus creating a cascaded backup virtual server. The maximum depth
of cascading backup virtual servers is 10. The appliance searches for a backup virtual server that is up
and accesses that virtual server to deliver the content.

You can configure URL redirection on the primary for use when the primary and the backup virtual
servers are down or have reached their thresholds for handling requests.

Note: If no backup virtual server exists, an error message appears, unless the virtual server is config-
ured with a redirect URL. If both a backup virtual server and a redirect URL are configured, the backup
virtual server takes precedence.

To configure a backup virtual server by using the CLI

At the command prompt, type the following commands to configure a backup server and verify the
configuration:

• <set lb vserver <name> [-backupVserver <string>]

• <show lb vserver <name>

Example

“‘ pre codeblock

set lb vserver vserver-LB-1 -backupVserver vserver-LB-2

Done
show lb vserver vserver-LB-1
vserver-LB-1 (10.102.29.60:80) - HTTP Type: ADDRESS
State: DOWN
Last state change was at Wed Jun 17 08:56:34 2009 (+661 ms)
.
.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 184

NetScaler 12.0

.
Backup: vserver-LB-2
.
.
.
Done

“‘

To set up a backup virtual server by using the GUI

1. <Navigate to Traffic Management > Load Balancing > Virtual Servers.

2. <In the details pane, select the virtual server for which you want to configure the backup virtual
server (for example, vserver-LB-1), and then click Open.
3. <In the Configure Virtual Server (Load Balancing) dialog box, on the Advanced tab, in the Backup
Virtual Server list, select the backup virtual server (for example, vserver-LB-2, and then click OK.
4. <Verify that the backup virtual server you configured appears in the Details section at the bottom
of the pane.
Note: If the primary server goes down and then comes back up, and you want the backup virtual
server to function as the primary server until you explicitly reestablish the primary virtual server,
select the
Disable Primary When Down check box.

1.
2. Citrix ADC
3. NetScaler 12.0

A typical load balancing scenario

January 6, 2019

Contributed by:
C

In a load balancing setup, the NetScaler appliances are logically located between the client and the
server farm, and they manage traffic flow to the servers.

The following figure shows the topology of a basic load balancing configuration.

Figure 1. Basic Load Balancing Topology

© 1999-2018 Citrix Systems, Inc. All rights reserved. 185

NetScaler 12.0

The virtual server selects the service and assigns it to serve client requests. Consider the scenario in
the preceding figure, where the services service-HTTP-1 and service-HTTP-2 are created and bound
to the virtual server named virtual server-LB-1. Virtual server-LB-1 forwards the client request to ei-
ther service-HTTP-1 or service-HTTP-2. The system selects the service for each request by using the
Least Connections load balancing method. The following table lists the names and values of the basic
entities that must be configured on the system.

Table 1. LB Configuration Parameter Values

The following figure shows the load balancing sample values and required parameters that are de-
scribed in the preceding table.

Figure 2. Load Balancing Entity Model

The following tables list the commands used to configure this load balancing setup by using the com-
mand line interface.

Task Command

To enable load balancing enable feature lb

To create a service named service-HTTP-1 add service service-HTTP-1 10.102.29.5 HTTP 80
To create a service named service-HTTP-2 add service service-HTTP-2 10.102.29.6 HTTP
80
To create a virtual server named vserver-LB-1 add lb vserver vserver-LB-1 HTTP 10.102.29.60
80
To bind a service named service-HTTP-1 to a bind lb vserver vserver-LB-1 service-HTTP-1
virtual server named vserver-LB-1
To bind a service named service-HTTP-2 to a bind lb vserver vserver-LB-1 service-HTTP-2
virtual server named vserver-LB-1

Table 2. Initial Configuration Tasks

For more information about the initial configuration tasks, see Setting Up Basic Load Balancing.

Task Command

To view the properties of a virtual server show lb vserver vserver-LB-1

named vserver-LB-1
To view the statistics of a virtual server named stat lb vserver vserver-LB-1
vserver-LB-1
To view the properties of a service named show service service-HTTP-1
service-HTTP-1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 186

NetScaler 12.0

Task Command

To view the statistics of a service named stat service service-HTTP-1

service-HTTP-1
To view the bindings of a service named show service bindings service-HTTP-1
service-HTTP-1

Table 3. Verification Tasks

Task Command

To configure persistence on a virtual server set lb vserver vserver-LB-1 -persistenceType

named vserver-LB-1 SOURCEIP -persistenceMask 255.255.255.255
-timeout 2
To configure COOKIEINSERT persistence on a set lb vserver vserver-LB-1 -persistenceType
virtual server named vserver-LB-1 COOKIEINSERT
To configure URLPassive persistence on a set lb vserver vserver-LB-1 -persistenceType
virtual server named vserver-LB-1 URLPASSIVE
To configure a virtual server to redirect the set lb vserver vserver-LB-1 -redirectURL http:
client request to a URL on a virtual server //www.newdomain.com/mysite/maintenance
named vserver-LB-1
To set a backup virtual server on a virtual set lb vserver vserver-LB-1 -backupVserver
server named vserver-LB-1 vserver-LB-2

Table 4. Customization Tasks

For more information about configuring persistence, see Choosing and Configuring Persistence Set-
tings. For information about configuring a virtual server to redirect a client request to a URL and set-
ting up a backup virtual server, see Configuring Features to Protect the Load Balancing Configuration.

1.
2. Citrix ADC
3. NetScaler 12.0

Accelerate load balanced traffic by using compression

January 6, 2019

© 1999-2018 Citrix Systems, Inc. All rights reserved. 187

NetScaler 12.0

Contributed by:
C

Compression is a popular means of optimizing bandwidth usage, and most web browsers support
compressed data. If you enable the compression feature, the NetScaler appliance intercepts requests
from clients and determines whether the client can accept compressed content. After receiving the
HTTP response from the server, the appliance examines the content to determine whether it is com-
pressible. If the content is compressible, the appliance compresses it, modifies the response header
to indicate the type of compression performed, and forwards the compressed content to the client.

NetScaler compression is a policy-based feature. A policy filters requests and responses to identify re-
sponses to be compressed, and specifies the type of compression to apply to each response. The appli-
ance provides several built-in policies to compress common MIME types such as text/html, text/plain,
text/xml, text/css, text/rtf, application/msword, application/vnd.ms-excel, and application/vnd.ms-
powerpoint. You can also create custom policies. The appliance does not compress compressed MIME
types such as application/octet-stream, binary, bytes, and compressed image formats such as GIF and
JPEG.

To configure compression, you must enable it globally and on each service that will provide responses
that you want compressed. If you have configured virtual servers for load balancing or content switch-
ing, you should bind the polices to the virtual servers. Otherwise, the policies apply to all traffic that
passes through the appliance.

Compression configuration task sequence

The following flow chart shows the sequence of tasks for configuring basic compression in a load bal-
ancing setup.

Figure 1. Sequence of Tasks to Configure Compression

Note: The steps in the above figure assume that load balancing has already been configured.

Enable compression

By default, compression is not enabled. You must enable the compression feature to allow compres-
sion of HTTP responses that are sent to the client.

To enable compression by using the CLI

At the command prompt, type the following commands to enable compression and verify the config-
uration:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 188

NetScaler 12.0

• enable ns feature CMP

• show ns feature

1 > enable ns feature CMP

2
3
4
5
6 Done
7
8
9 > show ns feature
10
11
12
13
14
15 Feature Acronym Status
16
17
18 ------- ------- ------
19
20
21 1) Web Logging WL ON
22
23
24 2) Surge Protection SP OFF
25
26
27 .
28
29
30 7) Compression Control CMP ON
31
32
33 8) Priority Queuing PQ OFF
34
35
36 .
37
38
39 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 189

NetScaler 12.0

To enable compression by using the GUI

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

2. In the details pane, under Modes and Features, click Change basic features.
3. In the Configure Basic Features dialog box, select the Compression check box, and then click OK.
4. In the Enable/Disable Feature(s)? dialog box, click Yes.

Configure services to compress data

In addition to enabling compression globally, you must enable it on each service that will deliver files
to be compressed.

To enable compression on a service by using the CLI

At the command prompt, type the following commands to enable compression on a service and verify
the configuration:

• set service <name> -CMP YES

• show service <name>

1 > show service SVC_HTTP1

2
3
4 SVC_HTTP1 (10.102.29.18:80) - HTTP
5
6
7 State: UP
8
9
10 Last state change was at Tue Jun 16 06:19:14 2009 (+737 ms)
11
12
13 Time since last state change: 0 days, 03:03:37.200
14
15
16 Server Name: 10.102.29.18
17
18
19 Server ID : 0 Monitor Threshold : 0
20
21
22 Max Conn: 0 Max Req: 0 Max Bandwidth: 0 kbits
23

© 1999-2018 Citrix Systems, Inc. All rights reserved. 190

NetScaler 12.0

24
25 Use Source IP: NO
26
27
28 Client Keepalive(CKA): NO
29
30
31 Access Down Service: NO
32
33
34 TCP Buffering(TCPB): NO
35
36
37 HTTP Compression(CMP): YES
38
39
40 Idle timeout: Client: 180 sec Server: 360 sec
41
42
43 Client IP: DISABLED
44
45
46 Cacheable: NO
47
48
49 SC: OFF
50
51
52 SP: OFF
53
54
55 Down state flush: ENABLED
56
57
58
59
60
61 1) Monitor Name: tcp-default
62
63
64 State: DOWN Weight: 1
65
66
67 Probes: 1095 Failed [Total: 1095 Current: 1095]
68

© 1999-2018 Citrix Systems, Inc. All rights reserved. 191

NetScaler 12.0

69
70 Last response: Failure - TCP syn sent, reset received.
71
72
73 Response Time: N/A
74
75
76 Done

To enable compression on a service by using the GUI

1. Navigate to Traffic Management > Load Balancing > Services.

2. In the details pane, select the service for which you want to configure compression (for exam-
ple, service-HTTP-1), and then click Open.
3. On the Advanced tab, under Settings, select the Compression check box, and then click OK.
4. Verify that, when the service is selected, HTTP Compression(CMP): ON appears in the De-
tails section at the bottom of the pane.

Bind a compression policy to a virtual server

If you bind a policy to a virtual server, the policy is evaluated only by the services associated with
that virtual server. You can bind compression policies to a virtual server either from the Configure
Virtual Server (Load Balancing) dialog box or from the Compression Policy Manager dialog box. This
topic includes instructions to bind compression policies to a load balancing virtual server by using
the Configure Virtual Server (Load Balancing) dialog box. For information about how you can bind a
compression policy to a load balancing virtual server by using the Compression Policy Manager dialog
box, see Configuring and Binding Policies with the Policy Manager.

To bind or unbind a compression policy to a virtual server by using the command line

At the command prompt, type the following commands to bind or unbind a compression policy to a
load balancing virtual server and verify the configuration:

(bind unbind) lb vserver <name> -policyName

<string>

• show lb vserver <name>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 192

NetScaler 12.0

Example:

1 bind lb vserver lbvip -policyName ns_cmp_msapp

2 Done
3 > show lb vserver lbvip
4 lbvip (8.7.6.6:80) - HTTP Type: ADDRESS
5 State: UP
6 Last state change was at Thu May 28 05:37:21 2009 (+685 ms)
7 Time since last state change: 19 days, 04:26:50.470
8 Effective State: UP
9 Client Idle Timeout: 180 sec
10 Down state flush: ENABLED
11 Disable Primary Vserver On Down : DISABLED
12 Port Rewrite : DISABLED
13 No. of Bound Services : 1 (Total) 1 (Active)
14 Configured Method: LEASTCONNECTION
15 Current Method: Round Robin, Reason: Bound service’s state changed to
UP
16 Mode: IP
17 Persistence: NONE
18 Vserver IP and Port insertion: OFF
19 Push: DISABLED Push VServer:
20 Push Multi Clients: NO
21 Push Label Rule:
22
23 Bound Service Groups:
24 1) Group Name: Service-Group-1
25
26 1) Service-Group-1 (10.102.29.252: 80) - HTTP State: UP Weight: 1
27
28 1) Policy : ns_cmp_msapp Priority:0
29 Done

To bind or unbind a compression policy to a load balancing virtual server by using the GUI

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.

2. In the details pane, select the virtual server to which you want to bind or unbind a compression
policy (for example, Vserver-LB-1), and then click Open.
3. In the Configure Virtual Server (Load Balancing) dialog box, on the Policies tab, click Compres-
sion.
4. Do one of the following:
• To bind a compression policy, click Insert Policy, and then select the policy you want to
bind to the virtual server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 193

NetScaler 12.0

• To unbind a compression policy, click the name of the policy you want to unbind from the
virtual server, and then click Unbind Policy.
5. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0

Secure load balanced traffic by using SSL

January 6, 2019

Contributed by:
C

The NetScaler SSL offload feature transparently improves the performance of web sites that conduct
SSL transactions. By offloading CPU-intensive SSL encryption and decryption tasks from the local
web server to the appliance, SSL offloading ensures secure delivery of web applications without the
performance penalty incurred when the server processes the SSL data. Once the SSL traffic is de-
crypted, it can be processed by all standard services. The SSL protocol works seamlessly with various
types of HTTP and TCP data and provides a secure channel for transactions using such data.

To configure SSL, you must first enable it. Then, you configure HTTP or TCP services and an SSL virtual
server on the appliance, and bind the services to the virtual server. You must also add a certificate-
key pair and bind it to the SSL virtual server. If you use Outlook Web Access servers, you must create
an action to enable SSL support and a policy to apply the action. An SSL virtual server intercepts
incoming encrypted traffic and decrypts it by using a negotiated algorithm. The SSL virtual server
then forwards the decrypted data to the other entities on the appliance for appropriate processing.

For detailed information about SSL offloading, see SSL offload and acceleration.

SSL configuration task sequence

To configure SSL, you must first enable it. Then, you must create an SSL virtual server and HTTP or TCP
services on the NetScaler appliance. Finally, you must bind a valid SSL certificate and the configured
services to the SSL virtual server.

An SSL virtual server intercepts incoming encrypted traffic and decrypts it using a negotiated algo-
rithm. The SSL virtual server then forwards the decrypted data to the other entities on the NetScaler
appliance for appropriate processing.

The following flow chart shows the sequence of tasks for configuring a basic SSL offload setup.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 194

NetScaler 12.0

Figure 1. Sequence of Tasks to Configure SSL Offloading

Enable SSL offload

You should enable the SSL feature before configuring SSL offload. You can configure SSL-based enti-
ties on the appliance without enabling the SSL feature, but they will not work until you enable SSL.

Eenable SSL by using the CLI

At the command prompt, type the following commands to enable SSL Offload and verify the configu-
ration:

• enable ns feature SSL

• show ns feature

1 > enable ns feature ssl

2
3
4
5
6 Done
7
8
9 > show ns feature
10
11
12 Feature Acronym Status
13
14
15 ------- ------- ------
16
17
18 1) Web Logging WL ON
19
20
21 2) SurgeProtection SP OFF
22
23
24 3) Load Balancing LB ON . . .
25
26
27 9) SSL Offloading SSL ON
28

© 1999-2018 Citrix Systems, Inc. All rights reserved. 195

NetScaler 12.0

29
30 10) Global Server Load Balancing GSLB ON . .
31
32
33 Done >

Enable SSL by using the GUI

Follow thesee steps:

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

2. In the details pane, under Modes and Features, click Change basic features.
3. Select the SSL Offloading check box, and then click OK.
4. In the Enable/Disable Feature(s)? message box, click Yes.

Create HTTP services

A service on the appliance represents an application on a server. Once configured, services are in the
disabled state until the appliance can reach the server on the network and monitor its status. This
topic covers the steps to create an HTTP service.

Note: For TCP traffic, perform the procedures in this and the following topics, but create TCP services
instead of HTTP services.

Add an HTTP service by using the CLI

At the command prompt, type the following commands to add a HTTP service and verify the configu-
ration:

add service <name> (<IP> <serverName>) <serviceType> <port>

•
• show service <name>
Example:

1 > add service SVC_HTTP1 10.102.29.18 HTTP 80

2
3
4 Done
5

© 1999-2018 Citrix Systems, Inc. All rights reserved. 196

NetScaler 12.0

6
7 > show service SVC_HTTP1
8
9
10 SVC_HTTP1 (10.102.29.18:80) - HTTP
11
12
13 State: UP
14
15
16 Last state change was at Wed Jul 15 06:13:05 2009
17
18
19 Time since last state change: 0 days, 00:00:15.350
20
21
22 Server Name: 10.102.29.18
23
24
25 Server ID : 0 Monitor Threshold : 0
26
27
28 Max Conn: 0 Max Req: 0 Max Bandwidth: 0 kbits
29
30
31 Use Source IP: NO
32
33
34 Client Keepalive(CKA): NO
35
36
37 Access Down Service: NO
38
39
40 TCP Buffering(TCPB): NO
41
42
43 HTTP Compression(CMP): YES
44
45
46 Idle timeout: Client: 180 sec Server: 360 sec
47
48
49 Client IP: DISABLED
50

© 1999-2018 Citrix Systems, Inc. All rights reserved. 197

NetScaler 12.0

51
52 Cacheable: NO
53
54
55 SC: OFF
56
57
58 SP: OFF
59
60
61 Down state flush: ENABLED
62
63
64
65
66
67 1) Monitor Name: tcp-default
68
69
70 State: UP Weight: 1
71
72
73 Probes: 4 Failed [Total: 0 Current: 0]
74
75
76 Last response: Success - TCP syn+ack received.
77
78
79 Response Time: N/A
80
81
82 Done

Add an HTTP service by using the GUI

Follow these steps:

1. Navigate to Traffic Management > SSL Offload > Services.

2. In details pane, click Add.
3. In the Create Service dialog box, in the Service Name, Server, and Port text boxes, type the name
of the service, IP address, and port (for example, SVC_HTTP1, 10.102.29.18, and 80).
4. In the Protocol list, select the type of the service (for example, HTTP).

© 1999-2018 Citrix Systems, Inc. All rights reserved. 198

NetScaler 12.0

5. Click Create, and then click Close. The HTTP service you configured appears in the Services
page.
6. Verify that the parameters you configured are correctly configured by selecting the service and
viewing the Details section at the bottom of the pane.

Add an SSL based virtual server

In a basic SSL offloading setup, the SSL virtual server intercepts encrypted traffic, decrypts it, and
sends the clear text messages to the services that are bound to the virtual server. Offloading CPU-
intensive SSL processing to the appliance allows the back-end servers to process a greater number of
requests.

Add an SSL-based virtual server by using the CLI

At the command prompt, type the following commands to create an SSL-based virtual server and
verify the configuration:

• add lb vserver <name> <serviceType> [<IPAddress> <port>]

• show lb vserver <name>
Caution: To ensure secure connections, you must bind a valid SSL certificate to the SSL-based
virtual server before you enable it.

Example:

1 > add lb vserver vserver-SSL-1 SSL 10.102.29.50 443

2
3
4
5
6 Done
7
8
9 > show lb vserver vserver-SSL-1
10
11
12 vserver-SSL-1 (10.102.29.50:443) - SSL Type: ADDRESS
13
14
15 State: DOWN[Certkey not bound] Last state change was at Tue Jun 16
06:33:08 2009 (+176 ms)
16
17
18 Time since last state change: 0 days, 00:03:44.120

© 1999-2018 Citrix Systems, Inc. All rights reserved. 199

NetScaler 12.0

19
20
21 Effective State: DOWN Client Idle Timeout: 180 sec
22
23
24 Down state flush: ENABLED
25
26
27 Disable Primary Vserver On Down : DISABLED
28
29
30 No. of Bound Services : 0 (Total) 0 (Active)
31
32
33 Configured Method: LEASTCONNECTION Mode: IP
34
35
36 Persistence: NONE
37
38
39 Vserver IP and Port insertion: OFF
40
41
42 Push: DISABLED Push VServer: Push Multi Clients: NO Push Label Rule:
Done

Add an SSL-based virtual server by using the GUI

Follow these steps:

1. Navigate to Traffic Management > SSL Offload > Virtual Servers.

2. In the details pane, click Add.
3. In the Create Virtual Server (SSL Offload) dialog box, in the Name, IP Address, and Port text
boxes, type the name of the virtual server, IP address, and port (for example, Vserver-SSL-1,
10.102.29.50, and 443).
4. In the Protocol list, select the type of the virtual server, for example, SSL.
5. Click Create, and then click Close.
6. Verify that the parameters you configured are correctly configured by selecting the virtual server
and viewing the Details section at the bottom of the pane. The virtual server is marked as DOWN
because a certificate-key pair and services have not been bound to it.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 200

NetScaler 12.0

Caution: To ensure secure connections, you must bind a valid SSL certificate to the SSL-based
virtual server before you enable it.

Bind services to the SSL virtual server

After decrypting the incoming data, the SSL virtual server forwards the data to the services that you
have bound to the virtual server.

Data transfer between the appliance and the servers can be encrypted or in clear text. If the data
transfer between the appliance and the servers is encrypted, the entire transaction is secure from
end to end. For more information about configuring the system for end-to-end security, see [sSSL
offload and acceleration.

Bind a service to a virtual server by using the CLI

At the command prompt, type the following commands to bind service to the SSL virtual server and
verify the configuration:

• bind lb vserver <name> <serviceName>

• show lb vserver <name>

Example:

1 > bind lb vserver vserver-SSL-1 SVC_HTTP1

2
3
4
5
6 Done
7
8
9 > show lb vserver vserver-SSL-1 vserver-SSL-1 (10.102.29.50:443) -
SSL Type:
10
11
12 ADDRESS State: DOWN[Certkey not bound]
13
14
15 Last state change was at Tue Jun 16 06:33:08 2009 (+174 ms)
16
17
18 Time since last state change: 0 days, 00:31:53.70
19

© 1999-2018 Citrix Systems, Inc. All rights reserved. 201

NetScaler 12.0

20
21 Effective State: DOWN Client Idle
22
23
24 Timeout: 180 sec
25
26
27 Down state flush: ENABLED Disable Primary Vserver On Down :
28
29
30 DISABLED No. of Bound Services : 1 (Total) 0 (Active)
31
32
33 Configured Method: LEASTCONNECTION Mode: IP Persistence: NONE Vserver
IP and
34
35
36 Port insertion: OFF Push: DISABLED Push VServer: Push Multi Clients:
NO Push Label Rule:
37
38
39
40
41
42 1) SVC_HTTP1 (10.102.29.18: 80) - HTTP
43
44
45 State: DOWN Weight: 1
46
47
48 Done

Bind a service to a virtual server by using the GUI

1. Navigate to Traffic Management > SSL Offload > Virtual Servers.

2. In the details pane, select a virtual server, and then click Open.
3. On the Services tab, in the Active column, select the check boxes next to the services that you
want to bind to the selected virtual server.
4. Click OK.
5. Verify that the Number of Bound Services counter in the Details section at the bottom of the
pane is incremented by the number of services that you bound to the virtual server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 202

NetScaler 12.0

Add a certificate key pair

An SSL certificate is an integral element of the SSL Key-Exchange and encryption/decryption process.
The certificate is used during SSL handshake to establish the identity of the SSL server. You can use
a valid, existing SSL certificate that you have on the NetScaler appliance, or you can create your own
SSL certificate. The appliance supports RSA/DSA certificates of up to 4096 bits.

Note: Citrix recommends that you use a valid SSL certificate that has been issued by a trusted
certificate authority. Invalid certificates and self-created certificates are not compatible with all
SSL clients.

Before a certificate can be used for SSL processing, you must pair it with its corresponding key. The
certificate key pair is then bound to the virtual server and used for SSL processing.

Add a certificate key pair by using the CLI

At the command prompt, type the following commands to create a certificate key pair and verify the
configuration:

• add ssl certKey <certkeyName> -cert <string> [-key <string>]

• show sslcertkey <name>

Example:

1 > add ssl certKey CertKey-SSL-1 -cert ns-root.cert -key ns-root.key

2
3
4
5
6 Done
7
8
9 > show sslcertkey CertKey-SSL-1
10
11
12 Name: CertKey-SSL-1 Status: Valid,
13
14
15 Days to expiration:4811 Version: 3
16
17
18 Serial Number: 00 Signature Algorithm: md5WithRSAEncryption Issuer:
C=US,ST=California,L=San
19
20

© 1999-2018 Citrix Systems, Inc. All rights reserved. 203

NetScaler 12.0

21 Jose,O=Citrix ANG,OU=NS Internal,CN=de fault

22
23
24 Validity Not Before: Oct 6 06:52:07 2006 GMT Not After : Aug 17
21:26:47 2022 GMT
25
26
27 Subject: C=US,ST=California,L=San Jose,O=Citrix ANG,OU=NS Internal,
CN=d efault Public Key
28
29
30 Algorithm: rsaEncryption Public Key
31
32
33 size: 1024
34
35
36 Done

Add a certificate key pair by using the GUI

Follow these steps:

1. Navigate to Traffic Management > SSL > Certificates.

2. In the details pane, click Add.
3. In the Install Certificate dialog box, in the Certificate-Key Pair Name text box, type a name for
the certificate key pair you want to add, for example, Certkey-SSL-1.
4. Under Details, in Certificate File Name, click Browse (Appliance) to locate the certificate. Both
the certificate and the key are stored in the /nsconfig/ssl/ folder on the appliance. To use a
certificate present on the local system, select Local.
5. Select the certificate you want to use, and then click Select.
6. In Private Key File Name, click Browse (Appliance) to locate the private key file. To use a private
key present on the local system, select Local.
7. Select the key you want to use and click Select. To encrypt the key used in the certificate key
pair, type the password to be used for encryption in the Password text box.
8. Click Install.
9. Double-click the certificate key pair and, in the Certificate Details window, verify that the param-
eters have been configured correctly and saved.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 204

NetScaler 12.0

Bind an SSL certificate key pair to the virtual server

After you have paired an SSL certificate with its corresponding key, you must bind the certificate key
pair to the SSL virtual server so that it can be used for SSL processing. Secure sessions require estab-
lishing a connection between the client computer and an SSL-based virtual server on the appliance.
SSL processing is then carried out on the incoming traffic at the virtual server. Therefore, before en-
abling the SSL virtual server on the appliance, you need to bind a valid SSL certificate to the SSL virtual
server.

Bind an SSL certificate key pair to a virtual server by using the CLI

At the command prompt, type the following commands to bind an SSL certificate key pair to a virtual
server and verify the configuration:

• bind ssl vserver <vServerName> -certkeyName <string>

• show ssl vserver <name>

Example:

1 > bind ssl vserver Vserver-SSL-1 -certkeyName CertKey-SSL-1

2
3
4
5
6 Done
7
8
9 > show ssl vserver Vserver-SSL-1
10
11
12
13
14
15 Advanced SSL configuration for VServer Vserver-SSL-1:
16
17
18 DH: DISABLED
19
20
21 Ephemeral RSA: ENABLED Refresh Count: 0
22
23
24 Session Reuse: ENABLED Timeout: 120 seconds
25

© 1999-2018 Citrix Systems, Inc. All rights reserved. 205

NetScaler 12.0

26
27 Cipher Redirect: ENABLED
28
29
30 SSLv2 Redirect: ENABLED
31
32
33 ClearText Port: 0
34
35
36 Client Auth: DISABLED
37
38
39 SSL Redirect: DISABLED
40
41
42 Non FIPS Ciphers: DISABLED
43
44
45 SSLv2: DISABLED SSLv3: ENABLED TLSv1: ENABLED
46
47
48
49
50
51 1) CertKey Name: CertKey-SSL-1 Server Certificate
52
53
54 1) Cipher Name: DEFAULT
55
56
57 Description: Predefined Cipher Alias
58
59
60 Done

Bind an SSL certificate key pair to a virtual server by using the GUI

Follow these steps:

1. Navigate to Traffic Management > SSL Offload > Virtual Servers.

2. Select the virtual server to which you want to bind the certificate key pair, for example, Vserver-
SSL-1, and click Open.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 206

NetScaler 12.0

3. In the Configure Virtual Server (SSL Offload) dialog box, on the SSL Settings tab, under Available,
select the certificate key pair that you want to bind to the virtual server (for example, Certkey-
SSL-1), and then click Add.
4. Click OK.
5. Verify that the certificate key pair that you selected appears in the Configured area.

Configure support for Outlook web access

If you use Outlook Web Access (OWA) servers on your NetScaler appliance, you must configure the
appliance to insert a special header field, FRONT-END-HTTPS: ON, in HTTP requests directed to the
OWA servers, so that the servers generate URL links as https:// instead of http://.

Note: You can enable OWA support for HTTP-based SSL virtual servers and services only. You cannot
apply it for TCP-based SSL virtual servers and services.

To configure OWA support, do the following:

• Create an SSL action to enable OWA support.

• Create an SSL policy.
• Bind the policy to the SSL virtual server.

Create an SSL action to enable OWA support

Before you can enable Outlook Web Access (OWA) support, you must create an SSL action. SSL actions
are bound to SSL policies and triggered when incoming data matches the rule specified by the policy.

Create an SSL action to enable OWA support by using the CLI

At the command prompt, type the following commands to create an SSL action to enable OWA support
and verify the configuration:

• add ssl action <name> -OWASupport ENABLED

• show SSL action <name>

Example:

1 > add ssl action Action-SSL-OWA -OWASupport enabled

2
3
4
5
6 Done
7

© 1999-2018 Citrix Systems, Inc. All rights reserved. 207

NetScaler 12.0

8
9 > show SSL action Action-SSL-OWA
10
11
12 Name: Action-SSL-OWA
13
14
15 Data Insertion Action: OWA
16
17
18 Support: ENABLED
19
20
21 Done

Create an SSL action to enable OWA support by using the GUI

Follow these steps:

1. Navigate to Traffic Management > SSL > Policies.

2. In the details pane, on the Actions tab, click Add.
3. In the Create SSL Action dialog box, in the Name text box, type Action-SSL-OWA.
4. Under Outlook Web Access, select Enabled.
5. Click Create, and then click Close.
6. Verify that Action-SSL-OWA appears in the SSL Actions page.

Create SSL policies

SSL policies are created by using the policy infrastructure. Each SSL policy has an SSL action bound
to it, and the action is carried out when incoming traffic matches the rule that has been configured in
the policy.

Create an SSL policy by using the CLI

At the command prompt, type the following commands to configure an SSL policy and verify the con-
figuration:

• add ssl policy <name> -rule <expression> -reqAction <string>

• show ssl policy <name>

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 208

NetScaler 12.0

1 > add ssl policy Policy-SSL-1 -rule ns_true -reqaction Action-SSL-OWA

2
3 Done
4
5 > show ssl policy Policy-SSL-1
6
7 Name: Policy-SSL-1 Rule: ns_true
8
9 Action: Action-SSL-OWA Hits: 0
10
11 Policy is bound to following entities
12
13 1) PRIORITY : 0
14
15 Done

Create an SSL policy by using the GUI

Follow these steps:

1. Navigate to Traffic Management > SSL > Policies.

2. In the details pane, click Add.
3. In the Create SSL Policy dialog box, in the Name text box, type the name of the SSL Policy (for
example, Policy-SSL-1).
4. In Request Action, select the configured SSL action that you want to associate with this policy
(for example, Action-SSL-OWA). The ns_true general expression applies the policy to all success-
ful SSL handshake traffic. However, if you need to filter specific responses, you can create poli-
cies with a higher level of detail. For more information about configuring granular policy expres-
sions, see [SSL actions and policies](/en-us/netscaler/12/ssl/ssl-actions-and-policies.html0.
5. In Named Expressions, choose the built-in general expression ns_true and click Add Expression.
The expression ns_true now appears in the Expression text box.
6. Click Create, and then click Close.
7. Verify that the policy is correctly configured by selecting the policy and viewing the Details sec-
tion at the bottom of the pane.

Bind the SSL policy to the SSL virtual server

After you configure an SSL policy for Outlook Web Access, bind the policy to a virtual server that will
intercept incoming Outlook traffic. If the incoming data matches any of the rules configured in the
SSL policy, the policy is triggered and the action associated with it is carried out.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 209

NetScaler 12.0

Bind an SSL policy to an SSL virtual server by using the CLI

At the command prompt, type the following commands to bind an SSL policy to an SSL virtual server
and verify the configuration:

• bind ssl vserver <vServerName> -policyName <string>

• show ssl vserver <name>

Example:

1 > bind ssl vserver Vserver-SSL-1 -policyName Policy-SSL-1

2
3 Done
4
5 > show ssl vserver Vserver-SSL-1
6
7 Advanced SSL configuration for VServer Vserver-SSL-1:
8
9 DH: DISABLED
10
11 Ephemeral RSA: ENABLED
12
13 Refresh Count: 0
14
15 Session Reuse: ENABLED
16
17 Timeout: 120 seconds
18
19 Cipher Redirect: ENABLED
20
21 SSLv2 Redirect: ENABLED
22
23 ClearText Port: 0
24
25 Client Auth: DISABLED
26
27 SSL Redirect: DISABLED
28
29 Non FIPS Ciphers: DISABLED
30
31 SSLv2: DISABLED SSLv3: ENABLED TLSv1: ENABLED
32
33 1) CertKey Name: CertKey-SSL-1 Server Certificate
34
35 1) Policy Name: Policy-SSL-1 Priority: 0
36

© 1999-2018 Citrix Systems, Inc. All rights reserved. 210

NetScaler 12.0

37 1) Cipher Name: DEFAULT Description: Predefined Cipher Alias

38
39 Done

Bind an SSL policy to an SSL virtual server by using the GUI

Follow these steps:

1. Navigate to Traffic Management > SSL Offload > Virtual Servers.

2. In the details pane, select the virtual server (for example, Vserver-SSL-1), and then click Open.
3. In the Configure Virtual Server (SSL Offload) dialog box, click Insert Policy, and then select the
policy that you want to bind to the SSL virtual server. Optionally, you can double-click the Pri-
ority field and type a new priority level.
4. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0

Features at a glance

December 28, 2018

Contributed by:
C

NetScaler features can be configured independently or in combinations to address specific needs.

Although some features fit more than one category, the numerous NetScaler features can generally
be categorized as application switching and traffic management features, application acceleration
features, and application security and firewall features, and an application visibility feature.

To understand the order in which the features perform their processing, see Processing Order of Fea-
tures section.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 211

NetScaler 12.0

Application switching and traffic management features

December 28, 2018

Contributed by:
C

Below are the application switching and traffic management features.

SSL Offloading

Transparently offloads SSL encryption and decryption from web servers, freeing server resources to
service content requests. SSL places a heavy burden on an application’s performance and can render
many optimization measures ineffective. SSL offload and acceleration allow all the benefits of Citrix
Request Switching technology to be applied to SSL traffic, ensuring secure delivery of web applica-
tions without degrading end-user performance.

For more information, see SSL offload and acceleration.

Access Control Lists

Compares incoming packets to Access Control Lists (ACLs). If a packet matches an ACL rule, the action
specified in the rule is applied to the packet. Otherwise, the default action (ALLOW) is applied and
the packet is processed normally. For the appliance to compare incoming packets to the ACLs, you
have to apply the ACLs. All ACLs are enabled by default, but you have to apply them in order for the
NetScaler appliance to compare incoming packets against them. If an ACL is not required to be a part
of the lookup table, but still needs to be retained in the configuration, it should be disabled before the
ACLs are applied. An ADC appliance does not compare incoming packets to disabled ACLs.

For more information, see Access Control List.

Load Balancing

Load balancing decisions are based on a variety of algorithms, including round robin, least connec-
tions, weighted least bandwidth, weighted least packets, minimum response time, and hashing based
on URL, domain source IP, or destination IP. Both the TCP and UDP protocols are supported, so the
NetScaler appliance can load balance all traffic that uses those protocols as the underlying carrier (for
example, HTTP, HTTPS, UDP, DNS, NNTP, and general firewall traffic). In addition, the ADC appliance
can maintain session persistence based on source IP, cookie, server, group, or SSL session. It allows

© 1999-2018 Citrix Systems, Inc. All rights reserved. 212

NetScaler 12.0

users to apply custom Extended Content Verification (ECV) to servers, caches, firewalls and other in-
frastructure devices to ensure that these systems are functioning properly and are providing the right
content to users. It can also perform health checks using ping, TCP, or HTTP URL, and the user can
create monitors based on Perl scripts.
To provide high-scale WAN optimization, the CloudBridge appliances deployed at data centers can be
load balanced through NetScaler appliances. The bandwidth and number of concurrent sessions can
be improved significantly.

For more information, see Load Balancing.

Traffic Domains

Traffic domains provide a way to create logical ADC partitions within a single NetScaler appliance.
They enable you to segment network traffic for different applications. You can use traffic domains
to create multiple isolated environments whose resources do not interact with each other. An appli-
cation belonging to a specific traffic domain communicates only with entities, and processes traffic,
within that domain. Traffic belonging to one traffic domain cannot cross the boundary of another traf-
fic domain. Therefore, you can use duplicate IP addresses on the appliance as long as an addresses is
not duplicated within the same domain.

For more information, see Traffic Domains.

Network Address Translation

Network address translation (NAT) involves modification of the source and/or destination IP ad-
dresses, and/or the TCP/UDP port numbers, of IP packets that pass through the NetScaler appliance.
Enabling NAT on the appliance enhances the security of your private network, and protects it from
a public network such as the Internet, by modifying your network’s source IP addresses when data
passes through the NetScaler appliance.

The NetScaler appliance supports the following types of network address translation:

INAT: In Inbound NAT (INAT), an IP address (usually public) configured on the NetScaler appliance lis-
tens to connection requests on behalf of a server. For a request packet received by the appliance on a
public IP address, the ADC replaces the destination IP address with the private IP address of the server.
In other words, the appliance acts as a proxy between clients and the server. INAT configuration in-
volves INAT rules, which define a 1:1 relationship between the IP address on the NetScaler appliance
and the IP address of the server.

RNAT: In Reverse Network Address Translation (RNAT), for a session initiated by a server, the NetScaler
appliance replaces the source IP address in the packets generated by the server with an IP address
(type SNIP) configured on the appliance. The appliance thereby prevents exposure of the server’s IP

© 1999-2018 Citrix Systems, Inc. All rights reserved. 213

NetScaler 12.0

address in any of the packets generated by the server. An RNAT configuration involves an RNAT rule,
which specifies a condition. The appliance performs RNAT processing on those packets that match
the condition.

Stateless NAT46 Translation: Stateless NAT46 enables communication between IPv4 and IPv6 net-
works, by way of IPv4 to IPv6 packet translation and vice versa, without maintaining any session infor-
mation on the NetScaler appliance. A stateless NAT46 configuration involves an IPv4-IPv6 INAT rule
and an NAT46 IPv6 prefix.

Stateful NAT64 Translation: The stateful NAT64 feature enables communication between IPv4 clients
and IPv6 servers through IPv6 to IPv4 packet translation, and vice versa, while maintaining session
information on the NetScaler appliance. A stateful NAT64 configuration involves an NAT64 rule and
an NAT64 IPv6 prefix.

For more information, see

Configuring Network Address Translation.

Multipath TCP Support

NetScaler appliances support Multipath TCP (MPTCP). MPTCP is a TCP/IP protocol extension that iden-
tifies and uses multiple paths available between hosts to maintain the TCP session. You must enable
MPTCP on a TCP profile and bind it to a virtual server. When MPTCP is enabled, the virtual server func-
tions as an MPTCP gateway and converts MPTCP connections with the clients to TCP connections that
it maintains with the servers.

For more information, see MPTCP (Multi-Path TCP).

Content Switching

Determines the server to which to send the request on the basis of configured content switching poli-
cies. Policy rules can be based on the IP address, URL, and HTTP headers. This allows switching de-
cisions to be based on user and device characteristics such as who the user is, what type of agent is
being used, and what content the user requested.

For more information, see Content Switching.

Global Server Load Balancing (GSLB)

Extends the traffic management capabilities of a NetScaler to include distributed Internet sites and
global enterprises. Whether installations are spread across multiple network locations or multiple
clusters in a single location, the NetScaler maintains availability and distributes traffic across them. It
makes intelligent DNS decisions to prevent users from being sent to a site that is down or overloaded.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 214

NetScaler 12.0

When the proximity-based GSLB method is enabled, the NetScaler can make load balancing decisions
based on the proximity of the client’s local DNS server (LDNS) in relation to different sites. The main
benefit of the proximity-based GSLB method is faster response time resulting from the selection of
the closest available site.

For more information, see Global Server Load Balancing.

Dynamic Routing

Enables routers to obtain topology information, routes, and IP addresses from neighboring routers
automatically. When dynamic routing is enabled, the corresponding routing process listens to route
updates and advertises routes. The routing processes can also be placed in passive mode. Routing
protocols enable an upstream router to load balance traffic to identical virtual servers hosted on two
standalone NetScaler units using the Equal Cost Multipath technique.

For more information, see Configuring Dynamic Routes.

Link Load Balancing

Load balances multiple WAN links and provides link failover, further optimizing network performance
and ensuring business continuity. Ensures that network connections remain highly available, by
applying intelligent traffic control and health checks to distribute traffic efficiently across upstream
routers. Identifies the best WAN link to route both incoming and outbound traffic based on policies
and network conditions, and protects applications against WAN or Internet link failure by providing
rapid fault detection and failover.

1 For more information, see [Link Load Balancing](/en-us/netscaler/12/

link-load-balancing.html).

TCP Optimization

You can use TCP profiles to optimize TCP traffic. TCP profiles define the way that NetScaler virtual
servers process TCP traffic. Administrators can use the built-in TCP profiles or configure custom pro-
files. After defining a TCP profile, you can bind it to a single virtual server or to multiple virtual servers.

Some of the key optimization features that can be enabled by TCP profiles are:

• TCP keep-alive—Checks the operational status of the peers at specified time intervals to prevent
the link from being broken.
• Selective Acknowledgment (SACK)— Improves the performance of data transmission, especially
in long fat networks (LFNs).

© 1999-2018 Citrix Systems, Inc. All rights reserved. 215

NetScaler 12.0

• TCP window scaling— Allows efficient transfer of data over long fat networks (LFNs).

For more information on TCP Profiles, see Configuring TCP Profiles.

CloudBridge Connector

The Citrix NetScaler CloudBridge

Connector feature, a fundamental part of the Citrix OpenCloud framework, is a tool used to build a
cloud-extended data center. The OpenCloud Bridge enables you to connect one or more NetScaler
appliances or NetScaler virtual appliances on the cloud-to your network without reconfiguring your
network. Cloud hosted applications appear as though they are running on one contiguous enterprise
network. The primary purpose of the OpenCloud Bridge is to enable companies to move their appli-
cations to the cloud while reducing costs and the risk of application failure. In addition, the Open-
Cloud Bridge increases network security in cloud environments. An OpenCloud Bridge is a Layer-2
network bridge that connects a NetScaler appliance or NetScaler virtual appliance on a cloud instance
to a NetScaler appliance or NetScaler virtual appliance on your LAN. The connection is made through
a tunnel that uses the Generic Routing Encapsulation (GRE) protocol. The GRE protocol provides a
mechanism for encapsulating packets from a wide variety of network protocols to be forwarded over
another protocol. Then Internet Protocol security (IPsec) protocol suite is used to secure the commu-
nication between the peers in the OpenCloud Bridge.

For more information, see CloudBridge.

DataStream

The NetScaler DataStream feature provides an intelligent mechanism for request switching at the
database layer by distributing requests on the basis of the SQL query being sent.

When deployed in front of database servers, a NetScaler ensures optimal distribution of traffic from
the application servers and Web servers. Administrators can segment traffic according to information
in the SQL query and on the basis of database names, user names, character sets, and packet size.

You can configure load balancing to switch requests according to load balancing algorithms, or you
can elaborate the switching criteria by configuring content switching to make a decision based on SQL
query parameters, such as user name, database names, and command parameters. You can further
configure monitors to track the states of database servers.

The advanced policy infrastructure on the NetScaler appliance includes expressions that you can
use to evaluate and process the requests. The advanced expressions evaluate traffic associated
with MySQL database servers. You can use request-based expressions (expressions that begin with
MYSQL.CLIENT and MYSQL.REQ) in advanced policies to make request switching decisions at the

© 1999-2018 Citrix Systems, Inc. All rights reserved. 216

NetScaler 12.0

content switching virtual server bind point and response-based expressions (expressions that begin
with MYSQL.RES) to evaluate server responses to user-configured health monitors.

Note: DataStream is supported for MySQL and MS SQL databases.

For more information, see DataStream.

1.
2. Citrix ADC
3. NetScaler 12.0

Application acceleration features

December 28, 2018

Contributed by:
C
• AppCompress
Uses the gzip compression protocol to provide transparent compression for HTML and text files.
The typical 4:1 compression ratio yields up to 50% reduction in bandwidth requirements out
of the data center. It also results in significantly improved end-user response time, because it
reduces the amount of data that must be delivered to the user’s browser.
• Cache Redirection
Manages the flow of traffic to a reverse proxy, transparent proxy, or forward proxy cache farm. In-
spects all requests, and identifies non-cacheable requests and sends them directly to the origin
servers over persistent connections. By intelligently redirecting non-cacheable requests back
to the origin web servers, the NetScaler appliance frees cache resources and increases cache hit
rates while reducing overall bandwidth consumption and response delays for these requests.
For more information, see “Cache Redirection.”
• AppCache
Helps optimize web content and application data delivery by providing a fast in-memory
HTTP/1.1 and HTTP/1.0 compliant web caching for both static and dynamic content. This
on-board cache stores the results of incoming application requests even when an incoming
request is secured or the data compressed, and then reuses the data to fulfill subsequent
requests for the same information. By serving data directly from the on-board cache, the
appliance can reduce page regeneration times by eliminating the need to funnel static and
dynamic content requests to the server.
For more information, see “Integrated Caching.”

© 1999-2018 Citrix Systems, Inc. All rights reserved. 217

NetScaler 12.0

• TCP Buffering

Buffers the server’s response and delivers it to the client at the client’s speed, thus offloading
the server faster and thereby improving the performance of web sites.

1.
2. Citrix ADC
3. NetScaler 12.0

Application security and firewall features

December 28, 2018

Contributed by:
C

Below are the secuirty and firewarall features.

Denial of service (DoS) attack defense

Detects and stops malicious distributed denial-of-service (DDoS) attacks and other types of malicious
attacks before they reach your servers, preventing them from affecting network and application per-
formance. The NetScaler appliance identifies legitimate clients and elevates their priority, leaving
suspect clients unable to consume a disproportionate percentage of resources and cripple your site.
The appliance provides application-level protection from the following types of malicious attacks:

• SYN flood attacks

• Pipeline attacks
• Teardrop attacks
• Land attacks
• Fraggle attacks
• Zombie connection attacks

The appliance aggressively defends against these types of attacks by preventing the allocation of
server resources for these connections. This insulates servers from the overwhelming flood of packets
associated with these events.

The appliance also protects network resources from ICMP based attacks by using ICMP rate limiting
and aggressive ICMP packet inspection. It performs strong IP reassembly, drops a variety of suspicious
and malformed packets, and applies Access Control Lists (ACLs) to site traffic for further protection.

For more information, see HTTP Denial-of-Service Protection.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 218

NetScaler 12.0

Content Filtering

Provides protection from malicious attacks for web sites at the Layer 7 level. The appliance inspects
each incoming request according to user-configured rules based on HTTP headers, and performs the
action the user configured. Actions can include resetting the connection, dropping the request, or
sending an error message to the user’s browser. This allows the appliance to screen unwanted re-
quests and reduces your servers’ exposure to attacks.

This feature can also analyze HTTP GET and POST requests and filter out known bad signatures, al-
lowing it to defend your servers against HTTP-based attacks.

For more information, see Content Filtering.

Responder

Functions like an advanced filter and can be used to generate responses from the appliance to
the client. Some common uses of this feature are generation of redirect responses, user defined
responses, and resets.

For more information, see Responder.

Rewrite

Modifies HTTP headers and body text. You can use the rewrite feature to add HTTP headers to an HTTP
request or response, make modifications to individual HTTP headers, or delete HTTP headers. It also
enables you to modify the HTTP body in requests and responses.

When the appliance receives a request or sends a response, it checks for rewrite rules, and if applicable
rules exist, it applies them to the request or response before passing it on to the web server or client
computer.

For more information, see Rewrite.

Priority Queuing

Prioritizes user requests to ensure that the most important traffic is serviced first during surges in
request volume. You can establish priority based on request URLs, cookies, or a variety of other fac-
tors. The appliance places requests in a three-tier queue based on their configured priority, enabling
business-critical transactions to flow smoothly even during surges or site attacks.

For more information, see Priority Queuing.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 219

NetScaler 12.0

Surge Protection

Regulates the flow of user requests to servers and controls the number of users that can simultane-
ously access the resources on the servers, queuing any additional requests once your servers have
reached their capacity. By controlling the rate at which connections can be established, the appliance
blocks surges in requests from being passed on to your servers, thus preventing site overload.

For more information, see Surge Protection.

Citrix Gateway

1 Citrix Gateway is a secure application access solution that provides

administrators granular application-level policy and action controls
to secure access to applications and data while allowing users to
work from anywhere. It gives IT administrators a single point of
control and tools to help ensure compliance with regulations and the
highest levels of information security across and outside the
enterprise. At the same time, it empowers users with a single point
of access — optimized for roles, devices, and networks — to the
enterprise applications and data they need. This unique combination
of capabilities helps maximize the productivity of today’s mobile
workforce.
2
3 For more information, see [Citrix Gateway](https://docs.citrix.com/en-
us/netscaler-gateway.html).

Application Firewall

Protects applications from misuse by hackers and malware, such as cross site scripting attacks, buffer
overflow attacks, SQL injection attacks, and forceful browsing, by filtering traffic between each pro-
tected web server and users that connect to any web site on that web server. The application firewall
examines all traffic for evidence of attacks on web server security or misuse of web server resources,
and takes the appropriate action to prevent these attacks from succeeding.

For more information, see Application Firewall.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 220

NetScaler 12.0

Application visibility feature

December 28, 2018

Contributed by:
C

• NetScaler Insight Center

NetScaler Insight Center is a high performance collector that provides end-to-end user experi-
ence visibility across Web and HDX (ICA) traffic. It collects HTTP and ICA AppFlow records gen-
erated by NetScaler ADC appliances and populates analytical reports covering Layer 3 to Layer
7 statistics. NetScaler Insight Center provides in-depth analysis for the last five minutes of real-
time data, and for historical data collected for the last one hour, one day, one week, and one
month.
HDX (ICA) analytic dashboard enables you to drill down from HDX Users, Applications, Desktops,
and even from gateway-level information. Similarly, HTTP analytics provide a bird’s eye view
of Web Applications, URLs Accessed, Client IP Addresses and Server IP Addresses, and other
dashboards. The administrator can drill down and identify the pain points from any of these
dashboards, as appropriate for the use case.

• EdgeSight for NetScaler

Support for application performance monitoring based on end user experience. This solution
leverages the HTML injection feature to obtain various time values, which are used by EdgeSight
server for analysis and report generation. EdgeSight for NetScaler provides a way to monitor the
performance benefits of a NetScaler and determine potential bottlenecks in a network.

For more information, see “EdgeSight Monitoring for NetScaler.”

• Enhanced Application Visibility Using AppFlow

The NetScaler appliance is a central point of control for all application traffic in the data center.
It collects flow and user-session level information valuable for application performance mon-
itoring, analytics, and business intelligence applications. AppFlow transmits this information
by using the Internet Protocol Flow Information eXport (IPFIX) format, which is an open Inter-
net Engineering Task Force (IETF) standard defined in RFC 5101. IPFIX (the standardized version
of Cisco’s NetFlow) is widely used to monitor network flow information. AppFlow defines new
Information Elements to represent application-level information.

Using UDP as the transport protocol, AppFlow transmits the collected data, called flow records,
to one or more IPv4 collectors. The collectors aggregate the flow records and generate real-time
or historical reports.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 221

NetScaler 12.0

AppFlow provides visibility at the transaction level for HTTP, SSL, TCP, and SSL_TCP flows. You
can sample and filter the flow types that you want to monitor.

To limit the types of flows to monitor, by sampling and filtering the application traffic, you can
enable AppFlow for a virtual server. AppFlow can also provide statistics for the virtual server.

You can also enable AppFlow for a specific service, representing an application server, and mon-
itor the traffic to that application server.

For more information, see “AppFlow.”

• Stream Analytics

The performance of your web site or application depends on how well you optimize the delivery
of the most frequently requested content. Techniques such as caching and compression help ac-
celerate the delivery of services to clients, but you need to be able to identify the resources that
are requested most frequently, and then cache or compress those resources. You can identify
the most frequently used resources by aggregating real-time statistics about website or applica-
tion traffic. Statistics such as how frequently a resource is accessed relative to other resources
and how much bandwidth is consumed by those resources help you determine whether those
resources need to be cached or compressed to improve server performance and network uti-
lization. Statistics such as response times and the number of concurrent connections to the
application help you determine whether you must enhance server-side resources.

If the web site or application does not change frequently, you can use products that collect
statistical data, and then manually analyze the statistics and optimize the delivery of content.
However, if you do not want to perform manual optimizations, or if your web site or applica-
tion is dynamic in nature, you need infrastructure that can not only collect statistical data but
can also automatically optimize the delivery of resources on the basis of the statistics. On the
NetScaler appliance, this functionality is provided by the Stream Analytics feature. The feature
operates on a single NetScaler appliance and collects run-time statistics on the basis of crite-
ria that you define. When used with NetScaler policies, the feature also provides you with the
infrastructure that you need for automatic, real-time traffic optimization.

For more information, see “Action Analytics.”

1.
2. Citrix ADC
3. NetScaler 12.0

FAQs

September 17, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 222

NetScaler 12.0

Contributed by:
C

This section provides the frequently asked questions on the following NetScaler
features

• Admin Partition
• AppFlow
• Call Home
• Clustering
• Connection Management
• Content Switching
• Debugging
• Hardware
• High Availability
• Integrated Caching
• Installing, Upgrading, and Downgrading
• Load Balancing
• NetScaler GUI
• SSL

1.
2. Citrix ADC
3. NetScaler 12.0

AppFlow

September 25, 2018

Contributed by:
C

• Which build of NetScaler supports AppFlow?

AppFlow is supported on NetScaler appliances running version 9.3 and above with nCore build.

• What is the format used by AppFlow to transmit data?

AppFlow transmits information in the Internet Protocol Flow Information eXport (IPFIX) format,
which is an open Internet Engineering Task Force (IETF) standard defined in RFC 5101. IPFIX (the
standardized version of Cisco’s NetFlow) is widely used to monitor network flow information.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 223

NetScaler 12.0

• What do AppFlow records contain?

AppFlow records contain standard NetFlow or IPFIX information, such as time stamps for the
beginning and end of a flow, packet count, and byte count. AppFlow records also contain
application-level information (such as HTTP URLs, HTTP request methods and response-status
codes, server response time, and latency). IPFIX flow records are based on templates that must
be sent before sending flow records.
• After an upgrade to NetScaler Version 9.3 Build 48.6 Cl, why does an attempt to open a vir-
tual server from the GUI result in the error message “The AppFlow feature is only available
on Citrix Netscaler Ncore”?
AppFlow is supported only on nCore appliances. When you open the virtual server configuration
tab, clear the AppFlow checkbox.
• What does the transaction ID in an AppFlow records contain?
A transaction ID is an unsigned 32-bit number identifying an application-level transaction. For
HTTP, a transaction corresponds to a request and response pair. All flow records that corre-
spond to this request and response pair have the same transaction ID. A typical transaction has
four uniflow records. If the NetScaler generates the response by itself (served from the inte-
grated cache or by a security policy), there might be only two flow records for the transaction.
• What is an AppFlow action ?
An Appflow action is a set of collectors to which the flow records are sent if the associated
AppFlow policy matches.
• What commands can I run on the NetScaler appliance to verify that the AppFlow action is
a hit?
The show appflow action. For example:

1 > show appflow action

2 1) Name: aFL-act-collector-1
3 Collectors: collector-1
4 Hits: 0
5 Action Reference Count: 2
6 2) Name: apfl-act-collector-2-and-3
7 Collectors: collector-2, collecter-3
8 Hits: 0
9 Action Reference Count: 1
10 3) Name: apfl-act-collector-1-and-3
11 Collectors: collector-1, collecter-3
12 Hits: 0
13 Action Reference Count: 1

• What is an AppFlow collector?

© 1999-2018 Citrix Systems, Inc. All rights reserved. 224

NetScaler 12.0

A collector receives flow records generated by the NetScaler appliance. To be able to send flow
records, you must specify at least one collector. You can specify up to four. You can remove unused
collectors.

• What NetScaler verison is required for using AppFlow?

Use NetScaler version 9.3.49.5 or higher, and remember that AppFlow is available in only the
nCore builds.

• What transport protocol does AppFlow use?

AppFlow uses UDP as the transport protocol.

• What ports needs to be opened if I have a firewall in the network?

Port 4739. It is the default UDP port the AppFlow collector uses for listening on IPFIX messages.
If the user changes the default port, that port should be opened on the firewall.

• How can I change the default port AppFlow uses?

When you add an AppFlow collector by using the add appflowCollector command, you can spec-
ify the port to be used.

1 > add appflowCollector coll1 -IPAddress 10.102.29.251 -port 8000

2 Done

• What does setting clientTrafficOnly do?

NetScaler generates AppFlow records only for client-side traffic.

• How many collectors can be configured at a time?

You can configure up to four AppFlow collectors at a time on the NetScaler appliance. Please
note that the maximum number of collectors that can be configured on a NetScaler appliance
is four.

1.
2. Citrix ADC
3. NetScaler 12.0

Call Home

September 25, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 225

NetScaler 12.0

• What is Call Home on a NetScaler appliance?

Call Home monitors, and notifies critical events on a NetScaler appliance. By enabling Call
Home, you can automate the error notification process. You not only avoid calling Citrix sup-
port, raise a service request, and upload system data before Citrix support can troubleshoot the
issue, but also identify and resolve issues before it occurs.

• Is Call Home enabled by default on a NetScaler appliance?

Yes, Call Home is enabled by default on the appliance. If you upgrade to the latest software from
an older version where Call Home was disabled by default, the upgrade process automatically
enables the feature. If you later choose to disable it, the updated setting is remembered for all
further upgrades. For information, see Call Home.

• What are the pre-requisites for Call Home to work?

Access to an Internet connection.

Note: If your NetScaler appliance does not have an Internet connectivity, you can configure
a proxy server through which NetScaler can generate system logs and upload it to the Citrix
Technical Support server (CIS).

• What are the benefits of using Call Home?

– Monitor hardware and software error conditions.

– Notify about the occurrence of critical events that impact your network.
– Send performance data and system logs to Citrix to:
* Analyze and improve product quality.
* Provide real-time troubleshooting information for proactive issue identification, and
faster issue resolution.

• Which release of NetScaler software supports Call Home?

NetScaler release 10.0 and later.

• What NetScaler platform models support Call Home?

Call Home feature is enabled by default on all NetScaler platforms and all appliance models
(MPX, VPX, and SDX).

– NetScaler MPX: All MPX models.

– NetScaler VPX: All VPX models. In addition, it is supported on VPX appliances that obtain
their licenses from external or central licensing pools. However, the feature remains same
as for a standard VPX appliance.
– NetScaler SDX: Monitors the disk drive and assigned SSL chips for any errors or failures.
The VPX instances, however, do not have access to the Power Supply Unit (PSU) and there-
fore their status is not monitored. In an SDX platform, you can configure Call Home either
directly on an individual instance or through the SVM.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 226

NetScaler 12.0

• Should I configure SNMP alarm for Call Home to notify error conditions?

No, you need not configure SNMP for Call Home to monitor error conditions, because SNMP
and Call Home uploads are independent of each other. If you want to be notified each time
an error condition occurs, you can configure the CALLHOME-UPLOAD-EVENT SNMP alarm to
generate an SNMP alert whenever a Call Home upload happens. The SNMP alert notifies the
local administrator about the occurrences of critical events.

• How do I contact a technical support?

For all critical hardware-related events, Call Home automatically creates a service request to
Citrix. For other errors, after you review the system logs, you can contact the Citrix Technical
Support team to open a service request for further investigation. For more information, see
http://support.citrix.com/article/CTX126172.

• What error conditions does Call Home monitor in a NetScaler appliance?

Call Home supports monitoring of the following events in a NetScaler appliance:

– Compact flash drive errors

– Hard disk drive errors
– Power supply unit failure
– SSL card failure
– Warm restart
– Memory anomalies
– Rate limit drops

• Do you need a separate license for Call Home?

No, Call Home does not require a separate license. You can enable it in all NetScaler platform
licenses.

• What data does Call Home send to Citrix Support server and how frequently is it sent?

Call Home collects and sends two types of data to CIS. They are:

– Basic System information (running NetScaler version, deployment mode (standalone, HA,
cluster), hardware details and so on). It is sent at the time of Call Home registration and
as part of periodic heartbeats. The heartbeat is sent once every 30 days, but you can con-
figure this interval anywhere from 1 to 30 days. However, a value of less than 5 days is not
recommended, because frequent uploads are usually not very useful.
– An abbreviated version of show tech support bundle when there is an error condition. It is
sent upon the first occurrence of a particular error condition since the appliance was last
started. That is, a reoccurrence of same error condition does not trigger another upload
unless the appliance was rebooted after the previous occurrence.

• Can Call Home generate and upload system logs through a proxy server?

© 1999-2018 Citrix Systems, Inc. All rights reserved. 227

NetScaler 12.0

Yes. If your NetScaler appliance does not have direct Internet connectivity, you can configure a
proxy server and upload system logs to Citrix Technical Support server (CIS).

• Can I review Call Home data before it is sent to CIS?

Unfortunately, you cannot review Call Home data before it is sent to CIS. Call Home does not col-
lect any other data in addition to the data that you will provide when contacting Citrix support
team.

• How secure and private are the Call Home uploads?

Call Home provides data security and privacy in the following ways:

– Uses a secure SSL/TLS channel to transfer data to Citrix servers.

– Uploaded data is reviewed only by authorized personnel and is not shared with any third
party.

1.
2. Citrix ADC
3. NetScaler 12.0

Clustering

September 25, 2018

Contributed by:
C

Click here for FAQs on clustering.

1.
2. Citrix ADC
3. NetScaler 12.0

Connection Management

November 2, 2018

Contributed by:
C

• What is an admin connection?

© 1999-2018 Citrix Systems, Inc. All rights reserved. 228

NetScaler 12.0

An admin connection establishes a connection to the NetScaler IP (NSIP) address and allows
administrators to configure and monitor the NetScaler appliance.
• What are the types of admin connections?
There are two types of admin connections:
– SSH connection – Admin users use an SSH client to logon through the NetScaler IP (NSIP)
address.
– NITRO API connection – Admin users use NITRO API’s to automate the logon process to
NetScaler appliance.
Note: Admin users can also log on through the NetScaler GUI to log on, by using a browser
to connect to the NSIP address. The GUI internally opens a NITRO API connection. There-
fore, a GUI session is equivalent to a NITRO API connection, and FAQs related to NITRO API
apply to GUI.
• How many concurrent admin connections are allowed on a NetScaler appliance?
The appliance allows up to 20 concurrent admin connections.
• Which login credentials are required for an admin logon?
Admin logon requires a user name and a password.
Note: An authentication key can be used instead of a password.
• Which external authentication methods does a NetScaler appliance support?
The appliance supports the following external authentication methods:
– RADIUS
– LDAP
– TACACS
• What is a client?
A client is a device (laptop or desktop), used by admin user to open an admin connection.
• What is a session token?
A session token is a unique identifier that the NetScaler appliance issues to a client that sends
a NITRO API logon request.
– API clients can reuse the session token, if it has not expired, for subsequent API requests
on new TCP connections
– GUI clients internally open NITRO API connections and keep the session token active for
the duration of the GUI session.
• What is an active session on a NetScaler appliance?
A CLI session is considered active if the session has not expired and has an open SSH connection
with a NetScaler appliance.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 229

NetScaler 12.0

A NITRO API session is considered active if the session token timeout has not expired on the
NetScaler appliance.

• How does NetScaler enforce the concurrent connection limit?

Every time the NetScaler appliance receives an admin connection request (SSH or NITRO API),
it checks the number of admin connections it has open. If the number is lower than 20, a new
connection is opened.

• Which counter reflects the number of admin connections on a NetScaler appliance?

The connection counter (nsconfigd_cur_clients) reflects the number of active connections. This
counter is incremented when a client opens new connection to the appliance, and is decre-
mented when a connection is closed.

• Which counter reflects the number of active tokens on the NetScaler appliance?

The
configd_cur_tokens counter reflects the number of active tokens on NetScaler appliance.

• How does NetScaler appliance handle errors on a connection?

The NetScaler appliance immediately closes the client (CLI, API, and GUI) connection if it en-
counters errors on a connection.

• Does a CLI or GUI session on a connection to the management address count against the
admin connection limit?

Yes, all CLI and GUI connections are TCP based connections, and every TCP connection to the
management address counts against the admin connection limit.

• Does a NITRO session count against the admin connection limit?

A NITRO session counts against the admin connection limit if there is an open TCP connection
using the session token issued by the NetScaler appliance.

• What is the default timeout period for API, GUI, and CLI sessions on NetScaler appliance?

The following table lists the default timeout period for API, GUI and CLI sessions on the NetScaler
appliance:

CLI default timeout API default timeout GUI default timeout

NetScaler Releases period (min) period (min) period (min)

NetScaler 9.3 None 30 Minutes 30 Minutes

NetScaler 10.1 None 30 Minutes 30 Minutes
NetScaler 10.5 15 Minutes 30 Minutes 15 Minutes
Onwards

© 1999-2018 Citrix Systems, Inc. All rights reserved. 230

NetScaler 12.0

• How can you set the CLI sessions time out on a NetScaler appliance?

The CLI session timeout can be configured by executing the following command at the CLI
prompt:

set cli mode -timeout <xx seconds>

• How do you override the default timeout period when using the NITRO API?

You can override the default timeout period for a NITRO API by setting the timeout duration in
the “timeout” field of the login object. If the session timeout is set to zero, the session token
has an infinite timeout.
Note: An infinite timeout is not advisable, because sessions that do not time out continue to
count against the admin connection count.

• What happens if a user account is deleted from the NetScaler appliance after an admin
session is created?

For internal system users, NetScaler appliance closes the existing CLI or NITRO API session.

For external system users, session remains active until it expires.

• Can NITRO API clients use a single session token to open multiple admin connections on
the NetScaler appliance?

Yes. Each such connection counts against the admin connection limit.

• If management access is enabled for a MIP or SNIP address, do admin connections to that
address count against the limit for the number of admin connections?

Yes, admin connections to management address (MIP or SNIP) count against the admin connec-
tion limit on NetScaler appliance.

• Can a NetScaler admin log on to the NetScaler appliance after the maximum connections
limit is reached?

Yes. One additional admin connection is allowed after the maximum connection limit is
reached.

• Can NITRO API endpoints open multiple admin connections on NetScaler the appliance?

Yes, NITRO API endpoints can open multiple admin connections and exhaust the concurrent ad-
min connection limit on a NetScaler appliance. In such situations, an additional SSH/CLI con-
nection is allowed and the admin can force closure of old API sessions, or reduce the session
timeout duration for the existing API sessions.

• Can same client open multiple API sessions on a NetScaler appliance?

Yes, a client can open multiple API session by repeatedly logging on. For example, the client
might log back on after a reboot.
Note: Repeated client logons count against the admin connection limit on NetScaler appliance.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 231

NetScaler 12.0

• Can API clients use the entire API session token limit?

Yes, API clients can use the entire API session token limit, provided by repeatedly logging on
without using a previously issued token.

Note: If a client’s session timeout is zero, the token is valid forever. Repeated logons using new
session tokens can count against the limit for API session tokens.

• Do CLI sessions count against the API session token limit?

No, CLI sessions are not counted against the API session token limit.

• Can admin users use telnet to open a CLI session?

No. Only an SSH client can open a CLI session.

• What is connection limit and API session limit applicable for various NetScaler releases?

The following table lists the maximum concurrent admin connection and active API session lim-
its applicable for various NetScaler releases:

NetScaler 10.1 (Before 10.1 (Before 10.1 (From

Releases 9.3 130.x) 130.10) 130.10)

Maximum 20 20 20 20
number of
concurrent
admin
connections
Maximum 1000 20 1000 1000
number of active
API sessions*

Note:

– API sessions are considered active if they have not timed out. For example, if 500 API
sessions were created but 100 have expired, 400 API sessions are active.
– An API session need not open a TCP connection to the NetScaler appliance.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 232

NetScaler 12.0

Content Switching

September 25, 2018

Contributed by:
C

• I have installed a non-NetScaler load balancing appliance on the network. However, I

would like to use the content switching feature of the NetScaler appliance to direct the
client requests to the load balancing appliance. Is it possible to use the Content switching
feature of the NetScaler appliance with a non-NetScaler load balancing appliance?

Yes. You can use the Content switching feature of the NetScaler appliance with the load balanc-
ing feature of the NetScaler appliance or a non-NetScaler load balancing appliance. However,
when using the non-NetScaler load balancing appliance, make sure that you create a load bal-
ancing virtual server on the NetScaler appliance and bind it to the non-NetScaler load balancing
appliance as a service.

• How is a Content switching virtual server different from a load balancing virtual server?

A Content switching virtual server is capable only of sending the client requests to other virtual
servers. It does not communicate with the servers.

A Load balancing virtual server balances the client load among servers and communicates with
the servers. It monitors server availability and can be used to apply different load balancing
algorithms to distribute the traffic load.

Content switching is a method used to direct client requests for specific types of content to
targeted servers by way of load balancing virtual servers. You can direct the client requests to
the servers best suited to handle them. This result in reduced overheads to process the client
requests on the servers.

• I want to implement the Content switching feature of the NetScaler appliance to direct the
client requests. What types of client request can I direct by using the Content switching
feature?

You can direct only HTTP, HTTPS, FTP, TCP, Secure TCP, and RTSP client requests by using the
Content switching feature. To direct HTTPS client requests, you must configure the SSL offload
feature on the appliance.

• I want to create Content switching rules on the NetScaler appliance. What are the various
elements of the client request on which I can create a content switching rule?

You can create the content switching rules based on the following elements and their values in
the client request:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 233

NetScaler 12.0

– URL
– URL tokens
– HTTP version
– HTTP Headers
– Source IP address of the client
– Client version
– Destination TCP port

• I understand that the content switching feature of the NetScaler appliance helps enhance
the performance of the network. Is this correct?

Yes. You can direct the client requests you the servers best suited to handle them. The result is
reduced overhead for processing the client requests on the servers.

• Which feature of the NetScaler appliance should I configure on the NetScaler appliance to
enhance the site manageability and response time to the client requests?

You can configure the content switching feature of the NetScaler appliance to enhance the site
manageability and response time to the client request. This feature enables you to create con-
tent groups within the same domain name and IP address. This approach is flexible, unlike the
common approach of explicitly partitioning the content into different domain names and IP ad-
dresses, which are visible to the user.

Multiple partitions dividing a Web site into various domain names and IP addresses force the
browser to create a separate connection for each domain it finds when rendering and fetching
the content of a web page. These additional WAN connections degrade the response time for
the web page.

• I have hosted a web site on a web server farm. What advantages does the NetScaler content
switching feature offer for this type of setup?

The content switching feature provides the following advantages on a NetScaler appliance in a
site that is based in a web server farm:

– Manage the site content by creating a content group within the same domain and IP ad-
dress.
– Enhance the response time to client requests by using the content group within the same
domain and IP address.
– Avoid the need for full content replication across domains.
– Enable application-specific content partitioning. For example, you can direct client re-
quests to a server that handles only dynamic content or only static content, as appropriate
for the request.
– Support multi-homing of multiple domains on the same server and use the same IP ad-
dress.
– Reuse connections to the servers.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 234

NetScaler 12.0

• I want to implement the content switching feature on the NetScaler appliance. I want to
direct the client requests to the various servers after evaluating the various parameters
of each request. What approach should I follow to implement this setup when configuring
the content switching feature?

You can use policy expressions to create policies for the content switching feature. An expres-
sion is a condition evaluated by comparing the qualifiers of the client request to an operand
by using an operator. You can use the following parameters of the client request to create an
expression:

– Method- HTTP request method.

– URL- URL in the HTTP header.
– URL TOKENS- Special tokens in the URL.
– VERSION- HTTP request version.
– URL QUERY- Contains the URL Query LEN, URL LEN, and HTTP header.
– SOURCEIP- IP address of the client.

Following is a complete list of the operators that you can use to create an expression:

– == (equals)
– != (not equals)
– EXISTS
– NOT EXISTS
– CONTAINS
– NOT CONTAINS
– GT (greater than)
– LT (less than)

You can also create various (OR) operators. You can also
rules, which are logical use parenthesis to create
aggregations of a set of nested and complex rules.
expressions. You can combine
multiple expressions to create
rules. To combine
expressions, you can use the
&& (AND) and

• I want to configure a rule based policy along with a URL based policy for the same content
switching virtual server. Is it possible to create both types of policies for the same content
switching virtual server?
Yes. You can create both type of policies for the same content switching virtual server. However,
be sure to assign priorities to set an appropriate precedence for the policies.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 235

NetScaler 12.0

• I want to create content switching policies that evaluate the domain name, along with a
prefix and suffix of a URL, and direct the client requests accordingly. Which type of content
switching policy should I create?
You can create a Domain and Exact URL policy. When this type of policy is evaluated, the
NetScaler appliance selects a content group if the complete domain name and the URL in
the client request match the ones configured. The client request must match the configured
domain name and exactly match the prefix and suffix of the URL if they are configured.
• I want to create content switching policies that evaluate the domain name, along with a
partial prefix and suffix of URL, and direct the client requests accordingly. Which type of
content switching policy should I create?
You can create a Domain and Wildcard URL policy for the content switching virtual server. When
this type of policy is evaluated, the NetScaler appliance selects a content group if the request
matches the complete domain name and partially matches the URL prefix.
• What is a Wildcard URL policy?
You can use wildcards to evaluate partial URLs in client requests to the URL you have configured
on the NetScaler appliance. You can use wildcards in the following types of URL-based policies:
– Prefix only. For example, the /sports/* expression matches all URLs available under the
/sports URL. Similarly, the /sports* expression matches all URLs whose prefix is /sports .
– Suffix only. For example the /*.jsp expression matches all URLs with a file extension of jsp.
– Prefix and Suffix. For example, the /sports/*.jsp expression matches all URLs under the
/sports/ URL that also have the jsp file extension. Similarly, the /sports*.jsp expression
matches all URLs with a prefix of /sports* and a file extension of jsp.
• What is a Domain and Rule policy?
When you create a Domain and Rule policy, the client request must match the complete domain
and the rule configured on the NetScaler appliance.
• What is the default precedence set for evaluating policies?
By default, the rule based policies are evaluated first.
• If some of the content is the same for all client requests, what type of precedence should I
use for evaluating policies?
If some of the content is same for all the users and different content should be served on the
basis of client attributes, you can use URL-based precedence for policy evaluation.
• What policy expression syntaxes are supported in content switching?
Content switching supports two types of policy expressions:
– Classic Syntax- Classic syntax in content switching starts with the keyword REQ and is
more advanced than the default syntax. Classic policies cannot be bound to an action.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 236

NetScaler 12.0

Therefore, the target load balancing virtual server can be added only after binding the con-
tent switching virtual server.
– Default Syntax: Default syntax generally starts with key word HTTP and is easier to config-
ure. A target load balancing virtual server action can be bound to a Default Syntax policy,
and the policy can be used on multiple content switching virtual servers.

• Can I bind a single content switching policy to multiple virtual servers?

Yes. You can bind a single content switching policy to multiple virtual servers by using policies
with defined actions. Content switching policies that use an action can be bound to multiple
content switching virtual servers because the target load balancing virtual server is no longer
specified in the content switching policy. The ability to bind a single policy to multiple content
switching virtual servers helps to further reduce the size of the content switching configuration.

For more information, see the following Knowledge Center articles and eDocs topics:

– See CTX122918 - How to Bind the Same Content Switching Policy to Two Content Switching
vServers on a NetScaler Appliance.
– See CTX122736 - How to Bind the Same Advanced Policy to Multiple Content Switching
Virtual Servers using Policy Labels.
– Configuring a Content Switching Action.

• Can I create an action based policy using classic expressions?

No. As of now NetScaler does not support policies using classic syntax expressions with actions.
The target load balancing virtual server should be added when binding the policy instead of
defining it in an action.

1.
2. Citrix ADC
3. NetScaler 12.0

Debugging

September 25, 2018

Contributed by:
C

• How can I determine the interface (CLI, GUI, or API) through which an operation was per-
formed?

The NetScaler keeps track of the interfaces through which operations are performed. You can
view this information in syslogs (in the NetScaler GUI, navigate to

© 1999-2018 Citrix Systems, Inc. All rights reserved. 237

NetScaler 12.0

Configuration > System > Auditing > Audit Messages > Syslog messages) or in the ns.log (located
at the /var/log/ directory) file.

For example, operations that are performed through the API are flagged as “API CMD_EXECUTED.”

1.
2. Citrix ADC
3. NetScaler 12.0

Hardware

September 25, 2018

Contributed by:
C

Click here for FAQs about MPX hardware.

1.
2. Citrix ADC
3. NetScaler 12.0

High Availability

September 25, 2018

Contributed by:
C

• What are the various ports used to exchange the HA-related information between the
nodes in an HA configuration?

In an HA configuration, both nodes use the following ports to exchange HA related information:

– UDP Port 3003, to exchange heartbeat packets

– Port 3010, for synchronization and command propagation

• What configurations are not synced or propagated in an HA configuration in either INC or

non-INC mode?

Configurations implemented with the following commands are neither propagated nor synced
to the secondary node:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 238

NetScaler 12.0

– All node specific HA configuration commands. For example, add ha node, set ha node, and
bind ha node.
– All Interface related configuration commands. For example, set interface and unset inter-
face.
– All channel related configuration commands. For example, add channel, set channel, and
bind channel.

For more information about HA Configuration in INC mode, see

Configuring High Availability Nodes in Different Subnets.

• What configurations are not synced or propagated in an HA configuration in INC mode?

The following configurations are neither synced nor propagated. Each node has its own.

– MIPs
– SNIPs
– VLANs
– Routes (except LLB routes)
– Route monitors
– RNAT rules (except any RNAT rule with VIP as the NAT IP)
– Dynamic routing configurations.

• What are the conditions that trigger synchronization?

Synchronization is triggered by any of the following conditions:

– The incarnation number of the primary node, received by the secondary, does not match
that of the secondary node.
Note: Both nodes in an HA configuration maintain a counter called
incarnation number, which counts the number of configurations in the node’s configura-
tion file. Each node sends its incarnation number to each other node in the heartbeat
messages. The incarnation number is not incremented for the following commands:
* All HA configuration related commands. For example, add ha node, set ha node, and
bind ha node.
* All Interface related commands. For example, set interface and unset interface.
* All channel-related commands. For example, add channel, set channel, and bind
channel.
– The secondary node comes up after a restart.
– The primary node becomes secondary after a failover.

• Does a configuration added to the secondary node get synchronized on the primary?

No, a configuration added to the secondary node is not synchronized to the primary.

• What could be the reason for both nodes claiming to be the primary in an HA configuration?

© 1999-2018 Citrix Systems, Inc. All rights reserved. 239

NetScaler 12.0

The most likely reason is that the primary and secondary nodes are both healthy but the sec-
ondary does not receive the heartbeat packets from the primary. The problem could be with
the network between the nodes.

• Does an HA configuration run into any issues if you deploy the two nodes with different
system clock settings?

Different system-clock settings on the two nodes can cause the following issues:

– The time stamps in the log file entries do not match. This situation makes it difficult to
analyze the log entries for any issues.
– After a failover, you might have problems with any type of cookie based persistence for
load balancing. A significant difference between the times can cause a cookie to expire
sooner than expected, resulting in termination of the persistence session.
– Similar considerations apply to any time related decisions on the nodes.

• What are the conditions for failure of the force HA sync command?

Forced synchronization fails in any of the following circumstances:

– You force synchronization when synchronization is already in progress.

– The secondary node is disabled.
– HA synchronization is disabled on the current secondary node.
– HA propagation is disabled on the current primary node and you force synchronization
from the primary.

• What are the conditions for failure of the sync HA files command?

Synchronizing configuration files fail if the secondary node is disabled.

• In an HA configuration, if the secondary node takes over as the primary, does it switch back
to secondary status if the original primary comes back online?

No. After the secondary node takes over as the primary, it remains as primary even if the original
primary node comes back online again. To interchange the primary and secondary status of the
nodes, run the
force failover command.

• What are the conditions for failure of the force failover command?

A forced failover fails in any of the following circumstances:

– The secondary node is disabled.

– The secondary node is configured to remain secondary.
– The primary node is configured to remain primary.
– The state of the peer node is unknown.

1.
2. Citrix ADC

© 1999-2018 Citrix Systems, Inc. All rights reserved. 240

NetScaler 12.0

3. NetScaler 12.0

Integrated Caching

September 25, 2018

Contributed by:
C

Content Groups

• How is a DEFAULT content group different from other content groups?

The behavior of the DEFAULT content group is exactly the same as any other group. The only
attribute that makes the DEFAULT content group special is that if an object is being cached and
no content group has been created, the object is cached in the DEFAULT group.

• What is the ‘cache-Control’ option of the content group level?

You can send any cache-control header the browser. There is a content group level option, -
cacheControl, which enables you to specify the cache-control header that you want to be in-
serted in the response to the browser.

• What is the ‘Minhit’ option in content group level?

Minhit is an integer value specifying the minimum number of hits to a cache policy before the
object is cached. This value is configurable at the content group level. Following is the syntax
to configure this value from the NetScaler command line.
add/set cache contentGroup <Content_Group_Name> [-minHits <Integer>]

• What is the use of the expireAtLastByte option?

The expireAtLastByte option enables the integrated cache to expire the object as soon as it has
been downloaded. Only requests that are outstanding requests at that time are served from
cache. any new requests are sent to the server. This setting is useful when the object is fre-
quently modified, as in the case of stock quotes. This expiry mechanism works along with the
Flash Cache feature. To configure expireAtLastByte option, run the following command from
the NetScaler command line:

add cache contentGroup <Group_Name> –expireAtLastByte YES

© 1999-2018 Citrix Systems, Inc. All rights reserved. 241

NetScaler 12.0

Cache policy

• What is a caching policy?

Policies determine which transactions are cacheable and which are not. Additionally, policies
add or override the standard HTTP caching behavior. Policies determine an action, such as
CACHE or NOCACHE, depending on the specific characteristics of the request or response. If a
response matches policy rules, the object in the response is added to the content group con-
figured in the policy. If you have not configured a content group, the object is added to the
DEFAULT content group.

• What is a policy hit?

A hit occurs when a request or response matches a cache policy.

• What is a miss?

A miss occurs when a request or response does not match any cache policy. A miss can also
occur if the request or response matches a cache policy but some override of RFC behavior pre-
vents the object from being stored in the cache.

• I have configured Integrated Caching feature of the NetScaler appliance. When adding the
following policy, an error message appears. Is there any error in the command?

add cache policy image_caching -rule exp1 ns_ext_not_jpeg –action cache

> ERROR: No such command

In the preceding command, the expression should be within the quotation marks. Without quo-
tation marks, the operator is considered to be the pipe operator.

Memory Requirements

• What are the commands that I can run on the NetScaler appliance to check the memory
allocated to cache?

To display the memory allocated for cache in the NetScaler appliance, run any of the following
commands from the NetScaler command line:

– show cache parameter

In the output, check the value of the Memory usage limit parameter. This is the maximum
memory allocated for cache.

– show cache <Content_Group_Name>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 242

NetScaler 12.0

In the output, check the values of the Memory usage and Memory usage limit parameters
indicating the memory used and allocated for the individual content group.

• My NetScaler appliance has 2 GB of memory. Is there any recommended memory limit for
cache?

For any model of the NetScaler appliance, you can allocate half of the memory to the cache.
However, Citrix recommends allocating a little less than half of the memory, because of internal
memory dependency. You can run the following command to allocate 1 GB of memory to cache:

set cache parameter -memLimit 1024

• Is it possible to allocate memory for individual content groups?

Yes. Even though you allocate memory for the integrated cache globally by running the
set cache parameter –memlimit<Integer>, you can allocate memory to individual content
groups by running the
set cache <Content_Group_Name> –memLimit <Integer> command. The maximum memory
you can allocate to content groups (combined) cannot exceed the memory you have allocated
to the integrated cache.

• What is the dependency of memory between integrated cache and TCP buffer?

If the NetScaler appliance has 2 GB memory, then the appliance reserves approximately 800 to
900 MB of memory and remaining is allocated to FreeBSD operating system. Therefore, you can
allocate up to 512 MB of memory to integrated cache and the rest is allocated to TCP buffer.

• Does it affect the caching process if I do not allocate global memory to the integrated
cache?

If you do not allocate memory to integrated cache, all requests are sent to the server. To make
sure that you have allocated memory to the integrated cache, run the
show cache parameter command. Actually no objects will be cached if global memory is 0, so
this needs to be set first.

Verification commands

• What are the options for displaying cache statistics?

You can use either of the following options to display the statistics for cache:

– stat cache

To display the summary of the cache statistics.

– stat cache –detail

To display the full details of the cache statistics.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 243

NetScaler 12.0

• What are the options for displaying the cached content?

To display the cached content, you can run the

show cache object command.

• What is the command that I can run to display the characteristics of an object stored in
cache?

If the object stored in the cache is, for example, GET //10.102.12.16:80/index.html, you can dis-
play the details about the object by running the following command from the NetScaler com-
mand line of the appliance:

show cache object -url ‘/index.html’ -host 10.102.3.96 -port 80

• Is it mandatory to specify the group name as a parameter to display the parameterized

objects in cache?

Yes. It is mandatory to specify the group name as a parameter to display the parameterized
objects in cache. For example, consider that you have added the following policies with the
same rule:

1 add cache policy p2 -rule ns_url_path_cgibin -action CACHE ‒

storeInGroup g1
2 add cache policy p1 -rule ns_url_path_cgibin -action CACHE -
storeInGroup g2

In this case, for the multiple requests, if policy p1 is evaluated, its hit counter is incremented and
the policy stores the object in the g1 group, which has hit parameters. Therefore, you have to
run the following command to display the objects from the cache:

show cache object -url “/cgi-bin/setCookie.pl” -host 10.102.18.152 groupName g1

Similarly, for another set of multiple requests, if policy p2 is evaluated, its hit counter is incre-
mented and the policy stores the object in the g2 group, which does not have hit parameters.
Therefore, you have to run the following command to display the objects from the cache:

show cache object -url “/cgi-bin/setCookie2.pl” -host 10.102.18.152

• I notice that there are some blank entries in the output of the nscachemgr command. What
are those entries?

Consider the following sample output of the nscachemgr command. The blank entries in this
output are highlighted in bold face for your reference:

1 root@ns# /netscaler/nscachemgr -a
2 //10.102.3.89:80/image8.gif
3 //10.102.3.97:80/staticdynamic.html
4 //10.102.3.97:80/
5 //10.102.3.89:80/image1.gif

© 1999-2018 Citrix Systems, Inc. All rights reserved. 244

NetScaler 12.0

6 //10.102.3.89:80/file5.html
7 //10.102.3.96:80/
8 //10.102.3.97:80/bg_logo_segue.gif
9 //10.102.3.89:80/file500.html
10 //10.102.3.92:80/
11 //10.102.3.96:80/cgi-bin/rfc/ccProxyReval.pl
12 Total URLs in IC = 10

The blank entries in the output are due to the default caching properties for GET / HTTP/1.1.

Flushing Objects

• How can I flush a selective object from the cache?

You can identify an object uniquely by its complete URL. To flush such object, you can perform
any of the following tasks:

– Flush cache
– Flush content group
– Flush the specific object
To flush the specific object, you have to specify the query parameters. You specify the
invalParam parameter to flush the object. This parameter applies only to a query.

• Does any change in the cache configuration trigger flushing of cache?

Yes. When you make any changes to the cache configuration, all the SET cache commands in-
herently flush the appropriate content groups.

• I have updated the objects on the server. Do I need to flush the cached objects?

Yes. When you update objects on the server, you must flush the cached objects, or at least the
relevant objects and content groups. The integrated cache is not affected by an update to the
server. It continues to serve the cached objects until they expire.

Flash Cache

• What is Flash Cache feature of the NetScaler appliance?

The phenomenon of Flash crowds occurs when a large number of clients access the same con-
tent. The result is a sudden surge in traffic toward the server. The Flash Cache feature enables
the NetScaler appliance to improve performance in such situation by sending only one request
to the server. All other requests are queued on the appliance and the single response is served
to all of the requests. You can use either of the following commands to enable the Fast Cache
feature:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 245

NetScaler 12.0

– add cache contentGroup <Group_Name> -flashCache YES

– set cache contentGroup <Group_Name> -flashCache YES

• What is the limit for Flash Cache clients?

The number of Flash Cache clients depends on the availability of resources on the NetScaler
appliance.

Default Behaviour

• Does the NetScaler appliance proactively receive objects upon expiry?

The NetScaler appliance never proactively receives objects on expiry. This is true even for the
negative objects. The first access after expiry triggers a request to the server.

• Does the integrated cache add clients to the queue for serving even before it starts receiv-
ing the response?

Yes. The integrated cache adds clients to the queue for serving even before it starts receiving
the response.

• What is the default value for the Verify cached object using parameter of the cache config-
uration?

HOSTNAME_AND_IP is the default value.

• Does the NetScaler appliance create log entries in the log files?

Yes. The NetScaler appliance creates log entries in the log files.

• Are compressed objects stored in the cache?

Yes. Compressed objects are stored in the cache.

Interoperability with other features

• What happens to objects that are currently stored in cache and are being accessed though
SSL VPN?

Objects stored in the cache and accessed regularly are served as cache hits when accessed
through SSL VPN.

• What happens to objects stored in the cache when accessed through SSL VPN and later
accessed through a regular connection?

The objects stored through the SSL VPN access are served as a hit when accessed through the
regular connection.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 246

NetScaler 12.0

• When using weblogging, how do I differentiate entries that indicate response served from
cache from those served by the server?

For responses served from the integrated cache, the server log field contains the value IC. For
responses served from a server, the server log field contains the value sent by the server. Fol-
lowing is a sample log entry for an integrated caching transaction:

“10.102.1.52 - “Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 4.0; .NET CLR 1.0.3705)” “GET /”
200 0 “IC” 10.102.1.45”

Along with a client request, the response logged is the one sent to the client and not necessarily
the one sent by the server.

Miscellaneous

• What do you mean by configuring relexpiry and absexpiry?

By configuring relexpiry and absexpiry, it means that you are overriding the header irrespec-
tive of what appears in the header. You can configure different expiry setting and the content
group level. With relexpiry, expiration of the header is based on the time at which the object
was received by the NetScaler. With absexpiry, expiration is based on the time configured on
the NetScaler. Relexpiry is configured in terms of seconds. Absexpiry is a time of day.

• What do you mean by configuring weakpos and heuristic?

The weakpos and heuristic are like fall back values. If there is an expiry header, it is considered
only if the last-modified header is present. The NetScaler appliance sets expiry on the basis of
the last-modified header and the heuristic parameter. The heuristic expiry calculation deter-
mines the time to expiry by checking the last-modified header. Some percentage of the dura-
tion since the object was last modified is used as time to expiry. The heuristic of an object that
remains unmodified for longer periods of time and is likely to have longer expiry periods. The
–heurExpiryParam specifies what percentage value to use in this calculation. Otherwise, the
appliance uses the weakpos value.

• What should I consider before configuring dynamic caching?

If there is some parameter that is in name-value form and does not have the full URL query, or
the appliance receives the parameter in a cookie header or POST body, consider configuring
dynamic caching. To configure dynamic caching, you have to configure hitParams parameter.

• How is hexadecimal encoding supported in the parameter names?

On the NetScaler appliance, the %HEXHEX encoding is supported in the parameter names. In
the names that you specify for hitParams or invalParams, you can specify a name that contains
%HEXHEX encoding in the names. For example, name, nam%65, and n%61m%65 are equiva-
lent.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 247

NetScaler 12.0

• What is the process for selecting a hitParam parameter?

Consider the following excerpt of an HTTP header for a POST request:

1 POST /data2html.asp?param1=value1&param2=&param3&param4=value4
2 HTTP/1.1
3 Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg,
4 application/vnd.ms-powerpoint, application/vnd.ms-excel,
5 application/msword, application/x-shockwave-flash, */*
6 Referer: http://10.102.3.97/forms.html
7 Accept-Language: en-us
8 Content-Type: application/x-www-form-urlencoded
9 Accept-Encoding: gzip, deflate
10 User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)
11 Host: 10.102.3.97
12 Content-Length: 153
13 Connection: Keep-Alive
14 Cache-Control: no-cache
15 Cookie: ASPSESSIONIDQGQGGRNY=NNLLKDADEENOAFLCCDGFGDMO
16 S1=This+text+is+only+text%2C+not+more+and+not+less%2C+%0D%0Ajust+
text+to+be+itself%2C+namely+%22Text%22+to+be+posted+as+text
+%28what+else...%29&B1=Submit

In the above request, you can use S1 and B1, highlighted in bold face for your reference, as
hitParams depending on your requirements. Additionally, if you use -matchCookies YES in
the ASPSESSIONIDQGQGGRNY content group, then you can also use these parameters as
hitParams.
• What happens to the queued clients if the response is not cacheable?
If the response is not cacheable, all of the clients in the queue receive the same response that
the first client receives.
• Can I enable the Poll every time (PET) and Flash Cache features on the same content group?
No. You cannot enable PET and Flash Cache on the same content group. The integrated cache
does not perform AutoPET function on Flash Cache content groups. The PET feature ensures
that the integrated cache does not serve a stored object without consulting the server. You can
configure PET explicitly for a content group.
• When are the log entries created for the queued clients?
The log entries are created for the queued clients soon after the appliance receives the response
header. The log entries are created only if the response header does not make the object non-
cacheable.
• What is the meaning of the DNS, HOSTNAME, and HOSTNAME_AND_IP values of the Verify
cached object using parameter of the cache configuration?

© 1999-2018 Citrix Systems, Inc. All rights reserved. 248

NetScaler 12.0

The meanings are as follows:

– set cache parameter -verifyUsing HOSTNAME

This ignores the destination IP address.

– set cache parameter -verifyUsing HOSTNAME_AND_IP

This matches the destination IP address.

– set cache parameter -verifyUsing DNS

This uses the DNS server.

• I have set weakNegRelExpiry to 600, which is 10 minutes. I noticed that 404 responses are
not getting cached. What is the reason?

This completely depends on your configuration. By default, 404 responses are cached for 10
minutes. If you want all 404 responses to be fetched form the server, specify–weakNegRelExpiry
0. You can fine tune the –weakNegRelExpiry to a desired value, such as higher or lower to get the
404 responses cached appropriately. If you have configured –absExpiry for positive responses,
then it might not yield desired results.

• When the user accesses the site by using the Mozilla Firefox browser, the updated content is
served. However, when the user accesses the site by using the Microsoft Internet Explorer
browser, stale content is served. What could be the reason?

The Microsoft Internet Explorer browser might be taking the content from its local cache instead
of the NetScaler integrated cache. The reason could be that the Microsoft Internet Explorer
browser is not respecting the expiry related header in the response.

To resolve this issue, you can disable the local cache of the Internet Explorer and clear the offline
content. After clearing the offline content, the browser should display the updated content

• What if Hits are zero?

Check to see if the server time and NS time are in sync. And the weakPosrelexpiry limit set
should bear the time difference between NS and server as shown below

root@ns180# date

Tue May 15 18:53:52 IST 2012

• Why are policies getting hits but nothing is being cached?

Verify that memory is allocated to the integrated cache and that the allocation is greater than
zero.

• Is it possible to zero the cache counters?

There is no command line or GUI option for setting the cache counters to zero, and flushing the
cache does not do so either. Rebooting the box automatically sets these counters to zero.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 249

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0

Install, upgrade, and downgrade

October 3, 2018

Contributed by:
C

This is section, you’ll find answers to the following questions. Scroll down to see the answers.

Install and upgrade

• What is the use of the zebos.conf file available in a NetScaler release?

• I want to change the SSH port (22) on the NetScaler appliance to some other port. Is it possible
to change the SSH port on the appliance?

• I want to log on to the NetScaler appliance without entering the password. Is it possible to
configure SSH on the appliance to allow that?

• What is the procedure to reset the NetScaler appliance BIOS? Under what circumstances should
I reset the BIOS?

• I need to reset the NetScaler appliance to the factory defaults. What procedure should I follow?

• The appliance displays a message similar to the “Jun 21 12:20:18 ns /flash/ns-10.0-47.15:

[1/2]dc0: NIC hang condition #663: TX 10000/10000, RX 0, HF 0” message on the console. What
is the meaning of this message?

• After I upgraded the Citrix ADC release on the appliance, the appliance still displays the earlier
release/build. What could be the reason?

• Since I upgraded the Citrix ADC release on the appliance, the LCD display on the front panel
of the appliance displays the out of service message or does not display anything. How can I
resolve this issue?

• I have upgraded the Citrix ADC release/build. However, after the upgrade process, the appliance
fails to start. Can I downgrade the appliance’s software to the previous release/build?

• After upgrading the Citrix ADC release on the appliance, I accidently deleted the kernel file from
the /flash directory. As a result, I am not able to start the appliance. Is there a method for starting
the appliance in this situation?

© 1999-2018 Citrix Systems, Inc. All rights reserved. 250

NetScaler 12.0

• After upgrading the appliance software to Citrix ADC release 10.0, I am not able to log on to the
appliance, and the following message is appears:
login: nsroot Password: connect: No such file or directory nsnet_connect: No such file or direc-
tory Login incorrect
I tried to resolve this issue by using the password recovery procedure, but I was not successful.
Have I done something incorrectly?
• During an upgrade of a high availability pair, the following message appears repeatedly:
ns sshd[5035]: error: Invalid username or password
What could be the reason?
• I want to change the netmask of the NetScaler IP address on a Citrix ADC appliance. Can I do so
without causing an outage?
• I have configured a High Availability pair of Citrix ADC appliances. After upgrading the software
release from a beta release to a final release, I noticed that some of the appliance configurations
are missing. Can I retrieve the lost configurations?
• Can I upgrade a Citrix ADC appliance directly from release 10.0 to 10.5, or should I upgrade to
10.1 first and then to 10.5?
• Can the primary appliance and secondary appliance have separate builds?
• Can both the appliances in an High Availability (HA) pair be upgraded at the same time?
• Does Citrix support firmware upgrades in the amazon AWS cloud?
• Can I upgrade the Citrix ADC instance independently of the SDX version?
• Can I use the FTP server to upgrade the Citrix ADC appliance?
• Is the procedure for upgrading the Citrix ADC appliance with GSLB configurations different from
an upgrade of an appliance that is not involved in GSLB?

Downgrade

• I have received a Citrix ADC appliance with the latest Citrix ADC release installed on it. However,
I want to downgrade the software release. Can I do so?**
• When downgrading the Citrix ADC release, I followed the instructions. However, the appliance
displays the following message:

1 root@LBCOL03B# ./installns
2 installns version (10.0-47.7) kernel (ns-10.0-47.7.gz)
3 Note:
4 Installation may pause for up to 3 minutes while data is written to the
flash.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 251

NetScaler 12.0

5 Caution:
6 Do not interrupt the installation process.
7 Doing so may cause the system to become unusable.
8 Installation will proceed in 5 seconds, CTRL-C to abort
9 No Valid Netscaler Version Detected
10 root@LBCOL03B#

Am I doing something incorrectly?

• How is the rollback procedure performed on a Citrix ADC appliance?

Install and upgrade

What is the use of the zebos.conf file available in a NetScaler release?

A NetScaler appliance uses Zebos as the routing suite. The zebos.conf file available in a NetScaler
release is the configuration file for Zebos.

I want to change the SSH port (22) on the NetScaler appliance to some other port. Is it possible
to change the SSH port on the appliance?

Yes. You can change the SSH port on the NetScaler appliance by editing the sshd_config file in the
/nsconfig directory. If the file does not exist in the /nsconfig directory, copy it from the /etc directory.

In the sshd_config file, edit the entry for Port 22 to Port <Number>, where <Number> is the target port
number. If you do not want to restart the appliance and make the changes effective, terminate the
sshd process by using the kill command, and then restart the process.

The flash directory is missing from the NetScaler appliance. What procedure should I follow to
mount the flash directory?

To mount the flash directory, do the following:

1. Start the NetScaler appliance in single-user mode.

When the appliance starts, the following message appears:

Hit [Enter] to boot immediately, or any other key for command prompt. Booting [kernel] in 10
seconds…” Hit space and you should see the following prompt:

Type ‘?’ for a list of commands, ‘help’ for more detailed help.

2. Enter the following command to start FreeBSD in single-user mode:

boot –s

After the appliance starts, the following message appears:

Enter full pathname of shell or RETURN for /bin/sh:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 252

NetScaler 12.0

3. Press Enter to display the # prompt.

4. Run the following command to mount the flash directory:

1 mount /dev/ad0s1a /flash

2
3 Note: If the preceding command displays an error message about
permissions, run the following command to check the disk for
consistency:
4
5 fsck /dev/ad0s1a
6
7 Run the mount command again to mount the flash directory.

5. Restart the appliance.

6. From the shell prompt, run the following command to verify that the flash directory is mounted:

1 df -kh

I want to log on to the NetScaler appliance without entering the password. Is it possible to con-
figure SSH on the appliance to allow that?

Yes. You can configure SSH on the NetScaler appliance to log on without a password. However, you
must provide your user name. To configure SSH for logging in without a password, do the following:

1. Run the following command to generate the public and private keys:

1 \# ssh-keygen -t rsa

2. Run the following command to copy the id_rsa.pub file to the .ssh directory of the remote host
that you want to log on to:

1 \# scp id_dsa.pub \<user>@\<remote_host>/.ssh/id_dsa.pub

3. Log on to the remote host.

4. Change to the .ssh directory.

5. Run the following commands to add the public key of the client to the known public keys:

1 \# cat id_dsa.pub >> authorized_keys2

2
3 \# chmod 640 authorized_keys2
4
5 \# rm id_dsa.pub

© 1999-2018 Citrix Systems, Inc. All rights reserved. 253

NetScaler 12.0

What is the procedure to reset the NetScaler appliance BIOS? Under what circumstances should
I reset the BIOS?

To reset BIOS of the NetScaler appliance, complete the following procedure:

1. Connect to the appliance through the serial port.

2. Start the appliance and press Delete as soon as the boot-up process starts.

Pressing Delete during the POST process displays the appliance’s BIOS settings.

3. Activate the Exit page of the BIOS settings.

4. Select the Load Optimal Defaults option. The Load Optimal Settings message box appears.

5. Select OK.

6. Make the following changes to the BIOS settings on the various tabs:

Tab

7. Activate the Exit page of the BIOS settings.

8. Select Save changes and Exit.

9. Select OK to confirm.

10. Verify that the appliance starts cleanly and the serial console displays output after the appliance
starts.

1 You need to reset BIOS when the serial console does not respond. This
usually happens after you upgrade the appliance and the serial
console is disabled. However, you can still access the appliance by
using the telnet or SSH utility.

I need to reset the NetScaler appliance to the factory defaults. What procedure should I follow?

To reset the NetScaler appliance to the factory defaults, you need to reset two environments: the
NetScaler application environment and the base FreeBSD environment.
To reset the NetScaler application environment of the appliance to the factory defaults, do the follow-
ing:

1. Make a backup of the appliance’s /nsconfig/ns.conf.

2. Delete the /nsconfig/ns.conf file.
3. Restart the appliance.To reset the FreeBSD environment of the appliance to the factory defaults,
do the following:
a) Install a fresh NetScaler code image on the appliance. This overwrites a number of
FreeBSD-level configuration files with default values.
b) Delete any users and groups that are added to the appliance, that is, all except the default
users.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 254

NetScaler 12.0

c) Delete the /etc/resolv.conf file.

d) Delete the entries that you have added to the /etc/hosts file.
e) If the /etc/rc.netscaler file exists, delete it.
f) Open the /etc/nsperm_group_suser file and make sure that all IOCTL entries are comment
entries.
g) Open the /etc/rc.conf file and make sure that the syslogd_enable=NO entry is not changed
to syslogd_enable=YES.
h) Open the /etc/syslog.conf file and make sure that there are no additional entries in the file.
i) Delete the contents of the /var/nslog, /var/nstrace, and /var/crash files.
j) If the syslog process is enabled on the appliance and the appliance creates log files lo-
cally, delete the contents of the log files listed in the /etc/syslog.conf file. The files are
created in the /var/log directory. For example, if syslog process writes system events to
the /var/log/events file, and sslvpn access events to the /var/log/sslvpnevents file, delete
these files.

The appliance displays a message similar to the “Jun 21 12:20:18 ns /flash/ns-10.0-47.15:

[1/2]dc0: NIC hang condition #663: TX 10000/10000, RX 0, HF 0” message on the console. What
is the meaning of this message?

The message consists of the following components (shown here as examples):

• #663: Number of times this condition has occurred on the appliance.

• TX 10000/10000: Number of packets that the appliance attempted to transmit, and number of
packets transmitted. If both numbers are the same, as in this example, the NIC transmitted all
the packets that the appliance attempted to transmit.
• RX 0: Number of packets received. In this example, no packet was received.
• HF0: Number of hardware issues reported by the NIC. In this example, the NIC did not report
any hardware issue.

If the appliance does not receive any packets, it reports a hang condition, because on a network it is
very unlikely not to receive any packets. However, if the appliance is plugged into quite interface, you
can ignore this error message.

After I upgraded the NetScaler release on the appliance, the appliance still displays the earlier
release/build. What could be the reason?

The appliance displays the software version number from the /flash/boot/loader.conf file. If the ker-
nel entry for the current NetScaler release is missing from that file, the appliance displays the last
NetScaler release version for which the entry was available.
To resolve this issue, do the following:

1. Verify that the kernel file exists in the /nsconfig directory.

2. Check the /flash/boot/loader.conf file for an entry for the kernel.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 255

NetScaler 12.0

(You can expect the entry for the kernel of the release/build that you just installed to be missing
from the file.)

3. Open the loader.conf file in a text editor, such as the vi editor, and update the kernel entry for
the new release/build.

4. Save and close the file.

5. Repeat step 2 through step 4 for the /flash/boot/loader.conf.local file.

6. Update the release/build entry in the ns.conf file.

7. Restart the appliance.

Since I upgraded the NetScaler release on the appliance, the LCD display on the front panel of the
appliance displays the out of service message or does not display anything. How can I resolve
this issue?

Run the following command from the appliance’s shell prompt:

1 /netscaler/nslcd ‒ k

I have upgraded the NetScaler release/build. However, after the upgrade process, the appliance
fails to start. Can I downgrade the appliance’s software to the previous release/build?

Yes. You can start the appliance with the kernel.old kernel file. When you restart the appliance, press
the F1 key as soon as the appliance console displays the Press F1 message. Type kernel.old and press
Enter.

After upgrading the NetScaler release on the appliance, I accidently deleted the kernel file from
the /flash directory. As a result, I am not able to start the appliance. Is there a method for starting
the appliance in this situation?

Yes. You can start the appliance by using the kernel.GENERIC kernel file, as follows:

1. When you restart the appliance, press the F1 key as soon as the appliance console displays the
Press F1 message.
2. Type kernel.GENERIC and press Enter.
3. Login as the root user.
4. Reinstall the NetScaler release.
5. Restart the appliance.

After upgrading the appliance software to NetScaler release 10.0, I am not able to log on to the
appliance, and the following message is appears:

1 ‘‘‘
2 login: nsroot
3 Password:
4 connect: No such file or directory

© 1999-2018 Citrix Systems, Inc. All rights reserved. 256

NetScaler 12.0

5 nsnet_connect: No such file or directory

6 Login incorrect
7 ‘‘‘

I tried to resolve this issue by using the password recovery procedure, but I was not successful.
Have I done something incorrectly?

You cannot resolve this issue by using the password recovery procedure. NetScaler releases 8.0 and
later use the new licensing system, based on the Imgrd daemon, which runs during the startup pro-
cedure. For this daemon to work properly, the host name of NetScaler appliance, which is set in the
/nsconfig/rc.conf file, must be resolved by a name server to the NetScaler IP address. Alternately, you
can create a hosts file in the /nsconfig directory and add the 127.0.0.1 <Host_Name> entry in file.

Additionally, make sure that you have copied the license files to the /nsconfig/license/ directory.

During an upgrade of a high availability pair, the following message appears repeatedly:

<auth.err> ns sshd[5035]: error: Invalid username or password

What could be the reason?

This error message appears when the appliances involved in the high availability pairing have either
a different NetScaler release or a different builds of the same release installed. The appliances can
have different version installed if you have upgraded or downgraded one appliance but not the other.

I want to change the netmask of the NetScaler IP address on a NetScaler appliance. Can I do so
without causing an outage?

Changing the netmask of the NetScaler IP might result in a short outage. Make sure that you change
the netmask on the secondary appliance, and then break the high availability pairing. Check the func-
tionality of the appliance. If everything works as expected, rebuild the high availability pairing.

To change the netmask on the appliance, run the configns command from the CLI prompt, and then
choose the second option in the menu.

I have configured a High Availability pair of NetScaler appliances. After upgrading the software
release from a beta release to a final release, I noticed that some of the appliance configurations
are missing. Can I retrieve the lost configurations?

You can use the following procedure to restore the configuration:

1. Log on to the NetScaler command line of the primary appliance.

2. Run the following commands:

1 save config
2
3 shell
4

© 1999-2018 Citrix Systems, Inc. All rights reserved. 257

NetScaler 12.0

5 \#cp /nsconfig/ns.conf /nsconfig/ns.conf.bkup

6
7 The ns.conf.bkup file is a backup for the running configuration.

3. Upgrade software of both the appliances to the final release.

4. Log on to the NetScaler command line of the primary appliance.

Can I upgrade a NetScaler appliance directly from release 10.0 to 10.5, or should I upgrade to 10.1
first and then to 10.5?

You can directly upgrade a NetScaler appliance regardless of the version or the build number.

Can the primary appliance and secondary appliance have separate builds?

Recommended practice is to use the same version and build number on both the primary and the
secondary appliance.

Can both the appliances in an High Availability (HA) pair be upgraded at the same time?

No. In an HA pair, first upgrade the secondary node and then upgrade the primary node.

For details, refer Upgrading a High Availability Pair.

Does Citrix support firmware upgrades in the amazon AWS cloud?

Yes.

Can I upgrade the NetScaler instance independently of the SDX version?

It is not required to upgrade the SDX version when the NetScaler appliance is upgraded. However,
some features might not work.

Can I use the FTP server to upgrade the NetScaler appliance?

No. You must first download the firmware from the Citrix download site, save it on your local computer
and then upgrade the appliance.

Is the procedure for upgrading the NetScaler appliance with GSLB configurations different from
an upgrade of an appliance that is not involved in GSLB?

No. The upgrade procedure is similar to the basic upgrade procedure. The only difference is that you
can upgrade the standalone or HA appliances on different sites in a phased manner.

Downgrade

I have received a NetScaler appliance with the latest NetScaler release installed on it. However,
I want to downgrade the software release. Can I do so?

© 1999-2018 Citrix Systems, Inc. All rights reserved. 258

NetScaler 12.0

No. If you attempt to downgrade the software release, the appliance might not work as expected,
because the ns.conf file of the later release might not be compatible with the earlier release, and the
appliance might restore to the factory settings.

When downgrading the NetScaler release, I followed the instructions. However, the appliance
displays the following message:

1 root@LBCOL03B# ./installns
2 installns version (10.0-47.7) kernel (ns-10.0-47.7.gz)
3 Note:
4 Installation may pause for up to 3 minutes while data is written to the
flash.
5 Caution:
6 Do not interrupt the installation process.
7 Doing so may cause the system to become unusable.
8 Installation will proceed in 5 seconds, CTRL-C to abort
9 No Valid Netscaler Version Detected
10 root@LBCOL03B#

How is the rollback procedure performed on a NetScaler appliance?

The rollback procedure is similar to the basic upgrade procedure. Select the target build that you
want to roll back to and perform the downgrade.Before rolling back to a different release, Citrix rec-
ommends that you create a copy of your current configuration files. To downgrade from a release, see
Downgrading a NetScaler Standalone Appliance.

1.
2. Citrix ADC
3. NetScaler 12.0

Load Balancing

September 25, 2018

Contributed by:
C

• What are the various load balancing policies I can create on the NetScaler appliance?

You can create the following types of load balancing policies on the NetScaler appliance:

– Least Connections
– Round Robin
– Least response time

© 1999-2018 Citrix Systems, Inc. All rights reserved. 259

NetScaler 12.0

– Least bandwidth
– Least packets
– URL hashing
– Domain name hashing
– Source IP address hashing
– Destination IP address hashing
– Source IP - Destination IP hashing
– Token
– LRTM
• Can I achieve the Web farm security by implementing load balancing using the NetScaler
appliance?
Yes. You can achieve Web farm security by implementing load balancing using the NetScaler
appliance. NetScaler appliance enables you to implement the following options of the load
balancing feature:
– IP Address hiding: Enables you to install the actual servers to be on private IP address
space for security reasons and for IP address conservation. This process is transparent to
the end-user because the NetScaler appliance accepts requests on behalf of the server.
While in the address hiding mode, the appliance completely isolates the two networks.
Therefore, a client can access a service running on the private subnet, such as FTP or a
Telnet server, through a different VIP on the appliance for that service.
– Port Mapping: Enables the actual TCP services to be hosted on non-standard ports for
security reasons. This process is transparent to the end-user as the NetScaler appliance
accepts requests on behalf of the server on the standard advertised IP address and port
number.
• What are various devices that I can use to load balance with a NetScaler appliance?
You can load balance following devices with a NetScaler appliance:
– Server farms
– Caches or Reverse Proxies
– Firewall devices
– Intrusion detection systems
– SSL offload devices
– Compression devices
– Content Inspection servers
• Why should I implement the load balancing feature for the website?
You can implement the Load balancing feature for the website to take the following advantages:
– Reduce the response time: When you implement the load balancing feature for the web-
site, one of the major benefits is the boost you can look forward to in load time. With two

© 1999-2018 Citrix Systems, Inc. All rights reserved. 260

NetScaler 12.0

or more servers sharing the load of the web traffic, each of the servers runs less traffic
load than a single server alone. This means there are more resources available to fulfill
the client requests. This results in a faster website.
– Redundancy: Implementing the load balancing feature introduces a bit of redundancy.
For example, if the website is balanced across three servers and one of them does not re-
spond at all, the other two can keep running and the website visitors do not even notice
any downtime. Any load balancing solution immediately stops sending traffic to the back-
end server that is not available.

• Why do I need to disable the Mac Based Forwarding (MBF) option for Link Load Balancing
(LLB)?

– If you enable the MBF option, the NetScaler appliance considers that the incoming traffic
from the client and the outgoing traffic to the same client flow through the same upstream
router. However, the LLB feature requires that the best path be chosen for the return traffic.
– Enabling the MBF option breaks this topology design by sending the outgoing traffic
through the router that forwarded the incoming client traffic.

• What are the various persistence types available on the NetScaler appliance?

The NetScaler appliance supports the following persistence types:

– Source IP
– Cookie insert
– SSL session ID
– URL passive
– Custom Server ID
– Rule
– DESTIP

1.
2. Citrix ADC
3. NetScaler 12.0

NetScaler GUI

January 6, 2019

Contributed by:
C

• When I use Firefox to compare two NetScaler configurations, the browser seems to freeze?

© 1999-2018 Citrix Systems, Inc. All rights reserved. 261

NetScaler 12.0

Firefox will eventually display the differences in the configurations, but the process takes a con-
siderable amount of time if there are more than 1000 differences. Use Chrome for a faster re-
sponse.

• I am using a MAC Safari browser to upgrade a NetScaler appliance. On the upgrade wizard,
when I click the Browse button to choose the build file from the appliance, the dialog box
does not show any files or folders. Also, when I navigate back to the root folder, the dialog
box displays the top level folder, but I cannot browse it. What should I do?

On the Safari browser, click the Settings icon and navigate to Preferences > Security > Manage
Website Settings > Java, and then change value of the When visiting other websites setting to
Run in unsafe mode.

• What should I do before accessing the NetScaler GUI?

Before accessing a new version of the NetScaler software:

– Clear browser cache including cookies.

– Access GUI in browser incognito mode.
– Access GUI in some other browser.
– Uncheck ‘Use software acceleration’ option in setting and restart the browser.
– Access chrome: extensions, uncheck the ‘Enable’ box and restart Chrome browser.

• I am using HTTP to access the NetScaler GUI. Which port should I open?

Open TCP port 80 when using HTTP to access the NetScaler GUI.

• I am using HTTPS to access the NetScaler GUI. Which port should I open?

Open TCP port 443 when using HTTPS to access the NetScaler GUI.

• With which browsers is the NetScaler GUI compatible for different operating systems?

The following table lists the compatible browsers:

|Operating System|Browser|Versions|
|—|—|—|
|Windows 7|Internet Explorer|8 and 9|
|Windows 7|Mozilla Firefox|3.6.25 and above|
|Windows 7|Chrome|15 and above|
|Windows 64 bit|Internet Explorer|8 and 9|
|Windows 64 bit|Chrome|15 and above|
|MAC OS|Mozilla Firefox|12 and above|
|MAC OS|Safari|5.1.3|

• When I access the NetScaler GUI by using Internet Explorer version 8 or 9, the browser dis-
plays only a grey bar at the top of the screen. What should I do?

© 1999-2018 Citrix Systems, Inc. All rights reserved. 262

NetScaler 12.0

The browser might be set in compatibility mode. To disable compatibility mode, go to Tools >
Compatibility View Settings and clear the Display all websites in Compatibility View check
box.

• Even after I disable compatibility mode in Internet Explorer version 8 or 9, the NetScaler
GUI does not appear. What should I do?

Make sure that the browser mode and document mode in the browser are set to the same ver-
sion. To view the configuration, press F12. Set the values to either Internet Explorer 8 or Internet
Explorer 9.

• After logging into the NetScaler appliance, the page appears blank. What should I do?

Make sure you have disabled the Protected mode in your browser settings. If this is enabled,
the Java Script is causing the NetScaler user interface screen to appear blank.

To disable this option:

1. In your IE browser settings, go to Internet Options.

2. Go to Security tab settings, click Restricted sites zone to disable Enable Protected Mode
check box.

3. Click Apply and OK.

• When I access the NetScaler GUI by using Internet Explorer version 9, the utility displays
the following error message: “You are not logged in. Please login.” What should I do?

Make sure that the cookies are not blocked in your Interner Explorer settings. Go to Tools >
Internet Options. Click the Privacy tab, and then under Settings, make sure that the slider is
set to Medium or any lower value.

1.
2. Citrix ADC
3. NetScaler 12.0

SSL

September 25, 2018

Contributed by:
C

Click here for FAQs about SSL.

1.
2. Citrix ADC

© 1999-2018 Citrix Systems, Inc. All rights reserved. 263

NetScaler 12.0

3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Solutions for Telecom Service Providers

September 17, 2018

Contributed by:
C

Information and Communication Technology (ICT) is about bringing the Internet user closer to the
apps and data. The latest datacenter technologies have enabled the user, apps and data to be located
anywhere. A user can access apps and data from the office or from home, or from a location such as
an airport. The apps and data can be located either on the enterprise’s premises, in a public or private
cloud, or on a hybrid host. The result has been on only increased productivity, but also reduced costs
of ownership and maintenance.

Service provides offer the core infrastructure needed for carrying the user’s apps and data over the
network. Because the core infrastructure serves millions of subscribers and a wide variety of apps
and data, requirements for scale and protocol support are very high. The core infrastructure handles
two major types of traffic: data plane and control plane. Each of these planes has its own scale and
protocol-support requirements.

The data plane is the part of the core infrastructure that carries user apps and data from end to end,
that is, between end-user equipment and the application server. The number of users accessing apps
and data is in the thousands of millions, so throughput and IP-addressing requirements are very high.
Every user in the network must be uniquely identifiable. Only then can the service provider control
the traffic, monitor network usage, deliver user-specific services, and log information correctly. Many
of the today’s client devices and application servers support IPv6 natively. The core infrastructure
must not only support a mix of IPv4 and IPv6 clients and servers, but also provide the technologies
for cross-communication between IPv4 and IPv6. Finally, a service provider is measured by the quality
of service (directly related to end-user experience) and the availability of service without disruptions.
The data plane should be resilient enough to provide both quality and availability at the same time.

The control-plane infrastructure manages user traffic and maintains the business and network opera-
tions services. The most important of the many protocols that run in this plane are Diameter, Radius,
and SMPP. Diameter is a base protocol over which several other function-specific protocols have been
developed. For example:

• Gx interface between the Policy and Charging Enforcement Function (PCEF) and the Policy and
Charging Rules Function (PCRF)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 264

NetScaler 12.0

• Gy interface between the Online Charging System (OCS) and the Cisco Packet Data Network
Gateway (PGW)/Policy and Charging Enforcement Function (PCEF)

The volume of control plane traffic is in direct proportion to user activity. To manage the control plane
traffic, service providers use several ADC functionalities, such as load balancing and content switch-
ing. They need fine-grain control of control plane traffic, which equals data-plane traffic in complexity.

Service providers must meet demanding service-level agreements (SLAs), and are scrutinized thor-
oughly by regulators for compliance. Adhering to requirements while managing the data and con-
trol plane traffic requires a service provider to keep its infrastructure nimble, within budget, easily
upgradable, and flexible. As the most powerful and advanced ADCs in the market today, NetScaler
ADC products are a natural fit for the service-provider environment.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Large Scale NAT

January 6, 2019

Contributed by:
C
Note

This feature is available with a NetScaler enterprise or platinum edition license.

The Internet’s phenomenal growth has resulted in a shortage of public IPv4 addresses. Large Scale
NAT (LSN/CGNAT) provides a solution to this issue, maximizing the use of available public IPv4 ad-
dresses by sharing a few public IPv4 addresses among a large pool of Internet users.

LSN translates private IPv4 addresses into public IPv4 addresses. It includes network address and
port translation methods to aggregate many private IP addresses into fewer public IPv4 addresses.
LSN is designed to handle NAT on a large scale. The NetScaler LSN feature is very useful for Internet
Service Providers (ISPs) and carriers providing millions of translations to support a large number of
users (subscribers) and at very high throughput.

LSN Architecture

The LSN architecture of an ISP using Citrix products consists of subscribers (Internet users) in private
address spaces accessing the Internet through a NetScaler appliance deployed in ISP’s core network.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 265

NetScaler 12.0

Subscribers are connected to the ISP through the ISP’s access network. Usually, subscribers for com-
mercial use of the Internet are directly connected to the ISP’s access network. Serving those sub-
scribers requires only one level of NAT (NAT44).

Noncommercial subscribers, however, are typically behind customer-premises equipment (CPE),

such as routers and modems, that also implements NAT. These two levels of NAT create the NAT444
model. Deploying a NetScaler appliance in an ISP’s core network for LSN functionality is transparent
to the subscribers and requires no configuration changes to subscribers or the CPEs.

The NetScaler appliance receives all subscriber packets destined to the Internet. The appliance is con-
figured with a pool of pre-defined NAT IP addresses to use for LSN. The NetScaler appliance uses its
LSN feature to translate the source IP address (private) and port of the packet to the NAT IP address
(public) and NAT port, and then sends the packet to its destination on the Internet. The appliance
maintains a record of all active sessions that use the LSN feature. These sessions are called LSN ses-
sions. The NetScaler appliance also maintains the mappings between subscriber IP address and port,
and NAT IP address and port, for each session. These mappings are called LSN mappings. From LSN
sessions and LSN mappings, the NetScaler appliance recognizes a response packet (received from the
Internet) belonging to a particular session. The appliance translates the destination IP address and
port of the response packet from NAT IP address:port to the subscriber IP address:port, and sends the
translated packet to the subscriber.

LSN Features Supported on NetScaler appliance

The following describes some of the LSN features supported on NetScaler appliance:

NAT Resource Allocation

The NetScaler appliance allocates NAT IP addresses and ports, from its pre-defined NAT resource pool,
to subscribers to translate their packets for transmission to external hosts (Internet). The NetScaler
appliance supports the following types of NAT IP address and port allocation for subscribers:

• Deterministic. The NetScaler appliance allocates a NAT IP address and a block of ports to each
subscriber. The appliance sequentially allocates NAT resources to these subscribers. It assigns
the first block of ports on the beginning NAT IP address to the beginning subscriber IP address.
The next range of ports is assigned to the next subscriber, and so on, until the NAT address does
not have enough ports for the next subscriber. At that point, the first port block on the next NAT
address is assigned to the subscriber, and so on.

The NetScaler appliance logs the allocated NAT IP address and the port block for a subscriber.
For a connection, a subscriber can be identified just by its mapped NAT IP address and port
block. Because of this reason, the NetScaler appliance does not log any LSN session created

© 1999-2018 Citrix Systems, Inc. All rights reserved. 266

NetScaler 12.0

or deleted. If the entire block of ports is being used, the NetScaler appliance drops any new
connection from the subscriber.

• Dynamic. The NetScaler appliance allocates a random NAT IP address and a port from the LSN
NAT pool for a subscriber’s connection. When port block allocation is enabled in the configu-
ration, the appliance allocates a random NAT IP address and a block of ports for a subscriber
when it initiates a connection for the first time. The NetScaler appliance then allocates this NAT
IP address and one of the ports from the allocated block to each subsequent connection from
this subscriber. If the entire block of ports is being used, the appliance allocates a new random
port block to the subscriber when it initiates a new connection. One of the port in the new port
block is allocated for the new connection.

IP Pooling

The following NAT resource allocation options are available for subsequent sessions of a subscriber
who was allocated a random NAT IP address and port for an existing session.

• Paired. The NetScaler appliance allocates the same NAT IP address for all sessions asso-
ciated with the same subscriber. When no more ports are available for that address, the
appliance drops any new connections from the subscriber. This option is needed for proper
functioning of certain applications that require creation of multiple sessions on the same
source IP address (for example in peer-to-peer applications that use RTP or RTCP protocol.
• Random. The NetScaler appliance allocates random NAT IP addresses, from the pool, for differ-
ent sessions associated with the same subscriber.

Reusing LSN Mappings

The NetScaler appliance can reuse an existing LSN map for new connections originating from the same
subscriber IP address and port. The NetScaler LSN feature supports the following types of LSN map-
ping reuse:

1. Endpoint Independent. The NetScaler appliance reuses the LSN mapping for subsequent pack-
ets sent from the same subscriber IP address and port (X:x) to any external IP address and
port. This type of LSN map reuse is useful for proper functioning of VOIP and peer-to-peer appli-
cations.
2. Address dependent. The NetScaler appliance reuses the LSN mapping for subsequent packets
sent from the same subscriber IP address and port (X:x) to the same external IP address (Y),
regardless of the external port.
3. Address port dependent. The NetScaler appliance reuses the LSN mapping for subsequent
packets sent from the same internal IP address and port (X:x) to the same external IP address
and port (Y:y) while the mapping is still active.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 267

NetScaler 12.0

LSN Filtering

The NetScaler appliance can filter packets from external hosts based on the active LSN sessions and
LSN mappings. Consider an example of an LSN mapping that includes the mapping of subscriber
IP:port (X:x), NAT IP:port (N:n), and external host IP:port (Y:y). The NetScaler LSN feature supports the
following types of filtering:

1. Endpoint Independent. The NetScaler appliance filters out only those packets that are not des-
tined to NAT IP:port (N:n), which represents subscriber IP:port (X:x), regardless of the external
host IP address and port source (Z:z). The NetScaler appliance forwards any packets destined
to X:x. In other words, sending packets from the subscriber to any external IP address is suffi-
cient to allow packets from any external host to the subscriber. This type of filtering is useful
for proper functioning of VOIP and peer-to-peer applications.
2. Address dependent. The NetScaler appliance filters out packets not destined to NAT IP:port
(N:n), which represents subscriber IP:port (X:x). In addition, the appliance filters out packets
from external host IP address and port (Y:y) destined for N:n if the subscriber has not previously
sent packets to Y:anyport (external port independent). In other words, receiving packets from
a specific external host requires that the subscriber first send packets to that specific external
host’s IP address.
3. Address port dependent. The NetScaler appliance filters out packets not destined to NAT
IP:port (N:n), which represents subscriber IP:port (X:x). In addition, the appliance filters out
packets from external host IP address and port (Y:y) destined for N:n if the subscriber has not
previously sent packets to Y:y. In other words, receiving packets from a specific external host
requires that the subscriber first send packets to that specific external IP address and port.

Quotas

The NetScaler appliance can limit the number of NAT ports and sessions for each subscriber to ensure
fair distribution of resources among subscribers. The NetScaler appliance can also limit the number
of session for a subscriber group to ensure fair distribution of resources among different subscriber
groups.

• Port quota. The NetScaler appliance can limit the LSN NAT ports to be used at a time by each
subscriber for a specified protocol. For example, you could limit each subscriber to a maxi-
mum of 500 TCP NAT ports. When the LSN NAT mappings for a subscriber reach the limit, the
NetScaler appliance does not allocate additional NAT ports of the specified protocol to that sub-
scriber.
• Subscriber Session Limit. The number of concurrent session for a subscriber can be more than
it port quota. The NetScaler appliance can limit the LSN sessions allowed for each subscriber
for a specified protocol. When the number of LSN sessions reaches the limit for a subscriber, the

© 1999-2018 Citrix Systems, Inc. All rights reserved. 268

NetScaler 12.0

NetScaler appliance does not allow the subscriber to open additional sessions of the specified
protocol.
• Group Session Limit. The NetScaler appliance can limit the total number of LSN sessions al-
lowed for a subscriber group for a specified protocol. When the total number of LSN sessions
reaches the limit for a group for a specified protocol, the NetScaler appliance does not allow any
subscriber of the group to open additional sessions of the specified protocol. For example, You
limit a group to a maximum of 10000 UDP sessions. When the total number of UDP sessions for
this group reaches 10000, the NetScaler appliance does not allow any subscriber of the group
to open additional UDP sessions.

Application Layer Gateways

For some Application layer protocols, the IP addresses and protocol port numbers are also communi-
cated in the packet’s payload. Application Layer Gateway for a protocol parses the packet’s payload
and does necessary changes to ensure that the protocol continues to work over LSN.

The NetScaler appliance supports ALG for the following protocols:

• FTP
• ICMP
• TFTP
• PPTP
• SIP
• RTSP

Hairpin Support

The NetScaler appliance supports communication between subscribers or internal hosts using NAT
IP addresses. This type of communication between two subscribers using NAT IP addresses is called
hairpin flow. Hairpin flow is enabled by default, and you cannot disable it.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Points to Consider before Configuring LSN

September 17, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 269

NetScaler 12.0

Contributed by:
C

Consider the following points before configuring LSN on a NetScaler appliance:

• Make sure that you understand the different components of Large Scale NAT, described in RFCs
6888, 5382, 5508, and 4787.
• Endpoint independent mapping (EIM) and endpoint independent filtering (EIF) are disabled by
default. These options must be enabled for proper functioning of VoIP and peer-to-peer (P2P)
applications.
• Logging LSN: Following are the consideration points for logging LSN information:
– Citrix recommends logging the LSN information on external log servers instead of on the
NetScaler appliance. Logging on external servers facilitates optimal performance when
the appliance creates large numbers of LSN log entries (in order of millions).
– Citrix recomends using SYSLOG over TCP, or NSLOG. By default SYSLOG uses UDP, and
NSLOG uses only TCP to transfer log information to the log servers. TCP is more reliable
than UDP for transferring complete data.
– The following limitations apply to SYSLOG over TCP:
* The Syslog over TCP solution does not provide authentication, integrity check, and
privacy.
* The NetScaler appliance relies on the TCP protocol to provide confirmation of SYSLOG
message delivery to external log servers.
• High Availability: Following are the consideration points for high availability of NetScaler ap-
pliances for LSN:
– Citrix recommends configuring the LSN feature in a high availability deployment of two
NetScaler appliances for uninterrupted and seamless operation of all LSN sessions.
– In a high availability deployment, Citrix recommends:
* Setting the SYNC VLAN parameter for dedicating a VLAN for all HA related communi-
cation.
* Synchronizing the symmetric RSS key of the primary node to the secondary node for
stateful synchronization of a large number of LSN mappings and sessions.
* Binding the subnet of LSN IP addresses to a VLAN to avoid flooding of GARP broadcasts
on all VLANs after a failover.
– In a high availability deployment of NetScaler appliances, ALG-related sessions are not
mirrored to the secondary appliance.
• Application Layer Gateways (ALGs): Following are the consideration points related for ALGs
on a NetScaler appliance:
– The following are not supported for SIP ALG:
* Multicast IP addresses
* Encrypted SDP
* SIP messages over TLS

© 1999-2018 Citrix Systems, Inc. All rights reserved. 270

NetScaler 12.0

* FQDN translation in SIP messages

* Authentication of SIP messages
* Traffic domains, admin partitions, andNetScaler clusters.
* SIP messages with multipart bodies.
– The following are not supported for RTSP ALG:
* Multicast RTSP sessions
* RTSP session over UDP
* NetScaler traffic domains, admin partitions, andNetScaler clusters
– The NetScaler appliance does not support ALG for the IPSec protocol.
• If you disable the LSN feature when some LSN sessions exist on the NetScaler appliance, these
sessions continue to exist for the duration of the configured timeout interval.
• LSN takes precedence over RNAT. If a packet from a specified LSN subscriber also matches a
RNAT rule, the packet is translated according to the LSN configuration.
• Forwarding of packets related only to the LSN sessions is based on the NetScaler appliance’s
routing table.
• Unlike with subnet IP addresses, selection of an LSN NAT IP address for a subscriber’s connec-
tion is not based on the routing entry for the destination IP address.
• For inbound packets, static LSN mappings take precedence over dynamic LSN mappings.
• For outbound packets, LSN application profiles take precedence over static mapping.
• When a large number of LSN sessions (> 1 million) exist on the NetScaler appliance, Citrix recom-
mends displaying selected LSN sessions instead of all of them. In the command line interface
or the configuration utility, use the selection parameters for showing LSN session operation.
• LSN is not supported in a NetScaler cluster.
• To reduce the amount of active memory allocated to the LSN feature, you must warm restart
the NetScaler appliance after changing the configured-memory setting. Without a warm restart,
you can only increase the amount of active memory.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Configuration Steps for LSN

September 17, 2018

Contributed by:
C

Configuring LSN on a NetScaler appliance consists of the following tasks:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 271

NetScaler 12.0

1. Set the global LSN parameters. Global parameters include the amount of NetScaler memory
reserved for the LSN feature and synchronization of LSN sessions in a high availability setup.
2. Create an LSN client entity and bind subscribers to it. An LSN client entity is a set of sub-
scribers on whose traffic you want the NetScaler appliance to perform LSN. The client entity
includes IPv4 addresses and extended ACL rules for identifying subscribers. An LSN client can
be bound to only one LSN group. The command line interface has two commands for creating
an LSN client entity and binding a subscriber to the LSN client entity. The configuration utility
combines these two operations on a single screen.
3. Create an LSN pool and bind NAT IP addresses to it. An LSN pool defines a pool of NAT IP ad-
dresses to be used by the NetScaler appliance to perform LSN. The pool is assigned parameters,
such as port block allocation and NAT type (Deterministic or Dynamic). An LSN pool bound to
an LSN group applies to all subscribers of an LSN client entity bound to the same group. Only
LSN Pools and LSN groups with the same NAT type settings can be bound together. Multiple LSN
pools can be bound to an LSN group. For Dynamic NAT, an LSN pool can be bound to multiple
LSN groups. For Deterministic NAT, pools bound to an LSN group cannot be bound to other LSN
groups. The command line interface has two commands for creating an LSN pool and binding
NAT IP addresses to the LSN pool. The configuration utility combines these two operations on
a single screen.
4. (Optional) Create an LSN Transport Profile for a specified protocol. An LSN transport pro-
file defines various timeouts and limits, such as maximum LSN sessions and maximum ports
usage, that a subscriber can have for a given protocol. You bind an LSN transport profile for
each protocol (TCP, UDP, and ICMP) to an LSN group. A profile can be bound to multiple LSN
groups. A profile bound to an LSN group applies to all subscribers of an LSN client bound to
the same group. By default, one LSN transport profile with default settings for TCP, UDP, and
ICMP protocols is bound to an LSN group during its creation. This profile is called default trans-
port profile. An LSN transport profile that you bind to an LSN group overrides the default LSN
transport profile for that protocol.
5. (Optional) Create an LSN Application Profile for a specified protocol and bind a set of des-
tination ports to it. An LSN application profile defines the LSN mapping and LSN filtering con-
trols of a group for a given protocol and for a set of destination ports. For a set of destination
ports, you bind an LSN profile for each protocol (TCP, UDP, and ICMP) to an LSN group. A profile
can be bound to multiple LSN groups. An LSN application profile bound to an LSN group applies
to all subscribers of an LSN client bound to the same group. By default, one LSN application pro-
file with default settings for TCP, UDP, and ICMP protocols for all destination ports is bound to
an LSN group during its creation. This profile is called a default application profile. When you
bind an LSN application profile, with a specified set of destination ports, to an LSN group, the
bound profile overrides the default LSN application profile for that protocol at that set of desti-
nation ports. The command line interface has two commands for creating an LSN application
profile and binding a set of destination ports to the LSN application profile. The configuration

© 1999-2018 Citrix Systems, Inc. All rights reserved. 272

NetScaler 12.0

utility combines these two operations on a single screen.

6. Create an LSN Group and bind LSN pools, (optional) LSN transport profiles, and (optional)
LSN application profiles to the LSN group. An LSN group is an entity consisting of an LSN
client, LSN pool(s), LSN transport profile(s), and LSN application profiles(s). A group is assigned
parameters, such as port block size and logging of LSN sessions. The parameter settings apply to
all the subscribers of an LSN client bound to the LSN group. Only LSN Pools and LSN groups with
the same NAT type settings can be bound together. Multiples LSN pools can be bound to an LSN
group. For Dynamic NAT, an LSN pool can be bound to multiple LSN groups. For Deterministic
NAT, pools bound to an LSN group cannot be bound to other LSN groups. Only one LSN client
entity can be bound to an LSN group, and an LSN client entity bound to an LSN group cannot
be bound to other LSN groups. The command line interface has two commands for creating an
LSN group and binding LSN pools, LSN transport profiles, LSN application profiles to the LSN
group. The configuration utility combines these two operations in a single screen.

The following table lists the maximum numbers of different LSN entities and bindings that can be
created on a NetScaler appliance. These limits are also subject to memory available on the NetScaler
appliance.

LSN entities and bindings Limit

LSN clients 1024

LSN pools 128
LSN groups 1024
Subscriber networks that can be bound to an 64
LSN client
Extended ACLs that can be bound to an LSN 1024
client
NAT IP addresses in a Pool 4096
LSN pools that can be bound to an LSN group 8
LSN groups that can use the same LSN pool 16
LSN transport profiles that can be bound to an 3 (one each for TCP, UDP, and ICMP protocols )
LSN group
LSN groups that can use same LSN transport 8
profile
LSN application profiles that can be bound to 64
an LSN group
LSN groups that can use same LSN application 8
profile

© 1999-2018 Citrix Systems, Inc. All rights reserved. 273

NetScaler 12.0

LSN entities and bindings Limit

Port ranges that can be bound to an LSN 8

application profile

Configuration Using the Command Line Interface

To create an LSN client by using the command line interface

At the command prompt, type:

1 add lsn client <clientname>

2
3 show lsn client

To bind a network address or an ACL rule to an LSN client by using the command line interface

At the command prompt, type:

1 bind lsn client <clientname> ((-network <ip_addr> [-netmask <netmask>]

[-td<positive_integer>]) | -aclname <string>)
2
3 show lsn client

To create an LSN pool by using the command line interface

At the command prompt, type:

1 add lsn pool <poolname> [-nattype ( DYNAMIC | DETERMINISTIC )] [-

portblockallocation ( ENABLED | DISABLED )] [-portrealloctimeout <
secs>] [-maxPortReallocTmq <positive_integer>]
2
3 show lsn pool

To bind an IP address range to an LSN pool by using the command line interface

At the command prompt, type:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 274

NetScaler 12.0

1 bind lsn pool <poolname> <lsnip>

2
3 show lsn pool

Note: For removing LSN IP addresses from an LSN pool, use the unbind lsn pool command.

To create an LSN transport profile by using the command line interface

At the command prompt, type:

1 add lsn transportprofile <transportprofilename> <transportprotocol> [-

sessiontimeout <secs>] [-finrsttimeout <secs>] [-portquota <
positive_integer>] [-sessionquota <positive_integer>] [-
portpreserveparity ( ENABLED | DISABLED )] [-portpreserverange (
ENABLED | DISABLED )] [-syncheck ( ENABLED | DISABLED )]
2
3 show lsn transportprofile

To create an LSN application profile by using the command line interface

At the command prompt, type:

1 add lsn appsprofile <appsprofilename> <transportprotocol> [-ippooling (

PAIRED | RANDOM )] [-mapping <mapping>] [-filtering <filtering>][-
tcpproxy ( ENABLED | DISABLED )] [-td <positive_integer>]
2
3 show lsn appsprofile

To bind an application protocol port range to an LSN application profile by using the command
line interface

At the command prompt, type:

1 bind lsn appsprofile <appsprofilename> <lsnport>

2
3 show lsn appsprofile

To create an LSN group by using the command line interface

At the command prompt, type:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 275

NetScaler 12.0

1 add lsn group <groupname> -clientname <string> [-nattype ( DYNAMIC |

DETERMINISTIC )] [-portblocksize <positive_integer>] [-logging (
ENABLED | DISABLED )] [-sessionLogging ( ENABLED | DISABLED )][-
sessionSync (ENABLED | DISABLED )] [-snmptraplimit <positive_integer
>] [-ftp ( ENABLED | DISABLED )]
2
3 show lsn group

To bind LSN profiles and LSN pools to an LSN group by using the command line interface

At the command prompt, type:

1 bind lsn group <groupname> (-poolname <string> | -transportprofilename 

<string> | -appsprofilename <string>)
2
3 show lsn group

Configuration Using the Configuration Utility

To configure an LSN client and bind an IPv4 network address or an ACL rule by using the configuration
utility

Navigate to System > Large Scale NAT > Clients, and add a client and then bind an IPv4 network
address or an ACL rule to the client.

To configure an LSN pool and bind NAT IP addresses by using the configuration utility

Navigate to System > Large Scale NAT > Pools, and add a pool and then bind an NAT IP address or a
range of NAT IP addresses to the pool.

To configure an LSN transport profile by using the configuration utility

1. Navigate to System > Large Scale NAT > Profiles.

2. On the details pane, click Transport tab, and then add a transport profile.

To configure an LSN application profile by using the configuration utility

1. Navigate to System > Large Scale NAT > Profiles.

2. On the details pane, click Application tab, and then add an application profile.

To configure an LSN group and bind an LSN client, pools, transport profiles, and application profiles
by using the configuration utility

Navigate to System > Large Scale NAT > Groups, and add a group and then bind an LSN client, pools,
transport profiles, and application profiles to the group.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 276

NetScaler 12.0

Parameter Descriptions (of commands listed in the CLI procedure)

• add lsn client

– clientname

Name for the LSN client entity. Must begin with an ASCII alphanumeric or underscore (_)
character, and must contain only ASCII alphanumeric, underscore, hash (#), period (.),
space, colon (:), at (@), equals (=), and hyphen (-) characters. Cannot be changed after
the LSN client is created. The following requirement applies only to the CLI: If the name
includes one or more spaces, enclose the name in double or single quotation marks (for
example, “lsn client1” or ‘lsn client1’).

This is a mandatory argument. Maximum Length: 127

Parameter Descriptions (of commands listed in the CLI procedure)

• bind lsn client

– clientname

Name for the LSN client entity. Must begin with an ASCII alphanumeric or underscore (_)
character, and must contain only ASCII alphanumeric, underscore, hash (#), period (.),
space, colon (:), at (@), equals (=), and hyphen (-) characters. Cannot be changed after
the LSN client is created. The following requirement applies only to the CLI: If the name
includes one or more spaces, enclose the name in double or single quotation marks (for
example, “lsn client1” or ‘lsn client1’).

This is a mandatory argument. Maximum Length: 127

– network

IPv4 address(es) of the LSN subscriber(s) or subscriber network(s) on whose traffic you
want the NetScaler appliance to perform Large Scale NAT.

– netmask

Subnet mask for the IPv4 address specified in the Network parameter.

Default value: 255.255.255.255

– td

ID of the traffic domain on which this subscriber or the subscriber network (as specified
by the network parameter) belongs.

If you do not specify an ID, the subscriber or the subscriber network becomes part of the
default traffic domain.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 277

NetScaler 12.0

Default value: 0

Minimum value: 0

Maximum value: 4094

– aclname

Name(s) of any configured extended ACL(s) whose action is ALLOW. The condition spec-
ified in the extended ACL rule identifies the traffic from an LSN subscriber for which the
NetScaler appliance is to perform large scale NAT. Maximum Length: 127

Parameter Descriptions (of commands listed in the CLI procedure)

• add lsn pool

– poolname

Name for the LSN pool. Must begin with an ASCII alphanumeric or underscore (_) char-
acter, and must contain only ASCII alphanumeric, underscore, hash (#), period (.), space,
colon (:), at (@), equals (=), and hyphen (-) characters. Cannot be changed after the LSN
pool is created. The following requirement applies only to the CLI: If the name includes
one or more spaces, enclose the name in double or single quotation marks (for example,
“lsn pool1” or ‘lsn pool1’).

This is a mandatory argument. Maximum Length: 127

– nattype

Type of NAT IP address and port allocation (from the LSN pools bound to an LSN group)
for subscribers (of the LSN client entity bound to the LSN group):

Available options function as follows:

* Deterministic—Allocate a NAT IP address and a block of ports to each subscriber (of

the LSN client bound to the LSN group). The NetScaler appliance sequentially allo-
cates NAT resources to these subscribers. The NetScaler appliance assigns the first
block of ports (block size determined by the port block size parameter of the LSN
group) on the beginning NAT IP address to the beginning subscriber IP address. The
next range of ports is assigned to the next subscriber, and so on, until the NAT address
does not have enough ports for the next subscriber. In this case, the first port block on
the next NAT address is used for the subscriber, and so on. Because each subscriber
now receives a deterministic NAT IP address and a block of ports, a subscriber can be
identified without any need for logging. For a connection, a subscriber can be iden-
tified based only on the NAT IP address and port, and the destination IP address and
port.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 278

NetScaler 12.0

* Dynamic—Allocate a random NAT IP address and a port from the LSN NAT pool for a
subscribers connection. If port block allocation is enabled (in LSN pool) and a port
block size is specified (in the LSN group), the NetScaler appliance allocates a random
NAT IP address and a block of ports for a subscriber when it initiates a connection
for the first time. The appliance allocates this NAT IP address and a port (from the
allocated block of ports) for different connections from this subscriber. If all the ports
are allocated (for different subscribers connections) from the subscribers allocated
port block, the appliance allocates a new random port block for the subscriber. Only
LSN Pools and LSN groups with the same NAT type settings can be bound together.
Multiples LSN pools can be bound to an LSN group.

Possible values: DYNAMIC, DETERMINISTIC

Default value: DYNAMIC

– portblockallocation

Allocate a random NAT port block, from the available NAT port pool of an NAT IP address,
for each subscriber when the NAT allocation is set as Dynamic NAT. For any connection ini-
tiated from a subscriber, the NetScaler appliance allocates a NAT port from the subscribers
allocated NAT port block to create the LSN session.

You must set the port block size in the bound LSN group. For a subscriber, if all the ports
are allocated from the subscribers allocated port block, the NetScaler appliance allocates
a new random port block for the subscriber.

For Deterministic NAT, this parameter is enabled by default, and you cannot disable it.

Possible values: ENABLED, DISABLED

Default value: DISABLED

– portrealloctimeout

The waiting time, in seconds, between deallocating LSN NAT ports (when an LSN mapping
is removed) and reallocating them for a new LSN session. This parameter is necessary in
order to prevent collisions between old and new mappings and sessions. It ensures that
all established sessions are broken instead of redirected to a different subscriber. This is
not applicable for ports used in:

* Deterministic NAT
* Address-Dependent filtering and Address-Port-Dependent filtering
* Dynamic NAT with port block allocation

In these cases, ports are immediately reallocated.

Default value: 0

Maximum value: 600

© 1999-2018 Citrix Systems, Inc. All rights reserved. 279

NetScaler 12.0

– maxPortReallocTmq

Maximum number of ports for which the port reallocation timeout applies for each NAT IP
address. In other words, the maximum deallocated-port queue size for which the reallo-
cation timeout applies for each NAT IP address.

When the queue size is full, the next port deallocated is reallocated immediately for a new
LSN session.

Default value: 65536

Maximum value: 65536

Parameter Descriptions (of commands listed in the CLI procedure)

• bind lsn pool

– poolname

Name for the LSN pool. Must begin with an ASCII alphanumeric or underscore (_) char-
acter, and must contain only ASCII alphanumeric, underscore, hash (#), period (.), space,
colon (:), at (@), equals (=), and hyphen (-) characters. Cannot be changed after the LSN
pool is created. The following requirement applies only to the CLI: If the name includes
one or more spaces, enclose the name in double or single quotation marks (for example,
“lsn pool1” or ‘lsn pool1’).

This is a mandatory argument. Maximum Length: 127

– lsnip

IPv4 address or a range of IPv4 addresses to be used as NAT IP address(es) for LSN.

After the pool is created, these IPv4 addresses are added to the NetScaler appliance as
NetScaler owned IP address of type LSN. An LSN IP address associated with an LSN pool
cannot be shared with other LSN pools. IP addresses specified for this parameter must
not already exist on the NetScaler appliance as any NetScaler owned IP addresses. In the
command line interface, separate the range with a hyphen. For example: 10.102.29.30-
10.102.29.189. You can later remove some or all the LSN IP addresses from the pool, and
add IP addresses to the LSN pool.

Parameter Descriptions (of commands listed in the CLI procedure)

• add lsn transportprofile

– transportprofilename

© 1999-2018 Citrix Systems, Inc. All rights reserved. 280

NetScaler 12.0

Name for the LSN transport profile. Must begin with an ASCII alphanumeric or underscore
(_) character, and must contain only ASCII alphanumeric, underscore, hash (#), period (.),
space, colon (:), at (@), equals (=), and hyphen (-) characters. Cannot be changed after the
LSN transport profile is created. The following requirement applies only to the CLI: If the
name includes one or more spaces, enclose the name in double or single quotation marks
(for example, “lsn transport profile1” or ‘lsn transport profile1’).

This is a mandatory argument. Maximum Length: 127

– transportprotocol

Protocol for which to set the LSN transport profile parameters.

This is a mandatory argument.

Possible values: TCP, UDP, ICMP

– sessiontimeout

Timeout, in seconds, for an idle LSN session. If an LSN session is idle for a time that exceeds
this value, the NetScaler appliance removes the session.

This timeout does not apply for a TCP LSN session when a FIN or RST message is received
from either of the endpoints.

Default value: 120

Minimum value: 60

– finrsttimeout

Timeout, in seconds, for a TCP LSN session after a FIN or RST message is received from one
of the endpoints.

f a TCP LSN session is idle (after the NetScaler appliance receives a FIN or RST message)
for a time that exceeds this value, the NetScaler appliance removes the session.

Since the LSN feature of the NetScaler appliance does not maintain state information of
any TCP LSN sessions, this timeout accommodates the transmission of the FIN or RST,
and ACK messages from the other endpoint so that both endpoints can properly close the
connection.

Default value: 30

– portquota

Maximum number of LSN NAT ports to be used at a time by each subscriber for the speci-
fied protocol. For example, each subscriber can be limited to a maximum of 500 TCP NAT
ports. When the LSN NAT mappings for a subscriber reach the limit, the NetScaler appli-
ance does not allocate additional NAT ports for that subscriber.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 281

NetScaler 12.0

Default value: 0

Minimum value: 0

Maximum value: 65535

– sessionquota

Maximum number of concurrent LSN sessions allowed for each subscriber for the spec-
ified protocol. When the number of LSN sessions reaches the limit for a subscriber, the
NetScaler appliance does not allow the subscriber to open additional sessions.

Default value: 0

Minimum value: 0

Maximum value: 65535

– portpreserveparity

Enable port parity between a subscriber port and its mapped LSN NAT port. For example,
if a subscriber initiates a connection from an odd numbered port, the NetScaler appliance
allocates an odd numbered LSN NAT port for this connection. You must set this parameter
for proper functioning of protocols that require the source port to be even or odd num-
bered, for example, in peer-to-peer applications that use RTP or RTCP protocol.

Possible values: ENABLED, DISABLED

Default value: DISABLED

– portpreserverange

If a subscriber initiates a connection from a well-known port (0-1023), allocate a NAT port
from the well-known port range (0-1023) for this connection. For example, if a subscriber
initiates a connection from port 80, the NetScaler appliance can allocate port 100 as the
NAT port for this connection.

This parameter applies to dynamic NAT without port block allocation. It also applies to
Deterministic NAT if the range of ports allocated includes well-known ports.

When all the well-known ports of all the available NAT IP addresses are used in different
subscribers connections (LSN sessions), and a subscriber initiates a connection from a
well- known port, the NetScaler appliance drops this connection.

Possible values: ENABLED, DISABLED

Default value: DISABLED

– syncheck

Silently drop any non-SYN packets for connections for which there is no LSN-NAT session
present on the NetScaler appliance.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 282

NetScaler 12.0

If you disable this parameter, the NetScaler appliance accepts any non-SYN packets and
creates a new LSN session entry for this connection.

Following are some reasons for the NetScaler appliance to receive such packets:

* LSN session for a connection existed but the NetScaler appliance removed this ses-
sion because the LSN session was idle for a time that exceeded the configured session
timeout.
* Such packets can be a part of a DoS attack.

Possible values: ENABLED, DISABLED

Default value: ENABLED

Parameter Descriptions (of commands listed in the CLI procedure)

• add lsn appsprofile

– appsprofilename

Name for the LSN application profile. Must begin with an ASCII alphanumeric or under-
score (_) character, and must contain only ASCII alphanumeric, underscore, hash (#), pe-
riod (.), space, colon (:), at (@), equals (=), and hyphen (-) characters. Cannot be changed
after the LSN application profile is created. The following requirement applies only to the
CLI: If the name includes one or more spaces, enclose the name in double or single quota-
tion marks (for example, “lsn application profile1” or ‘lsn application profile1’).

This is a mandatory argument. Maximum Length: 127

– transportprotocol

Name of the protocol for which the parameters of this LSN application profile applies.

This is a mandatory argument.

Possible values: TCP, UDP, ICMP

– ippooling

NAT IP address allocation options for sessions associated with the same subscriber.

Available options function as follows:

* Paired—The NetScaler appliance allocates the same NAT IP address for all sessions
associated with the same subscriber. When all the ports of a NAT IP address are used
in LSN sessions (for same or multiple subscribers), the NetScaler appliance drops any
new connection from the subscriber.
* Random—The NetScaler appliance allocates random NAT IP addresses, from the
pool, for different sessions associated with the same subscriber.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 283

NetScaler 12.0

This parameter is applicable to dynamic NAT allocation only.

Possible values: PAIRED, RANDOM

Default value: RANDOM

– mapping

Type of LSN mapping to apply to subsequent packets originating from the same subscriber
IP address and port.

Consider an example of an LSN mapping that includes the mapping of the subscriber
IP:port (X:x), NAT IP:port (N:n), and external host IP:port (Y:y).

Available options function as follows:

* ENDPOINT-INDEPENDENT—Reuse the LSN mapping for subsequent packets sent

from the same subscriber IP address and port (X:x) to any external IP address and
port.
* ADDRESS-DEPENDENT—Reuse the LSN mapping for subsequent packets sent from
the same subscriber IP address and port (X:x) to the same external IP address (Y), re-
gardless of the external port.
* ADDRESS-PORT-DEPENDENT—Reuse the LSN mapping for subsequent packets sent
from the same internal IP address and port (X:x) to the same external IP address and
port (Y:y) while the mapping is still active.

Possible values: ENDPOINT-INDEPENDENT, ADDRESS-DEPENDENT, ADDRESS-PORT-

DEPENDENT

Default value: ADDRESS-PORT-DEPENDENT

– filtering

Type of filter to apply to packets originating from external hosts.

Consider an example of an LSN mapping that includes the mapping of subscriber IP:port
(X:x), NAT IP:port (N:n), and external host IP:port (Y:y).

Available options function as follows:

* ENDPOINT INDEPENDENT—Filters out only packets not destined to the subscriber

IP address and port X:x, regardless of the external host IP address and port source
(Z:z). The NetScaler appliance forwards any packets destined to X:x. In other words,
sending packets from the subscriber to any external IP address is sufficient to allow
packets from any external hosts to the subscriber.
* ADDRESS DEPENDENT—Filters out packets not destined to subscriber IP address and
port X:x. In addition, the appliance filters out packets from Y:y destined for the sub-
scriber (X:x) if the client has not previously sent packets to Y:anyport (external port

© 1999-2018 Citrix Systems, Inc. All rights reserved. 284

NetScaler 12.0

independent). In other words, receiving packets from a specific external host requires
that the subscriber first send packets to that specific external host’s IP address.
* ADDRESS PORT DEPENDENT (the default)—Filters out packets not destined to sub-
scriber IP address and port (X:x). In addition, the NetScaler appliance filters out pack-
ets from Y:y destined for the subscriber (X:x) if the subscriber has not previously sent
packets to Y:y. In other words, receiving packets from a specific external host requires
that the subscriber first send packets first to that external IP address and port.

Possible values: ENDPOINT-INDEPENDENT, ADDRESS-DEPENDENT, ADDRESS-PORT-

DEPENDENT

Default value: ADDRESS-PORT-DEPENDENT

– tcpproxy

Enable TCP proxy, which enables the NetScaler appliance to optimize the TCP traffic by
using Layer 4 features.

Possible values: ENABLED, DISABLED

Default value: DISABLED

– td

ID of the traffic domain through which the NetScaler appliance sends the outbound traffic
after performing LSN.

If you do not specify an ID, the appliance sends the outbound traffic through the default
traffic domain, which has an ID of 0.

Default value: 65535

Maximum value: 65535

Parameter Descriptions (of commands listed in the CLI procedure)

• bind lsn appsprofile

– appsprofilename

Name for the LSN application profile. Must begin with an ASCII alphanumeric or under-
score (_) character, and must contain only ASCII alphanumeric, underscore, hash (#), pe-
riod (.), space, colon (:), at (@), equals (=), and hyphen (-) characters. Cannot be changed
after the LSN application profile is created. The following requirement applies only to the
CLI: If the name includes one or more spaces, enclose the name in double or single quota-
tion marks (for example, “lsn application profile1” or ‘lsn application profile1’).

This is a mandatory argument. Maximum Length: 127

© 1999-2018 Citrix Systems, Inc. All rights reserved. 285

NetScaler 12.0

– lsnport

Port numbers or range of port numbers to match against the destination port of the incom-
ing packet from a subscriber. When the destination port is matched, the LSN application
profile is applied for the LSN session. Separate a range of ports with a hyphen. For exam-
ple, 40-90.

Parameter Descriptions (of commands listed in the CLI procedure)

• add lsn group

– groupname

Name for the LSN group. Must begin with an ASCII alphanumeric or underscore (_) char-
acter, and must contain only ASCII alphanumeric, underscore, hash (#), period (.), space,
colon (:), at (@), equals (=), and hyphen (-) characters. Cannot be changed after the LSN
group is created. The following requirement applies only to the CLI: If the name includes
one or more spaces, enclose the name in double or single quotation marks (for example,
“lsn group1” or ‘lsn group1’).

This is a mandatory argument. Maximum Length: 127

– clientname

Name of the LSN client entity to be associated with the LSN group. You can associate only
one LSN client entity with an LSN group. You cannot remove this association or replace
with another LSN client entity once the LSN group is created.

This is a mandatory argument. Maximum Length: 127

– nattype

Type of NAT IP address and port allocation (from the bound LSN pools) for subscribers:

Available options function as follows:

* Deterministic—Allocate a NAT IP address and a block of ports to each subscriber (of

the LSN client bound to the LSN group). The NetScaler appliance sequentially allo-
cates NAT resources to these subscribers. The NetScaler appliance assigns the first
block of ports (block size determined by the port block size parameter of the LSN
group) on the beginning NAT IP address to the beginning subscriber IP address. The
next range of ports is assigned to the next subscriber, and so on, until the NAT address
does not have enough ports for the next subscriber. In this case, the first port block on
the next NAT address is used for the subscriber, and so on. Because each subscriber
now receives a deterministic NAT IP address and a block of ports, a subscriber can be

© 1999-2018 Citrix Systems, Inc. All rights reserved. 286

NetScaler 12.0

identified without any need for logging. For a connection, a subscriber can be iden-
tified based only on the NAT IP address and port, and the destination IP address and
port.
* Dynamic—Allocate a random NAT IP address and a port from the LSN NAT pool for a
subscriber’s connection. If port block allocation is enabled (in LSN pool) and a port
block size is specified (in the LSN group), the NetScaler appliance allocates a random
NAT IP address and a block of ports for a subscriber when it initiates a connection
for the first time. The appliance allocates this NAT IP address and a port (from the
allocated block of ports) for different connections from this subscriber. If all the ports
are allocated (for different subscribers connections) from the subscribers allocated
port block, the appliance allocates a new random port block for the subscriber.

Possible values: DYNAMIC, DETERMINISTIC

Default value: DYNAMIC

– portblocksize

Size of the NAT port block to be allocated for each subscriber.

To set this parameter for Dynamic NAT, you must enable the port block allocation param-
eter in the bound LSN pool. For Deterministic NAT, the port block allocation parameter is
always enabled, and you cannot disable it.

In Dynamic NAT, the NetScaler appliance allocates a random NAT port block, from the avail-
able NAT port pool of an NAT IP address, for each subscriber. For a subscriber, if all the
ports are allocated from the subscribers allocated port block, the appliance allocates a
new random port block for the subscriber.

– logging

Log mapping entries and sessions created or deleted for this LSN group. The NetScaler
appliance logs LSN sessions for this LSN group only when both logging and session logging
parameters are enabled.

The appliance uses its existing syslog and audit log framework to log LSN information. You
must enable global level LSN logging by enabling the LSN parameter in the related NSLOG
action and SYLOG action entities. When the Logging parameter is enabled, the NetScaler
appliance generates log messages related to LSN mappings and LSN sessions of this LSN
group. The appliance then sends these log messages to servers associated with the NSLOG
action and SYSLOG actions entities.

A log message for an LSN mapping entry consists of the following information:

* NSIP address of the NetScaler appliance

* Time stamp
* Entry type (MAPPING or SESSION)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 287

NetScaler 12.0

* Whether the LSN mapping entry is created or deleted

* Subscriber’s IP address, port, and traffic domain ID
* NAT IP address and port
* Protocol name
* Destination IP address, port, and traffic domain ID might be present, depending on
the following conditions:
· Destination IP address and port are not logged for Endpoint-Independent map-
ping
· Only Destination IP address (and not port) is logged for Address-Dependent map-
ping
· Destination IP address and port are logged for Address-Port-Dependent mapping

Possible values: ENABLED, DISABLED

Default value: DISABLED

– sessionLogging

Log sessions created or deleted for the LSN group. The NetScaler appliance logs LSN ses-
sions for this LSN group only when both logging and session logging parameters are en-
abled.

A log message for an LSN session consists of the following information:

* NSIP address of the NetScaler appliance

* Time stamp
* Entry type (MAPPING or SESSION)
* Whether the LSN session is created or removed
* Subscriber’s IP address, port, and traffic domain ID
* NAT IP address and port
* Protocol name
* Destination IP address, port, and traffic domain ID

Possible values: ENABLED, DISABLED

Default value: DISABLED

– sessionSync

In a high availability (HA) deployment, synchronize information of all LSN sessions related
to this LSN group with the secondary node. After a failover, established TCP connections
and UDP packet flows are kept active and resumed on the secondary node (new primary).

For this setting to work, you must enable the global session synchronization parameter.

Possible values: ENABLED, DISABLED

Default value: ENABLED

© 1999-2018 Citrix Systems, Inc. All rights reserved. 288

NetScaler 12.0

– snmptraplimit
Maximum number of SNMP Trap messages that can be generated for the LSN group in one
minute.
Default value: 100
Minimum value: 0
Maximum value: 10000
– ftp
Enable Application Layer Gateway (ALG) for the FTP protocol. For some application-layer
protocols, the IP addresses and protocol port numbers are usually communicated in the
packets payload. When acting as an ALG, the appliance changes the packets payload to
ensure that the protocol continues to work over LSN.
Note: The NetScaler appliance also includes ALG for ICMP and TFTP protocols. ALG for the
ICMP protocol is enabled by default, and there is no provision to disable it. ALG for the
TFTP protocol is disabled by default. ALG is enabled automatically for an LSN group when
you bind a UDP LSN application profile, with endpoint-independent-mapping, endpoint-
independent filtering, and destination port as 69 (well-known port for TFTP), to the LSN
group.
Possible values: ENABLED, DISABLED
Default value: ENABLED

Parameter Descriptions (of commands listed in the CLI procedure)

• bind lsn group

– groupname
Name for the LSN group. Must begin with an ASCII alphanumeric or underscore (_) char-
acter, and must contain only ASCII alphanumeric, underscore, hash (#), period (.), space,
colon (:), at (@), equals (=), and hyphen (-) characters. Cannot be changed after the LSN
group is created. The following requirement applies only to the CLI: If the name includes
one or more spaces, enclose the name in double or single quotation marks (for example,
“lsn group1” or ‘lsn group1’).
This is a mandatory argument. Maximum Length: 127
– poolname
Name of the LSN pool to bind to the specified LSN group. Only LSN Pools and LSN groups
with the same NAT type settings can be bound together. Multiples LSN pools can be bound
to an LSN group.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 289

NetScaler 12.0

For Deterministic NAT, pools bound to an LSN group cannot be bound to other LSN groups.
For Dynamic NAT, pools bound to an LSN group can be bound to multiple LSN groups.
Maximum Length: 127

– transportprofilename

Name of the LSN transport profile to bind to the specified LSN group. Bind a profile for
each protocol for which you want to specify settings.

By default, one LSN transport profile with default settings for TCP, UDP, and ICMP protocols
is bound to an LSN group during its creation. This profile is called a default transport.

An LSN transport profile that you bind to an LSN group overrides the default LSN transport
profile for that protocol. Maximum Length: 127

– appsprofilename

Name of the LSN application profile to bind to the specified LSN group. For each set of
destination ports, bind a profile for each protocol for which you want to specify settings.

By default, one LSN application profile with default settings for TCP, UDP, and ICMP pro-
tocols for all destination ports is bound to an LSN group during its creation. This profile is
called a default application profile.

When you bind an LSN application profile, with a specified set of destination ports, to an
LSN group, the bound profile overrides the default LSN application profile for that protocol
at that set of destination ports. Maximum Length: 127

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Sample LSN Configurations

September 17, 2018

Contributed by:
C

The following are examples of configuring LSN through command line interface.

Create a simple LSN configuration with a single subscriber network, single LSN NAT IP address,
and default settings:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 290

NetScaler 12.0

1 add lsn client LSN-CLIENT-1

2
3 Done
4
5 bind lsn client LSN-CLIENT-1 -network 192.0.2.0 -netmask 255.255.255.0
6
7 Done
8
9 add lsn pool LSN-POOL-1
10
11 Done
12
13 bind lsn pool LSN-POOL-1 203.0.113.3
14
15 Done
16
17 add lsn group LSN-GROUP-1 -clientname LSN-CLIENT-1
18
19 Done
20
21 bind lsn group LSN-GROUP-1 -poolname pool1 LSN-POOL-1
22
23 Done

Create an LSN configuration with an extended ACL for identifying LSN subscribers:

1 add ns acl LSN-ACL-2 ALLOW -srcIP 192.0.2.10-192.0.2.20

2
3 Done
4
5 apply acls
6
7 Done
8
9 add lsn client LSN-CLIENT-2
10
11 Done
12
13 bind lsn client LSN-CLIENT-2 ‒ aclname LSN-ACL-2
14
15 Done
16
17 add lsn pool LSN-POOL-2
18

© 1999-2018 Citrix Systems, Inc. All rights reserved. 291

NetScaler 12.0

19 Done
20
21 bind lsn pool LSN-POOL-2 203.0.113.5-203.0.113.10
22
23 Done
24
25 add lsn group LSN-GROUP-2 -clientname LSN-CLIENT-2
26
27 Done
28
29 bind lsn group LSN-GROUP-2 -poolname LSN-POOL-2
30
31 Done

Create an LSN configuration with endpoint-independent mapping for HTTP protocol (port 80)
and address-port dependent mapping for SSH protocol (port 22). Also, restrict each subscriber
to use a maximum of 1000 NAT ports for TCP protocol and 100 NAT ports for UDP protocol. Re-
strict each subscriber to have a maximum of 2000 concurrent sessions for TCP protocol. Restrict
the group to have a maximum of 30000 concurrent sessions for TCP protocol:

1 add lsn client LSN-CLIENT-3

2
3 Done
4
5 bind lsn client LSN-CLIENT-3 -network 192.0.3.0 -netmask 255.255.255.0
6
7 Done
8
9 add lsn pool LSN-POOL-3
10
11 Done
12
13 bind lsn pool LSN-POOL-3 203.0.113.11
14
15 Done
16
17 add lsn group LSN-GROUP-3 -clientname LSN-CLIENT-3
18
19 Done
20
21 bind lsn group LSN-GROUP-3 -poolname LSN-POOL-3
22
23 Done
24

© 1999-2018 Citrix Systems, Inc. All rights reserved. 292

NetScaler 12.0

25 add lsn appsprofile LSN-APPS-HTTPPROFILE-3 TCP -mapping ENDPOINT-

INDEPENDENT
26
27 Done
28
29 bind lsn appsprofile LSN-APPS-HTTPPROFILE-3 80
30
31 Done
32
33 bind lsn group LSN-GROUP-3 -applicationprofilename LSN-APPS-HTTPPROFILE
-3
34
35 Done
36
37 add lsn appsprofile LSN-APPS-SSHPROFILE-3 TCP -mapping ADDRESS-PORT-
DEPENDENT
38
39 Done
40
41 bind lsn appsprofile LSN-APPS-SSHPROFILE-3 22
42
43 Done
44
45 bind lsn group LSN-GROUP-3 -applicationprofilename LSN-APPS-SSHPROFILE
-3
46
47 Done
48
49 add lsn transportprofile LSN-TRANS-PROFILE-TCP-3 TCP -portquota 1000 -
sessionquota 2000 -groupSessionLimit 30000
50
51 Done
52
53 bind lsn group LSN-GROUP-3 -transportprofilename LSN-TRANS-PROFILE-TCP
-3
54
55 Done
56
57 add lsn transportprofile LSN-TRANS-PROFILE-UDP-3 UDP -portquota 100
58
59 Done
60
61 bind lsn group LSN-GROUP-3 -transportprofilename LSN-TRANS-PROFILE-UDP
-3
62

© 1999-2018 Citrix Systems, Inc. All rights reserved. 293

NetScaler 12.0

63 Done

Create an LSN configuration for a large set of subscribers:

1 add lsn client LSN-CLIENT-4

2
3 Done
4
5 bind lsn client LSN-CLIENT-4 -network 192.0.4.0 -netmask 255.255.255.0
6
7 Done
8
9 bind lsn client LSN-CLIENT-4 -network 192.0.5.0 -netmask 255.255.255.0
10
11 Done
12
13 bind lsn client LSN-CLIENT-4 -network 192.0.6.0 -netmask 255.255.255.0
14
15 Done
16
17 bind lsn client LSN-CLIENT-4 -network 192.0.7.0 -netmask 255.255.255.0
18
19 Done
20
21 bind lsn client LSN-CLIENT-4 -network 192.0.8.0 -netmask 255.255.255.0
22
23 Done
24
25 add lsn pool LSN-POOL-4
26
27 Done
28
29 bind lsn pool LSN-POOL-4 203.0.113.30-203.0.113.40
30
31 Done
32
33 bind lsn pool LSN-POOL-4 203.0.113.45-203.0.113.50
34
35 Done
36
37 bind lsn pool LSN-POOL-4 203.0.113.55-203.0.113.60
38
39 Done
40
41 add lsn group LSN-GROUP-4 -clientname LSN-CLIENT-4

© 1999-2018 Citrix Systems, Inc. All rights reserved. 294

NetScaler 12.0

42
43 Done
44
45 bind lsn group LSN-GROUP-4 -poolname LSN-POOL-4
46
47 Done
48
49 add lsn appsprofile LSN-APPS-WELLKNOWNPROFILE-4 TCP -mapping ENDPOINT-
INDEPENDENT
50
51 Done
52
53 bind lsn appsprofile LSN-APPS-WELLKNOWN-PORTS-PROFILE-4 1- 1023
54
55 Done
56
57 bind lsn group LSN-GROUP-4 -applicationprofilename LSN-APPS-WELLKNOWN-
PORTS-PROFILE-4
58
59 Done

Create an LSN configuration with sharing of NAT resources among multiple LSN groups. In this
example, LSN pool LSN-POOL-5 is shared with LSN groups LSN-GROUP-5 and LSN-GROUP-6:

1 add lsn client LSN-CLIENT-5

2
3 Done
4
5 bind lsn client LSN-CLIENT-5 -network 192.0.15.0 -netmask 255.255.255.0
6
7 Done
8
9 add lsn pool LSN-POOL-5
10
11 Done
12
13 bind lsn pool LSN-POOL-5 203.0.113.12-203.0.113.14
14
15 Done
16
17 add lsn group LSN-GROUP-5 -clientname LSN-CLIENT-5
18
19 Done
20
21 bind lsn group LSN-GROUP-5 -poolname LSN-POOL-5

© 1999-2018 Citrix Systems, Inc. All rights reserved. 295

NetScaler 12.0

22
23 Done
24
25 add lsn client LSN-CLIENT-6
26
27 Done
28
29 bind lsn client LSN-CLIENT-6 -network 192.0.16.0 -netmask 255.255.255.0
30
31 Done
32
33 add lsn pool LSN-POOL-6
34
35 Done
36
37 bind lsn pool LSN-POOL-6 203.0.113.15-203.0.113.18
38
39 Done
40
41 add lsn group LSN-GROUP-6 -clientname LSN-CLIENT-6
42
43 Done
44
45 bind lsn group LSN-GROUP-6 -poolname LSN-POOL-6
46
47 Done
48
49 bind lsn group LSN-GROUP-6 -poolname LSN-POOL-5
50
51 Done

Create an LSN configuration with deterministic NAT resource allocation:

1 add lsn client LSN-CLIENT-7

2
3 Done
4
5 bind lsn client LSN-CLIENT-7 -network 192.0.17.0 -netmask 255.255.255.0
6
7 Done
8
9 add lsn pool LSN-POOL-7 -nattype DETERMINISTIC
10
11 Done
12

© 1999-2018 Citrix Systems, Inc. All rights reserved. 296

NetScaler 12.0

13 bind lsn pool LSN-POOL-7 203.0.113.19-203.0.113.23

14
15 Done
16
17 add lsn group LSN-GROUP-7 -clientname LSN-CLIENT-7 -nattype
DETERMINISTIC -portblocksize 1024
18
19 Done
20
21 bind lsn group LSN-GROUP-7 -poolname LSN-POOL-7
22
23 Done

Create an LSN configuration with multiple subscriber networks having the same network ad-
dress but each network belonging to a different traffic domain. Also, restrict the outbound traf-
fic related to HTTP protocol (port 80), sending it through a particular traffic domain (td 5):

1 add lsn client LSN-CLIENT-8

2
3 Done
4
5 bind lsn client LSN-CLIENT-8 -network 192.0.18.0 -netmask 255.255.255.0
-td 1
6
7 Done
8
9 bind lsn client LSN-CLIENT-8 -network 192.0.18.0 -netmask 255.255.255.0
-td 2
10
11 Done
12
13 bind lsn client LSN-CLIENT-8 -network 192.0.18.0 -netmask 255.255.255.0
-td 3
14
15 Done
16
17 add lsn pool LSN-POOL-8
18
19 Done
20
21 bind lsn pool LSN-POOL-8 203.0.113.80-203.0.113.86
22
23 Done
24
25 add lsn group LSN-GROUP-8 -clientname LSN-CLIENT-8

© 1999-2018 Citrix Systems, Inc. All rights reserved. 297

NetScaler 12.0

26
27 Done
28
29 bind lsn group LSN-GROUP-8 -poolname LSN-POOL-8
30
31 Done
32
33 add lsn appsprofile LSN-APPS-HTTP-PROFILE-8 TCP -td 5
34
35 Done
36
37 bind lsn appsprofile LSN-APPS-HTTP-PROFILE-8 80
38
39 Done
40
41 bind lsn group LSN-GROUP-8 -applicationprofilename LSN-APPS-HTTP-
PROFILE-8
42
43 Done

Create an LSN configuration that restricts the outbound traffic of a specific protocol (TCP), send-
ing it through a particular traffic domain (td 5). With endpoint-independent filtering, receive
inbound traffic related to this protocol (TCP) on any traffic domain:

1 add lsn client LSN-CLIENT-9

2
3 Done
4
5 bind lsn client LSN-CLIENT-9 -network 192.0.9.0 -netmask 255.255.255.0
-td 1
6
7 Done
8
9 add lsn pool LSN-POOL-9
10
11 Done
12
13 bind lsn pool LSN-POOL-9 203.0.113.90
14
15 Done
16
17 add lsn group LSN-GROUP-9 -clientname LSN-CLIENT-9
18
19 Done
20

© 1999-2018 Citrix Systems, Inc. All rights reserved. 298

NetScaler 12.0

21 bind lsn group LSN-GROUP-9 -poolname LSN-POOL-9

22
23 Done
24
25 add lsn appsprofile LSN-APPS-PROFILE-9 TCP -filtering ENDPOINT-
INDEPENDENT -td 5
26
27 Done
28
29 bind lsn group LSN-GROUP-9 -approfile LSN-APPS-PROFILE-9
30
31 Done

Create an LSN configuration that restricts outbound HTTP (port 80) traffic, sending it through a
particular traffic domain (td 10). With address-dependent filtering, receive inbound traffic re-
lated to this protocol (HTTP) on the specified traffic domain (td 10):

1 add lsn client LSN-CLIENT-10

2
3 Done
4
5 bind lsn client LSN-CLIENT-10 -network 192.0.10.0 -netmask
255.255.255.0 -td 1
6
7 Done
8
9 add lsn pool LSN-POOL-10
10
11 Done
12
13 bind lsn pool LSN-POOL-10 203.0.113.100
14
15 Done
16
17 add lsn group LSN-GROUP-10 -clientname LSN-CLIENT-10
18
19 Done
20
21 bind lsn group LSN-GROUP-10 -poolname LSN-POOL-10
22
23 Done
24
25 add lsn appsprofile LSN-APPS-PROFILE-10 TCP -mapping ENDPOINT -
INDEPENDENT -filtering ADDRESS-DEPENDENT -td 10
26

© 1999-2018 Citrix Systems, Inc. All rights reserved. 299

NetScaler 12.0

27 Done
28
29 bind lsn appsprofile LSN-APPS-PROFILE-10 80
30
31 Done
32
33 bind lsn group LSN-GROUP-10 -approfile LSN-APPS-PROFILE-10
34
35 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Configuring Static LSN Maps

September 17, 2018

Contributed by:
C

The NetScaler appliance supports manual creation of a one-to-one LSN mapping between a sub-
scriber IP address:port and a NAT IP address:port. Static LSN mappings are useful in cases where you
want to ensure that the connections initiated to a NAT IP:Port maps to the subscriber IP address:Port.
For example, Web servers located in the internal network.

To create a static LSN mapping by using the command line interface

At the command prompt, type:

1 add lsn static <name> <transportprotocol> <subscrIP> <subscrPort> [-td

<positive_integer>] [<natIP> [<natPort>]] [-destIP <ip_addr> [-dsttd
<positive_integer>]]
2
3 - show lsn static

To create a static LSN mapping by using the configuration utility

Navigate to System > Large Scale NAT > Static, and add a new static mapping.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 300

NetScaler 12.0

Parameter Descriptions (of commands listed in the CLI procedure)

add lsn static name

Name for the LSN static mapping entry. Must begin with an ASCII alphanumeric or underscore (_)
character, and must contain only ASCII alphanumeric, underscore, hash (#), period (.), space, colon
(:), at (@), equals (=), and hyphen (-) characters. Cannot be changed after the LSN group is created.
The following requirement applies only to the CLI: If the name includes one or more spaces, enclose
the name in double or single quotation marks (for example, “lsn static1” or ‘lsn static1’). This is a
mandatory argument. Maximum Length: 127

transportprotocol

Protocol for the LSN mapping entry. This is a mandatory argument. Possible values: TCP, UDP, ICMP

subscrIP

IPv4 address of an LSN subscriber for the LSN mapping entry. This is a mandatory argument.

subscrPort

Port of the LSN subscriber for the LSN mapping entry. This is a mandatory argument. Maximum value:
65535

td

ID of the traffic domain to which the subscriber belongs. If you do not specify an ID, the subscriber
is assumed to be a part of the default traffic domain. Default value: 0, Minimum value: 0, Maximum
value: 4094

natIP

IPv4 address, already existing on the NetScaler appliance as type LSN, to be used as NAT IP address
for this mapping entry.

natPort

NAT port for this LSN mapping entry.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 301

NetScaler 12.0

destIP

Destination IP address for the LSN mapping entry.

dsttd

ID of the traffic domain through which the destination IP address for this LSN mapping entry is reach-
able from the NetScaler appliance. If you do not specify an ID, the destination IP address is assumed
to be reachable through the default traffic domain, which has an ID of 0. Default value: 0, Minimum
value: 0, Maximum value: 4094

Wildcard Port Static Maps

A static mapping entry is usually a one-to-one LSN mapping between a subscriber IP address:port and
a NAT IP address:port. A one-to-one static LSN mapping entry exposes only one port of the subscriber
to the Internet.

Some situations might require exposing all ports (64K) of a subscriber to the Internet (for example,
a server hosted on an internal network and running a different service on each port). To make these
internal services accessible through the Internet, you have to expose all the ports of the server to
the Internet.

One way to meet this requirement is to add 64K one-to-one static mapping entries, one mapping
entry for each port. Creating 64K entries is very cumbersome and a big task. Also, this large number
of configuration entries might lead to performance issues in the NetScaler appliance.

Another simple method is to use wildcard ports in a static mapping entry. You just need to create
one static mapping entry with NAT-port and subscriber-port parameters set to the wildcard charac-
ter (*), and the protocol parameter set to ALL, to expose all the ports of a subscriber to the Internet.
For a subscriber’s inbound or outbound connections matching a wildcard static mapping entry, the
subscriber’s port does not change after the NAT operation.

When a subscriber-initiated connection to the Internet matches a wildcard static mapping entry, the
NetScaler appliance assigns a NAT port that has the same number as the subscriber port from which
the connection is initiated. Similarly, an Internet host gets connected to a subscriber’s port by con-
necting to the NAT port that has the same number as the subscriber’s port.

Configuring the NetScaler appliance to Provide Access to All Ports of an IPv4 Subscriber

To configure the NetScaler appliance to provide access to all ports of an IPv4 subscriber, create a wild-
card static map with the following mandatory parameter settings:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 302

NetScaler 12.0

• Protocol=ALL
• Subscriber port = *
• NAT port = *
In a wildcard static map, unlike in a one-to-one static map, setting the NAT IP parameter is mandatory.
Also, the NAT IP address assigned to a wildcard static map cannot be used for any other subscribers.
To create a wildcard static map by using the command line interface
At the command prompt, type:

1 add lsn static <name> ALL <subscrIP> *  <natIP> * [-td <

positive_integer>] [-destIP <ip_addr> [-dsttd <positive_integer>]]
2
3 show lsn static

Sample Configuration

In the following sample configuration of a wildcard static map, all ports of a subscriber whose IP ad-
dress is 192.0.2.10 are made accessible through NAT IP 203.0.11.33.
Sample configuration:

1 add lsn static NAT44-WILDCARD-STATIC-1 ALL  192.0.2.10 * 203.0.113.33 *

2
3 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Configuring Application Layer Gateways

September 17, 2018

Contributed by:
C
For some Application layer protocols, the IP addresses and protocol port numbers are also communi-
cated in the packet’s payload. Application Layer Gateway for a protocol parses the packet’s payload
and does necessary changes to ensure that the protocol continues to work over LSN.
The NetScaler appliance supports ALG for the following protocols:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 303

NetScaler 12.0

• FTP
• ICMP
• TFTP
• PPTP
• SIP
• RTSP

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Application Layer Gateway for FTP, ICMP, and TFTP Protocols

September 17, 2018

Contributed by:
C

You can enable or disable ALG for the FTP protocol for an LSN configuration by enabling or disabling
the FTP option of the LSN group of the LSN configuration.

ALG for the ICMP protocol is enabled by default, and there is no provision to disable it.

ALG for the TFTP protocol is disabled by default. TFTP ALG is enabled automatically for an LSN configu-
ration when you bind a UDP LSN application profile, with endpoint-independent-mapping, endpoint-
independent filtering, and destination port as 69 (well-known port for TFTP), to the LSN group.

Sample LSN Configuration for FTP ALG:

In the following sample LSN configuration, FTP ALG is enabled for subscribers that have IP address in
the range 192.0.2.30-192.0.2.100.

1 add ns acl LSN-ACL-1 ALLOW -srcIP 192.0.2.30-192.0.2.100
2
3 Done
4
5 apply acls
6
7 Done
8
9 add lsn client LSN-CLIENT-1
10
11 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 304

NetScaler 12.0

12
13 bind lsn client LSN-CLIENT-1  ‒ aclname LSN-ACL
14
15 Done
16
17 add lsn pool LSN-POOL-1
18
19 Done
20
21 bind lsn pool LSN-POOL-1 203.0.113.10
22
23 Done
24
25 add lsn group LSN-GROUP-1 -clientname LSN-CLIENT-1  -FTP ENABLED
26
27 Done
28
29 bind lsn group LSN-GROUP-1 -poolname pool1 LSN-POOL-1
30
31 Done

Sample LSN Configuration for TFTP ALG:

In the following sample LSN configuration, endpoint-independent mapping and endpoint-

independent filtering are enabled for TFTP protocol (UDP port 69). The NetScaler appliance
automatically enables TFTP ALG for this LSN configuration.

1 add lsn client LSN-CLIENT-2
2
3 Done
4
5 bind lsn client LSN-CLIENT-2 -network 198.51.100.0 -netmask 255
.255.255.0
6
7 Done
8
9 add lsn pool LSN-POOL-2
10
11 Done
12
13 bind lsn pool LSN-POOL-2 203.0.113.10-203.0.113.11
14
15 Done
16
17 add lsn group LSN-GROUP-2 -clientname LSN-CLIENT-2

© 1999-2018 Citrix Systems, Inc. All rights reserved. 305

NetScaler 12.0

18
19 Done
20
21 bind lsn group LSN-GROUP-2 -poolname pool1 LSN-POOL-2
22
23 Done
24
25 add lsn appsprofile LSNAPPSPROFILE-TFTP-2 UDP -mapping ENDPOINT-
INDEPENDENT  ‒ filtering  ENDPOINT-INDEPENDENT
26
27 Done
28
29 bind lsn appsprofile LSNAPPSPROFILE-TFTP-2 69
30
31 Done
32
33 bind lsn group LSN-GROUP-1 -applicationprofilename LSNAPPSPROFILE-TFTP
-2
34
35 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Application Layer Gateway for PPTP Protocol

September 17, 2018

Contributed by:
C

The NetScaler appliance supports Application Layer Gateways (ALGs) for the Point-to-Point Tunneling
Protocol (PPTP).

PPTP is a network protocol that enables secure transfer of data from a remote client to an enterprise
server by creating a tunnel across TCP/IP-based data networks. PPTP encapsulates PPP packets into
IP packets for transmission over the Internet. PPTP establishes a tunnel for each communicating
PPTP network server (PNS)-PPTP Access Concentrator (PAC) pair. After the tunnel is set up, enhanced
generic routing encapsulation (GRE) is used to exchange PPP packets. A call ID in the GRE header
indicates the session to which a particular PPP packet belongs.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 306

NetScaler 12.0

The NetScaler appliance recognizes PPTP packets that arrive on the default TCP port, 1723. The appli-
ance parses PPTP control packets, translates the call ID, and assigns a NAT IP address. For two-way
data communication between the client and server, the NetScaler appliance creates an LSN session
entry based on the server call ID, and an LSN session based on the client call ID. The appliance then
parses the GRE data packets and translates call IDs on the basis of the two LSN session entries.

For PPTP protocol, the NetScaler appliance also includes timeout setting for any idle PPTP LSN ses-
sions. If a PPTP LSN session is idle for a time that exceeds the timeout setting, the NetScaler appliance
removes the session.

Limitations:

The following are the limitations of PPTP ALG on a NetScaler appliance:

• PPTP ALG is not supported for hairpin LSN flow.

• PPTP ALG is not supported to work with any RNAT configuration.
• PPTP ALG is not supported inNetScaler clusters.

Configuring PPTP ALG

Configuring PPTP ALG on the NetScaler appliance consist of the following tasks:

• Create an LSN configuration and enable PPTP ALG on it. In an LSN configuration, the LSN group
includes the PPTP ALG setting. For instructions on creating an LSN configuration, see Configu-
ration Steps for LSN.
• (Optional) Set the global timeout for idle PPTP LSN sessions.

To enable PPTP ALG for an LSN configuration by using the CLI

At the command prompt, type:

1 add lsn group <groupname> -clientname <string> [-pptp ( ENABLED |

DISABLED )]
2
3 show lsn group

To set the global timeout for idle PPTP LSN sessions by using the CLI

At the command prompt, type:

1 set appAlgParam -pptpGreIdleTimeout <positive_integer>
2
3 show appAlgParam

© 1999-2018 Citrix Systems, Inc. All rights reserved. 307

NetScaler 12.0

Example:

In the following sample LSN configuration, PPTP ALG is enabled for subscribers in the 192.0.2.0/24
network.

Also idle PPTP LSN session timeout is set to 200 secs.

1 add lsn client LSN-CLIENT-1

2
3 Done
4
5 bind lsn client LSN-CLIENT-1 -network 192.0.2.0 -netmask 255.255.255.0
6
7 Done
8
9 add lsn pool LSN-POOL-1
10
11 Done
12
13 bind lsn pool LSN-POOL-1 203.0.113.3
14
15 Done
16
17 add lsn group LSN-GROUP-1 -clientname LSN-CLIENT-1  -pptp ENABLED
18
19 Done
20
21 bind lsn group LSN-GROUP-1 -poolname pool1 LSN-POOL-1
22
23 Done
24
25 set appAlgParam -pptpGreIdleTimeout 200
26
27 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Application Layer Gateway for SIP Protocol

January 6, 2019

© 1999-2018 Citrix Systems, Inc. All rights reserved. 308

NetScaler 12.0

Contributed by:
C

Using Large Scale NAT (LSN) with Session Initiation Protocol (SIP) is complicated, because SIP mes-
sages contain IP addresses in the SIP headers as well as in the SIP body. When LSN is used with SIP,
the SIP headers contain information about the caller and the receiver, and the device translates this
information to hide it from the outside network. The SIP body contains the Session Description Proto-
col (SDP) information, which includes IP addresses and port numbers for transmission of the media.

SIP ALG adheres to the following RFCs:

• RFC 3261
• RFC 3581
• RFC 4566
• RFC 4475

How SIP ALG Works

How IP address translation is performed depends on the type and direction of the message. A message
can be any of the following:

• Inbound request
• Outbound response
• Outbound request
• Inbound response

For an outgoing message, the private IP address and port number of the SIP client are replaced with
the NetScaler owned public IP address and port number, called the LSN pool IP address and port num-
ber, specified during LSN configuration. For an incoming message, the LSN pool IP address and the
port number are replaced with the private address of the client. If the message contains any public IP
addresses, the NetScaler SIP ALG retains them. Also, a pinhole is created on the:

• LSN pool IP address and port on behalf of the private client, so that the messages that arrive at
this IP address and port from the public network are treated as SIP messages.
• Public IP address and port on behalf of the public clients, so that the messages that arrive at
this IP address and port from the private network are treated as SIP messages.

When a SIP message is sent out across the network, the SIP Application Layer Gateway (ALG) collects
information from the message and translates the IP addresses in the following headers into LSN pool
IP addresses:

• Via
• Contact
• Route

© 1999-2018 Citrix Systems, Inc. All rights reserved. 309

NetScaler 12.0

• Record-Route

In the following sample SIP request message, LSN replaces the IP addresses in the header fields to
hide them from the outside network.

“‘ pre codeblock
INVITE [email protected] SIP/2.0 Via: SIP/2.0/UDP 192.170.1.161:62914 From: [email protected]
To: [email protected] Call-ID: [email protected] Contact: [email protected] Route:
<sip:[email protected]:5060> Record-Route: <sip:[email protected]:5060>

1 When a message containing SDP information arrives, the SIP ALG collects
information from the message and translates the IP addresses in the
following fields into LSN pool IP addresses and port numbers:
2
3 - c= (connection information)
4
5 This field can appear at the session or media level. It appears in
the following format:
6
7 ‘c=<network-type><address-type><connection-address>‘
8
9 If the destination IP address is a unicast IP address, the SIP ALG
creates pinholes by using the IP address and port numbers
specified in the m= field.
10
11 - m= (media announcement)
12
13 This field appears at the media level and contains the description
of the media. It appears in the following format:
14
15 ‘m=<media><port><transport><fmt list>‘
16
17 - a= (information about the media field)
18
19 This field can appear at the session or media level, in the
following format:
20
21 ‘a=<attribute>‘
22
23 ‘a=<attribute>:<value>‘
24
25 The following excerpt from a sample SDP section shows the fields that
are translated for resource allocation.
26
27 o=user 2344234 55234434 IN IP4 10.150.20.3

© 1999-2018 Citrix Systems, Inc. All rights reserved. 310

NetScaler 12.0

28
29 c=IN IP4 10.150.20.3
30
31 m=audio 43249 RTP/AVP 0
32
33 The following table shows how SIP payload is translated.
34 ||||
35 |-|-|-|
36 |Inbound Request (from public to private)|To:|None|
37 ||From:|None|
38 ||Call-ID:|None|
39 ||Via:|None|
40 ||Request-URI:|Replace LSN pool IP address with private IP address|
41 ||Contact:|None|
42 ||Record-Route|None|
43 ||Route:|None|
44 |Outbound Response (from private to public)|To:|None|
45 ||From:|None|
46 ||Call-ID:|None|
47 ||Via:|None|
48 ||Request-URI:|Replace private IP address with LSN pool IP address|
49 ||Contact:|Replace private IP address with LSN pool IP address|
50 ||Record-Route|None|
51 ||Route:|None|
52 |Outbound Request (from private to public)|To:|None|
53 ||From:|None|
54 ||Call-ID:|None|
55 ||Via:|Replace private IP address with LSN pool IP address|
56 ||Request-URI:|None|
57 ||Contact:|Replace private IP address with LSN pool IP address|
58 ||Record-Route|None|
59 ||Route:|None
60 |Inbound Response (from public to private)|To:|None|
61 ||From:|None|
62 ||Call-ID:|None|
63 ||Via:|Replace LSN pool IP address with private IP address|
64 ||Request-URI:|None|
65 ||Contact:|Retain public IP address, if present|
66 ||Record-Route|None|
67 ||Route:|None|
68
69 ## Limitations of SIP ALG
70
71 A SIP ALG has the following limitations:
72

© 1999-2018 Citrix Systems, Inc. All rights reserved. 311

NetScaler 12.0

73 - Only SDP payload is supported.

74 - The following are not supported:
75 - Multicast IP addresses
76 - Encrypted SDP
77 - SIP TLS
78 - FQDN translation
79 - SIP layer authentication
80 - TD/partitioning/cluster
81 - Multipart body
82 - SIP messages over IPv6 network
83 - Line folding
84
85 ## Tested SIP Clients and Proxy Servers
86
87 The following SIP clients and proxy server have been tested with SIP
ALG:
88
89 - **SIP Clients:** X-Lite, Zoiper, Ekiga. Avaya
90 - **Proxy Server:** openSIPS
91
92 ## LSN SIP Scenario: SIP Proxy Outside the Private Network (Public
Network)
93
94 ### SIP Client Registration
95
96 For a typical SIP call, SIP client must register with the SIP registrar
by composing a REGISTER request and sending it to the SIP registrar
. The NetScaler appliance ’ s SIP ALG intercepts the request,
replaces the IP address and port number in the request with the LSN
pool IP address and port number provided in the LSN configuration,
and forwards the request to the SIP registrar. The SIP ALG then
opens a pinhole in the NetScaler configuration to allow further SIP
communication between the SIP client and the SIP registrar. The SIP
registrar sends a 200 OK response to the SIP client over the LSN
pool IP address and port number. The NetScaler appliance captures
this response in the pinhole, and the SIP ALG replaces the SIP
header, putting the original Contact, Via, Route, and Record-Route
SIP fields back into the message. The SIP ALG then forwards the
message to the SIP client. The following figure shows how SIP ALG
uses LSN in a SIP call registration flow.![localized image](/en-us/
netscaler/media/img-1.jpg)
97
98 ### Outgoing Calls
99
100 A SIP call is initiated with a SIP INVITE message sent from the

© 1999-2018 Citrix Systems, Inc. All rights reserved. 312

NetScaler 12.0

internal to the external network. The SIP ALG performs NAT on the IP
addresses and port numbers in the Via, Contact, Route, and Record-
Route SIP header fields, replacing them with the LSN pool IP address
and port number. LSN stores these mappings for subsequent SIP
messages in the SIP call. The SIP ALG then opens separate pinholes
in the NetScaler configuration to allow SIP and media through the
NetScaler appliance on the dynamically assigned ports specified in
the SDP and SIP headers. When a 200 OK message arrives at the
NetScaler, it is captured by one of the created pinholes. The SIP
ALG replaces the SIP header, restoring the original Contact, Via,
Route, and Record-Route SIP fields, and then forwards the message to
the internal SIP client.![localized image](/en-us/netscaler/media/
img-1.1.jpg)
101
102 ### Incoming Calls
103
104 A SIP incoming call is initiated with a SIP INVITE message from the
external client to the internal network. The SIP registrar forwards
the INVITE message to the SIP client in the internal network, using
the pinhole that was created when the Internal SIP client registered
with the SIP registrar.
105
106 The SIP ALG performs NAT on the LSN IP addresses and port numbers in
the Via, Contact, Route, and Record-Route SIP header fields,
translating them to the IP address and port number of the internal
SIP client, and forwards the request to the SIP client. When the 200
OK response message sent by the internal SIP client arrives at the
NetScaler appliance, the SIP ALG performs NAT on the IP addresses
and port numbers in the Via, Contact, Route, and Record-Route SIP
header fields, translating them to the LSN pool IP address and port
number, forwards the response message to the SIP registrar, and then
opens a pinhole in the outbound direction for further SIP
communication.
107
108 ### Call Termination
109
110 The BYE message terminates a call. When the device receives a BYE
message, it translates the header fields in the message just as it
does for any other message. But because a BYE message must be
acknowledged by the receiver with a 200 OK, the ALG delays call
teardown for 15 seconds to allow time for transmission of the 200 OK
.
111
112 ### Call Between Clients in the Same Network
113

© 1999-2018 Citrix Systems, Inc. All rights reserved. 313

NetScaler 12.0

114 When both client A and client B in the same network initiate a call,
the SIP messages are routed through the SIP proxy in the outside
network. The SIP ALG processes the INVITE from client A as a normal
outgoing call. Since client B is in the same network, the SIP proxy
sends the INIVITE back to the NetScaler appliance. The SIP ALG
examines the INIVITE message, determines that it contains the NAT IP
address of client A, and replaces that address with the private IP
address of client A before sending the message to client B. Once the
call is established between the clients, the NetScaler is not
involved in the media transmission between the clients.
115
116 ## More LSN SIP Scenarios: SIP Proxy Inside the Private Network
117
118 If you want to host the SIP Proxy server inside the private network,
Citrix recommends that you do one of the following:
119
120 - Configure a static LSN Mapping for the private SIP proxy. For more
information, see [Configuring Static LSN Maps](/en-us/netscaler/12/
netscaler-support-for-telecom-service-providers/lsn-introduction/
configuration-steps-lsn.html). Make sure that the NAT port is the
same as the port configured in the SIP ALG profile.
121 - Configure the SIP Proxy server inside a demilitarized zone (DMZ).
122
123 Figure 1. SIP Call Registration
124
125 
126
127 Figure 2. SIP Incoming Call Flow
128
129 ![localized image](/en-us/netscaler/media/sip-proxy-inside-private-
scenario3.png)
130
131 Figures 1 and 2 show the following scenarios:
132
133 - Scenario 1 — SIP client in the private network registers with the SIP
proxy server in the same network. ALG operations are not performed,
because the SIP client and SIP proxy server are in the same network
.
134 - Scenario 2 — SIP client in the public network registers with the SIP
proxy server in the private network. The REGISTER message from the
public SIP client is sent to the NetScaler appliance by using the
static LSN mapping configured on the appliance, and the appliance
creates a pinhole for further SIP operations.
135 - Scenario 3 — SIP Incoming call flow. A SIP incoming call is
initiated with a SIP INVITE message from the external to the

© 1999-2018 Citrix Systems, Inc. All rights reserved. 314

NetScaler 12.0

internal network. The NetScaler appliance receives the INVITE

message from SIP client C2, which is in the external network,
through the static LSN maps configured on the NetScaler appliance.
136 The appliance creates a pinhole and forwards the INVITE message to
the SIP proxy. The SIP proxy then forwards the INVITE message to
SIP client C1 in the internal network. SIP client C1 then sends
180 and 200 OK messages to the SIP proxy, which in turn
forwards the message to SIP client C2 through the NetScaler
appliance.
137 When the 200 OK response message sent by internal SIP client C1
arrives at the NetScaler, the SIP ALG performs NAT on the IP
addresses and port numbers in the Via, Contact, Route, and
Record-Route SIP header fields, and in the SDP fields, replacing
them with the LSN pool IP address and port number. The SIP ALG
then forwards the response message to SIP client C2 and opens a
pinhole in the outbound direction for further SIP communication.
138
139 ## Support for Audit Logs
140
141 You can log ALG information as part of LSN logging by enabling ALG in
the LSN audit logging configuration. For more information on LSN
logging, see [Logging and Monitoring LSN](/en-us/netscaler/12/
netscaler-support-for-telecom-service-providers/lsn-introduction/lsn
-logging-monitoring.html). A log message for an ALG entry in the LSN
log consists of the following information:
142
143 - Time stamp
144 - Type of SIP message (for example, SIP request)
145 - Source IP address and port of the SIP client
146 - Destination IP address and port of the SIP proxy
147 - NAT IP address and port
148 - SIP method
149 - Sequence number
150 - Whether or not the SIP client is registered
151 - Caller ’ s user name and domain
152 - Receiver ’ s user name and domain
153
154 **Sample audit log:**
155
156 **Request:**

07/19/2013:09:49:19 GMT Informational 0-PPE-0 : default ALG ALG_SIP_INFO_PACKET_EVENT 169 0 :

Infomsg: “SIP request” - Group: g2 - Call_ID: NTY0YjYwMTJmYjNhNDU5ZjlhMmQxOTM5ZTE3Zjc3NjM.
- Transport: TCP - Source_IP: 192.169.1.165 - Source_port: 57952 - Destination_IP: 10.102.185.156

© 1999-2018 Citrix Systems, Inc. All rights reserved. 315

NetScaler 12.0

- Destination_port: 5060 - Natted_IP: 10.102.185.191 - Natted_port: 10313 - Method: REGISTER

- Sequence_Number: 3060 - Register: YES - Content_Type: - Caller_user_name: 156_pvt_1 -
Callee_user_name: 156_pvt_1 - Caller_domain_name: - Callee_domain_name: -

1 **Response:**

07/19/2013:09:49:19 GMT Informational 0-PPE-0 : default ALG ALG_SIP_INFO_PACKET_EVENT 170 0 :

Infomsg: “SIP response” - Group: g2 - Call_ID: NTY0YjYwMTJmYjNhNDU5ZjlhMmQxOTM5ZTE3Zjc3NjM.
- Transport: TCP - Response_code 200 - Source_IP: 10.102.185.156 - Source_port: 5060 - Destina-
tion_IP: 192.169.1.165 - Destination_port: 57952 - Natted_IP: 10.102.185.191 - Natted_port: 10313 -
Sequence_Number: 3060 - Content_Type: - Caller_user_name: 156_pvt_1 - Callee_user_name:
156_pvt_1 - Caller_domain_name: - Callee_domain_name: -

1 ## Configuring SIP ALG

2
3 You need to configure the SIP ALG as part of the LSN configuration. For
instructions on configuring LSN, see [Configuration Steps for LSN](
http://docs.citrix.com/en-us/netscaler/11-1/netscaler-support-for-
telecom-service-providers/lsn-introduction/configuration-steps-lsn.
html). While configuring LSN, make sure that you:
4
5 - Set the following parameters while adding the LSN application
profile:
6 - IP Pooling = PAIRED
7 - Address and Port Mapping = ENDPOINT-INDEPENDENT
8 - Filtering = ENDPOINT-INDEPENDENT
9
10 Important: For the SIP ALG to work, a full cone NAT configuration is
mandatory.
11
12 **Example:**

add lsn appsprofile app_tcp TCP -ippooling PAIRED -mapping ENDPOINT-INDEPENDENT -filtering
ENDPOINT-INDEPENDENT

1 - Create a SIP ALG profile and make sure that you define either the
source port range or destination port range.
2
3 **Example:**

add lsn sipalgprofile sipalgprofile_tcp -sipsrcportrange 1-65535 -sipdstportrange 5060 -openViaPinhole

ENABLED -openRecordRoutePinhole ENABLED –sipTransportProtocol TCP

1 - Set SIP ALG = ENABLED, while creating the LSN group.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 316

NetScaler 12.0

2
3 **Example:**

add lsn group g1 -clientname c1 -sipalg ENABLED

1 - Bind the SIP ALG profile to the LSN group.

2
3 **Sample SIP ALG Configuration:**
4
5 The following sample configuration shows how to create a simple LSN
configuration with a single subscriber network, single LSN NAT IP
address, SIP ALG specific setting, and configure SIP ALG:

add lsn pool p1

Done

bind lsn pool p1 10.102.185.190

Done

add lsn client c1

Done

bind lsn client c1 -network 192.170.1.0 -netmask 255.255.255.0

Done

add lsn appsprofile app_tcp TCP -ippooling PAIRED -mapping ENDPOINT-INDEPENDENT -filtering
ENDPOINT-INDEPENDENT

Done

add lsn appsprofile app_udp UDP -ippooling PAIRED -mapping ENDPOINT-INDEPENDENT -filtering
ENDPOINT-INDEPENDENT

Done

bind lsn appsprofile app_tcp 1-65535

Done

bind lsn appsprofile app_udp 1-65535

Done

add lsn sipalgprofile sipalgprofile_tcp -sipdstportrange 5060 -openViaPinhole ENABLED -openRecordRoutePinhole

ENABLED –sipTransportProtocol TCP

Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 317

NetScaler 12.0

add lsn sipalgprofile sipalgprofile_udp -sipdstportrange 5060 -openViaPinhole ENABLED -

openRecordRoutePinhole ENABLED -sipTransportProtocol UDP

Done

add lsn group g1 -clientname c1 -sipalg ENABLED

Done

bind lsn group g1 -poolname p1

Done

bind lsn group g1 -appsprofilename app_tcp

Done

bind lsn group g1 -appsprofilename app_udp

Done

bind lsn group g1 -sipalgprofilename sipalgprofile_tcp

Done

bind lsn group g1 -sipalgprofilename sipalgprofile_udp

Done
“‘

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Application Layer Gateway for RTSP Protocol

January 6, 2019

Contributed by:
C

Real Time Streaming Protocol (RTSP) is an application-level protocol for the transfer of real-time me-
dia data. Used for establishing and controlling media sessions between end points, RTSP is a control
channel protocol between the media client and the media server. The typical communication is be-
tween a client and a streaming media server.

Streaming media from a private network to a public network requires translating IP addresses and
port numbers over the network. NetScaler functionality includes an Application Layer Gateway (ALG)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 318

NetScaler 12.0

for RTSP, which can be used with Large Scale NAT (LSN) to parse the media stream and make any
necessary changes to ensure that the protocol continues to work over the network.

How IP address translation is performed depends on the type and direction of the message, and the
type of media supported by the client-server deployment. Messages are translated as follows:

• Outbound request—Private IP address to NetScaler owned public IP address called an LSN pool
IP address.
• Inbound response—LSN pool IP address to private IP address.
• Inbound request—No translation.
• Outbound response—Private IP address to LSN pool IP address.

Limitations of RTSP ALG

The RTSP ALG does not support the following:

• Multicast RTSP sessions

• RTSP session over UDP
• TD/admin partitioning/cluster deployments
• RSTP Authentication
• HTTP tunneling

RTSP and LSN scenario

The following figure shows an RTSP SETUP request flow. Typically, a SETUP request specifies how a
single media stream must be transported. The request contains the media stream URL and a transport
specifier. This specifier typically includes one local port for receiving RTP data (audio or video), and
another for receiving RTCP data (meta information). The server reply usually confirms the chosen
parameters and fills in the missing parts, such as the server’s chosen ports. Each media stream must
be configured by using the SETUP command before an aggregate play request can be sent.

In a typical RTSP communication, the media client in the public network sends a SETUP request to
the media server in the private network. RSTP ALG intercepts the request and, in the media stream,
replaces the public IP address and port number with the LSN pool IP address and LSN port number.
The following figure shows the translation performed by a NetScaler appliance in the media stream
for an outbound request:

The media server in the private network uses the LSN pool IP address and LSN port number to send
a 200 OK response to the media client in the public network. The NetScaler RTSP ALG intercepts the
response and replaces the LSN pool IP address and LSN port number with the public IP address and
port number of the media client. The following figure shows the translation performed by a NetScaler
appliance in the media stream for an inbound response:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 319

NetScaler 12.0

Configuring RTSP ALG

Configure RTSP ALG as part of the LSN configuration. For instructions on configuring LSN, see Config-
uration Steps for LSN. While configuring LSN, make sure that you:
• Set the NAT Type as DETERMINSTIC or DYNAMIC while adding the LSN pool.
• Set the following parameters while adding the LSN application profile:
– IP Pooling = PAIRED
– Address and Port Mapping = ENDPOINT-INDEPENDENT
– Filtering = ENDPOINT-INDEPENDENT
• Create a RTSP ALG profile and bind the RTSP ALG profile to the LSN group
Sample RTSP ALG Configuration:
The following sample configuration shows how to create a simple LSN configuration with a single sub-
scriber network, single LSN NAT IP address, and RTSP ALG settings:

1 enable ns feature WL SP LB CS LSN

2
3 Done
4
5 add lsn pool pool1 -nattype DETERMINISTIC
6
7 Done
8
9 bind lsn pool pool1 10.102.218.246
10
11 Done
12
13 add lsn client client1
14
15 Done
16
17 bind lsn client client1 -network 200.200.200.11 -netmask 255.255.255.0
18
19 Done
20
21 add lsn appsprofile app1 TCP -ippooling PAIRED -mapping ENDPOINT-
INDEPENDENT -filtering ENDPOINT-INDEPENDENT
22
23 Done
24
25 add lsn appsprofile app2 UDP -ippooling PAIRED -mapping ENDPOINT-
INDEPENDENT -filtering ENDPOINT-INDEPENDENT
26
27 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 320

NetScaler 12.0

28
29 bind lsn appsprofile app1 1-65535
30
31 Done
32
33 bind lsn appsprofile app2 1-65535
34
35 Done
36
37 add lsn rtspalgprofile rtspalgprofiledefault -rtspIdleTimeout 1000 -
rtspportrange 554
38
39 Done
40
41 add lsn group group1 -clientname client1 -nattype DETERMINISTIC -
portblocksize 512 -rtspalg ENABLED
42
43 Done
44
45 bind lsn group group1 -poolname pool1
46
47 Done
48
49 bind lsn group group1 -appsprofilename app1
50
51 Done
52
53 bind lsn group group1 -appsprofilename app2
54
55 Done
56
57 bind lsn group group1 -rtspalgprofilename rtspalgprofiledefault
58
59 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

© 1999-2018 Citrix Systems, Inc. All rights reserved. 321

NetScaler 12.0

Application Layer Gateway for IPSec Protocol

September 17, 2018

Contributed by:
C

If communication between two network devices (for example, client and server) uses the IPSec pro-
tocol, IKE traffic (which is over UDP) uses port fields, but Encapsulating Security Payload (ESP) traffic
does not. If a NAT device on the path assigns the same NAT IP address (but different ports) to two
or more clients at the same destination, the NAT device is unable to distinguish and properly route
the return ESP traffic does not contain port information. Therefore, IPSec ESP traffic fails at the NAT
device.

NAT-Traversal (NAT-T) capable IPSec endpoints detect the presence of an intermediate NAT device
during IKE phase 1 and switch to UDP port 4500 for all subsequent IKE and ESP traffic (encapsulat-
ing ESP in UDP). Without NAT-T support on the peer IPSec endpoints, IPSec protected ESP traffic is
transmitted without any UDP encapsulation. Therefore, IPSec ESP traffic fails at the NAT device.

The NetScaler appliance supports IPSec application layer gateway (ALG) functionality for large scale
NAT configurations. The IPSec ALG processes IPSec ESP traffic and maintains session information so
that the traffic does not fail when the IPSec endpoints do no support NAT-T (UDP encapsulation of ESP
traffic).

How IPSec ALG Works

An IPSec ALG monitors IKE traffic between a client and the server, and permits only one IKE phase 2
message exchange between the client and the server at any given time.

Once the two-way ESP packets are received for a particular flow, the IPSec ALG creates a NAT session
for this particular flow so that subsequent ESP traffic can flow smoothly. The ESP traffic is identified
by Security Parameters Indexes (SPIs), which are unique for a flow and for each direction. An IPSec
ALG uses ESP SPIs in place of source and destination ports for performing large scale NAT.

If a gate receives no traffic, it times out. After both gates time out, another IKE phase 2 exchange is
permitted.

IPSec ALG Timeouts

IPsec ALG on a NetScaler appliance has three timeout parameters:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 322

NetScaler 12.0

• ESP Gate Timeout. Maximum time that the NetScaler appliance blocks an IPSec ALG gate for
a particular client on a specific NAT IP address for a given server if no two-way ESP traffic is
exchanged between the client and the server.
• IKE Session Timeout. Maximum time that the NetScaler appliance keeps the IKE session infor-
mation before removing it if there is no IKE traffic for that session.
• ESP Session Timeout. Maximum time that NetScaler appliance keeps the ESP session informa-
tion before removing it if there is no ESP traffic for that session.

Points to Consider before Configuring IPSec ALG

Before you start configuring IPSec ALG, consider the following points:
• You must understand the different components of IPSec protocol.
• IPSec ALG is not supported for DS-Lite and Large scale NAT64 configurations.
• IPSec ALG is not supported for hairpin LSN flow.
• IPSec ALG does not work with RNAT configurations.
• IPSec ALG is not supported inNetScaler clusters.

Configuration Steps

Configuring IPSec ALG for large scale NAT44 on a NetScaler appliance consists of the following tasks:
• Create an LSN application profile and bind it to the LSN configuration. Set the following
parameters while configuring an application profile:
– Protocol=UDP
– IP Pooling = PAIRED
– Port=500
Bind the application profile to the LSN group of an LSN configuration. For instructions on creating an
LSN configuration, see Configuration Steps for LSN.
• Create an IPSec ALG profile. An IPSec profile includes various IPSec timeouts, such as IKE ses-
sion timeout, ESP session timeout, and ESP gate timeout. You bind an IPSec ALG profile to an
LSN group. An IPSec ALG profile has the following default settings:
– IKE session timeout = 60 minutes
– ESP session timeout = 60 minutes
– ESP gate timeout = 30 seconds
• Bind the IPSec ALG profile to the LSN configuration. IPSec ALG is enabled for an LSN configu-
ration when you bind an IPSec ALG profile to the LSN configuration. Bind the IPSec ALG profile
to the LSN configuration by setting the IPSec ALG profile parameter to the name of the created
profile in the LSN group. An IPSec ALG profile can be bound to multiple LSN groups, but an LSN
group can have only one IPSec ALG profile.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 323

NetScaler 12.0

To create an LSN application profile by using the command line interface

At the command prompt, type:

1 add lsn appsprofile <appsprofilename> UDP -ippooling PAIRED

2
3 show lsn appsprofile

To bind destination port to the LSN application profile by using the command line interface

At the command prompt, type:

1 bind lsn appsprofile <appsprofilename> <lsnport>

2
3 show lsn appsprofile

To bind an LSN application profile to an LSN group by using the command line interface

At the command prompt, type:

1 bind lsn group <groupname> -appsprofilename <string>

2
3 show lsn group

To create an IPSec ALG profile by using the CLI

At the command prompt, type:

1 add ipsecalg profile <name> [-ikeSessionTimeout <positive_integer>] [-

espSessionTimeout <positive_integer>] [-espGateTimeout <
positive_integer>] [-connfailover ( ENABLED | DISABLED)
2
3 show ipsecalg profile <name>

To bind an IPSec ALG profile to an LSN configuration by using the CLI

At the command prompt, type:

1 bind lsn group <groupname> -poolname <string> - ipsecAlgProfile <string

>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 324

NetScaler 12.0

2
3 show lsn group <name>

To create an LSN application profile and bind it to an LSN configuration by using the GUI

Navigate to System > Large Scale NAT > Profiles, click Application tab, add an LSN application profile
and bind it to an LSN group.

To create an IPSec ALG profile by using the GUI**

Navigate to System > Large Scale NAT > Profiles, click IPSEC ALG tab, and then add an IPSec ALG
profile.

To bind an IPSec ALG profile to an LSN configuration by using the GUI**

1. Navigate to System > Large Scale NAT > LSN Group, open the LSN group.
2. In Advanced Settings, click + IPSEC ALG Profile to bind the created IPSec ALG profile to the
LSN group.

Sample Configuration

In the following sample large scale NAT44 configuration, IPSec ALG is enabled for subscribers in the
192.0.2.0/24 network. IPSec ALG profile IPSECALGPROFILE-1 with various IPSec timeout settings is
created and is bound to LSN group LSN Group -1.

Sample configuration:

1 add lsn client LSN-CLIENT-1

2
3 Done
4
5 bind lsn client LSN-CLIENT-1 -network 192.0.2.0 -netmask 255.255.255.0
6
7 Done
8
9 add lsn pool LSN-POOL-1
10
11 Done
12
13 bind lsn pool LSN-POOL-1 203.0.113.3-203.0.113.9
14
15 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 325

NetScaler 12.0

16
17 add lsn appsprofile LSN-APPSPROFILE-1 UDP -ippooling PAIRED
18
19 Done
20
21 bind lsn appsprofile LSN-APPSPROFILE-1 500
22
23 Done
24
25 add ipsecalg profile  IPSECALGPROFILE-1 -ikeSessionTimeout 45 ‒
espSessionTimeout 40 ‒ espGateTimeout 20 -connfailover ENABLED
26
27 Done
28
29 bind lsn group LSN-GROUP-1 -appsprofilename LSN-APPSPROFILE-1
30
31 Done
32
33 bind lsn group LSN-GROUP-1 -poolname LSN-POOL-1
34
35 Done
36
37 bind lsn group LSN-GROUP-1 - ipsecAlgProfile IPSECALGPROFILE-1
38
39 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Logging and Monitoring LSN

January 6, 2019

Contributed by:
C

You can log LSN information to diagnose, troubleshoot problems, and to meet legal requirements.
You can monitor the performance of the LSN feature by using LSN statistical counters and displaying
current LSN sessions.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 326

NetScaler 12.0

Logging LSN

Logging LSN information is one of the important functions required by the ISPs to meet legal require-
ments and for identifying the source of traffic at any given time.

A NetScaler appliance logs LSN mapping entries and the LSN sessions created or deleted for each
LSN group. You can control logging of LSN information for an LSN group by using the logging and
session logging parameters of the LSN group. These are group level parameters and are disabled by
default. The NetScaler appliance logs LSN sessions for an LSN group only when both logging and
session logging parameters are enabled.

The following table displays the logging behavior for an LSN group for various settings of logging and
session logging parameters.

Logging Session Logging Logging Behavior

Enabled Enabled Logs LSN mapping entries as

well as LSN sessions.
Enabled Disabled Logs LSN mapping entries but
not LSN sessions.
Disabled Enabled Logs neither mapping entries
nor LSN sessions.

A log message for an LSN mapping entry consists of the following information:

• NetScaler owned IP address (NSIP address or SNIP address) from which the log message is
sourced.
• Time stamp
• Entry type (MAPPING)
• Whether the LSN mapping entry was created or deleted
• Subscriber’s IP address, port, and traffic domain ID
• NAT IP address and port
• Protocol name
• Destination IP address, port, and traffic domain ID might be present, depending on the following
conditions:
– Destination IP address and port are not logged for Endpoint-Independent mapping.
– Only the destination IP address is logged for Address-Dependent mapping. The port is not
logged.
– Destination IP address and port are logged for Address-Port-Dependent mapping.

A log message for an LSN session consists of the following information:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 327

NetScaler 12.0

• NetScaler owned IP address (NSIP address or SNIP address) from which the log message is
sourced.
• Time stamp
• Entry type (SESSION)
• Whether the LSN session is created or removed
• Subscriber’s IP address, port, and traffic domain ID
• NAT IP address and port
• Protocol name
• Destination IP address, port, and traffic domain ID
The appliance uses its existing syslog and audit log framework to log LSN information. You must en-
able global level LSN logging by enabling the LSN parameter in the related NSLOG action and SYLOG
action entities. When the Logging parameter is enabled, the NetScaler appliance generates log mes-
sages related to LSN mappings and LSN sessions of this LSN group. The appliance then sends these
log messages to servers associated with the NSLOG action and SYSLOG action entities.
For logging LSN information, Citrix recommends:
• Logging the LSN information on external log servers instead of on the NetScaler appliance.
Logging on external servers facilitates optimal performance when the appliance creates large
amounts of LSN log entries (in order of millions).
• Using SYSLOG over TCP, or NSLOG. By default SYSLOG uses UDP, and NSLOG uses only
TCP to transfer log information to the log servers. TCP is more reliable than UDP for transfer-
ring complete data.
Note:
– The SYSLOG generated on NetScaler appliance are dynamically sent to the external log
servers.
– When using SYSLOG over TCP, if the TCP connection is down or the SYSLOG server is busy,
then the NetScaler appliances stores the logs in buffer and send the data once the connec-
tion is active.
For more information about configuring logging, see Audit Logging.
Configuring LSN logging consists of the following tasks:
• Configuring the NetScaler appliance for logging. This task involves creating and setting vari-
ous entities and parameters of the NetScaler appliance:
– Create a SYSLOG or NSLOG audit logging configuration. Creating an audit logging con-
figuration involves the following tasks:
* Create a NSLOG or SYSLOG audit action and enable the LSN parameter. Audit actions
specify the IP addresses of log servers.
* Create a SYSLOG or NSLOG audit policy and bind the audit action to the audit pol-
icy. Audit actions specify the IP addresses of log servers. Optionally, you can set the

© 1999-2018 Citrix Systems, Inc. All rights reserved. 328

NetScaler 12.0

transport method for log messages that are sent to the external log servers. By de-
fault UDP is selected, you can set the transport method as TCP for a reliable transport
mechanism.Bind the audit policy to system global.
* Create a SYSLOG or NSLOG audit policy and bind the audit action to the audit policy.
* Bind the audit policy to system global.
Note: For an existing audit logging configuration, just enable the LSN parameter for
logging LSN information in the server specified by the audit action.
– Enable logging and session logging parameters. Enable logging and session logging
parameters either as you add LSN groups or after you have created the groups. The
NetScaler appliance generates log messages related to these LSN groups and sends them
to the server of those audit actions that have the LSN parameter enabled.
• Configuring log servers. This task involves installing SYSLOG or NSLOG packages on the de-
sired servers. This task also involves specifying the NSIP address of the NetScaler appliance in
the configuration file of SYSLOG or NSLOG. Specifying the NSIP address enables the server to
identify the log information sent by the NetScaler appliance for storing them in a log file.

For more information about configuring logging, see Audit Logging.

SYSLOG Configuration Using the Command Line Interface

To create a SYSLOG server action for LSN logging by using the command line interface

At the command prompt, type:

1 add audit syslogAction <name> <serverIP> [-serverPort <port>] -logLevel

<logLevel>... [-transport (TCP)] [-lsn ( ENABLED | DISABLED )]

To create a SYSLOG server policy for LSN logging by using the command line interface

At the command prompt, type:

1 add audit syslogPolicy <name> <rule> <action>

To bind a SYSLOG server policy to system global for LSN logging by using the command line in-
terface

At the command prompt, type:

1 bind system global [<policyName> [-priority <positive_integer>]]

© 1999-2018 Citrix Systems, Inc. All rights reserved. 329

NetScaler 12.0

SYSLOG Configuration Using the Configuration Utility

To configure a SYSLOG server action for LSN logging by using the configuration utility

1. Navigate to Systems > Auditing > Syslog and, on the Servers tab, add a new auditing server or
edit an existing server.
2. To enable LSN logging, select the Large Scale NAT Logging option.
3. (Optional) To enable SYSLOG over TCP, select the TCP Logging option.

To configure a SYSLOG server policy for LSN logging by using the configuration utility

Navigate to Systems > Auditing > Syslog and, on the Policies tab, add a new policy or edit an existing
policy.

To bind a SYSLOG server policy to system global for LSN logging by using the configuration utility

1. Navigate to Systems > Auditing > Syslog.

2. On the Policies tab, in the Action list, click Global Bindings to bind the audit global policies.

NSLOG Configuration Using the Command Line Interface

To create a NSLOG server action for LSN logging by using the command line interface

At the command prompt, type:

1 add audit nslogAction <name> <serverIP> [-serverPort <port>] -logLevel

<logLevel> ... [-lsn ( ENABLED | DISABLED )]

To create a NSLOG server policy for LSN logging by using the command line interface

At the command prompt, type:

1 add audit nslogPolicy <name> <rule> <action>

To bind a NSLOG server policy to system global for LSN logging by using the command line inter-
face

At the command prompt, type:

1 bind system global [<policyName>]

© 1999-2018 Citrix Systems, Inc. All rights reserved. 330

NetScaler 12.0

NSLOG Configuration Using the Configuration Utility

To configure a NSLOG server action for LSN logging by using the configuration utility

1. Navigate to Systems > Auditing > Nslog and, on the Servers tab, add a new auditing server or,
edit an existing server.
2. To enable LSN logging, select the Large Scale NAT Logging option.

To configure a NSLOG server policy for LSN logging by using the configuration utility

Navigate to Systems > Auditing > Nslog and, on the Policies tab, add a new policy or edit an existing
policy.

To bind a NSLOG server policy to system global for LSN logging by using the configuration utility

1. Navigate to Systems > Auditing > Nslog.

2. On the Policies tab, in the Action list, click Global Bindings to bind the audit global policies.

Example

The following configuration specifies two SYSLOG and two NSLOG servers for storing log entries in-
cluding LSN logs. LSN Logging is configured for LSN groups LSN-GROUP-2 and LSN-GROUP-3.

The NetScaler appliance generates log messages related to LSN mappings and LSN sessions of these
LSN groups, and sends them to the specified log servers.

1 add audit syslogAction SYS-ACTION-1 198.51.101.10 -logLevel ALL -lsn

ENABLED
2 Done
3 add audit syslogPolicy SYSLOG-POLICY-1 ns_true SYS-ACTION-1
4 Done
5 bind system global SYSLOG-POLICY-1
6 Done
7
8 add audit syslogAction SYS-ACTION-2 198.51.101.20 -logLevel ALL -lsn
ENABLED
9 Done
10 add audit syslogPolicy SYSLOG-POLICY-2 ns_true SYS-ACTION-2
11 Done
12 bind system global SYSLOG-POLICY-2
13 Done
14

© 1999-2018 Citrix Systems, Inc. All rights reserved. 331

NetScaler 12.0

15 add audit nslogAction NSLOG-ACTION-1 198.51.101.30 -logLevel ALL -lsn

ENABLED
16 Done
17 add audit nslogPolicy NSLOG-POLICY-1 ns_true NSLOG-ACTION-1
18 Done
19 bind system global NSLOG-POLICY-1
20 Done
21 add audit nslogAction NSLOG-ACTION-2 198.51.101.40 -logLevel ALL -lsn
ENABLED
22 Done
23 add audit nslogPolicy NSLOG-POLICY-2 ns_true NSLOG-ACTION-2
24 Done
25 bind system global NSLOG-POLICY-2
26 Done
27
28 add lsn group LSN-GROUP-3 -clientname LSN-CLIENT-2 ‒ logging ENABLED
‒ sessionLogging ENABLED
29 Done
30 set lsn group LSN-GROUP-2 ‒ logging ENABLED ‒ sessionLogging ENABLED
31 Done

The following configuration specifies SYSLOG configuration for sending log messages to
the external SYSLOG server 192.0.2.10 using TCP.

1 add audit syslogAction SYS-ACTION-1 192.0.2.10 -logLevel ALL -transport

TCP
2 Done
3
4 add audit syslogPolicy SYSLOG-POLICY-1 ns_true SYS-ACTION-1
5 Done
6
7 bind system global SYSLOG-POLICY-1
8 Done

The following table displays sample LSN log entries of each type stored on the configured log servers.
These LSN log entries are generated by a NetScaler appliance whose NSIP address is 10.102.37.115.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 332

NetScaler 12.0

LSN Log Entry Type Sample Log Entry

LSN session creation Local4.Informational 10.102.37.115

08/05/2014:09:59:48 GMT 0-PPE-0 : LSN
LSN_SESSION 2581750 : SESSION CREATED
Client IP:Port:TD 192.0.2.10: 15136:0,
NatIP:NatPort 203.0.113.6: 6234, Destination
IP:Port:TD 198.51.100.9: 80:0, Protocol: TCP
LSN session deletion Local4.Informational 10.102.37.115
08/05/2014:10:05:12 GMT 0-PPE-0 : LSN
LSN_SESSION 3871790 : SESSION DELETED
Client IP:Port:TD 192.0.2.11: 15130:0,
NatIP:NatPort 203.0.113.6: 7887, Destination
IP:Port:TD 198.51.101.2:80:0, Protocol: TCP
LSN mapping creation Local4.Informational 10.102.37.115
08/05/2014:09:59:47 GMT 0-PPE-0 : LSN
LSN_MAPPING 2581580 : EIM CREATED Client
IP:Port 192.0.2.15: 14567, NatIP:NatPort
203.0.113.5: 8214, Protocol: TCP
LSN mapping deletion Local4.Informational 10.102.37.115
08/05/2014:10:05:12 GMT 0-PPE-0 : LSN
LSN_MAPPING 3871700 : EIM DELETED Client
IP:Port 192.0.3.15: 14565, NatIP:NatPort
203.0.113.11: 8217, Protocol: TCP

Minimal Logging

Deterministic LSN configurations and Dynamic LSN configurations with port block significantly re-
duces the LSN log volume. For these two types of configuration, the NetScaler appliance allocates
a NAT IP address and a block of ports to a subscriber. The NetScaler appliance generates a log mes-
sage for a port block at the time of allocation to a subscriber. The NetScaler appliance also generates
a log message when a NAT IP address and port block is freed. For a connection, a subscriber can be
identified just by its mapped NAT IP address and port block. Because of this reason, the NetScaler ap-
pliance does not log any LSN session created or deleted. The appliance also neither logs any mapping
entry created for a session nor when the mapping entry gets removed.

The minimal logging feature for deterministic LSN configurations and dynamic LSN configurations
with port block is enabled by default and there is no provision to disable it. In other words, the
NetScaler appliance automatically do minimal logging for deterministic LSN configurations and dy-

© 1999-2018 Citrix Systems, Inc. All rights reserved. 333

NetScaler 12.0

namic LSN configurations with port block. There is no option available for disabling this feature. The
appliance sends the log messages to all the configured log servers.

A log message for each port block consists of the following information:

• NSIP address of the NetScaler appliance

• Time stamp
• Entry type as DETERMINISTIC or PORTBLOCK
• Whether a port block is allocated or is freed
• Subscriber’s IP address and the assigned NAT IP address and port block
• Protocol name

Minimal Logging for Deterministic LSN Configuration

Consider an example of a simple deterministic LSN configuration for four subscribers having the IP
address 192.0.17.1, 192.0.17.2, 192.0.17.3, and 192.0.17.4.

In this LSN configuration, the port block size is set to 32768 and LSN NAT IP address pool has IP ad-
dresses in the range 203.0.113.19-203.0.113.23.

1 add lsn client LSN-CLIENT-7

2 Done
3 bind lsn client LSN-CLIENT-7 -network 192.0.17.0 -netmask
255.255.255.253
4 Done
5 add lsn pool LSN-POOL-7 -nattype DETERMINISTIC
6 Done
7 bind lsn pool LSN-POOL-7 203.0.113.19-203.0.113.23
8 Done
9 add lsn group LSN-GROUP-7 -clientname LSN-CLIENT-7 -nattype
DETERMINISTIC -portblocksize 32768
10 Done
11 bind lsn group LSN-GROUP-7 -poolname LSN-POOL-7
12 Done

The NetScaler appliance sequentially preallocates, from the LSN NAT IP pool and on the basis of the
set port block size, an LSN NAT IP address and a block of ports to each subscriber. It assigns the first
block of ports (1024-33791) on the beginning NAT IP address (203.0.113.19) to the beginning subscriber
IP address (192.0.17.1). The next range of ports is assigned to the next subscriber, and so on, until the
NAT address does not have enough ports for the next subscriber. At that point, the first port block on
the next NAT IP address is assigned to the subscriber, and so on. The appliance logs the NAT IP address
and the block of ports allocated for each subscriber.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 334

NetScaler 12.0

The NetScaler appliance does not log any LSN session created or deleted for these subscribers. The
appliance generates the following log messages for the LSN configuration.

1 1) 03/23/2015:00:30:56 GMT Informational 0-PPE-0 : default LSN

LSN_DETERMINISTIC 79201453 0 : Dtrstc ALLOC Client 12.0.0.241,
NatInfo 50.0.0.2:59904 to 60415
2 2) 03/23/2015:00:30:56 GMT Informational 0-PPE-0 : default LSN
LSN_DETERMINISTIC 79201454 0 : Dtrstc ALLOC Client 12.0.0.242,
NatInfo 50.0.0.2:60416 to 60927
3 3) 03/23/2015:00:30:56 GMT Informational 0-PPE-0 : default LSN
LSN_DETERMINISTIC 79201455 0 : Dtrstc ALLOC Client 12.0.0.243,
NatInfo 50.0.0.2:60928 to 61439
4 4) 03/23/2015:00:30:56 GMT Informational 0-PPE-0 : default LSN
LSN_DETERMINISTIC 79201455 0 : Dtrstc ALLOC Client 12.0.0.243,
NatInfo 50.0.0.2:60928 to 61439

When you remove the LSN configuration, the allocated NAT IP address and block of ports is freed from
each subscriber. The appliance logs NAT IP address and block of ports freed from each subscriber.
The appliance generates the following log messages for each subscriber when you remove the LSN
configuration.

“‘ pre codeblock
1) 03/23/2015:00:33:57 GMT Informational 0-PPE-0 : default LSN LSN_DETERMINISTIC 79201706 0 :
Dtrstc FREE Client 12.0.0.238, NatInfo 50.0.0.2:58368 to 58879
2) 03/23/2015:00:33:57 GMT Informational 0-PPE-0 : default LSN LSN_DETERMINISTIC 79201707 0 :
Dtrstc FREE Client 12.0.0.239, NatInfo 50.0.0.2:58880 to 59391
3) 03/23/2015:00:33:57 GMT Informational 0-PPE-0 : default LSN LSN_DETERMINISTIC 79201708 0 :
Dtrstc FREE Client 12.0.0.240, NatInfo 50.0.0.2:59392 to 59903

1 ### Minimal Logging for Dynamic LSN Configuration with Port Block
2
3 Consider an example of a simple dynamic LSN configuration with port
block for any subscriber in the network 192.0.2.0/24. In this LSN
configuration, the port block size is set to 1024 and LSN NAT IP
address pool has IP addresses in the range 203.0.113.3-203.0.113.4.

set lsn parameter -memLimit 4000

Done
add lsn client LSN-CLIENT-1
Done
bind lsn client LSN-CLIENT-1 -network 192.0.2.0 -netmask 255.255.255.0
Done
add lsn pool LSN-POOL-1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 335

NetScaler 12.0

Done
bind lsn pool LSN-POOL-1 203.0.113.3-203.0.113.4
Done
add lsn group LSN-GROUP-1 -clientname LSN-CLIENT-1 -portblocksize 1024
Done
bind lsn group LSN-GROUP-1 -poolname pool1 LSN-POOL-1
Done

1 The NetScaler appliance allocates a random NAT IP address and a block

of ports, from the LSN NAT IP pool and on the basis of the set port
block size, for a subscriber when it initiates a session for the
first time. The NetScaler logs the NAT IP address and block of ports
allocated to this subscriber. The appliance does not log any LSN
session created or deleted for this subscriber. If all the ports are
allocated (for different subscriber ’ s sessions) from the
subscriber ’ s allocated port block, the appliance allocates a new
random NAT IP address and port block for the subscriber for
additional sessions. The NetScaler logs every NAT IP address and
port block allocated to a subscriber.
2
3 The appliance generates the following log message when the subscriber,
having the IP address 192.0.2.1, initiates a session. The log
message shows that the appliance has allocated NAT IP address
203.0.113.3 and port block 1024-2047 to the subscriber.

03/23/2015:00:07:12 GMT Informational 0-PPE-3 : default LSN LSN_PORTBLOCK 106725793 0 : Port-

block ALLOC Client 12.0.2.72, NatInfo 203.0.113.3:1024 to 2047, Proto:TCP

1 Once there are no more sessions left that is using the allocated NAT IP
address and one of the ports in the allocated port block, the
allocated NAT IP address and block of ports is freed from the
subscriber. The NetScaler logs that the NAT IP address and the block
of ports is freed from the subscriber. The appliance generates the
following log messages for the subscriber, having the IP address
192.0.2.1 , when no more sessions are left that is using the
allocated NAT IP address ( 203.0.113.3 ) and a port from the
allocated port block ( 1024-2047 ). The log message shows that the
NAT IP address and port block are freed from the subscriber.

03/23/2015:00:11:09 GMT Informational 0-PPE-3 : default LSN LSN_PORTBLOCK 106814342 0 : Port-

block FREE Client 12.0.3.122, NatInfo 203.0.113.3: 1024 to 2047, Proto:TC

1 ## Load Balancing SYSLOG Servers

2

© 1999-2018 Citrix Systems, Inc. All rights reserved. 336

NetScaler 12.0

3 The NetScaler appliance send its SYSLOG events and messages to all the
configured external log servers. This results in storing redundant
messages and makes monitoring difficult for system administrators.
To address this issue, the NetScaler appliance offers load balancing
algorithms that can load balance the SYSLOG messages among the
external log servers for better maintenance and performance. The
supported load balancing algorithms include RoundRobin,
LeastBandwidth, CustomLoad, LeastConnection, LeastPackets, and
AuditlogHash.
4
5 ### Load balancing of SYSLOG servers using the command line interface
6
7 Add a service and specify the service type as SYSLOGTCP or SYSLOGUDP.

add service ( | ) <serviceType (SYSLOGTCP | SYSLOGUDP)>

1 Add a load balancing virtual server, specify the service type as

SYSLOGTCP or SYSLOGTCP, and load balancing method as AUDITLOGHASH.

add lb vserver <serviceType (SYSLOGTCP | SYSLOGUDP)> [-lbMethod ]

1 Bing the service to the load balancing virtual server.

Bind lb vserver

1 Add a SYSLOG action and specify the load balancing server name that has
SYSLOGTCP or SYSLOGUDP as service type.

add syslogaction [-lbVserverName ] [-logLevel ]

1 Add a SYSLOG policy by specifying the rule and action.

add syslogpolicy

1 Bind the SYSLOG policy to the system global for the policy to take
effect.

bind system global

1 ### Load balancing of SYSLOG servers using the configuration utility

2
3 1. Add a service and specify the service type as SYSLOGTCP or
SYSLOGUDP.
4
5 Navigate to Traffic Management > Services, click Add and
select SYLOGTCP or SYSLOGUDP as protocol.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 337

NetScaler 12.0

6
7 1. Add a load balancing virtual server, specify the service type as
SYSLOGTCP or SYSLOGTCP, and load balancing method as AUDITLOGHASH.
8
9 Navigate to Traffic Management > Virtual Servers, click Add and
select SYLOGTCP or SYSLOGUDPas protocol.
10
11 1. Bing the service to the load balancing virtual server to the
service.
12
13 Bing the service to the load balancing virtual server.
14
15 Navigate to Traffic Management > Virtual Servers, select a virtual
server and then selectAUDITLOGHASH in the Load Balancing Method.
16
17 1. Add a SYSLOG action and specify the load balancing server name that
has SYSLOGTCP or SYSLOGUDP as service type.
18
19 Navigate to System > Auditing, click Servers and add a server by
selecting LB Vserver option inServers.
20
21 1. Add a SYSLOG policy by specifying the rule and action.
22
23 Navigate to System > Syslog, click Policies and add a SYSLOG policy
.
24
25 1. Bind the SYSLOG policy to the system global for the policy to take
effect.
26
27 Navigate to System > Syslog, select a SYSLOG policy and
click Action, and then click Global Bindings and bind the policy
to system global.
28
29 **Example:**
30
31 The following configuration specifies load balance of SYSLOG messages
among the external log servers using the AUDITLOGHASH as load
balancing method. The NetScaler appliance generates SYSLOG events
and messages that are load balanced amongst the services, service1,
service2, and service 3.

add service service1 192.0.2.10 SYSLOGUDP 514

Done

add service service2 192.0.2.11 SYSLOGUDP 514

© 1999-2018 Citrix Systems, Inc. All rights reserved. 338

NetScaler 12.0

Done

add service service3 192.0.2.11 SYSLOGUDP 514

Done

add lb vserver lbvserver1 SYSLOGUDP -lbMethod AUDITLOGHASH

Done

bind lb vserver lbvserver1 service1

Done

bind lb vserver lbvserver1 service2

Done

bind lb vserver lbvserver1 service3

Done

add syslogaction sysaction1 -lbVserverName lbvserver1 -logLevel All

Done

add syslogpolicy syspol1 ns_true sysaction1

Done

bind system global syspol1

Done

1 ## Logging HTTP Header Information

2
3 The NetScaler appliance can now log request header information of an
HTTP connection that is using the LSN fucntionality of the NetScaler
. The following header information of an HTTP request packet can be
logged:
4
5 - URL that the HTTP request is destined to.
6 - HTTP Method specified in the HTTP request.
7 - HTTP version used in the HTTP request.
8 - IP address of the subscriber that sent the HTTP request.
9
10 The HTTP header logs can be used by ISPs to see the trends related to
the HTTP protocol among a set a subscribers. For example, an ISP can
use this feature to find out the most popular websites among a set
of subscribers.
11
12 An HTTP header log profile is a collection of HTTP header attributes (
for example, URL and HTTP method) that can be enabled or disabled
for logging. The HTTP header log profile is then bound to an LSN
group. The NetScaler appliance then logs HTTP header attributes,
which are enabled in the bound HTTP header log profile for logging,

© 1999-2018 Citrix Systems, Inc. All rights reserved. 339

NetScaler 12.0

of any HTTP requests related to the LSN group. The appliance then
sends the log messages to the configured log servers.
13
14 An HTTP header log profile can be bound to multiple LSN groups but an
LSN group can have only one HTTP header log profile.
15
16 ### To create an HTTP header log profile by using the the command line
interface
17
18 At the command prompt, type:

add lsn httphdrlogprofile [-logURL ( ENABLED | DISABLED )] [-logMethod ( ENABLED | DISABLED )] [-

logVersion ( ENABLED | DISABLED )] [-logHost ( ENABLED | DISABLED )]

show lsn httphdrlogprofile

1 ### To bind an HTTP header log profile to an LSN group by using the the
command line interface
2
3 At the command prompt, type:

bind lsn group -httphdrlogprofilename

show lsn group

1 ### Example
2
3 In the following example of an LSN configuration, HTTP header log
profile HTTP-Header-LOG-1 is bound to LSN group LSN-GROUP-1. The log
profile has all the HTTP attributes (URL, HTTP method, HTTP version
, and HOST IP address) enabled for logging so that all these
attributes are logged for any HTTP requests from subscribers (in the
network 192.0.2.0/24) related to the LSN group.

add lsn httphdrlogprofile HTTP-HEADER-LOG-1

Done

set lsn parameter -memLimit 4000

Done

add lsn client LSN-CLIENT-1

Done

bind lsn client LSN-CLIENT-1 -network 192.0.2.0 -netmask 255.255.255.0

Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 340

NetScaler 12.0

add lsn pool LSN-POOL-1

Done

bind lsn pool LSN-POOL-1 203.0.113.3-203.0.113.4

Done

add lsn group LSN-GROUP-1 -clientname LSN-CLIENT-1 -portblocksize 1024

Done

bind lsn group LSN-GROUP-1 -poolname pool1 LSN-POOL-1

Done

bind lsn group LSN-GROUP-1 -httphdrlogprofilename HTTP-HEADER-LOG-1

Done

1 The NetScaler generates the following HTTP header log message when one
of the subscriber belonging to the LSN configuration example sends
an HTTP request.
2
3 The log message tells us that a client having the IP address 192.0.2.33
sends an HTTP request to URL example.com using HTTP method GET and
HTTP version 1.1.

03/19/2015:16:24:04 GMT Informational 0-PPE-1 : default LSN Message 59 0 : “LSN Client IP:TD
10.102.37.118:0 URL: example.com Host: 192.0.2.33 Version: HTTP1.1 Method: GET”

1 ## Logging MSISDN Information

2
3 A Mobile Station Integrated Subscriber Directory Number (MSISDN)
is a telephone number uniquely identifying a subscriber across
multiple mobile networks. The MSISDN is associated with a country
code and a national destination code identifying the subscriber’s
operator.
4
5 You can configure a NetScaler appliance to include MSISDNs in LSN log
entries for subscribers in mobile networks. The presence of MSISDNs
in the LSN logs helps the administrator in faster and accurate back
tracing of a mobile subscriber who has violated a policy or law, or
whose information is required by lawful interception agencies.
6
7 The following sample LSN log entries include MSISDN information for a
connection from a mobile subscriber in an LSN configuration. The log
entries show that a mobile subscriber whose MSISDN is E164
:5556543210 was connected to destination IP:port 23.0.0.1:80 through
the NAT IP:port 203.0.113.3:45195.
8

© 1999-2018 Citrix Systems, Inc. All rights reserved. 341

NetScaler 12.0

9 |Log Entry Type|Sample Log Entry|

10 |-|-|
11 |LSN session creation|Oct 14 15:37:30 10.102.37.77 10/14/2015:10:08:14
GMT 0-PPE-6 : default LSN LSN_SESSION 25012 0 : SESSION CREATED E164
:5556543210 Client IP:Port:TD 192.0.2.50:4649:0, NatIP:NatPort
203.0.113.3:45195, Destination IP:Port:TD 23.0.0.1:0:0, Protocol:
TCP|
12 |LSN mapping creation|Oct 14 15:37:30 10.102.37.77 10/14/2015:10:08:14
GMT 0-PPE-6 : default LSN LSN_ADDR_MAPPING 25013 0 : ADM
CREATED E164:5556543210 Client IP:Port:TD 192.0.2.50:4649:0, NatIP:
NatPort 203.0.113.3:45195, Destination IP:Port:TD 23.0.0.1:0:0,
Protocol: TCP|
13 |LSN session deletion|Oct 14 15:40:30 10.102.37.77 10/14/2015:10:11:14
GMT 0-PPE-6 : default LSN LSN_SESSION 25012 0 : SESSION CREATED E164
:5556543210 Client IP:Port:TD 192.0.2.50:4649:0, NatIP:NatPort
203.0.113.3:45195, Destination IP:Port:TD 23.0.0.1:0:0, Protocol:
TCP|
14 |LSN mapping|Oct 14 15:40:30 10.102.37.77 10/14/2015:10:11:14 GMT 0-PPE
-6 : default LSN LSN_ADDR_MAPPING 25013 0 : ADM CREATED E164
:5556543210 Client IP:Port:TD 192.0.2.50:4649:0, NatIP:NatPort
203.0.113.3:45195, Destination IP:Port:TD 23.0.0.1:0:0, Protocol:
TCP|
15
16 ### Perform the following tasks for including MSISDN information in LSN
logs
17
18 - **Create an LSN log profile**. An LSN log profile includes the log
subscriber ID parameter, which specifies whether to or not to
include the MSISDN information in the LSN logs of an LSN
configuration. Enable the log subscriber ID parameter when creating
the LSN log profile.
19 - **Bind the LSN log profile to an LSN group of an LSN configuration
**. Bind the created LSN log profile to an LSN group of an LSN
configuration by setting the log profile name parameter to the
created LSN log profile name. For instructions on configuring Large
Scale NAT, see [Configuration Steps for LSN](/en-us/netscaler/12/
netscaler-support-for-telecom-service-providers/lsn-introduction/
configuration-steps-lsn.html).
20
21 #### To create an LSN log profile by using the CLI
22
23 At the command prompt, type:

add lsn logprofile <logprofilename -logSubscriberID ( ENABLED | DISABLED )

© 1999-2018 Citrix Systems, Inc. All rights reserved. 342

NetScaler 12.0

show lsn logprofile

1 #### To bind an LSN log profile to an LSN group of an LSN configuration

by using the CLI
2
3 At the command prompt, type:

bind lsn group -logProfileName

show lsn group

1 **Sample Configuration:**
2
3 In this example of LSN configuration, the LSN log profile has the log
subscriber ID parameter enabled. The profile is bound to LSN group
LSN-GROUP-9. MSISDN information is included in the LSN session and
LSN mapping logs for connections from mobile subscribers (in the
network 192.0.2.0/24).

add lsn logprofile LOG-PROFILE-MSISDN-9 -logSubscriberID ENABLED

Done
add lsn client LSN-CLIENT-9

Done
bind lsn client LSN-CLIENT-9 -network 192.0.2.0 -netmask 255.255.255.0

Done
add lsn pool LSN-POOL-9

Done
bind lsn pool LSN-POOL-9 203.0.113.3-203.0.113.4

Done
add lsn group LSN-GROUP-9 -clientname LSN-CLIENT-9

Done
bind lsn group LSN-GROUP-9 -poolname LSN-POOL-9

Done
bind lsn group LSN-GROUP-9 -logprofilename LOG-PROFILE-MSISDN-9

Done

1 ## Displaying Current LSN Sessions

2
3 You can display the current LSN sessions for detecting any unwanted or
inefficient LSN sessions on the NetScaler appliance. You can display
all or some LSN sessions on the basis of selection parameters.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 343

NetScaler 12.0

4
5 Note: When more than a million LSN sessions exist on the NetScaler
appliance, Citrix recommends displaying selected LSN sessions
instead of all by using the selection parameters.
6
7 ### Configuration Using the Command Line Interface
8
9 #### To display all LSN sessions by using the command line interface
10
11 At the command prompt, type:

show lsn session

1 #### To display selective LSN sessions by using the command line

interface
2
3 At the command prompt, type:

show lsn session [-clientname ] [-network [-netmask ] [-td ]] [-natIP [-natPort ]]

1 ##### Example
2
3 To display all LSN sessions existing on a NetScaler
4
5 
6
7 To display all LSN sessions related to an LSN client entity LSN-CLIENT
-2
8
9 
10 Done
11
12 To display all LSN sessions that uses 203.0.113.5 as the NAT IP address
13
14 
15
16 ### Configuration Using the Configuration Utility
17
18 #### To display all or selected LSN sessions by using the configuration
utility
19
20 1. Navigate to System  > Large Scale NAT > Sessions, and click the
NAT44 tab.
21 1. For displaying LSN sessions on the basis of selection parameters,
click Search.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 344

NetScaler 12.0

22
23 ### Parameter Descriptions (of commands listed in the CLI procedure)
24
25 -
26 show lsn session
27
28 -
29 clientname
30
31 Name of the LSN Client entity. Maximum Length: 127
32
33 -
34 network
35
36 IP address or network address of subscriber(s).
37
38 -
39 netmask
40
41 Subnet mask for the IP address specified by the network
parameter.
42
43 Default value: 255.255.255.255
44
45 -
46 td
47
48 Traffic domain ID of the LSN client entity.
49
50 Default value: 0
51
52 Minimum value: 0
53
54 Maximum value: 4094
55
56 -
57 natIP
58
59 Mapped NAT IP address used in LSN sessions.
60
61 ## Displaying LSN Statistics
62
63 You can display statistics related to the LSN feature for evaluating
the performance of the LSN feature or to troubleshoot problems. You
can display a summary of statistics of the LSN feature or of a

© 1999-2018 Citrix Systems, Inc. All rights reserved. 345

NetScaler 12.0

particular LSN group. The statistical counters reflect events since

the NetScaler appliance was last restarted. All these counters are
reset to 0 when the NetScaler appliance is restarted.
64
65 ### To display all LSN statistics by using the command line interface
66
67 At the command prompt, type:

stat lsn

1 ### To display statistics for a specified LSN group by using the

command line interface
2
3 At the command prompt, type:

stat lsn group []

1 #### Example

stat lsn

Large Scale NAT statistics

Rate(/s) Total
LSN TCP Received Packets 0 40
LSN TCP Received Bytes 0 3026
LSN TCP Transmitted Packets 0 40
LSN TCP Transmitted Bytes 0 3026
LSN TCP Dropped Packets 0 0
LSN TCP Current Sessions 0 0
LSN UDP Received Packets 0 0
LSN UDP Received Bytes 0 0
LSN UDP Transmitted Packets 0 0
LSN UDP Transmitted Bytes 0 0
LSN UDP Dropped Packets 0 0
LSN UDP Current Sessions 0 0
LSN ICMP Received Packets 0 982
LSN ICMP Received Bytes 0 96236
LSN ICMP Transmitted Packets 0 0
LSN ICMP Transmitted Bytes 0 0
LSN ICMP Dropped Packets 0 982
LSN ICMP Current Sessions 0 0
LSN Subscribers 0 1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 346

NetScaler 12.0

Done
stat lsn group LSN-GROUP-1

LSN Group Statistics

Rate (/s) Total
TCP Translated Pkts 0 40
TCP Translated Bytes 0 3026
TCP Dropped Pkts 0 0
TCP Current Sessions 0 0
UDP Translated Pkts 0 0
UDP Translated Bytes 0 0
UDP Dropped Pkts 0 0
UDP Current Sessions 0 0
ICMP Translated Pkts 0 0
ICMP Translated Bytes 0 0
ICMP Dropped Pkts 0 0
ICMP Current Sessions 0 0
Current Subscribers 0 1
Done

1 ### Parameter Descriptions (of commands listed in the CLI procedure)

2
3 -
4 stat lsn group
5
6 -
7 groupname
8
9 Name of the LSN Group. Maximum Length: 127
10
11 -
12 detail
13
14 Specifies detailed output (including more statistics). The
output can be quite voluminous. Without this argument, the
output will show only a summary.
15
16 -
17 fullValues
18
19 Specifies that numbers and strings should be displayed in their
full form. Without this option, long strings are shortened
and large numbers are abbreviated.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 347

NetScaler 12.0

20
21 -
22 ntimes
23
24 The number of times, in intervals of seven seconds, the
statistics should be displayed.
25
26 Default value: 1
27
28 -
29 logFile
30
31 The name of the log file to be used as input.
32
33 -
34 clearstats
35
36 Clear the statsistics / counters
37
38 Possible values: basic, full
39
40 ## Compact Logging
41
42 Logging LSN information is one of the important functions needed by
ISPs to meet legal requirements and be able to identify the source
of traffic at any given time. This eventually results in a huge
volume of log data, requiring the ISPs to make large investments to
maintain the logging infrastructure.
43
44 Compact logging is a technique for reducing the log size by using a
notational change involving short codes for event and protocol names
. For example, C for client, SC for session created, and T for TCP.
 Compact logging results in an average of 40 percent reduction in
log size.
45
46 The following examples of NAT44 mapping creation log entries show the
advantage of compact logging.
47
48 |-|-|
49
50 |Default logging format|02/02/2016:01:13:01 GMT Informational 0-PPE-2 :
default LSN LSN_ADDRPORT_MAPPING 85 0 : A&PDM CREATED ClientIP:Port
:TD1.1.1.1:6500:0,NatIP:NatPort8.8.8.8:47902, DestinationIP:Port:TD2
.2.2.2:80:0, Protocol: TCP|
51 |Compact logging format|02/02/2016:01:14:57 GMT Info 0-PE2:default LSN

© 1999-2018 Citrix Systems, Inc. All rights reserved. 348

NetScaler 12.0

87 0:A&PDMC|C-1.1.1.1:6500:0|N-8.8.8.9:51066|D-2.2.2.2:80:0|T|
52
53 ## Configuration Steps
54
55 Perform the following tasks for logging LSN information in compact
format:
56
57 - **Create an LSN log profile.** An LSN log profile includes the Log
Compact parameter, which specifies whether to or not to log
information in compact format for an LSN configuration.
58 - **Bind the LSN log profile to an LSN group of an LSN configuration
.** Bind the created LSN log profile to an LSN group of an LSN
configuration by setting the Log Profile Name parameter to the
created LSN log profile name. All sessions and mappings for this LSN
group are logged in compact format.
59
60 ### To create an LSN log profile by using the CLI
61
62 At the command prompt, type:

add lsn logprofile -logCompact (ENABLED|DISABLED)

show lsn logprofile

1 ### To bind an LSN log profile to an LSN group of an LSN configuration

by using the CLI
2
3 At the command prompt, type:

bind lsn group -logProfileName

show lsn group

1 **Sample configuration:**

add lsn logprofile LOG-PROFILE-COMPACT-9 -logCompact ENABLED

Done
add lsn client LSN-CLIENT-9
Done
bind lsn client LSN-CLIENT-9 -network 192.0.2.0 -netmask 255.255.255.0
Done
add lsn pool LSN-POOL-9
Done
bind lsn pool LSN-POOL-9 203.0.113.3-203.0.113.4

© 1999-2018 Citrix Systems, Inc. All rights reserved. 349

NetScaler 12.0

Done
add lsn group LSN-GROUP-9 -clientname LSN-CLIENT-9
Done
bind lsn group LSN-GROUP-9 -poolname LSN-POOL-9
Done
bind lsn group LSN-GROUP-9 –logProfileName LOG-PROFILE-COMPACT-9
Done

1 ## IPFIX Logging
2
3 The NetScaler appliance supports sending information about LSN events
in Internet Protocol Flow Information Export (IPFIX) format to the
configured set of IPFIX collector(s). The appliance uses the
existing AppFlow feature to send LSN events in IPFIX format to the
IPFIX collectors.
4
5 IPFIX based logging is available for the following large scale NAT44
related events:
6
7 - Creation or deletion of an LSN session.
8 - Creation or deletion of an LSN mapping entry.
9 - Allocation or de-allocation of port blocks in the context of
deterministic NAT.
10 - Allocation or de-allocation of port blocks in the context of dynamic
NAT.
11 - Whenever subscriber session quota is exceeded.
12
13 ### Points to Consider before you Configure IPFIX logging
14
15 Before you start configuring IPSec ALG, consider the following points:
16
17 - You must configure the AppFlow feature and IPFIX collector(s) on the
NetScaler appliance. For instructions, see Configuring the AppFlow
feature topic.
18
19 ### Configuration Steps
20
21 Perform the following tasks for logging LSN information in IPFIX format
:
22
23 - **Enable LSN logging in the AppFlow configuration**. Enable the LSN
logging parameter as part of AppFlow configuration.
24 - **Create an LSN log profile**. An LSN log profile includes the IPFIX
parameter that enables or disables the log information in IPFIX

© 1999-2018 Citrix Systems, Inc. All rights reserved. 350

NetScaler 12.0

format.
25 - **Bind the LSN log profile to an LSN group of an LSN configuration
**. Bind the LSN log profile to one or multiple LSN group(s). Events
related to the bound LSN group will be logged in IPFIX format.
26
27 #### To enable LSN logging in the AppFlow configuration by using the
CLI
28
29 At the command prompt, type:

set appflow param -lsnLogging ( ENABLED | DISABLED )

show appflow param

1 #### To create an LSN log profile by using the CLIAt the command prompt
2
3 At the command prompt, type:

set lsn logprofile -logipfix ( ENABLED | DISABLED )

show lsn logprofile

1 #### To bind the LSN log profile to an LSN group of an LSN

configuration by using the CLI
2
3 At the command prompt, type:

bind lsn group -logProfileName

show lsn group

“‘

To create an LSN log profile by using the GUI

Navigate to System > Large Scale NAT > Profiles, click Log tab, and then add a log profile.

To bind the LSN log profile to an LSN group of an LSN configuration by using the GUI

1. Navigate to System > Large Scale NAT > LSN Group, open the LSN group.
2. In Advanced Settings, click + Log Profile to bind the created Log profile to the LSN group.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

© 1999-2018 Citrix Systems, Inc. All rights reserved. 351

NetScaler 12.0

STUN Timeout

September 17, 2018

Contributed by:
C

STUN (Session Traversal Utilities for NAT) enables an end host operating behind a NAT device to dis-
cover its NAT IP address and NAT port allocated by the NAT device. Interactive communication ap-
plications (for example real-time voice, video, and messaging) running on these hosts use the STUN
protocol for discovering NAT IP address and port information. This information is used by these appli-
cations to connect to their peer applications in the Internet. STUN protocol includes servers, known
as STUN servers, residing in the Internet. Using the STUN protocol, an application of an end host
sends a request to a known STUN server, which in turn then embeds the NAT IP address and port in
the payload of its response packet.

In an LSN deployment of a NetScaler appliance for an ISP, interactive communication applications

(for example real-time voice, video, and messaging) running on a subscribers can use the STUN pro-
tocol to discover whether it is behind a NAT (NetScaler appliance) device or not. These applications
send a request to a known STUN server. On receiving the request, the NetScaler allocates a NAT IP
address and a port for this request, creates an LSN session and an LSN mapping entry, translates the
packet with the allocated NAT IP address and port, and then forwards the packet to the STUN server.
The STUN server embeds the allocated NAT IP address and port in the payload of its response packet.
When the subscriber finally receives the packet, from the payload of the packet it learns that it is be-
hind a NAT device, and the NAT IP address and port allocated for the session.

The application then notifies the peer applications that it is reachable at the NAT IP address and the
port of the LSN mapping entry created for the STUN session. It notifies by embedding the NAT IP ad-
dress and port in the payload of the packets sent to the peer applications. For making the application
reachable at the same LSN mapping entry for any external application, full Cone NAT (endpoint In-
dependent mapping and Endpoint Independent filtering) is enabled for the LSN configuration on the
NetScaler appliance.

The NetScaler detects an LSN session of type STUN if the request packets are destined to TCP or UDP
port 3478, and then marks the created mapping entry of type STUN. The NetScaler applies a time-
out called, STUN timeout, to the created STUN LSN mapping entry. A STUN timeout is the maximum
time that the NetScaler maintains an idle STUN LSN mapping entry since it was last used by any LSN
session. If the STUN LSN mapping session is unused for a time that exceeds the STUN timeout, the
NetScaler removes the mapping entry.

For an application on a subscriber that use STUN LSN mapping entry to stay available to other peer
applications on the Internet, the application periodically sends keep-alive messages to the NetScaler

© 1999-2018 Citrix Systems, Inc. All rights reserved. 352

NetScaler 12.0

appliance so that the STUN LSN mapping entry does not timeout. A higher frequency of keep-alive
messages can have an affect on the performance a subscriber, especially, if the subscriber is a mo-
bile device. A higher value of STUN timeout reduces the frequency of keep-alive messages from a
subscriber.

ALGs on the NetScaler appliance do not apply to an LSN session that use a STUN LSN mapping en-
try because NAT IP address and NAT port are communicated in payload of the packets related to the
session.

For subscribers’ applications that use STUN protocol, the LSN configuration must have the following
settings:

• STUN timeout. In an LSN configuration, the LSN group includes the STUN timeout setting.
• Endpoint-independent mapping and endpoint-independent filtering for STUN protocol ports.

For instructions on creating an LSN configuration, see Configuration Steps for LSN.

Example:

The following sample LSN configuration applies to applications that use STUN protocol over TCP or
UDP. STUN timeout is set to 10 mins. Endpoint-independent mapping and endpoint-independent fil-
tering is set for the STUN TCP port (3748) and the STUN UDP port (3748).

1 add lsn client LSN-CLIENT-1

2
3 Done
4
5 bind lsn client LSN-CLIENT-1 -network 192.0.2.0 -netmask 255.255.255.0
6
7 Done
8
9 add lsn pool LSN-POOL-1
10
11 Done
12
13 bind lsn pool LSN-POOL-1 203.0.113.3
14
15 Done
16
17 add lsn group LSN-GROUP-1 -clientname LSN-CLIENT-1 -stuntimeout 10
18
19 Done
20
21 bind lsn group LSN-GROUP-1 -poolname pool1 LSN-POOL-1
22
23 Done
24

© 1999-2018 Citrix Systems, Inc. All rights reserved. 353

NetScaler 12.0

25 add lsn appsprofile LSNAPPSPROFILE-TCP-STUN-1 TCP -mapping ENDPOINT-

INDEPENDENT ‒ filtering ENDPOINT-INDEPENDENT
26
27 Done
28
29 bind lsn appsprofile LSNAPPSPROFILE-TCP-STUN-1 3748
30
31 Done
32
33 bind lsn group LSN-GROUP-1 -applicationprofilename LSNAPPSPROFILE-TCP-
STUN-1
34
35 Done
36
37 add lsn appsprofile LSNAPPSPROFILE-UDP-STUN-1 UDP -mapping ENDPOINT-
INDEPENDENT ‒ filtering ENDPOINT-INDEPENDENT
38
39 Done
40
41 bind lsn appsprofile LSNAPPSPROFILE-UDP-STUN-1 3748
42
43 Done
44
45 bind lsn group LSN-GROUP-1 -applicationprofilename LSNAPPSPROFILE-UDP-
STUN-1
46
47 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

TCP SYN Idle Timeout

September 17, 2018

Contributed by:
C

SYN idle timeout is the timeout for establishing TCP connections that use LSN on the NetScaler appli-
ance. If a TCP session is not established within the configured timeout period, the NetScaler removes

© 1999-2018 Citrix Systems, Inc. All rights reserved. 354

NetScaler 12.0

the session. SYN idle timeout is useful in providing protection against SYN flood attacks. In an LSN
configuration, the LSN group entity includes the SYN idle timeout setting.

Example:

In the following sample LSN configuration, SYN idle timeout is set to 30 secs for TCP connections re-
lated to subscribers from the 192.0.2.0/24 network.

1 add lsn client LSN-CLIENT-1

2
3 Done
4
5 bind lsn client LSN-CLIENT-1 -network 192.0.2.0 -netmask 255.255.255.0
6
7 Done
8
9 add lsn pool LSN-POOL-1
10
11 Done
12
13 bind lsn pool LSN-POOL-1 203.0.113.3
14
15 Done
16
17 add lsn group LSN-GROUP-1 -clientname LSN-CLIENT-1 ‒ synidletimeout 30
18
19 Done
20
21 bind lsn group LSN-GROUP-1 -poolname pool1 LSN-POOL-1
22
23 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Overriding LSN configuration with Load Balancing Configuration

September 17, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 355

NetScaler 12.0

An LSN configuration takes precedence over any load balancing configuration by default. For over-
riding the large scale networking (LSN) configuration with the load balancing configuration for traffic
matching both configurations, create a net profile with Override LSN parameter enabled and bind
this profile to the virtual server of the load balancing configuration. USNIP or USIP settings of the load
balancing configuration are applied to the traffic, instead of applying the LSN IP address of the LSN
configuration.

This option is useful in an LSN deployment that includes NetScaler appliances and value added ser-
vices, such as firewall and optimization devices. In this type of deployment, the ingress traffic on the
NetScaler appliance is required to pass through these value-added services before an LSN configura-
tion on the appliance is applied to the traffic. For the NetScaler appliance to send the ingress traffic
to a value added service, a load balancing configuration is created and override LSN is enabled on
the appliance. The load balancing configuration includes value added services, represented as load
balancing services, bound to a virtual server of type ANY. The virtual server is configured with listen
policies for identifying the traffic to be sent to the value added service.

To enable override lsn in a net profile by using the CLI

To enable override lsn while adding a net profile, at the command prompt, type

1 add netProfile <name> -overrideLsn ( ENABLED | DISABLED )

2
3 show netprofile <name>

To enable override lsn while adding a net profile, at the command prompt, type

1 set netProfile <name> -overrideLsn ( ENABLED | DISABLED )

2
3 show netprofile <name>

To enable override lsn in a net profile by using GUI

1. Navigate to System > Network > Net Profiles.

2. Set the Override LSN parameter while adding or modifying net profiles.

In the following sample configuration, net profile NETPROFILE-OVERRIDELSN-1 has override LSN op-
tion enabled and is bound to load balancing virtual server LBVS-1.

Sample configuration:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 356

NetScaler 12.0

1 add netprofile NETPROFILE-OVERRIDELSN-1 -overrideLsn ENABLED

2
3 Done
4
5 set lb vserver LBVS-1 -netprofile NETPROFILE-OVERRIDELSN-1
6
7 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Clearing LSN Sessions

September 17, 2018

Contributed by:
C

You can remove any unwanted or inefficient LSN sessions from the NetScaler appliance. The appli-
ance immediately releases resources (such as NAT IP address, port, and memory) allocated for these
sessions, making the resources available for new sessions. The appliance also drops all the subse-
quent packets related to these removed sessions. You can remove all or selected LSN sessions from
the NetScaler appliance.

To clear all LSN sessions by using the command line interface

At the command prompt, type:

1 flush lsn session

2
3 show lsn session

To clear selective LSN sessions by using the command line interface

At the command prompt, type:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 357

NetScaler 12.0

1 flush lsn session [-clientname <string>] [-network <ip_addr> [-netmask

<netmask>] [-td <positive_integer>]] [-natIP <ip_addr> [-natPort <
port>]]
2
3 show lsn session

Example

Clear all LSN sessions existing on a NetScaler

1 flush lsn session

2
3 Done

Clear all LSN sessions related to LSN client entity LSN-CLIENT-1

1 flush lsn session -clientname LSN-CLIENT-1

2
3 Done

Clear all LSN sessions related to a subscriber network (192.0.2.0) of LSN client entity LSN-CLIENT-2
belonging to traffic domain 100

1 flush lsn session -clientname LSN-CLIENT-2 ‒ network 192.0.2.0 ‒

netmask 255.255.255.0 ‒ td 100
2
3 Done

To clear all LSN sessions by using the configuration utility

Navigate to System > Large Scale NAT > Sessions, and click Flush Sessions.

Parameter Descriptions (of commands listed in the CLI procedure)

• flush lsn session

– clientname

Name of the LSN Client entity. Maximum Length: 127

– network

IP address or network address of subscriber(s).

© 1999-2018 Citrix Systems, Inc. All rights reserved. 358

NetScaler 12.0

– netmask

Subnet mask for the IP address specified by the network parameter.

Default value: 255.255.255.255

– td

Traffic domain ID of the LSN client entity.

Default value: 0

Minimum value: 0

Maximum value: 4094

– natIP

Mapped NAT IP address used in LSN sessions.

– natPort

Mapped NAT port used in the LSN sessions.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Load Balancing SYSLOG Servers

September 17, 2018

Contributed by:
C

The NetScaler appliance send its SYSLOG events and messages to all the configured external log
servers. This results in storing redundant messages and makes monitoring difficult for system
administrators. To address this issue, the NetScaler appliance offers load balancing algorithms
that can load balance the SYSLOG messages among the external log servers for better maintenance
and performance. The supported load balancing algorithms include RoundRobin, LeastBandwidth,
CustomLoad, LeastConnection, LeastPackets, and AuditlogHash.

Load balancing of SYSLOG servers using the command line interface

At the command prompt, type:

Add a service and specify the service type as SYSLOGTCP or SYSLOGUDP.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 359

NetScaler 12.0

1 add service <name>(<IP> | <serverName>) <serviceType (SYSLOGTCP |

SYSLOGUDP)> <port>

Add a load balancing virtual server, specify the service type as SYSLOGTCP or SYSLOGTCP, and load
balancing method as AUDITLOGHASH.

1 add lb vserver <name> <serviceType (SYSLOGTCP | SYSLOGUDP)> [-lbMethod 

<AUDITLOGHASH>]

Bind the service to the load balancing virtual server.

1 bind lb vserver <name> <serviceName>

1. Add a SYSLOG action and specify the load balancing server name that has SYSLOGTCP or SYS-
LOGUDP as service type.

1 add syslogaction <name> <serverIP> [-lbVserverName <string>] [-

logLevel <logLevel>]

Add a SYSLOG policy by specifying the rule and action.

1 add syslogpolicy <name> <rule> <action>

Bind the SYSLOG policy to the system global for the policy to take effect.

1 bind system global <policyName>

Load balancing of SYSLOG servers using the configuration utility

1. Add a service and specify the service type as SYSLOGTCP or SYSLOGUDP.

Navigate to Traffic Management > Services, click Add and select SYLOGTCP or SYSLOGUDP as
protocol.
2. Add a load balancing virtual server, specify the service type as SYSLOGTCP or SYSLOGTCP, and
load balancing method as AUDITLOGHASH.
Navigate to Traffic Management > Virtual Servers, click Add and select SYLOGTCP or SYSLOGUD-
Pas protocol.
3. Bing the service to the load balancing virtual server to the service.
Bing the service to the load balancing virtual server.
Navigate to Traffic Management > Virtual Servers, select a virtual server and then selectAUDIT-
LOGHASH in the Load Balancing Method.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 360

NetScaler 12.0

4. Add a SYSLOG action and specify the load balancing server name that has SYSLOGTCP or SYS-
LOGUDP as service type.

Navigate to System > Auditing, click Servers and add a server by selecting LB Vserver option
inServers.

5. Add a SYSLOG policy by specifying the rule and action.

Navigate to System > Syslog, click Policies and add a SYSLOG policy.

6. Bind the SYSLOG policy to the system global for the policy to take effect.

Navigate to System > Syslog, select a SYSLOG policy and click Action, and then click Global Bind-
ings and bind the policy to system global.

Example:

The following configuration specifies load balance of SYSLOG messages among the external log
servers using the AUDITLOGHASH as load balancing method. The NetScaler appliance generates
SYSLOG events and messages that are load balanced amongst the services, service1, service2, and
service 3.

1 add service service1 192.0.2.10 SYSLOGUDP 514

2
3 add service service2 192.0.2.11 SYSLOGUDP 514
4
5 add service service3 192.0.2.11 SYSLOGUDP 514
6
7 add lb vserver lbvserver1 SYSLOGUDP -lbMethod AUDITLOGHASH
8
9 bind lb vserver lbvserver1 service1
10
11 bind lb vserver lbvserver1 service2
12
13 bind lb vserver lbvserver1 service3
14
15 add syslogaction sysaction1 -lbVserverName lbvserver1 -logLevel All
16
17 add syslogpolicy syspol1 ns_true sysaction1
18
19 bind system global syspol1

Limitations:

The NetScaler appliance does not support an external load balancing virtual server load balancing the
SYSLOG messages among the log servers.

1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 361

NetScaler 12.0

2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Port Control Protocol

September 17, 2018

Contributed by:
C

NetScaler appliances now support Port Control Protocol (PCP) for large scale NAT (LSN). Many of an
ISP’s subscriber applications must be accessible from Internet (for example, Internet of Things (IOT)
devices, such as an IP camera that provides surveillance over the Internet). One way to meet this
requirement is to create static large scale NAT (LSN) maps. But for a very large number of subscribers,
creating static LSN NAT maps is not a feasible solution.

Port Control Protocol (PCP) enables a subscriber to request specific LSN NAT mappings for itself
and/or for other 3rd party devices. The large scale NAT device creates an LSN map and sends it to the
subscriber. The subscriber sends the remote devices on the Internet the NAT IP address:NAT port at
which they can connect to the subscriber.

Applications usually send frequent keep-alive messages to the large scale NAT device so that their LSN
mappings do not time out. PCP helps reduce the frequency of such keep-alive messages by enabling
the applications to learn the timeout settings of the LSN mappings. This helps reduce bandwidth
consumption on the ISP’s access network and battery consumption on mobile devices.

PCP is a client-server model and runs over the UDP transport protocol. A NetScaler appliance imple-
ments the PCP server component and is compliant with RFC 6887.

Configuration Steps

Perform the following tasks for configuring PCP:

• (Optional) Create a PCP profile. A PCP profile includes settings for PCP related parameters (for
example, to listen for mapping and peer PCP requests). A PCP profile can be bound to a PCP
server. A PCP profile bound to a PCP server applies all its settings to the PCP server. A PCP profile
can be bound to multiple PCP servers. By default, one PCP profile with default parameters
settings is bound to all PCP servers. A PCP profile that you bind to a PCP server overrides the
default PCP profile settings for that server. A default PCP profile has the following parameter
settings:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 362

NetScaler 12.0

– Mapping: Enabled
– Peer: Enabled
– Minimum map life: 120 seconds
– Maximum max life: 86400 seconds
– Announce count: 10
– Third Party: Disabled
• Create a PCP server and bind a PCP profile to it. Create a PCP server on the NetScaler appliance
to listen for PCP related requests and messages from the subscribers. A Subnet IP (SNIP) address
must be assigned to a PCP server to access it. By default, a PCP server listens on port 5351.
• Bind the PCP server to an LSN group of an LSN configuration. Bind the created PCP server to an
LSN group of an LSN configuration by setting the PCP Server parameter to specify the created
PCP server. The created PCP server can be accessed only by the subscribers of this LSN group.

Note

A PCP server for a large scale NAT configuration does not serve requests from subscribers that
are identified from ACL rules.

To create a PCP profile by using the CLI

At the command prompt, type:

1 add pcp profile <name> [-mapping ( ENABLED | DISABLED )] [-peer (

ENABLED | DISABLED )] [-minMapLife <secs>]  [-maxMapLife <secs>] [-
announceMultiCount <positive_integer>][-thirdParty ( ENABLED |
DISABLED )]
2
3 show pcp profile <name>

To create a PCP server by using the CLI

At the command prompt, type:

1 add pcp server <name> <IPAddress> [-port <portNum|*>] [-pcpProfile <

string>]
2
3 show pcp server <name>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 363

NetScaler 12.0

Sample Configuration for NAT44

In the following sample configuration, PCP server PCP-SERVER-9, with default PCP settings, is
bound to LSN group LSN-GROUP-9. PCP-SERVER-9 serves PCP requests from subscribers in network
192.0.2.0/24.

Sample configuration:

1 add pcp server PCP-SERVER-9 192.0.3.9

2
3 Done
4
5 add lsn client LSN-CLIENT-9
6
7 Done  
8
9 bind lsn client LSN-CLIENT-9 -network 192.0.2.0 -netmask 255.255.255.0
10
11 Done  
12
13 add lsn pool LSN-POOL-9
14
15 Done  
16
17 bind lsn pool LSN-POOL-9 203.0.113.3-203.0.113.4
18
19 Done
20
21 add lsn group LSN-GROUP-9 -clientname LSN-CLIENT-9
22
23 Done  
24
25 bind lsn group LSN-GROUP-9 -poolname LSN-POOL-9
26
27 Done  
28
29 bind lsn group  LSN-GROUP-9  -pcpServer PCP-SERVER-9
30
31 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

© 1999-2018 Citrix Systems, Inc. All rights reserved. 364

NetScaler 12.0

Dual-Stack Lite

January 6, 2019
Contributed by:
C
Because of the shortage of IPv4 addresses, and the advantages of IPv6 over IPv4, many ISPs have
started transitioning to IPv6 infrastructure. But during the transition, ISPs must continue to support
IPv4 along with IPv6, because most of the public Internet still uses only IPv4, and many subscribers
do not support IPv6.
Dual Stack Lite (DS-Lite) is an IPv6 transition solution for ISPs with IPv6 infrastructure to connect their
IPv4 subscribers to the Internet. DS-Lite uses IPv4-in-IPv6 tunneling to send a subscriber’s IPv4 packet
through a tunnel on the IPv6 access network to the ISP. The IPv6 packet is decapsulated to recover the
subscriber’s IPv4 packet and is then sent to the Internet after NAT address and port translation and
other LSN related processing. The response packets traverse through the same path to the subscriber.
The NetScaler appliance implements the AFTR component of a DS-Lite deployment and is compliant
with RFC 6333.

Architecture

The Dual-Stack Lite architecture for an ISP consists of the following components:
• Basic Bridging Broadband (B4). Basic Bridging broadband, or B4, is a device or component
that resides in the subscriber premises. Typically, B4 is a component in the CPE devices in
the subscriber premises. IPv4 subscribers are connected to the IPv6-only ISP access network
through the CPE device containing the B4 component. The main function of the B4 is to initiate
an IPv6 tunnel between B4 and an address family transition router (AFTR) in order to send or re-
ceive subscriber IPv4 request or response packets over the tunnel. B4 includes an IPv6 address
known as the B4 tunnel endpoint address. B4 uses this address to source IPv6 packets to AFTR
and receive packets from AFTR.
• Address family transition router (AFTR). AFTR is a device or component residing in the ISP’s
core network. AFTR terminates the IPv6 tunnel from the B4 device. In other words, the IPv6 tun-
nel is formed between B4 in the subscriber premise and AFTR in ISP core network. AFTR decap-
sulates IPv6 packets received from B4 to recover the subscribers’ original IPv4 packets. AFTR
sends the IPv4 packets to the LSN device or component. LSN routes the IPv4 packets to their
destination after performing NAT address and port translation (NAT 44) and other LSN related
processing. AFTR includes an IPv6 address known as the AFTR tunnel endpoint address. AFTR
uses this address to source IPv6 packets to B4 and receive IPv6 packets from B4. The NetScaler
appliance implements the AFTR component.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 365

NetScaler 12.0

• Softwire. The IPv6 tunnel created between B4 and AFTR is called a softwire.

The DS-Lite architecture of an ISP using a NetScaler appliance consists of subscribers in private ad-
dress spaces accessing the Internet through a NetScaler appliance deployed in ISP’s core network.
IPv4 subscribers are connected to a CPE device that includes the DS-Lite B4 functionality. The CPE
device is connected to the ISP core network through ISP’s IPv6-only access network. The NetScaler
appliance contains the DS-Lite AFTR and LSN functionality.

IPv4 subscribers connected to the CPE device are assigned private IPv4 addresses either manually
or through DHCP server running on the CPE device. On the CPE device, the AFTR tunnel endpoint
address is specified manually or through DHCPv6. Configuration of CPE devices is vendor specific
and therefore outside the scope of this documentation.

Upon receiving a request packet that is from an IPv4 subscriber and destined to a location on the In-
ternet, the B4 component of the CPE device encapsulates the IPv4 packet in an IPv6 packet and sends
it to the NetScaler appliance in the ISP core network. The NetScaler appliance‘s AFTR functionality
decapsulates the IPv6 packet to recover the subscriber’s original IPv4 packet. The LSN functionality
of the NetScaler appliance translates the source IP address and port of the IPv4 packet to an NAT IP
address and NAT port selected from the configured NAT pool, and then sends the packet to its desti-
nation on the Internet.

The appliance maintains a record of all active sessions that use the AFTR and LSN functionalities.
These sessions are called DS-Lite sessions. The NetScaler appliance also maintains the mappings
between B4 IPv6 address, subscriber IPv4 address and port, and NAT IPv4 address and port, for each
DS-Lite session. These mappings are called DS-Lite LSN mappings. From DS-Lite session entries and
DS-Lite LSN mapping entries, the NetScaler appliance recognizes a response packet (received from
the Internet) as belonging to a particular DS-Lite session.

When the NetScaler appliance receives a response packet belonging to a particular DS-Lite session,
the appliance’s LSN functionality translates the destination IP address and port of the response packet
from NAT IP address and port to the subscriber IP address and port, the AFTR functionality encapsu-
lates the resulting packet in an IPv6 packet and sends it to the CPE device. The B4 functionality of
the CPE device decapsulates the IPv6 packet to recover the IPv4 response packet, and then sends the
IPv4 packet to the subscriber.

Example

Consider an example of a DS-Lite deployment consisting of NetScaler NS-1 in an ISP’s core network,
CPE device B4-CPE-1 in a subscriber premise, and a single IPv4 subscriber SUB-1. B4-CPE-1 supports
the B4 functionality of DS-Lite feature.

The following table lists the settings used in this example.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 366

NetScaler 12.0

Entity Name Details

IPv4 address of subscriber 192.0.2.51

SUB-1
IPv6 address of softwire 2001:DB8::3:4
endpoint on the B4 device
(B4-CPE-1)
IPv6 address of the softwire 2001:DB8::5:6
endpoint on the AFTR device
(NS-1)

Settings on NetScaler appliance NS-1:

Entity Name Details

LSN client LSN-DSLITE-CLIENT-1 Network6 (Identifying traffic

from B4 devices) =
2001:DB8::3:0/100
LSN pool LSN-DSLITE-POOL-1 LSN IPs (NAT IP) = 203.0.113.61
- 203.0.113.70
IPv6 Profile LSN-DSLITE-PROFILE-1 Type = DS-LITE; IPv6 address
(AFTR IPv6 address) = One of
the NetScaler owned IPv6
address of type SNIP6 =
2001:DB8::5:6
LSN group LSN-DSLITE-GROUP-1 LSN client =
LSN-DSLITE-CLIENT-1; LSN
pool =
LSN-DSLITE-POOL-1;IPv6
profile =
LSN-DSLITE-PROFILE-1

Following is the traffic flow in this example:

1. IPv4 subscriber SUB-1 sends a request to (http://www.example.com/). The IPv4 packet has:

• Source IP address = 192.0.2.51

• Source port = 2552
• Destination IP address = 198.51.100.250

© 1999-2018 Citrix Systems, Inc. All rights reserved. 367

NetScaler 12.0

• Destination port = 80

2. Upon receiving the IPv4 request packet, B4-CPE-1 encapsulates it in the payload of an IPv6 packet
and then sends the IPv6 packet to NS-1. The IPv6 packet has:

• Source IP address = 2001:DB8::3:4

• Destination IP address = 2001:DB8::5:6

3. When NS-1 receives the IPv6 packet, the AFTR module decapsulates the packet by removing the
IPv6 headers. The resulting packet is SUB-1’s original IPv4 request packet.

4. The LSN module of NS-1 translates the source IP address and port of the packet to an NAT IP
address and NAT port selected from the configured NAT pool. The translated IPv4 packet has:

• Source IP address = 203.0.113.61

• Source port = 3002
• Destination IP address = 198.51.100.250
• Destination port = 80

5. The LSN module also creates an LSN mapping and session entry for this DS Lite session. The
mapping includes the following information:

• Source IP address of the IPv6 packet (B4-CPE-1’s IPv6 address) = 2001:DB8::3:4

• Source IP address of the IPv4 packet (SUB-1’s IPv4 address) = 192.0.2.51
• Source port of the IPv4 packet = 2552
• NAT IP address = 203.0.113.61
• NAT port = 3002

6. NS-1 sends the resulting IPv4 packet to its destination on the Internet.

7. The server for www.example.com processes the request packet and sends a response packet. The
IPv4 response packet has:

• Source IP address = 198.51.100.250

• Source port = 80
• Destination IP address = 203.0.113.61
• Destination port = 3002

8. Upon receiving the IPv4 packet, NS-1 examines the LSN mapping and session entries and finds
that the IPv4 response packet belongs to a DS Lite session. The LSN module of NS-1 translates the
destination IP address and port. The IPv4 packet now has:

• Source IP address = 198.51.100.250

• Source port = 80
• Destination IP address = 192.0.2.51
• Destination port = 2552

© 1999-2018 Citrix Systems, Inc. All rights reserved. 368

NetScaler 12.0

9. The AFTR module of NS-1 encapsulates the IPv4 packet in an IPv6 packet and then sends the IPv6
packet to B4-CPE-1. The IPv6 packet has:

• Source IP address = 2001:DB8::5:6

• Destination IP address = 2001:DB8::3:4

10. Upon receiving the packet, B4-CPE-1 decapsualtes the IPv6 packet by removing the IPv6 headers,
and then sends the resulting IPv4 packet to CL-1.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Points to Consider before Configuring DS-Lite

September 17, 2018

Contributed by:
C

Consider the following points before configuring DS-Lite on a NetScaler appliance:

1. You must understand the different components of DS-Lite, described in RFC 6333.

2. A DS-lite configuration on a NetScaler appliance uses the LSN commands sets. In a DS-Lite configu-
ration, the LSN client entity specifies the IPv6 address or IPv6 network address or ACL6 rules for iden-
tifying the traffic from the B4 device. A DS-Lite configuration also includes an IPv6 profile, which spec-
ifies the IPv6 address AFTR component on a NetScaler appliance. For more information on NetScaler
LSN feature, see Large Scale NAT.

3. For a DS-Lite configuration, the NetScaler appliance supports LSN for IPv4 packets that belong to
one of the following protocols only. The NetScaler appliance drops IPv4 packets belonging to other
protocols:

• TCP
• UDP
• ICMP

4. The NetScaler appliance supports the following ALGs DS-Lite:

• ICMP
• FTP
• TFTP
• Session Initiation Protocol (SIP)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 369

NetScaler 12.0

• Real Time Streaming Protocol (RTSP)

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Configuring DS-Lite

September 20, 2018

Contributed by:
C

A DS-lite configuration on a NetScaler appliance uses the LSN commands sets. In a DS-Lite configura-
tion, the LSN client entity specifies the IPv6 address or IPv6 network address or ACL6 rules for iden-
tifying the traffic from the B4 device. For more information on the NetScaler LSN feature, see Large
Scale NAT. A DS-Lite configuration also includes an IPv6 profile, which specifies the IPv6 address (of
type SNIP6) of the DS-Lite AFTR component on a NetScaler appliance.

Configuring DS-Lite on a NetScaler appliance consists of the following tasks:

Set the global LSN parameters. Global parameters include the amount of NetScaler memory re-
served for the LSN feature and synchronization of LSN sessions in a high availability setup.

• Create an LSN client entity for identifying traffic from B4 CPE devices. The LSN client entity
refers to a set of DS-Lite B4 devices. The client entity includes IPv6 addresses or IPv6 network
address or ACL6 rules for identifying the traffic from these B4 devices. An LSN client can be
bound to only one LSN group. The command line interface has two commands for creating
an LSN client entity and binding a subscriber to the LSN client entity. The configuration utility
combines these two operations on a single screen.
• Create an LSN pool and bind NAT IP addresses to it. An LSN pool defines a pool of NAT IP
addresses to be used by the NetScaler appliance to perform LSN. The command line interface
has two commands for creating an LSN pool and binding NAT IP addresses to the LSN pool. The
configuration utility combines these two operations on a single screen.
• Create an LSN IP6 profile. An LSN IP6 profile defines the IPv6 address of the DS-Lite AFTR
component on the NetScaler appliance. The IPv6 address must be one of the NetScaler owned
IPv6 address of type SNIP6.
• (Optional) Create an LSN Transport Profile for a specified protocol. An LSN transport profile
defines various timeouts and limits, such as maximum LSN sessions and maximum ports usage
that a subscriber can have for a given protocol. You bind an LSN transport profile for each pro-
tocol (TCP, UDP, and ICMP) to an LSN group. A profile can be bound to multiple LSN groups.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 370

NetScaler 12.0

A profile bound to an LSN group applies to all subscribers of an LSN client bound to the same
group. By default, one LSN transport profile with default settings for TCP, UDP, and ICMP pro-
tocols is bound to an LSN group during its creation. This profile is called the default transport
profile. An LSN transport profile that you bind to an LSN group overrides the default LSN trans-
port profile for that protocol.
• (Optional) Create an LSN Application Profile for a specified protocol and bind a set of desti-
nation ports to it. An LSN application profile defines the LSN mapping and LSN filtering controls
of a group for a given protocol and for a set of destination ports. For a set of destination ports,
you bind an LSN profile for each protocol (TCP, UDP, and ICMP) to an LSN group. A profile can be
bound to multiple LSN groups. An LSN application profile bound to an LSN group applies to all
subscribers of an LSN client bound to the same group. By default, one LSN application profile
with default settings for TCP, UDP, and ICMP protocols for all destination ports is bound to an
LSN group during its creation. This profile is called a default application profile. When you bind
an LSN application profile, with a specified set of destination ports, to an LSN group, the bound
profile overrides the default LSN application profile for that protocol at that set of destination
ports. The command line interface has two commands for creating an LSN application profile
and binding a set of destination ports to the LSN application profile. The configuration utility
combines these two operations on a single screen.
• Create an LSN Group and bind LSN pools, LSN IPv6 profile, (optional) LSN transport pro-
files, and (optional) LSN application profiles to the LSN group. An LSN group is an entity
consisting of an LSN client, an LSN IPv6 profile, LSN pool(s), LSN transport profile(s), and LSN
application profiles(s). A group is assigned parameters, such as port block size and logging of
LSN sessions. The parameter settings apply to all the subscribers of an LSN client bound to the
LSN group. Only one LSN IPv6 profile can be bound to an LSN group, and an LSN IPv6 profile
bound to an LSN group cannot be bound to other LSN groups. Only LSN Pools and LSN groups
with the same NAT type settings can be bound together. Multiples LSN pools can be bound to
an LSN group. Only one LSN client entity can be bound to an LSN group, and an LSN client en-
tity bound to an LSN group cannot be bound to other LSN groups. The command line interface
has two commands for creating an LSN group and binding LSN pools, LSN transport profiles,
and LSN application profiles to the LSN group. The configuration utility combines these two
operations in a single screen.

Configuration by Using the Command Line

To create an LSN client by using the command line interface:

At the command prompt, type:

1 add lsn client <clientname>

2
3 show lsn client

© 1999-2018 Citrix Systems, Inc. All rights reserved. 371

NetScaler 12.0

To bind an IPv6 network or an ACL6 rule to an LSN client by using the command line interface:

At the command prompt, type:

1 bind lsn client <clientname> (-network6 <ipv6_addr|*>| -acl6name <

string>)
2
3 show lsn client

To create an LSN pool by using the command line interface:

At the command prompt, type:

1 add lsn pool <poolname> [-nattype ( DYNAMIC )] [-portblockallocation (

ENABLED | DISABLED )] [-portrealloctimeout <secs>] [-
maxPortReallocTmq <positive_integer>]
2
3 show lsn pool

To bind an IP address range to an LSN pool by using the command line interface:

At the command prompt, type:

1 bind lsn pool <poolname> <lsnip>

2
3 show lsn pool

Note: For removing LSN IP addresses from an LSN pool, use the unbind lsn pool command.

To configure an LSN IPv6 profile by using the command line interface:

At the command prompt, type:

1 add lsn ip6profile <name> ‒ type DS-Lite ‒ network6 < ipv6_addr|*s >
2
3 show lsn ip6profile

To create an LSN transport profile by using the command line interface:

At the command prompt, type:

1 add lsn transportprofile <transportprofilename> <transportprotocol> [-

sessiontimeout <secs>] [-finrsttimeout <secs>] [-portquota <
positive_integer>] [-sessionquota <positive_integer>] [-
portpreserveparity ( ENABLED | DISABLED )] [-portpreserverange (
ENABLED | DISABLED )] [-syncheck ( ENABLED | DISABLED )]

© 1999-2018 Citrix Systems, Inc. All rights reserved. 372

NetScaler 12.0

2
3 show lsn transportprofile

To create an LSN application profile by using the command line interface:

At the command prompt, type:

1 add lsn appsprofile <appsprofilename> <transportprotocol> [-ippooling (

PAIRED | RANDOM )] [-mapping <mapping>] [-filtering <filtering>][-
tcpproxy ( ENABLED | DISABLED )] [-td <positive_integer>]
2
3 show lsn appsprofile

To bind an application protocol port range to an LSN application profile by using the command
line interface:

At the command prompt, type:

1 bind lsn appsprofile <appsprofilename> <lsnport>

2
3 show lsn appsprofile  

To create an LSN group by using the command line interface:

At the command prompt, type:

1 add lsn group <groupname> -clientname <string> [-nattype ( DYNAMIC )]

[-portblocksize <positive_integer>] [-logging (ENABLED | DISABLED )]
[-sessionLogging ( ENABLED | DISABLED )][-sessionSync ( ENABLED |
DISABLED )] [-snmptraplimit<positive_integer>] [-ftp ( ENABLED |
DISABLED )] [-pptp ( ENABLED |DISABLED )] [-sipalg ( ENABLED |
DISABLED )] [-rtspalg ( ENABLED |DISABLED )] [-ip6profile <string>]
2
3 show lsn group

To bind LSN protocol profiles and LSN pools to an LSN group by using the command line interface:

At the command prompt, type:

1 bind lsn group <groupname> (-poolname <string> | -transportprofilename

<string> | -httphdrlogprofilename <string> | -appsprofilename <
string> | -sipalgprofilename <string> | rtspalgprofilename <string>)
2
3 show lsn group

© 1999-2018 Citrix Systems, Inc. All rights reserved. 373

NetScaler 12.0

Configuration by Using the Configuration Utility

To configure an LSN client and bind an IPv6 network address or an ACL6 rule by using the con-
figuration utility:

Navigate to System > Large Scale NAT > Clients, and add a client and then bind an IPv6 network
address or an ACL6 rule to the client.

To configure an LSN pool and bind NAT IP addresses by using the configuration utility:

Navigate to System > Large Scale NAT > Pools, and add a pool and then bind an NAT IP address or a
range of NAT IP addresses to the pool.

To configure an LSN IPv6 profile by using the configuration utility:

Navigate to System > Large Scale NAT > Profiles, click the IPv6 tab, and assign an IPv6 address for
DS-Lite AFTR.

To configure an LSN transport profile by using the configuration utility:

1. Navigate to System > Large Scale NAT > Profiles.

2. On the details pane, click Transport, and then add a transport profile.

To configure an LSN application profile by using the configuration utility:

1. Navigate to System > Large Scale NAT > Profiles.

2. On the details pane, click Application, and then add an application profile.

To configure an LSN group and bind an LSN client, an LSN IPv6 profile, pools, transport profiles,
and application profiles by using the configuration utility:

Navigate to System > Large Scale NAT > Groups, and add a group and then bind an LSN client, an
LSN IPv6 profile, pools, transport profiles, and application profiles to the group.

1 > add lsn client LSN-DSLITE-CLIENT-1

2 Done
3 > bind lsn client LSN-DSLITE-CLIENT-1 -network6 2001:DB8::3:0/100
4 Done
5 > add lsn pool LSN-DSLITE-POOL-1
6 Done
7 > bind lsn pool LSN-DSLITE-POOL-1 203.0.113.61 - 203.0.113.70
8 Done
9 > add lsn ip6profile LSN-DSLITE-PROFILE-1 -type DS-Lite -network6 2001:
DB8::5:6
10 Done
11 > add lsn group LSN-DSLITE-GROUP-1 -clientname LSN-DSLITE-CLIENT-1 -
portblocksize 1024 -ip6profile LSN-DSLITE-PROFILE-1
12 Done
13 > add lsn group LSN-DSLITE-GROUP-1 -poolname LSN-DSLITE-POOL-1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 374

NetScaler 12.0

14 Done

Logging and Monitoring DS-Lite

You can log DS-Lite information to diagnose or troubleshoot problems, and to meet legal require-
ments. The NetScaler appliance supports all LSN logging features for logging DS-Lite information.
For configuring DS-Lite logging, use the procedures for configuring LSN logging, described at Logging
and Monitoring LSN.

A log message for a DS-Lite LSN mapping entry consists of the following information:

• NetScaler owned IP address (NSIP address or SNIP address) from which the log message is
sourced
• Time stamp
• Entry type (MAPPING)
• Whether the DS-Lite LSN mapping entry was created or deleted
• IPv6 address of B4
• Subscriber’s IP address, port, and traffic domain ID
• NAT IP address and port
• Protocol name
• Destination IP address, port, and traffic domain ID might be present, depending on the following
conditions:
– Destination IP address and port are not logged for Endpoint-Independent mapping.
– Only the destination IP address is logged for Address-Dependent mapping. The port is not
logged.
– Destination IP address and port are logged for Address-Port-Dependent mapping.

A log message for a DS-Lite session consists of the following information:

• NetScaler owned IP address (NSIP address or SNIP address) from which the log message is
sourced
• Time stamp
• Entry type (SESSION)
• Whether the DS-Lite session is created or removed
• IPv6 address of B4
• Subscriber’s IP address, port, and traffic domain ID
• NAT IP address and port
• Protocol name
• Destination IP address, port, and traffic domain ID

The following table shows sample DS-Lite log entries of each type stored on the configured log servers.
These log entries are generated by a NetScaler appliance whose NSIP address is 10.102.37.115.You can

© 1999-2018 Citrix Systems, Inc. All rights reserved. 375

NetScaler 12.0

log DS-Lite information to diagnose or troubleshoot problems, and to meet legal requirements. The
NetScaler appliance supports all LSN logging features for logging DS-Lite information. For configuring
DS-Lite logging, use the procedures for configuring LSN logging, described at Logging and Monitoring
LSN.

A log message for a DS-Lite LSN mapping entry consists of the following information:

• NetScaler owned IP address (NSIP address or SNIP address) from which the log message is
sourced
• Time stamp
• Entry type (MAPPING)
• Whether the DS-Lite LSN mapping entry was created or deleted
• IPv6 address of B4
• Subscriber’s IP address, port, and traffic domain ID
• NAT IP address and port
• Protocol name
• Destination IP address, port, and traffic domain ID might be present, depending on the following
conditions:
– Destination IP address and port are not logged for Endpoint-Independent mapping.
– Only the destination IP address is logged for Address-Dependent mapping. The port is not
logged.
– Destination IP address and port are logged for Address-Port-Dependent mapping.

A log message for a DS-Lite session consists of the following information:

• NetScaler owned IP address (NSIP address or SNIP address) from which the log message is
sourced
• Time stamp
• Entry type (SESSION)
• Whether the DS-Lite session is created or removed
• IPv6 address of B4
• Subscriber’s IP address, port, and traffic domain ID
• NAT IP address and port
• Protocol name
• Destination IP address, port, and traffic domain ID

The following table shows sample DS-Lite log entries of each type stored on the configured log servers.
These log entries are generated by a NetScaler appliance whose NSIP address is 10.102.37.115.

LSN Log Entry Type Sample Log Entry

© 1999-2018 Citrix Systems, Inc. All rights reserved. 376

NetScaler 12.0

DS-Lite session creation Local4.Informational 10.102.37.115

08/14/2015:13:35:38 GMT 0-PPE-1 : default LSN
LSN_SESSION 37647607 0 : SESSION
CREATED 2001:DB8::3:4 Client IP:Port:TD
192.0.2.51:2552:0, NatIP:NatPort
203.0.113.61:3002, Destination IP:Port:TD
198.51.100.250:80:0, Protocol:TCP
DS-Lite session deletion Local4.Informational 10.102.37.115 08/14/2015:13:38:22
GMT 0-PPE-1 : default LSN LSN_SESSION
37647617 0 : SESSION DELETED 2001:DB8::3:4
Client IP:Port:TD 192.0.2.51:2552:0,
NatIP:NatPort 203.0.113.61:3002, Destination
IP:Port:TD 198.51.100.250:80:0, Protocol: TCP
DS-Lite LSN mapping creation Local4.Informational 10.102.37.115 08/14/2015:13:35:39
GMT 0-PPE-1 : default LSN LSN_EIM_MAPPING
37647610 0 : EIM CREATED 2001:DB8::3:4 Client
IP:Port:TD 192.0.2.51:2552:0, NatIP:NatPort
198.51.100.250:80, Protocol: TCP
DS-Lite LSN mapping deletion Local4.Informational 10.102.37.115 08/14/2015:13:38:25
GMT 0-PPE-1 : default LSN LSN_EIM_MAPPING
37647618 0 : EIM DELETED 2001:DB8::3:4 Client
IP:Port:TD 192.0.2.51:2552:0, NatIP:NatPort
198.51.100.250:80, Protocol: TCP

Displaying Current DS-Lite Sessions

You can display the current DS-Lite sessions for detecting any unwanted or inefficient sessions on the
NetScaler appliance. You can display all or some DS-Lite sessions, on the basis of selection parame-
ters.

Configuration by Using the Command Line Interface

To display all DS-Lite sessions by using the command line interface:

At the command prompt, type:

1 show lsn session  ‒ nattype DS-Lite

© 1999-2018 Citrix Systems, Inc. All rights reserved. 377

NetScaler 12.0

To display selected DS-Lite sessions by using the command line interface:

At the command prompt, type:

1 show lsn session  ‒ nattype DS-Lite [-clientname <string>] [-network <

ip_addr> [-netmask <netmask>] [-td <positive_integer>]] [-natIP <
ip_addr> [-natPort <port>]]

Example:

The following sample ouput displays all DS-Lite sessions existing on a NetScaler appliance:

1 show lsn session ‒ nattype DS-Lite

2   B4-Address SubscrIP SubscrPort SubscrTD DstIP DstPort DstTD NatIP
NatPort Proto Dir
3
4 1. 2001:DB8::3:4 192.0.2.51 2552 0 198.51.100.250 80 0 203.0.113.61
3002 TCP OUT
5
6 2. 2001:DB8::3:4 192.0.2.51 3551 0 198.51.100.300 80 0 203.0.113.61
52862 TCP OUT
7
8 3. 2001:DB8::3:4 192.0.2.100 4556 0 198.51.100.250 0 0 203.0.113.61
48116 ICMP OUT
9
10 4. 2001: DB8::190 192.0.2.150 3881 0 198.51.100.199 80 0 203.0.113.69
48305 TCP OUT
11
12 Done

Configuration Using the Configuration Utility

To display all or selected DS-Lite sessions by using the configuration utility

1. Navigate to System > Large Scale NAT > Sessions, and click the DS-Lite tab.
2. For displaying DS-Lite sessions on the basis of selection parameters, click Search.

Clearing DS-Lite Sessions

You can remove any unwanted or inefficient DS-Lite sessions from the NetScaler appliance. The ap-
pliance immediately releases the resources (such as NAT IP address, port, and memory) allocated for
these sessions, making the resources available for new sessions. The appliance also drops all the sub-
sequent packets related to these removed sessions. You can remove all or selected DS-Lite sessions
from the NetScaler appliance.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 378

NetScaler 12.0

To clear all DS-Lite sessions by using the command line interface:

At the command prompt, type:

flush lsn session –nattype DS-Lite

show lsn session –nattype DS-Lite

To clear selected DS-Lite sessions by using the command line interface:

At the command prompt, type:

1 flush lsn session  ‒ nattype DS-Lite [-clientname <string>] [-network <

ip_addr> [-netmask <netmask>] [-td <positive_integer>]] [-natIP <
ip_addr> [-natPort <port>]]
2
3 show lsn session  ‒ nattype DS-Lite

To clear all or selected DS-Lite sessions by using the configuration utility:

1. Navigate to System > Large Scale NAT > Sessions, and click the DS-Lite tab.
2. Click Flush Sessions.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Configuring DS-Lite Static Maps

September 17, 2018

Contributed by:
C

The NetScaler appliance supports manual creation of DS-Lite LSN mappings, which contain the map-
ping between the following information:

• Subscriber’s IP address and port, and IPv6 address of B4 device or component

• NAT IP address and port

Static DS-Lite LSN mappings are useful in cases where you want to ensure that the connections initi-
ated to a NAT IP address and port map to the subscriber IP address and port through the specified B4
device (for example, web servers located in the internal network).

Note: This feature is supported in release 11.0 build 64.x and later.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 379

NetScaler 12.0

To create a DS-Lite static LSN mapping by using the command line

At the command prompt, type:

1 add lsn static <name> <transportprotocol> <subscrIP> <subscrPort> [-td 

<positive_integer>] [-network6 <B4_ADDR>] [<natIP> [<natPort>]] [-
destIP<ip_addr> [-dsttd <positive_integer>]]
2
3 show lsn static

Parameter Descriptions

add lsn static

• name

Name for the LSN static mapping entry. Must begin with an ASCII alphanumeric or underscore (_)
character, and must contain only ASCII alphanumeric, underscore, hash (#), period (.), space, colon
(:), at (@), equals (=), and hyphen (-) characters. Cannot be changed after the LSN group is created.
The following requirement applies only to the CLI: If the name includes one or more spaces, enclose
the name in double or single quotation marks (for example, “ds-lite lsn static1” or ‘ds-lite lsn static1’).
This is a mandatory argument. Maximum Length: 127

• transportprotocol

Protocol for the DS-Lite LSN mapping entry.

• subscrIP

IPv4 address of a subscriber for the DS-Lite LSN mapping entry.

• subscrPort

Port of the subscriber for the DS-Lite LSN mapping entry.

• Network6

IPv6 address of the B4 device or component.

• td

ID of the traffic domain to which the B4 device belongs. The IPv6 address of the B4 device is specified
in the network6 paramter. If you do not specify an ID, the B4 device is assumed to be a part of the
default traffic domain.

• natIP

IPv4 address, already existing on the NetScaler appliance as type LSN, to be used as NAT IP address
for this mapping entry.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 380

NetScaler 12.0

• natPort

NAT port for this DS-Lite LSN mapping entry.

• destIP

Destination IP address for the DS-Lite LSN mapping entry.

• dsttd

ID of the traffic domain through which the destination IP address for this DS-Lite LSN mapping entry
is reachable from the NetScaler appliance. If you do not specify an ID, the destination IP address is
assumed to be reachable through the default traffic domain, which has an ID of 0.

To create a DS-Lite static LSN mapping by using the configuration utility

Navigate to System > Large Scale NAT > Static, and add a new DS-Lite static LSN mapping.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Configuring Deterministic NAT Allocation for DS-Lite

September 17, 2018

Contributed by:
C

Deterministic NAT allocation for DS-Lite LSN deployments is a type of NAT resource allocation in which
the NetScaler appliance pre-allocates, from the LSN NAT IP pool and on the basis of the specified
port block size, an LSN NAT IP address and a block of ports to each subscriber (subscriber behind B4
device).

Note: This feature is supported in release 11.0 build 64.x and later.

The appliance sequentially allocates NAT resources to these subscribers. It assigns the first block of
ports on the beginning NAT IP address to the beginning subscriber IP address. The next range of ports
is assigned to the next subscriber, and so on, until the NAT address does not have enough ports for the
next subscriber. At that point, the first port block on the next NAT address is assigned to the subscriber,
and so on.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 381

NetScaler 12.0

The NetScaler appliance logs the allocated NAT IP address and the port block for a subscriber. For a
connection, a subscriber can be identified by just its mapped NAT IP address and port block. For this
reason, the NetScaler appliance does not log the creation or deletion of an LSN session.

A DS-Lite subscriber can have only one deterministic port block. If the entire block of ports is being
used, the NetScaler appliance drops any new connection from the subscriber.

Example: Deterministic DS-Lite

In this example, a deterministic DS-Lite configuration includes four subscribers with IP addresses
192.0.17.5, 192.0.17.6, 192.0.17.7, and 192.0.17.8. These ipv4 subscribers are behind a B4 device hav-
ing the IPv6 address 2001:DB8::3:4. In this configuration, the port block size is set to 20480 and LSN
NAT IP address pool has IP addresses in the range 203.0.113.41-203.0.113.42.

The NetScaler appliance sequentially pre-allocates, from the LSN NAT IP pool and on the basis of the
set port block size, an LSN NAT IP address and a block of ports to each subscriber. It assigns the first
block of ports (1024-21503) on the beginning NAT IP address (203.0.113.41) to the beginning subscriber
IP address (192.0.17.5). The next range of ports is assigned to the next subscriber, and so on, until the
NAT address does not have enough ports for the next subscriber. At that point, the first port block on
the next NAT IP address is assigned to the subscriber, and so on. The NetScaler logs the NAT IP address
and the block of ports allocated for each subscriber.

The NetScaler appliance does not log any LSN session created or deleted for these subscribers.

The following table lists the NAT IP address and blocks of ports allocated to each subscriber in this
example:

Subscriber IP address Allocated NAT IP Allocated Block of IPv6 address of B4

address Ports
192.0.17.5 203.0.113.41 1024 - 21503 2001:DB8::3:4
192.0.17.6 203.0.113.41 21504 - 41983 2001:DB8::3:4
192.0.17.7 203.0.113.41 41984 - 62463 2001:DB8::3:4
192.0.17.8 203.0.113.42 1024 - 21503 2001:DB8::3:4

Configuration Steps

You need to configure deterministic NAT as part of the DS-Lite configuration. For instructions on con-
figuring DS-Lite, see Configuring DS-Lite.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 382

NetScaler 12.0

While configuring DS-Lite, make sure that you:

• Set the NAT Type parameter to Deterministic when adding the LSN pool and the LSN group.
• Set the desired port block size parameter when adding the LSN group, unless you can accept
the default value.

Points to Consider before Configuring Deterministic DS-Lite

Consider the following points before configuring deterministic DS-Lite:

• The complete IP address of each subscriber must be specified in a separate add lsn client com-
mand, by setting the Network and Netmask parameters. (Set Netmask to 255.255.255.255.) Also
the IPv4 address of the B4 device specified in Network6 parameter must be complete (/128 pre-
fix). In other words, Network and Network6 parameter do not accept addresses other than /32
bit mask and /128 prefix, respectively.
• The NetScaler appliance drops connections from subscribers that are not specified in any de-
terministic DS-Lite configuration but are behind B4 devices specified in a deterministic DS-lite
configuration.
• The NetScaler appliance recognizes subscribers having the same IPv4 address as different sub-
scribers if they are behind different B4 devices. A combination of subscriber IPv4 address and
B4 device defines a unique subscriber in the LSN client entity of a DS-Lite configuration.
Sample Deterministic DS-Lite Configuration:
The following configuration uses the settings listed in section Example: Deterministic DS-Lite.

1 add lsn client LSN-DSLITE-CLIENT-10
2
3 Done
4 bind lsn client LSN-DSLITE-CLIENT-10 -network 192.0.17.5 -netmask
255.255.255.255 -network6 2001:DB8::3:4/128
5
6 Done
7 bind lsn client LSN-DSLITE-CLIENT-10 -network 192.0.17.6 -netmask 255
.255.255.255 -network6 2001:DB8::3:4/128
8
9 Done
10 bind lsn client LSN-DSLITE-CLIENT-10 -network 192.0.17.7 -netmask 255
.255.255.255 -network6 2001:DB8::3:4/128
11
12 Done
13 bind lsn client LSN-DSLITE-CLIENT-10 -network 192.0.17.8 -netmask 255
.255.255.255 -network6 2001:DB8::3:4/128
14
15 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 383

NetScaler 12.0

16 add lsn pool LSN-DSLITE-POOL-10 -nattype DETERMINISTIC
17
18 Done
19 bind lsn pool LSN-DSLITE-POOL-10  203.0.113.41-203.0.113.42
20
21 Done
22 add lsn ip6profile LSN-DSLITE-PROFILE-10 -type DS-Lite -network6 2001:
DB8::5:6
23
24 Done
25 add lsn group LSN-DSLITE-GROUP-10 -clientname LSN-DSLITE-CLIENT-10 -
nattype DETERMINISTIC -portblocksize 20480 -ip6profile LSN-DSLITE-
PROFILE-10
26
27 Done
28 bind lsn group LSN-DSLITE-GROUP-10 -poolname LSN-DSLITE-POOL-10
29
30 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Configuring Application Layer Gateways for DS-Lite

September 17, 2018

Contributed by:
C

For some application layer protocols, the IP addresses and protocol port numbers are also commu-
nicated in the packet’s payload. Application Layer Gateway (AGL) for a protocol parses the packet
payload and does necessary changes to ensure that the protocol continues to work over DS-Lite.

The NetScaler appliance supports ALG for the following protocols for DS-Lite:

• FTP
• ICMP
• TFTP
• SIP
• RTSP

© 1999-2018 Citrix Systems, Inc. All rights reserved. 384

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Application Layer Gateway for FTP, ICMP, and TFTP Protocols

September 17, 2018

Contributed by:
C

You can enable or disable ALG for the FTP protocol for a DS-Lite configuration by enabling or disabling
the FTP ALG option of the LSN group of the configuration.

ALG for the ICMP protocol is enabled by default, and there is no provision to disable it.

ALG for the TFTP protocol is disabled by default. TFTP ALG is enabled automatically for a DS-Lite
configuration when you bind a UDP LSN application profile, with endpoint-independent-mapping,
endpoint-independent filtering, and destination port as 69 (well-known port for TFTP), to the LSN
group.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Application Layer Gateway for SIP Protocol

September 17, 2018

Contributed by:
C

Using DS-Lite with Session Initiation Protocol (SIP) is complicated, because SIP messages contain IP
addresses in the SIP headers as well as in the SIP body. When LSN is used with SIP, the SIP headers
contain information about the caller and the receiver, and the device translates this information to
hide it from the outside network. The SIP body contains the Session Description Protocol (SDP) in-
formation, which includes IP addresses and port numbers for transmission of the media. SIP ALG for
DS-Lite is compliant with RFC 3261, RFC 3581, RFC 4566, and RFC 4475.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 385

NetScaler 12.0

Limitations of SIP ALG

SIP ALG for DS-Lite has the following limitations:

• Only SDP payload is supported.

• The following are not supported:
– Multicast IP addresses
– Encrypted SDP
– SIP TLS
– FQDN translation
– SIP layer authentication
– Admin partitions
– NetScaler clusters
– Multipart body
– Line folding

Configuring SIP ALG

You need to configure the SIP ALG as part of the LSN configuration. For instructions on configuring
LSN, see Configuring DS-Lite. While configuring LSN, make sure that you:

• Set the following parameters while adding an LSN application profile:

o IP Pooling = PAIRED

o Address and Port Mapping = ENDPOINT-INDEPENDENT

o Filtering = ENDPOINT-INDEPENDENT

• Create a SIP ALG profile and make sure that you define either the source port range or destina-
tion port range. Bind the SIP ALG profile to the LSN group
• Enable SIP ALG in the LSN group

To enable SIP ALG for an LSN configuration by using the CLI

At the command prompt, type:

1 add lsn group <groupname> -clientname <string>[-sipalg ( ENABLED |

DISABLED )]
2
3 show lsn group<groupname>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 386

NetScaler 12.0

To enable SIP ALG for an LSN configuration by using the CLI

At the command prompt, type:

1 add lsn sipalgprofile<sipalgprofilename>[-dataSessionIdleTimeout<

positive_integer>][-sipSessionTimeout<positive_integer>][-
registrationTimeout<positive_integer>][-sipsrcportrange<port[-port
]>][-sipdstportrange<port[-port]>][-openRegisterPinhole ( ENABLED |
DISABLED )][-openContactPinhole ( ENABLED | DISABLED )][-
openViaPinhole ( ENABLED | DISABLED )][-openRecordRoutePinhole (
ENABLED | DISABLED )]-sipTransportProtocol ( TCP | UDP )[-
openRoutePinhole ( ENABLED | DISABLED )][-rport ( ENABLED | DISABLED
)]
2
3 show lsn sipalgprofile<sipalgprofilename>

Sample Configuration

The following sample DS-Lite configuration, SIP ALG is enabled for TCP traffic from B4 devices in the
network 2001:DB8::3:0/96.

1 add lsn client LSN-DSLITE-CLIENT-1

2 Done
3 bind lsn client LSN-DSLITE-CLIENT-1 -network6 2001:DB8::3:0/96
4 Done
5 add lsn pool LSN-DSLITE-POOL-1
6 Done
7 bind lsn pool LSN-DSLITE-POOL-1 203.0.113.61 - 203.0.113.70
8 Done
9 add lsn ip6profile LSN-DSLITE-PROFILE-1 -type DS-Lite -network6 2001:
DB8::5:6
10 Done
11 add lsn appsprofile LSN-DSLITE-APPS-PROFILE-1 TCP -ippooling PAIRED ‒
mapping ENDPOINT-INDEPENDENT -filtering ENDPOINT-INDEPENDENT
12 Done
13 add lsn sipalgprofile SIPALGPROFILE-1  -sipdstportrange 5060 -
sipTransportProtocol TCP
14 Done
15 add lsn group LSN-DSLITE-GROUP-1 -clientname LSN-DSLITE-CLIENT-1 -
portblocksize 1024 -ip6profile LSN-DSLITE-PROFILE-1 -sipalg ENABLED
16 Done
17 bind lsn group LSN-DSLITE-GROUP-1 -poolname LSN-DSLITE-POOL-1
18 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 387

NetScaler 12.0

19 bind lsn group LSN-DSLITE-GROUP-1 -appsprofilename LSN-DSLITE-APPS-

PROFILE-1
20 Done
21 bind lsn group LSN-DSLITE-GROUP-1 -sipalgprofilename SIPALGPROFILE-1
22 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Application Layer Gateway for RTSP Protocol

September 17, 2018

Contributed by:
C

Real Time Streaming Protocol (RTSP) is an application-level protocol for the transfer of real-time me-
dia data. Used for establishing and controlling media sessions between end points, RTSP is a control
channel protocol between the media client and the media server. The typical communication is be-
tween a client and a streaming media server.

Streaming media from a private network to a public network requires translating IP addresses and
port numbers over the network. NetScaler functionality includes an Application Layer Gateway (ALG)
for RTSP, which can be used with Large Scale NAT (LSN) to parse the media stream and make any
necessary changes to ensure that the protocol continues to work over the network.

How IP address translation is performed depends on the type and direction of the message, and the
type of media supported by the client-server deployment. Messages are translated as follows:

• Outbound request—Private IP address to NetScaler owned public IP address called LSN IP ad-
dress.
• Inbound response—LSN IP address to private IP address.
• Inbound request—No translation.
• Outbound response—Private IP address to LSN pool IP address.

Limitations of RTSP ALG

The RTSP ALG does not support the following:

• Multicast RTSP sessions

© 1999-2018 Citrix Systems, Inc. All rights reserved. 388

NetScaler 12.0

• RTSP session over UDP

• Admin partitions
• NetScaler clusters
• RTSP Authentication
• HTTP tunneling

Configuring RTSP ALG

Configure RTSP ALG as part of the LSN configuration. For instructions on configuring LSN, see Config-
uring DS-Lite. While configuring LSN, make sure that you:
• Set the following parameters while adding an LSN application profile:
– IP Pooling = PAIRED
– Address and Port Mapping = ENDPOINT-INDEPENDENT
– Filtering = ENDPOINT-INDEPENDENT
• Enable RTSP ALG in the LSN group
• Create a RTSP ALG profile and bind the RTSP ALG profile to the LSN group

To enable RTSP ALG for an LSN configuration by using the CLI

At the command prompt, type:

1 add lsn group <groupname> -clientname <string> [-rtspalg ( ENABLED |

DISABLED )]
2
3 show lsn group <groupname>

To enable RTSP ALG for an LSN configuration by using the CLI

At the command prompt, type:

1 add lsn rtspalgprofile <rtspalgprofilename> [-rtspIdleTimeout <

positive_integer>] -rtspportrange <port[-port]> [-
rtspTransportProtocol (TCP|UDP)]
2
3 show lsn rtspalgprofile <rtspalgprofilename>

Sample RTSP ALG Configuration

The following sample DS-Lite configuration, RTSP ALG is enabled for TCP traffic from B4 devices in the
network 2001:DB8::4:0/96.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 389

NetScaler 12.0

Sample RTSP ALG Configuration:

1 add lsn client LSN-DSLITE-CLIENT-5

2 Done
3 bind lsn client LSN-DSLITE-CLIENT-5 -network6 2001:DB8::4:0/96
4 Done
5 add lsn pool LSN-DSLITE-POOL-5
6 Done
7 bind lsn pool LSN-DSLITE-POOL-5 203.0.113.61 - 203.0.113.70
8 Done
9 add lsn ip6profile LSN-DSLITE-PROFILE-5 -type DS-Lite -network6 2001:
DB8::5:6
10 Done
11 add lsn appsprofile LSN-DSLITE-APPS-PROFILE-5 TCP -ippooling PAIRED ‒
mapping ENDPOINT-INDEPENDENT -filtering ENDPOINT-INDEPENDENT
12 Done
13 add lsn rtspalgprofile RTSPALGPROFILE-5 -rtspIdleTimeout 1000 -
rtspportrange 554
14 Done
15 add lsn group LSN-DSLITE-GROUP-5 -clientname LSN-DSLITE-CLIENT-5 -
portblocksize 1024 -ip6profile LSN-DSLITE-PROFILE-5 -rtspalg ENABLED
16 Done
17 bind lsn group LSN-DSLITE-GROUP-5 -poolname LSN-DSLITE-POOL-5
18 Done
19 bind lsn group LSN-DSLITE-GROUP-5 -appsprofilename LSN-DSLITE-APPS-
PROFILE-5
20 Done
21 bind lsn group LSN-DSLITE-GROUP-5 -rtspalgprofilename RTSPALGPROFILE-5
22 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Logging and Monitoring DS-Lite

September 17, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 390

NetScaler 12.0

You can log DS-Lite information to diagnose or troubleshoot problems, and to meet legal require-
ments. The NetScaler appliance supports all LSN logging features for logging DS-Lite information.
For configuring DS-Lite logging, use the procedures for configuring LSN logging, described at Logging
and Monitoring LSN.
A log message for a DS-Lite LSN mapping entry consists of the following information:
• NetScaler owned IP address (NSIP address or SNIP address) from which the log message is
sourced
• Time stamp
• Entry type (MAPPING)
• Whether the DS-Lite LSN mapping entry was created or deleted
• IPv6 address of B4
• Subscriber’s IP address, port, and traffic domain ID
• NAT IP address and port
• Protocol name
• Destination IP address, port, and traffic domain ID might be present, depending on the following
conditions:
– Destination IP address and port are not logged for Endpoint-Independent mapping.
– Only the destination IP address is logged for Address-Dependent mapping. The port is not
logged.
– Destination IP address and port are logged for Address-Port-Dependent mapping.
A log message for a DS-Lite session consists of the following information:
• NetScaler owned IP address (NSIP address or SNIP address) from which the log message is
sourced
• Time stamp
• Entry type (SESSION)
• Whether the DS-Lite session is created or removed
• IPv6 address of B4
• Subscriber’s IP address, port, and traffic domain ID
• NAT IP address and port
• Protocol name
• Destination IP address, port, and traffic domain ID
The following table shows sample DS-Lite log entries of each type stored on the configured log servers.
These log entries are generated by a NetScaler appliance whose NSIP address is 10.102.37.115.You can
log DS-Lite information to diagnose or troubleshoot problems, and to meet legal requirements. The
NetScaler appliance supports all LSN logging features for logging DS-Lite information. For configuring
DS-Lite logging, use the procedures for configuring LSN logging, described at Logging and Monitoring
LSN.
A log message for a DS-Lite LSN mapping entry consists of the following information:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 391

NetScaler 12.0

• NetScaler owned IP address (NSIP address or SNIP address) from which the log message is
sourced
• Time stamp
• Entry type (MAPPING)
• Whether the DS-Lite LSN mapping entry was created or deleted
• IPv6 address of B4
• Subscriber’s IP address, port, and traffic domain ID
• NAT IP address and port
• Protocol name
• Destination IP address, port, and traffic domain ID might be present, depending on the following
conditions:
– Destination IP address and port are not logged for Endpoint-Independent mapping.
– Only the destination IP address is logged for Address-Dependent mapping. The port is not
logged.
– Destination IP address and port are logged for Address-Port-Dependent mapping.

A log message for a DS-Lite session consists of the following information:

• NetScaler owned IP address (NSIP address or SNIP address) from which the log message is
sourced
• Time stamp
• Entry type (SESSION)
• Whether the DS-Lite session is created or removed
• IPv6 address of B4
• Subscriber’s IP address, port, and traffic domain ID
• NAT IP address and port
• Protocol name
• Destination IP address, port, and traffic domain ID

The following table shows sample DS-Lite log entries of each type stored on the configured log servers.
These log entries are generated by a NetScaler appliance whose NSIP address is 10.102.37.115.

LSN Log Entry Type Sample Log Entry

DS-Lite session creation Local4.Informational 10.102.37.115
08/14/2015:13:35:38 GMT 0-PPE-1 : default LSN
LSN_SESSION 37647607 0 : SESSION
CREATED 2001:DB8::3:4 Client IP:Port:TD
192.0.2.51:2552:0, NatIP:NatPort
203.0.113.61:3002, Destination IP:Port:TD
198.51.100.250:80:0, Protocol:TCP

© 1999-2018 Citrix Systems, Inc. All rights reserved. 392

NetScaler 12.0

DS-Lite session deletion Local4.Informational 10.102.37.115 08/14/2015:13:38:22

GMT 0-PPE-1 : default LSN LSN_SESSION
37647617 0 : SESSION DELETED 2001:DB8::3:4
Client IP:Port:TD 192.0.2.51:2552:0,
NatIP:NatPort 203.0.113.61:3002, Destination
IP:Port:TD 198.51.100.250:80:0, Protocol: TCP
DS-Lite LSN mapping creation Local4.Informational 10.102.37.115 08/14/2015:13:35:39
GMT 0-PPE-1 : default LSN LSN_EIM_MAPPING
37647610 0 : EIM CREATED 2001:DB8::3:4 Client
IP:Port:TD 192.0.2.51:2552:0, NatIP:NatPort
198.51.100.250:80, Protocol: TCP
DS-Lite LSN mapping deletion Local4.Informational 10.102.37.115 08/14/2015:13:38:25
GMT 0-PPE-1 : default LSN LSN_EIM_MAPPING
37647618 0 : EIM DELETED 2001:DB8::3:4 Client
IP:Port:TD 192.0.2.51:2552:0, NatIP:NatPort
198.51.100.250:80, Protocol: TCP

Displaying Current DS-Lite Sessions

You can display the current DS-Lite sessions for detecting any unwanted or inefficient sessions on the
NetScaler appliance. You can display all or some DS-Lite sessions, on the basis of selection parame-
ters.

To display all DS-Lite sessions by using the command line interface

At the command prompt, type:

1 show lsn session  ‒ nattype DS-Lite

To display selected DS-Lite sessions by using the command line interface

At the command prompt, type:

1 show lsn session  ‒ nattype DS-Lite [-clientname <string>] [-network <

ip_addr> [-netmask <netmask>] [-td <positive_integer>]] [-natIP <
ip_addr> [-natPort <port>]]

© 1999-2018 Citrix Systems, Inc. All rights reserved. 393

NetScaler 12.0

The following sample ouput displays all DS-Lite sessions existing on a NetScaler appliance:

show lsn session –nattype DS-Lite

1   B4-Address SubscrIP SubscrPort SubscrTD DstIP DstPort DstTD NatIP

NatPort Proto Dir
2
3 1. 2001:DB8::3:4 192.0.2.51 2552 0 198.51.100.250 80 0 203.0.113.61
3002 TCP OUT
4
5 2. 2001:DB8::3:4 192.0.2.51 3551 0 198.51.100.300 80 0 203.0.113.61
52862 TCP OUT
6
7 3. 2001:DB8::3:4 192.0.2.100 4556 0 198.51.100.250 0 0 203.0.113.61
48116 ICMP OUT
8
9 4. 2001: DB8::190 192.0.2.150 3881 0 198.51.100.199 80 0 203.0.113.69
48305 TCP OUT
10 Done

Configuration Using the Configuration Utility

To display all or selected DS-Lite sessions by using the configuration utility

1. Navigate to System > Large Scale NAT > Sessions, and click the DS-Lite tab.
2. For displaying DS-Lite sessions on the basis of selection parameters, click Search.

Clearing DS-Lite Sessions

You can remove any unwanted or inefficient DS-Lite sessions from the NetScaler appliance. The ap-
pliance immediately releases the resources (such as NAT IP address, port, and memory) allocated for
these sessions, making the resources available for new sessions. The appliance also drops all the sub-
sequent packets related to these removed sessions. You can remove all or selected DS-Lite sessions
from the NetScaler appliance.

To clear all DS-Lite sessions by using the command line interface

At the command prompt, type:

1 flush lsn session  ‒ nattype DS-Lite

2
3 show lsn session  ‒ nattype DS-Lite

© 1999-2018 Citrix Systems, Inc. All rights reserved. 394

NetScaler 12.0

To clear selected DS-Lite sessions by using the command line interface

At the command prompt, type:

1 flush lsn session  ‒ nattype DS-Lite [-clientname <string>] [-network <

ip_addr> [-netmask <netmask>] [-td <positive_integer>]] [-natIP <
ip_addr> [-natPort <port>]]
2
3 show lsn session  ‒ nattype DS-Lite

To clear all or selected DS-Lite sessions by using the configuration utility

1. Navigate to System > Large Scale NAT > Sessions, and click the DS-Lite tab.
2. Click Flush Sessions.

Logging HTTP Header Information

The NetScaler appliance can log request header information of an HTTP connection that is using the
DS-Lite functionality. The following header information of an HTTP request packet can be logged:

• URL that the HTTP request is destined to

• HTTP Method specified in the HTTP request
• HTTP version used in the HTTP request
• IPv4 address of the subscriber that sent the HTTP request

The HTTP header logs can be used by ISPs to see the trends related to the HTTP protocol among a set
of subscribers. For example, an ISP can use this feature to find out the most popular website among
a set of subscribers.

Configuration Steps

Perform the following tasks for configuring the NetScaler appliance to log HTTP header information:

• Create an HTTP header log profile. An HTTP header log profile is a collection of HTTP header
attributes (for example, URL and HTTP method) that can be enabled or disabled for logging.
• Bind the HTTP header to an LSN group of a DS-Lite LSN configuration. Bind the HTTP header
log profile to an LSN group of an LSN configuration by setting the HTTP header log profile name
parameter to the name of the created HTTP header log profile. The NetScaler appliance then
logs HTTP header information of any HTTP requests related to the LSN group. An HTTP header
log profile can be bound to multiple LSN groups, but an LSN group can have only one HTTP
header log profile.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 395

NetScaler 12.0

To create an HTTP header log profile by using the command line interface

At the command prompt, type:

1 add lsn httphdrlogprofile <httphdrlogprofilename> [-logURL ( ENABLED |

DISABLED )] [-logMethod ( ENABLED | DISABLED )] [-logVersion (
ENABLED | DISABLED )] [-logHost ( ENABLED | DISABLED )]
2
3 show lsn httphdrlogprofile

To bind an HTTP header log profile to an LSN group by using the command line interface

At the command prompt, type:

1 bind lsn group <groupname> -httphdrlogprofilename <string>

2
3 show lsn group <groupname>

Sample Configuration

In the following DS-Lite LSN configuration, HTTP header log profile HTTP-Header-LOG-1 is bound to
LSN group LSN-DSLITE-GROUP-1. The log profile has all the HTTP attributes (URL, HTTP method, HTTP
version, and HOST IP address) enabled for logging, so that all these attributes are logged for any HTTP
requests from B4 devices (in the network 2001:DB8:5001::/96).

Sample Configuration:

1 add lsn httphdrlogprofile HTTP-HEADER-LOG-1

2
3 Done
4
5 add lsn client LSN-DSLITE-CLIENT-1
6
7 Done
8
9 bind lsn client LSN-DSLITE-CLIENT-1 -network6 2001:DB8::3:0/100
10
11 Done
12
13 add lsn pool LSN-DSLITE-POOL-1
14
15 Done
16
17 bind lsn pool LSN-DSLITE-POOL-1 203.0.113.61 - 203.0.113.70

© 1999-2018 Citrix Systems, Inc. All rights reserved. 396

NetScaler 12.0

18
19 Done
20
21 add lsn ip6profile LSN-DSLITE-PROFILE-1 -type DS-Lite -network6 2001:
DB8::5:6
22
23 Done
24
25 add lsn group LSN-DSLITE-GROUP-1 -clientname LSN-DSLITE-CLIENT-1 -
portblocksize 1024 -ip6profile LSN-DSLITE-PROFILE-1
26
27 Done
28
29 bind lsn group LSN-DSLITE-GROUP-1 -poolname LSN-DSLITE-POOL-1
30
31 Done
32
33 bind lsn group LSN-DSLITE-GROUP-1 -httphdrlogprofilename HTTP-HEADER-
LOG-1
34
35 Done

IPFIX Logging

The NetScaler appliance supports sending information about LSN events in Internet Protocol Flow
Information Export (IPFIX) format to the configured set of IPFIX collector(s). The appliance uses the
existing AppFlow feature to send LSN events in IPFIX format to the IPFIX collectors.

IPFIX based logging is available for the following DS_Lite related events:

• Creation or deletion of an LSN session.

• Creation or deletion of an LSN mapping entry.
• Allocation or de-allocation of port blocks in the context of deterministic NAT.
• Allocation or de-allocation of port blocks in the context of dynamic NAT.
• Whenever subscriber session quota is exceeded.

Points to Consider before you Configure IPFIX logging

Before you start configuring IPSec ALG, consider the following points:

• You must configure the AppFlow feature and IPFIX collector(s) on the NetScaler appliance. For
instructions, see Configuring the AppFlow feature.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 397

NetScaler 12.0

Configuration Steps

Perform the following tasks for logging LSN information in IPFIX format:

• Enable LSN logging in the AppFlow configuration. Enable the LSN logging parameter as part
of AppFlow configuration.
• Create an LSN log profile. An LSN log profile includes the IPFIX parameter that enables or dis-
ables the log information in IPFIX format.
• Bind the LSN log profile to an LSN group of an LSN configuration. Bind the LSN log profile
to one or multiple LSN group(s). Events related to the bound LSN group will be logged in IPFIX
format.

To enable LSN logging in the AppFlow configuration by using the CLI

At the command prompt, type:

1 set appflow param -lsnLogging (ENABLED |DISABLED )

2
3 show appflow param

To create an LSN log profile by using the CLIAt the command prompt, type

At the command prompt, type:

1 set lsn logprofile <logProfileName>  -logipfix ( ENABLED | DISABLED )

2
3 show lsn logprofile

To bind the LSN log profile to an LSN group of an LSN configuration by using the CLI

At the command prompt, type:

1 bind lsn group <groupname>  -logProfileName <lsnlogprofilename>

2
3 show lsn group

To create an LSN log profile by using the GUI

Navigate to System > Large Scale NAT > Profiles, click Log tab, and then add a log profile.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 398

NetScaler 12.0

To bind the LSN log profile to an LSN group of an LSN configuration by using the GUI

1. Navigate to System > Large Scale NAT > LSN Group, open the LSN group.
2. In Advanced Settings, click + Log Profile to bind the created Log profile to the LSN group.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Port Control Protocol for DS-Lite

September 17, 2018

Contributed by:
C

NetScaler appliances now support Port Control Protocol (PCP) for large scale NAT (LSN). Many of an
ISP’s subscriber applications must be accessible from Internet (for example, Internet of Things (IOT)
devices, such as an IP camera that provides surveillance over the Internet). One way to meet this
requirement is to create static large scale NAT (LSN) maps. But for a very large number of subscribers,
creating static LSN NAT maps is not a feasible solution.

Port Control Protocol (PCP) enables a subscriber to request specific LSN NAT mappings for itself
and/or for other 3rd party devices. The large scale NAT device creates an LSN map and sends it to the
subscriber. The subscriber sends the remote devices on the Internet the NAT IP address:NAT port at
which they can connect to the subscriber.

Applications usually send frequent keep-alive messages to the large scale NAT device so that their LSN
mappings do not time out. PCP helps reduce the frequency of such keep-alive messages by enabling
the applications to learn the timeout settings of the LSN mappings. This helps reduce bandwidth
consumption on the ISP’s access network and battery consumption on mobile devices.

PCP is a client-server model and runs over the UDP transport protocol. A NetScaler appliance imple-
ments the PCP server component and is compliant with RFC 6887.

Configuration Steps

Perform the following tasks for configuring PCP:

• (Optional) Create a PCP profile. A PCP profile includes settings for PCP related parameters (for
example, to listen for mapping and peer PCP requests). A PCP profile can be bound to a PCP
server. A PCP profile bound to a PCP server applies all its settings to the PCP server. A PCP profile

© 1999-2018 Citrix Systems, Inc. All rights reserved. 399

NetScaler 12.0

can be bound to multiple PCP servers. By default, one PCP profile with default parameters
settings is bound to all PCP servers. A PCP profile that you bind to a PCP server overrides the
default PCP profile settings for that server. A default PCP profile has the following parameter
settings:
– Mapping: Enabled
– Peer: Enabled
– Minimum map life: 120 seconds
– Maximum max life: 86400 seconds
– Announce count: 10
– Third Party: Disabled
• Create a PCP server and bind a PCP profile to it. Create a PCP server on the NetScaler appliance
to listen for PCP related requests and messages from the subscribers. A Subnet IP (SNIP) address
must be assigned to a PCP server to access it. By default, a PCP server listens on port 5351.
• Bind the PCP server to an LSN group of an LSN configuration. Bind the created PCP server to an
LSN group of an LSN configuration by setting the PCP Server parameter to specify the created
PCP server. The created PCP server can be accessed only by the subscribers of this LSN group.
Note: A PCP server for a large scale NAT configuration does not serve requests from subscribers
that are identified from ACL rules.

To create a PCP profile by using the CLI

At the command prompt, type:

1 add pcp profile <name> [-mapping ( ENABLED | DISABLED )] [-peer (

ENABLED | DISABLED )] [-minMapLife <secs>]  [-maxMapLife <secs>] [-
announceMultiCount <positive_integer>][-thirdParty ( ENABLED |
DISABLED )]
2
3 show pcp profile <name>

To create a PCP server by using the CLI

At the command prompt, type:

1 add pcp server <name> <IPAddress> [-port <portNum|*>] [-pcpProfile <

string>]
2
3 show pcp server <name>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 400

NetScaler 12.0

Sample Configuration for DS-LITE

In the following sample configuration, PCP server PCP-SERVER-1, with PCP settings from PCP-DSLITE-
PROFILE-1, is bound to LSN group LSN-DSLITE-GROUP-1. PCP-SERVER-9 serves PCP requests from
IPv4 subscribers behind B4 devices from network 2001:DB8::3:0/100.
Sample configuration:

1 add pcp profile PCP-DSLITE-PROFILE-1 -minMapLife 300

2 Done
3 add pcp server PCP-DSLITE-SERVER-1 192.0.3.10  -pcpProfile PCP-DSLITE-
PROFILE-1
4 Done
5 add lsn client LSN-DSLITE-CLIENT-1
6 Done
7 bind lsn client LSN-DSLITE-CLIENT-1 -network6 2001:DB8::3:0/100
8 Done
9 add lsn pool LSN-DSLITE-POOL-1
10 Done
11 bind lsn pool LSN-DSLITE-POOL-1 203.0.113.61 - 203.0.113.70
12 Done
13 add lsn ip6profile LSN-DSLITE-PROFILE-1 -type DS-Lite -network6 2001:
DB8::5:6
14 Done
15 add lsn group LSN-DSLITE-PROFILE-1 -clientname LSN-NAT64-CLIENT-1  -
ip6profile LSN-NAT64-PROFILE-1
16 Done
17 bind lsn group LSN-DSLITE-GROUP-1 -poolname LSN-NAT64-POOL-1
18 Done
19 bind lsn group LSN-DSLITE-GROUP-1 -poolname  PCP-NAT64-SERVER-1
20 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Large Scale NAT64

January 6, 2019
Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 401

NetScaler 12.0

Because of the imminent exhaustion of IPv4 addresses, ISPs have started transitioning to IPv6 infras-
tructure. But during the transition, ISPs must continue to support IPv4 along with IPv6, because most
of the public Internet still uses IPv4. Large scale NAT64 is an IPv6 transition solution for ISPs with IPv6
infrastructure to connect their IPv6-only subscribers to the IPv4 Internet. DNS64 is a solution for en-
abling discovery of IPv4-only domains by IPv6-only clients. DNS64 is used with large scale NAT64 to
enable seamless communication between IPv6-only clients and IPv4-only servers.

A NetScaler appliance implements large scale NAT64 and DNS64 and is compliant with RFCs 6145,
6146, 6147, 6052, 3022, 2373, 2765, and 2464.

Architecture

The NAT64 architecture of an ISP using a NetScaler appliance consists of IPv6 subscribers access-
ing the IPv4 Internet through a NetScaler appliance deployed in the ISP’s core network. IPv6 sub-
scribers are connected to the ISP core network through the ISP’s IPv6-only access network.

The large scale NAT64 functionality of a NetScaler appliance enables communication between IPv6
clients and IPv4 servers through IPv6-to-IPv4 packet translation, and vice versa, while maintaining
session information on the NetScaler appliance.NetScaler DNS64 functionality represents IPv4-only
domains to IPv6-subscribers by synthesizing DNS AAAA records for IPv4-only domains and sending
them to the subscribers.

Large scale NAT64 has two main components: NAT64 prefix and NAT IPv4 pool. DNS64 has one main
component, DNS64 prefix, which has the same value as NAT64 prefix.

Upon receiving an AAAA request from an IPv6-only subscriber for a domain name that is hosted on an
IPv4-only web server on the Internet, the NetScaler DNS64 functionality synthesizes an AAAA record
for the domain name and sends it to the subscriber. The AAAA record is synthesized by concatenating
the DNS64 prefix (which is set to the NAT64 prefix) and the actual IPv4 address of the domain name.

The subscriber now has an IPv6 destination address that corresponds to the desired domain name.
The subscriber sends the request to the synthesized IPv6 address. Upon receiving the IPv6 request,
the large scale NetScaler NAT64 functionality translates the IPv6 request packet to an IPv4 request
packet. Large scale NAT64 sets the IPv4 request’s destination address to the IPv4 address, which is
extracted from the IPv6 request’s destination address by stripping the NAT64 prefix from the IPv6 ad-
dress. The destination port is retained from the IPv6 request. Large Scale NAT64 also sets the source
IP address:source port of the IPv4 packet to the NAT IP address:NAT port selected from the configured
NAT pool.

The appliance maintains a record of all active sessions that use the large scale NAT64 functionality.
These sessions are called large scale NAT64 sessions. The appliance also maintains the mappings be-
tween subscriber IPv6 address and port, and NAT IPv4 address and port, for each large scale NAT64
session. These mappings are called large scale NAT64 mappings. From large scale NAT64 session en-

© 1999-2018 Citrix Systems, Inc. All rights reserved. 402

NetScaler 12.0

tries and large scale NAT64 mapping entries, the NetScaler appliance recognizes a response packet
(received from the Internet) as belonging to a particular NAT64 session.

When the appliance receives an IPv4 response packet belonging to a particular NAT64 session, it uses
the information stored in the NAT64 session to translate the IPv4 packet into an IPv6 packet, and then
sends the IPv6 response packet to the subscriber.

Example: Traffic Flow of NAT64 and DNS64 Deployment

Consider an example of a large scale NAT64 and DNS64 deployment consisting of NetScaler appliance
NS-1 and two local DNS servers, DNS-1 and DNS-2, in an ISP’s core network, and IPv6 subscriber SUB-1.
SUB-1 is connected to NS-1 through the ISP’s IPv6 access network. NS-1 includes large scale NAT64
and DNS64 configurations for enabling the communication between IPv6 subscriber SUB-1 and IPv4
hosts (internal and external).

Large scale NAT64 configuration includes a NAT64 prefix (2001:DB8:300::/96) and NAT IPv4 pool for
translation of IPv6 requests to IPv4 requests and IPv4 responses to IPv6 responses.

DNS64 configuration includes a DNS load balancing virtual server LBVS-DNS64-1 (2001:DB8:9999::99)
and a DNS64 prefix (2001:DB8:300::/96). LBVS-DNS64-1 represents local DNS server DNS-1 and DNS-
2 to ISP’s subscribers. The DNS64 prefix, which has the same value as the NAT64 prefix, is used for
synthesizing DNS AAAA records from DNS A records received from DNS servers DNS-1 and DNS-2. NS-
1 responds with a synthesized AAAA record to SUB-1 for a DNS request to resolve an IPv4 host.

DNS64 Traffic Flow

Traffic flows between IPv6 subscriber SUB-1 and site www.example.com, which resides on an IPv4-
only web server on the Internet, as follows:

1. IPv6 subscriber SUB-1 sends a DNS AAAA request for www.example.com to its designated DNS
server (2001:DB8:9999::99).
2. DNS load balancing virtual server LBVS-DNS64-1 (2001:DB8:9999::99) on NetScaler appliance
NS1 receives the AAAA request. LBVS-DNS64-1’s load balancing algorithm selects DNS server
DNS-1 and forwards the AAAA request to it.
3. DNS-1 returns an empty record or an error message, because there is no AAAA record available
for www.example.com.
4. Because the DNS64 option is enabled on LBVS-DNS64-1 and the AAAA request from CL1 matches
the condition specified in DNS64-Policy-1, NS1 sends a DNS A request to DNS-1 for the IPv4 ad-
dress of www.example.com.
5. DNS-1 responds with the A record of 192.0.2.60 for www.example.com.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 403

NetScaler 12.0

6. DNS64 module on NS1 synthesizes an AAAA record for www.example.com by concatenating the
DNS64 Prefix (2001:DB8:300::/96) associated with LBVS-DNS64-1, and IPv4 address (192.0.2.60)
for www.example.com = 2001:DB8:300::192.0.2.60
7. NS1 sends the synthesized AAAA record to IPv6 client CL1. NS1 also caches the A record into
its memory. NS1 uses the cached A record to synthesize AAAA records for subsequent AAAA re-
quests.

NAT64 Traffic Flow

1. IPv6 subscriber SUB-1 sends a request to 2001:DB8:5001:30 www.example.com. The IPv6 packet
has:
• Source IP address = 2001:DB8:5001:30
• Source port = 2552
• Destination IP address = 2001:DB8:300::192.0.2.60
• Destination port = 80
2.IPv6 subscriber SUB-1 sends a request to 2001:DB8:5001:30 www.example.com. The IPv6 packet
has:
• Source IP address = 2001:DB8:5001:30
• Source port = 2552
• Destination IP address = 2001:DB8:300::192.0.2.60
• Destination port = 80
3. When NS-1 receives the IPv6 packet, the large scale NAT64 module creates a translated IPv4
request packet with:
• Source IP address = One of the IPv4 addresses available in the configured NAT pool (203.0.113.61)
• Source port = One of ports available with the allocated NAT IPv4 address (3002)
• Destination IP address = IPv4 address extracted from the IPv6 request’s destination address by
stripping the NAT64 prefix (2001:DB8:300::/96) from the IPv6 address (192.0.2.60)
• Destination port = IPv6 request’s destination port (80)
4. The large scale NAT64 module also creates mapping and session entries for this large scale NAT64
flow. The session and mapping entries include the following information:
• Source IP address of the IPv6 packet = 2001:DB8:5001:30
• Source port of the IPv6 packet = 2552
• NAT IP address = 203.0.113.61
• NAT port = 3002
• NS-1 sends the resulting IPv4 packet to its destination on the Internet.
5. Upon receiving the request packet, the server for www.example.com processes the packet and
sends a response packet to NS-1. The IPv4 response packet has:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 404

NetScaler 12.0

• Source IP address = 192.0.2.60

• Source port = 80
• Destination IP address = 203.0.113.61
• Destination port = 3002
6. Upon receiving the IPv4 response packet, NS-1 examines the large scale NAT64 mapping and ses-
sion entries and finds that the IPv4 response packet belongs to a large scale NAT64 session. The large
scale NAT64 module creates a translated IPv6 response packet:
• Source IP address = 2001:DB8:300::192.0.2.60
• Source port = 80
• Destination IP address = 2001:DB8:5001:30
• Destination port = 2552
7. NS-1 sends the translated IPv6 response to client SUB-1.

Large Scale NAT64 features Supported on NetScaler appliances

Large scale NAT64 on a NetScaler appliance supports the standard LSN feature set. For more informa-
tion on these LSN features, see LSN Architecture.
Following are some of the large scale NAT64 features supported on NetScaler appliances:
• ALGs. Support of application Layer Gateway (ALG) for SIP, RTSP, FTP, ICMP, and TFTP protocols.
• Deterministic/Fixed NAT. Support for pre-allocation of blocks of ports to subscribers to minimize
logging.
• Mapping. Support of Endpoint-independent mapping (EIM), Address-dependent mapping
(ADM), and Address-Port dependent mapping (APDM).
• Filtering. Support of Endpoint-Independent Filtering (EIF), Address-Dependent Filtering (ADF),
and Address-Port-Dependent Filtering (APDF).
• Quotas. Configurable limits on number of ports, sessions per subscriber, and sessions per LSN
group.
• Static Mapping. Support for manually defining a large scale NAT64 mapping.
• Hairpin Flow. Support for communication between subscribers or internal hosts using NAT IP
addresses.
• 464XLAT connections. Support for communication between IPv4-only applications on IPv6 sub-
scriber hosts and IPv4 hosts on the Internet through IPv6 network.
• Variable length NAT64 and DNS64 prefixes. The NetScaler appliance supports defining NAT64
and DNS64 prefixes of lengths of 32, 40, 48, 56, 64, and 96.
• Multiple NAT64 and DNS64 prefix. The NetScaler appliance supports multiple NAT64 and DNS64
prefixes.
• LSN Clients. Support for specifying or identifying subscribers for large scale NAT64 by using IPv6
prefixes and extended ACL6 rules.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 405

NetScaler 12.0

• Logging. Support for logging NAT64 sessions for law enforcement. In addition, the following
are also supported for logging.
– Reliable SYSLOG. Support for sending SYSLOG messages over TCP to external log servers
for a more reliable transport mechanism.
– Load balancing of log servers. Support for load balancing of external log servers for pre-
venting storage of redundant log messages.
– Minimal Logging. Deterministic LSN configurations or Dynamic LSN configurations with
port block significantly reduce the large scale NAT64 log volume.
– Logging MSISDN information. Support for including subscribers’ MSISDN information in
large scale NAT64 logs to identify and track subscriber activity over the Internet.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Points to Consider for Configuring Large Scale NAT64

September 17, 2018

Contributed by:
C

Before you start configuring large scale NAT64 and DNS64, consider these points:

1. Make sure you understand the different components of large scale NAT64, described in RFCs.
2. The NetScaler appliance supports only the following ALGs for large Scale NAT64:
• FTP
• TFTP
• ICMP
• SIP
• RTSP
3. In a high availability setup of two NetScaler appliances, large NAT64 session synchronization
(connection mirroring) is not supported.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

© 1999-2018 Citrix Systems, Inc. All rights reserved. 406

NetScaler 12.0

Configuring DNS64

September 17, 2018

Contributed by:
C

Creating the required entities for stateful NAT64 configuration on the NetScaler appliance involves the
following procedures:

• Add DNS services. DNS services are logical representations of DNS servers for which the
NetScaler appliance acts as a DNS proxy server. For more information on setting optional
parameters of a service, see “Load Balancing”.
• Add DNS64 action and DNS64 policy and then bind the DNS64 action to the DNS64 policy. A
DNS64 policy specifies conditions to be matched against traffic for DNS64 processing accord-
ing to the settings in the associated DNS64 action. The DNS64 action specifies the mandatory
DNS64 prefix and the optional exclude-rule and mapped-rule settings.
• Create a DNS load balancing virtual server and bind the DNS services and the DNS64 policy to
it. The DNS load balancing virtual server acts as a DNS proxy server for DNS servers represented
by the bound DNS services. Traffic arriving at the virtual server is matched against the bound
DNS64 policy for DNS64 processing. For more information on setting optional parameters of a
load balancing virtual server, see “Load Balancing.

Note

The command line interface has separate commands for these two tasks, but the GUI combines
them in a single dialog box.

• Enable caching of DNS records. Enable the global parameter for the NetScaler appliance to
cache DNS records, which are obtained through DNS proxy operations. For more information
on enabling caching of DNS records, see “Enabling Caching of DNS Records”.

To create a service of type DNS by using the command line interface

At the command prompt, type:

1 add service <name> <IP> <serviceType> <port> …

To create a DNS64 action by using the command line interface

At the command prompt, type:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 407

NetScaler 12.0

1 add dns action64 <actionName> -Prefix <ipv6_addr|*> [-mappedRule <

expression>] [-excludeRule <expression>]

To create a DNS64 policy by using the command line interface

At the command prompt, type:

1 add dns policy64 <name> -rule <expression> -action <string>

To create a DNS load balancing virtual server by using the command line interface

At the command prompt, type:

1 add lb vserver <name> DNS <IPAddress> <port> -dns64 (ENABLED | DISABLED

) [-bypassAAAA ( YES | NO)] …

To bind the DNS services and the DNS64 policy to the DNS load balancing virtual server
by using the command line interface

At the command prompt, type:

1 bind lb vserver <name> <serviceName> ...

2
3 bind lb vserver <name> -policyName <string> -priority <positive_integer
> ...

Sample configuration:

1 add service SVC-DNS-1 203.0.113.50 DNS 53

2 Done
3 add service SVC-DNS-2 203.0.113.60 DNS 53
4 Done
5 add dns Action64 DNS64-Action-1 -Prefix 2001:DB8:300::/96
6 Done
7 add dns Policy64 DNS64-Policy-1 -rule ”CLIENT.IPv6.SRC.IN_SUBNET(2001:
DB8:5001::/64)” -action DNS64-Action-1
8 Done
9 add lb vserver LBVS-DNS64-1 DNS 2001:DB8:9999::99 53 -dns64 ENABLED
10 Done
11 bind lb vserver LBVS-DNS64-1 SVC-DNS-1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 408

NetScaler 12.0

12 Done
13 bind lb vserver LBVS-DNS64-1 SVC-DNS-2
14 Done
15 bind lb vserver LBVS-DNS64-1 -policyname DNS64-Policy-1 -priority 2
16 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Configuring Large Scaler NAT64

December 27, 2018

Contributed by:
C

A large scale NAT64 configuration on a NetScaler appliance uses the LSN commands sets. In a large
scale NAT64 configuration, the LSN client entity specifies the IPv6 address or IPv6 network address,
or ACL6 rules, for identifying IPv6 subscribers. A NAT64 configuration also includes an IPv6 profile,
which specifies a NAT64 prefix.

Configuring NAT64 on a NetScaler appliance consists of the following tasks:

• Set the global LSN parameters. Global parameters include the amount of NetScaler memory
reserved for the LSN feature and synchronization of LSN sessions in a high availability setup.
• Create an LSN client entity for identifying traffic from IPv6 subscribers. The LSN client entity
refers to a set of IPv6 subscribers. The client entity includes IPv6 addresses or IPv6 network
prefixes, or ACL6 rules, for identifying the traffic from these subscribers. An LSN client can be
bound to only one LSN group. The command line interface has two commands for creating an
LSN client entity and binding a subscriber to the LSN client entity. The GUI combines these two
operations on a single screen.
• Create an LSN pool and bind NAT IP addresses to it. An LSN pool defines a pool of NAT IP ad-
dresses to be used by the NetScaler appliance to perform large scale NAT64. The command line
interface has two commands for creating an LSN pool and binding NAT IP addresses to the LSN
pool. The GUI combines these two operations on a single screen.
• Create an LSN IP6 profile. An LSN IP6 profile defines the NAT64 prefix for a large scale NAT64
configuration.
• (Optional) Create an LSN Transport Profile for a specified protocol. An LSN transport profile de-
fines various timeouts and limits, such as maximum large scale NAT64 sessions and maximum

© 1999-2018 Citrix Systems, Inc. All rights reserved. 409

NetScaler 12.0

ports usage that a subscriber can have for a given protocol. You bind an LSN transport profile
for each protocol (TCP, UDP, and ICMP) to an LSN group. A profile can be bound to multiple LSN
groups. A profile bound to an LSN group applies to all subscribers of an LSN client bound to
the same group. By default, one LSN transport profile with default settings for TCP, UDP, and
ICMP protocols is bound to an LSN group during its creation. This profile is called the default
transport profile. An LSN transport profile that you bind to an LSN group overrides the default
LSN transport profile for that protocol.
• (Optional) Create an LSN Application Profile for a specified protocol and bind a set of destination
ports to it. An LSN application profile defines the LSN mapping and LSN filtering controls of a
group for a given protocol and for a set of destination ports. For a set of destination ports, you
bind an LSN profile for each protocol (TCP, UDP, and ICMP) to an LSN group. A profile can be
bound to multiple LSN groups. An LSN application profile bound to an LSN group applies to all
subscribers of an LSN client bound to the same group. By default, one LSN application profile
with default settings for TCP, UDP, and ICMP protocols for all destination ports is bound to an
LSN group during its creation. This profile is called a default application profile. When you bind
an LSN application profile, with a specified set of destination ports, to an LSN group, the bound
profile overrides the default LSN application profile for that protocol at that set of destination
ports. The command line interface has two commands for creating an LSN application profile
and binding a set of destination ports to the LSN application profile. The GUI combines these
two operations on a single screen.
• Create an LSN Group and bind LSN pools, LSN IPv6 profile, (optional) LSN transport profiles,
and (optional) LSN application profiles to the LSN group. An LSN group is an entity consisting
of an LSN client, an LSN IPv6 profile, LSN pool(s), LSN transport profile(s), and LSN application
profiles(s). A group is assigned parameters, such as port block size and logging of LSN sessions.
The parameter settings apply to all the subscribers of an LSN client bound to the LSN group.
Only one LSN IPv6 profile can be bound to an LSN group, and an LSN IPv6 profile bound to
an LSN group cannot be bound to other LSN groups. Only LSN Pools and LSN groups with the
same NAT type settings can be bound together. Multiples LSN pools can be bound to an LSN
group. Only one LSN client entity can be bound to an LSN group, and an LSN client entity bound
to an LSN group cannot be bound to other LSN groups. The command line interface has two
commands for creating an LSN group and binding LSN pools, LSN transport profiles, and LSN
application profiles to the LSN group. The GUI combines these two operations in a single screen.

Configuration Using the Command Line

You can create different configurations using the command line interface. Follow the steps given be-
low.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 410

NetScaler 12.0

To create an LSN client by using the command line interface

At the command prompt, type:

1 add lsn client <clientname

2
3 show lsn client

To bind an IPv6 network or an ACL6 rule to an LSN client by using the command line interface

At the command prompt, type:

1 bind lsn client <clientname> (-network6 <ipv6_addr|*>| -acl6name <

string>)
2
3 show lsn client

To create an LAN pool by using the command line interface

At the command prompt, type:

1 add lsn pool <poolname>

2
3 show lsn pool <poolname>

To bind NAT IP addresses to an LSN pool by using the command line interface

At the command prompt, type:

1 bind lsn pool <poolname> <lsnip>

2
3 show lsn pool

Note

For removing NAT IP (LSN IP addresses) addresses from an LSN pool, use the unbind lsn pool
command.

To configure an LSN IPv6 profile by using the command line interface

At the command prompt, type:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 411

NetScaler 12.0

1 add lsn ip6profile <name> ‒ type NAT64 -natprefix <ipv6_addr|*>

2
3 show lsn ip6profile

To create an LSN transport profile by using the command line interface

At the command prompt, type:

1 add lsn transportprofile <transportprofilename> <transportprotocol> [-

sessiontimeout <secs>] [-finrsttimeout <secs>] [-portquota <
positive_integer>] [-sessionquota <positive_integer>] [-
portpreserveparity ( ENABLED | DISABLED )] [-portpreserverange (
ENABLED | DISABLED )] [-syncheck ( ENABLED | DISABLED )]
2
3 show lsn transportprofile

To create an LSN application profile by using the command line interface

At the command prompt, type:

1 add lsn appsprofile <appsprofilename> <transportprotocol> [-ippooling (

PAIRED | RANDOM )] [-mapping <mapping>] [-filtering <filtering>][-
tcpproxy ( ENABLED | DISABLED )]
2
3 show lsn appsprofile

To bind an application protocol port range to an LSN application profile by using the command
line interface

At the command prompt, type:

1 bind lsn appsprofile <appsprofilename> <lsnport>

2
3 show lsn appsprofile

To create an LSN group by using the command line interface

At the command prompt, type:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 412

NetScaler 12.0

1 add lsn group <groupname> -clientname <string> [-nattype ( DYNAMIC |

DETERMINISTIC )] [-portblocksize <positive_integer>] [-logging(
ENABLED | DISABLED )] [-sessionLogging ( ENABLED | DISABLED )][-
sessionSync ( ENABLED | DISABLED )] [-snmptraplimit<positive_integer
>] [-ftp ( ENABLED | DISABLED )] [-sipalg ( ENABLED | DISABLED )] [-
rtspalg ( ENABLED |DISABLED )] [-ip6profile <string>]
2
3 show lsn group

To bind LSN protocol profiles and LSN pools to an LSN group by using the command line
interface

At the command prompt, type:

1 bind lsn group <groupname> (-poolname <string> | -transportprofilename

<string> | -httphdrlogprofilename <string> | -appsprofilename <
string> | -sipalgprofilename <string> | rtspalgprofilename <string>)
2
3 show lsn group

Sample Large Scale NAT64 Configurations

Here are some sample configurations of large scale NAT64:

Simple large scale NAT64 configuration with default settings:

1 add lsn client LSN-NAT64-CLIENT-1

2
3 bind lsn client LSN-NAT64-CLIENT-1 -network6 2001:DB8:5001::/96
4
5 add lsn pool LSN-NAT64-POOL-1
6
7 bind lsn pool LSN-NAT64-POOL-1 203.0.113.61 - 203.0.113.70
8
9 add lsn ip6profile LSN-NAT64-PROFILE-1 -type NAT64 -natprefix 2001:DB8
:300::/96
10
11 add lsn group LSN-NAT64-GROUP-1 -clientname LSN-NAT64-CLIENT-1 -
ip6profile LSN-NAT64-PROFILE-1
12
13 bind lsn group LSN-NAT64-GROUP-1 -poolname LSN-NAT64-POOL-1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 413

NetScaler 12.0

Simple large scale NAT64 configuration with an extended ACL6 rule for identifying subscribers:

1 add ns acl6 LSN-NAT64-ACL-2 ALLOW ‒ srcIPv6 = 2001:DB8:5002::20 - 2001:

DB8:5002::200
2
3 apply acl6s
4
5 add lsn client LSN-NAT64-CLIENT-2
6
7 bind lsn client LSN-NAT64-CLIENT-2 ‒ acl6name LSN-NAT64-ACL-2
8
9 add lsn pool LSN-NAT64-POOL-2
10
11 bind lsn pool LSN-NAT64-POOL-2 203.0.113.5-203.0.113.10
12
13 add lsn ip6profile LSN-NAT64-PROFILE-2 -type NAT64 -natprefix 2001:DB8
:302::/96
14
15 add lsn group LSN-NAT64-GROUP-2 -clientname LSN-NAT64-CLIENT-2 -
ip6profile LSN-NAT64-PROFILE-2
16
17 bind lsn group LSN-NAT64-GROUP-2 -poolname LSN-NAT64-POOL-2

Large scale NAT64 configuration with deterministic NAT resource allocation:

1 add lsn client LSN-NAT64-CLIENT-7

2
3 bind lsn client LSN-NAT64-CLIENT-7 -network6 2001:DB8:1002::7/128
4
5 add lsn pool LSN-NAT64-POOL-7 -nattype DETERMINISTIC
6
7 bind lsn pool LSN-NAT64-POOL-7 203.0.113.24-203.0.113.27
8
9 add lsn ip6profile LSN-NAT64-PROFILE-7 -type NAT64 -natprefix 2001:DB8
:307::/96
10
11 add lsn group LSN-NAT64-GROUP-7 -clientname LSN-NAT64-CLIENT-7 -
ip6profile LSN-NAT64-PROFILE-7 -nattype DETERMINISTIC -portblocksize
256
12
13 bind lsn group LSN-NAT64-GROUP-7 -poolname LSN-POOL-7

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 414

NetScaler 12.0

4. Solutions for Telecom Service Providers

Configuring Application Layer Gateways for Large Scale NAT64

September 17, 2018

Contributed by:
C

For some Application layer protocols, the IP addresses and protocol port numbers are also commu-
nicated in the packet payload. Application Layer Gateway for a protocol parses the packet’s payload
and does necessary changes to ensure that the protocol continues to work over large scale NAT64.

The NetScaler appliance supports ALG for the following protocols for large scale NAT64:

• FTP
• ICMP
• TFTP
• SIP
• RTSP

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Application Layer Gateway for FTP, ICMP, and TFTP Protocols

September 17, 2018

Contributed by:
C

You can enable or disable ALG for the FTP protocol for an large scale NAT64 configuration by enabling
or disabling the FTP ALG option of the LSN group of the configuration.

ALG for the ICMP protocol is enabled by default, and there is no provision to disable it.

ALG for the TFTP protocol is disabled by default. TFTP ALG is enabled automatically for an large
scale NAT64 configuration when you bind a UDP LSN application profile, with endpoint-independent-
mapping, endpoint-independent filtering, and destination port as 69 (well-known port for TFTP), to
the LSN group.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 415

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Application Layer Gateway for SIP Protocol

September 17, 2018

Contributed by:
C

Using Large Scale NAT64 with Session Initiation Protocol (SIP) is complicated, because SIP messages
contain IP addresses in the SIP headers as well as in the SIP body. When LSN is used with SIP, the
SIP headers contain information about the caller and the receiver, and the device translates this infor-
mation to hide it from the outside network. The SIP body contains the Session Description Protocol
(SDP) information, which includes IP addresses and port numbers for transmission of the media. SIP
ALG for large scale NAT64 is compliant with RFC 3261, RFC 3581, RFC 4566, and RFC 4475.

Limitations of SIP ALG

SIP ALG for large scale NAT64 has the following limitations:

• Only SDP payload is supported.

• The following are not supported:
– Multicast IP addresses
– Encrypted SDP
– SIP TLS
– FQDN translation
– SIP layer authentication
– Traffic Domains
– Admin partitions
– NetScaler clusters
– Multipart body
– Line folding

© 1999-2018 Citrix Systems, Inc. All rights reserved. 416

NetScaler 12.0

Configuring SIP ALG

You need to configure the SIP ALG as part of the LSN configuration. For instructions on configuring
LSN, see Configuration Large Scale NAT64. While configuring LSN, make sure that you:
• Set the following parameters while adding an LSN application profile:
– IP Pooling = PAIRED
– Address and Port Mapping = ENDPOINT-INDEPENDENT
– Filtering = ENDPOINT-INDEPENDENT
• Create a SIP ALG profile and make sure that you define either the source port range or destina-
tion port range. Bind the SIP ALG profile to the LSN group.
• Enable SIP ALG in the LSN group.

To enable SIP ALG for an LSN configuration by using the CLI

At the command prompt, type:

1 add lsn group <groupname> -clientname <string> [-sipalg ( ENABLED |

DISABLED )]
2
3 show lsn group <groupname>

To enable SIP ALG for an LSN configuration by using the CLI

At the command prompt, type:

1 add lsn sipalgprofile <sipalgprofilename>[-dataSessionIdleTimeout <

positive_integer>][-sipSessionTimeout <positive_integer>] [-
registrationTimeout <positive_integer>] [-sipsrcportrange <port[-
port]>] [-sipdstportrange <port[-port]>] [-openRegisterPinhole (
ENABLED | DISABLED )] [-openContactPinhole ( ENABLED | DISABLED )]
[-openViaPinhole ( ENABLED | DISABLED )] [-openRecordRoutePinhole (
ENABLED | DISABLED )]-sipTransportProtocol ( TCP | UDP ) [-
openRoutePinhole ( ENABLED | DISABLED )] [-rport ( ENABLED |
DISABLED )]
2
3 show lsn sipalgprofile <sipalgprofilename

Sample Configuration

The following sample large scale NAT64 configuration, SIP ALG is enabled for TCP traffic from sub-
scriber devices in the network 2001:DB8:1003::/96.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 417

NetScaler 12.0

1 add lsn client LSN-NAT64-CLIENT-9

2
3 Done
4 bind lsn client LSN-NAT64-CLIENT-9 -network6 2001:DB8:1002::/96
5
6 Done
7 add lsn pool LSN-NAT64-POOL-9
8
9 Done
10 bind lsn pool LSN-NAT64-POOL-9 203.0.113.90
11
12 Done
13 add lsn ip6profile LSN-NAT64-PROFILE-9 -type NAT64 -natprefix 2001:DB8
:309::/96
14
15 Done
16 add lsn appsprofile LSN-NAT64-APPS-PROFILE-9 TCP -ippooling PAIRED ‒
mapping ENDPOINT-INDEPENDENT -filtering ENDPOINT-INDEPENDENT
17
18 Done
19 add lsn sipalgprofile SIPALGPROFILE-9  -sipdstportrange 5060  -
sipTransportProtocol TCP
20
21 Done
22 add lsn group LSN-NAT64-GROUP-9 -clientnameLSN-NAT64-CLIENT-9 -
ip6profile LSN-NAT64-PROFILE-7 -sipalg ENABLED
23
24 Done
25 bind lsn group LSN-NAT64-GROUP-9 -poolnameLSN-NAT64-POOL-9
26 Done
27 bind lsn group LSN-NAT64-GROUP-9 -appsprofilename LSN-NAT64-APPS-
PROFILE-9
28 Done
29 bind lsn group LSN-NAT64-GROUP-9 -sipalgprofilename SIPALGPROFILE-9
30 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

© 1999-2018 Citrix Systems, Inc. All rights reserved. 418

NetScaler 12.0

Application Layer Gateway for RTSP Protocol

September 17, 2018

Contributed by:
C
Real Time Streaming Protocol (RTSP) is an application-level protocol for the transfer of real-time me-
dia data. Used for establishing and controlling media sessions between end points, RTSP is a control
channel protocol between the media client and the media server. The typical communication is be-
tween a client and a streaming media server.
Streaming media from a private network to a public network requires translating IP addresses and
port numbers over the network. NetScaler functionality includes an Application Layer Gateway (ALG)
for RTSP, which can be used with Large Scale NAT (LSN) to parse the media stream and make any
necessary changes to ensure that the protocol continues to work over the network.
How IP address translation is performed depends on the type and direction of the message, and the
type of media supported by the client-server deployment. Messages are translated as follows:
• Outbound request—Private IP address to NetScaler owned public IP address called LSN IP ad-
dress.
• Inbound response—LSN IP address to private IP address.
• Inbound request—No translation.
• Outbound response—Private IP address to LSN pool IP address.

Limitations of RTSP ALG

The RTSP ALG does not support the following:

• Multicast RTSP sessions
• RTSP session over UDP
• Admin partitions
• NetScaler clusters
• RTSP Authentication
• HTTP tunneling

Configuring RTSP ALG

Configure RTSP ALG as part of the LSN configuration. For instructions on configuring LSN, see Config-
uring Large Scale NAT64. While configuring, make sure that you:
• Set the following parameters while adding an LSN application profile:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 419

NetScaler 12.0

– IP Pooling = PAIRED
– Address and Port Mapping = ENDPOINT-INDEPENDENT
– Filtering = ENDPOINT-INDEPENDENT
• Enable RTSP ALG in the LSN group
• Create a RTSP ALG profile and bind the RTSP ALG profile to the LSN group

To enable RTSP ALG for an LSN configuration by using the CLI

At the command prompt, type:

1 add lsn group <groupname> -clientname <string> [-rtspalg ( ENABLED |

DISABLED )]
2
3 show lsn group <groupname>

To enable RTSP ALG for an LSN configuration by using the CLI

At the command prompt, type:

1 add lsn rtspalgprofile <rtspalgprofilename> [-rtspIdleTimeout <

positive_integer>] -rtspportrange <port[-port]> [-
rtspTransportProtocol (TCP|UDP)]
2
3 show lsn rtspalgprofile <rtspalgprofilename>

Sample RTSP ALG Configuration

The following sample large scale NAT64 configuration, RTSP ALG is enabled for TCP traffic from sub-
scriber devices in the network 2001:DB8:1002::/96.

1 add lsn client LSN-NAT64-CLIENT-9

2 Done
3 bind lsn client LSN-NAT64-CLIENT-9 -network6 2001:DB8:1002::/96
4 Done
5 add lsn pool LSN-NAT64-POOL-9
6 Done
7 bind lsn pool LSN-NAT64-POOL-9 203.0.113.90
8 Done
9 add lsn ip6profile LSN-NAT64-PROFILE-9 -type NAT64 -natprefix 2001:DB8
:309::/96
10 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 420

NetScaler 12.0

11 add lsn appsprofile LSN-NAT64-APPS-PROFILE-9 TCP -ippooling PAIRED ‒

mapping ENDPOINT-INDEPENDENT -filtering ENDPOINT-INDEPENDENT
12 Done
13 add lsn rtspalgprofile RTSPALGPROFILE-9 -rtspIdleTimeout 1000 -
rtspportrange 554
14 Done
15 add lsn group LSN-NAT64-GROUP-9 -clientname LSN-NAT64-CLIENT-9 -
ip6profile LSN-NAT64-PROFILE-7 -rtspalg ENABLED
16 Done
17 bind lsn group LSN-NAT64-GROUP-9 -poolname LSN-NAT64-POOL-9
18 Done
19 bind lsn group LSN-NAT64-GROUP-9 -appsprofilename LSN-NAT64-APPS-
PROFILE-9
20 Done
21 bind lsn group LSN-NAT64-GROUP-9  -rtspalgprofilename RTSPALGPROFILE-9
22 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Configuring Static Large Scale NAT64 Maps

September 17, 2018

Contributed by:
C

The NetScaler appliance supports manual creation of NAT64 mappings, which contain the mapping
between the following information:

• Subscriber’s IP address and port

• NAT IP address and port

Static Large Scale NAT64 mappings are useful in cases where you want to ensure that the IPv4 con-
nections initiated to a NAT IP address:port are IPv6 translated and mapped to the subscriber IP ad-
dress:port (for example, web servers located in the internal network).

To create a Large Scale NAT64 mapping by using the command line

At the command prompt, type:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 421

NetScaler 12.0

1 add lsn static <name> <transportprotocol> <subscrIP> <subscrPort>  [<

natIP> [<natPort>]] [-destIP <ip_addr> [-dsttd <positive_integer>]]
2
3 show lsn static

Wildcard Port Static Large Scale NAT64 Maps

A static large scale NAT64 mapping entry is usually a one-to-one mapping between a subscriber IPv6
address:port and a NAT IPv4 address:port. A one-to-one static large scale NAT64 mapping entry ex-
poses only one port of the subscriber IP address to the Internet.
Some situations might require exposing all ports (64K - limited to the maximum number of ports of a
NAT IPv4 address) of a subscriber IP address to the Internet (for example, a server hosted on an internal
network and running a different service on each port). To make these internal services accessible
through the Internet, you have to expose all the ports of the server to the Internet.
One way to meet this requirement is to add 64 thousand one-to-one static mapping entries, one map-
ping entry for each port. Creating those entries is very cumbersome and a big task. Also, this large
number of configuration entries might lead to performance issues in the NetScaler appliance.
A simpler method is to use wildcard ports in a static mapping entry. You just need to create one static
mapping entry with NAT-port and subscriber-port parameters set to the wildcard character (*), and
the protocol parameter set to ALL, to expose all the ports of a subscriber IP address for all protocols
to the Internet.
For a subscriber’s inbound or outbound connections matching a wildcard static mapping entry, the
subscriber’s port does not change after the NAT operation. When a subscriber-initiated connection
to the Internet matches a wildcard static mapping entry, the NetScaler appliance assigns a NAT port
that has the same number as the subscriber port from which the connection is initiated. Similarly, an
Internet host gets connected to a subscriber’s port by connecting to the NAT port that has the same
number as the subscriber’s port.
To configure the NetScaler appliance to provide access to all ports of a subscriber IPv6 address, create
a wildcard static map with the following mandatory parameter settings:
• Protocol=ALL
• Subscriber port = *
• NAT port = *
In a wildcard static map, unlike in a one-to-one static map, setting the NAT IP parameter is mandatory.
Also, the NAT IP address assigned to a wildcard static map cannot be used for any other subscribers.
To create a wildcard static map by using the command line interface
At the command prompt, type:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 422

NetScaler 12.0

1 add lsn static <name> ALL <subscrIP> *  <natIP> * [-td <

positive_integer>] [-destIP <ip_addr>
2
3 show lsn static  

In the following sample configuration of a wildcard static map, all ports of a subscriber whose IP ad-
dress is 2001:DB8:5001::3 are made accessible through NAT IP 203.0.11.33.

1 add lsn static NAT64-WILDCARD-STATIC-1 ALL 2001:DB8:5001::3 *

203.0.113.33 *
2 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Logging and Monitoring Large Scale NAT64

September 17, 2018

Contributed by:
C

You can log large scale NAT64 information to diagnose and troubleshoot problems, and to meet le-
gal requirements. You can monitor the performance of the large scale NAT64 deployment by using
statistical counters and displaying the related current sessions.

Logging Large Scale NAT64

Logging large scale NAT64 information is required for ISPs to meet legal requirements and identify the
source of traffic at any given time.

A log message for a large scale NAT64 mapping entry consists of the following information:

• NetScaler owned IP address (NSIP address or SNIP address) from which the log message is
sourced.
• Time stamp.
• Entry type (MAPPING).
• Whether the mapping entry was created or deleted.
• Subscriber’s IP address, port, and traffic domain ID.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 423

NetScaler 12.0

• NAT IP address and port.

• Protocol name.
• Destination IP address, port, and traffic domain ID might be present, depending on the following
conditions:
– Destination IP address and port are not logged for endpoint-independent mapping.
– Only the destination IP address is logged for address-dependent mapping. The port is not
logged.
– Destination IP address and port are logged for address-port-dependent mapping.

A log message for a large scale NAT64 session consists of the following information:

• NetScaler owned IP address (NSIP address or SNIP address) from which the log message is
sourced
• Time stamp
• Entry type (SESSION)
• Whether the session is created or removed
• Subscriber’s IP address, port, and traffic domain ID
• NAT IP address and port
• Protocol name
• Destination IP address, port, and traffic domain ID

The following table displays sample large scale NAT64 log entries of each type stored on the config-
ured log servers. The log entries show that a subscriber whose IPv6 address is 2001:db8:5001::9 was
connected to destination IP:port 23.0.0.1:80 through NAT IP:port 203.0.113.63:45195 on April 7, 2016,
from 14:07:57 GMT to 14:10:59 GMT.

Log Entry Type Sample Log Entry

Session Creation 04/07/2016:14:07:57 GMT Informational

0-PPE-10 : default LSN LSN_SESSION 5532 0
: SESSION CREATED Client IP-Port:TD
2001:db8:5001::9-34937:0, NatIP:NatPort
203.0.113.63:45195, Destination IP:Port:TD
23.0.0.1:0:80, Protocol: TCP
Mapping Creation 04/07/2016:14:07:57 GMT Informational
0-PPE-10 : default LSN LSN_ADDR_MAPPING
5533 0 : ADM CREATED Client IP-Port:TD
2001:db8:5001::9-34937:0, NatIP:NatPort
203.0.113.63:45195, Destination IP:TD
23.0.0.1:80, Protocol: TCP

© 1999-2018 Citrix Systems, Inc. All rights reserved. 424

NetScaler 12.0

Log Entry Type Sample Log Entry

Session Deletion 04/07/2016:14:10:59 GMT 0-PPE-10 : default

LSN LSN_SESSION 25012 0 : SESSION DELETED
Client IP-Port:TD 2001:db8:5001::9-34937:0,
NatIP:NatPort 203.0.113.63:45195, Destination
IP:Port:TD 23.0.0.1:0:80, Protocol: TCP
Mapping Deletion 04/07/2016:14:10:59 GMT 0-PPE-10 : default
LSN LSN_ADDR_MAPPING 25013 0 : ADM
DELETED Client IP-Port:TD
2001:db8:5001::9-34937:0, NatIP:NatPort
203.0.113.63:45195, Destination IP:Port:TD
23.0.0.1:0:80, Protocol: TCP

Configuration Steps

You can configure logging of large scale NAT64 information for a large scale NAT64 configuration by
setting the LSN groups’s logging and session logging parameters. These are group level parameters
and are disabled by default. The NetScaler appliance logs large scale NAT64 sessions for an LSN group
only when both logging and session logging parameters are enabled.

The following table displays the logging behavior for an LSN group for various settings of logging and
session logging parameters.

Logging Session Logging Logging Behavior

Enabled Enabled Logs LSN mapping entries as

well as LSN sessions
Enabled Disabled Logs LSN mapping entries but
not LSN sessions
Disabled Enabled Logs neither mapping entries
nor LSN sessions

To log large scale NAT64 information by using the CLI

To set the logging and session logging parameters while adding an LSN group, at the command
prompt, type:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 425

NetScaler 12.0

1 add lsn group <groupname> -clientname <string> [-logging (ENABLED|

DISABLED)] [-sessionLogging (ENABLED|DISABLED)]
2
3 show lsn group

To set the logging and session logging parameters for an existing LSN group, at the command prompt,
type:

1 set lsn group <groupname> [-logging (ENABLED|DISABLED)] [-

sessionLogging (ENABLED|DISABLED)]
2
3 show lsn group

Sample Configuration

In this example of large scale NAT64 configuration, logging and session logging paramters are enabled
for LSN group LSN-NAT64-GROUP-1.

The NetScaler appliance logs large scale NAT64 session and mapping information for connections
from subscribers (in the network 2001:DB8:5001::/96).

Sample configuration:

1 add lsn client LSN-NAT64-CLIENT-1 Done

2 Done
3 bind lsn client LSN-NAT64-CLIENT-1 -network6 2001:DB8:5001::/96
4 Done
5 add lsn pool LSN-NAT64-POOL-1
6 Done
7 bind lsn pool LSN-NAT64-POOL-1 203.0.113.61 - 203.0.113.70
8 Done
9 add lsn ip6profile LSN-NAT64-PROFILE-1 -type NAT64 -natprefix 2001:DB8
:300::/96
10 Done
11 add lsn group LSN-NAT64-GROUP-1 -clientname LSN-NAT64-CLIENT-1  -
ip6profile LSN-NAT64-PROFILE-1  -logging ENABLED -sessionLogging
ENABLED
12 Done
13 bind lsn group LSN-NAT64-GROUP-1 -poolname LSN-NAT64-POOL-1
14 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 426

NetScaler 12.0

Logging MSISDN Information for Large Scale NAT64

A Mobile Station Integrated Subscriber Directory Number (MSISDN) is a telephone number uniquely iden-
tifying a subscriber across multiple mobile networks. The MSISDN is associated with a country code
and a national destination code identifying the subscriber’s operator.

You can configure a NetScaler appliance to include MSISDNs in large scale NAT64 LSN log entries for
subscribers in mobile networks. The presence of MSISDNs in the LSN logs facilitates faster and accu-
rate back tracing of a mobile subscriber who has violated a policy or law, or whose information is
required by lawful interception agencies.

The following sample LSN log entries include MSISDN information for a connection from a mo-
bile subscriber in an LSN configuration. The log entries show that a mobile subscriber whose
MSISDN is E164:5556543210 and IPv6 address is 2001:db8:5001::9 was connected to destination
IP:port 23.0.0.1:80 through the NAT IP:port 203.0.113.63:45195 on April 7, 2016, from 14:07:57 GMT
to 14:10:59 GMT.

Log Entry Type Sample Log Entry

Session Creation 04/07/2016:14:07:57 GMT Informational

0-PPE-10 : default LSN LSN_SESSION 5532 0
: SESSION CREATED E164:5556543210 Client
IP-Port:TD 2001:db8:5001::9-34937:0,
NatIP:NatPort 203.0.113.63:45195, Destination
IP:Port:TD 23.0.0.1:0:80, Protocol: TCP
Mapping Creation 04/07/2016:14:07:57 GMT Informational
0-PPE-10 : default LSN LSN_ADDR_MAPPING
5533 0 : ADM CREATED E164:5556543210
Client IP-Port:TD 2001:db8:5001::9-34937:0,
NatIP:NatPort 203.0.113.63:45195, Destination
IP:TD 23.0.0.1:80, Protocol: TCP
Session Deletion 04/07/2016:14:10:59 GMT 0-PPE-10 : default
LSN LSN_SESSION 25012 0 : SESSION
DELETED E164:5556543210 Client IP-Port:TD
2001:db8:5001::9-34937:0, NatIP:NatPort
203.0.113.63:45195, Destination IP:Port:TD
23.0.0.1:0:80, Protocol: TCP

© 1999-2018 Citrix Systems, Inc. All rights reserved. 427

NetScaler 12.0

Log Entry Type Sample Log Entry

Mapping Deletion 04/07/2016:14:10:59 GMT 0-PPE-10 : default

LSN LSN_ADDR_MAPPING 25013 0 : ADM
DELETED E164:5556543210 Client IP-Port:TD
2001:db8:5001::9-34937:0, NatIP:NatPort
203.0.113.63:45195, Destination IP:Port:TD
23.0.0.1:0:80, Protocol: TCP

Configuration Steps

Perform the following tasks for including MSISDN information in LSN logs:

• Create an LSN log profile. An LSN log profile includes the log subscriber ID parameter, which
specifies whether to or not to include the MSISDN information in the LSN logs of an LSN config-
uration.
• Bind the LSN log profile to an LSN group of an LSN configuration.Bind the created LSN log pro-
file to an LSN group of an LSN configuration by setting the log profile name parameter to the
created LSN log profile name. MSISDN information is included in all LSN logs related to mo-
bile subscribers of this LSN group.

To create an LSN log profile by using the CLI

At the command prompt, type:

1 add lsn logprofile <logprofilename> -logSubscriberID ( ENABLED |

 DISABLED )
2
3 show lsn logprofile

To bind an LSN log profile to an LSN group of an NAT64 LSN configuration by using the CLI

At the command prompt, type:

1 bind lsn group <groupname>  -logProfileName <lsnlogprofilename>

2
3 show lsn group

© 1999-2018 Citrix Systems, Inc. All rights reserved. 428

NetScaler 12.0

Sample Configuration

In this example of NAT64 LSN configuration, the LSN log profile LOG-PROFILE-MSISDN-1 has the log
subscriber ID parameter enabled. LOG-PROFILE-MSISDN-1 is bound to LSN group LSN-NAT64-GROUP-
1. MSISDN information is included in the LSN session and LSN mapping logs for connections from
mobile subscribers (in network 2001:DB8:5001::/96).

1 add lsn logprofile  LOG-PROFILE-MSISDN-1  -logSubscriberID ENABLED

2 Done
3 add lsn client LSN-NAT64-CLIENT-1
4 Done
5 bind lsn client LSN-NAT64-CLIENT-1 -network6 2001:DB8:5001::/96
6 Done
7 add lsn pool LSN-NAT64-POOL-1
8 Done
9 bind lsn pool LSN-NAT64-POOL-1 203.0.113.61 - 203.0.113.70
10 Done
11 add lsn ip6profile LSN-NAT64-PROFILE-1 -type NAT64 -natprefix 2001:DB8
:300::/96
12 Done
13 add lsn group LSN-NAT64-GROUP-1 -clientname LSN-NAT64-CLIENT-1  -
ip6profile LSN-NAT64-PROFILE-1
14 Done
15 bind lsn group LSN-NAT64-GROUP-1 -poolname LSN-NAT64-POOL-1
16 Done
17 bind lsn group LSN-NAT64-GROUP-1 -logprofilename  LOG-PROFILE-MSISDN-1
18 Done

Compact Logging for Large Scale NAT

Logging LSN information is one of the important functions needed by ISPs to meet legal requirements
and be able to identify the source of traffic at any given time. This eventually results in a huge volume
of log data, requiring the ISPs to make large investments to maintain the logging infrastructure.

Compact logging is a technique for reducing the log size by using a notational change involving
short codes for event and protocol names. For example, C for client, SC for session created, and T for
TCP. Compact logging results in an average of 40 percent reduction in log size.

Configuration Steps

Perform the following tasks for logging LSN information in compact format:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 429

NetScaler 12.0

1. Create an LSN log profile. An LSN log profile includes the Log Compact parameter, which speci-
fies whether to or not to log information in compact format for an LSN configuration.
2. Bind the LSN log profile to an LSN group of an LSN configuration. Bind the created LSN log
profile to an LSN group of an LSN configuration by setting the Log Profile Name parameter to
the created LSN log profile name. All sessions and mappings for this LSN group are logged in
compact format.

To create an LSN log profile by using the CLI

At the command prompt, type:

1 add lsn logprofile <logprofilename> -logCompact (ENABLED|DISABLED)

2
3 show lsn logprofile

To bind an LSN log profile to an LSN group of an LSN configuration by using the CLI

At the command prompt, type:

1 bind lsn group <groupname> -logProfileName <lsnlogprofilename>

2
3 show lsn group

Sample Configuration for NAT64:

1 add lsn logprofile  LOG-PROFILE-COMPACT-1 -logCompact ENABLED

2 Done
3 add lsn client LSN-NAT64-CLIENT-1
4 Done
5 bind lsn client LSN-NAT64-CLIENT-1 -network6 2001:DB8:5001::/96
6 Done
7 add lsn pool LSN-NAT64-POOL-1
8 Done
9 bind lsn pool LSN-NAT64-POOL-1 203.0.113.61 - 203.0.113.70
10 Done
11 add lsn ip6profile LSN-NAT64-PROFILE-1 -type NAT64 -natprefix 2001:DB8
:300::/96
12 Done
13 add lsn group LSN-NAT64-PROFILE-1 -clientname LSN-NAT64-CLIENT-1  -
ip6profile LSN-NAT64-PROFILE-1
14 Done
15 bind lsn group LSN-NAT64-GROUP-1 -poolname LSN-NAT64-POOL-1
16 Done
17 bind lsn group LSN-NAT64-GROUP-1 ‒ logProfileName LOG-PROFILE-COMPACT-1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 430

NetScaler 12.0

18 Done

Logging HTTP Header Information

The NetScaler appliance can log request header information of an HTTP connection that is using
the NetScaler large scale NAT64 functionality. The following header information of an HTTP request
packet can be logged:

• URL that the HTTP request is destined to

• HTTP Method specified in the HTTP request
• HTTP version used in the HTTP request
• IPv6 address of the subscriber that sent the HTTP request

The HTTP header logs can be used by ISPs to see the trends related to the HTTP protocol among a set
of subscribers. For example, an ISP can use this feature to find out the most popular website among
a set of subscribers.

Configuration Steps

Perform the following tasks for configuring the NetScaler appliance to log HTTP header information:

• Create an HTTP header log profile. An HTTP header log profile is a collection of HTTP header
attributes (for example, URL and HTTP method) that can be enabled or disabled for logging.
• Bind the HTTP header to an LSN group of a large scale NAT64 configuration. Bind the HTTP
header log profile to an LSN group of an LSN configuration by setting the HTTP header log profile
name parameter to the name of the created HTTP header log profile. The NetScaler appliance
then logs HTTP header information of any HTTP requests related to the LSN group. An HTTP
header log profile can be bound to multiple LSN groups, but an LSN group can have only one
HTTP header log profile.

To create an HTTP header log profile by using the the command line interface

At the command prompt, type:

1 add lsn httphdrlogprofile <httphdrlogprofilename> [-logURL ( ENABLED |

DISABLED )] [-logMethod ( ENABLED | DISABLED )] [-logVersion (
ENABLED | DISABLED )] [-logHost ( ENABLED | DISABLED )]
2
3 show lsn httphdrlogprofile

© 1999-2018 Citrix Systems, Inc. All rights reserved. 431

NetScaler 12.0

To bind an HTTP header log profile to an LSN group by using the the command line interface

At the command prompt, type:

1 bind lsn group <groupname> -httphdrlogprofilename <string>

2
3 show lsn group <groupname>

Sample Configuration

1 add lsn httphdrlogprofile HTTP-HEADER-LOG-1

2 Done
3 add lsn client LSN-NAT64-CLIENT-1 Done
4 Done
5 bind lsn client LSN-NAT64-CLIENT-1 -network6 2001:DB8:5001::/96
6 Done
7 add lsn pool LSN-NAT64-POOL-1
8 Done
9 bind lsn pool LSN-NAT64-POOL-1 203.0.113.61 - 203.0.113.70
10 Done
11 add lsn ip6profile LSN-NAT64-PROFILE-1 -type NAT64 -natprefix 2001:DB8
:300::/96
12 Done
13 add lsn group LSN-NAT64-GROUP-1 -clientname LSN-NAT64-CLIENT-1  -
ip6profile LSN-NAT64-PROFILE-1
14 Done
15 bind lsn group LSN-NAT64-GROUP-1 -poolname LSN-NAT64-POOL-1
16 Done
17 bind lsn group LSN-NAT64-GROUP-1 -httphdrlogprofilename HTTP-HEADER-LOG
-1
18 Done

Displaying Current Large Scale NAT64 Sessions

You can display the current large scale NAT64 sessions in order to detect any unwanted or inefficient
sessions on the NetScaler appliance. You can display all or some large scale NAT64 sessions on the
basis of selection parameters.

Note

When more than a million large scale NAT64 sessions exist on the NetScaler appliance, Citrix rec-
ommends using the selection parameters to display selected large scale NAT64 sessions instead

© 1999-2018 Citrix Systems, Inc. All rights reserved. 432

NetScaler 12.0

of displaying all of them.

To display all large scale NAT64 sessions by using the command line interface

At the command prompt, type:

1 show lsn session ‒ nattype NAT64

To display selective large scale NAT64 sessions by using the command line interface

At the command prompt, type:

1 show lsn session ‒ nattype NAT64 [-network6 <ipv6_addr|*>] [-clientname

<string>] [-natIP <ip_addr> [-natPort <port>]]

Displaying Large Scale NAT64 Statistics

You can display statistics related to large scale NAT64 module, and evaluate its performance or trou-
bleshoot problems. You can display a summary of statistics of all large scale NAT64 configurations
or of a particular large scale NAT64 configuration. The statistical counters reflect events since the
NetScaler appliance was last restarted. All these counters are reset to 0 when the NetScaler appliance
is restarted.

To display total statistics of large scale NAT64 by using the command line interface

At the command prompt, type:

1 stat lsn nat64

To display statistics for a specified large scale NAT64 configuration by using the command line
interface

At the command prompt, type:

1 stat lsn group <groupname>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 433

NetScaler 12.0

Clearing Large Scale NAT64 Sessions

You can remove any unwanted or inefficient large scale NAT64 sessions from the NetScaler appliance.
The appliance immediately releases resources (such as NAT IP address, port, and memory) allocated
for these sessions, making the resources available for new sessions. The appliance also drops all the
subsequent packets related to these removed sessions. You can remove all or selected large scale
NAT64 sessions from the NetScaler appliance.

To clear all large scale NAT64 sessions by using the command line interface

At the command prompt, type:

1 flush lsn session  ‒ nattype NAT64

2
3 show lsn session  ‒ nattype NAT64

To clear selective large scale NAT64 sessions by using the command line interface

At the command prompt, type:

1 flush lsn session  ‒ nattype NAT64 [-network6 <ipv6_addr|*>] [-

clientname <string>] [-natIP <ip_addr> [-natPort <port>]]
2
3 show lsn session  ‒ nattype NAT64 [-network6 <ipv6_addr|*>] [-clientname
<string>] [-natIP <ip_addr> [-natPort <port>]]

Sample configuration:

Clear all large scale NAT64 sessions existing on a NetScaler appliance

1 flush lsn session  ‒ nattype NAT64

2 Done  

Clear all large scale NAT64 sessions related to client entity LSN-NAT64-CLIENT-1

1 flush lsn session ‒ nattype NAT64 -clientname LSN-NAT64-CLIENT-1

2 Done  

Clear all large scale NAT64 sessions related to a subscriber network (2001:DB8:5001::/96) of LSN client
entity LSN-NAT64-CLIENT-2

1 flush lsn session ‒ nattype NAT64 ‒ network6 2001:DB8:5001::/96 -

clientname LSN-NAT64-CLIENT-2

© 1999-2018 Citrix Systems, Inc. All rights reserved. 434

NetScaler 12.0

2 Done

IPFIX Logging

The NetScaler appliance supports sending information about LSN events in Internet Protocol Flow
Information Export (IPFIX) format to the configured set of IPFIX collector(s). The appliance uses the
existing AppFlow feature to send LSN events in IPFIX format to the IPFIX collectors.
IPFIX based logging is available for the following NAT64 related events:
• Creation or deletion of an LSN session.
• Creation or deletion of an LSN mapping entry.
• Allocation or de-allocation of port blocks in the context of deterministic NAT.
• Allocation or de-allocation of port blocks in the context of dynamic NAT.
• Whenever subscriber session quota is exceeded.

Points to Consider before you Configure IPFIX logging

Before you start configuring IPSec ALG, consider the following points:
• You must configure the AppFlow feature and IPFIX collector(s) on the NetScaler appliance. For
instructions, see Configuring the AppFlow feature.

Configuration Steps

Perform the following tasks for logging LSN information in IPFIX format:
• Enable LSN logging in the AppFlow configuration. Enable the LSN logging parameter as part
of AppFlow configuration.
• Create an LSN log profile. An LSN log profile includes the IPFIX parameter that enables or dis-
ables the log information in IPFIX format.
• Bind the LSN log profile to an LSN group of an LSN configuration. Bind the LSN log profile
to one or multiple LSN group(s). Events related to the bound LSN group will be logged in IPFIX
format.

To enable LSN logging in the AppFlow configuration by using the CLI

At the command prompt, type:

1 set appflow param -lsnLogging ( ENABLED | DISABLED )

2
3 show appflow param

© 1999-2018 Citrix Systems, Inc. All rights reserved. 435

NetScaler 12.0

To create an LSN log profile by using the CLIAt the command prompt, type

At the command prompt, type:

1 set lsn logprofile <logProfileName>  -logipfix ( ENABLED | DISABLED )

2
3 show lsn logprofile

To bind the LSN log profile to an LSN group of an LSN configuration by using the CLI

At the command prompt, type:

1 bind lsn group <groupname>  -logProfileName <lsnlogprofilename>

2
3 show lsn group

To create an LSN log profile by using the GUI

Navigate to System > Large Scale NAT > Profiles, click Log tab, and then add a log profile.

To bind the LSN log profile to an LSN group of an LSN configuration by using the GUI

1. Navigate to System > Large Scale NAT > LSN Group, open the LSN group.
2. In Advanced Settings, click + Log Profile to bind the created Log profile to the LSN group.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Port Control Protocol for Large Scale NAT64

September 17, 2018

Contributed by:
C

NetScaler appliances now support Port Control Protocol (PCP) for large scale NAT (LSN). Many of an
ISP’s subscriber applications must be accessible from Internet (for example, Internet of Things (IOT)
devices, such as an IP camera that provides surveillance over the Internet). One way to meet this

© 1999-2018 Citrix Systems, Inc. All rights reserved. 436

NetScaler 12.0

requirement is to create static large scale NAT (LSN) maps. But for a very large number of subscribers,
creating static LSN NAT maps is not a feasible solution.

Port Control Protocol (PCP) enables a subscriber to request specific LSN NAT mappings for itself
and/or for other 3rd party devices. The large scale NAT device creates an LSN map and sends it to the
subscriber. The subscriber sends the remote devices on the Internet the NAT IP address:NAT port at
which they can connect to the subscriber.

Applications usually send frequent keep-alive messages to the large scale NAT device so that their LSN
mappings do not time out. PCP helps reduce the frequency of such keep-alive messages by enabling
the applications to learn the timeout settings of the LSN mappings. This helps reduce bandwidth
consumption on the ISP’s access network and battery consumption on mobile devices.

PCP is a client-server model and runs over the UDP transport protocol. A NetScaler appliance imple-
ments the PCP server component and is compliant with RFC 6887.

Configuration Steps

Perform the following tasks for configuring PCP:

• (Optional) Create a PCP profile. A PCP profile includes settings for PCP related parameters
(for example, to listen for mapping and peer PCP requests). A PCP profile can be bound to a PCP
server. A PCP profile bound to a PCP server applies all its settings to the PCP server. A PCP profile
can be bound to multiple PCP servers. By default, one PCP profile with default parameters
settings is bound to all PCP servers. A PCP profile that you bind to a PCP server overrides the
default PCP profile settings for that server. A default PCP profile has the following parameter
settings:
– Mapping: Enabled
– Peer: Enabled
– Minimum map life: 120 seconds
– Maximum max life: 86400 seconds
– Announce count: 10
– Third Party: Disabled
• Create a PCP server and bind a PCP profile to it. Create a PCP server on the NetScaler appli-
ance to listen for PCP related requests and messages from the subscribers. A Subnet IP (SNIP)
or (SNIP6) address must be assigned to a PCP server to access it. By default, a PCP server listens
on port 5351.
• Bind the PCP server to an LSN group of an LSN configuration. Bind the created PCP server to
an LSN group of an LSN configuration by setting the PCP Server parameter to specify the created
PCP server. The created PCP server can be accessed only by the subscribers of this LSN group.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 437

NetScaler 12.0

Note

A PCP server for a large scale NAT configuration does not serve requests from subscribers that
are identified from ACL rules.

To create a PCP profile by using the CLI

At the command prompt, type:

1 add pcp profile <name> [-mapping ( ENABLED | DISABLED )] [-peer (

ENABLED | DISABLED )] [-minMapLife <secs>]  [-maxMapLife <secs>] [-
announceMultiCount <positive_integer>][-thirdParty ( ENABLED |
DISABLED )]
2
3 show pcp profile <name>

To create a PCP server by using the CLI

At the command prompt, type:

1 add pcp server <name> <IPAddress> [-port <portNum|*>] [-pcpProfile <

string>]
2
3 show pcp server <name>

Sample Configuration for NAT64

In the following sample configuration, PCP server PCP-SERVER-1, with PCP settings from PCP-
PROFILE-1,is bound to LSN group LSN-NAT64-GROUP-1. PCP-SERVER-1 serves PCP requests from IPv6
subscribers in network 2001:DB8:5001::/96.

Sample configuration:

1 add pcp profile PCP-PROFILE-1 -minMapLife 400

2 Done
3 add pcp server PCP-SERVER-1 2001:DB8:6001::90  -pcpProfile PCP-PROFILE
-1
4 Done
5 add lsn client LSN-NAT64-CLIENT-1
6 Done
7 bind lsn client LSN-NAT64-CLIENT-1 -network6 2001:DB8:5001::/96
8 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 438

NetScaler 12.0

9 add lsn pool LSN-NAT64-POOL-1

10 Done
11 bind lsn pool LSN-NAT64-POOL-1 203.0.113.61 - 203.0.113.70
12 Done
13 add lsn ip6profile LSN-NAT64-PROFILE-1 -type NAT64 -natprefix 2001:DB8
:300::/96
14 Done
15 add lsn group LSN-NAT64-PROFILE-1 -clientname LSN-NAT64-CLIENT-1  -
ip6profile LSN-NAT64-PROFILE-1
16 Done
17 bind lsn group LSN-NAT64-GROUP-1 -poolname LSN-NAT64-POOL-1
18 Done
19 bind lsn group LSN-NAT64-GROUP-1 ‒ pcpServer PCP-NAT64-SERVER-1
20 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Mapping Address and Port using Translation

September 17, 2018

Contributed by:
C

Mapping Address and Port using Translation (MAP-T) is an IPv6 transition solution for ISPs with IPv6
infrastructure to connect their IPv4 subscribers to the IPv4 internet_.MAP-T is built on
stateless IPv4 and IPv6 address translation technologies. MAP-T is a mechanism that performs double
translation (IPv4 to IPv6 and vice versa) on customer edge (CE) devices and border routers (in ISP core
network).

In a MAP-T deployment, the CE device implements a combination of stateful NAPT44 translation and
stateless NAT46 translation. The CE device obtains NAT-IP and the port-block to be used for translation
through DHCPv6 or any other method.

When an IPv4 packet from a subscriber device arrives at the CE device, the CE device performs NAPT44
and stores the NAPT44 binding information. After NAT44 translation, the packet is subjected to NAT46
translation and then forwarded to the border router (BR) device located in the ISP’s core network. The
BR device receives the IPv6 packets from the CE device, extracts and validates the NAT-IP and port-
block embedded in the IPv6 header, and forwards the IPv4 packet to the IPv4 Internet. When the BR

© 1999-2018 Citrix Systems, Inc. All rights reserved. 439

NetScaler 12.0

receives the IPv4 packet from the Internet, it translates the IPv4 packet to an IPv6 packet and send the
IPv6 packet to the CE device.

MAP-T is stateless on a BR device, so it does not require the BR device to perform NAT on the traffic. In-
stead, NAT functionality is delegated to the CE devices. This delegation and stateless functionality in
BR devices allows the BR deployment to scale in proportion to the volume of traffic.

The NetScaler appliance implements the BR functionality of a MAP-T solution as described by RFC
7599.

Configuring MAP-T

Configuring MAP-T on a NetScaler appliance consists of the following tasks:

• Add a default mapping rule

• Add a basic mapping rule
• Bind an IPv4 NAT address range of CE devices to a basic mapping rule
• Add a map domain and bind a basic mapping rule and default mapping rule to the domain

To add a default mapping rule by using the CLI

At the command prompt, type:

1 add MapDmr <name> -BRIpv6Prefix ( <ipv6_addr> | <*> )

2
3 show MapDmr <name>

To add a basic mapping rule by using the CLI

At the command prompt, type:

1 add MapBmr <name> -RuleIpv6Prefix <ipv6_addr> | <*>  [-psidoffset <

positive_integer>] [-EAbitLength <positive_integer>]  [-psidlength <
positive_integer>]
2
3 show MapBmr <name>

To bind IPv4 NAT address range of CE devices to a basic mapping rule by using the CLI

At the command prompt, type:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 440

NetScaler 12.0

1 bind MapBmr <name> (-network <ip_addr>  [-netmask <netmask>])

2
3 show MapBmr <name>

To add a map domain by using the CLI

At the command prompt, type:

1 add MapDomain <name> -MapDmrName <string>

2
3 show MapDomain <name>

To bind a basic mapping rule to a map domain by using the CLI

At the command prompt, type:

1 bind MapDomain <name> -MapBmrName <string>

2
3 show MapDomain <name>

Sample configuration

1 add mapdmr DMR-1 -BRIpv6Prefix 2002:db8::/64

2
3 Done
4
5 add mapbmr BMR-1 -ruleIpv6Prefix 2002:db8:89ab::/48 -eAbitLength 16 -
psidlength 8 -psidoffset 6
6
7 Done
8
9 bind mapbmr BMR-1 -network 192.0.1.0 -netmask 255.255.255.0
10
11 Done
12
13 add MapDomain MAP-DOMAIN-1 -mapdmrname DMR-1
14
15 Done
16
17 bind MapDomain MAP-DOMAIN-1 -mapbmrname BMR-1
18 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 441

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Telco subscriber management

January 6, 2019

Contributed by:
C

The number of subscribers in a telco network is increasing at an unprecedented rate, and managing
them is becoming a challenge for service providers. Newer, faster, and smarter devices are placing
high demand on the network and the subscriber management systems. It is no longer feasible to
provide each subscriber the same standard of service, and the need for traffic processing on a per-
subscriber basis is imperative.

The NetScaler appliance provides the intelligence to profile subscribers on the basis of their informa-
tion stored in the Policy and Charging Rules Function (PCRF). When a mobile subscriber connects to
the Internet, the packet gateway associates an IP address with the subscriber and forwards the data
packet to the appliance. The appliance receives the subscriber information dynamically, or you can
configure static subscribers. This information enables the appliance to apply its rich traffic manage-
ment capabilities, such as content switching, integrated caching, rewrite, and responder, on a per-
subscriber basis to manage the traffic.

Before you configure the NetScaler appliance to manage subscribers, you must allocate memory to
the module that stores subscriber sessions. For dynamic subscribers, you must configure an interface
through which the appliance receives session information. Static subscribers must be assigned IDs,
and you can associate them with policies.

You can also do the following:

• Subscriber policy enforcement and management.

• Configure the appliance to uniquely identify a subscriber by using only the IPv6 prefix instead
of the complete IPv6 address.
• Use policies to optimize TCP traffic for both dynamic and static subscribers. These policies as-
sociate different TCP profiles with different types of users.
• Manage idle sessions on a NetScaler appliance.
• Enable logging to a log server.
• Remove LSN sessions for deleted subscriber sessions.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 442

NetScaler 12.0

Allocating memory for the subscriber session store module

Each subscriber session entry consumes 1 KB of memory. Storing 500,000 subscriber sessions at any
point in time requires 500 MB of memory. This value must be added to the minimum memory require-
ment, which is shown as part of the output of the “show extendedmemoryparam” command. In the
following example, the output is for a NetScaler VPX instance with 3 packet engines and 8 GB memory.

To store 500,000 subscriber sessions on this appliance, the configured memory must be 2058+500 MB
(500,000 x 1 KB = 500 MB.)
Note

The configured memory must be in multiples of 2 MB and must not exceed the maximum memory
usage limit. The appliance must be restarted for the changes to take effect.

Example

1 show extendedmemoryparam
2       Extended Memory Global Configuration. This memory is utilized by
LSN and Subscriber Session Store Modules:
3         Active Memory Usage: 0 MBytes
4         Configured Memory Limit: 0 MBytes
5         Minimum Memory Required: 2058 MBytes
6         Maximum Memory Usage Limit: 2606 MBytes
7 Done
8 set extendedmemoryparam -memLimit 2558
9 Done
10 show extendedmemoryparam
11         Extended Memory Global Configuration. This memory is
utilized by LSN and Subscriber Session Store Modules:
12
13         Active Memory Usage: 2558 MBytes
14         Configured Memory Limit: 2558 MBytes
15         Minimum Memory Required: 2058 MBytes
16         Maximum Memory Usage Limit: 2606 MBytes
17 Done

Configure an interface for dynamic subscribers

The NetScaler appliance dynamically receives the subscriber information through any of the following
types of interface:

• Gx Interface

© 1999-2018 Citrix Systems, Inc. All rights reserved. 443

NetScaler 12.0

• RADIUS Interface
• RADIUS and Gx Interface
Note

• Starting with NetScaler release 12.0 build 57.19, Gx interface is supported for a cluster de-
ployment. For more information see Gx interface in a cluster topology.

• In an HA setup, the subscriber sessions are continually synchronized on the secondary

node. In the event of a failover, the subscriber information is still available on the
secondary node.

Gx interface

A Gx interface (as specified in 3GPP 29.212) is a standard interface based on the Diameter protocol
that allows exchange of policy control and charging rules between a PCRF and a Policy and Charging
Enforcement Function (PCEF) entity in a Telco network.

As soon as an IP-CAN session is established, the packet gateway forwards the subscriber ID, such as
the MSISDN, and Framed-IP address information about the subscriber to the PCRF as a Diameter mes-
sage. When the data packet arrives at the appliance from packet gateway (PGW), the appliance uses
the subscriber IP address to query the PCRF to get the subscriber information. This is also known as
secondary PCEF functionality.

The Policy and Charging Control (PCC) rules received by the appliance over the Gx interface are stored
on the appliance for the duration of the subscriber session, that is, until the PCRF sends a Re-Auth-
Request (RAR) message with a Session-Release-Cause AVP or the subscriber session is terminated
from the CLI or the configuration utility. If there are any updates to an existing subscriber, the PCRF
sends the updates in an RAR message. A subscriber session is initiated when a subscriber logs on to
the network, and terminated when the subscriber logs off.

The following illustration shows the high-level traffic flow. It assumes that the data plane traffic is
HTTP. The appliance sends a Credit Control Request (CCR) over a Gx interface to the PCRF server and,
in the credit control answer (CCA), receives the PCC rules and, optionally, other information, such as
the Radio Access Technology (RAT) type, that applies to the particular subscriber. PCC rules include
one or more policy (rule) names and other parameters. The appliance uses this information to retrieve
the predefined rules stored on the appliance, and to direct the flow of traffic. It also stores this informa-
tion in the subscriber policy and enforcement management system for the duration of the subscriber
session. After a subscriber session is terminated, the appliance discards all the information about the
subscriber.

The following example shows the commands for configuring a Gx interface. The commands are in
boldface.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 444

NetScaler 12.0

To set up a Gx interface, perform the following tasks

Add a DIAMETER service for each Gx interface. For example:

1 add service pcrf-svc1 203.0.113.1 DIAMETER 3868

2
3 add service pcrf-svc2 203.0.113.2 DIAMETER 3868

Add a non-addressable DIAMETER load balancing virtual sever and bind the services created in step
1 to this virtual server. For more than one service, specify a persistenceType and the persistAVPno so
that specific sessions are handled by the same PCRF server. For example:

1 add lb vserver vdiam DIAMETER 0.0.0.0 0 -persistenceType DIAMETER -

persistAVPno 263
2
3 bind lb vserver vdiam pcrf-svc1
4
5 bind lb vserver vdiam pcrf-svc2

Configure NetScaler diameter identity and realm. Identity and realm are used as Origin-Host and
Origin-Realm AVPs in diameter messages sent by the Gx client. For example:

1 set ns diameter ‒ identity netscaler.com ‒ realm com

Configure the Gx interface to use the virtual server created in step 2 as the PCRF virtual server. Specify
the PCRF realm to use as Destination-Realm AVP in diameters messages sent by the Gx client. For
example:

1 set subscriber gxInterface -vServer vdiam -pcrfRealm pcrf.com

Set the subscriber interface type to GxOnly. For example:

1 set subscriber param -interfaceType GxOnly

To see the Gx interface configuration and status, type:

1 show subscriber gxinterface

Example

1 show subscriber gxinterface

2 Gx Interface parameters:
3     PCRF Vserver: vdiam (UP)
4     Gx Client Identity...:  netscaler.com

© 1999-2018 Citrix Systems, Inc. All rights reserved. 445

NetScaler 12.0

5     Gx Client Realm ..........:  com

6     PCRF Realm: pcrf.com
7     Hold Packets On Subscriber Absence: YES
8     CCR Request Timeout: 10 Seconds
9     CCR Request Retry Attempts: 3
10     RevalidationTimeout: 1200 Seconds
11     NegativeTTL: 120 Seconds
12     ServicePath AVP code:262099 ServicePath AVP VendorID: 3845
13     PCRF Connection State: Gx Connection Established with PCRF.
14 Done

ARGUMENTS

vServer

Name of the load balancing or content switching virtual server to which the Gx connections are estab-
lished. The service type of the virtual server must be DIAMETER or SSL_DIAMETER. This parameter is
mutually exclusive with the service parameter. Therefore, you cannot set both service and the virtual
server in the Gx interface.

Service

Name of DIAMETER or SSL_DIAMETER service corresponding to PCRF to which the Gx connection is

established. This parameter is mutually exclusive with the vserver parameter. Therefore, you cannot
set both service and the virtual server in the Gx Interface.

pcrfRealm

The realm of PCRF to which the message is to be routed. This is the realm used in Destination-Realm
AVP by NetScaler Gx client (as a Diameter node).

holdOnSubscriberAbsence

Set to Yes to hold packets until the subscriber session information is fetched from the PCRF server. If
set to No, the default subscriber profile is applied until the subscriber session information is fetched
from the PCRF server. If a default subscriber profile is not configured, an UNDEF is raised for expres-
sions that use subscriber attributes.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 446

NetScaler 12.0

requestTimeout

Time, in seconds, within which the Gx CCR request must complete. If the request does not complete
within this time, the request is retransmitted for the number of times specified in the requestRetry-
Attempts parameter. If request is not complete even after retransmitting, then the default subscriber
profile is applied to this subscriber. If a default subscriber profile is not configured, an UNDEF is raised
for expressions that use subscriber attributes. Zero disables the timeout. Default value: 10

requestRetryAttempts

Specify the number of times a request must be retransmitted if the request does not complete within
the value specified in the requestTimeout parameter. Default value: 3

revalidationTimeout

Time, in seconds, after which the Gx CCR-U request is sent after any PCRF activity on a session. Any
RAR or CCA message resets the timer. Zero value disables the idle timeout.

negativeTTL

Time, in seconds, after which the Gx CCR-I request is resent for sessions that have not been resolved
by PCRF because the server is down or there is no response or a failed response is received. Instead of
polling the PCRF server constantly, a negative-TTL makes the appliance hold on to an unresolved ses-
sion. For negative sessions, the appliance inherits the attributes from the default subscriber profile,
if one is configured and from the RADIUS accounting message, if one is received. Zero value disables
the negative sessions. The appliance does not install negative sessions even if a subscriber session
could not be fetched. Default value: 600

servicePathAVP

The AVP code in which PCRF sends the service path applicable to a subscriber.

servicePathVendorid

The vendor id of the AVP in which PCRF sends the service path applicable to a subscriber.

To configure Gx interface by using the GUI

1. Navigate to Traffic Management > Subscriber > Parameters.

2. Click Configure Subscriber Parameters.
3. In Interface Type, select GxOnly.
4. Specify the values for the all required parameters.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 447

NetScaler 12.0

5. Click OK.

Gx interface in a cluster topology

The NetScaler appliance supports Gx interface in a cluster topology.

The NetScaler nodes in the cluster communicate with an external PCRF server through the Gx inter-
face. When a node receives client traffic, the appliance performs the following:

• Sends a CCR-I request to the PCRF server to fetch subscriber information.

• The PCRF server responds with a CCR-A.
• The NetScaler node then stores the received subscriber information in its subscriber store and
applies the rules to the client traffic.

Each node maintains an independent subscriber store and subscriber sessions are not synchronized
to other nodes.

As per the Diameter Base Protocol RFC 6733, each peer must be configured with a unique diameter
identity to communicate with other peers over the diameter protocol. Hence, in a cluster deployment,
configuration of diameter identity is spotted. The diameter parameters (identity, realm, server close
propagation) for each node can be configured individually by using the GUI or the CLI.

When a node is added to a cluster, it assumes the default diameter parameters (identity=netscaler.com,
realm=com, serverClosePropogation=NO). After the nodes are added, the diameter parameters for
each node must be configured.

To configure the diameter parameters by using the GUI

1. Navigate to System > Settings.

2. In the details pane, click Change Diameter Parameters.
3. In the Diameter Parameters page, select the NetScaler node for which you want to configure the
diameter parameters and then click Configure.
4. In the Configure Diameter Parameters page, configure the diameter Identity, diameter Realm,
and server Close Propagation for the selected node.
5. Click OK.

To configure the diameter parameters by using the CLI

At the command prompt, type:

1 set ns diameter [-identity <string>] [-ownerNode <positive_integer>]

ARGUMENTS

© 1999-2018 Citrix Systems, Inc. All rights reserved. 448

NetScaler 12.0

Identity

Diameter Identity is used to identify a Diameter node uniquely. Before setting up diameter configu-
ration, the NetScaler appliance (as a Diameter node) must be assigned a unique diameter identity.

For example, set ns diameter -identity netscaler.com -ownerNode 1. So, whenever NetScaler system
needs to use identity in diameter messages, it uses ‘netscaler.com’ as Origin-Host AVP as defined in
RFC3588.

Maximum Length: 255

OwnerNode

OwnerNode represents the ID of the cluster node for which the diameter ID is set. OwnerNode can
be configured only through CLIP.

Minimum value: 0

Maximum value: 31

Example:

set ns diameter -identity netscaler1.com -ownerNode 1

Note:

The OwnerNode option is also added to the show ns diameter command.

Example:

1 show diameter -ownerNode <0-31>

When the show ns diameter command is executed, it displays the diameter parameters for a given
node.

To configure a Gx interface for cluster deployment

To set up a Gx interface, perform the following tasks:

Add a DIAMETER service for each Gx interface.

Example:

1 add service pcrf-svc1 203.0.113.1 DIAMETER 3868

2 add service pcrf-svc2 203.0.113.2 DIAMETER 3868

Add a DIAMETER load balancing virtual sever and bind the services created in step 1 to this virtual
server.

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 449

NetScaler 12.0

1 add lb vserver vdiam DIAMETER 0.0.0.0 0 -persistenceType DIAMETER -

persistAVPno 263
2
3 bind lb vserver vdiam pcrf-svc1
4
5 bind lb vserver vdiam pcrf-svc2

Configure NetScaler diameter identity and realm on all the cluster nodes. Identity and realm are used
as Origin-Host and Origin-Realm AVPs in diameter messages sent by the Gx client.

Example:

1 set ns diameter -identity node0.netscaler.com -realm netscaler.com -

ownerNode 0
2
3 set ns diameter -identity node1.netscaler.com -realm netscaler.com -
ownerNode 1

Configure the Gx interface to use the virtual server created in step 2 as the PCRF virtual server and set
the PCRF realm as well.

Example:

1 set subscriber gxInterface -vServer vdiam -pcrfRealm pcrf.com

2
3 Set the subscriber interface type to GxOnly.

Example:

1 set subscriber param -interfaceType GxOnly

To see the Gx interface configuration and status, type:

1 show subscriber gxinterface

RADIUS interface

With a RADIUS interface, the packet gateway forwards the subscriber information in a RADIUS Account-
ing Start message to the appliance through the RADIUS interface as soon as an IP-CAN session is estab-
lished. A service of type RADIUSListener processes RADIUS Accounting messages. Add a shared secret
for the RADIUS client. If a shared secret is not configured, the RADIUS message is silently dropped. The
following example shows the commands for configuring a RADIUS interface. The commands are in
boldface.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 450

NetScaler 12.0

To set up a RADIUS interface, perform the following tasks:

Create a RADIUS listener service at the SNIP address where the RADIUS messages are received. For
example:

1 add service srad1 192.0.0.206 RADIUSLISTENER 1813

Configure the subscriber RADIUS interface to use this service. For example:

1 set subscriber radiusInterface -listeningService srad1

Set the subscriber interface type to RadiusOnly. For example:

1 set subscriber param -interfaceType RadiusOnly

Add a RADIUS client specifying a subnet and shared secret. For example:

1 add radius client 192.0.2.0/24 -radkey client123

A subnet of 0.0.0.0/0 implies that it is the default shared secret for all clients.To see the RADIUS inter-
face configuration and status, type:

1 show subscriber radiusInterface

RADIUS Interface parameters:

Radius Listener Service: srad1(UP)
Done
Example:

1 add service pcrf-svc1 203.0.113.1 DIAMETER 3868

2
3 add service pcrf-svc2 203.0.113.2 DIAMETER 3868

ARGUMENTS

ListeningService
Name of the RADIUS listening service that will process the RADIUS accounting requests.

svrState
The state of the RADIUS listening service.
The following illustration shows the high-level traffic flow.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 451

NetScaler 12.0

To configure RadiusOnly interface by using the GUI

1. Navigate to Traffic Management > Subscriber > Parameters.
2. Click Configure Subscriber Parameters.
3. In Interface Type, select RadiusOnly.
4. Specify the values for the all required parameters.
5. Click OK.

RADIUS and Gx interface

With a RADIUS and Gx interface, as soon as an IP-CAN session is established, the packet gateway for-
wards the subscriber ID, such as the MSISDN, and Framed-IP address information about the subscriber
to the appliance through the RADIUS interface. The appliance uses this subscriber ID to query the
PCRF on the Gx interface to get the subscriber information. This is known as primary PCEF function-
ality. The following example shows the commands for configuring a RADIUS and Gx interface.

1 set subscriber param -interfaceType RadiusandGx

2 add service pcrf-svc 203.0.113.1 DIAMETER 3868
3 add lb vserver vdiam DIAMETER 0.0.0.0 0 -persistenceType DIAMETER -
persistAVPno 263
4 bind lb vserver vdiam pcrf-svc
5 set subscriber gxInterface -vServer vdiam -pcrfRealm testrealm1.net -
holdOnSubscriberAbsence YES -revalidationTimeout 60 -negativeTTL 120
6 add service srad1 192.0.0.206 RADIUSLISTENER 1813 set subscriber
radiusInterface -listeningService srad1

The following illustration shows the high-level traffic flow.

To configure RadiusAndGx interface by using the GUI

1. Navigate to Traffic Management > Subscriber > Parameters.
2. Click Configure Subscriber Parameters.
3. In Interface Type, select RadiusAndGx.
4. Specify the values for the all required parameters.
5. Click OK.

Configure static subscribers

You can configure the subscribers manually on the NetScaler appliance by using the command line
or the configuration utility. You create static subscribers by assigning a unique subscriber ID and op-
tionally associating a policy with each subscriber. The following examples show the commands for
configuring a static subscriber.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 452

NetScaler 12.0

In the following examples, subscriptionIdvalue specifies the international telephone number, and
subscriptionIdType (E164 in this example) specifies the general format for international telephone
numbers.

1 add subscriber profile 203.0.113.6 -subscriberRules policy1 policy2 -

subscriptionIdType E164 ‒ subscriptionIdvalue 98767543211
2 add subscriber profile 2002::a66:e8d3/64 -subscriberRules policy1
policy3 -subscriptionIdtype E164 ‒ subscriptionIdvalue 98767543212

To view the configured subscriber profiles, type:

show subscriber profile

1 > show subscriber profile

2 1)      Subscriber IP: 2002::/64
3         Profile Attributes:
4                 Active Rules: policy1, policy3
5                 Subscriber Id Type: E164
6                 Subscriber Id Value: 98767543212
7 2)      Subscriber IP: 203.0.113.6
8         Profile Attributes:
9                 Active Rules: policy1, policy2
10                 Subscriber Id Type: E164
11                 Subscriber Id Value: 98767543211
12  Done

Default subscriber profile

A default subscriber profile is used if the subscriber IP address is not found in the subscriber session
store on the appliance. In the following example, a default subscriber profile is added with the sub-
scriber rule policy1.

1 > add subscriber profile * -subscriberRules policy1

View and clear subscriber sessions

Use the following command to display all the static and dynamic subscriber sessions.

show subscriber sessions

1 > show subscriber sessions

2 1)      Subscriber IP: 2002::/64
3         Session Attributes:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 453

NetScaler 12.0

4                Active Rules: policy1, policy3

5                Subscriber Id Type: E164
6                Subscriber Id Value: 98767543212
72)      Subscriber IP: *
8        Session Attributes:
9                Active Rules: policy1
10 3)      Subscriber IP: 203.0.113.6
11        Session Attributes:
12                 Active Rules: policy1, policy2
13                 Subscriber Id Type: E164
14                 Subscriber Id Value: 98767543211
15 4)      Subscriber IP: 192.168.0.11
16         Session Attributes:
17                 Idle TTL remaining: 361 Seconds
18                 Active Rules: policy1
19                 Subscriber Id Type: E164
20                 Subscriber Id Value: 1234567811
21                 Service Path: policy1
22                 AVP(44): 34 44 32 42 42 38 41 43  2D 30 30 30 30 30 30
31 31
23                 AVP(257): 00 01 C0 A8 0A 02
24                 PCRF-Host: host.pcrf.com
25                 AVP(280): 74 65 73 74 2E 63 6F 6D
26 …
27 Done

Use the following command to clear a single session or the complete session store. If you do not
specify an IP address, the complete subscriber session store is cleared.

1 clear subscriber sessions <ip>

Subscriber policy enforcement & management system

The NetScaler appliance uses the subscriber’s IP address as the key to the subscriber policy enforce-
ment and management system.

You can add subscriber expressions to read the subscriber information available in the Subscriber
Policy Enforcement & Management System. These expressions can be used with policy rules and ac-
tions that are configured for NetScaler features, such as integrated caching, rewrite, responder, and
content switching.

The following commands are an example of adding a subscriber-based responder action and policy.
The policy evaluates to true if the subscriber rule value is“pol1”.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 454

NetScaler 12.0

1 add responder action error_msg respondwith ’”HTTP/1.1 403 OKrnrn” + ”

You are  not authorized to access Internet”’
2 add responder policy no_internet_access ”SUBSCRIBER.RULE_ACTIVE(”pol1”)
” error_msg

The following example shows the commands to add a subscriber-based rewrite action and policy.
The action inserts an HTTP header “X-Nokia-MSISDN” by using the value of AVP(45) in the subscriber
session.

1 > add rewrite action AddHDR-act insert_http_header X-Nokia-MSISDN ”

SUBSCRIBER.AVP(45).VALUE”
2 > add rewrite policy AddHDR-pol ”HTTP.REQ.HOSTNAME.APPEND(HTTP.REQ.URL)
.EQUALS_ANY(”patset-test”)” AddHDR-act

In the following example, two policies are configured on the appliance. When the appliance checks the
subscriber information and the subscriber rule is cache_enable, it performs caching. If the subscriber
rule is cache_disable, the appliance does not perform caching.

1 > add cache policy nocachepol -rule ”SUBSCRIBER.RULE_ACTIVE(”

cache_disable”)” - action NOCACHE
2 > add cache policy cachepol -rule ”SUBSCRIBER.RULE_ACTIVE(”cache_enable
”)” - action CACHE -storeInGroup cg1

For a complete list of expressions starting with “SUBSCRIBER.” see the Policy Configuration Guide.

IPv6 prefix based subscriber sessions

A telco user is generally identified by the IPv6 prefix rather than the complete IPv6 address. The
NetScaler appliance now uses the prefix instead of the complete IPv6 address (/128) to identify a sub-
scriber in the database (subscriber store). For communicating with the PCRF server (for example, in
a CCR-I message), the appliance now uses the framed-IPv6-Prefix AVP instead of the complete IPv6
address. The default prefix length is /64, but you can configure the appliance to use a different value.

To configure the IPv6 prefix by using the command line

set subscriber param [-ipv6PrefixLookupList ...]

The first example command below sets a single prefix and the second example command sets multiple
prefixes.

1 set subscriber param -ipv6PrefixLookupList 64

2 set subscriber param -ipv6PrefixLookupList 64 72 96

© 1999-2018 Citrix Systems, Inc. All rights reserved. 455

NetScaler 12.0

To configure the IPv6 prefix by using the configuration utility

1. Navigate to Traffic Management > Subscriber > Parameters.

2. In the details pane, under Settings, click Configure Subscriber Parameters and in IPv6 Prefix
Lookup List, specify one or more prefixes.

Idle session management of subscriber sessions in a Telco network

Subscriber session cleanup on a NetScaler appliance is based on control plane events, such as a RA-
DIUS Accounting Stop message, a Diameter RAR (session release) message, or a “clear subscriber ses-
sion” command. In some deployments, the messages from a RADIUS client or a PCRF server might
not reach the appliance. Additionally, during heavy traffic, the messages might be lost. A subscriber
session that is idle for a long time continues to consume memory and IP resources on the NetScaler ap-
pliance. The idle session management feature provides configurable timers to identify idle sessions,
and cleans up these sessions on the basis of the specified action.
A session is considered idle if no traffic from this subscriber is received on the data plane or the control
plane. You can specify an update, terminate (inform PCRF and then delete the session), or delete
(without informing PCRF) action. The action is taken only after the session is idle for the time specified
in the idle timeout parameter.

To configure the idle session timeout and the associated action by using the command line

1 set subscriber param [-idleTTL <positive_integer>] [-idleAction <

idleAction>]

Examples:

1 set subscriber param -idleTTL 3600 -idleAction ccrTerminate

2
3 set subscriber param -idleTTL 3600 -idleAction ccrUpdate
4
5 set subscriber param -idleTTL 3600 -idleAction delete

To disable the idle session timeout, set the idle timeout to zero.
set subscriber param –idleTTL 0

To configure the idle session timeout and the associated action by using the configuration
utility

1. Navigate to Traffic Management > Subscriber > Parameters.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 456

NetScaler 12.0

2. In the details pane, under Settings, click Configure Subscriber Parameters and specify an Idle
Time and Idle Action.

Subscriber session event logging

If you enable subscriber logging, you can track the RADIUS and Gx control plane messages specific to
a subscriber, and use the historical data to analyze subscriber activities. Some of the key attributes
are MSISDN and time stamp. The following attributes are also logged:

• Session Event (Install, Update, Delete, Error)

• Gx Message Type (CCR-I, CCR-U, CCR-T, RAR)
• Radius Message Type (Start, Stop)
• Subscriber IP
• SubscriberID Type (MSISDN(E164), IMSI)
• SubscriberID value

By using these logs, you can track users by IP address and, if available, MSISDN.

You can enable subscriber session logging to a local or remote syslog or nslog server. The following
example shows how to enable subscriber logging to a remote syslog server.

1 > add syslogAction sysact1 192.0.2.0 -loglevel EMERGENCY ALERT CRITICAL

ERROR WARNING NOTICE INFORMATIONAL -subscriberlog enabled

From these logs, you can learn about any activity related to a user, such as the time when a session
was updated, deleted, or created (installed). Additionally, error messages are also logged.

Examples:

1. The following log entries are examples of RADIUSandGx session creation, session update, and
session deletion.
09/30/2015:16:29:18 GMT Informational 0-PPE-0 : default SUBSCRIBER SESSION_EVENT
147 0 : Session Install, GX MsgType: CCR-I, RADIUS MsgType: Start, IP: 100.10.1.1, ID: E164 -
30000000001

09/30/2015:16:30:18 GMT Informational 0-PPE-0 : default SUBSCRIBER SESSION_EVENT

148 0 : Session Update, GX MsgType: CCR-U, IP: 100.10.1.1, ID: E164 - 30000000001

09/30/2015:17:27:56 GMT Informational 0-PPE-0 : default SUBSCRIBER SESSION_EVENT

185 0 : Session Delete, GX MsgType: CCR-T, RADIUS MsgType: Stop, IP: 100.10.1.1, ID: E164 -
30000000001

2. The following log entries are examples of failure messages, such as when a subscriber is not
found on the PCRF server and when the appliance cannot connect to the PCRF server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 457

NetScaler 12.0

09/30/2015:16:44:15 GMT Error 0-PPE-0 : default SUBSCRIBER SESSION_FAILURE 169 0

: Failure Reason: PCRF failure response, GX MsgType: CCR-I, IP: 100.10.1.1

Sep 30 13:03:01 09/30/2015:16:49:08 GMT 0-PPE-0 : default SUBSCRIBER SES-

SION_FAILURE 176 0 : Failure Reason: Unable to connect to PCRF, GX MsgType: CCR-I, RA-
DIUS MsgType: Start, IP: 100.10.1.1, ID: E164 - 30000000001#000#000#000#000#000#000#000#000#000#0

Subscriber aware LSN session termination

In earlier releases, if a subscriber session is deleted when a RADIUS Accounting STOP or a PCRF-RAR
message is received, or as a result of any other event, such as TTL expiry or flush, the corresponding
LSN sessions of the subscriber are removed only after the configured LSN timeout period. LSN ses-
sions that are kept open until this timeout expires continue to consume resources on the appliance.

From release 11.1, a new parameter (subscrSessionRemoval) is added. If this parameter is enabled,
and the subscriber information is deleted from the subscriber database, LSN sessions corresponding
to that subscriber are also removed. If this parameter is disabled, the subscriber sessions are timed
out as specified by the LSN timeout settings.

To configure subscriber aware LSN session termination by using the CLI

At the command prompt, type:

set lsn parameter -subscrSessionRemoval ( DISABLED )

ENABLED

1 > set lsn parameter -subscrSessionRemoval ENABLED

2 Done
3 > sh lsn parameter
4             LSN Global Configuration:
5
6             Active Memory Usage: 0 MBytes
7             Configured Memory Limit: 0 MBytes
8             Maximum Memory Usage Limit: 912 MBytes
9             Session synchronization: ENABLED
10             Subscriber aware session removal: ENABLED

To configure subscriber aware LSN session termination by using the GUI

1. Navigate to System > Large Scale NAT.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 458

NetScaler 12.0

2. In Getting started, click Set LSN Parameter.

3. Set the Subscriber Aware Session Removal parameter.

Troubleshooting

If your deployment is not working as expected, use the following commands to troubleshoot:

• show subscriber gxinterface

This command’s output can include the following error messages (shown here with suggested
responses):
– Gx Interface Not Configured-Use set subscriber param command to configure the correct
interface type.
– PCRF not configured-Configure a Diameter vServer or Service on GxInterface-Use the set
subscriber gx interface command to assign a Diameter virtual server or service to this in-
terface.
– PCRF is not ready-Check corresponding vserver/service for more details-Use the show LB
vserver or show service command to check the state of the service.
– NetScaler is waiting for CEA from PCRF-Capability negotiation between the PCRF and
NetScaler might be failing. This could be an intermittent state. If it persists, check the
DIAMETER settings on your PCRF server.
– Memory is not configured to store subscriber sessions. Please use ‘set extendedmem-
oryparam -memlimit <>’-Use the set extendedmemoryparam command to configure ex-
tended memory.

• show subscriber radiusinterface

If “Not Configured” is the output of this command, use the set subscriber radiusinterface com-
mand to specify a RADIUSListener service.

If subscriber logging is enabled, you can get more detailed information from the log files.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Subscriber aware traffic steering

January 6, 2019

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 459

NetScaler 12.0

Traffic steering directs subscriber traffic from one point to another. When a subscriber connects to
the network, the packet gateway associates an IP address with the subscriber and forwards the data
packet to the NetScaler appliance. The appliance communicates with the PCRF server over the Gx
interface to get the policy information. Depending on the policy information, the appliance performs
one of the following actions:

• Forward the data packet to another set of services (as shown in the following illustration).
• Drop the packet.
• Perform only Large Scale NAT (LSN), if LSN is configured on the appliance.

The values shown in the following figure are configured in the CLI procedure that follows the figure.
A content switching virtual server on the NetScaler appliance directs requests to the value added ser-
vices or skips them, depending on the defined rule, and then sends the packet out to the Internet after
performing LSN.

To configure traffic steering for the above deployment by using the CLI

Add the appliance’s subnet IP (SNIP) addresses.

Example:

1 add ns ip 192.168.10.1 255.255.255.0 -type snip

2
3 add ns ip 192.168.20.1 255.255.255.0 -type snip
4
5 add ns ip 100.100.100.1 255.0.0.0 -type snip
6
7 add ns ip 200.200.200.1 255.0.0.0 -type snip
8
9 add ns ip 100.1.1.1 255.0.0.0 -type snip
10
11 add ns ip 200.201.1.1 255.0.0.0 -type snip

Add the VLANs. VLANs help the appliance identify the source of the traffic. Bind the VLANs to the
interfaces and subnet IP addresses.

Example:

1 add vlan 10
2
3 add vlan 20
4
5 add vlan 100
6
7 add vlan 200

© 1999-2018 Citrix Systems, Inc. All rights reserved. 460

NetScaler 12.0

8
9 bind vlan 10 -ifnum 1/4 -tagged -IPAddress 192.168.10.1 255.255.255.0
10
11 bind vlan 20 -ifnum 1/4 -tagged -IPAddress 192.168.20.1 255.255.255.0
12
13 bind vlan 100 -ifnum 1/2 -tagged -IPAddress 100.1.1.1 255.0.0.0
14
15 bind vlan 200 -ifnum 1/3 -tagged -IPAddress 200.1.1.1 255.0.0.0

Specify the VLAN on which the subscriber traffic arrives on the appliance. Specify the service path
AVP that tells the appliance where to look for the service path name within the subscriber session.
For primary PCEF functionality, specify the interfaceType as RadiusAndGx.

Example:

1 set ns param -servicePathIngressVLAN 100

2
3 set subscriber gxinterface -servicepathAVP 1001 1005 -
servicepathVendorid 10415
4
5 set subscriber param -interfaceType RadiusAndGx

Configure a service and virtual server of type Diameter, and bind the service to the virtual server. Then,
specify the PCRF realm and subscriber Gx interface parameters. For primary PCEF functionality, con-
figure a RADIUS listener service and RADIUS interface.

Example:

1 add service sd1 10.102.232.200 DIAMETER 3868

2
3 add lb vserver vdiam DIAMETER 0.0.0.0 0 -persistenceType DIAMETER -
persistAVPno 263
4
5 bind lb vserver vdiam sd1
6
7 set ns diameter -identity netscaler.sc1.net -realm pcrf1.net
8
9 set subscriber gxInterface -vServer vdiam -pcrfRealm pcrf1.net -
holdOnSubscriberAbsence YES -idleTTL 1200 -negativeTTL 120
10
11 add service srad1 10.102.232.236 RADIUSListener 1813
12
13 set subscriber radiusInterface -listeningService srad1

Add service functions to associate a VAS with an ingress VLAN. Add a service path to define the chain,

© 1999-2018 Citrix Systems, Inc. All rights reserved. 461

NetScaler 12.0

that is, specify the VAS that the packet must be sent to and the order in which it must go to that VAS.
The service path name is usually sent by the PCRF. However, the service path of the default subscriber
profile (*) applies if any of the following is true:

• PCRF does not have the subscriber information.

• The subscriber information does not include this AVP.
• The appliance is unable to query the PCRF. For example, the service representing the PCRF is
DOWN.

The service path AVP that contains this name must already be configured as part of the global config-
uration. Bind the service function to the service path. The service index specifies the order in which
the VAS is added to the chain. The highest number (255) indicates the beginning of the chain.

Example:

1 add ns servicefunction SF1 -ingressVLAN 20

2
3 add ns servicepath pol1
4
5 bind ns servicepath pol1 -servicefunction SF1 -index 255
6
7 add subscriber profile * -subscriberrules default_path

Add the LSN configuration. That is, define the NAT pool and identify the clients for which the appliance
must perform LSN.

1 add lsn pool pool1

2
3 bind lsn pool pool1 200.201.1.1
4
5 add lsn client client1
6
7 bind lsn client client1 -network 100.0.0.0 -netmask 255.0.0.0
8
9 add lsn group group1 -clientname client1
10
11 bind lsn group group1 -poolname pool1

The appliance performs LSN by default. To override LSN, you must create a net profile with the over-
rideLsn parameter enabled, and bind this profile to all the load balancing virtual servers that are con-
figured for value added services (VASs).

Example:

1 add netprofile np1

2

© 1999-2018 Citrix Systems, Inc. All rights reserved. 462

NetScaler 12.0

3 set netprofile np1 -overrideLsn ENABLED

4
5 set lb vserver vs1 -netprofile np1

Configure the VAS on the appliance. This includes creating the services and virtual servers and then
binding the services to the virtual servers.

1 add service vas1 192.168.10.2 ANY 80 -usip YES

2
3 add service sint 200.10.1.10 ANY 80 -usip YES
4
5 add lb vserver vs1 ANY -m MAC -l2Conn ON
6
7 add lb vserver vint ANY -m MAC -l2Conn ON
8
9 bind lb vserver vs1 vas1
10
11 bind lb vserver vint sint

Add the content switching (CS) configuration. This includes virtual servers, policies, and their associ-
ated actions. The traffic arrives at the CS virtual server and is then redirected to the appropriate load
balancing virtual server. Define expressions that associate a virtual server with a service function.

Example:

1 add cs vserver cs1 ANY * 80 -l2Conn ON

2
3 add cs action csact1 -targetLBVserver vs1
4
5 add cs action csactint -targetLBVserver vint
6
7 add cs policy cspol1 -rule  SUBSCRIBER.SERVICEPATH.IS_NEXT(”SF1”) &&
SYS.VSERVER(”vs1”).STATE.EQ(UP)” -action csact1
8
9 bind cs vserver cs1 -policyName cspol1 -priority 110
10
11 bind cs vserver cs1 -lbvserver vint

To configure traffic steering on the appliance by using the GUI

1. Navigate to System> Network> IPs and add the subnet IP addresses.

2. Navigate to System > Network > VLANs and add VLANs, Bind the VLANs to the interfaces and
subnet IP addresses.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 463

NetScaler 12.0

3. Navigate to Traffic Management> Service Chaining> Configure Service Path Ingress VLAN
and specify an ingress VLAN.
4. Navigate to Traffic Management> Subscriber> Parameters> Configure Subscriber Parame-
ters and specify the following:
• Interface Type: Specify RadiusAndGx.
• Configure a diameter virtual server, PCRF realm, and the subscriber GX interface parame-
ters.
• Specify the RADIUS interface parameters.
5. Navigate to Traffic Management> Service Chaining> Service Function and add service func-
tions to associate a value-added service with an ingress VLAN.
6. Navigate to System> Network> Large Scale NAT. Click Pools and add a pool. Click Clients and
add a client. Click Groups and add a group and specify the client. Edit the group and bind the
pool to this group.
7. Navigate to System> Network> Net Profiles and add a net profile. Select Override LSN. Op-
tionally, navigate to System> Network> Settings> Configure Layer 3 Parameters and verify
that Override LSN is not selected.
8. Navigate to Traffic Management> Load Balancing> Virtual Servers and configure the virtual
servers and value-added services on the appliance. Bind the services and the net profile to the
virtual server.
9. Navigate to Traffic Management> Content Switching> Virtual Servers and configure a virtual
server, policy, and action. Specify the target load balancing virtual server.

To configure service chaining on the appliance by using the GUI

1. Navigate to System> Network> IPs and add the subnet IP addresses.

2. Navigate to System > Network > VLANs and add VLANs, Bind the VLANs to the interfaces and
subnet IP addresses.
3. Navigate to Traffic Management> Service Chaining> Configure Service Path Ingress VLAN
and specify an ingress VLAN.
4. Navigate to Traffic Management> Subscriber> Parameters> Configure Subscriber Parame-
ters and specify the following:
• Interface Type: Specify RadiusAndGx.
• Configure a diameter virtual server, PCRF realm, and the subscriber GX interface parame-
ters.
• Specify the RADIUS interface parameters.
5. Navigate to Traffic Management> Service Chaining> Service Function and add service func-
tions to associate a value-added service with an ingress VLAN.
6. Navigate to System> Network> Large Scale NAT. Click Pools and add a pool. Click Clients and
add a client. Click Groups and add a group and specify the client. Edit the group and bind the

© 1999-2018 Citrix Systems, Inc. All rights reserved. 464

NetScaler 12.0

pool to this group.

7. Navigate to System> Network> Net Profiles and add a net profile. Select Override LSN. Op-
tionally, navigate to System> Network> Settings> Configure Layer 3 Parameters and verify
that Override LSN is not selected.
8. Navigate to Traffic Management> Load Balancing> Virtual Servers and configure the virtual
servers and value-added services on the appliance. Bind the services and the net profile to the
virtual server.
9. Navigate to Traffic Management> Content Switching> Virtual Servers and configure a virtual
server, policy, and action. Specify the target load balancing virtual server.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Subscriber aware service chaining

January 6, 2019

Contributed by:
C

With the huge increase in the data traffic passing through telco networks, it is no longer feasible for
service providers to steer all the traffic through all the value added services (VAS). A service provider
should be able to optimize usage of VAS and intelligently steer traffic to improve the user experience.
For example, video optimization is not required for traffic that does not include a video. Moreover, if a
subscriber is connected to a 4G network, content can be streamed in high definition (HD), and video
optimization might not be needed. However, video optimization improves the experience for a user
in a 3G network. Similarly, caching provides a faster and better user experience and can be enabled
depending on the subscriber plan. Another example of VAS is parental control. If parents provide a
mobile handset to a minor child, they would like some kind of control over the websites that their
child visits.

To do the above and more, service providers must be able to provide value-added services on a per-
subscriber basis. In other words, entities in the service provider network must be capable of extracting
the subscriber information and intelligently steering the packet on the basis of this information.

Service chaining determines the set of services through which the traffic from a subscriber must pass
before going to the Internet. Instead of sending all the traffic to all the services, the NetScaler intel-
ligently routes all requests from a subscriber to a specific set of services on the basis of the policy
defined for that subscriber.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 465

NetScaler 12.0

The following figure shows the entities involved in service chaining. The values shown are configured
in the procedure that follows the figure. A content switching virtual server on the NetScaler appliance
directs requests to the value added services or skips them, depending on the defined rule, and then
sends the packet out to the Internet after performing LSN.

To configure service chaining for the above deployment by using the CLI

Add the appliance’s subnet IP (SNIP) addresses.

Example:

1 add ns ip 192.168.10.1 255.255.255.0 -type snip

2
3 add ns ip 192.168.20.1 255.255.255.0 -type snip
4
5 add ns ip 192.168.30.1 255.255.255.0 -type snip
6
7 add ns ip 192.168.40.1 255.255.255.0 -type snip
8
9 add ns ip 192.168.50.1 255.255.255.0 -type snip
10
11 add ns ip 192.168.60.1 255.255.255.0 -type snip
12
13 add ns ip 100.1.1.1 255.0.0.0 -type snip
14
15 add ns ip 200.201.1.1 255.0.0.0 -type snip

Add the VLANs. VLANs help the appliance identify the source of the traffic. Bind the VLANs to the
interfaces and subnet IP addresses. Add an ingress and an egress VLAN for each VAS.

Example:

1 add vlan 10
2
3 add vlan 20
4
5 add vlan 30
6
7 add vlan 40
8
9 add vlan 50
10
11 add vlan 60
12
13 add vlan 100

© 1999-2018 Citrix Systems, Inc. All rights reserved. 466

NetScaler 12.0

14
15 add vlan 200
16
17 bind vlan 10 -ifnum 1/4 -tagged -IPAddress 192.168.10.1 255.255.255.0
18
19 bind vlan 20 -ifnum 1/4 -tagged -IPAddress 192.168.20.1 255.255.255.0
20
21 bind vlan 20 -ifnum 1/4 -tagged -IPAddress 192.168.30.1 255.255.255.0
22
23 bind vlan 20 -ifnum 1/4 -tagged -IPAddress 192.168.40.1 255.255.255.0
24
25 bind vlan 20 -ifnum 1/4 -tagged -IPAddress 192.168.50.1 255.255.255.0
26
27 bind vlan 20 -ifnum 1/4 -tagged -IPAddress 192.168.60.1 255.255.255.0
28
29 bind vlan 100 -ifnum 1/2 -tagged -IPAddress 100.1.1.1 255.0.0.0
30
31 bind vlan 200 -ifnum 1/3 -tagged -IPAddress 200.201.1.1 255.0.0.0

Specify the VLAN on which the subscriber traffic arrives on the appliance. Specify the service path
AVP that tells the appliance where to look for the service path name within the subscriber session.
For primary PCEF functionality, specify the interfaceType as RadiusAndGx.

Example:

1 set ns param -servicePathIngressVLAN 100

2
3 set subscriber gxinterface -servicepathAVP 1001 1005 -
servicepathVendorid 10415
4
5 set subscriber param -interfaceType RadiusAndGx

Configure a service and virtual server of type Diameter, and bind the service to the virtual server. Then,
specify the PCRF realm and subscriber Gx interface parameters. For primary PCEF functionality, con-
figure a RADIUS listener service and RADIUS interface.

Example:

1 add service sd1 10.102.232.200 DIAMETER 3868

2
3 add lb vserver vdiam DIAMETER 0.0.0.0 0 -persistenceType DIAMETER -
persistAVPno 263
4
5 bind lb vserver vdiam sd1
6

© 1999-2018 Citrix Systems, Inc. All rights reserved. 467

NetScaler 12.0

7 set ns diameter -identity netscaler.sc1.net -realm pcrf1.net

8
9 set subscriber gxInterface -vServer vdiam -pcrfRealm pcrf1.net -
holdOnSubscriberAbsence YES -idleTTL 1200 -negativeTTL 120
10
11 add service srad1 10.102.232.236 RADIUSListener 1813
12
13 set subscriber radiusInterface -listeningService srad1

Add service functions to associate a VAS with an ingress VLAN. Add a service path to define the chain,
that is, specify the VAS that the packet must be sent to and the order in which it must go to that VAS.
The service path name is usually sent by the PCRF. However, the service path of the default subscriber
profile (*) applies if any of the following is true:

• PCRF does not have the subscriber information.

• The subscriber information does not include this AVP.
• The appliance is unable to query the PCRF. For example, the service representing the PCRF is
DOWN.

The service path AVP that contains this name must be configured as part of the global configuration
earlier. Bind the service function to the service path. The service index specifies the order in which the
VAS is added to the chain. The highest number (255) indicates the beginning of the chain.

Example:

1 add ns servicefunction SF1 -ingressVLAN 20

2
3 add ns servicefunction SF2 -ingressVLAN 40
4
5 add ns servicefunction SF3 -ingressVLAN 60
6
7 add ns servicepath pol1
8
9 bind ns servicepath pol1 -servicefunction SF1 -index 255
10
11 bind ns servicepath pol1 -servicefunction SF2 -index 254
12
13 bind ns servicepath pol1 -servicefunction SF3 -index 253
14
15 add ns servicepath pol2
16
17 bind ns servicepath pol2 -servicefunction SF2 -index 255
18
19 add ns servicepath pol3
20

© 1999-2018 Citrix Systems, Inc. All rights reserved. 468

NetScaler 12.0

21 bind ns servicepath pol3 -servicefunction SF1 -index 255

22
23 add subscriber profile * -subscriberrules default_path

Add the LSN configuration. That is, define the NAT pool and identify the clients for which the appliance
must perform LSN.

Example:

1 add lsn pool pool1

2
3 bind lsn pool pool1 200.201.1.1
4
5 add lsn client client1
6
7 bind lsn client client1 -network 100.0.0.0 -netmask 255.0.0.0
8
9 add lsn group group1 -clientname client1
10
11 bind lsn group group1 -poolname pool1

The appliance performs LSN by default. To override LSN, you must create a net profile with over-
rideLsn parameter enabled and bind this profile to all the load balancing virtual servers that are con-
figured for value added services (VASs).

Example:

1 add netprofile np1

2
3 set netprofile np1 -overrideLsn ENABLED
4
5 set lb vserver vs1 -netprofile np1

Configure the VAS on the appliance. This includes creating the services and virtual servers and then
binding the services to the virtual servers.

Example:

1 add service vas1 192.168.10.2 ANY 80 -usip YES

2
3 add service vas2 192.168.30.2 ANY 80 -usip YES
4
5 add service vas3 192.168.50.2 ANY 80 -usip YES
6
7 add service sint 200.10.1.10 ANY 80 -usip YES
8

© 1999-2018 Citrix Systems, Inc. All rights reserved. 469

NetScaler 12.0

9 add lb vserver vs1 ANY -m MAC -l2Conn ON

10
11 add lb vserver vs2 ANY -m MAC -l2Conn ON
12
13 add lb vserver vs3 ANY -m MAC -l2Conn ON
14
15 add lb vserver vint ANY -m MAC -l2Conn ON
16
17 bind lb vserver vs1 vas1
18
19 bind lb vserver vs2 vas2
20
21 bind lb vserver vs3 vas3
22
23 bind lb vserver vint sint

Add the content switching (CS) configuration. This includes virtual servers, policies, and their associ-
ated actions. The traffic arrives at the CS virtual server and is then redirected to the appropriate load
balancing virtual server. Define expressions that associate a virtual server with a service function.

Example:

1 add cs vserver cs1 ANY * 80 -l2Conn ON

2
3 add cs action csact1 -targetLBVserver vs1
4
5 add cs action csact2 -targetLBVserver vs2
6
7 add cs action csact3 -targetLBVserver vs3
8
9 add cs action csactint -targetLBVserver vint
10
11 add cs policy cspol1 -rule ”SUBSCRIBER.SERVICEPATH.IS_NEXT(”SF1”) &&
SYS.VSERVER(”vs1”).STATE.EQ(UP)” -action csact1
12
13 add cs policy cspol2 -rule ”SUBSCRIBER.SERVICEPATH.IS_NEXT(”SF2”) &&
SYS.VSERVER(”vs2”).STATE.EQ(UP)” -action csact2
14
15 add cs policy cspol3 -rule ”SUBSCRIBER.SERVICEPATH.IS_NEXT(”SF3”) &&
SYS.VSERVER(”vs3”).STATE.EQ(UP)” -action csact3
16
17 bind cs vserver cs1 -policyName cspol1 -priority 110
18
19 bind cs vserver cs1 -policyName cspol2 -priority 120
20

© 1999-2018 Citrix Systems, Inc. All rights reserved. 470

NetScaler 12.0

21 bind cs vserver cs1 -policyName cspol3 -priority 130

22
23 bind cs vserver cs1 -lbvserver vint

To configure service chaining on the appliance by using the GUI

1. Navigate to System > Network > IPs and add the subnet IP addresses.
2. Navigate to System > Network > VLANs and add VLANs, Bind the VLANs to the interfaces and
subnet IP addresses.
3. Navigate to Traffic Management > Service Chaining> Configure Service Path Ingress VLAN
and specify an ingress VLAN.
4. Navigate to Traffic Management > Subscriber > Parameters > Configure Subscriber Param-
eters and specify the following:
• Interface Type: Specify RadiusAndGx.
• Configure a diameter virtual server, PCRF realm, and the subscriber GX interface parame-
ters.
• Specify the RADIUS interface parameters.
5. Navigate to Traffic Management > Service Chaining> Service Function and add service func-
tions to associate a value-added service with an ingress VLAN.
6. Navigate to System> Network> Large Scale NAT. Click Pools and add a pool. Click Clients and
add a client. Click Groups and add a group and specify the client. Edit the group and bind the
pool to this group.
7. Navigate to System> Network> Net Profiles and add a net profile. Select Override LSN. Op-
tionally, navigate to System> Network> Settings> Configure Layer 3 Parameters and verify
that Override LSN is not selected.
8. Navigate to Traffic Management> Load Balancing> Virtual Servers and configure the virtual
servers and value-added services on the appliance. Bind the services and the net profile to the
virtual server.
9. Navigate to Traffic Management> Content Switching> Virtual Servers and configure a virtual
server, policy, and action. Specify the target load balancing virtual server.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

© 1999-2018 Citrix Systems, Inc. All rights reserved. 471

NetScaler 12.0

Policy based TCP profile selection

September 17, 2018

Contributed by:
C
You can configure the NetScaler appliance to perform TCP optimization based on subscriber at-
tributes. For example, the appliance can select different TCP profiles at run time, based on the
network to which the user equipment (UE) is connected. As a result, you can improve a mobile
user’s experience by setting some parameters in the TCP profiles and then using policies to select the
appropriate profile.
Create separate TCP profiles for subscribers connecting through a 4G network and for users connect-
ing through any other network. Define a policy rule that is selected on the basis of a subscriber param-
eter, such as RAT-type. In the following examples, if RAT-Type is EUTRAN, a TCP profile that supports
a faster connection is selected (Example 1). For all other RAT-Type values, a different TCP profile is
selected (Example 2).
Note

The RAT-Type AVP (AVP code 1032) is of type Enumerated and is used to identify the radio access
technology that is serving the UE.

The value “1004” indicates that the RAT is EUTRAN. (RFC 29.212).

Example1:

1 add ns tcpProfile tcp2 -WS ENABLED -SACK ENABLED -WSVal 8 -initialCwnd

16 - oooQSize 15000 -slowStartIncr 1 -bufferSize 1000000 -flavor BIC
- dynamicReceiveBuffering DISABLED -sendBuffsize 1000000 -dsack
DISABLED -maxcwnd 4000000 -fack ENABLED -minRTO 500 -maxburst 15
2
3 add appqoe action appact2 -priority HIGH -tcpprofile tcp2
4
5 add appqoe policy apppol2 -rule ”SUBSCRIBER.AVP(1032).VALUE.
GET_UNSIGNED32(0, BIG_ENDIAN).EQ(1004)” -action appact2
6
7 bind cs vserver <name>  -policyname apppol2 -priority 20 -type request

Example2:

1 add ns tcpProfile tcp1 -WS ENABLED -SACK ENABLED -WSVal 8 -initialCwnd

16 - oooQSize 15000 -slowStartIncr 1 -bufferSize 150000 -flavor BIC
- dynamicReceiveBuffering DISABLED -sendBuffsize 150000 -dsack
DISABLED -maxcwnd 4000000 -fack ENABLED -minRTO 200 -maxburst 15

© 1999-2018 Citrix Systems, Inc. All rights reserved. 472

NetScaler 12.0

2
3 add appqoe action appact1 -priority HIGH -tcpprofile tcp1
4
5 add appqoe policy apppol1 -rule ”SUBSCRIBER.AVP(1032).VALUE.
GET_UNSIGNED32(0, BIG_ENDIAN).NE(1004)” -action appact1
6
7 bind cs vserver <name>  -policyname apppol1 -priority 10 -type request

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Load Balance Control-Plane Traffic that is based on Diameter, SIP, and

SMPP Protocols

September 17, 2018

Contributed by:
C

With the increase in control-plane traffic, the servers can become a bottleneck because the traffic
is not optimally distributed among the servers. Therefore, messages must be load balanced. The
NetScaler appliance supports Diameter, SIP, and SMPP load balancing.

SIP

NetScaler enables you to load balance SIP messages over UDP or over TCP (including TLS) to a group
of proxy servers. NetScaler also provides Call-ID based persistence and Call-ID hash load balancing
method using which you direct packets for a particular SIP session to the same load balanced SIP
server.
The NetScaler default expressions language contains a number of expressions that operate on Ses-
sion Initiation Protocol (SIP) connections. These expressions are intended to be used in policies for
SIP protocol that operates on a request/response basis. These expressions can be used in content
switching, rate limiting, responder, and rewrite policies.

For more information, see Load Balancing a Group of SIP Servers.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 473

NetScaler 12.0

SMPP

Millions of short messages are exchanged daily between individuals and value-added service
providers, such as banks, advertisers, and directory services, by using the short message peer to peer
(SMPP) protocol. Often, message delivery is delayed because servers are overloaded and traffic is not
optimally distributed among the servers.
The NetScaler appliance provides optimal distribution of messages across your servers, preventing
poor performance and outages. The NetScaler appliance:

• Load balances messages originating from the server and from the client
• Monitors the health of the message centers
• Provides content switching support for the message centers
• Handles concatenated messages

Limitation: Message IDs, from the message center, longer than 59 bytes are not supported. If the
message ID length returned by the message center is more than 59 bytes, ancillary operations fail and
the NetScaler appliance responds with an error message.

For more information, see SMPP Load Balancing

Diameter

Diameter is a base protocol with more than 50 protocols (also called applications) built over it. There-
fore, the diameter traffic generated in a Telco network is high. To optimally maintain this diameter
traffic, the NetScaler appliance performs load balancing, content switching, and acts as a relay agent.
Additionally, the appliance offers rewrite and responder functionality. The appliance supports rate
limiting of Diameter messages.

For more information, see Configuring Diameter Load Balancing.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Provide DNS Infrastructure/Traffic Services, such as, Load Balancing,

Caching, and Logging for Telecom Service Providers

September 17, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 474

NetScaler 12.0

Contributed by:
C

Telecom service providers can configure the NetScaler appliance to function as a DNS proxy. Caching
of DNS records, which is an important function of a DNS proxy, is enabled by default on the NetScaler
appliance. This enables the NetScaler appliance to provide quick responses for repeated translations
and hence enhances the customer experience and also saves the bandwidth. The caches responses
from DNS name servers. When the appliance receives a DNS query, it checks for the queried domain in
its cache. If the address for the queried domain is present in its cache, the NetScaler appliance returns
the corresponding address to the client. Otherwise, it forwards the query to a DNS name server that
checks for the availability of the address and returns it to the NetScaler appliance. The NetScaler
appliance then returns the address to the client.

For requests for a domain that has been cached earlier, the NetScaler appliance serves the Address
record of the domain from the cache without querying the configured DNS server and hence saves the
bandwidth.

From 11.0 release onwards, NetScaler also logs the DNS requests that it receives and also the responses
that it sends to the client. Telecom service providers can use this log to:

• Audit the DNS responses to the client

• Audit DNS clients
• Detect and prevent DNS attacks
• Troubleshooting

For more information, see

Domain Name System.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Provide Subscriber Load Distribution Using GSLB Across Core-Networks

of a Telecom Service Provider

October 24, 2018

Contributed by:
C

Scalability, high availability and performance are critical to service provider deployments. While many

© 1999-2018 Citrix Systems, Inc. All rights reserved. 475

NetScaler 12.0

service providers deploy there infrastructure at a single location or multiple location, these deploy-
ments are subject to a number of inherent limitations, such as:

• If the site loses connectivity to all or part of the public Internet, it will be inaccessible to users
and customers, which can have significant impact on the business.
• Users accessing the site from geographically distant locations may experience large and highly
variable delays, which are exacerbated by the large number of round trips that HTTP requires
to transfer content.

NetScaler appliance’s Global Server Load Balancing (GSLB) overcomes these problems by distributing
traffic among sites deployed in multiple geographic locations. By serving content from many different
points in the Internet, GSLB alleviates the impact of network bandwidth bottlenecks and provides
robustness in case of network failures at a particular site. Users can be automatically directed to the
nearest or least loaded site at the time of the request, minimizing the likelihood of long download
delays and/or service disruptions.
You can use NetScaler appliance’s global server load balancing for:

• Disaster recovery or high availability by configuring an Active-standby data center setup that
consists of an active and a standby data center. When a failover occurs as a result of a disaster
event, the standby data center becomes operational.
• High availability and speed by configuring an active-active data center setup that consists of
multiple active data centers. Client requests are load balanced across active data centers.
• Directing client requests to the data center that is closest in geographical distance or network
distance by configuring a proximity setup.
• Full-DNS resolutions, GSLB processes DNS queries of the A, AAAA and CNAME types, and the
DNS function option can process DNS queries of all other types, such as MX and PTR. Also, if the
recursive resolution is enabled, the appliance will forward DNS queries for domain names that
are not configured on the NetScaler appliance.

For more information, see

Global Server Load Balancing.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Bandwidth Utilization Using Cache Redirection Functionality

September 17, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 476

NetScaler 12.0

Contributed by:
C

The volume of web traffic on the Internet is enormous and a large percentage of that traffic is redun-
dant. Multiple clients ask web servers for the same content repeatedly leading to inefficient use of
bandwidth. To relieve the origin web server of processing each request, Internet Service Providers
(ISPs) can use the cache redirection feature of NetScaler appliance and serve the content from a cache
server instead of from the origin server. The NetScaler appliance analyzes incoming requests, sends
requests for cacheable data to cache servers, and sends non-cacheable requests and dynamic HTTP
requests to origin servers. Cache redirection feature of NetScaler is policy-based, and by default, re-
quests that match a policy are sent to the origin server, and all other requests are sent to a cache
server. You can combine content switching with cache redirection to cache selective content and
serve content from specific cache servers for specific types of requested content.

For more information, see Cache Redirection.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

NetScaler TCP Optimization

September 17, 2018

Contributed by:
C

The NetScaler appliance provides advanced TCP tuning and optimization techniques and capabilities
that are well suited to modern 3.5 and 4G networks, improving user experience and perceived down-
load speeds significantly.

This section focuses on detailed instructions relevant to:

• Choosing and inserting an appropriate NetScaler T1000 Series model in a mobile network for
TCP optimization
• Full configuration instructions related to not only TCP optimization but also for appropriate
Layer-2 and Layer-3 configuration of the T1 device

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

© 1999-2018 Citrix Systems, Inc. All rights reserved. 477

NetScaler 12.0

Getting Started

January 6, 2019
Contributed by:
C

Hardware

Citrix provides a wide breath of NetScaler models that might be loosely based on two factors:
• Capacity, currently ranging from hundreds of Mbps for the low-end VPX appliance to 160Gbps
for the high-end 25000 MPX series appliance
• Telco grade, with the availability of the T1000 series for Telco datacenters.
Your Citrix Sales or Support representative can help you select the appropriate hardware for your
demo, trial, or production needs.
The remainder of this section uses a NetScaler T1200 as a reference hardware. Note that putting aside
superficial differences related to number and notation of available interfaces (see * in note) or well-
documented limitations of NetScaler VPX (see ** in note) the instructions should apply mostly verba-
tim regardless of the NetScaler model selected.
Note

* For instance a the T1010 model only has 12x1GbE typically marked as 1/1-1/12 rather than the
10/x notation used in this document.

** A NetScaler VPX instance typically doesn’t support LACP aggregation; it might also not support
VLAN tagging.

Initial Setup

Through Serial Console

After a serial cable is connected, you can log on to the NetScaler appliance with the following creden-
tials:
• Username: nsroot
• Password: nsroot
Once logged in, configure the basic details of the NetScaler appliance as shown in the screen capture
below.
Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 478

NetScaler 12.0

1 set ns config ‒ IPAddress <ip_addr> -netmask <netmask>

2
3 saveconfig
4
5 reboot -warm

After you restart the appliance, you might use SSH for further configuration of the T1100 nodes.

Through LOM

Lights out Management (LOM) port on the front panel of the NetScaler appliance allows operator to
remotely monitor and manage the appliance independently of the operating system. Operator can
change the IP address, power cycle, and perform a code dump by connecting to the NetScaler appli-
ance through the LOM port.

Default IP Address of LOM port is 192.168.1.3

Figure. Intial Configuration of LOM Module

Set a static IP on your laptop and plug it directly into the LOM interface with a crossover cable or into
a switch in the same broadcast domain as the LOM interface.

For initial configuration, type the port’s default address: http://192.168.1.3 in a web browser and
change the LOM port’s default IP address.

Refer to Configuration Guides for further details.

Software

The NetScaler TCP optimization for mobile networks is constantly evolving. The capabilities and
tunings outlined in this document require a NetScaler Telco build. Here is an example showing the
NetScaler Telco build.

Example:

1 show ver
2
3 NetScaler NS11.0: Build 64.957.nc, Date: Aug 26 2016, 02:00:23

If the T1000 has not shipped with the appropriate build revision, contact the NetScaler Customer
Support.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 479

NetScaler 12.0

Important

Both the appliances should have the same software image.

SSH Client

A NetScaler appliance can be configured by using either the CLI or the HTML5 GUI. However, this sec-
tion provides only CLI-based instructions.

While the CLI is accessible through the NetScaler serial console, an SSH client is normally recom-
mended to allow for remote NetScaler configuration.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Management Network

January 6, 2019

Contributed by:
C

Connectivity

Most NetScaler devices offer redundant 1GbE OAM ports, notated as 0/1 and 0/2. To provide for redun-
dancy in case of a switch failure, you should connect the relevant ports to different upstream switches.

A high-level overview of the recommended connectivity is outlined in the following diagram:

After the NetScaler appliance is connected to the management network, subsequent configuration
steps can be performed remotely using SSH or web connectivity to the CLI and GUI respectively.

Routing

The add route command may be used to configure any routes appropriate to the management net-
work. The relevant gateway should be reachable on the NSIP subnet, as shown below.

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 480

NetScaler 12.0

1 add route <network>  <netmask>  <gateway>

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Licensing

September 17, 2018

Contributed by:
C

A valid license file should be installed on the NetScaler appliance. The license should support at least
as many Gbps as the expected maximum Gi-LAN throughput.

License files should be copied through an SCP client to the /nsconfig/license of the appliance, as
shown in the screen capture below.

EXample:

1 shell ls /nsconfig/license/
2
3 CNS_V3000_SERVER_PLT_Retail.lic ssl

Do a warm restart to apply the new license, as shown in the screen capture below.

EXample:

1 reboot -warm
2
3 Are you sure you want to restart NetScaler (Y/N)? [N]:y
4
5 Done

After the restart completes, verify that the license has been properly applied, by using the show license
CLI.

In the example below a 3Gbps Platinum license has been successfully installed.

EXample:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 481

NetScaler 12.0

1 > show license

2
3              License status:
4
5                                      Web Logging: YES
6
7                                                ...
8
9                                  Model Number ID: 3000
10
11                                     License Type: Platinum License
12
13 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

High Availability

January 6, 2019

Contributed by:
C

High availability (HA) refers to an active-standby operational mode of a NetScaler device pair. Each
device has its own dedicated management IP address. All other IP addresses are owned by the active
device in the pair.

Connectivity

While there are multiple connectivity options for aNetScaler HA pair, the most recommended one is
depicted in the following diagram:

In the above diagram, the N+1 red links between each T1000 and the respective switch imply N+1 re-
dundancy - as explained in Connectivity. For instance, considering a 45 Gbps Gi-LAN N=5 is an appro-
priate value, with 6x10GbE LACP channels between each switch and the respective T1000 as well as
between the two switches.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 482

NetScaler 12.0

An extra pair of links is recommended between the NetScaler pair, to provide for HA communication
isolation from the OAM network.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Gi-LAN Integration

January 6, 2019

Contributed by:
C

Typically, a NetScaler appliance is inserted as a separate L3 inline node in the Gi-LAN, similarly to an
L3 router.

Figure: A simple depiction of a Gi-LAN

Connectivity

A physical NetScaler connectivity to upstream switches is recommended to provide for sufficient re-
dundancy. For example, assuming that a NetScaler appliance is inserted in a Gi-LAN that is handling
a total (uplink+downlink) of 24Gbps, connectivity with 4x10GbE or more interfaces is recommended.
This effectively provides for N+1 redundancy in case of a link failure.

The relevant ports on the upstream switch should be configured for LACP port aggregation. The rele-
vant configuration on NetScaler is outlined below:

Connectivity Configuration:

1 set interface 10/1 ‒ tagall ON ‒ lacpMode ACTIVE ‒ lacpKey 1

2
3 set interface 10/2 ‒ tagall ON ‒ lacpMode ACTIVE ‒ lacpKey 1
4
5 set interface 10/3 ‒ tagall ON ‒ lacpMode ACTIVE ‒ lacpKey 1
6
7 set interface 10/4 ‒ tagall ON ‒ lacpMode ACTIVE ‒ lacpKey 1

You can verify the appropriate functionality of LACP using the “show interface” command:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 483

NetScaler 12.0

show interface:

sh interface LA/1

1 1)      Interface LA/1 (802.3ad Link Aggregate) #39

2
3          flags=0x4100c020 <ENABLED, UP, AGGREGATE, UP, HAMON, 802.1q>
4
5          MTU=1500, native vlan=1, MAC=02:e0:ed:33:88:b0, uptime 340
h11m56s
6
7          Requested: media NONE, speed AUTO, duplex NONE, fctl NONE,
8
9          throughput 0
10
11          Actual: throughput 4000
12
13          LLDP Mode: NONE,
14
15          RX: Pkts(918446) Bytes(110087414) Errs(0) Drops(795989) Stalls
(0)
16
17          TX: Pkts(124113) Bytes(15255532) Errs(0) Drops(0) Stalls(0)
18
19          NIC: InDisc(0) OutDisc(0) Fctls(0) Stalls(0) Hangs(0) Muted(0)
20
21          Bandwidth thresholds are not set.

Disable the remaining unused interfaces and turn off the monitor.

set interface 10/5 –haMonitor OFF

Command:

1 set interface 10/24 ‒ haMonitor OFF

2
3 disable interface 10/5
4
5 disable interface 10/24

Configuration of physical interfaces is not shared across the two NetScaler units. Hence, the above
commands must be run across both NetScaler nodes in case of an HA pair deployment.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 484

NetScaler 12.0

HA Configuration

All other configuration parameters are shared between the NetScaler nodes of an HA pair. Hence, HA
sync should be enabled prior to any other configuration commands being run. Basic HA configuration
involves the following steps:

1. Using the exact same NetScaler hardware, software, and license: HA pairs are not supported be-
tween different models (i.e. a T1100 and an MPX21550) or same models with different firmware levels.
Refer to the appropriate instructions on upgrading an existing HA pair - Upgrading to Release 11.1.

2. Establishing the HA pair.

Example:

1 netscaler-1> add HA node 1 <netscaler-2-NSIP>

2
3 netscaler-2> add HA node 1 <netscaler-1-NSIP>

3. Verify the HA pair establishment running the following command in either node; both nodes should
be visible, one of them as Primary (active), the other as a Secondary (standby).

Example:

“‘show HA node

1 4\. Enable failsafe mode and maxFlips. This ensures that in case of a
route monitor failure on both nodes at least one node remains active
without active/standby status constantly switching.
2
3 **Example:**

set HA node –failsafe ON

set HA node -maxFlips 3 -maxFlipTime 1200

1 5\. Finally, enable HA sync to occur over the dedicated intra-NetScaler

ports rather than the OAM network.
2
3 **Example:**

add vlan 4080 -aliasName syncVlan

set HA node -syncvlan 4080

1 > **Note**
2 >
3 > The VLAN 4080 in the commands in the above example shouldn ’ t be
taken literally. Any unused VLAN-ID might be reserved.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 485

NetScaler 12.0

4
5 ## VLAN Configuration
6
7 After the physical interfaces have been appropriately configured, you
might configure the appropriate Gi-LAN VLANs. For instance, consider
a rather simple Gi-LAN environment with an ingress/egress VLAN pair
with 100/101 VLAN-identifier respectively.
8
9 The following commands configure the relevant VLANs on top of the LACP
channel created in the prior step.

add vlan 100

add vlan 101
bind vlan 100 –ifnum LA/1 –tagged
bind vlan 101 –ifnum LA/1 –tagged

1 ## IPv4 Configuration
2
3 Typically, a NetScaler appliance requires one SNIP per VLAN. The
example below assumes that the networks outlined in the Gi-LAN
integration diagram, given in the begining of this page, have a /24
subnet mask:

add ns ip 192.168.1.254 255.255.255.0 –vserver DISABLED –mgmtAccess DISABLED

add ns ip 192.168.2.254 255.255.255.0 –vserver DISABLED –mgmtAccess DISABLED

1 After the SNIPs have been configured they should be associated with the
appropriate VLAN:

bind vlan 100 –IPAddress 192.168.1.254 255.255.255.0

bind vlan 101 –IPAddress 192.168.2.254 255.255.255.0

1 ## IPv4 Static Routing

2
3 The example outlined in the [Management Network](/en-us/netscaler/12/
netscaler-support-for-telecom-service-providers/NS_TCP_optimization/
NS_TCP_opt_mgmt_network.html) section calls for only a couple of
static routing rules:
4
5 - A 10.0.0.0/8 static route to the clients through the ingress router
6 - A default route to the internet through the egress router
7
8 **Example:**

© 1999-2018 Citrix Systems, Inc. All rights reserved. 486

NetScaler 12.0

add route 0.0.0.0 0.0.0.0 192.168.2.1

add route 10.0.0.0 255.0.0.0 192.168.1.1

1 ## IPv4 Policy-Based (VLAN - VLAN) routing

2
3 A NetScaler appliance allows for policy-based routing instead of static
routing, with routing decisions usually keyed against the incoming
interface and/or VLAN rather than destination IP. Policy-based
routing is either a convenient alternative, in case the client
source IP address range is subject to periodic changes, or a
mandatory consideration, in case a packet ’ s destination IP address
is not sufficient by itself to reach a routing decision (i.e. in
case of overlapping client IP addresses across multiple VLANs).
4
5 **Example:**

add ns pbr fromWirelessToInternet ALLOW –nextHop 192.168.2.1 –vlan 100 –priority 10

Done

add ns pbr fromInternetToWireless ALLOW –nextHop 192.168.1.1 –vlan 200 –priority 20

Done

apply ns pbrs

1 ## IPv6 Configuration
2
3 The following commands assign IPv6 SNIP per vlan. The example below
assumes that the networks outlined in the Figure: A simple depiction
of a Gi-LAN in this page have a /64 subnet mask:
4
5 **Command:**

add ns ip6 fd00:192:168:1::254/64 -vServer DISABLED –mgmtAccess DISABLED

add ns ip6 fd00:192:168:2::254/64 -vServer DISABLED –mgmtAccess DISABLED
bind vlan 100 -IPAddress fd00:192:168:1::254/64
bind vlan 200 -IPAddress fd00:192:168:2::254/64

1 ## IPv6 Routing
2
3 After  IPv6 addressing is complete, IPv6 static routing might be
configured:
4
5 - A fd00:10::/64 static route to the clients via the ingress router
6 - A default route to the internet via the egress router
7

© 1999-2018 Citrix Systems, Inc. All rights reserved. 487

NetScaler 12.0

8 **Example:**

add route6 fd00:10::/64 fd00:192:168:1::1

add route6 ::/0 fd00:192:168:2::1

1 Or using policy-based routing:

2
3 **Example:**

add ns pbr6 fromWirelessToInternetv6 ALLOW -vlan 100 -priority 10 -nextHop fd00:192:168:2::1

add ns pbr6 fromInternetToWirelessv6 ALLOW -vlan 200 -priority 20 -nextHop fd00:192:168:1::1

apply ns pbr6

1 ## LACP Redundancy and Failover

2
3 In case of an HA configuration, it ’ s recommended to leverage the
throughput option to configure a low threshold for the LACP channel.
For instance, consider a 25Gbps Gi-LAN and a 4x10GbE channel
between each NetScaler appliance in the HA pair and the upstream
switch to provide N+1 link redundancy:
4
5 **Example:**

set interface LA/1 –haMonitor ON –throughput 29000

1 In case of a double-link failure between the primary appliance and the

upstream switch the maximum Gi-LAN throughput that can be supported
would fall to 20Gbps. A 29Gbps low threshold per the example above
would result in a redundancy switchover event to the secondary
appliance (which has not suffered similar link failures) so that Gi-
LAN traffic is not affected.
2
3 ## Route Monitors
4
5 In addition to LACP redundancy, route monitor checks might be
configured and associated with the HA pair configuration. Route
monitor checks can be useful to detect failures between the
NetScaler appliance and the next-hop routers, especially if said
routers are not directly connected but through an upstream switch.
6
7 A typical HA route monitor configuration per the sample Gi-LAN in
section 2.5.1 is outlined below:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 488

NetScaler 12.0

add route 192.168.1.0 255.255.255.0 192.168.1.1 -msr ENABLED -monitor arp

add route 192.168.2.0 255.255.255.0 192.168.2.1 -msr ENABLED -monitor arp
bind HA node -routeMonitor 192.168.1.0 255.255.255.0
bind HA node -routeMonitor 192.168.2.0 255.255.255.0
“‘

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

TCP Optimization Configuration

January 6, 2019

Contributed by:
C

Before configuring TCP optimization, apply the following basic configuration settings on the NetScaler
appliance:

Initial configuration:

1 enable ns feature LB IPv6PT

2 enable ns mode FR L3 USIP MBF Edge USNIP PMTUD
3 disable ns feature SP
4 disable ns mode TCPB
5 set lb parameter -preferDirectRoute NO
6 set lb parameter -vServerSpecificMac ENABLED
7 set l4param -l2ConnMethod Vlan
8 set rsskeytype -rsstype SYMMETRIC
9 set ns param -useproxyport DISABLED

Note

Restart the NetScaler appliance if you change the rsskeytype system parameter.

TCP Termination

For NetScaler T1 to apply TCP optimization it needs to first terminate incoming TCP traffic. Towards
this end, a wildcard TCP vserver should be created and configured to intercept ingress traffic and then
forward it to the Internet router.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 489

NetScaler 12.0

Static/Dynamic Routing Environment

For environments with static or dynamic routing in place, vserver can rely on routing table info to for-
ward packets towards internet router. Default route must point to the internet router and also routing
entries for client subnets towards wireless router should be in place:

Example:

1 add lb vserver vsrv-wireless TCP * * -persistenceType NONE -

Listenpolicy ”CLIENT.VLAN.ID.EQ(100) && SYS.VSERVER(\”vsrv-wireless
\”).STATE.EQ(UP)” -m IP -cltTimeout 9000
2 add route 0.0.0.0 0.0.0.0 192.168.2.1
3 add route 10.0.0.0 255.0.0.0 192.168.1.1

VLAN-to-VLAN (PBR) Environment

There are customer environments where subscriber traffic is segmented to multiple flows and needs
to be forwarded to different routers based on incoming traffic parameters. Policy Based Routing (PBR)
can be used to route packets based on incoming packet parameters, such as VLAN, MAC address, In-
terface, source IP, source port, destination IP address, and destination port.

Example:

1 add lb vserver vsrv-wireless TCP * * -m IP -l2Conn ON -listenpolicy ”

CLIENT.VLAN.ID.EQ(100) || CLIENT.VLAN.ID.EQ(101) || CLIENT.VLAN.ID.
EQ(102)”
2
3 add ns pbr pbr-vlan100-to-vlan200 ALLOW -vlan 100 -nexthop 172.16.200.1
4
5 add ns pbr pbr-vlan101-to-vlan201 ALLOW -vlan 101 -nexthop 172.16.201.1
6
7 add ns pbr pbr-vlan102-to-vlan202 ALLOW -vlan 102 -nexthop 172.16.202.1

Using Policy Based Routing to route TCP optimized traffic is a new feature added in release 11.1 50.10.
For previous releases, having multiple “mode MAC” vserver entities per VLAN is an alternative solution
for multi-VLAN environments. Each vserver has a bound service representing the internet router for
the particular flow.

Example:

1 add server internet_router_1 172.16.200.1

2
3 add server internet_router_2 172.16.201.1
4

© 1999-2018 Citrix Systems, Inc. All rights reserved. 490

NetScaler 12.0

5 add server internet_router_3 172.16.202.1

6
7 add service svc-internet-1 internet_router_1 TCP * -usip YES -
useproxyport NO
8
9 add service svc-internet-2 internet_router_2 TCP * -usip YES -
useproxyport NO
10
11 add service svc-internet-3 internet_router_3 TCP * -usip YES -
useproxyport NO
12
13 bind service svc-internet-1 -monitorName arp
14
15 bind service svc-internet-2 -monitorName arp
16
17 bind service svc-internet-3 -monitorName arp
18
19 add lb vserver vsrv-wireless-1 TCP * * -Listenpolicy ”CLIENT.VLAN.ID.EQ
(100) && SYS.VSERVER(\”vsrv-wireless-1\”).STATE.EQ(UP)” -m MAC -
l2Conn ON
20
21 add lb vserver vsrv-wireless-2 TCP * * -Listenpolicy ”CLIENT.VLAN.ID.EQ
(101) && SYS.VSERVER(\”vsrv-wireless-2\”).STATE.EQ(UP)” -m MAC -
l2Conn ON
22
23 add lb vserver vsrv-wireless-3 TCP * * -Listenpolicy ”CLIENT.VLAN.ID.EQ
(102) && SYS.VSERVER(\”vsrv-wireless-3\”).STATE.EQ(UP)” -m MAC -
l2Conn ON
24
25 bind lb vserver vsrv-wireless-1 svc-internet-1
26
27 bind lb vserver vsrv-wireless-2 svc-internet-2
28
29 bind lb vserver vsrv-wireless-3 svc-internet-3

Note

The vserver mode is MAC in contrast to previous examples where it is mode IP. This is required
to retain the destination IP information when we have service(s) bound to vserver. Also, the ad-
ditional PBR configuration need to route non-optimized traffic.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 491

NetScaler 12.0

TCP Optimization

Out-of-the-box NetScaler TCP termination is configured for TCP pass-through functionality. TCP pass-
through essentially means that NetScaler T1 may transparently intercept a client-server TCP stream
but does not retain separate client/server buffers or otherwise apply any optimization techniques.

To enable TCP optimization a TCP profile, named as nstcpprofile, is used to specify TCP configurations
that is used if no TCP configurations are provided at the service or virtual server level and it should be
modified as follows:

Command:

1 add ns tcpProfile nstcpprofile -WS ENABLED -SACK ENABLED -WSVal 8 -mss

1460 -maxBurst 30 -initialCwnd 16 -oooQSize 15000 -minRTO 800 -
bufferSize 4000000 -flavor BIC -dynamicReceiveBuffering ENABLED -KA
ENABLED -sendBuffsize 4000000 -rstWindowAttenuate ENABLED -
spoofSynDrop ENABLED -ecn ENABLED -frto ENABLED -maxcwnd 1000000 -
fack ENABLED -rstMaxAck enABLED -tcpmode ENDPOINT

Note

If there is not any profile explicitly created and bound to vserver and service, the profile
nstcp_default_profile is bound by default.

In case of multiple TCP profiles requirement, extra TCP profiles can be created and associated
with the appropriate virtual server

Command:

1 add ns tcpProfile custom_profile -WS ENABLED -SACK ENABLED -WSVal 8 -

mss 1460 -maxBurst 30 -initialCwnd 16 -oooQSize 15000 -minRTO 800 -
bufferSize 4000000 -flavor BIC -dynamicReceiveBuffering ENABLED -KA
ENABLED -sendBuffsize 4000000 -rstWindowAttenuate ENABLED -
spoofSynDrop ENABLED -ecn ENABLED -frto ENABLED -maxcwnd 1000000 -
fack ENABLED -rstMaxAck enABLED -tcpmode ENDPOINT
2
3 set lb vserver vsrv-wireless -tcpProfileName custom_profile

Note

For deployments with vserver -m MAC and service, same profile should be associated with ser-
vice.

1 set service svc-internet -tcpProfileName custom_profile

© 1999-2018 Citrix Systems, Inc. All rights reserved. 492

NetScaler 12.0

TCP Optimization Capabilities

Most of the relevant TCP optimization capabilities of a NetScaler appliance are exposed through a
corresponding TCP profile. Typical CLI parameters that should be considered when creating a TCP
profile are the following:

1. Window Scaling (WS): TCP Window scaling allows increasing the TCP receive window size be-
yond 65535 bytes. It helps improving TCP performance overall and specially in high bandwidth
and long delay networks. It helps with reducing latency and improving response time over TCP.
2. Selective acknowledgment (SACK): TCP SACK addresses the problem of multiple packet loss
which reduces the overall throughput capacity. With selective acknowledgement the receiver
can inform the sender about all the segments which are received successfully, enabling sender
to only retransmit the segments which were lost. This technique helps T1 improve overall
throughput and reduce the connection latency.
3. Window Scaling Factor (WSVal): Factor used to calculate the new window size. It must be
configured with a high value in order to allow the advertised window by NS to be at least equal
to the buffer size.
4. Maximum Segment Size (MSS): MSS of a single TCP segment. This value depends on the MTU
setting on intermediate routers and end clients. A value of 1460 corresponds to an MTU of 1500.
5. maxBurst: Maximum number of TCP segments allowed in a burst.
6. Initial Congestion Window size(initialCwnd): TCP initial congestion window size determines
the number of bytes which can be outstanding in beginning of the transaction. It enables T1 to
send those many bytes without bothering for congestion on the wire.
7. Maximum OOO packet queue size(oooQSize): TCP maintains Out Of Order queue to keep the
OOO packets in the TCP communication. This setting impacts system memory if the queue size
is long as the packets need to be kept in runtime memory. Thus this needs to be kept at opti-
mized level based on the kind of network and application characteristics.
8. Minimum RTO(minRTO): The TCP retransmission timeout is calculated on each received ACK
based on internal implementation logic. The default retransmission timeout happens at 1 sec-
ond to start with and this can be tweaked with this setting. For second retransmission of these
packets RTO will be calculated by N*2 and then N*4 … N*8… goes on till last retransmission
attempt.
9. bufferSize / sendBuffsize: these refer to the maximum amount of data that the T1 may receive
from the server and buffer internally without sending to the client. They should be set to a
value larger (at least double) than the Bandwidth Delay Product of the underlying transmission
channel.
10. flavor: this refers to the TCP congestion control algorithm. Valid values are Default, BIC, CUBIC,
Westwood and Nile.
11. Dynamic receive buffering: allows the receive buffer to be adjusted dynamically based on
memory and network conditions. It will fill up the buffer as much as it’s required to keep the

© 1999-2018 Citrix Systems, Inc. All rights reserved. 493

NetScaler 12.0

client’s download pipe full instead of filling up, by reading ahead from server, a fixed size buffer,
as latter is specified in TCP profile and typically based on criteria such as 2*BDP, for a connec-
tion. NetScaler T1 monitors the network conditions to the client and estimates how much it
should read ahead from the server.
12. Keep-Alive (KA): Send periodic TCP keep-alive (KA) probes to check if peer is still up.
13. rstWindowAttenuate: Defending TCP against spoofing attacks. It will reply with corrective ACK
when a sequence number is invalid.
14. rstMaxAck: Enable or disable acceptance of RST that is out of window yet echoes highest ACK
sequence number.
15. spoofSynDrop: Drop of invalid SYN packets to protect against spoofing.
16. Explicit Congestion Notification(ecn): It sends notification of the network congestion status
to the sender of the data and takes corrective measures for data congestion or data corruption.
17. Forward RTO-Recovery: In case of spurious retransmissions, the congestion control configura-
tions are reverted to their original state.
18. TCP maximum congestion window (maxcwnd): TCP maximum congestion window size that
is user configurable.
19. Forward acknowledgment (FACK): To avoid TCP congestion by explicitly measuring the total
number of data bytes outstanding in the network, and helping the sender (either T1 or a client)
control the amount of data injected into the network during retransmission timeouts.
20. tcpmode: TCP optimization modes for specific profile.

For the above parameters please consult [1] for guidance on picking the appropriate values. For the
remaining ones, the values outlined in TCP Optimization should apply to most cases.

Silently Dropping Idle Connections

In a Telco network, almost 50 percent of a NetScaler appliance’s TCP connections become idle, and
the appliance sends RST packets to close them. The packets sent over radio channels activate those
channels unnecessarily, causing a flood of messages that in turn cause the appliance to generate a
flood of service-reject messages. The default TCP profile now includes DropHalfClosedConnOnTime-
out and DropEstConnOnTimeout parameters, which by default are disabled. If you enable both of
them, neither a half closed connection nor an established connection causes a RST packet to be sent
to the client when the connection times out. The appliance just drops the connection.

1 set ns tcpProfile nstcpprofile  -DropHalfClosedConnOnTimeout ENABLED

2
3 set ns tcpProfile nstcpprofile  -DropEstConnOnTimeout ENABLED

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 494

NetScaler 12.0

4. Solutions for Telecom Service Providers

Analytics and Reporting

September 17, 2018

Contributed by:
C

The TCP Speed Reporting is a NetScaler feature which extracts TCP connection statistics, as a measure
of TCP download and upload performance, and is utilized in TCP Insight reports of the Citrix Applica-
tion Delivery Management (ADM). To achieve this, NetScaler monitors each TCP connection, locates
packet bursts on an idle time-out basis and reports key metrics (such as byte count, retransmitted
byte count and duration) for the identified maximum burst. TCP Speed Reporting feature is enabled
by default, support both TCP and HTTP vServers and depends on the Appflow/ULFD reporting infras-
tructure.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Real-time Statistics

September 17, 2018

Contributed by:
C

The stat command might be used to verify that TCP optimization is properly applied:

Command:

1 > stat lb vserver vsrv-wireless

2 Virtual Server Summary
3                       vsvrIP  port     Protocol        State   Health 
actSvcs
4 vsrv...eless               *     0          TCP           UP      100
        1
5
6            inactSvcs

© 1999-2018 Citrix Systems, Inc. All rights reserved. 495

NetScaler 12.0

7 vsrv...eless       0
8 Virtual Server Statistics
9                                           Rate (/s)               
Total
10 Vserver hits                                       0                  
10
11 Requests                                           0                   
0
12 Responses                                          0                   
0
13 Request bytes                                      0                
1580
14 Response bytes                                     0           
532594360
15 Total Packets rcvd                                 0              
216463
16 Total Packets sent                                 0              
369898
17 Current client connections                        --                   
0
18 Current Client Est connections                    --                  
 0
19 Current server connections                        --                   
0
20 Requests in surge queue                           --                   
0
21 Requests in vserver’s surgeQ                      --                   
0
22 Requests in service’s surgeQs                     --                   
0
23 Spill Over Threshold                              --                   
0
24 Spill Over Hits                                   --                   
0
25 Labeled Connection                                --            
       0
26 Push Labeled Connection                           --                   
0
27 Deferred Request                                   0                   
0
28 Invalid Request/Response                          --                   
0
29 Invalid Request/Response Dropped                  --                   
0
30 Bound Service(s) Summary

© 1999-2018 Citrix Systems, Inc. All rights reserved. 496

NetScaler 12.0

31                           IP  port         Type        State     Hits  

Hits/s
32 svc-internet     192.168.2.2     0          TCP           UP       10
      0/s
33
34                  Req    Req/s      Rsp    Rsp/s Throughp ClntConn  
SurgeQ
35 svc-internet       0      0/s        0      0/s        0        0
        0
36                   SvrConn   ReuseP  MaxConn ActvTran  SvrTTFB     Load
37 svc-internet       0        0        0        0        0        0

The Total counters should constantly increase for an operational system. In addition, the Rate coun-
ters should be non-zero.
Note

The preceding output is from an operational yet idle lab system, explaining the zero rate.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

SNMP

September 17, 2018

Contributed by:
C

SNMP agent can be queried for system specific information from a remote device (SNMP Manager).
Based on the query, the agent searches for the equal object identifier (OID) in the management in-
formation base (MIB) for the data requested and sends the information to the SNMP Manager. The
following are the most useful SNMP OIDs for Telco deployments:

Memory

• resMemUsage (1.3.6.1.4.1.5951.4.1.1.41.2)

Percentage of memory utilization on NetScaler.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 497

NetScaler 12.0

Packet Engine CPU

• resCpuUsage (1.3.6.1.4.1.5951.4.1.1.41.1)

CPU utilization percentage.

• nsCPUTable (1.3.6.1.4.1.5951.4.1.1.41.6)

This table contains information about each CPU in NetScaler.

Indexed on: nsCPUname

• nsCPUname (1.3.6.1.4.1.5951.4.1.1.41.6.1.1)

The name of the CPU.

• nsCPUusage (1.3.6.1.4.1.5951.4.1.1.41.6.1.2)

CPU utilization percentage.

Throughput

• allNicTotRxMbits (1.3.6.1.4.1.5951.4.1.1.71.1)

Number of megabits received by the NetScaler appliance.

• allNicTotTxMbits (1.3.6.1.4.1.5951.4.1.1.71.2)

Number of megabits transmitted by the NetScaler appliance.

• ipTotRxPkts (1.3.6.1.4.1.5951.4.1.1.43.25)

IP packets received.

• ipTotRxMbits (1.3.6.1.4.1.5951.4.1.1.43.27)

Megabits of IP data received.

• ipTotTxPkts (1.3.6.1.4.1.5951.4.1.1.43.28)

IP packets transmitted.

• ipTotTxMbits (1.3.6.1.4.1.5951.4.1.1.43.30)

Megabits of IP data transmitted.

Connections

Active connections:

• tcpActiveServerConn (1.3.6.1.4.1.5951.4.1.1.46.8)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 498

NetScaler 12.0

Connections to a server currently responding to requests.

Total connections:

• tcpCurServerConn (1.3.6.1.4.1.5951.4.1.1.46.1)

Server connections, including connections in the Opening, Established, and Closing state.

• tcpCurClientConn (1.3.6.1.4.1.5951.4.1.1.46.2)

Client connections, including connections in the Opening, Established, and Closing state.

Note: Because of SYN-Cookie, this doesn’t include Client in Opening state

• tcpTotZombieCltConnFlushed (1.3.6.1.4.1.5951.4.1.1.46.26)

Client connections that are flushed because the client has been idle for some time.

• tcpTotZombieSvrConnFlushed (1.3.6.1.4.1.5951.4.1.1.46.27)

Server connections that are flushed because there have been no client requests in the queue for some
time.

Errors

• tcpErrSynGiveUp (1.3.6.1.4.1.5951.4.1.1.46.37)

Attempts to establish a connection on the NetScaler that timed out.

• tcpErrRetransmitGiveUp (1.3.6.1.4.1.5951.4.1.1.46.60)

Number of times NetScaler terminates a connection after retransmitting the packet seven times on
that connection.Retrasnmission happens when recieving end doesn’t acknowledges the packet.

• ifInDiscards (1.3.6.1.2.1.2.2.1.13)

The number of inbound packets which were chosen to be discarded even though no errors had been
detected to prevent their being deliverable to a higher-layer protocol. One possible reason for dis-
carding such a packet could be to free up buffer space.

• ifOutDiscards (1.3.6.1.2.1.2.2.1.19)

The number of outbound packets which were chosen to be discarded even though no errors had been
detected to prevent their being transmitted. One possible reason for discarding such a packet could
be to free up buffer space.

• ifErrTxOverflow (1.3.6.1.4.1.5951.4.1.1.54.1.36)

Number of packets that have passed through the overflow queues, during transmission on the speci-
fied interface, since the NetScaler appliance was started or the interface statistics were cleared. This
gets incremented only on congested ports.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 499

NetScaler 12.0

Optimized/Bypass connections

• tcpOptimizationEnabled (1.3.6.1.4.1.5951.4.1.1.46.131)

Total number of connections enabled with TCP optimization.

• tcpOptimizationBypassed (1.3.6.1.4.1.5951.4.1.1.46.132)

Total number of connections bypassed TCP Optimization.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Technical Recipes

September 17, 2018

Contributed by:
C

The NetScaler T1 models provide advanced features and a powerful policy configuration language that
allow for evaluation of complex decision in runtime.

While it is not possible to evaluate all capabilities that are potentially unlocked by the T1000 features
and policy configuration guide, technical receipes consider implementation of various requirements
brought in by Telco operators. Feel free to re-use the “recipes” as is or adapt to your environment.

Per-user Connection Limit

The NetScaler T1 model can be configured to limit the number of connections per unique subscriber
IP. With the below configuration, N concurrent TCP connections per IP (CLIENT.IP.SRC) is allowed.
For every attempt for connection beyond the configured threshold, T1 sends an RST. For maximum 2
concurrent connections per user:

Command:

1 add stream selector streamSel_usrlimit CLIENT.IP.SRC

2 add ns limitIdentifier limitId_usrlimit -threshold 2 -mode CONNECTION -
selectorName streamSel_usrlimit
3 add responder policy respPol_usrlimit ”SYS.CHECK_LIMIT(\”
limitId_usrlimit\”)” RESET

© 1999-2018 Citrix Systems, Inc. All rights reserved. 500

NetScaler 12.0

4 bind lb vserver vsrv-wireless -policyName respPol_usrlimit -priority 1

-gotoPriorityExpression END

Smooth Insertion/Deletion of Vserver

Many operators concern about TCP connections disruption when the NetScaler T1 model is activated
inline for TCP optimization or when it is disabled for maintenance purposes. To avoid breaking exist-
ing connections when vserver is introduced, the following configuration needs to be applied before
configuring or activating vserver for TCP optimization:

Command:

1 add ns acl acl-ingress ALLOW ‒ vlan 100

2 add forwardingSession fwd-ingress ‒ aclname acl-ingress
3 apply ns acls

Forwarding sessions are effective on top of routing (either static or dynamic or PBR) and create session
entries for traffic that is routed (L3 mode). Any existing connection is handled by forwarding session
due to corresponding sessions, and upon vserver introduction it starts capturing only new TCP con-
nections.

ACLs can be configured to capture only specific ports like vserver, in order to avoid creating sessions
for unnecessary traffic, which is memory consuming. Another option is to remove specific configura-
tion after vserver activation.

For maintenance purposes, vserver should be disabled and its state appears as OUT OF SERVICE.
When this happens, the vserver terminates all connections immediately by default. To make vserver
to still serve the existing connections and not accept new, the following configuration should be ap-
plied:

Command:

1 set lb vserver vsrv-wireless ‒ downStateFlush DISABLED

New connections go through the routing table, and corresponding session entries are created due to
forwarding sessions.

Policy-Based TCP Profiling

Policy-based TCP Profile selection allows operators to configure TCP profile dynamically for clients
coming from different traffic domains (i.e. 3G or 4G). Some of the QoS metrics are different for these
traffic domains, and in order to achieve better performance, you need to change some of the TCP pa-
rameter dynamically. Consider a case where clients coming from 3G and 4G hit same vserver and use

© 1999-2018 Citrix Systems, Inc. All rights reserved. 501

NetScaler 12.0

same TCP profile, which have negative impact on some client’s performance. AppQoE functionality
can classify these clients and dynamically change TCP profile on vserver.

Example:

1 enable feature AppQoE

2
3 add ns tcpProfile nstcpprofile1 -WS ENABLED -SACK ENABLED -WSVal 8 -mss
1460 -maxBurst 30 -initialCwnd 16 -oooQSize 15000 -minRTO 800 -
slowStartIncr 1 -bufferSize 4000000 -flavor BIC -KA ENABLED -
sendBuffsize 4000000 -rstWindowAttenuate ENABLED -spoofSynDrop
ENABLED -frto ENABLED -maxcwnd 1000000 -fack ENABLED -tcpmode
ENDPOINT
4
5 add ns tcpProfile nstcpprofile2 -WS ENABLED -SACK ENABLED -WSVal 8 -mss
1460 -maxBurst 15 -initialCwnd 16 -oooQSize 15000 -minRTO 800 -
slowStartIncr 1 -bufferSize 128000 -flavor BIC -KA ENABLED -
sendBuffsize 6000000 -rstWindowAttenuate ENABLED -spoofSynDrop
ENABLED -frto ENABLED -maxcwnd 64000 -fack ENABLED -tcpmode ENDPOINT
6
7 add appqoe action action_1 -priority HIGH -tcpprofile nstcpprofile1
8
9 add appqoe action action_2 -priority HIGH -tcpprofile nstcpprofile2
10
11 add appqoe policy appqoe_4G -rule ”CLIENT.VLAN.ID.EQ(100)” -action
action_1
12
13 add appqoe policy appqoe_3G -rule ”CLIENT.VLAN.ID.EQ(200)” -action
action_2
14
15 bind lb vserver vsrv-wireless -policyName appqoe_4G -priority 100
16
17 bind lb vserver vsrv-wireless -policyName appqoe_3G -priority 110

The NetScaler T1 model is capable to receive the subscriber information dynamically through Gx or
Radius or Radius and Gx interface and apply different TCP profile on a per-subscriber basis.

Command:

1 add appqoe action action_1 -priority HIGH -tcpprofile nstcpprofile1

2
3 add appqoe action action_2 -priority HIGH -tcpprofile nstcpprofile2
4
5 add appqoe policy appqoe_4G -rule ”SUBSCRIBER.RULE_ACTIVE(\”3G\”)” -
action action_1
6

© 1999-2018 Citrix Systems, Inc. All rights reserved. 502

NetScaler 12.0

7 add appqoe policy appqoe_3G -rule ”SUBSCRIBER.RULE_ACTIVE(\”4G\”)” -

action action_2

For integration of the NetScaler T1 model with operator control-plane network, see Telco Subscriber
Management.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Scalability

January 6, 2019

Contributed by:
C

Because TCP optimization is resource intensive, a single NetScaler appliance, even a high end
–appliance, might not be able to sustain high Gi-LAN throughputs. To expand the capacity of your
network, you can deploy NetScaler appliances in an N+1 cluster formation. In a cluster deployment,
the NetScaler appliances work together as a single system image. The client traffic is distributed
across the cluster nodes with the help of external switch device.

Topology

Figure 1 is an example of a cluster consisting of four T1300-40G nodes.

The setup shown in Figure 1 has the following properties:

1. All cluster nodes belong to the same network (also known as an L2 cluster).
2. Data plane and backplane traffic are handled by different switches.
3. Assuming Gi-LAN throughput is 200 Gbps and that a T1300-40G appliance can sustain 80Gbps
of throughput, we need three T1300-40G appliances. To provide redundancy in case of single
cluster node failure, we deploy four appliances in total.
4. Each node will receive up to 67Gbps of traffic (50Gbps in normal operating conditions and
67Gbps in case of single cluster node failure), so it needs 2x40Gbps connections to the up-
stream switch. To provide redundancy in case of switch failure, we deploy a couple of upstream
switches and double the number of connections.
5. Cluster Link Aggregation (CLAG) is used to distribute traffic across cluster nodes. A single CLAG
handles both client and server traffic. Link Redundancy is enabled on the CLAG, so only one

© 1999-2018 Citrix Systems, Inc. All rights reserved. 503

NetScaler 12.0

“subchannel” is selected at any given time and handles the traffic. If some link fails or through-
put falls below specified threshold, the other subchannel is selected.
6. The upstream switch performs symmetric port-channel load balancing (for example, source-
dest-ip-only algorithm of Cisco IOS 7.0(8) N1(1)) so that forward and reverse traffic flows are
handled by the same cluster node. This property is desirable because it eliminates packet re-
ordering, which would degrade TCP performance.
7. Fifty percent of data traffic is expected to be steered to backplane, which means each node will
steer up to 34Gbps to other cluster nodes (25Gbps in normal operating conditions and 34Gbps
in case of single cluster node failure). Thus, each node needs at least 4x10G connections to
the backplane switch. To provide redundancy in case of switch failure, we deploy a couple of
backplane switches and double the number of connections. Link redundancy is not currently
supported for backplane, so Cisco VPC or equivalent technology is desired to achieve switch-
level redundancy.
8. MTU size of steered packets is 1578 bytes, so backplane switches must support an MTU more
than 1500 bytes.

Note: The design depicted in Figure 1 is also applicable to T1120 and T1310 appliances. For T1310 we
would use 40GbE interfaces for the backplane connections, since it lacks 10GbE ports.

Note: While this document uses Cisco VPC as an example, if working with non-Cisco switches alternate
equivalent solutions could be used, such as Juniper’s MLAG.

Note: While other topologies such as ECMP instead of CLAG are possible, they are not currently sup-
ported for this particular use case.

Configuring TCP Optimization in a NetScaler T1000 Cluster

After physical installation, physical connectivity, software installation, and licensing are completed,
you can proceed with the actual cluster configuration. The configurations described below apply to
the cluster depicted in Figure 1.

Note: For more information about cluster configuration, see “Setting up a NetScaler cluster.”

Assume that the four T1300 nodes in Figure 1 have the following NSIP addresses:

Four T1300 nodes with NSIP address:

1 T1300-40-1: 10.102.29.60
2 T1300-40-2: 10.102.29.70
3 T1300-40-3: 10.102.29.80
4 T1300-40-4: 10.102.29.90

The cluster will be managed through the cluster IP (CLIP) address, which is assumed to be 10.78.16.61.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 504

NetScaler 12.0

Setting Up the Cluster

To begin configuring the cluster shown in Figure 1, log on to the first appliance that you want to add
to the cluster (for example, T1300-40-1) and do the following.
1. At the command prompt, enter the following commands:
Command:

1 > add cluster instance 1

2 > add cluster node 0 10.102.29.60 -state ACTIVE
3 > add ns ip 10.102.29.61 255.255.255.255 -type clip
4 > enable cluster instance 1
5 > save ns config
6 > reboot ‒ warm

2. After the appliance restarts, connect to the Cluster IP (CLIP) address and add the rest of the nodes
to the cluster:
Command:

1 > add cluster node 1 10.102.29.70 -state ACTIVE

2 > add cluster node 2 10.102.29.80 -state ACTIVE
3 > add cluster node 3 10.102.29.90 ‒ state ACTIVE
4 > save ns config

3. Connect to the NSIP address of each of the newly added nodes and join the cluster:
Command:

1 > join cluster -clip 10.102.29.61 -password nsroot

2 > save ns config
3 > reboot ‒ warm

4. After the nodes restart, proceed with backplane configuration. On the cluster IP address, enter the
following commands to create an LACP channel for the backplane link of each cluster node:
Command:

1 > set interface 0/10/[1-8] ‒ lacpkey 1 ‒ lacpmode ACTIVE

2 > set interface 1/10/[1-8] ‒ lacpkey 2 ‒ lacpmode ACTIVE
3 > set interface 2/10/[1-8] ‒ lacpkey 3 ‒ lacpmode ACTIVE
4 > set interface 3/10/[1-8] ‒ lacpkey 4 ‒ lacpmode ACTIVE

5. Similarly, configure dynamic LA and VPC on the backplane switches. Make sure the MTU of the
backplane switch interfaces is at least 1578 bytes.
6. Verify the channels are operational:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 505

NetScaler 12.0

Command:

1 > show channel 0/LA/1

2 > show channel 1/LA/2
3 > show channel 2/LA/3
4 > show channel 3/LA/4

7. Configure the cluster node backplane interfaces.

Command:

1 > set cluster node 0 -backplane 0/LA/1

2 > set cluster node 1 -backplane 1/LA/2
3 > set cluster node 2 -backplane 2/LA/3
4 > set cluster node 3 ‒ backplane 3/LA/4

8. Check the cluster status and verify that the cluster is operational:

1 > show cluster instance

2 > show cluster node

For more information on cluster setup, see “Setting up aNetScaler cluster”

Distributing Traffic Across Cluster Nodes

After you have formed theNetScaler cluster, deploy Cluster Link Aggregation (CLAG) to distribute traffic
across cluster nodes. A single CLAG link will handle both client and server traffic.

On the cluster IP address, execute the following commands to create the Cluster Link Aggregation
(CLAG) group shown in Figure 1:

Command:

1 > set interface 0/40/[1-4] -lacpMode active -lacpKey 5 -lagType Cluster

2 > set interface 1/40/[1-4] -lacpMode active -lacpKey 5 -lagType Cluster
3 > set interface 2/40/[1-4] -lacpMode active -lacpKey 5 -lagType Cluster
4 > set interface 3/40/[1-4] -lacpMode active -lacpKey 5 -lagType Cluster

Configure dynamic link aggregation on the external switches.

Then, enable Link Redundancy as follows:

Code:

1 > set channel CLA/1 -linkRedundancy ON -lrMinThroughput 240000

© 1999-2018 Citrix Systems, Inc. All rights reserved. 506

NetScaler 12.0

Finally, check the channel status by entering:

Command:

1 > show channel CLA/1

The channel should be UP and the actual throughput should be 320000.

For more information about cluster link aggregation, see the following topics:

• Dynamic Cluster Link Aggregation

• Link Redundancy in a Cluster with LACP.

Because we will be using MAC-based forwarding (MBF), configure a linkset and bind it to the CLAG
group as follows:

Command:

1 > add linkset LS/1

2 > bind linkset LS/1 -ifnum CLA/1

More information about linksets, see the following topics:

• Configuring Linksets
• Using Cluster LA Channel with Linksets

Configuring VLAN and IP Addresses

We will be using striped IP configuration, which means that IP addresses are active on all nodes (de-
fault setting). See “Striped, Partially Striped, and Spotted Configurations” for more information about
this topic.

1. Add the ingress and egress SNIPs:

Command:

1 > add ns ip 172.16.30.254 255.255.255.0 ‒ type SNIP

2 > add ns ip 172.16.31.254 255.255.255.0 ‒ type SNIP
3 > add ns ip6 fd00:172:16:30::254/112 ‒ type SNIP
4 > add ns ip6 fd00:172:16:31::254/112 ‒ type SNIP

2. Add the corresponding ingress and egress VLANs:

Command:

1 > add vlan 30 -aliasName wireless

2 > add vlan 31 -aliasName internet

© 1999-2018 Citrix Systems, Inc. All rights reserved. 507

NetScaler 12.0

3. Bind VLANs with IPs and linkset:

Command:

1 > bind vlan 31 -ifnum LS/1 -tagged

2 > bind vlan 30 -ifnum LS/1 -tagged
3 > bind vlan 30 -IPAddress 172.16.30.254 255.255.255.0
4 > bind vlan 31 -IPAddress 172.16.31.254 255.255.255.0
5 > bind vlan 30 -IPAddress fd00:172:16:30::254/112
6 > bind vlan 31 -IPAddress fd00:172:16:31::254/112

More ingress and egress VLANs can be added if needed.

Configuring TCP Optimization

At this point, we have applied all cluster specific commands. To complete the configuration, follow
the steps described in “[TCP optimization configuration]/en-us/netscaler/12/netscaler-support-for-
telecom-service-providers/NS_TCP_optimization/NS_TCP_opt_config.html)”.

Configuring Dynamic Routing

A NetScaler cluster can be integrated into the dynamic routing environment of the customer’s net-
work. Following is an example of dynamic routing configuration using BGP routing protocol (OSPF is
also supported).

1. From the CLIP address, enable BGP and dynamic routing on ingress and egress IP addresses:

Command:

1 > enable ns feature bgp

2 > set ns ip 172.16.30.254 ‒ dynamicRouting ENABLED
3 > set ns ip 172.16.31.254 ‒ dynamicRouting ENABLED

2. Open vtysh and configure BGP for the egress side:

Code:

1 > shell
2 root@ns# vtysh
3 ns# configure terminal
4 ns(config)# router bgp 65531
5 ns(config-router)# network 10.0.0.0/24
6 ns(config-router)# neighbor 172.16.31.100 remote-as 65530
7 ns(config-router)# neighbor 172.16.31.100 update-source 172.16.31.254
8 ns(config-router)# exit

© 1999-2018 Citrix Systems, Inc. All rights reserved. 508

NetScaler 12.0

9 ns(config)# ns route-install propagate

10 ns(config)# ns route-install default
11 ns(config)# ns route-install bgp
12 ns(config)# exit

3. Configure the egress-side BGP peer to advertise the default route to the NetScaler cluster. For
example:

Command:

1 router bgp 65530

2  bgp router-id 172.16.31.100
3  network 0.0.0.0/0
4  neighbor 172.16.31.254 remote-as 65531

4. Follow similar steps to configure the ingress side.

5. From vtysh verify that configuration is propagated to all cluster nodes, by entering:

Command:

1 ns# show running-config

6. Finally, log on to NSIP address of each cluster node and verify routes advertised from BGP peer:

Command:

1 > show route | grep BGP

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Optimizing TCP Performance using TCP Nile

September 17, 2018

Contributed by:
C

TCP uses the following optimization techniques and congestion control strategies (or algorithms) to
avoid network congestion in data transmission.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 509

NetScaler 12.0

Congestion Control Strategies

The Transmission Control Protocol (TCP) has long been used to establish and manage Internet connec-
tions, handle transmission errors, and smoothly connect web applications with client devices. But
network traffic has become more difficult to control, because packet loss does not depend only on
the congestion in the network, and congestion does not necessarily cause packet loss. Therefore, to
measure congestion, a TCP algorithm should focus on both packet loss and bandwidth.

NILE Algorithm

Citrix Systems has developed a new congestion-control algorithm, NILE, a TCP optimization algorithm
designed for high-speed networks such as LTE, LTE advanced and 3G. Nile addresses unique chal-
lenges caused by fading, random or congestive losses, link layer retransmissions and carrier aggre-
gation.

The NILE algorithm:

• Bases queue-latency estimates on round-trip time measurements.

• Uses a congestion-window-increase function that is inversely proportional to the measured
queue latency. This method results in approaching the network congestion point more slowly
than does the standard TCP method, and reduces the packet losses during congestion.
• Can distinguish between random loss and congestion based loss on the network by using the
estimated queue latency.

The telecom service providers can use the NILE algorithm in their TCP infrastructure to:

• Optimize mobile and long-distance networks— The NILE algorithm achieves higher throughput
compared to standard TCP. This feature is especially important for mobile and long-distance
networks.
• Decrease application perceived latency and enhance subscriber experience— The Nile algo-
rithm uses packet loss information to determine whether the transmission-window size should
be increased or decreased, and uses queuing delay information to determine the size of the
increment or decrement. This dynamic setting of transmission-window size decreases the
application latency on the network.

To configure NILE support using the command line interface

At the command prompt, type the following:

1 set ns tcpProfile <name> [-flavor NILE]

© 1999-2018 Citrix Systems, Inc. All rights reserved. 510

NetScaler 12.0

Configuring NILE support using the configuration utility

1. Navigate to System> Profiles> TCP Profiles and click TCP profiles.

2. From the TCP Flavor drop-down list, select NILE.

Example:

1 set ns tcpProfile tcpprofile1 -flavor NILE

Proportional Rate Recovery (PRR) Algorithm

TCP Fast Recovery mechanisms reduce web latency caused by packet losses. The new Proportional
Rate Recovery (PRR) algorithm is a fast recovery algorithm that evaluates TCP data during a loss recov-
ery. It is patterned after Rate-Halving, by using the fraction that is appropriate for the target window
chosen by the congestion control algorithm. It minimizes window adjustment, and the actual window
size at the end of recovery is close to the Slow-Start threshold (ssthresh).

TCP Fast Open (TFO)

TCP Fast Open (TFO) is a TCP mechanism that enables speedy and safe data exchange between a
client and a server during TCP’s initial handshake. This feature is available as a TCP option in the TCP
profile bound to a virtual server of a NetScaler appliance. TFO uses a TCP Fast Open Cookie (a secu-
rity cookie) that the NetScaler appliance generates to validate and authenticate the client initiating a
TFO connection to the virtual server. By using the TFO mechanism, you can reduce an application’s
network latency by the time required for one full round trip, which significantly reduces the delay
experienced in short TCP transfers.

How TFO works

When a client tries to establish a TFO connection, it includes a TCP Fast Open Cookie with the initial
SYN segment to authenticate itself. If authentication is successful, the virtual server on the NetScaler
appliance can include data in the SYN-ACK segment even though it has not received the final ACK
segment of the three-way handshake. This saves up to one full round-trip compared to a normal TCP
connection, which requires a three-way handshake before any data can be exchanged.

A client and a backend server perform the following steps to establish a TFO connection and exchange
data securely during the initial TCP handshake.

1. If the client does not have a TCP Fast Open Cookie to authenticate itself, it sends a Fast Open
Cookie request in the SYN packet to the virtual server on the NetScaler appliance.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 511

NetScaler 12.0

2. If the TFO option is enabled in the TCP profile bound to the virtual server, the appliance gen-
erates a cookie (by encrypting the client’s IP address under a secret key) and responds to the
client with a SYN-ACK that includes the generated Fast Open Cookie in a TCP option field.
3. The client caches the cookie for future TFO connections to the same virtual server on the appli-
ance.
4. When the client tries to establish a TFO connection to the same virtual server, it sends SYN that
includes the cached Fast Open Cookie (as a TCP option) along with HTTP data.
5. The NetScaler appliance validates the cookie, and if the authentication is successful, the server
accepts the data in the SYN packet and acknowledges the event with a SYN-ACK, TFO Cookie,
and HTTP Response.
Note: If the client authentication fails, the server drops the data and acknowledges the event only
with a SYN indicating a session timeout.
1. On the server side, if the TFO option is enabled in a TCP profile bound to a service, the NetScaler
appliance determines whether the TCP Fast Open Cookie is present in the service to which it is
trying to connect.
2. If the TCP Fast Open Cookie is not present, the appliance sends a cookie request in the SYN
packet.
3. When the backend server sends the Cookie, the appliance stores the cookie in the server infor-
mation cache.
4. If the appliance already has a cookie for the given destination IP pair, it replaces the old cookie
with the new one.
5. If the cookie is available in the server information cache when the virtual server tries to recon-
nect to the same backend server by using the same SNIP address, the appliance combines the
data in SYN packet with the cookie and sends it to the backend server.
6. The backend server acknowledges the event with both data and a SYN.
Note: If the server acknowledges the event with only a SYN segment, the NetScaler appliance immedi-
ately resends the data packet after removing the SYN segment and the TCP options from the original
packet.

Configuring TCP Fast Open

To use the TCP Fast Open (TFO) feature, enable the TCP Fast Open option in the relevant TCP profile
and set the TFO Cookie Timeout parameter to a value that suits the security requirement for that pro-
file.

To enable or disable TFO by using the command line

At the command prompt, type one of the following commands to enable or disable TFO in a new or
existing profile.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 512

NetScaler 12.0

Note: The default value is DISABLED.

1 add tcpprofile <TCP Profile Name> - tcpFastOpen ENABLED | DISABLED

2 set tcpprofile <TCP Profile Name> - tcpFastOpen ENABLED | DISABLED
3 unset tcpprofile <TCP Profile Name> - tcpFastOpen

Examples:
add tcpprofile Profile1 – tcpFastOpen
Set tcpprofile Profile1 – tcpFastOpen Enabled
unset tcpprofile Profile1 – tcpFastOpen

To set TCP Fast Open cookie timeout value by using the command line interface

At the command prompt, type:

1 set tcpparam ‒ tcpfastOpenCookieTimeout <Timeout Value>

Example:

1 set tcpprofile ‒ tcpfastOpenCookieTimeout 30secs

To configure the TCP Fast Open by using the GUI

1. Navigate to Configuration > System > Profiles > and then click Edit to modify a TCP profile.
2. On the Configure TCP Profile page, select the TCP Fast Open checkbox.
3. Click OK and then Done.

To Configure the TCP Fast Cookie timeout value by using the GUI

Navigate to Configuration > System > Settings > Change TCP Parameters and then Configure TCP
Parameters page to set the TCP Fast Open Cookie timeout value.

TCP Hystart

A new TCP profile parameter, hystart, enables the Hystart algorithm, which is a slow-start algorithm
that dynamically determines a safe point at which to terminate (ssthresh). It enables a transition to
congestion avoidance without heavy packet losses. This new parameter is disabled by default.
If congestion is detected, Hystart enters a congestion avoidance phase. Enabling it gives you better
throughput in high-speed networks with high packet loss. This algorithm helps maintain close to max-
imum bandwidth while processing transactions. It can therefore improve throughput.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 513

NetScaler 12.0

Configuring TCP Hystart

To use the Hystart feature, enable the Cubic Hystart option in the relevant TCP profile.

To configure Hystart by using the command line interface (CLI)

At the command prompt, type one of the following commands to enable or disable Hystart in a new
or existing TCP profile.

1 add tcpprofile <profileName> -hystart ENABLED

2 set tcpprofile <profileName> -hystart ENABLED
3 unset tcprofile <profileName> -hystart

Examples:

1 add tcpprofile Profile1 ‒ tcpFastOpen

2 Set tcpprofile Profile1 ‒ tcpFastOpen Enabled
3 unset tcpprofile Profile1 ‒ tcpFastOpen

To configure Hystart support by using the GUI

1. Navigate to Configuration > System > Profiles > and click Edit to modify a TCP profile.
2. On the Configure TCP Profile page, select the Cubic Hystart check box.
3. Click OK and then Done.

Optimization Techniques

TCP uses the following optimization techniques and methods for optimized flow controls.

Policy based TCP Profile Selection

Network traffic today is more diverse and bandwidth-intensive than ever before. With the increased
traffic, the effect that Quality of Service (QoS) has on TCP performance is significant. To enhance QoS,
you can now configure AppQoE policies with different TCP profiles for different classes of network
traffic. The AppQoE policy classifies a virtual server’s traffic to associate a TCP profile optimized for a
particular type of traffic, such as 3G, 4G, LAN, or WAN.

To use this feature, create a policy action for each TCP profile, associate an action with AppQoE poli-
cies, and bind the policies to the load balancing virtual servers.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 514

NetScaler 12.0

Configuring Policy Based TCP Profile Selection

Configuring policy based TCP profile selection consists of the following tasks:

• Enabling AppQoE. Before configuring the TCP profile feature, you must enable the AppQoE fea-
ture.
• Adding AppQoE Action. After enabling the AppQoE feature, configure an AppQoE action with a
TCP profile.
• Configuring AppQoE based TCP Profile Selection. To implement TCP profile selection for differ-
ent classes of traffic, you must configure AppQoE policies with which your NetScaler appliance
can distinguish the connections and bind the correct AppQoE action to each policy.
• Binding AppQoE Policy to Virtual Server. Once you have configured the AppQoE policies, you
must bind them to one or more load balancing, content switching, or cache redirection virtual
servers.

Configuring using the command line interface

To enable AppQoE by using the command line interface:

At the command prompt, type the following commands to enable the feature and verify that it is en-
abled:

1 enable ns feature appqoe

2
3 show ns feature

To bind a TCP profile while creating an AppQoE action using the command line interface

At the command prompt, type the following AppQoE action command with tcpprofiletobind option.

Binding a TCP Profile:

1 add appqoe action <name> [-priority <priority>] [-respondWith ( ACS |

NS ) [<CustomFile>] [-altContentSvcName <string>] [-altContentPath <
string>] [-maxConn <positive_integer>] [-delay <usecs>]] [-polqDepth
<positive_integer>] [-priqDepth <positive_integer>] [-
dosTrigExpression <expression>] [-dosAction ( SimpleResponse |
HICResponse )] [-tcpprofiletobind <string>]
2
3 show appqoe action

© 1999-2018 Citrix Systems, Inc. All rights reserved. 515

NetScaler 12.0

To configure an AppQoE policy by using the command line interface

At the command prompt, type:

1 add appqoe policy <name> -rule <expression> -action <string>

To bind an AppQoE policy to load balancing, cache redirection or content switching virtual
servers by using the command line interface

At the command prompt, type:

1 bind cs vserver cs1 -policyName <appqoe_policy_name> -priority <

priority>
2 bind lb vserver <name> - policyName <appqoe_policy_name> -priority <
priority>
3 bind cr vserver <name> -policyName <appqoe_policy_name> -priority <
priority>

Example:

1 add ns tcpProfile tcp1 -WS ENABLED -SACK ENABLED -WSVal 8 -nagle

ENABLED -maxBurst 30 -initialCwnd 16 -oooQSize 15000 -minRTO 500 -
slowStartIncr 1 -bufferSize 4194304 -flavor BIC -KA ENABLED -
sendBuffsize 4194304 -rstWindowAttenuate ENABLED -spoofSynDrop
ENABLED -dsack enabled -frto ENABLED -maxcwnd 4000000 -fack ENABLED
-tcpmode ENDPOINT
2
3 add appqoe action appact1 -priority HIGH -tcpprofile tcp1
4
5 add appqoe policy apppol1 -rule ”client.ip.src.eq(10.102.71.31)” -
action appact1
6
7 bind lb vserver lb2 -policyName apppol1 -priority 1 -
gotoPriorityExpression END -type REQUEST
8
9 bind cs vserver cs1 -policyName apppol1 -priority 1 -
gotoPriorityExpression END -type REQUEST

Configuring Policy based TCP Profiling using the GUI

To enable AppQoE by using the GUI

1. Navigate to System> Settings.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 516

NetScaler 12.0

2. In the details pane, click Configure Advanced Features.

3. In the Configure Advanced Features dialog box, select the AppQoE check box.
4. Click OK.

To configure AppQoE policy by using the GUI

1. Navigate to App-Expert > AppQoE > Actions.

2. In the details pane, do one of the following:
3. To create a new action, click Add.
4. To modify an existing action, select the action, and then click Edit.
5. In the Create AppQoE Action or the Configure AppQoE Action screen, type or select values
for the parameters. The contents of the dialog box correspond to the parameters described in
“Parameters for configuring the AppQoE Action” as follows (asterisk indicates a required param-
eter):
a) Name—name
b) Action type—respondWith
c) Priority—priority
d) Policy Queue Depth—polqDepth
e) Queue Depth—priqDepth
f) DOS Action—dosAction

6. Click Create.

To bind AppQoE policy by using the GUI

1. Navigate to Traffic Management > Load Balancing > Virtual Servers, select a server and then
click Edit.
2. In the Policies section and click (+) to bind an AppQoE policy.
3. In the Policies slider, do the following:
a) Select a policy type as AppQoE from the drop-down list.
b) Select a traffic type from the drop-down list.
4. In the Policy Binding section, do the following:
a) Click New to create a new AppQoE policy.
b) Click Existing Policy to select an AppQoE policy from the drop-down list.
5. Set the binding priority and click Bind to the policy to the virtual server.
6. Click Done.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 517

NetScaler 12.0

SACK Block Generation

TCP performance slows down when multiple packets are lost in one window of data. In such a sce-
nario, a Selective Acknowledgement (SACK) mechanism combined with a selective repeat retransmis-
sion policy overcomes this limitation. For every incoming out-of-order packet, you must generate a
SACK block.

If the out-of-order packet fits in the reassembly queue block, insert packet info in the block, and set
the complete block info as SACK-0. If an out-of-order packet does not fit into reassembly block, send
the packet as SACK-0 and repeat the earlier SACK blocks. If an out-of-order packet is a duplicate and
packet info is set as SACK-0 then D-SACK the block.

Note: A packet is considered as D-SACK if it is an acknowledged packet, or an out of order packet

which is already received.

Client Reneging

A NetScaler appliance can handle client reneging during SACK based recovery.

Memory checks for marking end_point on PCB is not considering total available
memory

In a NetScaler appliance, if the memory usage threshold is set to 75 percent instead of using the total
available memory, it causes new TCP connections to bypass TCP optimization.

Unnecessary retransmissions due to missing SACK blocks

In a non-endpoint mode, when you send DUPACKS, if SACK blocks are missing for few out of order
packets, triggers additional retransmissions from the server.

SNMP for number of connections bypassed optimization because of overload

The following SNMP ids have been added to a NetScaler appliance to track number of connections
bypassed TCP optimization due to overload.

1. 1.3.6.1.4.1.5951.4.1.1.46.13 (tcpOptimizationEnabled). To track the total number of connections

enabled with TCP optimization.
2. 1.3.6.1.4.1.5951.4.1.1.46.132 (tcpOptimizationBypassed). To track the total number of connec-
tions bypassed TCP Optimization.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 518

NetScaler 12.0

Dynamic Receive Buffer

To maximize TCP performance, a NetScaler appliance can now dynamically adjust the TCP receive
buffer size.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

CQA and Adaptive TCP Optimization

March 14, 2019

Contributed by:
C
Note

If you are interested in using CQA Reporting and Adaptive TCP, please contact Citrix sales team.

Mobile networks have unique characteristics that might affect TCP performance. By leveraging
NetScaler Connection Quality Analytics (CQA) and Adaptive TCP optimization techniques, mobile
operators can analyze the overall network behavior to provide an improved user experience and
increased levels of subscriber satisfaction.

Connection Quality Analytics (CQA)

When a client sends a TCP request, CQA monitors and extracts a large amount of detailed TCP layer
data during an active connection. With the extracted data, CQA uses a heuristic learning algorithm
to derive important characteristics of the connection, for example, network type (2G, 3G or 4G), con-
gestion level (None, Low, Medium, or High), and signal quality (Excellent, Good, Fair or Poor) on a per-
subscriber basis. NetScaler then stores the information in a subscriber store (so that it can be available
for the next TCP connections from the same subscriber) and exports the data to the AppFlow collec-
tors. The stored information is as raw values in a composite format that defines the network type,
congestion level, and signal quality of the subscriber connection. The detected characteristics can
be used for other applications, for example, to intelligently apply different TCP profiles for different
network characteristics. For more information, see topic Adaptive TCP.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 519

NetScaler 12.0

Benefit

Enable mobile operators to:

1. Understand congestion level of a subscriber network.

2. Analyzing overall network behavior of a subscriber.

Prerequisites

The CQA feature works on Telco platforms with the purchase of a basic CBM license and CBM Pre-
mium license and for otherNetScaler platforms, the feature works with the purchase of a CNS Plat-
inum license. Before you configure the TCP optimization feature, your appliance must have a suitable
license installed.

License support for Telco platforms:

• CBM_TXXX_SERVER_Retail.lic
• CBM_TPRE_SERVER_Retail.lic
• CNS_WEBF_SSERVER_Retail.lic

Where XXX is the throughput, for example, NetScaler T1000.

License support for otherNetScaler platforms:

• CNS_XXX_SERVER_PLT_Retail.lic

Where XXX is the throughput.

1 > show license

2
3              License status:
4
5
6
7
8                                            …
9
10                                      Adaptive TCP: YES
11
12
13
14
15              Connection Quality Analytics: YES

© 1999-2018 Citrix Systems, Inc. All rights reserved. 520

NetScaler 12.0

Configuring Connection Quality Analytics (CQA)

To optimize a TCP traffic using CQA technique, begin by enabling CQA and Appflow features on the
appliance. When the appliance receives a client TCP connection request, it monitors the incoming
traffic and uses the CQA configuration to derive CQA parameters from the raw TCP metrics.

Configure CQA by using the CLI

To configure CQA on a NetScaler appliance, you can perform the following tasks:

1. Enable CQA
2. Enable AppFlow Collector
3. Configure CQA Parameters
4. Verify CQA feature
5. Using CQA-based PI expressions

Enabling CQA

If you want the NetScaler appliance to extract TCP raw metric and derive CQA parameters, you must
enable the CQA feature and set adaptive TCP to ON. You must also enable the Appflow feature so that
the appliance can send the derived CQA data for network analysis.

To enable CQA:

At the command prompt, type the following command:

1 enable ns feature cqa

To enable Appflow collector:

You must have at least one Appflow collector to be running in your appliance. At the command
prompt, type the following command:

1 enable ns feature appflow

Configuring CQA Parameters

For CQA to derive parameters such as network type, signal quality, and congestion level, you must
configure CQA settings on the appliance.

To configure CQA:

At the command prompt, type the following command:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 521

NetScaler 12.0

1 set ns cqaparam [-harqretxdelay <positive_integer>] [-net1label <string

>] [-minRTTNet1 <positive_integer>][-lr1coeflist <string>] [-
lr1probthresh <float>] [-net1cclscale <string>] [-net1csqscale <
string>][-net1logcoef <string>] [-net2label <string>][-minRTTNet2 <
positive_integer>] [-lr2coeflist <string>][-lr2probthresh <float>]
[-net2cclscale <string>][-net2csqscale <string>] [-net2logcoef <
string>] [-net3label <string>][-minRTTNet3 <positive_integer>] [-
net3cclscale <string>][-net3csqscale <string>] [-net3logcoef <string
>]

Example:

1 set ns cqaparam -harqretxdelay 7 -net1label 2g -minRTTNet1 25 -

lr1coeflist ”intercept=4.95,thruputavg=5.92,iaiavg=-189.48,rttmin
=-15.75,loaddelayavg=0.01,noisedelayavg=-2.59” -lr1probthresh 6.00e
-01 -net1cclscale ”25,50,75” -net1csqscale ”25,50,75” -net1logcoef ”
1.49,3.62,-0.14,1.84,4.83” -net2label 3g -minRTTNet2 30 -lr2coeflist
”intercept=16.4,thruputavg=0.05981,iai1ms=53.27,iai2ms=-50.44,
iaiavg=-189.48,isiavg=-203.42,rttmin=-198.42,rttmax=-9.10,rttavg
=9.07,loaddelayavg=55.14,noisedelayavg=-68.50” -lr2probthresh 5.00e
-01 -net2cclscale ”25,50,75” -net2csqscale ”25,50,75” -net2logcoef ”
2.39,1.76,-0.08,1.73,4.74” -net3label 4g -minRTTNet3 35 -
net3cclscale ”25,50,75” -net3csqscale ”25,50,75” -net3logcoef ”
1.49,3.62,-0.14,1.84,4.83”

Where,

net1label is the name of the network label 1. Maximum Length: 15

net1csqscale is the signal quality score limit, such as Excellent, Good, or Fair. Maximum Length: 63

net1cclscale is the congestion level limit such as None, Low, or Medium. Maximum Length: 63

Note

For proper configuration of CQA parameters, please contact Citrix Customer Support.

Verify CQA parameters

To verify the CQA parameters, type the following command:

1 sh ns cqaparam
2 Configured CQA parameters:
3 harqretxdelay (in ms): 7
4 net1label: 2g

© 1999-2018 Citrix Systems, Inc. All rights reserved. 522

NetScaler 12.0

5 net1label Coeflist: intercept=4.95,thruputavg=5.92,iaiavg

=-189.48,rttmin=-15.75,loaddelayavg=0.01,noisedelayavg
=-2.59
6 net1label Probthresh: 0.600000
7 net1label CCL Scale: 25,50,75
8 net1label CSQ Scale: 25,50,75
9 net1label CRQ LogCoef: 1.49,3.62,-0.14,1.84,4.83
10 net1minrtt (in ms): 25
11 net2label: 3g
12 net2label Coeflist: intercept=16.4,thruputavg=0.05981,iai1ms
=53.27,iai2ms=-50.44,iaiavg=-189.48,isiavg=-203.42,rttmin
=-198.42,rttmax=-9.10,rttavg=9.07,loaddelayavg=55.14,
noisedelayavg=-68.50
13 net2label Probthresh: 0.500000
14 net2label CCL Scale: 25,50,75
15 net2label CSQ Scale: 25,50,75
16 net2label CRQ LogCoef: 2.39,1.76,-0.08,1.73,4.74
17 net2minrtt (in ms): 30
18 net3label: 4g
19 net3label CCL Scale: 25,50,75
20 net3label CSQ Scale: 25,50,75
21 net3label CRQ LogCoef: 1.49,3.62,-0.14,1.84,4.83
22 net3minrtt(in ms): 35
23 Done

Verifying CQA

To verify if the CQA parameters are derived during an active TCP action, execute the following com-
mand. Note: You can execute the command only if the TCP connection is open and active.

1 T1300-10-2> show connectiontable connection.ip.eq(XXX) -detail fulL+

2
3 srcIP          : 192.168.134.3     dstIP          : 192.168.216.72   
svcType        : TCP               C
4
5 srcPort        : 40073             dstPort        : 80               
state          : ESTABLISHED
6
7 svcName        : vsrv-internet     idleTime       : 7                
mss            : 1460
8
9 Traffic Domain : 0                 priority       : Surge Priority   
connid         : 30064847984
10

© 1999-2018 Citrix Systems, Inc. All rights reserved. 523

NetScaler 12.0

11 irs            : 1702584155        rcvNxt         : 1702584323       

maxAck         : 1702584323
12
13 rcvWnd         : 0                 advWnd         : 8000000          
maxRcvbuf      : 8000000
14
15 RxQinByte      : 168               iss            : 1998428965       
sndNxt         : 2002733045
16
17 sndUnack       : 2002731585        maxSndbuf      : 8000000
          sndBuf         : 2300
18
19 sndRecover     : 1998428965        congState      : open             
peerconnid     : 30064847967
20
21 TxQinByte      : 7997700           nTcpwaitQpkt   : 5477             
nRetxQpkt      : 1
22
23 tcpOpt         : sack ws           sackblocks     : 0                
ProfileName    : nstcp_default_profile
24
25 tcpMode        : ENDPOINT          nsWSvalue      : 7                
peerWSvalue    : 8
26
27 sndCwnd        : 595680            flavor         : BIC              
bwEstimate     : 1056
28
29 retxRetryCnt   : 2                 outoforderPkts : 0                
rttMin         : 67
30
31 rttSmoothed    : 308               rttVariance    : 3525             
rttReal(microsec) : 74427
32
33 BurstRateCntrl : DISABLED          CreditBytePrms : 0                
RateBytePerms  : 0
34
35 RateSchedulerQ : (null)            RttMin(ms)     : 66               
RttAvg(ms)     : 402
36
37 BifAvg(Bytes)  : 474824            ThrptAvg(Kbps) : 9                
RcvwndAvg(Kbytes) : 544169
38
39 Iai1msPct      : 30                Iai2msPct      : 70               
IaiSamples     : 2
40

© 1999-2018 Citrix Systems, Inc. All rights reserved. 524

NetScaler 12.0

41 CqaSamples     : 1166              NetClass       : 3g               

CongLevel      : 0.000000
42
43 SigQuality     : 0.000000 IaiAvg(us)     : 2                 IsiAvg(us)
     : 2
44
45 RcvwndMin      : 256               RetxCorr       : 0                
RetxCong       : 0
46
47 RetxPkts       : 0                 LoadDelayAvg(us) : 27               
NoiseDelayAvg(us) : 400
48
49 RttMax(ms)     : 559
50
51 AdaptiveTCP    : N/A

Using CQA-based PI Expressions

The NetScaler policy infrastructure is enhanced to use the derived CQA parameters (stored in sub-
scriber store) for string matching operations.

• NETWORK_TYPE: String value that matches the detected network type configured through the
cqaparam command interface.
• SIGNAL_QUALITY: Integer value ranging from 0 to 100 and matching the CQA signal quality pa-
rameter stored in the subscriber store (lower values indicate better signal quality).
• CONGESTION_LEVEL: Integer value ranging from 0 to 100 and matching CQA raw value of con-
gestion level parameter stored in the subscriber store (lower values indicate lower congestion).

Below are sample PI expressions with CQA parameters such as network type, congestion level, and
signal quality, evaluates an incoming traffic of network type 2G, exhibiting good or excellent signal
quality with a high congestion level:

1 ANALYTICS.CONNECTION_QUALITY.NETWORK_TYPE.EQ(”2G”) && ANALYTICS.

CONNECTION_QUALITY.SIGNAL_QUALITY.GT(60) && ANALYTICS.
CONNECTION_QUALITY.CONGESTION_LEVEL.GT(80)

Configure CQA by using the GUI

To configure CQA, you must perform the following tasks:

1. Enable CQA feature

2. Configure CQA reporting parameters.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 525

NetScaler 12.0

To enable CQA feature

1. Log on to NetScaler and navigate to Configuration> System> Settings.

2. In the details pane, click Configure Advanced features link under Settings.
3. In Configure Advanced Features page, select CQA and Appflow checkbox.

To configure CQA reporting parameter

1. Log on to NetScaler and navigate to Configuration > System > Appflow.

2. In the details pane, click Change Appflow Setting under Settings.
3. In the Configure Appflow Settings page, select CQA Reporting checkbox.
4. Click OK and Close.

Adaptive TCP Optimization

As subscribers in a telco network increase in an unprecedented rate, it is important to provide a quality

user experience to each subscriber. To achieve this, NetScaler uses an advanced optimization tech-
nique called Adaptive TCP. The technique optimizes traffic by independently adapting different TCP
profiles for each subscriber based on the information stored in a subscriber (UX) store. The UX store
contains subscriber’s details (such as network type, signal quality, and congestion level) in a com-
posite format. When a client sends a TCP request, the appliance queries the store for the subscriber
information and applies a suitable TCP optimization based on subscriber’s network conditions. The
appliance does this by enabling Adaptive TCP feature on a NetScaler TCP profile.

Benefit

Using Adaptive TCP optimization technique, a mobile operator can:

• Extract advanced and detailed insight of network conditions experienced by a mobile sub-
scriber.
• Automatically adapt traffic management actions of NetScaler based on the current network con-
ditions.

Prerequisites

The Adaptive TCP feature works only on telco traffic management platforms (such as NetScaler T1000
series and VPX-T platforms) with a Premium license. The VPX-T software and T1000 hardware appli-
ances are designed to meet the needs of telco mobile operators and service providers. Before you
configure the TCP optimization feature, your appliance must have the following license files installed:

1. Adaptive TCP

© 1999-2018 Citrix Systems, Inc. All rights reserved. 526

NetScaler 12.0

2. Connection Quality Metrics

For example, CBM_T1_SERVER_Retail.lic or CBM_TPRE_SERVER_Retail.lic

1 > show license

2
3              License status:
4
5                                            …
6
7              Adaptive TCP: YES
8
9              Connection Quality Analytics: YES

Configuring Adaptive TCP

The configuration begins by enabling CQA, Appflow, and Adaptive TCP features. Once you enable,
you can configure a normal TCP profile with ‘applyAdaptiveTcp’ option enabled and scrutinizing TCP
parameters such as TCP favor, TCP Max congestion window, Burst Rate Control (pacing), TCP Rate,
and TCP Rate Maximum Queue. When the appliance receives a TCP request, it applies a TCP profile
and Adaptive TCP logic is triggered. The logic queries the subscriber store for the subscriber’s CQA
information. Based on the derived metrics, the appliance independently adapts the TPC profile to
optimize the subscriber traffic.

Configuring Adaptive TCP by using the CLI

To configure Adaptive TCP, you must perform the following tasks:

1. Enable CQA, AppFlow, and Adaptive TCP features

2. Add load balancing virtual server for TCP traffic
3. Add load balancing virtual server for HTTP traffic
4. Set TCP profile parameters
5. Apply TCP Profile either by:
a) Associating the TCP profile to load balancing virtual server.
b) Using policy-based TCP optimization.
i. Adding an AppQoE action
ii. Adding an AppQoE policy
iii. Binding AppQoE policy to a TCP loading balancing virtual server

Enabling Adaptive TCP

© 1999-2018 Citrix Systems, Inc. All rights reserved. 527

NetScaler 12.0

If you want the appliance to optimize TCP traffic, you must enable CQA, AppFlow, and Adaptive TCP
features.

To enable Adaptive TCP feature:

At the command prompt, type the following command

1 enable ns feature adaptiveTCP cqa appflow LB

Adding a Virtual Server for TCP Traffic

A NetScaler appliance uses a TCP load balancing virtual servers for optimizing an adaptive TCP traffic.

Note: Adaptive TCP optimization technique works for HTTP traffic also.

To add a load balancing virtual server for TCP traffic:

At the command prompt, type the following:

1 add lbvserver <name> TCP <ip> <port>

Example:

1 add lbvserver tcplb TCP 10.102.29.200 80

Adding a Virtual Server for HTTP Traffic

A NetScaler appliance uses a HTTP load balancing virtual servers for optimizing HTTP traffic.

To add a load balancing virtual server for HTTP traffic:

At the command prompt, type the following:

1 add lbvserver <name> HTTP <port> -persistenceType <persistenceType> -

tcpProfileName <string>

Example:

1 add lb vserver httplb HTTP * 80 -persistenceType NONE -tcpProfileName

nstcp_default_profile_with_adtcp

Configuring TCP Profile for Adaptive TCP optimization

You can configure a normal TCP profile to apply Adaptive TCP optimization. This can done by either
adding a new profile or modifying an existing one.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 528

NetScaler 12.0

Note

Before you configure TCP profiles to apply Adaptive TCP optimization, please contact Citrix Cus-
tomer Support.

To configure a TCP profile:

At the command prompt, type the following:

1 add ns tcpProfile <name> -tcpmode (TRANSPARENT | ENPOINT) ‒

applyAdaptiveTcp (ENABLED | DISABLE)

Example:

1 add ns tcpProfile nstcp_profile_with_adtcp -tcpmode ENDPOINT -

applyAdaptiveTcp ENABLED

Applying TCP Profile

You can apply a TCP profile for Adaptive TCP optimization by either of the two ways:

• Associating adaptive TCP profile to a load balancing virtual server.

• Configuring policy-based Adaptive TCP optimization.

To apply adaptive TCP profile to a load balancing virtual server:

At the command prompt, type the following:

1 set lb vserver <name> -tcpProfileName <string>

Example:

1 set lb vserver tcplb -tcpProfileName nstcp_profile_with_adtcp

2
3 set lb vserver httplb -tcpProfileName nstcp_profile_with_adtcp

Configuring policy-based Adaptive TCP optimization

To configuring AppQoE policy-based optimization, you must complete the following tasks:

1. Add AppQoE action

2. Add AppQoE policy
3. Bind AppQoE policy to load balancing virtual server for TCP and HTTP traffic

To add an AppQoE action:

At the command prompt, type the following:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 529

NetScaler 12.0

1 add appqoe action <name> -priority <priority> ‒ tcpprofile <string>

Example:

1 add appqoe action appqoeact-adtcp -priority HIGH -tcpprofile

nstcp_profile_with_adtcp

To add an AppQoE policy:

At the command prompt, type the following:

1 add appqoe policy <name> -rule <expression> -action <string>

Example:

1 add appqoe policy appqoepol-adtcp -rule ”CLIENT.VLAN.ID.EQ(401)” -

action appqoeact-adtcp

To bind an AppQoE policy to a load balancing virtual server of HTTP and TCP traffic:
At the command prompt, type the following:

1 bind lb vserver <name> -policyName <string> -priority <positive_integer

> -gotoPriorityExpression <expression> -type (REQUEST | RESPONSE)

Example:

1 bind lb vserver tcplb -policyName appqoepol-adtcp -priority 1 -

gotoPriorityExpression END -type REQUEST
2
3 bind lb vserver httplb -policyName appqoepol-adtcp -priority 1 -
gotoPriorityExpression END -type REQUEST

Configuring Adaptive TCP by using the GUI

The GUI enables you to:
• Enable CQA and Adaptive TCP features.
• Create load balancing virtual server for TCP traffic.
• Create load balancing virtual server for HTTP traffic.
• Configure TCP profile parameters for Adaptive TCP optimization.
• Apply adaptive TCP profile to load balancing virtual server.
• Create AppQoE action for policy-based Adaptive TCP optimization.
• Create AppQoE policy for policy-based Adaptive TCP optimization.
• Bind AppQoE policy to load balancing virtual server for policy-based Adaptive TCP optimization.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 530

NetScaler 12.0

To enable Adaptive TCP feature

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

2. On the Settings page, click the Configure Advanced Features link.
3. On the Configure Advanced Features page, select the CQA and Adaptive TCP check box.
4. Click OK, and then click Close.

To create a load balancing virtual server for TCP traffic

1. Sign in to the NetScaler appliance and navigate to the Traffic Management > Load Balanc-
ing > Virtual Servers page.
2. In the details pane, click Add.
3. On the Load Balancing Virtual Server screen, set the following parameters:
a) Name. Name of the load balancing virtual server.
b) Protocol. Select protocol type as TCP.
c) IP Address Type. IP address type: IPv4 or IPv6.
d) IP Address. IPv4 or IPv6 address assigned to the virtual server.
e) Port. Port number of the virtual server.
4. Click OK to continue with configuration of other, optional, parameters. For more information,
see Creating a Virtual Server.
5. Click Create and Close.

To create a load balancing virtual server for HTTP traffic

1. Sign in to the NetScaler appliance and navigate to the Traffic Management > Load Balanc-
ing > Virtual Servers page.
2. In the details pane, click Add.
3. On the Load Balancing Virtual Server screen, set the following parameters:
a) Name. Name of the load balancing virtual server.
b) Protocol. Select protocol type as HTTP.
c) IP Address Type. IP address type: IPv4 or IPv6.
d) IP Address. IPv4 or IPv6 address assigned to the virtual server.
e) Port. Port number of the virtual server.
4. Click OK to continue with configuration of other, optional, parameters. For more information,
see Creating a Virtual Server.
5. Click Create and Close.

To set TCP profile for Adaptive TCP optimization

1. Log on to NetScaler appliance and navigate to the Configuration > System > Profiles page
2. In the Details pane, click TCP Profiles tab.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 531

NetScaler 12.0

3. In the Configure TCP Profiles page, select Apply Adaptive TCP checkbox.
4. Click OK and Close.

To apply adaptive TCP profile to load balancing virtual server for TCP traffic

1. Log on to NetScaler appliance and navigate to the Configuration > Traffic Management > Vir-
tual Servers.
2. In the details page, select a virtual server profile for TCP traffic and click Edit.
3. In the Load Balancing Virtual Server page, go to Profiles section and click pencil icon.
4. Apply the adaptive TCP profile to the virtual server.
5. Click OK and Done.

To apply adaptive TCP profile to load balancing virtual server for HTTP traffic

1. Log on to NetScaler appliance and navigate to the Configuration > Traffic Management > Vir-
tual Servers.
2. In the details page, select a virtual server profile for HTTP traffic and click Edit.
3. In the Load Balancing Virtual Server page, go to Profiles section and click pencil icon.
4. Apply the adaptive TCP profile to the HTTP virtual server.
5. Click OK and Done.

To add AppQoE action for policy-based Adaptive TCP optimization

1. Log on to NetScaler appliance and navigate to the Configuration > AppExpert > AppQoE > Ac-
tions.
2. In the details pane, click Add to create an action.
3. In the Create AppQoE Action screen, type or select values for the parameters. The contents
of the dialog box correspond to the parameters described in “Parameters for configuring the
AppQoE Action” as follows (asterisk indicates a required parameter):
a) Name—name
b) Action type—PRIORITY_QUEUING
c) TCP Profile—Apply a TCP profile by adding a new one or selecting an existing one.
d) Priority—HIGH
e) Policy Queue Depth—0
f) Queue Depth—0
g) Click Create and OK.

To add AppQoE policy for policy-based Adaptive TCP optimization

1. Log on to NetScaler appliance and navigate to the Configuration > AppExpert > AppQoE > Pol-
icy.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 532

NetScaler 12.0

2. In the details pane, click Add to create a policy.

3. In the Create AppQoE Policy screen, type or select values for the parameters. The contents
of the dialog box correspond to the parameters described in “Parameters for configuring the
AppQoE Policy” as follows (asterisk indicates a required parameter):
a) Name—name
b) Action—Associate an action to perform when the policy rule matches the TCP connection.
You can associate by adding a new action or selecting an existing one.
c) Expression—In the Rule text box, either enter the policy expression with CQA parameters
or use the expression editor to create a rule.
4. Click OK and Close.

To bind AppQoE policy to load balancing virtual server for policy-based Adaptive TCP optimiza-
tion

1. Log on to NetScaler appliance and navigate to the Configuration > Traffic Management > Load
Balancing > Virtual Servers.
2. In the details pane, select a load balancing virtual server of type HTTP or TCP and click Edit.
3. In the Load Balancing Virtual Server page, go to Policies section and click the + icon.
4. In the Policies slider page, do the following:
a) Choose policy. Policy name.
b) Choose type. Policy type as request or response.
5. Click Continue to close the slider page and go to the main page.
6. Click Done.

Analytics and Reporting

The TCP Speed Reporting is a NetScaler feature which extracts a rich set of TCP-level statistics, as a
measure of TCP download and upload performance, and is utilized in TCP Insight reports of the Citrix
Application Delivery Management (ADM) . To achieve this, NetScaler monitors each TCP connection,
locates packet bursts on an idle time-out basis and reports key metrics (such as byte count, retrans-
mitted byte count, an duration) for the identified maximum burst. In addition to this, the TCP raw
metrics such as RTT, BIF, receive window and so forth are also measured based on the optimization
type (endpoint or transparent) that you configure. The TCP Speed Reporting feature is enabled by de-
fault, supports both TCP and HTTP vServers and depends on Appflow/ULFD reporting infrastructure.
For more information, see Analytics and Reporting.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

© 1999-2018 Citrix Systems, Inc. All rights reserved. 533

NetScaler 12.0

Troubleshooting Guidelines

January 6, 2019
Contributed by:
C

Technical Support

All troubleshooting and escalation queries require a recent NetScaler techsupport bundle, which cap-
tures current configuration, firmware version installed, log files, outstanding cores, and others.
Example:

1 show techsupport
2
3 showtechsupport data collector tool - $Revision: #5 $!
4 ...
5 All the data will be collected under
6         /var/tmp/support/collector_P_192.168.121.117_18Jun2015_09_53
7 ...
8 Archiving all the data into ”/var/tmp/support/collector_P_192
.168.121.117_18Jun2015_09_53.tar.gz” ....
9 Created a symbolic link for the archive with /var/tmp/support/support.
tgz
10 /var/tmp/support/support.tgz  ---- points to ---> /var/tmp/support/
collector_P_192.168.121.117_18Jun2015_09_53.tar.gz
11
12 After a techsupport bundle has been generated, it might be copied using
SCP.

Traces

NetScaler TCP optimization issues normally require NetScaler traces to troubleshoot properly. Note
that one should try to capture traces under similar conditions, i.e. on the same cell, during the same
time of day, using the same user equipment and application, and others.
The start nstrace and stop nstrace commands might be used to capture traces:
• It’s strongly recommended that the appropriate filter is used to avoid capturing extraneous, un-
necessary packets on the trace. For instance use start nstrace -filter ‘IP == 10.20.30.40’ to only
capture packets being sent to or received from IP address 10.20.30.40, which is the user equip-
ment IP address.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 534

NetScaler 12.0

• Do not use the -tcpdump option, since it strips the nstrace headers which are required for de-
bugging.

Trace Analysis

After a NetScaler trace has been captured, it might be viewed with Wireshark 1.12 or later. Verify that
the captured traces include the appropriate NetScaler Packet Trace headers, as shown in the screen
capture below:

The additional debug headers are also visible per the illustration below:

Connection Table

When the issue is related to TCP optimization and it can be reproduced or it’s on-going, it is best to get
also the connection table when the issue occurs from the primary T1 node.

To get the table you shall need to switch to the BSD shell and run the following command:

1 shell
2 ...
3
4 nscli -U 127.0.0.1:nsroot:nsroot show connectiontable -detail full link
> /var/tmp/contable.log

Note

The command might be executed for a longer time and management CPU might be stressed at
that time (depends on the number of connection table entries), but it’s not service affecting.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Frequently Asked Questions

September 17, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 535

NetScaler 12.0

Timeouts
Important

Before using any nsapimgr knob, consult with Citrix Customer Support.

The following is a list of different idle connection timeouts that can be set on NetScaler T1 virtual
servers and services. Idle timeout set for client or server connections at the vserver or service level
are applicable only for the connections in TCP ESTABLISHED state and are idle.

• Load Balancing virtual server cltTimeout parameter specifies the time in seconds that a connec-
tion from a client to a Load Balancing virtual server must be idle, before the appliance closes
the connection.
• Service svrTimeout parameter specifies the time in seconds that a connection from the appli-
ance to a service or server must be idle, before the appliance closes the connection.
• Service cltTimeout parameter specifies the time in seconds that a connection from a client to a
service must be idle, before the appliance closes the connection.

When a service is bound to a Load Balancing virtual server, then the cltTimeout for the Load Balancing
virtual server takes precedence, and the service cltTimeout for service is ignored.

In case of there is not service bound to Load Balancing virtual server, global idle timeout, namely
tcpServer, is used for server side connections. It can be configured as follows:

Command:

1 set ns timeout ‒ tcpServer 9000

Connections in other state have different timeout values:

• Half open connections idle timeout: 120 seconds (hardcoded value)

• TIME_WAIT connections idle timeout: 40 seconds (hardcoded value)
• Half close connections idle timeout. By default it is 10s and can be configured between 1s and
600s using the snippet

Command:

1 set ns timeout ‒ halfclose 10

When half-close timeout is triggered, connection is moved to zombie state. When zombie timeout
expires, zombie cleanup kicks in and T1 sends RST on both client and server side for given connection
by default.

• Zombie timeout: Interval at which the zombie cleanup process must run to clean up inactive
TCP connections. Default timeout value is 120s and can be configured between 1s and 600s.

Command:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 536

NetScaler 12.0

1 set ns timeout ‒ zombie 120

Maximum Segment Size Table

A NetScaler T1 appliance defends against SYN flood attacks by using SYN cookies instead of maintain-
ing half-open connections on the system memory stack. The appliance sends a cookie to each client
that requests a TCP connection, but it does not maintain the states of half-open connections. Instead,
the appliance allocates system memory for a connection only upon receiving the final ACK packet, or,
for HTTP traffic, upon receiving an HTTP request. This prevents SYN attacks and allows normal TCP
communications with legitimate clients to continue uninterrupted. Specific function is enabled by
default without option to disable.

However, there is caveat as standard SYN cookies limit connections to the use of only eight Maximum
Segment Size (MSS) values. If connection MMS does not match with any predefined value, it will pick
up the next available lower value towards both client and server side.

The predefined TCP Maximum Segment Size (MSS) values are the following and can be configured
through a new nsapimgr knob.

1460 1440 1330 1220 956 536 384 128

The new MSS table:

• Need not contain Jumbo-Frame support. Even though by default 8 values are reserved in the
MSS table for jumbo frames, the table settings can be modified to include standard Ethernet-
sized frames only.
• Should have 16 values
• Should have values in descending order
• Should include 128 as the last value

If the new MSS table is valid, the table is stored and the old values are switched out at the SYN-cookie
rotation time. Otherwise the new table returns an error. Changes are applied to new connections
while existing connections preserve the old MSS table until the connections expire or are terminated.

To display the current MSS table in a NetScaler appliance, type the following command.

Command:

1 >shell
2

© 1999-2018 Citrix Systems, Inc. All rights reserved. 537

NetScaler 12.0

3 #nsapimgr -d mss_table

EXample:

1 #nsapimgr -d mss_table
2
3 MSS table
4
5 {
6 9176,9156,8192,7168,6144,4196,3072,2048,1460,1440,1330,1212,956,536,384,128
}
7
8
9 Done.

To change the mss table, type the following command:

Command:

1 >shell
2
3 #nsapimgr -s mss_table=<16 comma seperated values>

Example:

1 #nsapimgr -ys mss_table

=9176,9156,8192,7168,6144,4196,3072,2048,1460,1400,1330,1212,956,536,384,128

2
3 # nsapimgr -d mss_table
4
5 MSS table
6
7 {
8 9176,9156,8192,7168,6144,4196,3072,2048,1460,1400,1330,1212,956,536,384,128
}
9
10
11 Done.

An example using standard Ethernet-sized values is depicted below:

Example:

1 #nsapimgr -ys mss_table

=1460,1440,1420,1400,1380,1360,1340,1320,1300,1280,1260,1212,956,536,384,128

© 1999-2018 Citrix Systems, Inc. All rights reserved. 538

NetScaler 12.0

2
3 # nsapimgr -d mss_table
4
5 MSS table
6
7 {
8 1460,1440,1420,1400,1380,1360,1340,1320,1300,1280,1260,1212,956,536,384,128
}
9
10
11 Done.

To make this change permanent even after the NetScaler appliance restarts, include the command
“#nsapimgr -ys mss_table=<16 comma seperated values>” in the “/nsconfig/rc.netscaler” file. If the
“rc.netscaler” file doesn’t exist, create it under the “/nsconfig” folder, and then append the command.

Memory Overload Protection

A NetScaler Packet Processing Engine (PPE) starts bypassing connections from TCP optimization if
the memory in use by that one PPE is more than a specified high watermark value. If a PPE memory
utilization goes above ~2.6GB, then it starts bypassing any new connections from optimization. The
existing connections (ones admitted for optimization previously) continues getting optimization. This
watermark value has been purposefully selected and is not recommended for tuning.

Note

If you believe that there is a good reason to change that watermark value, contact Customer
Support.

Support for Happy Eyeballs Clients

If the NetScaler appliance receives a SYN for a destination for which the state is unknown, the appli-
ance first checks the reachability of the server and then acknowledges the client. This probing mech-
anism enables clients with dual IP stacks to discover the reachability of dual-stack internet servers.
If the client discovers that both IPv6 and IPv4 access are available, it establishes a connection to the
server that responds more quickly, and resets the other. For the connection for the NetScaler appli-
ance receives a reset, it will reset the corresponding server side connection.

Note: This feature has no user configurable TCP settings to be disabled/enabled on the NetScaler
appliance.

For more information on Happy Eyeballs support, see RFC 6555.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 539

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

NetScaler Video Optimization

September 17, 2018

Contributed by:
C

The NetScaler appliance provides optimization techniques and capabilities to optimization ABR video
traffic for video traffic over mobile networks. This improves user experience and reduces the overall
network bandwidth consumption.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Getting Started

January 6, 2019

Contributed by:
C

Media files have been driving an increasing amount of traffic over mobile networks, and migration to
faster networking technologies has dramatically increased the volume of encrypted video traffic. The
traditional media delivery technology (Progressive Download) is failing to deliver acceptable quality
of experience (QoE) at a high transmission rate. This has led to the introduction of the Adaptive Bit
Rate (ABR) protocol. It can adapt the streaming bit rate to the available network bandwidth and re-
strict streaming quality to match the capability of the handset receiving the video. However, the ABR
protocol does not work as well in mobile networks as it does over the internet. Mobile operators must,
therefore, optimize ABR traffic.

A NetScaler appliance has unique capabilities to detect incoming video traffic and selectively optimize
ABR videos.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 540

NetScaler 12.0

How NetScaler Video Optimization Works

A NetScaler appliance can identify and optimize encrypted ABR traffic (including Facebook video traf-
fic) over TCP, and YouTube ABR traffic over QUIC. The appliance has the following capabilities:

1. Detect Progressive Download (PD) videos over HTTP.

2. Detect and optimize ABR videos over HTTP.
3. Detect and optimize ABR videos over HTTPS.
4. Detect and optimize YouTube ABR videos over QUIC.

Also, the appliance uses the following support domains for detecting video traffic over TCP and QUIC
protocols.

• Unencrypted ABR videos over TCP. Appliance detects all standard compliant video streaming
web sites. The appliance detects ABR sessions by inspecting the response video payload header,
URL, and HTTP headers.
• Encrypted ABR video over TCP. Appliance detects ABR sessions using a generic and heuristic
algorithm based on domain, SSL header and traffic patterns. Using this, the appliance has a
built-in support to detect top video web sites, with 95 percent accuracy and we continue to add
support for new video types. NetScaler also has a program to provide additional verification for
top encrypted ABR sites for a region or country to ensure network coverage.
• Encrypted ABR videos over QUIC. The appliance detects ABR sessions for QUIC based video
provider, such as YouTube. The detection algorithm is on the basis of a heuristic leveraging
the QUIC headers and domain. NetScaler will continue to add support for newer video sites
using QUIC.

Benefits

Optimizing the ABR video traffic can provide the following benefits:

• Manage the network during congestion in peak hours.

• Improve video play consistency and reduce video stalling.
• Enable new video service offerings (for example, Binge-on video services).
• Enable customers to select the best sustainable video quality.
• Provide a consistent user experience for the subscriber.

Video Optimization over TCP

NetScaler optimization of ABR traffic over TCP works as follows:

1. HTTP or HTTPS traffic that the appliance receives over TCP is sent to the corresponding load
balancing virtual server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 541

NetScaler 12.0

2. The built-in detection policies bound to the virtual server combined with other proprietary de-
tection algorithms evaluate the traffic.
3. The policies use a set of built-in video detection signatures to detect the video type. The policy
that matches traffic applies an action that categorizes the video type as one of the following:
a) Clear-text PD
b) Clear-text ABR
c) Encrypted ABR
d) Other
4. The optimization policies bound to the same virtual server evaluate the traffic and determine
the optimization bit rate to apply to the traffic.
5. The optimization bit rate is applied if the traffic is either clear-text ABR or encrypted ABR.

A mobile service provider can improve the quality of experience (QoE) by setting the download speed
for 2G, 3G, and 4G mobile traffic. This reduces the video start times or buffering events. Optimization
can also reduce the amount of network bandwidth consumed by video sessions.

The optimization techniques include dynamic burst control and random sampling.

Dynamic Burst Control

NetScaler ABR optimization adapts dynamically to changing network conditions. It allows an initial
burst rate of 1.3 times the configured pacing rate for 15 seconds. The initial burst rate applies to the
beginning of every optimized ABR video session, even when multiple sessions use the same TCP con-
nection or group of TCP connections.

The appliance also supports recovery bursts in the event that the bit rate supported by the network
drops below the configured pacing rate. For example, if the effective bit rate drops at the 7th second
and recovers at 15th second of the initial burst, the appliance recovers the loss during the next burst
cycle. By doing so, the appliance dynamically optimizes the network bandwidth for all subscribers so
that the quality of video remains consistent per pixel.

Note: When a recovery burst happens during an initial burst, the pacing bit rate must not exceed the
maximum recovery-burst and initial-burst rates (you must not add the Recovery Burst factor on top
of the Initial Burst factor). Otherwise, it might be so fast that the media player shifts to a higher qual-
ity mode. However, if necessary, you can extend the duration of the Initial Burst to compensate the
unused bandwidth.

Random Sampling

To estimate the savings from video optimization, the NetScaler appliance implements random sam-
pling. With this technique, the appliance randomly selects a configurable percentage of the detected
video traffic (the random sampling parameter is an integer number ranging from 0 to 100, so less than

© 1999-2018 Citrix Systems, Inc. All rights reserved. 542

NetScaler 12.0

1 percent is not possible). These randomly selected and non-optimized transactions (and sessions)
become a reference group, and they are identified in the transaction logs (along with other character-
istics, such as byte size and timer fields. The characteristics of the optimized sessions are also logged,
and the reporting engine compares statistics of the optimized and reference groups to estimate the
savings from optimization (including the savings from ABR Optimization).

Video Optimization over UDP

Google has introduced a new transport protocol called QUIC. Google’s QUIC protocol is very similar
to TCP+TLS+HTTP/2 and is implemented on top of UDP. NetScaler can detect YouTube ABR videos
streamed over the QUIC protocol, and apply ABR video optimization in a similar way as ABR over TCP.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Licensing

September 17, 2018

Contributed by:
C

The Video Optimization feature works on Telco platforms with the purchase of a basic CBM license
and CBM Premium license and for otherNetScaler platforms, the feature works with the purchase of a
CNS Platinum license. Before you configure the video optimization feature, your appliance must have
a suitable license.

License support for Telco platforms:

• CBM_TXXX_SERVER_Retail.lic
• CBM_TPRE_SERVER_Retail.lic
• CNS_WEBF_SSERVER_Retail.lic

Where XXX is the throughput, for example, NetScaler T1000.

License support for otherNetScaler platforms:

• CNS_XXX_SERVER_PLT_Retail.lic

Where XXX is the throughput.

To upload a premium license file, follow the steps given below:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 543

NetScaler 12.0

1. A valid license file should be installed on the NetScaler appliance. The license should support at
least as many Gbps as the expected maximum Gi-LAN throughput.

License files should be copied through an SCP client to the /nsconfig/license of the appliance, as
shown in the screen capture below.

1 > shell ls /nsconfig/license/

2 CNS_V3000_SERVER_PLT_Retail.lic ssl

2. Do a warm restart to apply for the new license, as shown in the screen capture below.

1 > reboot -warm

2 Are you sure you want to restart NetScaler (Y/N)? [N]:y
3  Done

3. After the restart completes, verify that the license has been properly applied, by using the show
license CLI.

In the example below a premium license with premium edition has been successfully installed.

1 > show license

2
3              License status:
4
5                                      Video Optimization: YES
6
7                                                ...
8
9                                  Model Number ID: 110050
10
11                                     License Type: Platinum License

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Configuring Video Optimization over TCP

September 17, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 544

NetScaler 12.0

To optimize video traffic over TCP, begin by enabling the video optimization feature. The appliance
then activates the built-in detection policies to detect the incoming video traffic and identify the type
of video. User configurable optimization policies for each video type specify the optimization bit rate
needed for optimizing the traffic.

Configuring Video Optimization over TCP by using the CLI

To configure video optimization on a NetScaler appliance, you perform the following tasks:

1. Enable the video optimization feature.

2. Add virtual servers for HTTP and HTTPS traffic.
3. Bind all the built-in detection policies to a load balancing virtual server for HTTP traffic.
4. Bind all the built-in detection policies to an SSL-bridge load balancing virtual server for HTTPS
traffic.
5. Add the desired optimization policies for HTTP and HTTPS traffic.
6. Bind optimization policies to a load balancing virtual server for HTTP Traffic.
7. Bind optimization policies to an SSL-bridge load balancing virtual server for HTTPS traffic.

Enabling Video Optimization

If you want the NetScaler appliance to detect, optimize, and report video traffic, you must enable the
Video Optimization feature and set optimization to ON. After enabling the feature you can use built-in
detection policies to identify the incoming video traffic, and you can configure optimization policies
to optimize encrypted ABR traffic. To optimize ABR video traffic, you must configure the download bit
rate (also called the pacing rate).

You must also enable the load balancing feature, and if you want to use video optimization for HTTPS
traffic you must enable the SSL feature.

To enable the video optimization feature

At the command prompt, type the following command:

1 enable ns feature VideoOptimization

Note

If you want to monitor the video optimization performance and video insight reports you must
enable the AppFlow feature and then access the Video Analytics feature on Citrix Application
Delivery Management (ADM). For more information, see Video Insight documentation.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 545

NetScaler 12.0

Creating Virtual Servers for HTTP and HTTPS Video Traffic

A NetScaler appliance uses different virtual servers for detecting and optimizing the different types of
incoming video traffic. The appliance supports the following types of virtual servers for TCP traffic.

• HTTP Load Balancing virtual server. For detecting HTTP video traffic, the appliance uses an
HTTP load balancing virtual server. It manages HTTP video requests that the appliance receives
from clients.
• SSL-Bridge Load Balancing virtual server. To detect encrypted video traffic, you must config-
ure an SSL bridge virtual server on the appliance.

To add an HTTP Load Balancing virtual server for detecting HTTP video traffic

At the command prompt, type the following:

1 add lb vserver <name> HTTP * 80 -persistenceType NONE

Example:

1 add lb vserver ProxyVserver-HTTP HTTP * 80 -persistenceType NONE -

cltTimeout 120

To add an SSL Bridge virtual server for detecting HTTPS video traffic

At the command prompt, type the following:

1 add lb vserver <name> SSL_BRIDGE * 443 -persistenceType NONE

Example:

1 add lb vserver ProxyVserver-SSL SSL_BRIDGE * 443 -persistenceType NONE

-cltTimeout 180

Binding Built-In Detection Policies to an HTTP Load Balancing Virtual Server

To detect video traffic over an HTTP connection, you must bind all the built-in detection policies to
a load balancing virtual server. You must bind the policies to either request-time or response-time
processing, depending on the policy type.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 546

NetScaler 12.0

To bind detection policies for different video types to an HTTP load balancing virtual server

At the command prompt, type the appropriate command for each type. The available commands are:

1 bind lb vserver <name> -policyName ns_videoopt_http_abr_netflix -

priority <integer> -type (REQUEST | RESPONSE)
2
3 bind lb vserver <name>   -policyName ns_videoopt_http_abr_netflix2 -
priority <integer> -type (REQUEST | RESPONSE)
4
5 bind lb vserver <name>   -policyName ns_videoopt_http_abr_youtube -
priority <integer>  -type (REQUEST | RESPONSE)
6
7 bind lb vserver <name>    -policyName ns_videoopt_http_pd_youtube -
priority <integer>  -type (REQUEST | RESPONSE)
8
9 bind lb vserver <name>    -policyName ns_videoopt_http_pd_youtube2  -
priority <integer>  -type (REQUEST | RESPONSE)
10
11 bind lb vserver  <name>   -policyName ns_videoopt_http_pd_youtube3 -
priority <integer>  -type (REQUEST | RESPONSE)
12
13 bind lb vserver  <name>  -policyName ns_videoopt_http_abr_generic -
priority <integer> -type (REQUEST | RESPONSE)

Example:

1 bind lb vserver ProxyVserver-HTTP    -policyName

ns_videoopt_http_abr_netflix -priority 400  type RESPONSE
2
3 bind lb vserver ProxyVserver-HTTP    -policyName
ns_videoopt_http_abr_netflix2 -priority 500 -type RESPONSE
4
5 bind lb vserver ProxyVserver-HTTP    -policyName
ns_videoopt_http_abr_youtube -priority 600  -type RESPONSE
6
7 bind lb vserver ProxyVserver-HTTP    -policyName
ns_videoopt_http_pd_youtube -priority 800  -type RESPONSE
8
9 bind lb vserver ProxyVserver-HTTP    -policyName
ns_videoopt_http_pd_youtube2 -priority 900 -type RESPONSE
10
11 bind lb vserver  ProxyVserver-HTTP   -policyName
ns_videoopt_http_pd_youtube3 -priority 1000 -type REQUEST
12

© 1999-2018 Citrix Systems, Inc. All rights reserved. 547

NetScaler 12.0

13 bind lb vserver  ProxyVserver-HTTP   -policyName

ns_videoopt_http_abr_generic -priority 1100 -type RESPONSE

Binding the HTTP Body Content Detection Policy to Load Balancing Virtual Server

To detect video traffic over HTTP, you must bind the body content detection policy to the load balanc-
ing virtual server. You can use the following command:

1 bind lb vserver <name> -policyName ns_videoopt_http_body_detection -

priority <integer> -type (REQUEST | RESPONSE)

Example:

1 bind lb vserver ProxyVserver-HTTP -policyName

ns_videoopt_http_body_detection -priority 1500 -type REQUEST

Binding Built-In Detection Policies to an SSL-Bridge Load Balancing Virtual Server

To detect video traffic over an HTTPS connection, you must bind built-in detection policies to a SSL
Bridge load balancing virtual server.

To bind a detection policy to an SSL bridge load balancing virtual server

At the command prompt, type the appropriate command for each type. The available commands are:

1 bind lb vserver <name> -policyName ns_videoopt_https_abr_netflix -

priority <positive_integer> -type (REQUEST | RESPONSE)
2
3 bind lb vserver <name> -policyName ns_videoopt_https_abr_youtube -
priority <positive_integer> -type (REQUEST | RESPONSE)
4
5 bind lb vserver <name> -policyName ns_videoopt_https_abr_generic -
priority <positive_integer> -type (REQUEST | RESPONSE)

Example:

1 bind lb vserver ProxyVserver-SSL -policyName

ns_videoopt_https_abr_netflix -priority 120 -type REQUEST
2
3 bind lb vserver ProxyVserver-SSL -policyName
ns_videoopt_https_abr_youtube -priority 140 -type REQUEST

© 1999-2018 Citrix Systems, Inc. All rights reserved. 548

NetScaler 12.0

4
5 bind lb vserver ProxyVserver-SSL -policyName
ns_videoopt_https_abr_generic -priority 150 -type REQUEST

Adding Optimization Policies for Pacing ABR traffic

To optimize ABR traffic, you have to configure optimization policies and the associated actions. You
then bind the policies to the same load balancing virtual servers to which you bound the detection
policies. For each policy, create the action first, so that you can include it when you create the policy.

To add an optimization action

At the command prompt, type:

1 add videooptimization pacingaction <action Name> -rate <integer> [-

comment <string>]

Where the rate parameter specifies the rate in Kbps at which to send the traffic (the pacing rate).

Example:

1 add videooptimization pacingaction MyOptAct2000 -rate 2000

To add an optimization policy

At the command prompt, type:

1 add videooptimization pacingpolicy <name> -rule <expression> -action <

string>

Example:

1 add videooptimization pacingpolicy myOptPolicy2000 -rule TRUE -action

MyOptAct2000

Binding Optimization Policies to an HTTP Load Balancing Virtual Server

To optimize ABR video traffic over an HTTP connection, you must bind the optimization policies to a
load balancing virtual server to which the detection policies are bound.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 549

NetScaler 12.0

To bind an optimization policy to a Load Balancing virtual server

At the command prompt, type the following command:

1 bind lb vserver <name> -policyName <policy_name> -priority <

positive_integer> -type  (REQUEST | RESPONSE)

Example:

1 bind lb vserver ProxyVserver-HTTP -policyName myOptPolicy2000 -priority

3400 -type  REQUEST

Binding Optimization Policies to SSL-bridge Virtual Servers

To optimize ABR video traffic over an HTTPS connection, you must bind the optimization policies to
the SSL Bridge virtual server to which the built-in detection policies are bound.

To bind an optimization policy to SSL Bridge virtual server for pacing encrypted traffic

At the command prompt, type the following command:

1 bind lb vserver <name> -policyName <policy_name> -priority <

positive_integer> -type  (REQUEST |RESPONSE)

Example:

1 bind lb vserver ProxyVserver-SSL -policyName myOptPolicy2000 -priority

3400 -type  REQUEST

Setting video optimization pacing parameters

The CLI enables you to set the video optimization pacing parameters, such as random sampling per-
centage.

To set the random sampling percentage

At the command prompt, type the following command:

1 set videooptimization parameter ‒ RandomSamplingPercentage <realNumber>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 550

NetScaler 12.0

where realNumber is a value from 0.0 to 100.0.

Example:

1 set videooptimization parameter -RandomSamplingPercentage 50

Configuring Video Optimization over TCP by using the GUI

The GUI enables you to:

• Enable video optimization feature.

• Create HTTP load balancing virtual server.
• Create SSL-bridge load balancing virtual server.
• Bind built-in detection policies to HTTP load balancing virtual server.
• Bind built-in detection policies to SSL-bridge load balancing virtual server.
• Create optimization policy.
• Create optimization action.
• Configuring optimization pacing parameter.
• Bind optimization policy to load balancing virtual server for HTTP traffic.
• Bind optimization policy to SSL-bridge load balancing virtual server for HTTPS traffic.

To enable video optimization feature

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

2. On the Settings page, click the Configure Advanced Features link.
3. On the Configure Advanced Features page, select the Video Optimization check box.
4. Click OK, and then click Close.

To create load balancing virtual server for HTTP traffic

1. Sign in to the NetScaler appliance and navigate to the Traffic Management > Load Balancing
> Virtual Servers page.
2. In the details pane, click Add.
3. On the Load Balancing Virtual Server screen, set the following parameters:
a) Name. Name of the load balancing virtual server.
b) Protocol. Select protocol type as HTTP
c) IP Address Type. IP address type: IPv4 or IPv6.
d) IP Address. IPv4 or IPv6 address assigned to the virtual server.
e) Port. Port number of the virtual server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 551

NetScaler 12.0

4. Click OK to continue with configuration of other, optional, parameters. For more information,
see Creating a Virtual Server.
5. Click Create and Close.

To create load balancing virtual server for HTTPS traffic

1. Sign in to the NetScaler appliance and navigate to the Traffic Management > Load Balancing
> Virtual Servers page.
2. In the details pane, click Add.
3. On the Load Balancing Virtual Server screen, set the following parameters:
a) Name. Name of the load balancing virtual server.
b) Protocol. Select protocol type as SSL-bridge.
c) IP Address Type. IP address type: IPv4 or IPv6.
d) IP Address. IPv4 or IPv6 address assigned to the virtual server.
e) Port. Port number of the virtual server.
4. Click OK to continue with the configuration of other, optional, parameters. For more informa-
tion, see Creating a Virtual Server.
5. Click Create and then Close.

To bind a built-in detection policy to a load balancing virtual server

1. Sign in to the NetScaler appliance and navigate to Traffic Management > Load Balancing >
Virtual Servers screen.
2. In the details pane, select the load balancing virtual server and click Edit.
a) In the Advanced Setting section, click Policies.
b) In the Policies section, click the + icon to access the Policies slider.
c) In the Policies section, set the following parameters.
d) Choose Policy. Select a video optimization detection policy from the drop-down list.
e) Choose Type. Select the policy type as Request.
f) Click Continue.
3. Select the video detection policy from the list and click Close.

To bind a built-in detection policy to a SSL-bridge load balancing virtual server

1. Log on to the NetScaler appliance and navigate to the Traffic Management > Load Balancing
> Virtual Servers screen.
2. In the details pane, select the SSL-bridge load balancing virtual server and click Edit.
3. In the Advanced Setting section, click Policies.
4. In the Policies section, click the + icon to access the Policies slider.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 552

NetScaler 12.0

5. In the Policies section, set the following parameters.

a) Choose Policy. Select video optimization detection policy from the drop-down list.
b) Choose Type. Select the policy type as Request.
6. Click Continue.
7. Select the video detection policy from the list and click Close.

To create a video optimization action

1. Log on to the NetScaler appliance and navigate to Configuration > Optimization > Video Op-
timization > Pacing > Actions.
2. In the details pane, click Add.
3. On the Create Video Optimization Pacing Action page, set the following parameters.
a) Name. Name of the optimization action.
b) ABR Optimization Rate (Kbps). Pacing rate at which to send the ABR video traffic. The
default rate for ABR optimization is 1000 Kbps. The minimum value is 1, and the maximum
value is 2147483647.
c) Comment. A short description of the action.
4. Click Create and Close.

To create a video optimization policy

1. Log on to the NetScaler appliance and navigate to Configuration > Optimization > Video Op-
timization > Pacing > Policies.
2. In the details pane, click Add.
3. On the Create Video Optimization Pacing Policy page, set the following parameters.
a) Name. Name of the optimization policy
b) Expression. Custom regrex expressions that implement the policy.
c) Action. Optimization action associated with the policy to handle the incoming video traf-
fic.
d) UNDEF Action. Undefined event if the incoming request does not match the optimization
policy.
e) Comment. A short description of the policy.
f) Log Action. Select the audit log action that creates the desired log messages.
4. Click Create, and then click Close.

To set video optimization pacing parameters

1. Log on to the NetScaler appliance and navigate to Configuration > Optimization > Video Op-
timization.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 553

NetScaler 12.0

2. In the Video Optimization page, click Change Video Optimization Settings link.
3. In the Video Optimization Settings page, set the following parameter.
a) Random Sampling Percentage (%). Percentage of packets selected for random sampling.
4. Click OK and Close.

To bind a video optimization policy to an HTTP load balancing virtual server

1. Log on to the NetScaler appliance and navigate to Configuration > Optimization > Video Op-
timization.
2. On the Video Optimization page, click the Video Optimization Pacing Policy Manager link.
3. Set the following parameters.
a) Bind Point. The point at which to apply the optimization policy during request or response
processing.
b) Connection Type. Connection type as Request or Response.
c) Virtual Server. The load balancing virtual server to which to bind the policy.
d) Click Continue.
4. In the Bind Point section, do one of the following:
a) Select a policy from the list.
b) Click Add Binding to access the Policies Binding slider.
i. Select an existing policy or add a new policy.
ii. Enter binding details and click Bind.
5. Click Close.

To bind a video optimization policy to an SSL-bridge load balancing virtual server

1. Log on to the NetScaler appliance and navigate to Configuration > Optimization > Video Op-
timization.
2. On the Video Optimization page, click the Video Optimization Pacing Policy Manager link.
3. On the Video Optimization Policy Manager page, set the following parameters.
a) Bind Point. The point at which to apply the optimization policy during request/response
processing.
b) Connection Type. Connection type as Request or Response.
c) Virtual Server. The SSL-bridge load balancing virtual server to which to bind the policy.
4. Click Continue.
5. In the Bind Point section, do one of the following:
a) Select a policy binding from the list.
b) Click Add Binding to access the Policies Binding slider.
i. Select an existing policy or add a new policy.
ii. Enter binding details and click Bind.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 554

NetScaler 12.0

6. Click Close.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

Configuring Video Optimization over UDP

September 17, 2018

Contributed by:
C

To optimize QUIC ABR video traffic over UDP, begin by enabling the video optimization feature. After
you complete the configuration, the appliance detects QUIC based ABR video traffic and applies the
optimization bit rate that is configured on the appliance.

Configuring video optimization for QUIC by using the CLI

To configure video optimization for QUIC video traffic over UDP, you must perform the following tasks:

1. Enable Video Optimization.

2. Create a QUIC service.
3. Create a QUIC load balancing virtual server.
4. Bind QUIC web service to the loading balancing virtual server.
5. Create video optimization policy for pacing QUIC based UDP traffic.
6. Bind optimization policy to a QUIC based load balancing virtual server.

Enabling video optimization for QUIC traffic

If you want the NetScaler appliance to detect, optimize, and report video traffic, you must enable the
Video Optimization feature and set optimization ON.

Note

If you want to use video optimization for QUIC traffic, you must enable the load balancing and
AppFlow features.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 555

NetScaler 12.0

To enable the video optimization

At the command prompt, type the following command:

1 enable ns feature VideoOptimization

Creating a service for QUIC traffic

A NetScaler appliance uses a QUIC service for the load balancing virtual server to connect to the egress
router in the static routing mode.
Note

Currently, dynamic routing is not supported.

To create a load balancing web service for QUIC video traffic

At the command prompt, type:

1 add service <name> <router-IP> <serviceType> <port> -usip yes -

useproxyport  [yes | no]

Example:

1 add service svc-quic 10.102.29.200 QUIC 443 ‒ usip yes ‒ useproxyport

no
2
3 where IP address is the internet router address.

Creating a load balancing virtual server for QUIC traffic

A NetScaler appliance uses a load balancing virtual server for detecting and optimizing QUIC video
traffic over UDP.

To create a load balancing virtual server for QUIC video traffic

At the command prompt, type:

1 add lb vserver <name> <serviceType> <ip> <port> -m MAC

Example:

1 add lb vserver vs-quic QUIC * 443 -persistenceType NONE -m MAC -

cltTimeout 120

© 1999-2018 Citrix Systems, Inc. All rights reserved. 556

NetScaler 12.0

Binding a QUIC web service to the load balancing virtual server

After you have created the web services and load balancing virtual server for QUIC traffic, you must
bind the services to the virtual server.

To bind a web service to load balancing virtual server for QUIC video traffic

At the command prompt, type:

1 bind lb vserver <name> <serviceName>

Example:

1 bind lb vserver vs-quic svc-quic

Creating Video Optimization Policy for QUIC based UDP traffic

To optimize QUIC based UDP traffic, you have to configure optimization pacing policies and its actions.
You must then, bind the policies to QUIC based load balancing virtual servers. For each policy, create
an action first so that you can associate it to the policy.

To add an optimization action

At the command prompt, type:

1 add videooptimization pacingaction <action Name> -rate <integer> [-

comment <string>]

Where, the rate parameter specifies the rate in Kbps at which to send the traffic (the pacing rate).

Example:

1 set videooptimization parameter -QUICPacingRate 1000

where 1000 represents the desired pacing rate in Kbits/sec.

To add an optimization policy

At the command prompt, type:

1 add videooptimization pacingpolicy <name> -rule <expression> -action <

string>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 557

NetScaler 12.0

Example:

1 add videooptimization pacingpolicy myOptPolicy2000 -rule TRUE -action

MyOptAct2000

Binding Optimization Policies to a QUIC Load Balancing Virtual Server

To optimize QUIC video traffic over a UDP connection, you must bind the optimization policies to a
QUIC load balancing virtual server.

To bind an optimization policy to a QUIC Load Balancing virtual server

At the command prompt, type the following command:

1 bind lb vserver <name> -policyName <policy_name> -priority <

positive_integer> -type (REQUEST)

Note

The pacing policies must be bound to a QUIC load balancing virtual server only at request time.

Example:

1 bind lb vserver vs-quic -policyName myOptPolicy2000 -priority 3400 -

type  REQUEST

Configuring video optimization for QUIC by using the GUI

To configure the feature on the appliance through the GUI, you must perform the following tasks:

1. Enable video optimization

2. Configure a QUIC servers
3. Configure QUIC service
4. Configure a QUIC load balancing virtual server
5. Bind the QUIC web service to the load balancing virtual server
6. Create optimization policy.
7. Create optimization action.
8. Configuring optimization pacing parameter.
9. Bind optimization policy to load balancing virtual server for QUIC traffic.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 558

NetScaler 12.0

To enable video optimization

1. Log on to the NetScaler appliance and navigate to System > Settings.

2. On the details page, select Configure Advanced Features link.
3. On the Configure Advanced Features page, select the Video Optimization check box.

To create a QUIC servers

1. Log on to the NetScaler appliance and navigate to the Traffic Management > Load Balancing
> Servers screen.
2. In the details pane, click Add.
3. On the Create Server page, set the following parameters:
a) Name. Name of the QUIC server.
b) IP address. IP address of the QUIC server
c) Traffic Domain. Domain name of the server.
d) Enabling after creating. Initial state of the server.
e) Comments. Brief information about the server.
4. Click Create.

To create a QUIC service

1. Log on to the NetScaler appliance and navigate to the Traffic Management > Load Balancing
> Services screen.
2. In the details pane, click Add.
3. On the Load Balancing Service page, set the following parameters:
a) Service Name. Name of the QUIC service.
b) IP address. IP address assigned to the QUIC service.
c) Protocol. Select protocol as QUIC.
d) Port. Port number of the web service.
4. Click OK to continue. You can then configure other, optional, parameters. For more, see Config-
uring Services.
5. Once you configure the optional parameters, click OK and Close.

To create a load balancing virtual server

1. Log on to the NetScaler appliance and navigate to the Traffic Management > Load Balancing
> Virtual Servers screen.
2. In the details pane, click Add.
3. On the Load Balancing Virtual Server page, set the following parameters:
a) Name. Name of the load balancing virtual server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 559

NetScaler 12.0

b) Protocol. The protocol used by the service to send QUIC requests.

c) IP Address Type. IP address type: IPv4 or IPv6.
d) IP Address. IP 4 or IP6 IP address assigned to the virtual server.
e) Port. Port number of the virtual server.
4. Click OK to continue with the configuration of other, optional, parameters. For more informa-
tion, see Creating a Virtual Server.

To bind a load balancing virtual server to a QUIC service

1. Navigate to Traffic Management > Load Balancing> Virtual Servers, and select a virtual server.
2. Click Services and Service Groups to access the Load Balancing Virtual Server Service Bind-
ing screen.
3. Select a QUIC based web service and click Bind.
4. Click Done.

To bind a load balancing virtual server to a QUIC service

1. Navigate to Traffic Management> Load Balancing> Virtual Servers, and select a virtual server.
2. Click Services and Service Groups to access the Load Balancing Virtual Server Service Bind-
ing screen.
3. Select a QUIC based web service and click Bind.
4. Click Done.

To create a video optimization action for QUIC traffic

1. Log on to the NetScaler appliance and navigate to Configuration > Optimization > Video Op-
timization > Pacing > Actions.
2. In the details pane, click Add.
3. On the Create Video Optimization Pacing Action page, set the following parameters.
a) Name. Name of the optimization action.
b) ABR Optimization Rate (Kbps). Pacing rate at which to send the ABR video traffic. The
default rate for ABR optimization is 1000 Kbps. The minimum value is 1, and the maximum
value is 2147483647.
c) Comment. A short description of the action.
4. Click Create and Close.

To create a video optimization policy for QUIC traffic

1. Log on to the NetScaler appliance and navigate to Configuration > Optimization > Video Op-
timization > Pacing > Policies.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 560

NetScaler 12.0

2. In the details pane, click Add.

3. On the Create Video Optimization Pacing Policy page, set the following parameters.
a) Name. Name of the optimization policy
b) Expression. Custom regrex expressions that implement the policy.
c) Action. Optimization action associated with the policy to handle the incoming video traf-
fic.
d) UNDEF Action. Undefined event if the incoming request does not match the optimization
policy.
e) Comment. A short description of the policy.
f) Log Action. Select the audit log action that creates the desired log messages.
4. Click Create, and then click Close.

To bind a video optimization policy to an QUIC load balancing virtual server

1. Log on to the NetScaler appliance and navigate to Configuration> Optimization> Video Opti-
mization.
2. On the Video Optimization page, click the Video Optimization Pacing Policy Manager link.
3. On the Video Optimization Policy Manager page, set the following parameters.
a) Bind Point. The point at which to apply the optimization policy during request process-
ing. Note: The pacing policies must be bound to a QUIC load balancing virtual server only
at request time.
b) Connection Type. Connection type as Request or Response.
c) Virtual Server. The load balancing virtual server to which to bind the policy.
4. Click Continue.
5. In the Bind Point section, do one of the following:
a) Select a policy from the list.
b) Click Add Binding to access the Policies Binding slider.
i. Select an existing policy or add a new policy.
ii. Enter binding details and click Bind.
6. Click Close.
1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

NetScaler URL Filtering

November 14, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 561

NetScaler 12.0

Contributed by:
C
URL Filtering provides policy-based control of websites by using the information contained in URLs.
This feature helps network administrators monitor and control user access to malicious websites on
mobile networks.
As an administrator, you can configure a URL filtering policy by using either the URL Categorization
feature or the URL List feature.
URL List. Controls access to blacklisted websites and web pages by blocking access to URLs that are
in a URL set imported into the appliance.
URL Categorization. Controls access to websites and web pages by filtering traffic on the basis of a
predefined list of categories.
1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

URL List

November 15, 2018

Contributed by:
C
The URL List feature enables you to control access to customized URL lists (up to one million entries).
The feature filters websites by applying a URL filtering policy bound to a virtual server.
As an administrator, you must import the URL List into the NetScaler appliance. This imported list is
internally stored as a Policy data set called a URL Set. The appliance then applies a unique fast URL
matching algorithm to the incoming URL requests. If the incoming URL request matches an entry in
the set, the appliance applies the associated policy action to control access.

URL List Types

Each entry in a URL set can include a URL and, optionally, its metadata (URL category, category groups,
or any other related data). For URLs with a metadata, the appliance uses a policy expression that
evaluates the metadata. For more information, see URL Sets.
A NetScaler appliance supports two types of URL lists: Custom (with or without URL metadata) and
IWF (Internet Watch Foundation).

© 1999-2018 Citrix Systems, Inc. All rights reserved. 562

NetScaler 12.0

Custom URL List. You can create a customized URL set of up to 1,000,000 URL entries and import it
as a text file into your appliance. The list can contain URLs with or without metadata (which could be
like a URL category). TheNetScaler platform automatically detects whether metadata is present. It
also supports storing the imported lists securely. For more information, see URL Set.

IWF URL List. You can import an externally managed list maintained by the IWF. To access this list,
you need special access credentials, and you have to use a secure procedure. NetScaler has built-in
support for the IWF list, making it simple to use.

You can host the URL list and configure the NetScaler appliance to periodically update the list without
requiring manual intervention. Once the URL list is updated, the appliance can automatically detect
the metadata and the categories by using policy expressions to evaluate each incoming URL and then
apply actions such as allow, block, redirect, or notify the user.

URL List Policy Expressions

The following table describes the basic expressions you can use to evaluate incoming traffic. After you
import an URL List to the appliance, it is called a URL Set.

Expression Operation

<URL expression>.URLSET_MATCHES_ANY Evaluates to TRUE if the URL exactly matches

(<URLSET>) any entry in the URL set.
<URL expression>. The GET_URLSET_METADATA() expression
GET_URLSET_METADATA(<URLSET>) returns the associated metadata if the URL
exactly matches any pattern within the URL set.
An empty string is returned if there is no match.
<URL expression>.GET_ Evaluates to TRUE if the matched metadata is
URLSET_METADATA(<URLSET>).EQ(< equal to <METADATA>.
METADATA>)
<URLexpression>.GET_URLSET_METADATA Evaluates to TRUE if the matched metadata is
(<URLSET>).TYPECAST_LIST_T(‘,’).GET at the beginning of the category. This pattern
(0).EQ(<CATEGORY>) can be used to encode separate fields within
metadata, but match only the
1^st field.
HTTP.REQ.HOSTNAME.APPEND(HTTP.REQ.URL) Joins the host and URL parameters, which can
then be used as a <URL expression> for
matching.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 563

NetScaler 12.0

URL List Policy Actions

The most common enforcement action for URLs that match a URL list is to restrict access. Create a
URL list policy with a desired URL list matching expression and enforcement action. The policy group
usage depends upon the incoming traffic type (HTTP or HTTPS) and the virtual server configured on
the appliance. You can use a Responder policy for HTTP traffic or a Video Optimization policy for
HTTPS traffic. Specify actio ns to apply to the URLs that match the expressions in the policies. The
following table lists the available actions.

Action Type Policy Description

ALLOW Responder Allow the request to access

the target URL.
REDIRECT Responder Redirect the request to the
URL specified as the target.
DENY Responder Deny the request.
RESET Responder, Reset the connection.
VideoOptimization
DROP Responder, Drop the connection.
VideoOptimization

Prerequisites

To configure URL List feature, make sure you have configured the following server.

DNS Server for DNS Requests

You must configure a DNS server if you import a URL Set from a hostname URL.

At the command prompt, type:

1 add dns nameServer ((<IP> [-local]) | <dnsVserverName>) [-state (

ENABLED | DISABLED )] [-type <type>] [-dnsProfileName <string>]

Example:

1 add dns nameServer 10.140.50.5

© 1999-2018 Citrix Systems, Inc. All rights reserved. 564

NetScaler 12.0

Configuring a URL List

To configure a URL List, do the following:

• Import a custom URL list

• Set up IWF URL list support
• Configure a URL list for HTTP traffic.
– Add a URL List action.
– Add a URL List policy.
– Add an HTTP load balancing virtual server for HTTP traffic.
– Bind the URL List policy to the HTTP load Balancing virtual server for HTTP traffic.
• Configure a URL list for HTTPS traffic.
– Add a video optimization detection policy.
– Add an SSL-bridge load balancing virtual server for HTTPS traffic.
– Bind the video optimization detection policy to the SSL-bridge load balancing virtual
server for HTTPS traffic

Importing a custom URL list

To import a URL set, see See URL Set.

Setting up IWF URL List Support

To set up IWF URL list support, you need access credentials. The IWF gives each member the unique
access credentials required for setup. The access credentials include a user name password.

At the command prompt, type:

1 import urlset iwfset -url https://<*IWFUser*>:<*IWFPass*>@servicebak.

iwf.org.uk/ -private Done

Note

If the IWF changes the URL for importing a list, you can contact the NetScaler support team.

Configuring a URL List for HTTP traffic

The NetScaler appliance supports HTTP and HTTPS traffic. To configure a load balancing virtual server
for HTTP traffic and bind URL list policies to the server, do the following:

• Add URL List actions.

• Add URL List policies.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 565

NetScaler 12.0

• Add an HTTP load balancing virtual server for HTTP traffic

• Bind the URL List policies to the HTTP load balancing virtual server for HTTP traffic

To add a URL list action

At the command prompt, type the following:

1 add responder action <name> <type> (<target> | <htmlpage>) [-comment <

string>] [-responseStatusCode <positive_integer>] [-reasonPhrase <
string>]

Example:

1 add responder action act_iwf_url respondwith ’”HTTP/1.1 451 Unavailable

For Legal ReasonsrnrnURL is IWF NOT authorizedn”’

To add a URL list policy

At the command prompt, type the following:

1 add responder policy <name> <rule> <action> [<undefAction>] [-comment <

string>] [-logAction <string>] [-appflowAction <string>]

Example:

1 add responder policy pol_iwf_http ’HTTP.REQ.HOSTNAME.APPEND(HTTP.REQ.

URL).URLSET_MATCHES_ANY(”iwfset”)’ act_iwf_url

To add a HTTP load balancing virtual server for HTTP traffic

At the command prompt, type the following:

1 add vserver <name> [-td <positive_integer>] <serviceType> [-cltT imeout

<secs>]

Example:

1 add lb vserver vsrv-HTTP HTTP * 80 -persistenceType NONE -

cltTimeout 120

© 1999-2018 Citrix Systems, Inc. All rights reserved. 566

NetScaler 12.0

To bind URL list policy to HTTP load balancing virtual server

At the command prompt, type the following:

1 bind lb vserver <vServerName> -policyName <string> [-priority <

positive_integer>]

Example:

1 bind lb vserver vsrv-HTTP -policyName pol_iwf_http -priority 10 -

type REQUEST

Configuring URL List for HTTPS traffic

The NetScaler appliance supports HTTP and HTTPS traffic. To configure a SSL-bridge load balancing
virtual server for HTTPS traffic and bind URL list policies to the server, do the following:

• Add URL List actions.

• Add URL List policies.
• Add a SSL-bridge load balancing virtual server for HTTP traffic
• Bind the URL List policies to the SSL-bridge load balancing virtual server for HTTP traffic

To add a URL List policy for HTTPS traffic

At the command prompt, type:

1 add videooptimization detectionpolicy <name> -rule <expression> -action

<string> [-undefAction <string>] [-comment <string>] [-logAction <
string>]

Example:

1 add videooptimization detectionpolicy pol_iwf_https -rule CLIENT.SSL.

DETECTED_DOMAIN.URLSET_MATCHES_ANY(”iwfset”) -action RESET

To add a SSL-bridge load balancing virtual server

At the command prompt type:

1 add vserver <name> [-td <positive_integer>] <serviceType> [-cltT imeout

<secs>]

© 1999-2018 Citrix Systems, Inc. All rights reserved. 567

NetScaler 12.0

Example:

1 add lb vserver vsrv-HTTPS SSL_BRIDGE * 443 -persistenceType NONE -

cltTimeout 180

To bind URL List policy with SSL-bridge load balancing by using the CLI

At the command prompt type:

1 bind lb vserver <vServerName> -policyName <string> [-priority <

positive_integer>]

Example:

1 bind lb vserver vsrv-HTTPS -policyName pol_iwf_https -priority 20 -type

REQUEST

Configuring a URL List by using the GUI

The GUI enables you to:

• Import a URL list.

• Add a URL list.
• Configure URL list actions.
• Configure URL list policies for HTTP traffic.
• Add an HTTP load balancing virtual server for HTTP traffic.
• Add an SSL-bridge load balancing virtual server for HTTPS traffic.
• Bind URL list policies to the HTTP load balancing virtual server.
• Bind a URL list policies to the SSL-bridge load balancing virtual server.

To import a URL list

1. In the navigation pane, expand AppExpert > URL Sets.

2. In the details pane, click Import.
3. On the Configure URL Set page, set the following parameters.
a) Name. Name of the URL set.
b) URL. Web address of the location at which to access the URL Set.
c) Overwrite. Overwrite a previously imported URL set.
d) Delimiter. Character sequence that delimits a CSV file record.
e) Row Separator. Row separator used in the CSV file.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 568

NetScaler 12.0

f) Interval. Interval in seconds, rounded off to the nearest 15 minutes, at which the URL set
is updated.
g) Private Set. Option to prevent exporting the URL set
h) Canary URL. Internal URL for testing whether the content of the URL set is to be kept con-
fidential. The maximum length of the URL is 2047 characters
4. Click Create, and then Close.

To add a URL list

1. In the navigation pane, expand AppExpert > URL Sets.

2. In the details pane, click Add.
3. On the Create URL Set page, set the following parameters.
a) Name. The name of the URL set that was given when it was imported.
b) Comments. A short description about the URL set.
4. Click Create.

To configure a URL list action

1. In the navigation pane, navigate to AppExpert > Responder > Action.

2. In the details pane, click Add.
3. On the Create Responder Action page, set the following parameters.
a) Name. Name of the URL List policy action.
b) Type. Select an action type.
c) Expression. Use the expression editor to create the policy expression.
d) Comments. A short description about the policy action.
4. Click Create and Close.

To configure a URL list policy

1. In the navigation pane, expand AppExpert > Responder > Policies.

2. In the details pane, click Add.
3. On the Create Responder Policy page, set the following parameters.
a) Name. Name of the URL List policy action.
b) Action. Select the URL List action that you prefer to associate with the policy.
c) Log Action. Select the log action.
d) AppFlow. Select an AppFlow action.
e) Expression. Use the expression editor to create the policy expression.
f) Comments. A short description about the policy.
4. Click Create and Close.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 569

NetScaler 12.0

To add an HTTP load balancing virtual server

1. Navigate to the Traffic Management > Load Balancing > Virtual Servers page.
2. In the details pane, click Add.
3. On the Load Balancing Virtual Server screen, set the following parameters:
a) Name. Name of the load balancing virtual server.
b) Protocol. Choose protocol type as HTTP.
c) IP Address Type. IP addressable type.
d) IP Address. IP 4 or IP6 IP address assigned to the virtual server.
e) Port. Port number of the virtual server.
4. Click OK to continue with the configuration of other, optional, parameters. For more informa-
tion, see Creating a Virtual Server.

To bind a URL List policy to the HTTP load balancing virtual server

1. Navigate to Traffic Management > Load Balancing > Virtual Servers screen.
2. In the details pane, select the load balancing virtual server and click Edit.
3. In the Advanced Setting section, click Policies.
4. In the Policies section, click the + icon to access the Policies slider.
5. In the Policies section, set the following parameters.
a) Choose Policy. Select a URL categorization policy from the drop-down list.
b) Choose Type. Select the policy type as Request.
6. Click Continue.
7. Select the URL List policy from the list and click Close.

To add URL List policy for HTTPS traffic

1. Log on to the NetScaler appliance and navigate to Configuration > Optimization > Video Op-
timization > Detection.
2. On the Detection page, click the Video Optimization Detection Policies link.
3. On the Video Optimization Detection Policies page, click Add.
4. On the Create Video Optimization Detection Policy page, set the following parameters.
a) Name. Name of the optimization policy
b) Expression. Configure policy using custom expressions.
c) Action. Optimization action associated with the policy to handle the incoming video traf-
fic.
d) UNDEF Action. Undefined event if the incoming request does not match the optimization
policy.
e) Comment. A short description of the policy.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 570

NetScaler 12.0

f) Log Action. Select an audit log action that specifies the action to be performed for the log
messages.
5. Click Create and Close.

To add a SSL-bridge load balancing virtual server for HTTPS traffic

1. Navigate to the Traffic Management > Load Balancing > Virtual Servers page.
2. In the details pane, click Add.
3. On the Load Balancing Virtual Server screen, set the following parameters:
a) Name. Name of the load balancing virtual server.
b) Protocol. Select protocol type as SSL-bridge.
c) IP Address Type. IP address type: IPv4 or IPv6.
d) IP Address. IPv4 or IP6vIP address assigned to the virtual server.
e) Port. Port number of the virtual server.
4. Click OK to continue with the configuration of other, optional, parameters. For more informa-
tion, see “Creating a Virtual Server” topic.

To bind a URL List Policy to the SSL-bridge load balancing virtual server

1. Navigate to the Traffic Management > Load Balancing > Virtual Servers screen.
2. In the details pane, select the SSL-bridge load balancing virtual server and click Edit.
3. In the Advanced Setting section, click Policies.
4. In the Policies section, click the + icon to access the Policies slider.
5. Set the following parameters.
a) Choose Policy. Select video detection policy from the drop-down list.
b) Choose Type. Select the policy type as Request.
6. Click Continue.
7. Select the video detection policy from the list and click Close.

Configuring Audit Log Messaging

Audit logging enables you to review a condition or a situation in any phase of URL List process. When a
NetScaler appliance receives an incoming URL, if the responder policy has an URL Set advanced policy
expression, the audit log feature collects URL Set information in the URL and stores the details as a
log message for any target allowed by audit logging.

The log message contains the following information:

1. Timestamp.
2. Log message type.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 571

NetScaler 12.0

3. The predefined log levels (Critical, Error, Notice, Warning, Informational, Debug, Alert, and
Emergency).
4. Log message information, such as URL set name, policy action, URL.

To configure audit logging for URL List feature, you must complete the following tasks:

1. Enable Audit Log.

2. Create Audit Log message action.
3. Set URL List responder policy with Audit Log message action.

For more information, see Audit Logging.

URL List Semantics

The following table lists the URL Match patterns and describes how the URLs within a URL list are
matched against the incoming-request URLs. For example, the pattern www.example.com/bar
matches only with one page at www.example.com/bar. To match all the pages whose URL starts with
‘ www.example.com/bar’, you would add an asterisk (*) to the end of the URL.

Semantics URL Pattern Matched Unmatched

Subdomain matching domain.com domain.com; yourdomain.com;

[www.domain.com](http
wwwdomain.com
://www.domain.
com/
;sub.one.domain.com
URL matching, exact domain.com/example/bar/index.html
domain.com/example/bar/index.html;
wwwdomaincom/example/bar/index
path www.domain.com/example/bar/index.html;
do-
s.domain.com/example/bar/index.html
main.com/example/bar/index.html/o
URL matching, exact domain.com/example/bar/index.html
domain.com/example/bar/index.html?key=value;
wwwdomaincom/example/bar/index
path www.domain.com/example/bar/index.html?;
do-
s.domain.com/example/bar/index.html
main.com/example/bar/index.html/o
URL matching, domain.com/example/bar/
domain.com/example/bar/;domain.com/example/bar/index.h
wwwdomaincom/example/bar/index
subpath matching www.domain.com/example/bar/index.html;
do-
main.com/example/bar/index.html/one.jpg

1.
2. Citrix ADC
3. NetScaler 12.0
4. Solutions for Telecom Service Providers

© 1999-2018 Citrix Systems, Inc. All rights reserved. 572

NetScaler 12.0

URL Categorization

January 6, 2019

Contributed by:
C

URL Categorization restricts user access to specific websites and website categories. As a subscrip-
tion service offered by NetScaler T1000, the feature enables customers to filter web traffic by using a
commercial categorization database. The database has billions of URLs classified into different cate-
gories, such as social networking, gambling, adult content, new media, and shopping. In addition to
categorization, each URL has a reputation score kept up to date based on the site’s historical risk pro-
file. To filter your traffic, you can configure advanced policies based on categories, category groups
(such as Terrorism, Illegal drugs), or site-reputation scores.

For example, you might block access to dangerous sites, such as sites known to be infected with mal-
ware, and selectively restrict access to content such as adult content or entertainment streaming me-
dia.

How URL Categorization Works

The following figure shows how NetScaler URL Filtering service is integrated with a commercial URL
Categorization database and cloud services for frequent updates.

The components interact as follows:

1. Client sends internet bound URL request.

2. A NetScaler policy attempts to evaluate the request in terms of categorization details (such
as category, category group, and site-reputation score) retrieved from the URL categorization
database. If the database returns the category details, the process jumps to step 5.
3. If the database does not return categorization details, the request is sent to a cloud-based
lookup service maintained by a URL categorization vendor. However, the appliance does not
wait for a response. Instead, it marks the URL as Uncategorized and jumps to step 5. However,
it continues to monitor the cloud query feedback and uses it to update the cache so that future
requests can benefit from the cloud lookup.
4. The NetScaler appliance receives the URL category details (category, category group, and repu-
tation score) from the cloud-based service and stores it in the cloud cache.
5. If the policy allows the URL, the request is sent to the origin server. Otherwise, the appliance
drops or redirects the request, or responds with a custom HTML page.
6. The origin server responds with the requested data to the NetScaler appliance.
7. The appliance sends the response to the client.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 573

NetScaler 12.0

You can use the URL filtering feature to detect sites that violate safe internet usage mandates issued by
the government and implement policies to block these sites. Sites that host adult content, streaming
media, or social networking identified as unsafe for children or banned as illegal.

Prerequisites

The feature works on Telco platforms with the purchase of a basic CBM license and CBM Premium
license and for otherNetScaler platforms, the feature works with the purchase of a CNS Platinum li-
cense.

Note: In addition to a Basic CBM license and a CBM Premium license, the appliance must have a URL
Threat Intelligence feature license with a subscription service for one year or 3 years. Before enabling
and configuring the feature, you must install the following licenses:

License support for Telco platforms:

• CBM_TXXX_SERVER_Retail.lic
• CBM_TPRE_SERVER_Retail.lic
• CNS_WEBF_SSERVER_Retail.lic

Where XXX is the throughput, for example, NetScaler T1000.

License support for otherNetScaler platforms:

• CNS_XXX_SERVER_PLT_Retail.lic

Where XXX is the throughput.

URL Categorization Policy Expressions

The following table lists the different URL categorization policy expressions that you can use to iden-
tify incoming URLs to which to apply an action of allow, redirect, drop, reset the connection, or deny
access.

Expression Operation

<text>. URL_CATEGORIZE (< Returns a URL_CATEGORY object. If is greater

min_reputation>, <max_reputation>) than 0, the returned object does not contain a
category with a reputation lower than . If is
greater than 0, the returned object does not
contain a category with a reputation higher
than . If the category fails to resolve in a timely
manner, the undef value is returned.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 574

NetScaler 12.0

Expression Operation

. CATEGORY Returns the category string for this object. If

the URL does not have a category, or if the URL
is malformed, the returned value is
“Uncategorized”.
. GROUP Returns a string identifying the object’s
category group. This is a higher level grouping
of categories, which is useful in operations that
require less detailed information about the
URL category. If the URL does not have a
category, or if the URL is malformed, the
returned value is “Uncategorized”.
. REPUTATION Returns the reputation score as a number from
1 to 4, where 4 indicates the riskiest reputation.
If the category is “Uncategorized”, the
reputation value is 2.

Sample Policy Expressions

Policy Policy Expressions

Policy to select requests for URLs that are in add responder policy p1
the Search Engine category ‘HTTP.REQ.HOSTNAME.APPEND(HTTP.REQ.URL).URL_CATEGO
CATEGORY.EQ(“Search Engine”)
Policy to select requests for URLs that are in add responder policy p1
the Adult category group ‘HTTP.REQ.HOSTNAME.APPEND(HTTP.REQ.URL).URL_CATEGO
GROUP.EQ(“Adult”)’
Policy to select requests for Search Engine add responder policy p2
URLs with a reputation score equal to 4. ‘HTTP.REQ.HOSTNAME.APPEND(HTTP.REQ.URL).URL_CATEGO
CATEGORY.EQ(“Search Engine”)’
Policy to select requests for Search Engine and add policy patset good_categories; bind policy
Shopping URLs good_categories “Search Engine”; bind policy
good_categories “Shopping”; add responder
policy p3
‘HTTP.REQ.HOSTNAME.APPEND(HTTP.REQ.URL).URL_CATEGO
CATEGORY .EQUALS_ANY(“good_categories”)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 575

NetScaler 12.0

Policy Policy Expressions

Policy to select requests for Search Engine add responder policy p5

URLs with a reputation score equal to 4. ‘CLIENT.SSL.DETECTED_DOMAIN.URL_CATEGORIZE(4,0).
CATEGORY.EQ(“Search Engine”)

URL Categorization Policy Actions

A URL filtering policy evaluates the traffic to identify requests belonging to a particular category. The
following table lists the actions that you can assign to a URL filtering policy.

Policy Action Policy Group Description

ALLOW Responder Allow incoming request to

access the target URL
REDIRECT Responder Redirect incoming request to
the URL specified as the
target.
DENY Responder Deny incoming request.
RESET Responder, Reset connection.
VideoOptimization
DROP Responder, Drop connection.
VideoOptimization

Note

For encrypted traffic, the VideoOptimization policy includes actions that implement the URL Fil-
tering actions.

Configuring URL Categorization

To configure URL categorization, begin by enabling the URL Filtering feature. You must then config-
ure the cache memory limits, categorization policy, and virtual servers for HTTP and HTTPS traffic.
Configuring URL Categorization by using the CLI.

To use the CLI configure URL categorization on a NetScaler appliance, do the following:

• Set up URL Categorization.

– Enable the URL Filtering feature.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 576

NetScaler 12.0

– Configure shared memory to limit cache memory.

– Configure URL categorization parameters.
• Configure URL categorization for HTTP traffic.
– Add URL categorization actions.
– Add URL categorization policies.
– Add a load balancing virtual server for HTTP traffic.
– Bind URL categorization policies to the load balancing virtual server.
• Configure URL categorization for HTTPS traffic.
– Add URL categorization policies.
– Add a SSL-Bridge load balancing virtual server.
– Bind URL categorization policies to the load balancing virtual server.

Setting up URL Categorization

To set up the feature, you must enable the URL Categorization feature, configure the filtering parame-
ters and set the shared memory limit.

To enable URL Filtering feature

At the command prompt, type:

enable ns feature URLFiltering VideoOptimization Responder IC SSL AppFlow

To configure shared memory limit

At the command prompt, type:

1 set cache parameter [-memLimit <megaBytes>]

where memLimit is the memory limit for caching.

Example:

1 set cache parameter -memLimit 10

To configure URL categorization parameters

At the command prompt, type:

1 set urlfiltering parameter [-HoursBetweenDBUpdates <positive_integer>]

[-TimeOfDayToUpdateDB <HH:MM>]

© 1999-2018 Citrix Systems, Inc. All rights reserved. 577

NetScaler 12.0

*Example:

1 set urlfiltering parameter -HoursBetweenDBUpdates 3 -

TimeOfDayToUpdateDB 03:00

Configuring URL categorization for HTTP traffic

To configure the URL categorization feature for HTTP traffic, you must configure a loading balancing
virtual server, add URL categorization policies and bind the policies to the virtual server. By doing
so, the virtual server receives the HTTP traffic and based on policy evaluation, the system assigns a
filtering action.

To add URL categorization action for HTTP traffic

At the command prompt, type:

1 add responder action <name> <type> (<target> | <htmlpage>) [-comment <

string>] [-responseStatusCode <positive_integer>] [-reasonPhrase <
string>]

Example:

1 add responder action act_url_categorize respondwith ””HTTP/1.1 200 OK\r

\n\r\n\” + HTTP.REQ.HOSTNAME.APPEND(HTTP.REQ.URL).URL_CATEGORIZE
(0,0).CATEGORY + ”\n\””

To add URL categorization policy for HTTP traffic

At the command prompt, type:

1 add responder policy <name> <rule> <action> [<undefAction>] [-comment <

string>] [-logAction <string>] [-appflowAction <string>]

Example:

1 add responder policy pol_url_categorize_http ”HTTP.REQ.HOSTNAME.APPEND(

HTTP.REQ.URL).URL_CATEGORIZE(0,0).GROUP.EQ(\”Adult\”) || HTTP.REQ.
HOSTNAME.APPEND(HTTP.REQ.URL).URL_CATEGORIZE(0,0).GROUP.EQ (\”
Gambling\”)” RESET

© 1999-2018 Citrix Systems, Inc. All rights reserved. 578

NetScaler 12.0

To add a HTTP load balancing virtual server

If a virtual server for HTTP traffic is not already configured, at the command prompt, type:

1 add lb vserver <name> [-td <positive_integer>] <serviceType> [-clt

Timeout <secs>]

Example:

add lb vserver vsrv-HTTP HTTP * 80 -persistenceType NONE -cltTimeout 120

To bind URL categorization policy with load balancing virtual server

At the command prompt, type:

1 bind lb vserver <name> -policyName <string> [-priority <

positive_integer>]

Example:

1 bind lb vsrv-HTTP -policyName pol_url_categorize_http -priority 10 -

gotoPriorityExpression END -type REQUEST

Configuring URL categorization for HTTPS traffic

To configure the URL categorization feature for HTTPS traffic, you must configure a SSL-bride loading
balancing virtual server, add URL categorization policies and bind the policies to the SSL-bridge virtual
server. By doing so, the server receives the HTTPS traffic and based on policy evaluation, the system
assigns a filtering action.

To add URL categorization policy for HTTPS traffic

At the command prompt, type:

1 add videooptimization detectionpolicy <name> -rule <expression> -action

<string> [-undefAction <string>] [-comment <string>] [-logAction <
string>]

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 579

NetScaler 12.0

1 add videooptimization detectionpolicy

pol_url_categorize_https_block_adult ‒ rule ’CLIENT.SSL.
DETECTED_DOMAIN.URL_CATEGORIZE(0,0).CATEGORY.EQ(”Adult”)’ ‒ action
RESET

To add SSL-Bridge load balancing virtual server

At the command prompt, type:

1 add lb vserver <name> [-td <positive_integer>] <serviceType> [-cltT

imeout <secs>]

Example:

1 add lb vserver vsrv-HTTPS SSL_BRIDGE * 443 -persistenceType NONE -

cltTimeout 180

To bind categorization policy with SSL-Bridge virtual server

At the command prompt, type:

1 bind lb vserver <name> -policyName <string> [-priority <

positive_integer>]

Example:

1 bind lb vserver vsrv-HTTPS -policyName

pol_url_categorize_https_block_adult -priority 20 -type REQUEST

Configuring URL Categorization by using the GUI

The GUI enables you to:

• Enable the URL Categorization feature.

• Add URL Categorization actions for HTTP traffic.
• Add URL Categorization policies for HTTP traffic.
• Add URL Categorization policies for HTTPS traffic.
• Add a load balancing virtual server for HTTP traffic.
• Add an SSL bridge load balancing virtual server for HTTPS traffic.
• Bind URL Categorization policies to the load balancing virtual server.
• Bind URL Categorization policies to the SSL-Bridge load balancing virtual server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 580

NetScaler 12.0

• Configure shared memory limit.

• Configure URL categorization parameters.

To enable URL categorization

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

2. On the Settings page, click Configure Advanced Features link.
3. On the Configure Advanced Features page, select URL Filtering check box.
4. Click OK and Close.

To add a URL categorization action

1. In the navigation pane, expand AppExpert > Responder > Action.

2. In the details pane, click Add.
3. On the Create Responder Action page, set the following parameters.
a) Name. Name of the URL categorization policy action.
b) Type. Select an action type.
c) Expression. Use the expression editor to create the policy expression.
d) Comments. A short description of the policy action.
4. Click Create and Close.

To add a URL categorization policy for HTTP traffic

1. In the navigation pane, expand AppExpert > Responder > Policies.

2. On the details pane, click Add.
3. On the Create Responder Policy page, set the following parameters.
a) Name. Name of the URL categorization policy action.
b) Action. Select the URL Categorization action that you prefer to associate with the policy.
c) Log Action. Select the log action.
d) AppFlow. Select an Appflow action.
e) Expression. Use the expression editor to create the policy expression.
f) Comments. A short description about the policy action.
4. Click Create and Close.

To add a categorization policy for HTTPS traffic

1. Log on to the NetScaler appliance and navigate to Configuration > Optimization > Video Op-
timization > Detection.
2. On the Detection page, click the Video Optimization Detection Policies link.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 581

NetScaler 12.0

3. On the Video Optimization Detection Policies page, click Add.

4. On the Create Video Optimization Detection Policy page, set the following parameters.
a) Name. Name of the optimization policy
b) Expression. Configure policy using custom expressions.
c) Action. Optimization action associated with the policy to handle the incoming video traf-
fic.
d) UNDEF Action. Undefined event if the incoming request does not match the optimization
policy.
e) Comment. A short description about the policy.
f) Log Action. Select an audit log action that specifies the action to be performed for the log
messages.
5. Click Create and Close.

To add a load balancing virtual server for HTTP traffic

1. Navigate to the Traffic Management > Load Balancing > Virtual Servers page.
2. In the details pane, click Add.
3. On the Load Balancing Virtual Server page set the following parameters:
a) Name. Name of the load balancing virtual server.
b) Protocol. Choose protocol type as HTTP.
c) IP Address Type. IPv4 or IPv6.
d) IP Address. IPv4 or IPv6, VIP address assigned to the virtual server.
e) Port. Port number of the virtual server.
4. Click OK to continue with the configuration of other, optional, parameters.
5. Click Create and Close.

To add an SSL-bridge load balancing virtual server

1. Navigate to the Traffic Management > Load Balancing > Virtual Servers page.
2. On the details pane, click Add.
3. On the Load Balancing Virtual Server page, set the following parameters:
a) Name. Name of the load balancing virtual server.
b) Protocol. Select protocol type as SSL-bridge.
c) IP Address Type. IP addressable type.
d) IP Address. IP 4 or IP6 IP address assigned to the virtual server.
e) Port. Port number of the virtual server.
4. Choose OK to continue configuration other optional parameters.
5. Click Create and then Close.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 582

NetScaler 12.0

To bind a URL categorization policy to the HTTP load balancing virtual server

1. Navigate to Traffic Management > Load Balancing > Virtual Servers page.
2. On the details pane, select the load balancing virtual server and click Edit.
3. In the Advanced Setting section, click Policies.
4. In the Policies section, click the + icon to access the Policies slider.
5. Set the following parameters.
a) Choose Policy. Select URL categorization policy from the drop-down list.
b) Choose Type. Select the policy type as Request.
6. Click Continue.
7. Select the URL categorization policy from the list and click Close.

To bind a categorization policy to the SSL-bridge load balancing virtual server

1. Navigate to Traffic Management > Load Balancing > Virtual Servers screen.
2. In the details pane, select the SSL-bridge load balancing virtual server and click Edit.
3. In the Advanced Setting section, click Policies.
4. In the Policies section, click + icon to access the Policies slider.
5. In the Policies section, set the following parameters.
a) Choose Policy. Select video detection policy from the drop-down list.
b) Choose Type. Select the policy type as Request.
6. Click Continue.
7. Select the video detection policy from the list and click Close.

To configure the shared memory limit

1. Sign on to the appliance and navigate to Optimization.

2. In the details pane, click Change cache settings link.
3. On the Cache Global Settings page, set the following parameters.
a) Memory Usage Limit (MB).
b) Active memory Usage Limit.
c) Via Header.
d) Maximum Post Body Length to be Cached
e) Global Undefined-Result Action
f) Enable HA Object Persist
g) Verify Cached Object Persist
h) Prefetches
4. Click OK and Close

© 1999-2018 Citrix Systems, Inc. All rights reserved. 583

NetScaler 12.0

To configure URL categorization parameters

1. Sign to the appliance and navigate to Security.

2. On the details pane, click Change URL filtering settings link.
3. In the Configuring URL Filtering Params page, set the following parameters.
a) Hours Between DB Updates. URL Filtering hours between database updates. Minimum
value: 0 and Maximum value: 720.
b) Time of Day to Update DB. URL Filtering time of day to update the database.
4. Click OK and Close.

Configuring Audit Log Messaging

Audit logging enables you to review a condition or a situation in any phase of URL Categorization
process. When a NetScaler appliance receives an incoming URL, if the responder policy has an URL
Filtering expression, the audit log feature collects URL Set information in the URL and stores it as log
messages for any target allowed by audit logging.

Source IP address (the IP address of the client that made the request).

• Destination IP address (the IP address of the requested server).

• Requested URL containing the schema, the host and the domain name (http://www.example
.com).
• URL category that the URL filtering framework returns.
• URL category group that the URL filtering framework returned.
• URL reputation number that the URL filtering framework returned.
• Audit log action taken by URL Categorization policy.

To configure audit logging for URL List feature, you must complete the following tasks:

1. Enable Audit Log.

2. Create Audit Log message action.
3. Set URL List responder policy with Audit Log message action.

For more information, see Audit Logging topic.

Storing Failure Errors Using SYSLOG Messaging

At any stage of the URL Filtering process, if there is a system-level failure, the NetScaler appliance
uses the audit log mechanism to store logs in the ns.log file. The errors are stored as text messages in
SYSLOG format so that, an administrator can view it later in a chronological order of event occurrence.
These logs are also sent to an external SYSLOG server for archival. For more information, see article
CTX229399.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 584

NetScaler 12.0

For example, if a failure occurs when you initialize the URL Filtering SDK, the error message is stored
in the following messaging format.

Oct 3 15:43:40 <local0.err> ns URLFiltering[1349]: Error initializing NetStar SDK (SDK error=-1).
(status=1).

The NetScaler appliance stores the error messages under four different failure categories:

• Download failure. If an error occurs when you try to download the categorization database.
• Integration failure. If an error occurs when you integrate an update into the existing categoriza-
tion database.
• Initialization failure. If an error occurs when you initialize the URL Categorization feature, set
categorization parameters, or end a categorization service.
• Retrieval failure. If an error occurs when the appliance retrieves the categorization details of the
request.

URL Reputation Score

The URL Categorization feature provides policy-based control to restrict blacklisted URLs. You can
control access to web sites based on URL category, reputation score, or URL category and reputation
score. If a network administrator monitors a user accessing highly risky websites, he or she can use a
responder policy bound to the URL reputation score to block such risky web sites.

Upon receiving an incoming URL request, the appliance retrieves the category and reputation score
from the URL categorization database. Based on the reputation score returned by the database, the
appliance assigns a reputation rating for websites. The value can range from 1 to 4, where 4 is the
riskiest type of websites, as shown in the following table.

URL Reputation Rating Reputation Comment

1 Clean site.
2 Unknown site.
3 Potentially dangerous or affiliated to
dangerous site.
4 Malicious site.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 585

NetScaler 12.0

NetScaler Solutions

September 17, 2018

Contributed by:
C

NetScaler solutions simplify the task of setting up frequently deployed configurations. Check this
space from time to time for additional solutions.

This section includes the following solutions

• Setting Up NetScaler for XenApp/XenDesktop

• Global Server Load Balancing (GSLB) Powered Zone Preference
• NetScaler in a Private Cloud Managed by Microsoft Windows Azure Pack and Cisco ACI

1.
2. Citrix ADC
3. NetScaler 12.0

Setting Up NetScaler appliance for XenApp/XenDesktop

January 6, 2019

Contributed by:
C

A NetScaler appliance can provide load balanced, secure remote access to your XenApp/XenDesktop
applications. You can use the NetScaler appliance load balancing feature to distribute traffic across
the XenApp/XenDesktop servers, and the NetScaler Gateway feature to provide secure remote access
to the servers. NetScaler appliance can also accelerate and optimize the traffic flow and offer visibility
features that are useful for XenApp/XenDesktop deployments.

Figure 1. NetScaler appliance in XenApp/XenDesktop Setup

The above figure shows the components involved in this deployment:

• NetScaler Gateway.** Provides the URL for user access, and provides security by authenticating
the users.

• NetScaler appliance load balancing virtual server. Load balances the traffic for the Web In-
terface or StoreFront servers. You can also deploy a load balancing virtual server in front of the

© 1999-2018 Citrix Systems, Inc. All rights reserved. 586

NetScaler 12.0

XenApp/XenDesktop servers to load balance key components such as XML Broker and Desktop
Delivery Controller (DDC) server.

• Web Interface or StoreFront or Web Interface on NetScaler appliance. Provides the interface
through which you can access the applications.

Note: Web Interface on NetScaler (WIonNS) is a customization of the Web Interface product,
hosted on the NetScaler appliance.

• XenApp/XenDesktop. Provides the applications that your users want to access.

To set up the NetScaler appliance for XenApp/XenDesktop by using the NetScaler appliance GUI

Prerequisites

• XenApp/XenDesktop servers are configured and available.

• Web Interface, StoreFront, or Web Interface on NetScaler servers are configured and available.
• You have a working knowledge of NetScaler Gateway, NetScaler, XenApp, XenDesktop, and
StoreFront/Web Interface/Web Interface on NetScaler. For more information, see “Citrix eDocs.”
• Make sure that you have configured a virtual server and a service and bound the service to the
virtual server.

Procedure:

1. Log on to the NetScaler appliance and on the Configuration tab click XenApp and XenDesktop.
2. On the Details pane, click Get Started. If the setup exists on the NetScaler, click the Edit link
corresponding to each of the section that you want to modify.
3. Select the product (StoreFront, Web Interface, or Web Interface on NetScaler appliance) that in
your deployment provides the interface for access to the XenApp/XenDesktop applications.
4. Set up secure remote access.
a) In the NetScaler Gateway Settings** section, specify the details for the VPN virtual server
and click Continue.
b) In the Server Certificate section, choose an existing certificate or install a new certificate
and click Continue.
c) In the Authentication section, configure the primary authentication mechanism to be
used and specify the server details or use an existing server and click Continue.
d) In the StoreFront section, specify the details of the server that provides the interface for
accessing the applications and click Continue.
e) You can use one of the following as your StoreFront server.
i. LB vserver pointing to multiple SF servers.
ii. Web Interface or StoreFront server directly reachable from the NetScaler appliance.
iii. Web Interface on NetScaler.
5. Click Done to complete the configuration.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 587

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0

Global Server Load Balancing (GSLB) Powered Zone Preference

January 6, 2019

Contributed by:
C

GSLB powered zone preference is a feature that integrates XenApp/XenDesktop, StoreFront, and
NetScaler appliance to provide clients access to the most optimized data center on the basis of the
client location.

In a distributed XenApp/XenDesktop deployment, StoreFront might not select an optimal datacenter

when multiple equivalent resources are available from multiple datacenters. In such cases, StoreFront
randomly selects a datacenter. It can send the request to any of the XenApp/XenDesktop servers in
any datacenter, regardless of proximity to the client making the request.

With this enhancement, the client IP address is examined when an HTTP request arrives at the
NetScaler Gateway appliance, and the real client IP address is used to create the datacenter prefer-
ence list that is forwarded to StoreFront. If the NetScaler appliance is configured to insert the zone
preference header, StoreFront 3.5 or later can use the information provided by the appliance to
reorder the list of delivery controllers and connect to an optimal delivery controller in the same zone
as the client. StoreFront selects the optimal gateway VPN virtual server for the selected datacenter
zone, adds this information to the ICA file with appropriate IP addresses, and sends it to the client.
Storefront then tries to launch applications hosted on the preferred datacenter’s delivery controllers
before trying to contact equivalent controllers in other datacenters.

For more information about configuring this solution, click here.

For a video overview about GSLB powered zone preference solution, click https://www.youtube.com/
watch?v=Y8DELum0Xp0.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 588

NetScaler 12.0

NetScaler appliance in a Private Cloud Managed by Microsoft Windows

Azure Pack and Cisco ACI

January 6, 2019

Contributed by:
C

You can use a NetScaler appliance for load balancing in a private cloud that is managed through Mi-
crosoft Windows Azure Pack. The network for the private cloud is automated by using Cisco ACI and
NetScaler appliance.

This solution involves many integration points, such as Windows Azure Pack (WAP) to Cisco APIC, Cisco
APIC to System Center Virtual Machine Manager (SCVMM), and Cisco APIC to NetScaler appliance. As a
tenant in the private cloud, you can enable NAT, provision network services, and add a load balancer.

WAP supports tenant and administrator portals where an administrator can perform administrative
tasks such as ACI registration, VIP range, NetScaler appliance device association with virtual machine
cloud, tenant user account creation, and so on. Tenants can log on to the WAP Tenant Portal and
configure the network, bridge domains, and Virtual Routing and Forwarding (VRFs), and make use of
the NetScaler appliance load balancing and RNAT features.

Important

• In this solution, the NetScaler appliance provides only basic load balancing.
• Tenants can deploy multiple VIP addresses with different ports for the same network, but
must ensure that the IP and port combination is unique.
• The NetScaler appliance device package supports only single-context deployment. Each
Tenant gets a dedicated NetScaler appliance instance.
• WAP supports NetScaler appliance MPX appliances and NetScaler appliance VPX virtual ap-
pliances, including NetScaler appliance VPX instances deployed on the NetScaler appliance
SDX platform.

The following illustration provides an overview of the solution:

Prerequisites

Make sure that:

• You have conceptual knowledge of Cisco ACI components and NetScaler appliances.
– For more information about Cisco ACI and its components, see the product docu-
mentation at: http://www.cisco.com/c/en/us/support/cloud-systems-management/

© 1999-2018 Citrix Systems, Inc. All rights reserved. 589

NetScaler 12.0

application-policy-infrastructure-controller-apic/tsd-products-support-series-home.
html.
– For more information about the NetScaler appliances, see the NetScaler appliance prod-
uct documentation at http://docs.citrix.com/.
• All the required components of Cisco ACI, including Cisco APIC in the datacenter, are set up
and configured. For more information about Cisco ACI and its components, see the product
documentation at: http://www.cisco.com/c/en/us/support/cloud-systems-management/
application-policy-infrastructure-controller-apic/tsd-products-support-series-home.html.
• You know how to integrate Cisco ACI with Microsoft Windows Azure Pack. See the product doc-
umentation at: http://www.cisco.com/c/en/us/td/docs/switches/datacenter/aci/apic/sw/2-x/
virtualization/b_ACI_Virtualization_Guide_2_2_1.html.
• You have conceptual knowledge of Microsoft Windows Azure Pack. See the product documen-
tation at: https://www.microsoft.com/en-in/cloud-platform/windows-azure-pack.
• You have installed NetScaler appliance software release 11.1 or later.
• You configure NetScaler appliances in Cisco ACI, so that they can be managed by using Cisco
APIC.
• From Cisco APIC, make sure that:
– Management connectivity of Cisco APIC to NetScaler appliance are established.
– You upload the NetScaler appliance device package version 11.1-52.3 and register the
NetScaler appliance device in Cisco ACI by using Cisco APIC.
– You configure the NetScaler appliance in Cisco APIC’s common tenant and make sure that
there are no faults in Cisco APIC.
– You have configured all the APIC specific configurations such as, VLAN pool, L3OutServicesDom,
L3ExtOUt, resource pool, and so on. For more information, see Cisco documentation.

1.
2. Citrix ADC
3. NetScaler 12.0

Creating a NetScaler appliance Load Balancer in a Plan in the Service

Management Portal (Admin Portal)

January 6, 2019

Contributed by:
C

The Service Management Portal in WAP allows an administrator to register Cisco APIC with WAP and
also create a hosting plan. As part of the plan, you can specify the VIP range, associate the NetScaler

© 1999-2018 Citrix Systems, Inc. All rights reserved. 590

NetScaler 12.0

appliance load balancer with the plan, create tenant user accounts, and so on.

To create a NetScaler appliance Load Balancer in a Plan in the Admin Portal:

1. Log in to the Service Management Portal (Admin Portal).

2. In the Navigation pane, select PLANS.

3. In the plans pane, select the plan that you want to add a load balancer.

4. In the selected plan’s pane, select Networking (ACI).

5. On the Networking (ACI) pane, in the L4-L7 SERVICE POOL drop-down list, select the L4-L7
resource pool that you had created in Cisco APIC.

6. Create a tenant user account and associate the user with the plan you have created.

1.
2. Citrix ADC
3. NetScaler 12.0

Configuring a NetScaler appliance Load Balancer by Using the Service

Management Portal (Tenant Portal)

January 6, 2019

Contributed by:
C

In WAP, once the Tenant creates the Bride Domain (BD), VRF, and a Network, the Tenant can configure
NetScaler appliance Load Balancer through the Service Management Portal (Tenant Portal).

To configure NetScaler appliance Load Balancer in Service Management Portal (Tenant Portal)

1. Log on to the Service Management Portal (Tenant Portal).

2. Create a bridge domain and VRF, as follows:

a. In the navigation pane, select ACI.

b. Click NEW.

c. In the NEW pane, select BRIDGE DOMAIN.

d. In the BRIDGE DOMAIN field, enter the bridge domain name (for example, BD01).

e. (Optional) In the SUBNET’S GATEWAY field, enter the subnet’s gateway (for example,
192.168.1.1/24).

© 1999-2018 Citrix Systems, Inc. All rights reserved. 591

NetScaler 12.0

f. In the VRF field, select a VRF that is already part of the subscription or select Create One to
create a VRF.

g. Click CREATE.

3. Create a network and associate it with the bridge domain that you created. Do the following:

a. In the navigation pane, select ACI.

b. Click NEW.

c. In the NEW pane, select NETWORK.

d. In the NETWORK NAME field, enter the network name (for example, S01).

e. In the BRIDGE DOMAIN drop-down list, select the bridge domain you have created. (for
example, BD01).

f. In the subnet’s GATEWAY field, enter the subnet’s gateway address (for example, 172.23.2.1/24).

g. (Optional) In the DNS SERVER IP/IPS field, enter the DNS server details.

h. Click CREATE.

4. In the ACI pane, select NETWORKS.

5. Double-click the network that you have created. Then, in the network pane, select Enable load
balancer (public). In the IP ADDRESS field, a VIP is automatically assigned from the VIP Range that
the administrator configured in the Admin Portal. For more information, see [Creating a NetScaler
appliance Load Balancer to a Plan in Service Management Portal (Admin Portal)].
6. Double-click the network that you have created. Then, in the network pane, select Enable load
balancer (public). In the IP ADDRESS field, a VIP is automatically assigned from the VIP Range that
the administrator configured in the Admin Portal. For more information, see [Creating a NetScaler
appliance Load Balancer to a Plan in Service Management Portal Admin Portal]

6. In the network pane, select the Load Balancers tab, and click ADD.

7. In the ADD NETWORK LOAD BALANCER pane, do the following:

a. In the NAME field, enter the name for the load balancer.

b. Optionally, in the VIRTUAL IP ADDRESS field, assign the load balancer a VIP address from the
VIP range that you defined earlier.

c. Optionally, in the PROTOCOL field, select TCP.

d. In the PORT field, enter the port number.

8. Click CREATE.
The NetScaler appliance Load Balancer is displayed in the LOAD BALANCERS tab and the
NetScaler appliance Load Balancer is data path ready.

1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 592

NetScaler 12.0

2. Citrix ADC
3. NetScaler 12.0

Deleting a NetScaler appliance Load Balancer from the Network

January 6, 2019

Contributed by:
C

Using Service Management Portal (Tenant Portal), from the Network, you can delete the NetScaler
appliance load balancer that you created.

To delete a NetScaler appliance load balancer from the Network:

1. Log on to the Service Management Portal (Tenant Portal).

2. In the navigation pane, select ACI.

3. In the ACI pane, on the NETWORKS tab, click the network that you created.

4. In the selected network’s pane, select the NetScaler appliance load balancer and click DELETE.

5. Click OK to delete the NetScaler appliance load balancer.

1.
2. Citrix ADC
3. NetScaler 12.0

Deploy a NetScaler VPX instance

March 7, 2019

Contributed by:
C

The NetScaler VPX product is a virtual appliance that can be hosted on a wide variety of virtualization
and cloud platforms:

• Citrix XenServer
• VMware ESX
• Microsoft Hyper-V
• Linux KVM

© 1999-2018 Citrix Systems, Inc. All rights reserved. 593

NetScaler 12.0

• Amazon Web Services

• Microsoft Azure

For more information, see the NetScaler VPX data sheet.

For more information about provisioning a Citrix ADC VPX instance on an SDX appliance, see Provi-
sioning Citrix ADC instances.

NetScaler Management and Analytics for NetScaler VPX instances

NetScaler Management and Analytics Service (MAS) is a centralized management solution that simpli-
fies operations by providing administrators with enterprise-wide visibility and automating manage-
ment jobs that need to be executed across multiple instances.

You can manage and monitor NetScaler VPX instances as well as other Citrix application networking
products such as Citrix Gateway, NetScaler SDX, NetScaler CPX, and Citrix SD-WAN. You can use MAS to
manage, monitor, and troubleshoot the entire global application delivery infrastructure from a single,
unified console.

For more information, see NetScaler Management and Analytics documentation.

1.
2. Citrix ADC
3. NetScaler 12.0

Support matrix and usage guidelines

March 15, 2019

Contributed by:
C

This document lists the different hypervisors and features supported on a NetScaler VPX instance as
well as the limitations and usage guidelines that apply.

• Table 1-5 list the different supported hypervisors.

• Table 6 lists the different VPX features and limitations for the different hypervisors supported
on a NetScaler VPX instance.
• Table 7 lists the supported web browsers that allow you access the GUI and Dashboard.

Table 1. VPX instance on XenServer

© 1999-2018 Citrix Systems, Inc. All rights reserved. 594

NetScaler 12.0

XenServer version SysID VPX models

6.5, 7.0,7.1 450000 VPX 10, VPX 25, VPX 200, VPX
1000, VPX 3000, VPX 5000,
VPX 8000, VPX 10G, VPX 15G,
VPX 25G, VPX 40G

Table 2. VPX instance on VMware ESX server

VMware ESX version SysID VPX models

6.0, build numbers 3620759, 450010 VPX 10, VPX 25, VPX 200, VPX
5050593 (supported from 1000, VPX 3000, VPX 5000,
NetScaler release 12.0 build VPX 8000, VPX 10G, VPX 15G,
51.x onwards) 6765062 VPX 25G, VPX 40G, VPX 100G
(supported from NetScaler
release 12.0 build 56.20
onwards). 6.5, build numbers
4564106 and patch 7967591

Table 3. VPX on Microsoft Hyper-V

Hyper-V version SysID VPX models

2012, 2012R2 450020 VPX 10, VPX 25, VPX 200, VPX
1000, VPX 3000, VPX 8000

Table 4. VPX instance on generic KVM

Generic KVM version SysID VPX models

RHEL 7.3, Ubuntu 16.04 450070 VPX 10, VPX 25, VPX 200, VPX
1000, VPX 3000, VPX 5000,
VPX 8000, VPX 10G, VPX 15G.
VPX 25G, VPX 40G, VPX 100G

© 1999-2018 Citrix Systems, Inc. All rights reserved. 595

NetScaler 12.0

Note: The VPX instance is qualified for hypervisor release versions mentioned in table 1–4, and
not for patch releases within a version. However, the VPX instance is expected to work seamlessly
with patch releases of a supported version. If it does not, log a support case for troubleshooting
and debugging.

Table 5. VPX instance on AWS

AWS version SysID VPX models

N/A 450040 VPX 10, VPX 200, VPX 1000,

VPX 3000, VPX 5000, VPX 15G,
VPX BYOL

Table 6. VPX instance on Azure

Azure version SysID VPX models

N/A 450020 VPX 10, VPX 200, VPX 1000,

VPX 3000, VPX BYOL

Table 7. VPX feature matrix

*Clustering support is available on SRIOV for client- and server-facing interfaces and not for the back-
plane.

**Interface DOWN events are not recorded in NetScaler VPX instances.

For Static LA, traffic might still be sent on the interface whose physical status is DOWN.

For LACP, peer device knows interface DOWN event based on LACP timeout mechanism.

Short timeout: 3 seconds

Long timeout: 90 seconds

For LACP, interfaces should not be shared across VMs.

For Dynamic routing, convergence time depends on the Routing Protocol since link events are not
detected.

Monitored static Route functionality fails if monitors are not bound to static routes since Route state
depends on the VLAN status. The VLAN status depends on the link status.

Partial failure detection does not happen in high availability if there is link failure. High availability-
split brain condition might happen if there is link failure.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 596

NetScaler 12.0

***When any link event (disable/enable, reset) is generated from a VPX instance, the physical status of
the link does not change. For static LA, any traffic initiated by the peer gets dropped on the instance.

For LACP, peer device knows interface DOWN event based on LACP timeout mechanism.

Short timeout: 3 seconds

Long timeout: 90 seconds

For LACP, interfaces should not be shared across VMs.

• For the VLAN tagging feature to work, do the following:

On the VMware ESX, set the port group’s VLAN ID to 1–4095 on the vSwitch of VMware ESX server. For
more information about setting a VLAN ID on the vSwitch of VMware ESX server, see pdf.

Table 7. Supported browsers

Operating system Browser and versions

Windows 7 Internet Explorer- 8, 9, 10, and 11; Mozilla

Firefox 3.6.25 and above; Google Chrome- 15
and above
Windows 64 bit Internet Explorer - 8, 9; Google Chrome - 15 and
above
MAC Mozilla Firefox - 12 and above; Safari - 5.1.3;
Google Chrome - 15 and above

1.
2. Citrix ADC
3. NetScaler 12.0

Install a NetScaler VPX instance on XenServer

May 14, 2019

Contributed by:
C

To install VPX instances on Citrix XenServer, you must first install XenServer on a machine with ade-
quate system resources. To perform the NetScaler VPX instance installation, you use Citrix XenCenter,
which must be installed on a remote machine that can connect to the XenServer host through the
network.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 597

NetScaler 12.0

For more information about XenServer, see XenServer documentation.

The following figure shows the bare-metal solution architecture of NetScaler VPX instance on
XenServer.

Figure. A NetScaler VPX instance on XenServer

Prerequisites for installing a NetScaler VPX instance on XenServer

Before you begin installing a virtual appliance, do the following:

• Install XenServer version 6.0 or later on hardware that meets the minimum requirements.
• Install XenCenter on a management workstation that meets the minimum system requirements.
• Obtain virtual appliance license files. For more information about virtual appliance licenses,
see the NetScaler VPX Licensing Guide at http://support.citrix.com/article/ctx122426.

XenServer hardware requirements

The following table describes the minimum hardware requirements for a XenServer platform running
a NetScaler VPX instance.

Table 1. Minimum system requirements for XenServer running a nCore VPX instance

Component Requirement

CPU 2 or more 64-bit x86 CPUs with virtualization

assist (Intel-VT) enabled. Note: To run
NetScaler VPX instance, hardware support for
virtualization must be enabled on the
XenServer host. Make sure that the BIOS
option for virtualization support is not
disabled. Consult your BIOS documentation
for more details.
RAM 3 GB
Disk space Locally attached storage (PATA, SATA, SCSI)
with 40 GB of disk space. Note: XenServer
installation creates a 4 GB partition for the
XenServer host control domain; the remaining
space is available for NetScaler VPX instance
and other virtual machines.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 598

NetScaler 12.0

Component Requirement

NIC One 1-Gbps NIC; recommended: two 1-Gbps

NICs

For information about installing XenServer, see the XenServer documentation at http://support.citrix.
com/product/xens/.

The following table lists the virtual computing resources that XenServer must provide for each nCore
VPX virtual appliance.

Table 2. Minimum virtual computing resources required for running a ncore VPX instance

Component Requirement

Memory 2 GB
Virtual CPU (VCPU) 2
Virtual network interfaces 2

Note: For production use of

NetScaler VPX instance, Citrix recommends that CPU priority (in virtual machine properties) be
set to the highest level, in order to improve scheduling behavior and network latency.

XenCenter system requirements

XenCenter is a Windows client application. It cannot run on the same machine as the XenServer host.
For more information about minimum system requirements and installing XenCenter, see the follow-
ing XenServer documents:

• System requirements
• Install

Install NetScaler VPX instances on XenServer by using XenCenter

After you have installed and configured XenServer and XenCenter, you can use XenCenter to install
virtual appliances on XenServer. The number of virtual appliances that you can install depends on
the amount of memory available on the hardware that is running XenServer.

After you have used XenCenter to install the initial NetScaler VPX instance (.xva image) on XenServer,

© 1999-2018 Citrix Systems, Inc. All rights reserved. 599

NetScaler 12.0

you have the option to use Command Center to provision NetScaler VPX instance. For more informa-
tion, see the Command Center documentation.

To install NetScaler VPX instances on XenServer by using XenCenter, follow these steps:

1. Start XenCenter on your workstation.

2. On the Server menu, click Add.
3. In the Add New Server dialog box, in the Hostname text box, type the IP address or DNS name
of the XenServer that you want to connect to.
4. In the User Name and Password text boxes, type the administrator credentials, and then click
Connect. The XenServer name appears in the navigation pane with a green circle, which indi-
cates that the XenServer is connected.
5. In the navigation pane, click the name of the XenServer on which you want to install NetScaler
VPX instance.
6. On the VM menu, click Import.
7. In the Import dialog box, in Import file name, browse to the location at which you saved the
NetScaler VPX instance .xva image file. Make sure that the Exported VM option is selected, and
then click Next.
8. Select the XenServer on which you want to install the virtual appliance, and then click Next.
9. Select the local storage repository in which to store the virtual appliance, and then click Import
to begin the import process.
10. You can add, modify, or delete virtual network interfaces as required. When finished, click Next.
11. Click Finish to complete the import process.
Note: To view the status of the import process, click the
Log tab.
12. If you want to install another virtual appliance, repeat steps 5 through 11.

Note

After the initial configuration of the VPX instance, if you want to upgrade the appliance to the
latest software release, see Upgrading or Downgrading the System Software.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure VPX instances to use single root I/O virtualization (SR-IOV)

network interfaces

November 2, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 600

NetScaler 12.0

Contributed by:
C

After you have installed and configured a NetScaler VPX instance on XenServer, you can configure the
virtual appliance to use SR-IOV network interfaces.

Limitations

XenServer does not support the following features on SRIOV interfaces:

• L2 mode switching
• Clustering
• Admin partitioning [Shared VLAN mode]
• High Availability [Active - Active mode]
• Jumbo frames
• IPv6 protocol in Cluster environment

Prerequisites

On the XenServer host, ensure that you:

• Add the Intel 82599 Network Interface Card (NIC) to the host.
• Blacklist the ixgbevf driver by adding the following entry to the /etc/modprobe.d/blacklist.conf
file:
blacklist ixgbevf
• Enable SR-IOV Virtual Functions (VFs) by adding the following entry to the /etc/mod-
probe.d/ixgbe file:
options ixgbe max_vfs=<number_of_VFs>
where <number_VFs> is the number of SR-IOV VFs that you want to create.
• Verify that SR-IOV is enabled in BIOS.

IXGBE driver version 3.22.3 is recommended.

Assign SR-IOV VFs to the VPX instance by using the XenServer host

To assign SR-IOV network interfaces to NetScaler VPX instance, follow these steps:

1. On the XenServer host, use the following command to assign the SR-IOV VFs to the NetScaler VPX
instance:

xe host-call-plugin plugin=iovirt host-uuid=<Xen host UUID> fn=assign_free_vf args:uuid=<Netscalar

VM UUID> args:ethdev=<interface name> args:mac=<mac addr>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 601

NetScaler 12.0

Where:
• <Xen host UUID> is the UUID of the XenServer host.
• <Netscalar VM UUID> is the UUID of the NetScaler VPX instance.
• <interface name> is the interface for the SR-IOV VFs.
• <mac addr > is the mac address of the SR-IOV VF.
Note

Specify the mac address that you want use in the args:mac= parameter, if not specified, the iovirt
script randomly generates and assigns a mac address. Also, if you want use the SR-IOV VFs in Link
Aggregation mode, make sure that you specify the mac address as 00:00:00:00:00:00.

2. Boot the NetScaler VPX instance.

Unassign SR-IOV VFs to the VPX instance by using the XenServer host

If you have assigned an incorrect SR-IOV VFs or if you want modify the a assigned SR-IOV VFs, you need
to unassign and reassign the SR-IOV VFs to the NetScaler VPX instance.
To unassign SR-IOV network interface assigned to a NetScaler VPX instance, follow these steps:
1. On the XenServer host, use the following command to assign the SR-IOV VFs to the NetScaler VPX
instance and reboot the NetScaler VPX instance:
xe host-call-plugin plugin=iovirt host-uuid=<Xen_host_UUID> fn=unassign_all args:uuid=<Netscalar_VM_UUID>
Where:
• <Xen_host_UUID> - The UUID of the XenServer host.
• <Netscalar_VM_UUID> - The UUID of the NetScaler VPX instance
2. Boot the NetScaler VPX instance.

Configuring VLAN on the SR-IOV Interface

Important

While you are assigning the SR-IOV VFs to the NetScaler VPX instance, make sure that you specify
MAC address 00:00:00:00:00:00 for the VFs.
To use the SR-IOV virtual functions in link aggregation mode, you need to disable spoof checking for
virtual functions that you have created. On the XenServer host, use the following command to disable
spoof checking:
ip link set <interface_name> vf <VF_id> spoofchk off
Where:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 602

NetScaler 12.0

• <interface_name> is the interface name.

• <VF_id> is the virtual function ID.

After disabling spoof checking for all the Virtual Function that you have created, restart the NetScaler
VPX instance and configure link aggregation. For instructions, see Configure link aggregation.

Configure VLAN on the SR-IOV interface

You can configure VLAN on the SR-IOV Virtual Functions, for instructions, see Configuring a VLAN.

Important

Make sure that the XenServer host does not contain VLAN settings for the VF interface.

1.
2. Citrix ADC
3. NetScaler 12.0

Install a NetScaler VPX instance on VMware ESX

March 11, 2019

Contributed by:
C

Before installing
NetScaler VPX instances on VMware ESX, make sure that VMware ESX Server is installed on a machine
with adequate system resources. To install a NetScaler VPX instance on VMware ESXi
, you use VMware vSphere client. The client or tool must be installed on a remote machine that can
connect to VMware ESX through the network.

Important

You cannot install standard VMware Tools or upgrade the VMware Tools version available on a
NetScaler VPX instance. VMware Tools for a NetScaler VPX instance are delivered as part of the
NetScaler software release.

Prerequisites

Before you begin installing a virtual appliance, do the following:

• Install VMware ESX on hardware that meets the minimum requirements.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 603

NetScaler 12.0

• Install VMware Client on a management workstation that meets the minimum system require-
ments.
• Download the NetScaler VPX appliance setup files.
• Label the physical network ports of VMware ESX.
• Obtain VPX license files. For more information about NetScaler VPX instance licenses, see
the NetScaler VPX Licensing Guide at http://support.citrix.com/article/ctx131110.

VMware ESX hardware requirements

The following table describes the minimum system requirements for VMware ESX servers running
NetScaler VPX ncore virtual appliance.

Table 1. Minimum system requirements for a VMware ESX server running a NetScaler VPX instance

Component Requirement

- 2 or more 64-bit x86 CPUs with virtualization

assist (Intel-VT) enabled. Note that to run
NetScaler VPX instance, hardware support for
virtualization must be enabled on the VMware
ESX host. Make sure that the BIOS option for
virtualization support is not disabled. For more
information, see your BIOS documentation.
RAM 3 GB
Disk space 40 GB of disk space available
Network One 1-Gbps NIC; Two 1-Gbps NICs
recommended (The network interfaces must
be Intel E1000.)

For information about installing VMware ESX, see http://www.vmware.com/.

The following table lists the virtual computing resources that the VMware ESX server must provide for
each VPX ncore virtual appliance.

Table 2. Minimum virtual computing resources required for running a NetScaler VPX instance

Component Requirement

Memory 2 GB
Virtual CPU (VCPU) 2

© 1999-2018 Citrix Systems, Inc. All rights reserved. 604

NetScaler 12.0

Component Requirement

Virtual network interfaces 1. Note that with ESX, you can install a
maximum of 10 virtual network interfaces if the
VPX hardware is upgraded version to 7 or
higher.
Disk space 20 GB

Note that this is in addition to any disk requirements for the hypervisor.

For production use of VPX virtual appliance, the full memory allocation must be reserved. CPU cycles
(in MHz) equal to at least the speed of one CPU core of the ESX should also be reserved.

VMware vSphere client system requirements

VMware vSphere is a client application that can run on Windows and Linux operating systems. It can-
not run on the same machine as the VMware ESX server. The following table describes the minimum
system requirements.

Table 3. Minimum system requirements for VMware vSphere client installation

Component Requirement

Operating system For detailed requirements from VMware,

search for the “vSphere Compatibility
Matrixes” PDF file at http://kb.vmware.com/.
CPU 750 megahertz (MHz); 1 gigahertz (GHz) or
faster recommended
RAM 1 GB; 2 GB recommended
Network Interface Card (NIC) 100 Mbps or faster NIC

OVF Tool 1.0 system requirements

OVF Tool is a client application that can run on Windows and Linux systems. It cannot run on the same
machine as the VMware ESX server. The following table describes the minimum system requirements.

Table 4. Minimum system requirements for OVF tool installation

© 1999-2018 Citrix Systems, Inc. All rights reserved. 605

NetScaler 12.0

Component Requirement

Operating system For detailed requirements from VMware,

search for the “OVF Tool User Guide” PDF file
at http://kb.vmware.com/.
CPU 750 MHz minimum, 1 GHz or faster
recommended
RAM 1 GB Minimum, 2 GB recommended
Network Interface Card (NIC) 100 Mbps or faster NIC

For information about installing OVF, search for the “OVF Tool User Guide” PDF file at http:
//kb.vmware.com/.

Downloading the NetScaler VPX setup files

The NetScaler VPX instance setup package for VMware ESX follows the Open Virtual Machine (OVF)
format standard. You can download the files from MyCitrix.com. You need a My Citrix account to log
on. If you do not have a My Citrix account, access the home page at http://www.mycitrix.com, click
the New Users link, and follow the instructions to create a new My Citrix account.

Once logged on, navigate the following path from the My Citrix home page:

MyCitrix.com > Downloads > NetScaler > Virtual Appliances.

Copy the following files to a workstation on the same network as the ESX server. Copy all three files
into the same folder.

• NSVPX-ESX-<release number>-<build number>-disk1.vmdk (for example, NSVPX-ESX-9.3-39.8-

disk1.vmdk)
• NSVPX-ESX-<release number>-<build number>.ovf (for example, NSVPX-ESX-9.3-39.8.ovf)
• NSVPX-ESX-<release number>-<build number>.mf (for example, NSVPX-ESX-9.3-39.8.mf )

Label the physical network ports of VMware ESX

Before installing a VPX virtual appliance, label of all the interfaces that you plan to assign to virtual ap-
pliances, in a unique format, for example, NS_NIC_1_1, NS_NIC_1_2, and so on. In large deployments,
labeling in a unique format helps in quickly identifying the interfaces that are allocated to the VPX
virtual appliance among other interfaces used by other virtual machines, such as Windows and Linux.
Such labeling is especially important when different types of virtual machines share the same inter-
faces.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 606

NetScaler 12.0

To label the physical network ports of VMware ESX server, follow these steps:

1. Log on to the VMware ESX server by using the vSphere client.

2. On the vSphere client, select the Configuration tab, and then click Networking.
3. At the top-right corner, click Add Networking.
4. In the Add Network Wizard, for Connection Type, select Virtual Machine, and then click Next.
5. Scroll through the list of vSwitch physical adapters, and choose the physical port that will map
to interface 1/1 on the virtual appliances.
6. Enter the label of the interface, for example, NS_NIC_1_1 as the name of the vSwitch that will
be associated with interface 1/1 of the virtual appliances.
7. Click Next to finish the vSwitch creation. Repeat the procedure, beginning with step 2, to add
any additional interfaces to be used by your virtual appliances. Label the interfaces sequen-
tially, in the correct format (for example, NS_NIC_1_2).

Install a NetScaler VPX instance on VMware ESX

After you have installed and configured VMware ESX, you can use the VMware vSphere client to install
virtual appliances on the VMware ESX server. The number of virtual appliances that you can install
depends on the amount of memory available on the hardware that is running VMware ESX.

To install NetScaler VPX instances on VMware ESX by using VMware vSphere Client, follow these steps:

1. Start the VMware vSphere client on your workstation.

2. In the IP address / Name text box, type the IP address of the VMware ESX server that you want
to connect to.
3. In the User Name and Password text boxes, type the administrator credentials, and then click
Login.
4. On the File menu, click Deploy OVF Template.
5. In the Deploy OVF Template dialog box, in Deploy from file, browse to the location at which
you saved the NetScaler VPX instance setup files, select the .ovf file, and click Next.
6. Map the networks shown in the virtual appliance OVF template to the networks that you con-
figured on the ESX host. Click Nextto start installing a virtual appliance on VMware ESX. When
installation is complete, a pop-up window informs you of the successful installation.
7. You are now ready to start the NetScaler VPX instance. In the navigation pane, select the
NetScaler VPX instance that you have just installed and, from the right-click menu, select Power
On. Click the Consoletab to emulate a console port.
8. If you want to install another virtual appliance, repeat steps 4 through 6.

Note

By default, the NetScaler VPX instance uses E1000 network interfaces.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 607

NetScaler 12.0

After the installation, you can use vSphere client or vSphere Web Client to manage virtual appliances
on VMware ESX.
For the VLAN tagging feature to work,on the VMware ESX, set the port group’s VLAN ID to 1 -
4095 on the VSwitch of VMware ESX server. For more information about setting a VLAN ID on
the VSwitch of VMware ESX server, see http://www.vmware.com/pdf/esx3_vlan_wp.pdf.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure a NetScaler VPX instance to use VMXNET3 network interface

January 6, 2019

Contributed by:
C

After you have installed and configured the NetScaler VPX instance on the VMware ESX, you can use
the VMware vSphere web client to configure the virtual appliance to use VMXNET3 network interfaces.

To configure NetScaler VPX instances to use VMXNET3 network interfaces by using the VMware vSphere
Web Client:

1. In the vSphere Web Client, select Hosts and Clusters.

2. Upgrade the Compatibility setting of the NetScaler VPX instance to ESX, as follows:

a. Power off the NetScaler VPX instance.

b. Right-click the NetScaler VPX instance and select Compatibility > Upgrade VM Compatibility.

c. In the Configure VM Compatibility dialog box, select ESXi 5.5 and later from the Compatible
with drop-down list and click OK.

3. Right-click on the NetScaler VPX instance and click Edit Settings.

4. In the <virtual_appliance> - Edit Settings dialog box, click the CPU section.

5. In the CPU section, update the following:

- Number of CPUs

- Number of Sockets

- Reservations

- Limit

© 1999-2018 Citrix Systems, Inc. All rights reserved. 608

NetScaler 12.0

- Shares

Set the values as follows:

a. In the CPU drop-down list, select the number of CPUs to assign to the virtual appliance.

b. In the Cores per Socket drop-down list, select the number of sockets.

c. (Optional) In the CPU Hot Plug field, select or unselect the Enable CPU Hot Add checkbox.

Note: Citrix recommends accepting the default (disabled).

d. In the Reservation drop-down list, select the number that is shown as the maximum value.

e. In the Limit drop-down list, select the number that is shown as the maximum value.

f. In the Shares drop-down lists, select Custom and the number that is shown as the maximum value.

6. In the Memory section, update the following:

- Size of RAM

- Reservations

- Limit

- Shares

Set the values as follows:

a. In the RAM drop-down list, select the size of the RAM. It should be number of vCPUs x 2 GB. For
example, if the number of vCPUs is 4, the RAM should be 4 x 2 GB = 8 GB.

Note: For an Enterprise or Platinum edition of the NetScaler VPX appliance, make sure that you al-
locate 4 GB of RAM to each vCPU. For example, if the number of vCPU is 4 then RAM = 4 x 4 GB = 16
GB.

b. In the Reservation drop-down list, enter the value for the memory reservation, and select the Re-
serve all guest memory (All locked) checkbox. The memory reservation should be the number of vC-
PUs x 2 GB. For example, if the number of vCPUs is 4, the memory reservation should be 4 x 2 GB = 8
GB.

Note: For an Enterprise or Platinum edition of the NetScaler VPX appliance, make sure that you al-
locate 4 GB of RAM to each vCPU. For example, if the number of vCPU is 4 then RAM = 4 x 4 GB = 16
GB.

c. In the Limit drop-down list, select the number that is shown as the maximum value.

d. In the Shares drop-down lists, select Custom and the number that is shown as the maximum value.

7. Add a VMXNET3 network interface. From the New device drop-down list, select Network and
click Add.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 609

NetScaler 12.0

8. In the New Network section, from the drop-down list, select the network interface, and do the
following:

a. In the Adapter Type drop-down list, select VMXNET3.

Important

The default E1000 network interface and VMXNET3 cannot coexist, make sure that you remove
the E1000 network interface and use VMXNET3 (0/1) as the management interface.

9. Click OK.

10. Power on the NetScaler VPX instance.

11. Once the NetScaler VPX instance powers on, you can use the following command to verify the
configuration:

1 > show interface summary

The output should show all the interfaces that you configured:

1 > show interface summary

2 --------------------------------------------------------------------------------

3       Interface  MTU        MAC                  Suffix

4 --------------------------------------------------------------------------------

5 1     0/1        1500       00:0c:29:89:1d:0e    NetScaler Vir...rface,

VMXNET3
6 2     1/1        9000       00:0c:29:89:1d:18    NetScaler Vir...rface,
VMXNET3
7 3     1/2        9000       00:0c:29:89:1d:22    NetScaler Vir...rface,
VMXNET3
8 4     LO/1       9000       00:0c:29:89:1d:0e    Netscaler Loopback
interface

Note

After you add a VMXNET3 interface and restart the NetScaler VPX appliance, the VMWare ESX hy-
pervisor might change the order in which the NIC is presented to the VPX appliance. So, network
adapter 1 might not always remain 0/1, resulting in loss of management connectivity to the VPX
appliance. To avoid this issue, change the virtual network of the network adapter accordingly.

This is a VMWare ESX hypervisor limitation.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 610

NetScaler 12.0

Configure a NetScaler VPX instance to use SR-IOV network interface

January 6, 2019

Contributed by:
C

After you have installed and configured the NetScaler VPX instance on VMware ESX, you can use the
VMware vSphere web client to configure the virtual appliance to use single root I/O v irtualization (SR-
IOV) network interfaces.

Limitations

A NetScaler VPX configured with SR-IOV network interface has the following limitations:

• The following features are not supported on SR-IOV interfaces using Intel 82599 10G NIC on ESX
VPX:
– L2 mode switching
– Static Link Aggregation and LACP
– Clustering
– Admin partitioning [Shared VLAN mode]
– High Availability [Active - Active mode]
– Jumbo frames
– IPv6
• The following features are not supported for on SR-IOV interface with an Intel 82599 10G NIC on
KVM VPX:
– Static Link Aggregation and LACP
– L2 mode switching
– Clustering
– Admin partitioning [Shared VLAN mode]
– High Availability [Active – Active mode]
– Jumbo frames
– IPv6
– VLAN configuration on Hypervisor for SR-IOV VF interface through “ip link” command is not
supported

Prerequisite

Make sure that you:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 611

NetScaler 12.0

- Add the Intel 82599 Network Interface Card (NIC) to the ESX Host. IXGBE driver version 3.7.13.7.14iov is
recommended.

- Enable SR-IOV on the host physical adapter, as follows:

1. In the vSphere Web Client, navigate to the Host.

2. On the Manage > Networking tab, select Physical adapters. The SR-IOV Status field shows
whether a physical adapter supports SR-IOV.

3. Select the physical adapter, and then click the pencil icon to open the Edit Settings dialog box.

4. Under SR-IOV, select Enabled from the Status drop-down list.

5. In the Number of virtual functions field, enter the number of virtual functions that you want to
configure for the adapter.

6. Click OK.
7. Restart the host.

- Create a Distributed Virtual Switch (DVS) and Portgroups. For instructions, see the VMware Documen-
tation.
Note

Citrix has qualified the SR-IOV configuration on DVS and Portgroups only.

To configure NetScaler VPX instances to use SR-IOV network interface by using VMware vSphere
Web Client:

1. In the vSphere Web Client, select Hosts and Clusters.

2. Upgrade the Compatibility setting of the NetScaler VPX instance to ESX 5.5 or later, as follows:

a. Power off the NetScaler VPX instance.

b. Right-click the NetScaler VPX instance and select Compatibility > Upgrade VM Compatibility.

c. In the Configure VM Compatibility dialog box, select ESXi 5.5 and later from the Compatible
with drop-down list and click OK.

3. Right-click on the NetScaler VPX instance and click Edit Settings.

4. In the <virtual_appliance> - Edit Settings dialog box, click the CPU section.

5. In the CPU section, update the following settings:

- Number of CPUs

- Number of Sockets

- Reservations

- Limit

© 1999-2018 Citrix Systems, Inc. All rights reserved. 612

NetScaler 12.0

- Shares

Set the values as follows:

a. In the CPU drop-down list, select the number of CPUs to assign to the virtual appliance.

b. In the Cores per Socket drop-down list, select the number of sockets.

c. (Optional) In the CPU Hot Plug field, select or clear the Enable CPU Hot Add check box.

Note: Citrix recommends accepting the default (disabled).

d. In the Reservation drop-down list, select the number that is shown as the maximum value.

e. In the Limit drop-down list, select the number that is shown as the maximum value.

f. In the Shares drop-down lists, select Custom and the number that is shown as the maximum
value.

6. In the Memory section, update the following settings:

- Size of RAM

- Reservations

- Limit

- Shares

Set the values as follows:

a. In the RAM drop-down list, select the size of the RAM. It should be number of vCPUs x 2 GB. For
example, if the number of vCPU is 4 then RAM = 4 x 2 GB = 8 GB.

Note: For Enterprise or Platinum edition of the NetScaler VPX appliance, make sure that you allocate 4
GB of RAM to each vCPU. For example, if the number of vCPU is 4 then RAM = 4 x 4 GB = 16 GB.

b. In the Reservation drop-down list, enter the value for the memory reservation, and select
the Reserve all guest memory (All locked) check box. The memory reservation should be number
of vCPUs x 2 GB. For example, if the number of vCPUs is 4, the memory reservation should be 4 x 2 GB
= 8 GB.

Note: For Enterprise or Platinum edition of the NetScaler VPX appliance, make sure that you allocate 4
GB of RAM to each vCPU. For example, if the number of vCPU is 4 then RAM = 4 x 4 GB = 16 GB.

c. In the Limit drop-down list, select the number that is shown as the maximum value.

d. In the Shares drop-down lists, select Custom, and select the number that is shown as the
maximum value.

7. Add an SR-IOV network interface. From the New device drop-down list, select Network and click
Add.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 613

NetScaler 12.0

8. In the New Network section. From the drop-down list, select the Portgroup that you created,
and do the following:
a. In the Adapter Type drop-down list, select SR-IOV passthrough.

b. In the Physical function drop-down list, select the physical adapter mapped with the Port-
group.

c. In the Guest OS MTU Change drop-down list, select Disallow.

9. In the <virtual_appliance> - Edit Settings dialog box, click the VM Options tab.

10. On the VM Options tab, select the Advanced section. From the Latency Sensitivity drop-down
list, select High.

11. Click OK.

12. Power on the NetScaler VPX instance.

13. Once the NetScaler VPX instance powers on, you can use the following command to verify the con-
figuration:

1 > show interface summary

The output should show all the interfaces that you configured:

1 > show interface summary

2 --------------------------------------------------------------------------------

3       Interface  MTU        MAC                  Suffix

4 --------------------------------------------------------------------------------

5 1     0/1        1500       00:0c:29:1b:81:0b    NetScaler Virtual

Interface
6 2     10/1       1500       00:50:56:9f:0c:6f    Intel 82599 10G VF
Interface
7 3     10/2       1500       00:50:56:9f:5c:1e    Intel 82599 10G VF
Interface
8 4     10/3       1500       00:50:56:9f:02:1b    Intel 82599 10G VF
Interface
9 5     10/4       1500       00:50:56:9f:5a:1d    Intel 82599 10G VF
Interface
10 6     10/5       1500       00:50:56:9f:4e:0b    Intel 82599 10G VF
Interface
11 7     LO/1       1500       00:0c:29:1b:81:0b    Netscaler Loopback
interface
12  Done
13 > show inter 10/1
14 1)      Interface 10/1 (Intel 82599 10G VF Interface) #1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 614

NetScaler 12.0

15         flags=0xe460 <ENABLED, UP, UP, HAMON, 802.1q>

16         MTU=1500, native vlan=55, MAC=00:50:56:9f:0c:6f, uptime 0
h21m53s
17         Actual: media FIBER, speed 10000, duplex FULL, fctl NONE,
throughput 10000
18         LLDP Mode: NONE,                 LR Priority: 1024
19
20         RX: Pkts(838020742) Bytes(860888485431) Errs(0) Drops(2527)
Stalls(0)
21         TX: Pkts(838149954) Bytes(860895860507) Errs(0) Drops(0) Stalls
(0)
22         NIC: InDisc(0) OutDisc(0) Fctls(0) Stalls(0) Hangs(0) Muted(0)
23         Bandwidth thresholds are not set.
24  Done

1.
2. Citrix ADC
3. NetScaler 12.0

Migrating the NetScaler VPX from E1000 to SR-IOV or VMXNET3 Network

Interfaces

November 2, 2018

Contributed by:
C

You can configure your exiting NetScaler VPX instances that use E1000 network interfaces to use SR-
IOV or VMXNET3 network interfaces.

To configure an existing NetScaler VPX instance to use SR-IOV network interfaces, see Configuring
NetScaler VPX instances to use Single Root I/O Virtualization (SR-IOV) Network Interface.

To configure an existing NetScaler VPX instance to use VMXNET3 network interfaces, see Configuring
NetScaler VPX instances to use VMXNET3 Network Interface.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 615

NetScaler 12.0

Configure a NetScaler VPX instance to use PCI passthrough network

interface

January 6, 2019

Contributed by:
C

Overview

After you have installed and configured a NetScaler VPX instance on VMware ESX Server, you can use
the vSphere Web Client to configure the virtual appliance to use PCI passthrough network interfaces.

The PCI passthrough feature allows a guest virtual machine to directly access physical PCI and PCIe
devices connected to a host.

Prerequisites

• The firmware version of the Intel XL710 NIC on the host is 5.04.
• A PCI passthrough device connected to and configured on the host
• Supported NICs:
– Intel X710 10G NIC
– Intel XL710 Dual Port 40G NIC
– Intel XL710 Single Port 40G NIC

Configure passthrough devices on a host

Before configuring a passthrough PCI device on a virtual machine, you should configure it on the host
machne. Follow these steps to configure passthrough devices on a host.

1. Select the host from the Navigator panel of the vSphere Web Client.
2. Click Manage > Settings > PCI Devices. All available passthrough devices are displayed.
3. Right-click the device that you want to configure and click Edit.
4. The Edit PCI Device Availability window appears.
5. Select the devices to be used for passthrough and click OK.

6. Restart the host machine.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 616

NetScaler 12.0

Configure passthrough devices on a NetScaler VPX instance

Follow these steps to configure a passthrough PCI device on a NetScaler VPX instance.

1. Power off the virtual machine.

2. Right-click the virtual machine and select Edit Settings.
3. On the Virtual Hardware tab, select PCI Device from the New Device drop-down menu, and
click Add.

4. Expand New PCI device and select the passthrough device to connect to the virtual machine
from the drop-down list and click OK.

Note

VMXNET3 network interface and PCI Passthrough Network Interface cannot coexist.

6. Power on the guest virtual machine.

You have completed the steps to configuring NetScaler VPX to use PCI passthrough network interfaces.

1.
2. Citrix ADC
3. NetScaler 12.0

Install a NetScaler VPX instance on Microsoft Hyper-V server

March 6, 2019

Contributed by:
C

To install Citrix
NetScaler VPX instances on Microsoft Windows Server, you must first install Windows Server, with the
Hyper-V role enabled, on a machine with adequate system resources. While installing the Hyper-V
role, be sure to specify the network interface cards (NICs) on the server that Hyper-V will use to create
the virtual networks. You can reserve some NICs for the host. Use Hyper-V Manager to perform the
NetScaler VPX instance installation.

NetScaler VPX instance for Hyper-V is delivered in virtual hard disk (VHD) format. It includes the de-
fault configuration for elements such as CPU, network interfaces, and hard-disk size and format. After
you install NetScaler VPX instance, you can configure the network adapters on virtual appliance, add
virtual NICs, and then assign the NetScaler IP address, subnet mask, and gateway, and complete the
basic configuration of the virtual appliance.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 617

NetScaler 12.0

After the initial configuration of the VPX instance, if you want to upgrade the appliance to the latest
software release, see Upgrade a NetScaler VPX standalone appliance

Note

Intermediate System-to-Intermediate System (ISIS) protocol is not supported on the NetScaler

VPX virtual appliance hosted on the HyperV-2012 platform.

Prerequisites for installing NetScaler VPX instance on Microsoft servers

Before you begin installing a virtual appliance, do the following:

• Enable the Hyper-V role on Windows Servers . For more information, see http://technet.
microsoft.com/en-us/library/ee344837(WS.10).aspx.
• Download the virtual appliance setup files.
• Obtain NetScaler VPX instance license files. For more information about NetScaler VPX instance
licenses, see the NetScaler VPX Licensing Guide at http://support.citrix.com/article/ctx131110.

Microsoft server hardware requirements

The following table describes the minimum system requirements for Microsoft Servers.

Table 1. Minimum system requirements for Microsoft servers

Component Requirement

CPU 1.4 GHz 64-bit processor

RAM 3 GB
Disk Space 32 GB or greater

The following table lists the virtual computing resources for each
NetScaler VPX instance.

Table 2. Minimum virtual computing resources required for running a NetScaler VPX instance

Component Requirement

RAM 2 GB
Virtual CPU 2
Disk Space 20 GB

© 1999-2018 Citrix Systems, Inc. All rights reserved. 618

NetScaler 12.0

Component Requirement

Virtual Network Interfaces 1

Download the NetScaler VPX setup files

NetScaler VPX instance for Hyper-V is delivered in virtual hard disk (VHD) format. You can download
the files from MyCitrix.com. You will need a My Citrix account to log on. If you do not have a My Citrix
account, access the home page at http://www.mycitrix.com, click the New Users link, and follow the
instructions to create a new My Citrix account.

To download the NetScaler VPX instance setup files, follow these steps:

1. In a Web browser, go to http://www.citrix.com/ and click My Citrix.

2. Type your user name and password.

3. Click Downloads.

4. In Search Downloads by Product, select NetScaler.

5. Under Virtual Appliances, click NetScaler VPX.

6. Copy the compressed file to your server.

Install the NetScaler VPX instance on Microsoft servers

After you have enabled the Hyper-V role on Microsoft Server and extracted the virtual appliance files,
you can use Hyper-V Manager to install NetScaler VPX instance. After you import the virtual machine,
you need to configure the virtual NICs by associating them to the virtual networks created by Hyper-V.

You can configure a maximum of eight virtual NICs. Even if the physical NIC is DOWN, the virtual ap-
pliance assumes that the virtual NIC is UP, because it can still communicate with the other virtual
appliances on the same host (server).

Note

You cannot change any settings while the virtual appliance is running. Shut down the virtual
appliance and then make changes.

To install NetScaler VPX instance on Microsoft Server by using Hyper-V Manager:

1. To start Hyper-V Manager, click Start, point to Administrative Tools, and then click Hyper-V
Manager.
2. In the navigation pane, under Hyper-V Manager, select the server on which you want to install
NetScaler VPX instance.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 619

NetScaler 12.0

3. On the Action menu, click Import Virtual Machine.

4. In the Import Virtual Machine dialog box, in Location, specify the path of the folder that con-
tains the NetScaler VPX instance software files, and then select Copy the virtual machine (cre-
ate a new unique ID). This folder is the parent folder that contains the Snapshots, Virtual Hard
Disks, and Virtual Machines folders.
5. Note: If you received a compressed file, make sure that you extract the files into a folder before
you specify the path to the folder.
6. Click Import.
7. Verify that the virtual appliance that you imported is listed under Virtual Machines.
8. To install another virtual appliance, repeat steps 2 through 6.

Important

Make sure that you extract the files to a different folder in step 4.

Auto-provision a NetScaler VPX instance on Hyper-V

Auto-provisioning of NetScaler VPX instance is optional. If auto-provisioning is not done, the virtual
appliance provides an option to configure the IP address and so on.

To auto-provision NetScaler VPX instance on Hyper-V, follow these steps.

1. Create an ISO9660 compliant ISO image using the xml file as depicted in the example. Make sure
that the name of the xml file is userdata.

<?xml version=”1.0” encoding=”UTF-8” standalone=”no”?>

<Environment xmlns:oe=”http://schemas.dmtf.org/ovf/environment/1”

xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”

oe:id=””

xmlns=”http://schemas.dmtf.org/ovf/environment/1”>

<PlatformSection>

<Kind>HYPER-V</Kind>

<Version>2013.1</Version>

<Vendor>CISCO</Vendor>

<Locale>en</Locale>

</PlatformSection>

<PropertySection>

<Property oe:key=”com.citrix.netscaler.ovf.version” oe:value=”1.0”/>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 620

NetScaler 12.0

<Property oe:key=”com.citrix.netscaler.platform” oe:value=”NS1000V”/>

<Property oe:key=”com.citrix.netscaler.orch_env” oe:value=”cisco-orch-env”/>

<Property oe:key=”com.citrix.netscaler.mgmt.ip” oe:value=”10.102.100.122”/>

<Property oe:key=”com.citrix.netscaler.mgmt.netmask” oe:value=”255.255.255.128”/>

<Property oe:key=”com.citrix.netscaler.mgmt.gateway” oe:value=”10.102.100.67”/></PropertySection>

</Environment>

2. Copy the ISO image to hyper-v server.

3. Select the virtual appliance that you imported, and then on the Action menu, select Settings. You
can also select the virtual appliance and then right click and select Settings. The Settings window
for the selected virtual appliance is displayed.

4. In the Settings window, under the hardware section, click on IDE Controller.

5. In the right window pane, select DVD Drive and click on Add. The DVD Drive is added under the IDE
Controller section in the left window pane.

6. Select the DVD Drive added in step 5. In the right window pane, select the Image file radio button
and click on Browse and select the ISO image that you copied on Hyper-V server,
in step 2.

7. Click Apply.
Note

The virtual appliance instance comes up in the default IP address, when:

• The DVD drive is attached and the ISO file is not provided.
• The ISO file does not inculde the userdata file.
• The userdata file name or format is not correct.

To configure virtual NICs on the NetScaler VPX instance, follow these steps:

1. Select the virtual appliance that you imported, and then on the Action menu, select Settings.
2. In the Settings for <virtual appliance name> dialog box, click Add Hardware in the left pane.
3. In the right pane, from the list of devices, select Network Adapter.
4. Click Add.
5. Verify that Network Adapter (not connected) appears in the left pane.
6. Select the network adapter in the left pane.
7. In the right pane, from the Network drop-down list, select the virtual network to connect the
adapter to.
8. To select the virtual network for additional network adapters that you want to use, repeat
steps 6 and 7.
9. Click Apply, and then click OK.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 621

NetScaler 12.0

To configure the NetScaler VPX instance:

1. Right-click the virtual appliance that you previously installed, and then select Start.
2. Access the console by double-clicking the virtual appliance.
3. Type the NetScaler IP address, subnet mask, and gateway for your virtual appliance.

You have completed the basic configuration of your virtual appliance. Type the IP address in a Web
browser to access the virtual appliance.
Note

You can also use virtual machine (VM) template to provision NetScaler VPX instance using SCVMM.

If you use Microsoft Hyper-V NIC teaming solution with NetScaler VPX instances, see article
CTX224494 for more information.

1.
2. Citrix ADC
3. NetScaler 12.0

Install a NetScaler VPX instance on Linux-KVM platform

September 20, 2018

Contributed by:
C

To set up a NetScaler VPX for the Linux-KVM platform, you can use the graphical Virtual Machine Man-
ager (Virt-Manager) application. If you prefer the Linux-KVM command line, you can use the virsh pro-
gram.

The host Linux operating system must be installed on suitable hardware by using virtualization tools
such as KVM Module and QEMU. The number of virtual machines (VMs) that can be deployed on the
hypervisor depends on the application requirement and the chosen hardware.

After you provision a NetScaler VPX instance, you can add additional interfaces.

Limitations and usage guidelines

General recommendations

To avoid unpredictable behavior, apply the following recommendations:

• Do not change the MTU of the vnet interface associated with the VPX VM. Shut down the VPX VM
before modifying any configuration parameters, such as Interface modes or CPU.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 622

NetScaler 12.0

• Do not force a shutdown of the VPX VM. That is, do not use the Force off command.
• Any configurations done on the host Linux might or might not be persistent, depending on your
Linux distribution settings. You can choose to make these configurations persistent to ensure
consistent behavior across reboots of host Linux operating system.
• The NetScaler package has to be unique for each of the NetScaler VPX instance provisioned.

Limitations

• Live migration of a VPX instance that runs on KVM is not supported.

1.
2. Citrix ADC
3. NetScaler 12.0

Prerequisites for installing a NetScaler VPX instance on Linux-KVM

platform

December 5, 2018

Contributed by:
C

Check the minimum system requirements for a Linux-KVM serves running a NetScaler VPX instance.

CPU requirement:

• 64-bit x86 processors with the hardware virtualization features included in the AMD-V and Intel
VT-X processors.

To test whether your CPU supports Linux host, enter the following command at the host Linux shell
prompt:

1 *.egrep’^flags.*(vmx|svm)’/proc/cpuinfo*

If the BIOS settings for the above extension are disabled, you must enable them in BIOS.

• Provide at least 2 CPU cores to Host Linux.

• There is no specific recommendation for processor speed, but higher the speed, the better the
performance of the VM application.

Memory (RAM) requirement:

Minimum 4 GB for the host Linux kernel. Add additional memory as required by the VMs.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 623

NetScaler 12.0

Hard disk requirement:

Calculate the space for Host Linux kernel and VM requirements. A single NetScaler VPX VM requires 20
GB of disk space.

Software requirements

The Host kernel used must be a 64-bit Linux kernel, release 2.6.20 or later, with all virtualization tools.
Citrix recommends newer kernels, such as 3.6.11-4 and later.

Many Linux distributions such as Red Hat, Centos, and Fedora, have tested kernel versions and asso-
ciated virtualization tools.

Guest VM hardware requirements

NetScaler VPX supports IDE and virtIO hard disk type. The Hard Disk Type has been configured in the
XML file, which is a part of the NetScaler package.

Networking requirements

NetScaler VPX supports virtIO para-virtualized, SR-IOV, and PCI Passthrough network interfaces.

For more information about the supported network interfaces, see:

• Provision the NetScaler VPX instance by using the Virtual Machine Manager
• Configure a NetScaler VPX instance to use SR-IOV network interfaces
• Configure a NetScaler VPX instance to use PCI passthrough network interfaces

Source Interface and Modes

The source device type can be either Bridge or MacVTap. In case of MacVTap, four modes are possible
- VEPA, Bridge, Private and Pass-through.
Check the types of interfaces that you can use and the supported traffic types, as given below.

Bridge:

• Linux Bridge.
• Ebtables and iptables settings on host Linux might filter the traffic on the bridge if you do not
choose the correct setting or disable IPtable services.

MacVTap (VEPA mode):

• Better performance than a bridge.

• Interfaces from the same lower device can be shared across the VMs.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 624

NetScaler 12.0

• Inter-VM communication using the same

• lower device is possible only if upstream or downstream switch supports VEPA mode.

MacVTap (private mode):

• Better performance than a bridge.

• Interfaces from the same lower device can be shared across the VMs.
• Inter-VM communication using the same lower device is not possible.

MacVTap (bridge mode):

• Better as compared to bridge.

• Interfaces out of same lower device can be shared across the VMs.
• Inter-VM communication using the same lower device is possible, if lower device link is UP.

MacVTap (Pass-through mode):

• Better as compared to bridge.

• Interfaces out of same lower device cannot be shared across the VMs.
• Only one VM can use the lower device.

Note: For best performance by the VPX instance, ensure that the gro and lro capabilities are
switched off on the source interfaces.

Properties of source interfaces

Make sure that you switch off the generic-receive-offload (gro) and large-receive-offload (lro) capabil-
ities of the source interfaces. To switch off the gro and lro capabilities, run the following commands
at the host Linux shell prompt.

ethtool -K eth6 gro off

ethool -K eth6 lro off

Example:

1 [root@localhost ~]# ethtool -K eth6

2
3                  Offload parameters for eth6:
4
5                                    rx-checksumming: on
6
7                                    tx-checksumming: on
8
9                  scatter-gather: on
10
11                  tcp-segmentation-offload: on

© 1999-2018 Citrix Systems, Inc. All rights reserved. 625

NetScaler 12.0

12
13                  udp-fragmentation-offload: off
14
15                  generic-segmentation-offload: on
16
17                  generic-receive-offload: off
18
19                  large-receive-offload: off
20
21                  rx-vlan-offload: on
22
23                  tx-vlan-offload: on
24
25                  ntuple-filters: off
26
27                  receive-hashing: on
28
29 [root@localhost ~]#

Example:

If the host Linux bridge is used as a source device, as in the following example, gro and lro capabilities
must be switched off on the vnet interfaces, which are the virtual interfaces connecting the host to the
guest VMs.

1 [root@localhost ~]# brctl show eth6_br

2
3 bridge name     bridge  id               STP enabled interfaces
4
5 eth6_br         8000.00e0ed1861ae          no         eth6
6
7                                                       vnet0
8
9                                                       vnet2
10
11 [root@localhost ~]#

In the above example, the two virtual interfaces are derived from the eth6_br and are represented
as vnet0 and vnet2. Run the following commands to switch off gro and lro capabilities on these inter-
faces.

1 ethtool -K vnet0 gro off

2         ethtool -K vnet2 gro off
3         ethtool -K vnet0 lro off
4                  ethtool -K vnet2 lro off

© 1999-2018 Citrix Systems, Inc. All rights reserved. 626

NetScaler 12.0

Promiscuous mode

The promiscuos mode has to be enabled for the following features to work:

• L2 mode
• Multicast traffic processing
• Broadcast
• IPV6 traffic
• VMAC
• Dynamic routing

Use the following command to enable the promicuous mode.

1 [root@localhost ~]# ifconfig eth6 promisc

2 [root@localhost ~]# ifconfig eth6
3 eth6       Link encap:Ethernet  HWaddr 78:2b:cb:51:54:a3
4           inet6 addr: fe80::7a2b:cbff:fe51:54a3/64 Scope:Link
5           UP BROADCAST RUNNING PROMISC MULTICAST  MTU:9000  Metric:1
6           RX packets:142961 errors:0 dropped:0 overruns:0 frame:0
7           TX packets:2895843 errors:0 dropped:0 overruns:0 carrier:0
8           collisions:0 txqueuelen:1000
9           RX bytes:14330008 (14.3 MB)  TX bytes:1019416071 (1.0 GB)
10
11 [root@localhost ~]#

Module required

For better network performance, make sure the vhost_net module is present in the Linux host. To
check the existence of vhost_net module, run the following command on the Linux host :

1 lsmod | grep ”vhost\_net”

If vhost_net is not yet running, enter the following command to run it:

1 modprobe vhost\_net

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 627

NetScaler 12.0

Provision the NetScaler VPX instance by using OpenStack

January 6, 2019

Contributed by:
C

You can provision a NetScaler VPX instance in an Openstack environment either by using the Nova
boot command (OpenStack CLI) or Horizon (OpenStack dashboard) .

Provisioning a VPX instance, optionally involves using data from the config drive. Config drive is a spe-
cial configuration drive that attaches to the instance as a CD-ROM device when it boots. This configu-
ration drive can be used to pass networking configuration such as management IP address, network
mask, default gateway, and to inject customer scripts.

In a NetScaler appliance, the default authentication mechanism is password based. Now, SSH key-
pair authentication mechanism is supported for NetScaler VPX instances on OpenStack environment.

The key-pair (public key and private key) needs to be generated before using Public Key Cryptography
mechanism. You can use different mechanisms, such as Horizon, Puttygen.exe for Windows, and ssh-
keygen for Linux environment, to generate the key pair. Refer to online documentation of respective
mechanisms for more information about generating key pair.

Once a key pair is available, copy the private key to a secure location to which authorized persons
will have access. In OpenStack, public key can be deployed on a VPX instance by using Horizon or
Nova boot command. When a VPX instance is provisioned by using OpenStack, it first detects that
the instance is booting in an OpenStack environment by reading a specific BIOS string. This string is
“OpenStack Foundation” and for Red Hat Linux distributions it is stored in /etc/nova/release. This is
a standard mechanism that is available in all OpenStack implementations based on KVM hypervisor
platform. The drive should have a specific OpenStack label.

If the config drive is detected, the instance attempts to read the network configuration, custom scripts,
and SSH key pair if provided.

Userdata file

The NetScaler VPX instance uses a customized OVF file, also known as userdata file, to inject network
configuration, custom scripts. This file is provided as part of config drive. Here is an example of a
customized OVF file.

1 <?xml version=”1.0” encoding=”UTF-8” standalone=”no”?>

2 <Environment xmlns:oe=”http://schemas.dmtf.org/ovf/environment/1”
3 xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
4 oe:id=””

© 1999-2018 Citrix Systems, Inc. All rights reserved. 628

NetScaler 12.0

5 xmlns=”http://schemas.dmtf.org/ovf/environment/1”
6 xmlns:cs=”http://schemas.citrix.com/openstack”>
7 <PlatformSection>
8 <Kind></Kind>
9 <Version>2016.1</Version>
10 <Vendor>VPX</Vendor>
11 <Locale>en</Locale>
12 </PlatformSection>
13 <PropertySection>
14 <Property oe:key=”com.citrix.netscaler.ovf.version” oe:value=”1.0”/>
15 <Property oe:key=”com.citrix.netscaler.platform” oe:value=”NSVPX”/>
16 <Property oe:key=”com.citrix.netscaler.orch_env” oe:value=”openstack-
orch-env”/>
17 <Property oe:key=”com.citrix.netscaler.mgmt.ip” oe:value=”10.1.2.22”/>
18 <Property oe:key=”com.citrix.netscaler.mgmt.netmask” oe:value=”
255.255.255.0”/>
19 <Property oe:key=”com.citrix.netscaler.mgmt.gateway” oe:value=”10.1.2.1
”/>
20 </PropertySection>
21  <cs:ScriptSection>
22    <cs:Version>1.0</cs:Version>
23      <ScriptSettingSection xmlns=”http://schemas.citrix.com/openstack”
xmlns:i=”http://www.w3.org/2001/XMLSchema-instance”>
24          <Scripts>
25            <Script>
26                  <Type>shell</Type>
27                  <Parameter>X Y</Parameter>
28                 <Parameter>Z</Parameter>
29                 <BootScript>before</BootScript>
30                   <Text>
31                         #!/bin/bash
32                         echo ”Hi, how are you” $1 $2 >> /var/sample.txt
33                   </Text>
34            </Script>
35            <Script>
36                  <Type>python</Type>
37                  <BootScript>after</BootScript>
38                   <Text>
39                        #!/bin/python
40 print(”Hello”);
41                   </Text>
42            </Script>
43   <Script>
44                  <Type>perl</Type>
45                  <BootScript>before</BootScript>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 629

NetScaler 12.0

46                   <Text>
47                        !/usr/bin/perl
48 my $name = ”VPX”;
49 print ”Hello, World $name !\n” ;
50                   </Text>
51            </Script>
52            <Script>
53                 <Type>nscli</Type>
54                 <BootScript>after</BootScript>
55                 <Text>
56                  add vlan 33
57 bind vlan 33 -ifnum 1/2
58                 </Text>
59            </Script>
60          </Scripts>
61      </ScriptSettingSection>
62  </cs:ScriptSection>
63 </Environment>

In the OVF file above “PropertySection” is used for NetScaler networking configuration while
<cs:ScriptSection> is used to enclose all scripts. <Scripts></Scripts> tags are used to bundle all
scripts together. Each script is defined in between <Script> </Script> tags. Each script tag has
following fields/tags:

a) <Type>: Specifies value for script type. Possible values: Shell/Perl/Python/NSLCI (for NetScaler CLI
scripts)

b) <Parameter>: Provides parameters to the script. Each script can have multiple <Parameter> tags.

c) <BootScript>: Specifies script execution point. Possible values for this tag: before/after. “before”
specifies script will be executed before PE comes up. “after” specifies that the script will be executed
after PE comes up.

d) <Text>: Pastes content of a script.

Note

Currently the VPX instance does not take care of sanitization of scripts. As an administrator, you
should check the validity of the script.

Not all sections need to be present. Use an empty “PropertySection” to only define scripts to
execute on first boot or an empty <cs:ScriptSection> to only define networking configuration.

After the required sections of the OVF file (userdata file) are populated, use that file to provision
the VPX instance.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 630

NetScaler 12.0

Network configuration

As part of network configuration, the VPX instance reads:

• Management IP address
• Network mask
• Default gateway

After the parameters are successfully read, they are populated in the NetScaler configuration, to allow
managing the instance remotely. If the parameters are not read successfully or the config drive is not
available, the instance transitions to the default behavior, which is:

• The instance attempts to retrieve the IP address information from DHCP.

• If DHCP fails or times-out, the instance comes up with default network configuration
(192.168.100.1/16).

Customer script

The VPX instance allows to execute a custom script during initial provisioning. The appliance supports
script of type Shell, Perl, Python, and NetScaler CLI commands.

SSH key pair authentication

The VPX instance copies public key, available within the configuration drive as part of instance meta
data, into its “authorized_keys” file. This allows the user to access the instance with private key.

Note

When an SSH key is provided, the default credentials (nsroot/nsroot) no longer work. If password-
based access is needed, log on with the respective SSH private key and manually set a password.

Before you begin

Before you provision a VPX instance on OpenStack environment, extract the .qcow2 file from the .tgz
file and build

an OpenStack image from the qcow2 image. Follow these steps:

1. Extract the. qcow2 file from the .tqz file by typing the following command.

1 tar xvzf <TAR file>

2
3 tar xvzf <NSVPX-KVM-12.0-26.2_nc.tgz>
4 NSVPX-KVM.xml

© 1999-2018 Citrix Systems, Inc. All rights reserved. 631

NetScaler 12.0

5 NSVPX-KVM-12.0-26.2_nc.qcow2

2. Build an OpenStack image using the .qcoz2 file extracted in step 1 by typing the following command.

1 openstack image create --container-format bare --property hw_disk_bus=

ide --disk-format qcow2 --file <path to qcow2 file> --public <name
of the OpenStack image>
2
3 glance image-create --name=”NS-VPX-12-0-26-2” --property hw_disk_bus=
ide --ispublic=
4 true --container-format=bare --disk-format=qcow2< NSVPX-KVM-12.0-26.2
_nc.qcow2

Figure 1: The following illustration provides a sample output for the glance image-create command.

Provisioning the VPX instance

You can provision a VPX instance in two ways by using one of the options:

• Horizon (OpenStack dashboard)

• Nova boot command (OpenStack CLI)

Provision a VPX instance by using the OpenStack dashboard

Follow these steps to provision the VPX instance by using Horizon:

1. Log on to the OpenStack dashboard.

2. In the Project panel on the left hand side of the dashboard, select Instances.
3. In the Instances panel, click Launch Instance to open the Instance Launching wizard.

4. In the Launch Instance wizard, fill in the details, like:

1. Instance Name
2. Instance Flavor
3. Instance Count
4. Instance Boot Source
5. Image Name

5. Deploy a new key pair or an existing key pair through Horizon by completing the following steps:

a) If you don’t have an existing key pair, create the key by using any existing mechanisms. If you’ve an
existing key, skip this step.

b) Copy the content of public key.

c) Go to Horizon > Instances > Create New Instances.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 632

NetScaler 12.0

d) Click Access & Security.

e) Click the + sign next to the Key Pair drop-down menu and provide values for shown parameters.

f) Paste public key content in Public key box, give a name to the key and click Import Key Pair.

6. Click the Post Creation tab in the wizard. In Customization Script, add the content of the userdata
file. The userdata file contains the IP address, Netmask and Gateway details, and customer scripts of
the VPX instance.

7. After a key pair is selected or imported, check config-drive option and click Launch.

Provision the VPX instance by using OpenStack CLI

Follow these steps to provision a VPX instance by using OpenStack CLI.

1. To create an image from qcow2, type the following command:

1 openstack image create --container-format bare --property hw_disk_bus=

ide --diskformat  qcow2 --file NSVPX-OpenStack.qcow2 --public VPX-
ToT-Image

2. To select an image for creating an instance, type the following command:

1 openstack image list | more

3. To create an instance of a particular flavor, type the following command to choose a flavor ID/Name
of from a list:

1 openstack flavor list

4. To attach a NIC to a particular network, type the following command to choose a network ID from
a network list:

1 openstack network list

5. To create an instance, type the following command:

1 openstack server create --flavor FLAVOR_ID --image IMAGE_ID --key-name

KEY_NAME
2 --user-data USER_DATA_FILE_PATH --config-drive True --nic net-id=net-
uuid
3 INSTANCE_NAME
4 openstack server create --image VPX-ToT-Image --flavor m1.medium --user
-data
5 ovf.xml --config-drive True --nic net-id=2734911b-ee2b-48d0-a1b6-3
efd44b761b9

© 1999-2018 Citrix Systems, Inc. All rights reserved. 633

NetScaler 12.0

6 VPX-ToT

Figure 2: The following illustration provides a sample output.

1.
2. Citrix ADC
3. NetScaler 12.0

Provision the NetScaler VPX instance by using the Virtual Machine

Manager

January 6, 2019

Contributed by:
C

The Virtual Machine Manager is a desktop tool for managing VM guests. It enables you to create new
VM guests and various types of storage, and manage virtual networks. You can access the graphical
console of VM guests with the built-in VNC viewer and view performance statistics, either locally or
remotely.

After installing your preferred Linux distribution, with KVM virtualization enabled, you can proceed
with provisioning virtual machines.

While using the Virtual Machine Manager to provision a NetScaler VPX instance, you have two options:

• Enter the IP address, gateway, and netmask manually

• Assign the IP address, gateway, and netmask automatically (auto-provisioning)

You can use two kinds of images to provision a NetScaler VPX instance:

• RAW
• QCOW2

You can convert a NetScaler VPX RAW image to a QCOW2 image and provision the NetScaler VPX in-
stance. To convert the RAW image to a QCOW2 image, type the following command:

qemu-img convert -O qcow2 original-image.raw image-converted.qcow

For example:
qemu-img convert -O qcow2 NSVPX-KVM-11.1-12.5_nc.raw NSVPX-KVM-11.1-12.5_nc.qcow

A typical NetScaler VPX deployment on KVM includes the following steps:

• Checking prerequisites for Auto-Provisioning a NetScaler VPX Instance

• Provisioning the NetScaler VPX Instance by Using a RAW Image

© 1999-2018 Citrix Systems, Inc. All rights reserved. 634

NetScaler 12.0

• Provisioning the NetScaler VPX Instance by Using a QCOW2 Image

• Adding Additional Interfaces to a VPX Instance by using Virtual Machine Manager

Check prerequisites for auto-provisioning a NetScaler VPX instance

Auto-provisioning is an optional feature, and it involves using data from the CDROM drive. If this fea-
ture is enabled, you need not enter the management IP address, network mask, and default gateway
of the NetScaler VPX instance during initial setup.
You need to complete the following tasks before you can auto-provision a VPX instance:

1. Create a customized Open Virtualization Format (OVF) XML file or userdata file.
2. Convert the OVF file into an ISO image by using an online application (for example PowerISO).
3. Mount the ISO image on the the KVM host by using any secure copy (SCP)-based tools.

Sample OVF XML file:

Here’s is an example of the contents an OVF XML file, which you can use as a sample to create your file.

<?xml version=”1.0” encoding=”UTF-8” standalone=”no”?>

<Environment xmlns:oe=”http://schemas.dmtf.org/ovf/environment/1”

xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”

oe:id=””

xmlns=”http://schemas.dmtf.org/ovf/environment/1”

xmlns:cs=”http://schemas.citrix.com/openstack”\>

<PlatformSection>

<Kind></Kind>

<Version>2016.1</Version>

<Vendor>VPX</Vendor>

<Locale>en</Locale>

</PlatformSection>

<PropertySection>

<Property oe:key=”com.citrix.netscaler.ovf.version” oe:value=”1.0”/>

<Property oe:key=”com.citrix.netscaler.platform” oe:value=”NSVPX”/>

<Property oe:key=”com.citrix.netscaler.orch_env” oe:value=”KVM”/>

<Property oe:key=”com.citrix.netscaler.mgmt.ip” oe:value=”10.1.2.22”/>

<Property oe:key=”com.citrix.netscaler.mgmt.netmask” oe:value=”255.255.255.0”/>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 635

NetScaler 12.0

<Property oe:key=”com.citrix.netscaler.mgmt.gateway” oe:value=”10.1.2.1”/>

</PropertySection>

</Environment>

In the OVF XML file above, “PropertySection” is used for NetScaler networking configuration. When
you create the file, specify values for the parameters that are highlighted at the end of the example:

• Management IP address
• Netmask
• Gateway

Important

If the OVF file is not properly XML formatted, the VPX instance is assigned the default network
configuration, not the values specified in the file.

Provision the NetScaler VPX instance by using a RAW image

The Virtual Machine Manager enables you to provision a NetScaler VPX instancy by using a RAW image.

To provision a NetScaler VPX instance by using the Virtual Machine Manager, follow these steps:

1. Open the Virtual Machine Manager (Application > System Tools > Virtual Machine Manager)
and enter the logon credentials in the Authenticate window.

2. Click the icon or right-click localhost (QEMU) to create a new NetScaler VPX instance.

3. In the Name text box, enter a name for the new VM (for example, NetScaler-VPX).

4. In the New VM window, under “Choose how you would like to install the operating system,”
select Import existing disk image, and then and click Forward.

5. In the Provide the existing storage path field, navigate the path to the image. Choose the OS
type as UNIX and Version as FreeBSD 6.x. Then, click Forward.

6. Under Choose Memory and CPU settings select the following settings, and then click Forward:

• Memory (RAM)— 2048 MB

• CPUs— 2

7. Select the Customize configuration before install check box. Optionally, under Advanced op-
tions you can you can customize the MAC address. Make sure the Virt Type selected is kvm and
the Architecture selected is x86_64. Click Finish.

8. Select a NIC and provide the following configuration:

• Source device— ethX macvtap or Bridge

• Device model— virtio

© 1999-2018 Citrix Systems, Inc. All rights reserved. 636

NetScaler 12.0

• Source mode— Bridge

9. Click Apply.

10. If you want to auto-provision the VPX instance, see the section “Enabling Auto-Provisioning
by Attaching a CDROM Drive” in this document. Otherwise, click Begin Installation. After you
have provisioned the NetScaler VPX on KVM, you can add additional interfaces.

Provision the NetScaler VPX instance by using a QCOW2 image

Using the Virtual Machine Manager, you can provision the NetScaler VPX instance by using a QCOW2
image.

To provision a NetScaler VPX instance by using a QCOW2 image, follow these steps:

1. Follow step 1 to step 8 in Provision the NetScaler VPX instance by using a RAW image.
Note: Ensure that you select qcow2 image in step 5 .
2. Select Disk 1 and click Advanced options.
3. Select qcow2 from the Storage format drop-down list.

4. Click Apply, and then click

Begin Installation. After you have provisioned the NetScaler VPX on KVM, you can add additional
interfaces.

Enable auto-provisioning by attaching a CDROM drive

1. Click Add Hardware > Storage > Device type > CDROM device.

2. Click Manage and selec the correct ISO file that you mounted in the “Prerequisites for Auto-
Provisioning a NetScaler VPX Instance” section, and click Finish. A new CDROM under Resources on
your NetScaler VPX instance is created.

3. Power on the VPX instance, and it auto-provisions with the network configuration provided in the
OVF file, as shown in the example screen capture.

4. If auto-provision fails, the instance comes up with the default IP address (192.168.100.1). In that
case, you need to complete the initial configuration manually. For more information, see Configuring
a NetScaler for the First Time.

Add additional interfaces to the NetScaler VPX instance by using Virtual Machine
Manager

After you have provisioned the NetScaler VPX instance on KVM, you can add additional interfaces.

To add additional interfaces, follow these steps.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 637

NetScaler 12.0

1. Shut down the NetScaler VPX instance running on the KVM.

2. Right-click the VPX instance and choose Open from the pop-up menu.

3. Click the icon in the header to view the virtual hardware details.

4. Click Add Hardware. In the Add New Virtual Hardware window, select Network from the
navigation menu.

5. In Host Device field, select the physical interface type. The host device type can be either
Bridge or MacVTap. In case of MacVTap, four modes possible are VEPA, Bridge, Private and Pass-
through.

a) For Bridge
i. Host device— Select the “Specify shared device name” option.
ii. Provide the Bridge name that is configured in the KVM host.
Note: Make sure that you have configured a Linux bridge in the KVM host, bound the
physical interface to the bridge, and put the bridge in the UP state.
iii. Device model—virtio.
iv. Click Finish.
b) For MacVTap
i. Host device—Select the physical interface from the menu.
ii. Device model—virtio.
iii. Click Finish. You can view the newly added NIC in the navigation pane.
iv. Select the newly added NIC and select the Source mode for this NIC. The available
modes are VEPA, Bridge, Private, and Passthrough. For more details on the interface
and modes, see Source Interface and Modes.
v. Click Apply.

6. If you want to auto-provision the VPX instance, see the section “Adding a Config Drive to Enable
Auto-Provisioning” in this document. Otherwise, power on the VPX instance to complete the
initial configuration manually.

Important

Interface parameter configurations such as speed, duplex, and autonegotiation are not
supported.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 638

NetScaler 12.0

Configure a NetScaler VPX instance to use SR-IOV network interfaces

January 6, 2019

Contributed by:
C

You can use the Virtual Machine Manager to configure a NetScaler VPX instance running on Linux-KVM
to use single root I/O virtualization (SR-IOV) network interfaces with Intel 82599 10G NIC and X710 10G
and XL710 40G NICs.

This section describes how to:

• Configure a NetScaler VPX Instance to Use SR-IOV Network Interface

• Configure Static LA/LACP on the SR-IOV Interface
• Configure VLAN on the SR-IOV Interface

Limitations

Keep the limitations in mind while using Intel 82599, X710, XL710 NICs. The following features not
supported.

Limitations for Intel 82599 NICs:

• L2 mode switching
• Admin partitioning (shared VLAN mode)
• High availability (active-active mode
• Jumbo Frames.
• IPv6: You can configure only up to 30 unique IPv6 addresses in a VPX instance if you’ve alteast
one SR-IOV interface.
• VLAN configuration on Hypervisor for SRIOV VF interface through “ip link” command is not sup-
ported.
• Interface parameter configurations such as speed, duplex, and autonegotiations are not sup-
ported.

Limitations for X710 10G and XL710 40G NICs:

• L2 mode switching.
• In a cluster, Jumbo Frames are not supported when the XL710 NIC is used as a data interface.
• Interface list re-orders when interfaces are disconnected and reconnected.
• Interface parameter configurations such as speed, duplex, and auto negotiations are not sup-
ported.
• Interface name is 40/X for both XL710 and X710 NICs

© 1999-2018 Citrix Systems, Inc. All rights reserved. 639

NetScaler 12.0

• Up to 16 Intel XL710/X710 SRIOV or PCI Passthrough interfaces can be supported on a VPX in-
stance.
Note: For IPv6 to work with X710 10G and XL710 40G NICs, you need to enable trust mode on the
Virtual Functions (VFs) by typing the following command on the KVM host:

## ip link set <PNIC> <VF> trust on

For example:

## ip link set ens785f1 vf 0 trust on

Prerequisites

Before you configure a NetScaler VPX instance to use SR-IOV network interfaces, complete the follow-
ing prerequisite tasks. See the NIC column for details about about how to complete the corresponding
tasks.

Task 82599 NIC X710 and XL710 NICs

1. Add the NIC to the KVM - -

host.
2. Download and install the IXGBE driver I40E driver
latest Intel driver.
3. Blacklist the driver on the Add the following entry in the Add the following entry in the
KVM host. /etc/mod- /etc/mod-
probe.d/blacklist.conf file: probe.d/blacklist.conf file:
blacklist ixgbevf. Use IXGBE blacklist i40evf.Use i40e driver
driver version 4.3.15 version 2.0.26
(recommended). (recommended).

© 1999-2018 Citrix Systems, Inc. All rights reserved. 640

NetScaler 12.0

Task 82599 NIC X710 and XL710 NICs

4.Enable SR-IOV Virtual If you are using earlier version If you are using earlier version
Functions (VFs) on the KVM of kernel 3.8, then add the of kernel 3.8, then add the
host. In both the commands following entry to the following entry to the
in the next two columns: /etc/modprobe.d/ixgbe file /etc/modprobe.d/i40e.conf
number_of_VFs =the number and restart the KVM host: file and restart the KVM
of Virtual VFs that you want to *options ixgbe max_vfs=*.If host:*options i40e
create. device_name =the you are using kernel 3.8 max_vfs=*.If you are using
interface name. version or later, create VFs kernel 3.8 version or later,
using the following create VFs using the following
command: *echo > command: *echo >
/sys/class/net//device/s- /sys/class/net//device/s-
riov_numvfs*. See example in riov_numvfs*.See example in
figure 1. figure 2.
5. Make the VFs persistent by See example in figure 3. See example in figure 3.
adding the commands that
you used to create VFs, to the
rc.local file.

Important

When you are create the SR-IOV VFs, ensure that you do not assign MAC addresses to the VFs.

Figure 1: Enable SR-IOV VFs on the KVM host for 82599 10G NIC.

Figure 2: Enable SR-IOV VFs on the KVM host for X710 10G and XL710 40G NICs.

Figure 3: Make the VFs persistent.

Configure a NetScaler VPX instance to use SR-IOV network interface

To configure NetScaler VPX instance to use SR-IOV network interface by using Virtual Machine Manager,
complete these steps:

1. Power off the NetScaler VPX instance.

2. Select the NetScaler VPX instance and then select Open.

1. In the <virtual_machine on KVM> window, select the i icon.

1. Select Add Hardware.

5. In the Add New Virtual Hardware dialog box, do the following:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 641

NetScaler 12.0

1 a. Select PCI Host Device.

2 b. In the Host Device section, select the VF you have created and click
Finish.

Figure 4:VF for 82599 10G NIC

Figure 5: VF for XL710 NIC

6. Repeat Step 4 and 5 to add the VFs that you have created.
7. Power on the NetScaler VPX instance.
8. After the NetScaler VPX instance powers on, use the following command to verify the configu-
ration:

1 > show interface summary

The output shows all the interfaces that you configured.

Figure 6: output summary for 82599.

Figure 7. Output summary for X710 and XL710 NICs.

Configure static LA/LACP on the SR-IOV interface

Important

When you are creating the SR-IOV VFs, ensure that you do not assign MAC addresses to the VFs.

To use the SR-IOV VFs in link aggregation mode, disable spoof checking for VFs that you have created.
On the KVM host, use the following command to disable spoof checking:

*ip link set \<interface\\_name\> vf \<VF\\_id\> spoofchk off*

Where:

• Interface_name – is the interface name.

• VF_id – is the Virtual Function id.

For example:

After you disable spoof checking for all the VFs that you have created. Restart the NetScaler VPX in-
stance and configure link aggregation. For detailed instructions, see Configure Link Aggregation.

Configuring VLAN on the SR-IOV Interface

You can configure VLAN on SR-IOV VFs. For detailed instructions, see Configuring a VLAN.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 642

NetScaler 12.0

Important

Ensure that the KVM host does not contain VLAN settings for the VF interface.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure a NetScaler VPX instance to use PCI passthrough network

interfaces

January 6, 2019

Contributed by:
C

After you have installed and configured a NetScaler VPX instance on the Linux-KVM platform, you can
use the Virtual Machine Manager to configure the virtual appliance to use PCI passthrough network
interfaces.

Prerequisites

• The firmware version of the Intel XL710 Network Interface Card (NIC) on the KVM Host is 5.04.
• The KVM Host supports input–output memory management unit (IOMMU) and Intel VT-d, and
they are enabled in the BIOS of the KVM Host. On the KVM Host, to enable IOMMU, add the
following entry to the /boot/grub2/grub.cfg file:
intel_iommu=1
• Execute the following command and reboot the KVM Host:
Grub2-mkconfig –o /boot/grub2/grub.cfg

To configure NetScaler VPX instances to use PCI passthrough network interfaces by using the
Virtual Machine Manager:

1. Power off the NetScaler VPX instance.

2. Select the NetScaler VPX instance and click Open.

3. In the <virtual_machine on KVM> window, click the i icon.

4. Click Add Hardware.

5. In the Add New Virtual Hardware dialog box, do the following:

a. Select PCI Host Device.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 643

NetScaler 12.0

b. In the Host Device section, select the Intel XL710 physical function.
c. Click Finish.
6. Repeat steps 4 and 5 to add any additional Intel XL710 physical functions.
7. Power on the NetScaler VPX instance.
8. Once the NetScaler VPX instance powers on, you can use the following command to verify the con-
figuration:
The output should show all the interfaces that you configured:
1.
2. Citrix ADC
3. NetScaler 12.0

Provision the NetScaler VPX instance by using the virsh program

September 20, 2018

Contributed by:
C
The virsh program is a command line tool for managing VM Guests. Its functionality is similar to that
of Virtual Machine Manager. It enables you to change a VM Guest’s status (start, stop, pause, and so
on), to set up new Guests and devices, and to edit existing configurations. The virsh program is also
useful for scripting VM Guest management operations.
To provision NetScaler VPX by using the virsh program, follow these steps:
1. Use the tar command to untar the the NetScaler VPX package. The NSVPX-KVM-*_nc.tgz package
contains following components:
• The Domain XML file specifying VPX attributes [NSVPX-KVM-*_nc.xml]
• Check sum of NS-VM Disk Image [Checksum.txt]
• NS-VM Disk Image [NSVPX-KVM-*_nc.raw]
Example:

1 tar -xvzf NSVPX-KVM-10.1-117_nc.tgz

2 NSVPX-KVM-10.1-117_nc.xml
3 NSVPX-KVM-10.1-117_nc.raw
4 checksum.txt

2. Copy the NSVPX-KVM-*_nc.xml XML file to a file named <DomainName>-NSVPX-KVM-*_nc.xml.

The <DomainName> is also the name of the virtual machine. Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 644

NetScaler 12.0

1 cp NSVPX-KVM-10.1-117_nc.xml NetScaler-VPX-NSVPX-KVM-10.1-117_nc.
xml

3. Edit the <DomainName>-NSVPX-KVM-*_nc.xml file to specify the following parameters:

• name— Specify the name.

• mac— Specify the MAC address.
Note: The domain name and the MAC address have to be unique.
• sourcefile— Specify the absolute disk-image source path. The file path has to be absolute.
You can specify the path of the RAW image file or a QCOW2 image file.
If you want to specify a RAW image file, specify the disk image source path as shown in the
following example:

Example:
<name>NetScaler-VPX</name>
<mac address=’52:54:00:29:74:b3’/>
<source file=’/root/NSVPX-KVM-10.1-117_nc.raw’/>

Specify the absolute QCOW2 disk-image source path and define the driver type as qcow2,
as shown in the following example:

Example:
<name>NetScaler-VPX</name>
<mac address=’52:54:00:29:74:b3’/>
<driver name =’qemu’ type=’qcow2’/>
<source file=’/root/NSVPX-KVM-10.1-117_nc.qcow’/>

4. Edit the <DomainName>-NSVPX-KVM-*_nc.xml file to configure the networking details:

• source dev— specify the interface.

• mode— specify the mode. The default interface is Macvtap Bridge.

Example: Mode: MacVTap Bridge Set target interface as ethx and mode as bridge Model type as
virtio

1 <interface type=’direct’>
2 <mac address=’52:54:00:29:74:b3’/>
3 <source dev=’eth0’ mode=’bridge’/>
4 <target dev=’macvtap0’/>
5 <model type=’virtio’/>
6 <alias name=’net0’/>
7 <address type=’pci’ domain=’0x0000’ bus=’0x00’ slot=’0x03’
function=’0x0’/>
8 </interface>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 645

NetScaler 12.0

Here, eth0 is the physical interface attached to the VM.

5. Define the VM attributes in the <DomainName>-NSVPX-KVM-*_nc.xml file by using the following

command: virsh define <DomainName>-NSVPX-KVM-*_nc.xml Example:

1 virsh define NS-VPX-NSVPX-KVM-10.1-117_nc.xml

Start the VM by entering following command: <DomainUUID>] Example:

virsh start [<DomainName>

1 virsh start NetScaler-VPX

Connect the Guest VM <DomainUUID> <DomainID> ] Example:

through the console virsh
console [<DomainName>

6.
7.
1 virsh console NetScaler-VPX

Add additional interfaces to NetScaler VPX instance using virsh program

After you have provisioned the NetScaler VPX on KVM, you can add additional interfaces.

To add additional interfaces, follow these steps:

1. Shut down the NetScaler VPX instance running on the KVM.

Edit the <DomainName>-NSVPX-KVM-*_nc.xml <DomainUUID>]

file using the command: virsh edit
[<DomainName>

2.

3. In the <DomainName>-NSVPX-KVM-*_nc.xml file, append the following parameters:

a) For MacVTap

• Interface type— Specify the interface type as ‘direct’.

• Mac address— Specify the Mac address and make sure the MAC address is unique
across the interfaces.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 646

NetScaler 12.0

• source dev— Specify the interface name.

• mode— Specify the mode; the modes supported are - Bridge, VEPA, Private, and Pass-
through
• model type— Specify the model type as virtio

Example:

Mode: MacVTap Pass-through

Set target interface as

ethx, Mode as
bridge, and model type as
virtio

1 <interface type=’direct’>
2 <mac address=’52:54:00:29:74:b3’/>
3 <source dev=’eth1’ mode=’passthrough’/>
4 <model type=’virtio’/>
5 </interface>

Here eth1 is the physical interface attached to the VM.

b) For Bridge Mode

Note: Make sure that you have configured a Linux bridge in the KVM host, bound the phys-
ical interface to the bridge, and put the bridge in the UP state.

• Interface type— Specify the interface type as ‘bridge’.

• Mac address— Specify the Mac address and make sure the MAC address is unique
across the interfaces.
• source bridge— Specify the bridge name.
• model type— Specify the model type as virtio

Example: Bridge Mode

1 <interface type=’bridge’>
2 <mac address=’52:54:00:2d:43:a4’/>
3 <source bridge=’br0’/>
4 <model type=’virtio’/>
5 </interface>

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 647

NetScaler 12.0

Manage the NetScaler VPX guest VMs

January 6, 2019

Contributed by:
C

You can use the Virtual Machine Manager and the virsh program to perform management tasks such
as starting or stopping a VM Guest, setting up new guests and devices, editing existing configurations,
and connecting to the graphical console through Virtual Network Computing (VNC).

Manage the VPX guest VMs by using Virtual Machine Manager

• List the VM guests

The main Window of the Virtual Machine Manager displays a list of all the VM Guests for each VM
host server it is connected to. Each VM Guest entry contains the virtual machine’s name, along
with its status (Running, Paused, or Shutoff) displayed as icon.

• Open a graphical console

Opening a Graphical Console to a VM Guest enables you to interact with the machine like you
would with a physical host through a VNC connection. To open the graphical console in the
Virtual Machine Manager, right-click the VM Guest entry and select the Open option from the
pop-up menu.

• Start and shut down a guest

You can start or stop a VM Guest from the Virtual Machine Manager. To change the state of the
VM, right-click the VM Guest entry and select Run or one of the Shut Down options from the
pop-up menu.

• Reboot a guest

You can reboot a VM Guest from the Virtual Machine Manager. To reboot the VM, right-click the
VM Guest entry, and then select Shut Down > Reboot from the pop-up menu.

• Delete a guest

Deleting a VM Guest removes its XML configuration by default. You can also delete a guest’s
storage files. Doing so completely erases the guest.

1. In the Virtual Machine Manager, right-click the VM Guest entry.

2. Select Delete from the pop-up menu. A confirmation window opens.
Note: The Delete option is enabled only when the VM Guest is shut down.
3. Click Delete.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 648

NetScaler 12.0

4. To completely erase the guest, delete the associated .raw file by selecting the Delete Asso-
ciated Storage Files check box.

Manage the NetScaler VPX guest VMs using the virsh program

• List the VM Guests and their current states.

To use virsh to display information about the Guests

virsh list –all
The command output displays all domains with their states.
Example output:

1 Id Name State
2 ----------------------------------
3 0 Domain-0 running
4 1 Domain-1 paused
5 2 Domain-2 inactive
6 3 Domain-3 crashed

• Open a virsh console.

Connect the Guest VM through the console

virsh console [<DomainID> | <DomainName> | <DomainUUID>]
Example:
virsh console NetScaler-VPX

• Start and shut down a guest.

Guests can be started using the DomainName or Domain-UUID.

virsh start [<DomainName> | <DomainUUID>]
Example
virsh start NetScaler-VPX

To shut down a guest:

virsh shutdown [<DomainID> | <DomainName> | <DomainUUID>]
Example:
virsh shutdown NetScaler-VPX

• Reboot a guest

virsh reboot [<DomainID> | <DomainName> | <DomainUUID>]

Example:
virsh reboot NetScaler-VPX

Delete a guest

© 1999-2018 Citrix Systems, Inc. All rights reserved. 649

NetScaler 12.0

To delete a Guest VM you need to shut-down the Guest and un-define the
<DomainName>-NSVPX-KVM-*_nc.xml before you run the delete command.

1 virsh shutdown [<DomainID> | <DomainName> | <DomainUUID>]

2 virsh undefine [<DomainName> | <DomainUUID>]

Example:

1 virsh shutdown NetScaler-VPX

2 virsh undefine NetScaler-VPX

Note: The delete command doesn’t remove disk image file which needs to be removed manu-
ally.

1.
2. Citrix ADC
3. NetScaler 12.0

Provision the NetScaler VPX instance with SR-IOV, on OpenStack

January 6, 2019

Contributed by:
C

You can deploy high-performance NetScaler VPX instances that use single-root I/O virtualization (SR-
IOV) technology, on OpenStack.

You can deploy a NetScaler VPX instance that uses SR-IOV technology, on OpenStack, in three steps:

• Enable SR-IOV Virtual Functions (VFs) on the host.

• Configure and make the VFs available to OpenStack.
• Provision the NetScaler VPX on OpenStack.

Prerequisites

Ensure that you:

• Add the Intel 82599 Network Interface Card (NIC) to the host.
• Download and Install the latest IXGBE driver from Intel.
• Blacklist the IXGBEVF driver on the host. Add the following entry in the /etc/mod-
probe.d/blacklist.conf file: blacklist ixgbevf

© 1999-2018 Citrix Systems, Inc. All rights reserved. 650

NetScaler 12.0

Note

The ixgbe driver version should be minimum 5.0.4.

Enable SR-IOV VFs on the host

Do one of the following steps to enable SR-IOV VFs:

• If you are using a kernel version earlier than 3.8, add the following entry to the /etc/mod-
probe.d/ixgbe file and restart the host: options ixgbe max_vfs=<number_of_VFs>

• If you are using kernel 3.8 version or later, create VFs by using the following command:

1 echo <number_of_VFs> > /sys/class/net/<device_name>/device/

sriov_numvfs

Where:

• number_of_VFs is the number of Virtual Functions that you want to create.

• device_name is the interface name.
Important

While you are creating the SR-IOV VFs, make sure that you do not assign MAC addresses to the
VFs.

Here is an example of four VFs being created.

Make the VFs persistent, add the commands that you used to created VFs to the rc.local file. Here is
an example showing contents of rc.local file.

For more information, see this Intel SR-IOV Configuration Guide.

Configure and make the VFs available to OpenStack

Follow the steps given at the link below to configure SR-IOV on OpenStack: https://wiki.openstack.
org/wiki/SR-IOV-Passthrough-For-Networking.

Provision the NetScaler VPX instance on OpenStack

You can provision a NetScaler VPX instance in an Openstack environment by using the OpenStack CLI.

Provisioning a VPX instance, optionally involves using data from the config drive. The config drive is a
special configuration drive that attaches to the instance when it boots. This configuration drive can be
used to pass networking configuration information such as management IP address, network mask,
and default gateway etc. to the instance before you configure the network settings for the instance.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 651

NetScaler 12.0

When OpenStack provisions a VPX instance, it first detects that the instance is booting in an OpenStack
environment, by reading a specific BIOS string (OpenStack Foundation) that indicates OpenStack. For
Red Hat Linux distributions, the string is stored in /etc/nova/release. This is a standard mechanism
that is available in all OpenStack implementations based on KVM hyper-visor platform. The drive
should have a specific OpenStack label. If the config drive is detected, the instance attempts to read
the following information from the file name specified in the nova boot command. In the procedures
below, the file is called “userdata.txt.”

• Management IP address
• Network mask
• Default gateway

Once the parameters are successfully read, they are populated in the NetScaler stack. This helps in
managing the instance remotely. If the parameters are not read successfully or the config drive is not
available, the instance transitions to the default behavior, which is:

• The instance attempts to retrieve the IP address information from DHCP.

• If DHCP fails or times-out, the instance comes up with default network configuration
(192.168.100.1/16).

Provision the NetScaler VPX instance on OpenStack through CLI

You can provision a VPX instance in an OpenStack environment by using the OpenStack CLI. Here’s the
summary of the steps to provision a NetScaler VPX instance on OpenStack:

1. Extracting the .qcow2 file from the .tgz file

2. Building an OpenStack image from the qcow2 image

3. Provisioning a VPX instance

To provision a VPX instance in an OpenStack environment, do the following steps.

1. Extract the. qcow2 file from the .tqz file by typing the command:

1 tar xvzf <TAR file>

2
3 tar xvzf NSVPX-KVM-12.0-26.2_nc.tgz
4 NSVPX-KVM.xml
5 NSVPX-KVM-12.0-26.2_nc.qcow2

2. Build an OpenStack image using the .qcoz2 file extracted in step 1 by typing the following command:

1 glance image-create --name=”<name of the OpenStack image>” --

2 property hw_disk_bus=ide --is-public=
3  true --container-format=bare --disk-format=qcow2< <name of the

© 1999-2018 Citrix Systems, Inc. All rights reserved. 652

NetScaler 12.0

4 qcow2 file>
5
6 glance image-create --name=”NS-VPX-12-0-26-2” --property
7 hw_disk_bus=ide --is-public=
8 true --container-format=bare --disk-format=qcow2< NSVPX-KVM-12.0-
9 26.2_nc.qcow2

The following illustration provides a sample output for the glance image-create command.

3. After an OpenStack image is created, provision the NetScaler VPX instance instance.

1 nova boot --image NSVPX-KVM-12.0-26.2 --config-drive=true --userdata

2 ./userdata.txt --flavor m1. medium --nic net-id=3b258725-eaae-
3 455e-a5de-371d6d1f349f --nic port-id=218ba819-9f55-4991-adb6-
4 02086a6bdee2 NSVPX-10

In the above command, userdata.txt is the file which contains the details like, IP address, netmask,
and default gateway for the VPX instance. The userdata file is a user customizable file. NSVPX-KVM-
12.0-26.2 is the name of the virtual appliance that you want to provision. –nic port-id=218ba819-9f55-
4991-adb6-02086a6bdee2 is the OpenStack VF.

The following illustration gives a sample output of the nova boot command.

The following illustration shows a sample of the userdata.txt file. The values within the <PropertySection></Propert
tags are the values which is user configurable and holds the information like, IP address, netmask,and
default gateway.

1 <?xml version=”1.0” encoding=”UTF-8” standalone=”no”?>

2 <Environment xmlns:oe=”http://schemas.dmtf.org/ovf/environment/1”
3 xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
4 oe:id=””
5 xmlns=”http://schemas.dmtf.org/ovf/environment/1”>
6 <PlatformSection>
7 <Kind>NOVA</Kind>
8 <Version>2013.1</Version>
9 <Vendor>Openstack</Vendor>
10 <Locale>en</Locale>
11 </PlatformSection>
12 <PropertySection>
13 <Property oe:key=”com.citrix.netscaler.ovf.version” oe:value=”1.0”/>
14 <Property oe:key=”com.citrix.netscaler.platform” oe:value=”vpx”/>
15 citrix.com 4
16 <Property oe:key=”com.citrix.netscaler.orch_env”
17 oe:value=”openstack-orch-env”/>
18 <Property oe:key=”com.citrix.netscaler.mgmt.ip”
19 oe:value=”10.1.0.100”/>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 653

NetScaler 12.0

20 <Property oe:key=”com.citrix.netscaler.mgmt.netmask”
21 oe:value=”255.255.0.0”/>
22 <Property oe:key=”com.citrix.netscaler.mgmt.gateway”
23 oe:value=”10.1.0.1”/>
24 </PropertySection>
25 </Environment>

Additional supported Configurations: Creating and Deleting VLANs on SR-IOV VFs from the Host

Type the following command to create a VLAN on the SR-IOV VF:

1 ip link show enp8s0f0 vf 6 vlan 10

In the above command “enp8s0f0” is the name of the physical function.

Example: vlan 10, created on vf 6

Type the following command to delete a VLAN on the SR-IOV VF:

1 ip link show enp8s0f0 vf 6 vlan 0

Example: vlan 10, removed from vf 6

These steps complete the procedure for deploying a NetScaler VPX instance that uses SRIOV technol-
ogy, on OpenStack.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure a NetScaler VPX instance on KVM to use OVS DPDK-based host

interfaces

November 2, 2018

Contributed by:
C

You can configure a NetScaler VPX instance running on KVM (Fedora and RHOS) to use Open vSwitch
(OVS) with Data Plane Development Kit (DPDK) for better network performance. Also, certain
NetScaler VPX deployments require the VPX host on KVM to operate on the vhost-user ports exposed
by OVS rather than on MacVTap-based vhost interfaces.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 654

NetScaler 12.0

OVS is a multilayer virtual switch licensed under the open-source Apache 2.0 license. DPDK is a set of
libraries and drivers for fast packet processing.

The following Fedora, RHOS, OVS, and DPDK versions are qualified for configuring a NetScaler VPX
instance:

Fedora RHOS

Fedora 25 RHOS 7.4

OVS 2.7.0 OVS 2.6.1
DPDK 16.11.12 DPDK 16.11.12

Prerequisites

Before you install DPDK, make sure the host has 1 GB hugepages.
For more information, see this DPDK system requirements documentation.
Here is the summary of the steps required to configuring a NetScaler VPX Instance on KVM to use OVS
DPDK-based host interfaces:
• Install DPDK.
• Build and Install OVS.
• Create an OVS bridge.
• Attach a physical interface to the OVS bridge.
• Attach vhost-user ports to the OVS data path.
• Provision a KVM-VPX with OVS-DPDK based vhost-user ports.

Install DPDK

To install DPDK, follow the instruction given at this Open vSwitch with DPDK document .

Build and install OVS

Download OVS from the OVS download page. Next, build and install OVS by using a DPDK datapath.
Follow the instructions given in the Installing Open vSwitch document.
For more detailed information, DPDK Getting Started Guide for Linux.

Create an OVS bridge

Depending on your need, type the Fedora or RHOS command to create an OVS bridge:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 655

NetScaler 12.0

Fedora command:

1 > $OVS_DIR/utilities/ovs-vsctl add-br ovs-br0 -- set bridge ovs-br0

datapath_type=netdev

RHOS command:

1 ovs-vsctl add-br ovs-br0 -- set bridge ovs-br0 datapath_type=netdev

Attach physical interface to the OVS bridge

Bind the ports to DPDK and then attach them to the OVS bridge by typing the following Fedora or
RHOS commands:

Fedora command:

1 > $OVS_DIR/utilities/ovs-vsctl add-port ovs-br0 dpdk0 -- set Interface

dpdk0 type=dpdk  options:dpdk-devargs=0000:03:00.0
2
3 > $OVS_DIR/utilities/ovs-vsctl add-port ovs-br0 dpdk1 -- set Interface
dpdk1 type=dpdk  options:dpdk-devargs=0000:03:00.1

RHOS command:

1 ovs-vsctl add-port ovs-br0 dpdk0 -- set Interface dpdk0 type=dpdk

 options:dpdk-devargs=0000:03:00.0
2
3
4 ovs-vsctl add-port ovs-br0 dpdk1 -- set Interface dpdk1 type=dpdk
 options:dpdk-devargs=0000:03:00.1

The dpdk-devargs shown as part of options specifies the PCI BDF of the respective physical NIC.

Attach vhost-user ports to the OVS data path

Type the following Fedora or RHOS commands to attach vhost-user ports to the OVS data path:

Fedora command:

1 > $OVS_DIR/utilities/ovs-vsctl add-port ovs-br0 vhost-user1 -- set

Interface vhost-user1 type=dpdkvhostuser -- set Interface vhost-
user1  mtu_request=9000
2

© 1999-2018 Citrix Systems, Inc. All rights reserved. 656

NetScaler 12.0

3 > $OVS_DIR/utilities/ovs-vsctl add-port ovs-br0 vhost-user2 -- set

Interface vhost-user2 type=dpdkvhostuser -- set Interface vhost-
user2  mtu_request=9000
4
5 chmod g+w  /usr/local/var/run/openvswitch/vhost*

RHOS command:

1 ovs-vsctl add-port ovs-br0 vhost-user1 -- set Interface vhost-user1

type=dpdkvhostuser -- set Interface vhost-user1  mtu_request=9000
2
3 ovs-vsctl add-port ovs-br0 vhost-user2 -- set Interface vhost-user2
type=dpdkvhostuser -- set Interface vhost-user2  mtu_request=9000
4
5 chmod g+w /var/run/openvswitch/vhost*

Provision a KVM-VPX with OVS-DPDK-based vhost-user ports

You can provision a VPX instance on Fedora KVM with OVS-DPDK-based vhost-user ports only from CLI
by using the following QEMU commands:
Fedora command:

1 qemu-system-x86_64 -name KVM-VPX -cpu host -enable-kvm -m 4096M \

2
3 -object memory-backend-file,id=mem,size=4096M,mem-path=/dev/hugepages,
share=on -numa node,memdev=mem \
4
5 -mem-prealloc -smp sockets=1,cores=2 -drive file=<absolute-path-to-disc
-image-file>,if=none,id=drive-ide0-0-0,format=<disc-image-format> \
6
7 -device ide-drive,bus=ide.0,unit=0,drive=drive-ide0-0-0,id=ide0-0-0,
bootindex=1 \
8
9 -netdev type=tap,id=hostnet0,script=no,downscript=no,vhost=on \
10
11 -device virtio-net-pci,netdev=hostnet0,id=net0,mac=52:54:00:3c:d1:ae,
bus=pci.0,addr=0x3 \
12
13 -chardev socket,id=char0,path=</usr/local/var/run/openvswitch/vhost-
user1> \
14
15 -netdev type=vhost-user,id=mynet1,chardev=char0,vhostforce -device
virtio-net-pci,mac=00:00:00:00:00:01,netdev=mynet1,mrg_rxbuf=on \

© 1999-2018 Citrix Systems, Inc. All rights reserved. 657

NetScaler 12.0

16
17 -chardev socket,id=char1,path=</usr/local/var/run/openvswitch/vhost-
user2> \
18
19 -netdev type=vhost-user,id=mynet2,chardev=char1,vhostforce -device
virtio-net
20
21 pci,mac=00:00:00:00:00:02,netdev=mynet2,mrg_rxbuf=on \
22
23 --nographic

For RHOS, use the following sample XML file to provision the NetScaler VPX instance, by using virsh.

<domain type=’kvm’>

<name>dpdk-vpx1</name>

<uuid>aedb844b-f6bc-48e6-a4c6-36577f2d68d6</uuid>

<memory unit=’KiB’>16777216</memory>

<currentMemory unit=’KiB’>16777216</currentMemory>

<memoryBacking>

<hugepages>

<page size=’1048576’ unit=’KiB’/>

</hugepages>

</memoryBacking>

<vcpu placement=’static’>6</vcpu>

<cputune>

<shares>4096</shares>

<vcpupin vcpu=’0’ cpuset=’0’/>

<vcpupin vcpu=’1’ cpuset=’2’/>

<vcpupin vcpu=’2’ cpuset=’4’/>

<vcpupin vcpu=’3’ cpuset=’6’/>

<emulatorpin cpuset=’0,2,4,6’/>

</cputune>

<numatune>

<memory mode=’strict’ nodeset=’0’/>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 658

NetScaler 12.0

</numatune>

<resource>

<partition>/machine</partition>

</resource>

<os>

<type arch=’x86_64’ machine=’pc-i440fx-rhel7.0.0’>hvm</type>

<boot dev=’hd’/>

</os>

<features>

<acpi/>

<apic/>

</features>

<cpu mode=’custom’ match=’minimum’ check=’full’>

<model fallback=’allow’>Haswell-noTSX</model>

<vendor>Intel</vendor>

<topology sockets=’1’ cores=’6’ threads=’1’/>

<feature policy=’require’ name=’ss’/>

<feature policy=’require’ name=’pcid’/>

<feature policy=’require’ name=’hypervisor’/>

<feature policy=’require’ name=’arat’/>

<domain type=’kvm’>

<name>dpdk-vpx1</name>

<uuid>aedb844b-f6bc-48e6-a4c6-36577f2d68d6</uuid>

<memory unit=’KiB’>16777216</memory>

<currentMemory unit=’KiB’>16777216</currentMemory>

<memoryBacking>

<hugepages>

<page size=’1048576’ unit=’KiB’/>

</hugepages>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 659

NetScaler 12.0

</memoryBacking>

<vcpu placement=’static’>6</vcpu>

<cputune>

<shares>4096</shares>

<vcpupin vcpu=’0’ cpuset=’0’/>

<vcpupin vcpu=’1’ cpuset=’2’/>

<vcpupin vcpu=’2’ cpuset=’4’/>

<vcpupin vcpu=’3’ cpuset=’6’/>

<emulatorpin cpuset=’0,2,4,6’/>

</cputune>

<numatune>

<memory mode=’strict’ nodeset=’0’/>

</numatune>

<resource>

<partition>/machine</partition>

</resource>

<os>

<type arch=’x86_64’ machine=’pc-i440fx-rhel7.0.0’>hvm</type>

<boot dev=’hd’/>

</os>

<features>

<acpi/>

<apic/>

</features>

<cpu mode=’custom’ match=’minimum’ check=’full’>

<model fallback=’allow’>Haswell-noTSX</model>

<vendor>Intel</vendor>

<topology sockets=’1’ cores=’6’ threads=’1’/>

<feature policy=’require’ name=’ss’/>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 660

NetScaler 12.0

<feature policy=’require’ name=’pcid’/>

<feature policy=’require’ name=’hypervisor’/>

<feature policy=’require’ name=’arat’/>

<feature policy=’require’ name=’tsc_adjust’/>

<feature policy=’require’ name=’xsaveopt’/>

<feature policy=’require’ name=’pdpe1gb’/>

<numa>

<cell id=’0’ cpus=’0-5’ memory=’16777216’ unit=’KiB’ memAccess=’shared’/>

</numa>

</cpu>

<clock offset=’utc’/>

<on_poweroff>destroy</on_poweroff>

<on_reboot>restart</on_reboot>

<on_crash>destroy</on_crash>

<devices>

<emulator>/usr/libexec/qemu-kvm</emulator>

<disk type=’file’ device=’disk’>

<driver name=’qemu’ type=’qcow2’ cache=’none’/>

<source file=’/home/NSVPX-KVM-12.0-52.18_nc.qcow2’/>

<target dev=’vda’ bus=’virtio’/>

<address type=’pci’ domain=’0x0000’ bus=’0x00’ slot=’0x07’ function=’0x0’/>

</disk>

<controller type=’ide’ index=’0’>

<address type=’pci’ domain=’0x0000’ bus=’0x00’ slot=’0x01’ function=’0x1’/>

</controller>

<controller type=’usb’ index=’0’ model=’piix3-uhci’>

<address type=’pci’ domain=’0x0000’ bus=’0x00’ slot=’0x01’ function=’0x2’/>

</controller>

<controller type=’pci’ index=’0’ model=’pci-root’/>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 661

NetScaler 12.0

<interface type=’direct’>

<mac address=’52:54:00:bb:ac:05’/>

<source dev=’enp129s0f0’ mode=’bridge’/>

<model type=’virtio’/>

<address type=’pci’ domain=’0x0000’ bus=’0x00’ slot=’0x03’ function=’0x0’/>

</interface>

<interface type=’vhostuser’>

<mac address=’52:54:00:55:55:56’/>

<source type=’unix’ path=’/var/run/openvswitch/vhost-user1’ mode=’client’/>

<model type=’virtio’/>

<address type=’pci’ domain=’0x0000’ bus=’0x00’ slot=’0x04’ function=’0x0’/>

</interface>

<interface type=’vhostuser’>

<mac address=’52:54:00:2a:32:64’/>

<source type=’unix’ path=’/var/run/openvswitch/vhost-user2’ mode=’client’/>

<model type=’virtio’/>

<address type=’pci’ domain=’0x0000’ bus=’0x00’ slot=’0x05’ function=’0x0’/>

</interface>

<interface type=’vhostuser’>

<mac address=’52:54:00:2a:32:74’/>

<source type=’unix’ path=’/var/run/openvswitch/vhost-user3’ mode=’client’/>

<model type=’virtio’/>

<address type=’pci’ domain=’0x0000’ bus=’0x00’ slot=’0x06’ function=’0x0’/>

</interface>

<interface type=’vhostuser’>

<mac address=’52:54:00:2a:32:84’/>

<source type=’unix’ path=’/var/run/openvswitch/vhost-user4’ mode=’client’/>

<model type=’virtio’/>

<address type=’pci’ domain=’0x0000’ bus=’0x00’ slot=’0x09’ function=’0x0’/>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 662

NetScaler 12.0

</interface>

<serial type=’pty’>

<target port=’0’/>

</serial>

<console type=’pty’>

<target type=’serial’ port=’0’/>

</console>

<input type=’mouse’ bus=’ps2’/>

<input type=’keyboard’ bus=’ps2’/>

<graphics type=’vnc’ port=’-1’ autoport=’yes’>

<listen type=’address’/>

</graphics>

<video>

<model type=’cirrus’ vram=’16384’ heads=’1’ primary=’yes’/>

<address type=’pci’ domain=’0x0000’ bus=’0x00’ slot=’0x02’ function=’0x0’/>

</video>

<memballoon model=’virtio’>

<address type=’pci’ domain=’0x0000’ bus=’0x00’ slot=’0x08’ function=’0x0’/>

</memballoon>

</devices>

</domain

Points to note

In the XML file, the hugepage size must be 1 GB, as shown in the sample file.

<memoryBacking>

<hugepages>

<page size=’1048576’ unit=’KiB’/>

</hugepages>

Also, in the sample file vhost-user1 is the vhostuser port bound to ovs-br0.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 663

NetScaler 12.0

<interface type=’vhostuser’>

<mac address=’52:54:00:55:55:56’/>

<source type=’unix’ path=’/var/run/openvswitch/vhost-user1’ mode=’client’/>

<model type=’virtio’/>

<address type=’pci’ domain=’0x0000’ bus=’0x00’ slot=’0x04’ function=’0x0’/>

</interface>

To bring up the NetScaler VPX instance, start using virsh command.

1.
2. Citrix ADC
3. NetScaler 12.0

Deploy a NetScaler VPX instance on AWS

January 6, 2019

Contributed by:
C

You can launch a Citrix NetScaler VPX instance on Amazon Web Services (AWS). The NetScaler VPX ap-
pliance is available as an Amazon Machine Image (AMI) in AWS marketplace. A NetScaler VPX instance
on AWS enables customer like you to leverage AWS Cloud computing capabilities and use NetScaler
load balancing and traffic management features for their business needs. The VPX instance supports
all the traffic management features of a physical NetScaler appliance, and they can be deployed as
standalone instances or in HA pairs.

This section includes the following topics:

• AWS terminology
• How a NetScaler VPX instance on AWS works
• Supported instance type, ENI, and IP addresses

AWS terminology

Here is a brief description of the terms used in this document. For more information, see AWS Glos-
sary.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 664

NetScaler 12.0

Term Defintion

Amazon Machine Image (AMI) A machine image, which provides the

information required to launch an instance,
which is a virtual server in the cloud.
Elastic Block Store Provides persistent block storage volumes for
use with Amazon EC2 instances in the AWS
Cloud.
Simple Storage Service (S3) Storage for the Internet. It is designed to make
web-scale computing easier for developers.
Elastic Compute Cloud (EC2) A web service that provides secure, resizable
compute capacity in the cloud. It is designed to
make web-scale cloud computing easier for
developers.
Elastic Load Balancing (ELB) Distributes incoming application traffic across
multiple EC2 instances, in multiple Availability
Zones. This increases the fault tolerance of
your applications.
Elastic network interface (ENI) A virtual network interface that you can attach
to an instance in a VPC.
Elastic IP (EIP) address A static, public IPv4 address that you have
allocated in Amazon EC2 or Amazon VPC and
then attached to an instance. Elastic IP
addresses are associated with your account,
not a specific instance. They are elastic
because you can easily allocate, attach,
detach, and free them as your needs change.
Instance type Amazon EC2 provides a wide selection of
instance types optimized to fit different use
cases. Instance types comprise varying
combinations of CPU, memory, storage, and
networking capacity and give you the flexibility
to choose the appropriate mix of resources for
your applications.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 665

NetScaler 12.0

Term Defintion

Identity and Access Management (IAM) An AWS identity with permission policies that
determine what the identity can and cannot do
in AWS. You can use an IAM role to enable
applications running on an EC2 instance to
securely access your AWS resources.IAM role is
required for deploying VPX instances in a
high-availability setup.
Internet Gateway Connects a network to the Internet. You can
route traffic for IP addresses outside your VPC
to the Internet gateway.
Key pair A set of security credentials that you use to
prove your identity electronically. A key pair
consists of a private key and a public key.
Route tables A set of routing rules that controls the traffic
leaving any subnet that is associated with the
route table. You can associate multiple subnets
with a single route table, but a subnet can be
associated with only one route table at a time.
Security groups A named set of allowed inbound network
connections for an instance.
Subnets A segment of the IP address range of a VPC that
EC2 instances can be attached to. You can
create subnets to group instances according to
security and operational needs.
Virtual Private Cloud (VPC) A web service for provisioning a logically
isolated section of the AWS cloud where you
can launch AWS resources in a virtual network
that you define.
Auto Scaling A web service to launch or terminate Amazon
EC2 instances automatically based on
user-defined policies, schedules, and health
checks.
CloudFormation A service for writing or changing templates that
create and delete related AWS resources
together as a unit.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 666

NetScaler 12.0

How a NetScaler VPX instance on AWS works

The NetScaler VPX instance is available as an AMI in AWS marketplace, and it can be launched as an
EC2 instance within an AWS VPC. The NetScaler VPX AMI instance requires a minimum of 2 virtual CPUs
and 2 GB of memory. An EC2 instance launched within an AWS VPC can also provide the multiple
interfaces, multiple IP addresses per interface, and public and private IP addresses needed for VPX
configuration. Each VPX instance requires at least three IP subnets:
• A management subnet
• A client-facing subnet (VIP)
• A back-end facing subnet (SNIP,MIP, etc.)
Citrix recommends three network interfaces for a standard VPX instance on AWS installation.
AWS currently makes multi-IP functionality available only to instances running within an AWS VPC. A
VPX instance in a VPC can be used to load balance servers running in EC2 instances. An Amazon VPC
allows you to create and control a virtual networking environment, including your own IP address
range, subnets, route tables, and network gateways.
Note: By default, you can create up to 5 VPC instances per AWS region for each AWS account. You
can request higher VPC limits by submitting Amazon’s request form http://aws.amazon.com/contact-
us/vpc-request.
Figure 1. A Sample NetScaler VPX Instance Deployment on AWS Architecture
Figure 1 shows a simple topology of an AWS VPC with a
NetScaler VPX deployment. The AWS VPC has:
1. A single Internet gateway to route traffic in and out of the VPC.
2. Network connectivity between the Internet gateway and the Internet.
3. Three subnets, one each for management, client, and server.
4. Network connectivity between the Internet gateway and the two subnets (management and
client).
5. A standalone NetScaler VPX instance deployed within the VPC. The VPX instance has three ENIs,
one attached to each subnet.

Supported instance type, ENI, and IP addresses

For more information about Amazon EC2 instances and IP addresses supported per NIC per instance
type:
• Instance types
• IP addresses per network interface per instance type
For higher bandwidth, Citrix recommends the following instance types:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 667

NetScaler 12.0

Enhanced networking
Instance type Bandwidth (SR-IOV)

M4.10x large 3 Gbps and 5 Gbps Yes

C4.8x large 3 Gbps and 5 Gbps Yes

1.
2. Citrix ADC
3. NetScaler 12.0

Limitations and usage guidelines

November 2, 2018
Contributed by:
C
The following limitations and usage guidelines apply when deploying a NetScaler VPX instance on
AWS:
• Before you start, read the AWS terminology section in Deploy a NetScaler VPX instance on AWS.
• The clustering feature is not supported for VPX.
• For the high availability setup to work effectively, associate a dedicated NAT device to manage-
ment Interface or associate EIP to NSIP. For more information on NAT, in the AWS documenta-
tion, see NAT Instances .
• Data traffic and management traffic must be segregated with ENIs belonging to different sub-
nets.
• Only the NSIP address should be present on the management ENI.
• If a NAT instance is used for security instead of assigning an EIP to the NSIP, appropriate VPC
level routing changes are required. For instructions on making VPC level routing changes, in
the AWS documentation, see Scenario 2: VPC with Public and Private Subnets.
• A VPX instance can be moved from one EC2 instance type to another (for example, from m3.large
to an m3.xlarge).
• For storage options for VPX on AWS, Citrix recommends EBS, because it is durable and the data
is available even after it is detached from instance.
• Dynamic addition of ENIs to VPX is not supported. You have to restart the VPX instance to apply
the update. Citrix recommends you to stop the standalone or HA instance, attach the new ENI,
and then restart the instance.
• You can assign multiple IP addresses to an ENI. The maximum number of IP addresses per ENI
is determined by the EC2 instance type, see the section “IP Addresses Per Network Interface Per

© 1999-2018 Citrix Systems, Inc. All rights reserved. 668

NetScaler 12.0

Instance Type” in Elastic Network Interfaces . You must allocate the IP addresses in AWS before
you assign them to ENIs. For more information, see Elastic Network Interfaces .
• Citrix recommends that you avoid using the enable and disable interface commands on
NetScaler VPX interfaces.
• The NetScaler “set ha node <NODE_ID> -haStatus STAYPRIMARY” and “set ha node <NODE_ID>
-haStatus STAYSECONDARY” commands are disabled by default.
• Due to Amazon AWS limitations, these features are not supported:
– IPV6
– Gratuitous ARP(GARP)
– L2 mode
– Tagged VLAN
– Dynamic Routing
– Virtual MAC (VMAC)
• For RNAT to work, ensure Source/Destination Check is disabled. For more information, see
“Changing the Source/Destination Checking” in Elastic Network Interfaces .
• In a NetScaler VPX deployment on AWS, in some AWS regions, the AWS infrastructure might not
be able to resolve AWS API calls. This happens if the API calls are issued through a nonmanage-
ment interface on the NetScaler VPX instance.
As a workaround, restrict the API calls to the management interface only. To do that, create a
nsvlan on the VPX instance and bind the management interface to the nsvlan by using the ap-
propriate command.
For example:
set ns config -nsvlan <vlan id> -ifnum 1/1 -tagged NO
save config
Restart the VPX instance at the prompt. For more information about configuring nsvlan, see Con-
figuring NSVLAN.

1.
2. Citrix ADC
3. NetScaler 12.0

Prerequisites

September 20, 2018

Contributed by:
C

Before attempting to create a VPX instance in AWS, ensure you have the following:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 669

NetScaler 12.0

• An AWS account: to launch a NetScaler VPX AMI in an Amazon Web Services (AWS) Virtual Pri-
vate Cloud (VPC). You can create an AWS account for free at www.aws.amazon.com.
• An AWS Identity and Access Management (IAM) user account: to securely control access to
AWS services and resources for your users. For more information about how to create an IAM
user account, see the topic Creating IAM Users (Console).

An IAM role is mandatory for both standalone and high availability deployments. The IAM role must
have the following privileges:

ec2:DescribeInstances

ec2:DescribeNetworkInterfaces

ec2:DetachNetworkInterface

ec2:AttachNetworkInterface

ec2:StartInstances

ec2:StopInstances

ec2:RebootInstances

autoscaling:*

sns:*

sqs:*

iam:SimulatePrincipalPolicy

iam:GetRole

If you use the Citrix CloudFormation template, the IAM role is automatically created. The template
does not have the option to select an already created IAM role.

• AWS CLI: to use all of the functionality provided by the AWS Management Console from your
terminal program. For more information , see the AWS CLI user guide. You also need the AWS
CLI to change the network interface type to SR-IOV.

1.
2. Citrix ADC
3. NetScaler 12.0

Deploy a NetScaler VPX standalone instance on AWS

May 29, 2019

© 1999-2018 Citrix Systems, Inc. All rights reserved. 670

NetScaler 12.0

Contributed by:
C

You can deploy a Citrix

NetScaler VPX standalone instance on AWS by using the following options:

1. AWS web console

2. Citrix-authored CloudFormation template
3. AWS CLI

This topic describes the procedure for deploying a NetScaler VPX instance on AWS.

Before you start your deployment, read the following topics:

• Prerequisites
• Limitation and usage guidelines

Deploy a NetScaler VPX instance on AWS by using the AWS web console

You can deploy a NetScaler VPX instance on AWS through the AWS web console. The deployment
process includes the following steps:

1. Create a Key Pair

2. Create a Virtual Private Cloud (VPC)
3. Add additional subnets
4. Create security groups and security rules
5. Add route tables
6. Create an internet gateway
7. Create a NetScaler VPX instance
8. Create and attach additional network interfaces
9. Attach elastic IPs to the management NIC
10. Connect to the VPX instance

Step 1: Create a key pair.

Amazon EC2 uses a key pair to encrypt and decrypt logon information. To log on to your instance, you
must create a key pair, specify the name of the key pair when you launch the instance, and provide
the private key when you connect to the instance.

When you review and launch an instance by using the AWS Launch Instance wizard , you are prompted
to use an existing key pair or create a new key pair. More more information about how to create a key
pair, see Amazon EC2 Key Pairs.

Step 2: Create a VPC.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 671

NetScaler 12.0

A NetScaler VPC instance is deployed inside an AWS VPC. A VPC allows you to define virtual network
dedicated to your AWS account. For more information about AWS VPC, see Getting Started With Ama-
zon VPC.

While creating a VPC for your NetScaler VPX instance, keep the following points in mind.

• Use the VPC with a Single Public Subnet Only option to create a new AWS VPC in an AWS avail-
ability zone.
• Citrix recommends that you create at least three subnets, of the following types:
– One subnet for management traffic. You place the management IP(NSIP) on this subnet. By
default elastic network interface (ENI) eth0 is used for management IP.
– One or more subnets for client-access (user-to-NetScaler VPX) traffic, through which
clients connect to one or more virtual IP (VIP) addresses assigned to NetScaler load
balancing virtual servers.
– One or more subnets for the server-access (VPX-to-server) traffic, through which your
servers connect to VPX-owned subnet IP (SNIP) addresses. For more information about
NetScaler load balancing and virtual servers, virtual IP addresses (VIPs), and subnet IP
addresses (SNIPs), see:
– All subnets must be in the same availability zone.

Step 3: Add subnets.

When you used the VPC wizard, only one subnet was created. Depending on your requirement, you
might want to create additional subnets. For more information about how to create additional sub-
nets, see Adding a Subnet to Your VPC.

Step 4: Create security groups and security rules.

To control inbound and outbound traffic, create security groups and add rules to the groups. For more
information how to create groups and add rules, see Security Groups for Your VPC.

For NetScaler VPX instances, the EC2 wizard gives default security groups, which are generated by AWS
Marketplace and is based on recommended settings by Citrix. However, you can create additional
security groups based on your requirements.

Note

Port 22, 80, 443 to be opened on the Security group for SSH, HTTP, and HTTPS access respec-
tively.

Step 5: Add route tables.

Route table contains a set of rules, called routes, that are used to determine where network traffic is
directed. Each subnet in your VPC must be associated with a route table. For more information about
how to create a route table, see Route Tables.

Step 6: Create an internet gateway.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 672

NetScaler 12.0

An internet gateway serves two purposes: to provide a target in your VPC route tables for internet-
routable traffic, and to perform network address translation (NAT) for instances that have been as-
signed public IPv4 addresses.

Create an internet gateway for internet traffic. For more information about how to create an Internet
Gateway, see the section Attaching an Internet Gateway.

Step 7: Create a NetScaler VPX instance by using the AWS EC2 service.

To create a NetScaler VPX instance by using the AWS EC2 service, complete the following steps.

1. From the AWS dashboard, go to Compute > EC2 > Launch Instance > AWS Marketplace.

Before you click Launch Instance, ensure your region is correct by checking the note that appears
under Launch Instance.

2. In the Search AWS Marketplace bar, search with the keyword NetScaler VPX.

3. Select the version you want to deploy and then click Select. For the NetScaler VPX version, you the
following options:

• A licensed version
• NetScaler VPX Express appliance (This is a free virtual appliance, which is available from
NetScaler 12.0 56.20.)
• Bring your own device

The Launch Instance wizard starts. Follow the wizard to create an instance. The wizard prompts you
to:

• Choose Instance Type

• Configure Instance
• Add Storage
• Add Tags
• Configure Security Group
• Review

Step 8: Create and attach additional network interfaces.

Create two additional network interfaces for VIP and SNIP. For more information about how to create
additional network interfaces, see the Creating a Network Interface section.

After you’ve created the network interfaces, you must attach them to the VPX instance. Before at-
taching the interface, shut down the VPX instance, attach the interface, and power on the instance.
For more information about how to attach network interfaces, see the Attaching a Network Interface
When Launching an Instance section.

Step 9: Allocate and associate elastic IPs.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 673

NetScaler 12.0

If you assign a public IP address to an EC2 instance, it remains assigned only until the instance is
stopped. After that, the address is released back to the pool. When you restart the instance, a new
public IP address is assigned.

In contrast, an elastic IP (EIP) address remains assigned until the address is disassociated from an
instance.

Allocate and associate an elastic IP for the management NIC. For more information about how to allo-
cate and associate elastic IP addresses, see these topics:

• Allocating an Elastic IP Address

• Associating an Elastic IP Address with a Running Instance

These steps complete the procedure to create a NetScaler VPX instance on AWS. It can take a few min-
utes for the instance to be ready. Check that your instance has passed its status checks. You can view
this information in the Status Checks column on the Instances page.

Step 10: Connect to the VPX instance.

After you’ve created the VPX instance, you connect the instance by using the GUI and an SSH client.

• GUI

The following are the default administrator credentials to access a NetScaler VPX instance

User name: nsroot

Password: The default password for the nsroot account is set to the AWS instance-ID of the NetScaler
VPX instance.

• SSH client

From the AWS management console, select the NetScaler VPX instance and click Connect. Follow the
instructions given on the Connect to Your Instance page.

For more information about how to deploy a NetScaler VPX standalone instance on AWS by using the
AWS web console, see:

• Scenario: standalone instance

• How to configure a Citrix NetScaler VPX instance on AWS by using Citrix CloudFormation tem-
plate

Configure a NetScaler VPX instance by using the Citrix CloudFormation template

You can use the Citrix-provided CloudFormation template to automate VPX instance launch. The tem-
plate provides functionality to launch a single NetScaler VPX instance, or to create a high availability
environment with a pair of NetScaler VPX instances.

You can launch the template from AWS Marketplace or GitHub.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 674

NetScaler 12.0

The CloudFormation template requires an existing VPC environment, and it launches a VPX instance
with three elastic network interfaces (ENIs). Before you start the CloudFormation template, ensure
that you complete the following requirements:

• An AWS virtual private cloud (VPC)

• Three subnets within the VPC: one for management, one for client traffic, and one for back-end
servers
• An EC2 key pair to enable SSH access to the instance
• A security group with UDP 3003, TCP 3009-3010, HTTP, SSH ports open

See the “Deploy a NetScaler VPX Instance on AWS by Using the AWS Web Console” section or AWS
documentation for more information about how to complete the prerequisites.

Watch this video to learn about how to configure and launch a NetScaler VPX standalone instance by
using the Citrix CloudFormation template available in the AWS Marketplace.

Further, you configure and launch a NetScaler VPX Express standalone instance by using the Citrix
CloudFormation template available in GitHub:

https://github.com/citrix/netscaler-aws-cloudformation/tree/master/templates/express_single_
nic

An IAM role is not mandatory for a standalone deployment. However, Citrix recommends that you
create and attach an IAM role with the required privileges to the instance, for future need. The IAM
role ensures that the standalone instance is easily converted to a high availability node with SR-IOV,
when required.

For more information about the required privileges, see Configuring NetScaler VPX instances to Use
SR-IOV Network Interface.

Configure a NetScaler VPX instance by using the AWS CLI

You can use the AWS CLI to launch instances. For more information, see the AWS Command Line In-
terface Documentation.

1.
2. Citrix ADC
3. NetScaler 12.0

Download a NetScaler VPX license

September 20, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 675

NetScaler 12.0

Contributed by:
C

After the initial instance launch, NetScaler VPX for AWS requires a license. If you are bringing your own
license (BYOL), see the VPX Licensing Guide at http://support.citrix.com/article/CTX122426

You have to:

1. Use the licensing portal within MyCitrix to generate a valid license.

2. Upload the license to the instance.

If this is a paid marketplace instance, then you do not need to install a license. The correct feature set
and performance will activate automatically.

If you use a NetScaler VPX instance with a model number higher than VPX 5000, the network through-
put might not be the same as specified by the instance’s license. However, other features, such as SSL
throughput and SSL transactions per second, might improve.

5 Gbps network bandwidth is observed in c4.8xlarge instance type.

1.
2. Citrix ADC
3. NetScaler 12.0

Load balancing servers in different availability zones

September 20, 2018

Contributed by:
C

A VPX instance can be used to load balance servers running in the same availability zone, or in:

• A different availability zone (AZ) in the same AWS VPC

• A different AWS region
• AWS EC2 in a VPC

To enable a VPX instance to load balance servers running outside the AWS VPC that the
VPX instance is in, configure the instance to use EIPs to route traffic through the Internet gateway, as
follows:

1. Configure a SNIP on the NetScaler VPX instance by using the NetScaler CLI or the GUI.
2. Enable traffic to be routed out of the AZ, by creating a public facing subnet for the server-side
traffic.
3. Add an Internet gateway route to the routing table, using the AWS GUI console.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 676

NetScaler 12.0

4. Associate the routing table you just updated with the server-side subnet.
5. Associate an EIP with the server-side private IP address that is mapped to a NetScaler SNIP ad-
dress.

1.
2. Citrix ADC
3. NetScaler 12.0

Deploy a high availability pair on AWS

May 29, 2019

Contributed by:
C

You can configure two NetScaler VPX instances on AWS as a high-availability (HA) active-passive pair.
In this pair, one instance configured as the primary node and the other as the secondary node. The
primary node accepts connections and manages servers while the secondary node monitors the pri-
mary. If the primary node, for any reason, is unable to accept connections, the secondary node takes
over.

For more information on HA, see High availability.

Before you start your deployment, read the following topics:

• Prerequisites for the required IAM role privileges.

• Limitations and usage guidelines

The following figure shows an example of the HA deployment architecture for

NetScaler VPX instances on AWS.

Figure 1. A NetScaler VPX HA Pair on AWS

You can deploy a VPX HA pair on AWS in two ways:

• Create the instances with IAM role manually by using the AWS Management Console and then
configure the instances as an HA pair.
• Automate the HA deployment by using the Citrix CloudFormation template.

The CloudFormation template significantly decreases the number of steps involved for creating an HA
pair, and it automatically creates an IAM role. This section shows how to deploy a NetScaler VPX HA
(active-passive) pair by using the Citrix CloudFormation template.

Keep the following points in mind while deploying two NetScaler VPX instances as an HA pair.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 677

NetScaler 12.0

Points to note

• HA on AWS requires the primary node to have at least two ENIs - one for management and the
other for data traffic. And the secondary node to have one management ENI. However, for secu-
rity purposes, create three ENIs on the primary node, because this setup allows you to segregate
private and public network (recommended).
• The secondary node always has one ENI interface (for management) and the primary node can
have up to four ENIs.
• The NSIP addresses for each VPX instance in a high availability pair must be configured on the
default ENI of the instance.
• Amazon does not allow any broadcast/multicast packets in AWS. As a result, in an HA setup, data-
plane ENIs are migrated from the primary to the secondary VPX instance when the primary VPX
instance fails.
• Because the default (management) ENI cannot be moved to another VPX instance, do not use
the default ENI for client and server traffic (data-plane traffic).
• The message AWSCONFIG IOCTL NSAPI_HOTPLUG_INTF success output 0 in the /var/log/ns.log
indicates that the two data ENIs have successfully attached to the secondary instance (the new
primary).
• Failover might take up to 20 seconds due to the AWS detach/attach ENI mechanism.
• Upon failover, the failed instance always restarts.
• The heartbeat packets are received only on the management interface.
• The configuration file of the primary and secondary VPX instances is synchronized, including
the nsroot password. The nsroot password of the secondary node is set to that of the primary
node, after the HA configuration synchronizes.
• To access the AWS API servers, either the VPX instance must have a public IP address assigned
or routing must be set up correctly at VPC subnet level pointing to internet gateway of the VPC.
• Nameservers/DNS servers are configured at VPC level using DHCP options.
• The Citrix CloudFormation template does not create an HA setup between different availability
zones.
• The Citrix CloudFormation template does not create an INC mode.
• The AWS debug messages are available in the log file, /var/log/ns.log, on the VPX instance.

Deploy a high availability pair by using the Citrix CloudFormation template

Before start the CloudFormation template, ensure that you complete the following requirements:

• A VPC
• Three subnets within the VPC
• A security group with UDP 3003, TCP 3009–3010, HTTP, SSH ports open
• A key pair

© 1999-2018 Citrix Systems, Inc. All rights reserved. 678

NetScaler 12.0

Note

The Citrix CloudFormation template automatically creates an IAM role. Existing IAM roles do not
appear in the template.

To launch the Citrix CloudFormation template:

1. Log on to the AWS marketplace by using your AWS credentials.

2. In the search field, type NetScaler ADC VPX to search for the Citrix ADC AMI, and click Go.
3. On the search result page, click the desired Citrix ADC VPX offering.
4. Click the Pricing tab, to go to Pricing Information.
5. Select the region and Fulfillment Option as Netscaler AWS-VPX Cluster.
6. Click Continue to Subscribe.
7. Check the details in the Subscribe page and click Continue to Subscribe.
8. Select Fulfillment Option as CloudFormation Template.

1. Select Software Version and click Continue to Launch.

2. Under Choose Action, select Launch CloudFormation, and click Launch.

3. The Select Template page appears. Click Next.

4. The Specify Details appears. Enter the following details:

a. Type a Stack name. The name must be within 25 characters.

b. Under High Availability Configuration, select Yes from the menu for Create HA pair?.

c. Under Virtual Private Network Configuration:

• Select the VPC that you’ve already created for VPC ID.

• Type Remote SSH CIDR IP.

• Type Remote HTTP CIDR IP.

• Type Remote HTTPS CIDR IP.

• Select the key pair that you’ve already created from the menu for Key Pair.

d. Under Network Interface Configuration:

• Select Management Subnetwork, Client Subnetwork, and Server Subnetwork. Ensure

that you select the correct subnetworks you created within the VPC that you selected un-
der VPC ID in step c.

• Add Primary Management IP, Secondary Management IP, Client IP, and Server IP. The
IP addresses must belong to the same subnets of the respective subnetworks. Alterna-
tively, you can let the template assign the IP addresses automatically.

e. Under Other Parameters:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 679

NetScaler 12.0

• Select m4.large for Instant Type.

• Select default for Tenancy Type.

f. Click Next.

5. The Options page appears. (This page is optional.). Click Next.

6. The Review page appears. Take a moment to review the settings and make necessary changes
if necessary.

7. Select the I acknowledge that AWS CloudFormation might create IAM resources. check box,
and then click Create.

8. The CREATE-IN-PROGRESS status appears. Wait until the status is CREATE-COMPLETE. If the
status does not change to “COMPLETE,” check the Events tab for the reason of failure and recre-
ate the instance with proper configurations.

1. After an IAM resource is created, go to EC2 Management Console > Instances. The two VPX
instances created with an IAM role appear. The primary node is created with three private IP
addresses and three network interfaces.

The secondary node is created with one private IP address and one network interface.

Note

The secondary node is created with one interface by default in AWS. During failover, the interface
from the primary node gets attached to the secondary node (the new primary node) and gets
detached from the original primary node (the new secondary node).

1. Log on to the primary node with user name nsroot and the instance ID as the password. From
the GUI, go to System > High Availability. The NetScaler VPX HA pair appears.

Next, configure the HA pairing on both the instances. Configure the instance with three ENIs before
configuring HA on the instance with one ENI). Use the add HA node command, from within the VPX
CLI, or from the GUI.

add HA node <private IP of the first instance>

add HA node <private IP of the second instance>

After you run the “add HA node” commands, the two nodes form an HA pair, and configuration infor-
mation is synchronized between the two VPX instances.

Configuring SR-IOV on a high availability setup

Support for SR-IOV interfaces in a high availability setup is available from NetScaler release 12.0 57.19
onwards. For more information about how to configure SR-IOV, see Configuring NetScaler VPX in-
stances to Use SR-IOV Network Interface.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 680

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0

Add back-end AWS Auto Scaling service

January 6, 2019

Contributed by:
C

Efficient hosting of applications in a cloud involves easy and cost-effective management of resources
depending on the application demand. To meet increasing demand, you have to scale network re-
sources upward. Whether demand subsides, you need to scale down to avoid the unnecessary cost of
idle resources. To minimize the cost of running the application by deploying only as many instances
as are necessary during any given period of time, you have to constantly monitor traffic, memory and
CPU use, and so on. However, monitoring traffic manually is cumbersome. For the application envi-
ronment to scale up or down dynamically, you must automate the processes of monitoring traffic and
of scaling resources up and down whenever necessary.

Integrated with AWS Auto Scaling service, the NetScaler VPX instance provides the following advan-
tages:

• Load balance and management: Auto configures servers to scale up and scale down, depend-
ing on demand. The VPX instance auto detects Auto Scale groups in the back-end subnet and
allows user to select the Auto Scale groups to balance the load. All of this is done by auto con-
figuring the virtual and subnet IP addresses on the VPX instance.
• High availability: Detects Auto Scale groups that span multiple availability zones and load-
balance servers.
• Better network availability: The VPX instance supports:
– Back-end servers on different VPCs, by using VPC peering
– Back-end servers on same placement groups
– Back-end servers on different availability zones
• Graceful connection termination: Removes Auto Scale servers gracefully, avoiding loss of
client connections when scale-down activity occurs, by using the Graceful Timeout feature.

Diagram: AWS Auto Scaling Service with a NetScaler VPX Instance

The above diagram illustrates how the AWS Auto Scaling service works with a NetScaler VPX instance
(LB virtual server). For more information, see the following AWS topics.

• Auto Scaling groups

© 1999-2018 Citrix Systems, Inc. All rights reserved. 681

NetScaler 12.0

• CloudWatch
• Simple Notification Service (SNS)
• Simple Queue Service (Amazon SQS)

Before you begin

Before you start using Auto Scaling with your NetScaler VPX instance, you should complete the follow-
ing tasks.

1. Read the following topics:

• Prerequisites
• Limitation and usage guidelines

2. Create a NetScaler VPX instances on AWS according to your requirement.

• For more information about how to create a NetScaler VPX standalone instance, see Deploy a
NetScaler VPX standalone instance on AWS and Scenario: standalone instance
• For more information about how to deploy VPX instances in HA mode, see Deploy a high avail-
ability pair on AWS.

Citrix recommends CloudFormation template for creating NetScaler VPX instances on AWS.

Note

Citrix recommends you create three interfaces: one for management (NSIP), one for client-facing
LB virtual server (VIP), and one for subnet IP (NSIP).

3. Create an AWS Auto Scale group. If you don’t have an existing Auto Scaling configuration, you need
to:

a) Create a Launch Configuration

b) Create an Auto Scaling Group

c) Verify the Auto Scaling Group

For more information, see http://docs.aws.amazon.com/autoscaling/latest/userguide/GettingStartedTutorial.

html.

Add the AWS Auto Scaling service to a NetScaler VPX instance

You can add the Auto Scaling service to a VPX instance with a single click by using the GUI. Complete
these steps to add the Auto Scaling service to the VPX instance:

1. Log on to the VPX instance by using your credentials for nsroot.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 682

NetScaler 12.0

2. When you log on to the NetScaler VPX instance for the first time, you see the default Cloud Profile
page. Select the AWS auto scaling group from drop-down menu and click Create to create a cloud
profile. Click Skip if you want to create the cloud profile later.

Points to keep in mind while creating a Cloud Profile: By default the CloudFormation Template
creates and attaches the below IAM Role.

“Version”: “20120-17”,

“Statement”: [

“Action”: [

“ec2:DescribeInstances”,

“ec2:DescribeNetworkInterfaces”,

“ec2:DetachNetworkInterface”,

“ec2:AttachNetworkInterface”,

”ec2:StartInstances”,

”ec2:StopInstances”,

”ec2:RebootInstances”,

“autoscaling:*”,

”sns:*”,

“sqs:*”

“iam: SimulatePrincipalPolicy”

“iam: GetRole”

],

“Resource”: “*”,

“Effect”: “Allow”

Ensure the IAM Role of instance has proper permissions.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 683

NetScaler 12.0

• The virtual server IP address is autopopulated from the free IP address available to the
VPX instance. https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/MultipleIP.html#
ManageMultipleIP
• Auto Scale group is prepopulated from the Auto Scale group configured on your AWS ac-
count. http://docs.aws.amazon.com/autoscaling/latest/userguide/AutoScalingGroup.html.
• While selecting the Auto Scaling Group protocol and port, ensure your servers listen on those
protocol and ports and you bind the correct monitor in the service group. By default, TCP mon-
itor is used.
• For SSL Protocol type Autos Scaling, after you create the Cloud Profile the load balance virtual
server or service group will be down because of a missing certificate. You can bind the certificate
to the virtual server or service group manually.
• Select the Graceful Timeout option to remove Auto Scale servers gracefully. If this option is not
selected the server is the Auto Scale group is removed immediately after the load goes down,
which might cause service interruption for the existing connected clients. Selecting Graceful
and giving a timeout means in the event of scale down. The VPX instance does not remove the
server immediately but marks one of the servers for graceful deletion. During this period, the
instance does not allow new connections to this server. Existing connection are served till the
timeout occurs, and after timeout the VPX instance removes the server.

Figure: Default Cloud Profile page

3. After first time logon if you want to create Cloud Profile, on the GUI go to System > AWS > Cloud
Profile and click Add.

The Create Cloud Profile configuration page appears.

Cloud Profile creates a NetScaler load-balancing (LB) virtual server (virtual server) and a service group
with members (servers) as the servers of the Auto Scaling Group. Your back-end servers should be
reachable through the SNIP configured on the VPX instance.

Note

To view Auto Scale-related information in the AWS console, go to EC2 > Dashboard > Auto Scal-
ing > Auto Scaling Group.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure a NetScaler VPX instance to use SR-IOV network interface

January 6, 2019

© 1999-2018 Citrix Systems, Inc. All rights reserved. 684

NetScaler 12.0

Contributed by:
C
Note

Support for SR-IOV interfaces in a high availability setup is available from NetScaler release 12.0
57.19 onwards.

After you have created a NetScaler VPX instance on AWS, you can configure the virtual appliance to
use SR-IOV network interfaces, by using AWS CLI.

In all NetScaler VPX models, except NetScaler VPX AWS Marketplace Editions of 3G and 5G, SR-IOV is
not enabled in the default configuration of a network interface.

Before you start the configuration, read the following topics:

• Prerequisites
• Limitations and Usage Guidelines

This section includes the following topics:

• Change the Interface Type to SR-IOV

• Configure SR-IOV on a High Availability Setup

Change the interface type to SR-IOV

You can run the show interface summary command to check the default configuration of a network
interface.

Example 1: The following CLI screen capture shows the configuration of a network interface where
SR-IOV is enabled by default on NetScaler VPX AWS Marketplace Editions of 3G and 5G.

Example 2: The following CLI screen capture shows the default configuration of a network interface
where SR-IOV is not enabled.

For more information about changing the interface type to SR-IOV, see http://docs.aws.amazon.com/
AWSEC2/latest/UserGuide/sriov-networking.html

To change the interface type to SR-IOV

1. Shut down the NetScaler VPX instance running on AWS.

2. To enable SR-IOV on the network interface, type the following command in the AWS CLI.

$ aws ec2 modify-instance-attribute –instance-id <instance_id> –sriov-net-support simple

3. To check if SR-IOV has been enabled, type the following command in the AWS CLI.

$ aws ec2 describe-instance-attribute –instance-id <instance_id> –attribute sriovNetSupport

Example 3: Network interface type changed to SR-IOV, by using AWS CLI.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 685

NetScaler 12.0

If SR-IOV is not enabled, value for SriovNetSupport is absent.

Example 4: In the following example, SR-IOV support is not enabled.

3. Power on the VPX instance. To see the changed status of the network interface, type “show interface
summary” in CLI.

Example 5: The following screen capture shows the network interfaces with SR-IOV enabled. The
interfaces 10/1, 10/2, 10/3 are SR-IOV enabled.

These steps complete the procedure to configure VPX instances to use SR-IOV network interfaces.

Configure SR-IOV on a high availability setup

High availability is supported with SR-IOV interfaces from NetScaler release 12.0 build 57.19 onwards.

If the high availability setup was deployed manually or by using the Citrix CloudFormation template
for NetScaler version 12.0 56.20 and lower, the IAM role attached to the high availability setup must
have the following privileges:

• ec2:DescribeInstances
• ec2:DescribeNetworkInterfaces
• ec2:DetachNetworkInterface
• ec2:AttachNetworkInterface
• ec2:StartInstances
• ec2:StopInstances
• ec2:RebootInstances
• autoscaling:*
• sns:*
• sqs:*
• iam:SimulatePrincipalPolicy
• iam:GetRole

By default, the Citrix CloudFormation template for NetScaler version 12.0 57.19 automatically adds the
required privileges to the IAM role.

Note

A high availability setup with SR-IOV Interfaces take around 100 seconds of down time.

Related resources:

For more information about IAM roles, see AWS documentation.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 686

NetScaler 12.0

Upgrade a NetScaler VPX instance on AWS

December 5, 2018

Contributed by:
C

You can upgrade the EC2 instance type, throughput, software edition, and the system software of a
NetScaler VPX running on AWS. For certain types of upgrades, Citrix recommends using the High Avail-
ability Configuration method to minimize downtime.

Note:
• NetScaler software release 10.1.e-124.1308.e or later for a NetScaler VPX AMI (including both
utility license and customer license) does not support the M1 and M2 instance families.

• Because of changes in VPX instance support, downgrading from 10.1.e-124 or a later release
to 10.1.123.x or an earlier release is not supported.

• Most of the upgrades do not require the launch of a new AMI, and the upgrade can be done on
the current NetScaler AMI instance. If you do want to upgrade to a new NetScaler AMI instance,
use the high availability configuration method.

Change the EC2 instance type of a NetScaler VPX instance on AWS

If your NetScaler VPX instances are running release 10.1.e-124.1308.e or later, you can change the EC2
instance type from the AWS console as follows:

1. Stop the VPX instance.

2. Change the EC2 instance type from the AWS console.
3. Start the instance.

You can also use the above procedure to change the EC2 instance type for a release, earlier than 10.1.e-
124.1308.e, unless you want to change the instance type to M3. In that case, you must first follow the
standard NetScaler upgrade procedure, at , to upgrade the NetScaler software to 10.1.e-124 or a later
release, and then follow the above steps.

Upgrade the throughput or software edition of a NetScaler VPX instance on AWS

To upgrade the software edition (for example, to upgrade from Standard to Platinum edition) or
throughput (for example, to upgrade from 200 mbps to 1000mbps), the method depends on the
instance’s license.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 687

NetScaler 12.0

Using a customer license (Bring-Your-Own-License)

If you are using a customer license, you can purchase and download the new license from the Citrix
Licensing portal (MyCitrix), and then install the license on the VPX instance. For more information
about downloading and installing a license from the MyCitrix portal, see the VPX Licensing Guide.

Using a utility license (Utility license with hourly fee)

AWS does not support direct upgrades for fee-based instances. To upgrade the software edition or
throughput of a fee based NetScaler VPX instance, launch a new AMI with the desired license and ca-
pacity and migrate the older instance configuration to the new instance. This can be achieved by using
a NetScaler high availability configuration as described in Upgrade to a new NetScaler AMI instance
by using a NetScaler high availability configuration subsection in this page.

Upgrade the system software of a NetScaler VPX instance on AWS

If you need to upgrade a VPX instance running 10.1.e-124.1308.e or a later release, follow the standard
NetScaler upgrade procedure at .

If you need to upgrade a VPX instance running a release older than 10.1.e-124.1308.e to 10.1.e-124.1308.e
or a later release, first upgrade the system software, and then change the instance type to M3 as fol-
lows:

1. Stop the VPX instance.

2. Change the EC2 instance type from the AWS console.
3. Start the instance.

Upgrade to a new NetScaler AMI instance by using a NetScaler high availability

configuration

To use the high availability method of upgrading to a new NetScaler AMI instance, perform the follow-
ing tasks:

• Create a new instance with the desired EC2 instance type, software edition, throughput, or soft-
ware release from the AWS marketplace.
• Configure high availability between the old instance (to be upgraded) and the new instance.
After high availability is configured between the old and the new instance, configuration from
the old instance is synchronized to the new instance.
• Force an HA failover from the old instance to the new instance. As a result, the new instance
becomes primary and starts receiving traffic.
• Stop, and reconfigure or remove the old instance from AWS.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 688

NetScaler 12.0

Prerequisites and points to consider

• Ensure you understand how high availability works between two NetScaler VPX instances on
AWS. For more information about high availability configuration between two NetScaler VPX
instances on AWS, see Deploy a high availability pair on AWS.
• You must create the new instance in the same availability zone as the old instance, having the
exact same security group and subnet.
• High availability setup requires access and secret keys associated with the user’s AWS Identity
and Access Management (IAM) account for both instances. If the correct key information is not
used when creating VPX instances, the HA setup fails. For more information about creating an
IAM account for a VPX instance, see Prerequisites.
– You must use the EC2 console to create the new instance. You cannot use the AWS 1-click
launch, because it does not accept the access and secret keys as the input.
– The new instance should have only one ENI interface.

To upgrade a NetScaler VPX Instance by using a high availability configuration, follow these steps:

1. Configure high availability between the old and the new instance. To configure high availability
between two NetScaler VPX instances, at the command prompt of each intance, type:

• add ha node <nodeID> <IPaddress of the node to be added>

• save config

Example:

At the command prompt of the old instance, type:

1 add ha node 30 192.0.2.30

2 Done

At the command prompt of the new instance, type:

1 add ha node 10 192.0.2.10

2 Done

Note the following:

• In the HA setup, the old instance is the primary node and the new instance is the secondary
node.
• The NSIP IP address is not copied from the old instance to the new instance. Therefore, after the
upgrade, your new instance has a different management IP address from the previous one.
• The nsroot account password of the new instance is set to that of the old instance after HA syn-
chronization.

For more information about high availability configuration between two NetScaler VPX instances on
AWS, see Deploy a high availability pair on AWS.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 689

NetScaler 12.0

2. Force an HA failover. To force a failover in a high availability configuration, at the command prompt
of either of the instances, type:

1 force HA failover

As the result of forcing a failover, the ENIs of the old instance are migrated to the new instance and
traffic flows through the new instance (the new primary node). The old instance (the new secondary
node) restarts.
If the following warning message appears, type N to abort the operation:

1 [WARNING]:Force Failover may cause configuration loss, peer health not

optimum. Reason(s):
2 HA version mismatch
3 HA heartbeats not seen on some interfaces
4 Please confirm whether you want force-failover (Y/N)?

The warning message appears because the system software of the two VPX instances is not HA com-
patible. As a result, the configuration of the old instance cannot be automatically synced to the new
instance during a forced failover.
Following is the workaround for this issue:

1/. At the NetScaler shell prompt of the old instance, type the following command to create a backup
of the configuration file (ns.conf):
copy /nsconfig/ns.conf to /nsconfig/ns.conf.bkp

2. Remove the following line from the backup configuration file (ns.conf.bkp):

• set ns config -IPAddress <IP> -netmask <MASK>

For example, set ns config -IPAddress 192.0.2.10 -netmask 255.255.255.0

3. Copy the old instance’s backup configuration file (ns.conf.bkp) to the /nsconfig directory of the the
new instance.

4. At the NetScaler shell prompt of the new instance, type the following command to load the old
instance’s configuration file (ns.conf.bkp) on the new instance:

• batch -f /nsconfig/ns.conf.bkp

5. Save the configuration on the new instance.

• Save conifg

6. At the command prompt of either of the nodes, type the following command to force a failover, and
then type Y for the warning message to confirm the force failover operation:

• force ha failover

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 690

NetScaler 12.0

1 > force ha failover

2
3 WARNING]:Force Failover may cause configuration loss, peer health not
optimum.
4 Reason(s):
5 HA version mismatch
6 HA heartbeats not seen on some interfaces
7 Please confirm whether you want force-failover (Y/N)? Y

3. Remove the HA configuration, so that the two instances are no longer in an HA configuration. First
remove the HA configuration from the secondary node and then remove the HA configuration from
the primary node.

To remove an HA configuration between two NetScaler VPX instances, at the command prompt of each
instance, type:

1 > remove ha node \<nodeID\>

2 > save config

For more information about high availability configuration between two VPX instances on AWS, see
Deploy a high availability pair on AWS.

Example:

At the command prompt of the old instance (new secondary node), type:

1 > remove ha node 30

2 Done
3 > save config
4 Done

At the command prompt of the new instance (new primary node), type:

1 > remove ha node 10

2 Done
3 > save config
4 Done

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 691

NetScaler 12.0

Troubleshoot a VPX instance on AWS

January 6, 2019

Contributed by:
C

Amazon does not provide console access to a NetScaler VPX instance. To troubleshoot, you have to
use the AWS GUI to view the activity log. You can debug only if the network is connected. To view an
instance’s system log, right-click the instance and select system log.

Citrix provides support for fee based NetScaler VPX instances (utility license with hourly fee) on AWS.
To file a support case, find your AWS account number and support PIN code, and call Citrix support.
You will also be asked for your name and email address. To find the support PIN, log on to the VPX GUI
and navigate to the System page.

Here is an example of a system page showing the support PIN.

1.
2. Citrix ADC
3. NetScaler 12.0

Deploy a NetScaler VPX instance on Microsoft Azure

January 6, 2019

Contributed by:
C

Microsoft Azure Resource Manager (ARM) is a management framework that allows administrators to
deploy, manage, and monitor Azure resources. Azure Resource Manager can handle these tasks as a
group, rather than individually, in a single operation.

The NetScaler VPX virtual appliance is available as an image in the Microsoft Azure Marketplace and
GitHub. For more information, see the GitHub repository for Citrix NetScaler solution templates for
deploying NetScaler VPX instances in Microsoft Azure Cloud Services.

When you deploy NetScaler VPX on Microsoft Azure Resource Manager (ARM), you can leverage the
Azure cloud computing capabilities and use NetScaler load balancing and traffic management fea-
tures for your business needs. You can deploy NetScaler VPX instances on Azure Resource Manager
either as standalone instances or as high availability pairs in active-active or active-standby modes.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 692

NetScaler 12.0

This document assumes that you are familiar with Azure terminology and network details. For infor-
mation, see Azure terminology.

This document also assumes that you have basic knowledge of a NetScaler appliance. For detailed
information the NetScaler appliance, see:

• NetScaler
• NetScaler Gateway

For information about NetScaler Gateway configuration for Citrix XenApp and XenDesktop
in Azure cloud, see https://www.citrix.com/content/dam/citrix/en_us/documents/products-
solutions/netscaler-vpx-deployment-with-xendesktop-and-xenapp-on-microsoft-azure.pdf.

Note

The Citrix XenApp and XenDesktop NetScaler Gateway configuration is based on the Azure Ser-
vice Management mode and not on the Azure Resource Management mode.

Network architecture

In ARM, a NetScaler VPX virtual machine (VM) resides in a virtual network. A virtual Network Interface
Card (NIC) is created on each NetScaler VM. The network security group (NSG) configured in the virtual
network is bound to the NIC, and together they control the traffic flowing into the VM and out of the
VM.

The NSG forwards the requests to the NetScaler VPX instance, and the VPX instance sends them to the
servers. The response from a server follows the same path in reverse. The NSG can be configured to
control a single VPX VM, or, with subnets and virtual networks, can control traffic in multiple VPX VM
deployment.

The NIC contains network configuration details such as the virtual network, subnets, internal IP ad-
dress, and Public IP address.

While on ARM, it is good to know the following IP addresses that are used to access the VMs deployed
with a single NIC and a single IP address:

• Public IP (PIP) address is the internet-facing IP address configured directly on the virtual NIC of
the NetScaler VM. This allows you to directly access a VM from the external network.
• NetScaler IP (NSIP) address is internal IP address configured on the VM. It is non-routable.
• Virtual IP address (VIP) is configured by using the NSIP and a port number. Clients access
NetScaler services through the PIP address, and when the request reaches the NIC of the
NetScaler VPX VM or the Azure load balancer, the VIP gets translated to internal IP (NSIP) and
internal port number.
• Internal IP address is the private internal IP address of the VM from the virtual network’s address
space pool. This IP address cannot be reached from the external network. This IP address is by

© 1999-2018 Citrix Systems, Inc. All rights reserved. 693

NetScaler 12.0

default dynamic unless you set it to static. Traffic from the internet is routed to this address
according to the rules created on the NSG. The NSG works with the NIC to selectively send the
right type of traffic to the right port on the NIC, which depends on the services configured on
the VM.

The following figure shows how traffic flows from a client to a server through a NetScaler VPX instance
provisioned in ARM.

How a NetScaler VPX instance works on Azure

In an on-premises deployment, a NetScaler VPX instance requires at least three IP addresses:

• Management IP address, called the NetScaler IP (NSIP) address

• Subnet IP (SNIP) address for communicating with the server farm
• Virtual server IP (VIP) address for accepting client requests

In an Azure deployment, you can provision a NetScaler VPX instance on Azure in two ways:

• With a single-IP architecture

• With a multi-NIC, multi-IP architecture
Note

VPX virtual appliances can be deployed on any instance type that has two or more cores and
more than 2 GB memory.

The following image illustrates how multiple IP addresses are used to perform the functions of NSIP,
SNIP, and VIP, with a single NIC in a standalone deployment. According to your requirement, you can
configure multiple NICs with different IP addresses.

For more information about NetScaler multi-NIC, multi-IP deployment on Azure, see the following
links:

• Configure multiple IP addresses for a NetScaler standalone instance

• Configure multiple IP addresses for a NetScaler VPX instance in standalone mode by using Pow-
erShell commands

The following image illustrates how a single IP address is used to perform the functions of NSIP, SNIP,
and VIP.
Note

The single IP mode is available only in Azure deployments. This mode is not available for a
NetScaler VPX instance on your premises, on AWS, or in other type of deployment.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 694

NetScaler 12.0

Traffic flow through port address translation

In an Azure deployment, when you provision the NetScaler VPX instance as a virtual machine (VM),
Azure assigns a public IP address and an internal IP address (nonroutable) to the NetScaler VPX in-
stance. Inbound and outbound rules are defined on the NSG for the VPX instance, along with a public
port and a private port for each rule defined. The VPX instance listens on the internal IP address and
private port.

Any external request is received on the virtual NIC of the NetScaler VPX VM. The NIC is bound to the
NSG, which specifies the private IP and private port combination into which to translate the request’s
destination address and port (the public IP address and port). ARM performs port address translation
(PAT) to map the public IP address and port to the internal IP address and private port of the NetScaler
VPX instance, and forwards the traffic to the virtual machine.

The following figure shows how Azure performs port address translation to direct traffic to the
NetScaler internal IP address and private port.

In this example, the Public IP address assigned to the VM is 140.x.x.x, and the internal IP address is
10.x.x.x. When the inbound and outbound rules are defined, public HTTP port 80 is defined as the
port on which the client requests are received, and a corresponding private port, 10080, is defined as
the port on which the NetScaler VPX instance listens. The client request is received on the Public IP
address 140.x.x.x at port 80. Azure performs port address translation to map this address and port to
internal IP address 10.x.x.x on private port 10080 and forwards the client request.

For information about port usage guidelines while, see the Port usage guidelines section.

For information about NSG and access control lists, see What is a Network Security Group?

Traffic flow through network address translation

You can also request a public IP (PIP) address for your NetScaler VPX instance (instance level). If you
use this direct PIP at the VM level, you need not define inbound and outbound rules to intercept the
network traffic. The incoming request from the Internet is received on the VM directly. Azure per-
forms network address translation (NAT) and forwards the traffic to the internal IP address of the VPX
instance.

The following figure shows how Azure performs network address translation to map the NetScaler
internal IP address.

In this example, the Public IP assigned to the NSG is 140.x.x.x and the internal IP address is 10.x.x.x.
When the inbound and outbound rules are defined, public HTTP port 80 is defined as the port on
which the client requests are received, and a corresponding private port, 10080, is defined as the
port on which the NetScaler VPX instance listens. The client request is received on the Public IP ad-

© 1999-2018 Citrix Systems, Inc. All rights reserved. 695

NetScaler 12.0

dress (140.x.x.x). Azure performs network address translation to map the PIP to the internal IP address
10.x.x.x on port 10080, and forwards the client request.

Note

NetScaler VPX VMs in high availability are controlled by external or internal load balancers that
have inbound rules defined on them to control the load balancing traffic. The external traffic is
first intercepted by these load balancers and the traffic is diverted according to the load balancing
rules configured, which has back-end pools, NAT rules, and health probes defined on the load
balancers.

Port usage guidelines

You can configure more inbound and outbound rules n NSG while creating the NetScaler VPX instance
or after the virtual machine is provisioned. Each inbound and outbound rule is associated with a
public port and a private port.

Before configuring NSG rules, note the following guidelines regarding the port numbers you can use:

1. The NetScaler VPX instance reserves the following ports. You cannot define these as private ports
when using the Public IP address for requests from the internet.
Ports 21, 22, 80, 443, 8080, 67, 161, 179, 500, 520, 3003, 3008, 3009, 3010, 3011, 4001, 5061, 9000, 7000.
However, if you want internet-facing services such as the VIP to use a standard port (for example,
port 443) you have to create port mapping by using the NSG. The standard port is then mapped to a
different port that is configured on the NetScaler for this VIP service.
For example, a VIP service might be running on port 8443 on the VPX instance but be mapped to public
port 443. So, when the user accesses port 443 through the Public IP, the request is directed to private
port 8443.

2. Public IP address does not support protocols in which port mapping is opened dynamically, such
as passive FTP or ALG.

3. High availability does not work for traffic that uses a public IP address (PIP) associated with a VPX
instance, instead of a PIP configured on the Azure load balancer. For more information, see Configure
a high-availability setup with a single IP address and a single NIC.

4. In a NetScaler Gateway deployment, you need not configure a SNIP address, because the NSIP can
be used as a SNIP when no SNIP is configured.
You must configure the VIP address by using the NSIP address and some nonstandard port number.
For call-back configuration on the back-end server, the VIP port number has to be specified along with
the VIP URL (for example, url:port).

© 1999-2018 Citrix Systems, Inc. All rights reserved. 696

NetScaler 12.0

Note

In Azure Resource Manager, a NetScaler VPX instance is associated with two IP addresses - a pub-
lic IP address (PIP) and an internal IP address. While the external traffic connects to the PIP,
the internal IP address or the NSIP is non-routable. To configure VIP in VPX, use the internal IP
address (NSIP) and any of the free ports available. Do not use the PIP to configure VIP.

For example, if NSIP of a NetScaler VPX instance is 10.1.0.3 and an available free port is 10022,
then you can configure VIP by providing the 10.1.0.3:10022 (NSIP address+port) combination.

NetScaler VPX licensing

A NetScaler VPX instance on Azure requires a license. The following licensing options are available for
NetScaler VPX instances running on Azure.

• Subscription-based licensing: NetScaler VPX appliances are available as paid instances on

Azure Marketplace. Subscription based licensing is a pay-as-you-go option. Users are charged
hourly. The following VPX models and license types are available on Azure Marketplace.

VPX model License Type

VPX10 Standard, Enterprise, Platinum

VPX200 Standard, Enterprise, Platinum
VPX1000 Standard, Enterprise, Platinum
VPX3000 Standard, Enterprise, Platinium

• Bring your own license (BYOL): If you bring your own license (BYOL), see the VPX Licensing
Guide at http://support.citrix.com/article/CTX122426. You have to:
– Use the licensing portal within MyCitrix to generate a valid license.
– Upload the license to the instance.
• NetScaler VPX Check-In/Check-Out licensing: For more information, see NetScaler VPX Check-
In/Check-Out Licensing.

Starting with NetScaler release 12.0 56.20, VPX Express for on-premises and cloud deployments does
not require a license file. For more information on NetScaler VPX Express see the “NetScaler VPX Ex-
press license” section in NetScaler Licensing Overview.

Note

Regardless of the subscription-based hourly license bought from Azure Marketplace, in rare
cases, the NetScaler VPX instance deployed on Azure might come up with a default NetScaler

© 1999-2018 Citrix Systems, Inc. All rights reserved. 697

NetScaler 12.0

license. This happens due to issues with Azure Instance Metadata Service (IMDS).

Do a warm restart before making any configuration change on the NetScaler VPX instance, to
enable the correct NetScaler VPX license.

Limitations

Running the NetScaler VPX load balancing solution on ARM imposes the following limitations:

1. The Azure architecture does not accommodate support for the following NetScaler features:

• Clustering
• IPv6
• Gratuitous ARP (GARP)
• L2 Mode
• Tagged VLAN
• Dynamic Routing
• Virtual MAC (VMAC)
• USIP
• Jumbo Frames

2. If you expect that you might have to shut down and temporarily deallocate the NetScaler VPX virtual
machine at any time, assign a static Internal IP address while creating the virtual machine. If you do
not assign a static internal IP address, Azure might assign the virtual machine a different IP address
each time it restarts, and the virtual machine might become inaccessible.

3. In an Azure deployment, only the following NetScaler VPX models are supported: VPX 10, VPX 200,
VPX 1000, and VPX 3000. For for information, see the NetScaler VPX Data Sheet.

If you use a NetScaler VPX instance with a model number higher than VPX 3000, the network through-
put might not be the same as specified by the instance’s license. However, other features, such as SSL
throughput and SSL transactions per second, might improve.

4. The “deployment ID” that is generated by Azure during virtual machine provisioning is not visible
to the user in ARM. You cannot use the deployment ID to deploy NetScaler VPX appliance on ARM.

5. The NetScaler VPX instance supports 20 Mb/s throughput and standard edition features when it’s
initialized.

6. For a XenApp and XenDesktop deployment, a VPN virtual server on a VPX instance can be configured
in the following modes:

• Basic mode, where the ICAOnly VPN virtual server parameter is set to ON. The Basic mode works
fully on an unlicensed NetScaler VPX instance.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 698

NetScaler 12.0

• Smart-Access mode, where the ICAOnly VPN virtual server parameter is set to OFF. The Smart-
Access mode works for only 5 NetScaler AAA session users on an unlicensed NetScaler VPX in-
stance.
Note

To configure the Smart Control feature, you must apply a Platinum license to the NetScaler VPX
instance.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure a NetScaler VPX standalone instance

January 6, 2019

Contributed by:
C

You can provision a single NetScaler VPX instance in Azure Resource Manager (ARM) portal in a stan-
dalone mode by creating the virtual machine and configuring other resources.

Before you begin

Ensure that you have the following:

• A Microsoft Azure user account

• Access to Microsoft Azure Resource Manager
• Microsoft Azure SDK
• Microsoft Azure PowerShell

On the Microsoft Azure Portal page, log on to the Azure Resource Manager portal by providing your
user name and password.

Note

In ARM portal, clicking an option in one pane opens a new pane to the right. Navigate from one
pane to another to configure your device.

Summary of configuration steps

1. Configure a resource group

© 1999-2018 Citrix Systems, Inc. All rights reserved. 699

NetScaler 12.0

2. Configure a network security group

3. Configure virtual network and its subnets
4. Configure a storage account
5. Configure an availability set
6. Configure a NetScaler VPX instance.

Configure a resource group

Create a new resource group that is a container for all your resources. Use the resource group to de-
ploy, manage, and monitor your resources as a group.

1. Click New > Management > Resource group.

2. In the Resource group pane, enter the following details:
• Resource group name
• Resource group location
3. Click Create.

Configure a network security group

Create a network security group (NSG) to assign inbound and outbound rules to control the incoming
and outgoing traffic within the virtual network. NSG allows you to define security rules for a single
virtual machine and also to define security rules for a virtual network subnet.

1. Click New > Networking > Network security group.

2. In the Create network security group pane, enter the following details, and then click Create.
• Name - type a name for the security group
• Resource group - select the resource group from the drop-down list

Note

Ensure that you have selected the correct location. The list of resources that appear in the drop-
down list is different for different locations.

Configure a virtual network and subnets

Virtual networks in ARM provide a layer of security and isolation to your services. VMs and services
that are part of the same virtual network can access each other.

For these steps to create a virtual network and subnets.

1. Click New > Networking > Virtual Network.

2. In the Virtual Network pane, ensure the deployment mode is Resource Manager and click Create.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 700

NetScaler 12.0

3. In the Create virtual network pane, enter the following values, and then click Create.

• Name of the virtual network

• Address space - type the reserved IP address block for the virtual network
• Subnet - type the name of the first subnet (you will create the second subnet later in this step)
• Subnet address range - type the reserved IP address block of the subnet
• Resource group - select the resource group created earlier from the drop-down list

Configure the second subnet

1. Select the newly created virtual network from All resources pane and in the Settings pane, click
Subnets.

2. Click +Subnet and create the second subnet by entering the following details.

• Name of the second subnet

• Address range - type the reserved IP address block of the second subnet
• Network security group - select the NSG from the drop-down list

3. Click Create.

Configure a storage account

The ARM IaaS infrastructure storage includes all services where we can store data in the form of blobs,
tables, queues, and files. You can also create applications using these forms of storage data in ARM.

Create a storage account to store all your data.

1. Click +New > Data + Storage > Storage account.

2. In the Create storage account pane, enter the following details:
• Name of the account
• Deployment mode - make sure to select Resource Manager
• Account kind - select General purpose from the drop-down list
• Replication - select Locally redundant storage from the drop-down list
• Resource group - select the newly created resource group from the drop-down list
3. Click Create.

Configure an availability set

An availability set guarantees that at least one VM is kept up and running in case of planned or un-
planned maintenance. Two or more VMs under the same ‘availability set’ are placed on different fault
domains to achieve redundant services.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 701

NetScaler 12.0

1. Click +New.
2. Click See all in the MARKETPLACE pane and click Virtual Machines.
3. Search for availability set, and then select Availability set entity from the list displayed.

4. Click Create, and in the Create availability set pane, enter the following details:

• Name of the set

• Resource group - select the newly created resource group from the drop-down list

5. Click Create.

Configure a NetScaler VPX instance

Create an instance of NetScaler VPX in the virtual network. Obtain the NetScaler VPX image from
the Azure marketplace, and then use the Azure Resource Manager portal to create a NetScaler VPX
instance.

Before you begin creating the NetScaler VPX instance, make sure that you have created a virtual net-
work with required subnets in which the instance will reside. You can create virtual networks during
VM provisioning, but without the flexibility to create different subnets. For information about cre-
ating virtual networks, see http://azure.microsoft.com/en-us/documentation/articles/create-virtual-
network/.

Optionally, configure DNS server and VPN connectivity that allows a virtual machine to access Internet
resources.
Note

Citrix recommends that you create resource group, network security group, virtual network, and
other entities before you provision the NetScaler VPX VM, so that the network information is avail-
able during provisioning.

1. Click +New > Networking.

2. Click See All and in the Networking pane, click NetScaler VPX Bring Your Own License.

As a quick way to find any entity on ARM portal, you can also type the name of the entity in the
Azure Marketplace search box and press <Enter>. Type NetScaler in the search box to find the Citrix
NetScaler images.

Note

Ensure to select the latest image. Your Citrix NetScaler image might have the release number in
the name.

3. On the NetScaler VPX Bring Your Own License page, from the drop-down list, select Resource
Manager and click Create.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 702

NetScaler 12.0

4. In the Create virtual machine pane, specify the required values in each section to create a virtual
machine. Click OK in each section to save your configuration.

Basic:

• Name - specify a name for the NetScaler VPX instance

• VM disk type - select SSD (default value) or HDD from the drop-down menu
• User name and Password - specify a user name and password to access the resources in the
resource group that you have created
• Authentication Type - select SSH Public Key or Password
• Resource group - select the resource group you have created from the drop-down list

You can create a resource group here, but Citrix recommends that you create a resource group from
Resource groups in Azure Resource Manager and then select the group from the drop-down list.

Size:

Depending on the VM disk type, SDD or HDD, you selected in Basic settings, the disk sizes are dis-
played.

• Select a disk size according to your requirement and click Select.

Settings:

• Select the default (Standard) disk type

• Storage account - select the storage account
• Virtual network - select the virtual network
• Subnet - set the subnet address
• Public IP address - select the type of IP address assignment
• Network security group - select the security group that you have created. Ensure that inbound
and outbound rules are configured in the security group.
• Availability Set - select the availability set from the drop-down box

Summary:

The configuration settings are validated and the Summary page displays the result of the validation.
If the validation fails, the Summary page displays the reason of the failure. Go back to the particular
section and make changes as required. If the validation passes, click OK.

Buy:

Review the offer details and legal terms on the Purchase page and click Purchase.

For high availability deployment, create two independent instances of NetScaler VPX in the same avail-
ability set and in the same resource group to deploy them in active-standby configuration.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 703

NetScaler 12.0

Configure multiple IP addresses for a NetScaler VPX standalone instance

January 6, 2019

Contributed by:
C

This section explains how to configure a standalone NetScaler VPX instance with multiple IP ad-
dresses, in Azure Resource Manager (ARM). The VPX instance can have one or more NIC attached to it,
and each NIC can have one or more static or dynamic public and private IP addresses assigned to it.
You can assign multiple IP addresses as NSIP, VIP, SNIP, and so on.

For more information, see the Azure documentation Assign multiple IP addresses to virtual machines
using the Azure portal.

If you want to use PowerShell commands, see Configuring multiple IP addresses for a NetScaler VPX
instance in standalone mode by using PowerShell commands.

Use case

In this use case, a standalone NetScaler VPX appliance is configured with a single NIC that is connected
to a virtual network (VNET). The NIC is associated with three IP configurations (ipconfig), each servers
a different purpose - as shown in the table.

IPconfig Assocaited with Purpose

ipconfig1 Static public IP address; static Serves management traffic

private IP address
ipconfig2 Static public IP address; static Serves client-side traffic
private address
ipconfig3 Static private IP address Communicates with back-end
servers

Note

IPConfig-3 is not associated with any public IP address.

Diagram: Topology

Here is the visual representation of the use case.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 704

NetScaler 12.0

Note

In a multi-NIC, multi-IP Azure NetScaler VPX deployment, the private IP associated with the pri-
mary (first) IPConfig of the primary (first) NIC is automatically added as the management NSIP of
the appliance. The remaining private IP addresses associated with IPConfigs need to be added
in the VPX instance as a VIP or SNIP by using the “add ns ip” command, according to your require-
ment.

Before you begin

Before you begin, create a VPX instance by following the steps given at this link:
Configure a NetScaler VPX standalone instance
For this use case, the NSDoc0330VM VPX instance is created.
Procedure to configure multiple IP addresses for a NetScaler VPX instance in standalone mode.
For configuring multiple IP addresses for a NetScaler VPX appliance in standalone mode:
1. Add IP addresses to the VM
2. Configure NetScaler -owned IP addresses
Step 1: Add IP addresses to the VM
1. In the portal, click More services > type virtual machines in the filter box, and then click Virtual
machines.
2. In the Virtual machines blade, click the VM you want to add IP addresses to. Click Network inter-
faces in the virtual machine blade that appears, and then select the network interface.
In the blade that appears for the NIC you selected, click IP configurations. The existing IP configu-
ration that was assigned when you created the VM, ipconfig1, is displayed. For this use case, make
sure the IP addresses associated with ipconfig1 are static. Next, create two more IP configurations:
ipconfig2 (VIP) and ipconfig3 (SNIP).
To create additional ipconfigs, create Add.
In the Add IP configuration window, enter a Name, specify allocation method as Static, enter an IP
address (192.0.0.5 for this use case), and enable Public IP address.
Note

Before adding a static private IP address, check for IP address availability and make sure the IP
address belongs to the same subnet to which the NIC is attached.

Next, click Configure required settings to create a static public IP addresss for ipconfig2.
By default, public IPs are dynamic. To make sure that the VM always uses the same public IP address,
create a static Public IP.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 705

NetScaler 12.0

In the Create public IP address blade, add a Name, under Assignment click Static. And then click OK.

Note

Even when you set the allocation method to static, you cannot specify the actual IP address as-
signed to the public IP resource. Instead, it gets allocated from a pool of available IP addresses
in the Azure location the resource is created in.

Follow the steps to add one more IP configuration for ipconfig3. Public IP is not mandatory.

Step 2: Configure NetScaler-owned IP addresses

Configure the NetScaler-owned IP addresses by using the GUI or the command “add ns ip.” For more
information, see Configuring NetScaler-Owned IP Addresses.

You’ve now configured multiple IP addresses for a NetScaler VPX instance in standalone mode.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure a high-availability setup with multiple IP addresses and NICs

January 6, 2019

Contributed by:
C

You can deploy a pair of NetScaler virtual appliances with multiple NICs in an active-passive high avail-
ability (HA) setup on Azure. Each NIC can contain multiple IP addresses.

An active-passive deployment requires:

• An HA Independent Network Configuration (INC) configuration

• The Azure Load Balancer (ALB) in Direct Server Return (DSR) mode
All traffic goes through the primary node. The secondary node remains in standby mode until
the primary node fails.

Note

For a Citrix VPX high availability deployment on Azure cloud to work, you need a floating public
IP (PIP) that can be moved between the two VPX nodes. The Azure Load Balancer (ALB) provides
that floating PIP, which is moved to the second node automatically in the event of a failover.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 706

NetScaler 12.0

Diagram: Example of a high availability deployment architecture, using Azure Availability Set

In an active-passive deployment, the ALB floating public IP (PIP) addresses are added as the VIP ad-
dresses in each VPX node. In HA-INC configuration, the VIP addresses are floating and SNIP addresses
are instance specific.

ALB monitors each VPX instances by sending health probe at every 5 seconds and redirects traffic to
that instance only that sends health probes response on regular interval. So in an HA setup, the pri-
mary node responds to health probes and secondary does not. If the primary instance misses two
consecutive health probes, ALB does not redirect traffic to that instance. On failover, the new primary
starts responding to health probes and the ALB redirects traffic to it. The standard VPX high availabil-
ity failover time is three seconds. The total failover time that might take for traffic switching can be
maximum of 13 seconds.

You can deploy a VPX pair in active-passive high availability mode in two ways by using:

• NetScaler VPX standard high availability template: use this option to configure an HA pair
with the default option of three subnets and six NICs.
• Windows PowerShell commands: use this option to configure an HA pair according to your
subnet and NIC requirements.

This topic describes how to deploy a VPX pair in active-passive HA setup by using the Citrix template.
If you want to use PowerShell commands, see Configuring an HA Setup with Multiple IP Addresses and
NICs by Using PowerShell Commands.

Configure HA-INC nodes by using the Citrix high availability template

You can quickly and efficiently deploy a pair of VPX instances in HA-INC mode by using the standard
template. The template creates two nodes, with three subnets and six NICs. The subnets are for
management, client, and server-side traffic, and each subnet has two NICs for both the VPX instances.

You can get the NetScaler 12.0 HA Pair template at the Azure Marketplace.

Complete the following steps to launch the template and deploy a high availability VPX pair, by using
Azure Availability Sets.

1. From Azure Marketplace, select and initiate the Citrix solution template. The template appears.

2. Ensure deployment type is Resource Manager and select Create.

3. The Basics page appears. Create a Resource Group and select OK.

4. The General Settings page appears. Type the details and select OK.

5. The Network Setting page appears. Check the vnet and subnet configurations, edit the required
settings, and select OK.

6. The Summary page appears. Review the configuration and edit accordingly. Select OK to confirm.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 707

NetScaler 12.0

7. The Buy page appears. Select Purchase to complete the deployment.

It might take a moment for the Azure Resource Group to be created with the required configurations.
After completion, select the Resource Group in the Azure portal to see the configuration details, such
as LB rules, back-end pools, health probes, and so on. The high availability pair appears as ns-vpx0
and ns-vpx1.

If further modifications are required for your HA setup, such as creating more security rules and ports,
you can do that from the Azure portal.

Next, you need to configure the load-balancing vserver with the ALB public IP (PIP) address, on each
node. To find the ALB PIP, select ALB > Frontend IP configuration.

See the Resources section for more information about how to configure the load-balancing vserver.

Resources:

The following links provide additional information related to HA deployment and virtual server
(vserver) configuration:

• Configuring high availability nodes in different subnets

• Set up basic load balancing

Related resources:

• Configure a high-availability setup with multiple IP addresses and NICs by using PowerShell
commands
• Configuring GSLB on Active-Standby HA Deployment on Azure

1.
2. Citrix ADC
3. NetScaler 12.0

Configure a high-availability setup with multiple IP addresses and NICs

by using PowerShell commands

January 6, 2019

Contributed by:
C

You can deploy a pair of NetScaler VPX instances with multiple NICs in an active-passive high avail-
ability (HA) setup on Azure. Each NIC can contain multiple IP addresses.

An active-passive deployment requires:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 708

NetScaler 12.0

• An HA Independent Network Configuration (INC) configuration

• The Azure Load Balancer (ALB) in Direct Server Return (DSR) mode

All traffic goes through the primary node. The secondary node remains in standby mode until the
primary node fails.

Note

For a NetScaler VPX high availability deployment on Azure cloud to work, you need a floating
public IP (PIP) that can be moved between the two high-availability nodes. The Azure Load Bal-
ancer (ALB) provides that floating PIP, which is moved to the second node automatically in the
event of a failover.

Diagram: Example of an active-passive deployment architecture

In an active-passive deployment, the ALB floating public IP (PIP) addresses are added as the VIP ad-
dresses in each VPX node. In HA-INC configuration, the VIP addresses are floating and SNIP addresses
are instance specific.

ALB monitors each VPX instances by sending health probe at every 5 seconds and redirects traffic
to that instance only that sends health probes response on regular interval. So in an HA setup, the
primary node responds to health probes and secondary does not. If the primary instances misses
two consecutive health probes, ALB does not redirect traffic to that instance. On failover, the new
primary starts responding to health probes and the ALB redirects traffic to it. The standard VPX high
availability failover time is three seconds. The total failover time that might take for traffic switching
can be maximum of 13 seconds.

You can deploy a VPX pair in active-passive HA setup in two ways by using:

• NetScaler VPX Standard high availability template: use this option to configure an HA pair
with the default option of three subnets and six NICs.
• Windows PowerShell commands: use this option to configure an HA pair according to your
subnet and NIC requirements.

This topic describes how to deploy a VPX pair in active-passive HA setup by using PowerShell com-
mands. If you want to use the NetScaler VPX Standard HA template, see Configuring an HA Setup with
Multiple IP Addresses and NICs.

Configure HA-INC nodes by using PowerShell Ccmmands

Scenario: HA-INC PowerShell deployment

In this scenario, you deploy a NetScaler VPX pair by using the topology given in the table. Each VPX
instance contains three NICs, with each NIC is deployed in a different subnet. Each NIC is assigned
an IP configuration.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 709

NetScaler 12.0

ALB|VPX1|VPX2
|–|–|–|
|ALB is associated with public IP 3 (pip3)|Management IP is configured with IPConfig1, which includes
one public IP (pip1) and one private IP (12.5.2.24); nic1; Mgmtsubnet=12.5.2.0/24|Management IP is con-
figured with IPConfig5, which includes one public IP (pip3) and one private IP (12.5.2.26);nic4;Mgmtsubnet=12.5.2.0/
|LB rules and port configured are HTTP (80),SSL (443), health probe (9000)|Client-side IP is configured
with IPConfig3, which includes one private IP(12.5.1.27);nic2; FrontEndsubet=12.5.1.0/24|Client-side IP
is configured with IPConfig7, which includes one private IP (12.5.1.28);nic5;FrontEndsubet=12.5.1.0/24|
|-|Server-side IP is configured with IPConfig4, which includes one private IP(12.5.3.24); nic3;BackendSubnet=12.5.3.0
side IP is configured with IPConfig8, which includes one private IP(12.5.3.28);nic6;BackendSubnet=12.5.3.0/24|
|-|Rules and ports for NSG areSSH (22),HTTP (80),HTTPS (443)|-|

Parameter settings

The following parameter settings are used in this scenario.

$locName= “South east Asia”

$rgName = “MulitIP-MultiNIC-RG”

$nicName1= “VM1-NIC1”

$nicName2 = “VM1-NIC2”

$nicName3= “VM1-NIC3”

$nicName4 = “VM2-NIC1”

$nicName5= “VM2-NIC2”

$nicName6 = “VM2-NIC3”

$vNetName = “Azure-MultiIP-ALB-vnet”

$vNetAddressRange= “12.5.0.0/16”

$frontEndSubnetName= “frontEndSubnet”

$frontEndSubnetRange= “12.5.1.0/24”

$mgmtSubnetName= “mgmtSubnet”

$mgmtSubnetRange= “12.5.2.0/24”

$backEndSubnetName = “backEndSubnet”

$backEndSubnetRange = “12.5.3.0/24”

$prmStorageAccountName = “multiipmultinicbstorage”

$avSetName = “multiple-avSet”

© 1999-2018 Citrix Systems, Inc. All rights reserved. 710

NetScaler 12.0

$vmSize= “Standard_DS4_V2”

$publisher = “citrix”

$offer = “netscalervpx-120”

$sku = “netscalerbyol”

$version=”latest”

$pubIPName1=”VPX1MGMT”

$pubIPName2=”VPX2MGMT”

$pubIPName3=”ALBPIP”

$domName1=”vpx1dns”

$domName2=”vpx2dns”

$domName3=”vpxalbdns”

$vmNamePrefix=”VPXMultiIPALB”

$osDiskSuffix1=”osmultiipalbdiskdb1”

$osDiskSuffix2=”osmultiipalbdiskdb2”

$lbName= “MultiIPALB”

$frontEndConfigName1= “FrontEndIP”

$backendPoolName1= “BackendPoolHttp”

$lbRuleName1= “LBRuleHttp”

$healthProbeName= “HealthProbe”

$nsgName=”NSG-MultiIP-ALB”

$rule1Name=”Inbound-HTTP”

$rule2Name=”Inbound-HTTPS”

$rule3Name=”Inbound-SSH”

To complete the deployment, complete the following steps by using PowerShell commands:

1. Create a resource group, storage account, and availability set

2. Create a network security group and add rules
3. Create a virtual network and three subnets
4. Create public IP addresses
5. Create IP configurations for VPX1
6. Create IP configurations for VPX2
7. Create NICs for VPX1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 711

NetScaler 12.0

8. Create NICs for VPX2

9. Create VPX1
10. Create VPX2
11. Create ALB

Create a resource group, storage account, and availability set.

1 New-AzureRmResourceGroup -Name $rgName -Location $locName

2
3
4 $prmStorageAccount=New-AzureRMStorageAccount -Name
$prmStorageAccountName -ResourceGroupName $rgName -Type Standard_LRS
-Location $locName
5
6
7 $avSet=New-AzureRMAvailabilitySet -Name $avSetName -ResourceGroupName
$rgName -Location $locName

Create a network security group and add rules.

1 $rule1 = New-AzureRmNetworkSecurityRuleConfig -Name $rule1Name -

Description ”Allow HTTP” -Access Allow -Protocol Tcp -Direction
Inbound -Priority 101
2
3
4 -SourceAddressPrefix Internet -SourcePortRange * -
DestinationAddressPrefix * -DestinationPortRange 80
5
6
7 $rule2 = New-AzureRmNetworkSecurityRuleConfig -Name $rule2Name -
Description ”Allow HTTPS” -Access Allow -Protocol Tcp -Direction
Inbound -Priority 110
8
9
10 -SourceAddressPrefix Internet -SourcePortRange * -
DestinationAddressPrefix * -DestinationPortRange 443
11
12
13 $rule3 = New-AzureRmNetworkSecurityRuleConfig -Name $rule3Name -
Description ”Allow SSH” -Access Allow -Protocol Tcp -Direction
Inbound -Priority 120
14
15
16 -SourceAddressPrefix Internet -SourcePortRange * -
DestinationAddressPrefix * -DestinationPortRange 22

© 1999-2018 Citrix Systems, Inc. All rights reserved. 712

NetScaler 12.0

17
18
19 $nsg = New-AzureRmNetworkSecurityGroup -ResourceGroupName $rgName -
Location $locName -Name $nsgName -SecurityRules $rule1,$rule2,$rule3

Create a virtual network and three subnets.

1 $frontendSubnet=New-AzureRmVirtualNetworkSubnetConfig -Name
$frontEndSubnetName -AddressPrefix $frontEndSubnetRange (this
parameter value should be as per your requirement)
2
3
4 $mgmtSubnet=New-AzureRmVirtualNetworkSubnetConfig -Name $mgmtSubnetName
-AddressPrefix $mgmtSubnetRange
5
6
7 $backendSubnet=New-AzureRmVirtualNetworkSubnetConfig -Name
$backEndSubnetName -AddressPrefix $backEndSubnetRange
8
9
10 $vnet =New-AzureRmVirtualNetwork -Name $vNetName -ResourceGroupName
$rgName -Location $locName -AddressPrefix $vNetAddressRange -Subnet
$frontendSubnet,$backendSubnet, $mgmtSubnet
11
12
13 $subnetName =”frontEndSubnet”
14
15
16 $subnet1=$vnet.Subnets|?{
17 $_.Name -eq $subnetName }
18
19
20
21 $subnetName=”backEndSubnet”
22
23
24 $subnet2=$vnet.Subnets|?{
25 $_.Name -eq $subnetName }
26
27
28
29 $subnetName=”mgmtSubnet”
30
31
32 $subnet3=$vnet.Subnets|?{

© 1999-2018 Citrix Systems, Inc. All rights reserved. 713

NetScaler 12.0

33 $_.Name -eq $subnetName }

Create public IP addresses.

1 $pip1=New-AzureRmPublicIpAddress -Name $pubIPName1 -ResourceGroupName

$rgName -DomainNameLabel $domName1 -Location $locName -
AllocationMethod Dynamic
2
3
4 $pip2=New-AzureRmPublicIpAddress -Name $pubIPName2 -ResourceGroupName
$rgName -DomainNameLabel $domName2 -Location $locName -
AllocationMethod Dynamic
5
6
7 $pip3=New-AzureRmPublicIpAddress -Name $pubIPName3 -ResourceGroupName
$rgName -DomainNameLabel $domName3 -Location $locName -
AllocationMethod Dynamic

Create IP configurations for VPX1.

1 $IpConfigName1 = ”IPConfig1”
2
3
4 $IPAddress = ”12.5.2.24”
5
6
7 $IPConfig1=New-AzureRmNetworkInterfaceIpConfig -Name $IPConfigName1 -
Subnet $subnet3 -PrivateIpAddress $IPAddress -PublicIpAddress $pip1
-Primary
8
9
10 $IPConfigName3=”IPConfig-3”
11
12
13 $IPAddress=”12.5.1.27”
14
15
16 $IPConfig3=New-AzureRmNetworkInterfaceIpConfig -Name $IPConfigName3 -
Subnet $subnet1 -PrivateIpAddress $IPAddress -Primary
17
18
19 $IPConfigName4 = ”IPConfig-4”
20
21
22 $IPAddress = ”12.5.3.24”

© 1999-2018 Citrix Systems, Inc. All rights reserved. 714

NetScaler 12.0

23
24
25 $IPConfig4 = New-AzureRmNetworkInterfaceIpConfig -Name $IPConfigName4 -
Subnet $subnet2 -PrivateIpAddress $IPAddress -Primary

Create IP configurations for VPX2.

1 $IpConfigName5 = ”IPConfig5”
2
3
4 $IPAddress=”12.5.2.26”
5
6
7 $IPConfig5=New-AzureRmNetworkInterfaceIpConfig -Name $IPConfigName5 -
Subnet $subnet3 -PrivateIpAddress $IPAddress -PublicIpAddress $pip2
-Primary
8
9
10 $IPConfigName7=”IPConfig-7”
11
12
13 $IPAddress=”12.5.1.28”
14
15
16 $IPConfig7=New-AzureRmNetworkInterfaceIpConfig -Name $IPConfigName7 -
Subnet $subnet1 -PrivateIpAddress $IPAddress -Primary
17
18
19 $IPConfigName8=”IPConfig-8”
20
21
22 $IPAddress=”12.5.3.28”
23
24
25 $IPConfig8=New-AzureRmNetworkInterfaceIpConfig -Name $IPConfigName8 -
Subnet $subnet2 -PrivateIpAddress $IPAddress -Primary

Create NICs for VPX1.

1 $nic1=New-AzureRmNetworkInterface -Name $nicName1 -ResourceGroupName

$rgName -Location $locName -IpConfiguration $IpConfig1 -
NetworkSecurityGroupId $nsg.Id
2
3
4 $nic2=New-AzureRmNetworkInterface -Name $nicName2 -ResourceGroupName

© 1999-2018 Citrix Systems, Inc. All rights reserved. 715

NetScaler 12.0

$rgName -Location $locName -IpConfiguration $IpConfig3 -

NetworkSecurityGroupId $nsg.Id
5
6
7 $nic3=New-AzureRmNetworkInterface -Name $nicName3 -ResourceGroupName
$rgName -Location $locName -IpConfiguration $IpConfig4 -
NetworkSecurityGroupId $nsg.Id

Create NICs for VPX2.

1 $nic4=New-AzureRmNetworkInterface -Name $nicName4 -ResourceGroupName

$rgName -Location $locName -IpConfiguration $IpConfig5 -
NetworkSecurityGroupId $nsg.Id
2
3
4 $nic5=New-AzureRmNetworkInterface -Name $nicName5 -ResourceGroupName
$rgName -Location $locName -IpConfiguration $IpConfig7 -
NetworkSecurityGroupId $nsg.Id
5
6
7 $nic6=New-AzureRmNetworkInterface -Name $nicName6 -ResourceGroupName
$rgName -Location $locName -IpConfiguration $IpConfig8 -
NetworkSecurityGroupId $nsg.Id

Create VPX1.
This step includes the following substeps:
• Create VM config object
• Set credentials, OS, and image
• Add NICs
• Specify OS disk and create VM

1 $suffixNumber = 1
2
3
4 $vmName=$vmNamePrefix + $suffixNumber
5
6
7 $vmConfig=New-AzureRMVMConfig -VMName $vmName -VMSize $vmSize -
AvailabilitySetId $avSet.Id
8
9
10 $cred=Get-Credential -Message ”Type the name and password for VPX login
.”
11

© 1999-2018 Citrix Systems, Inc. All rights reserved. 716

NetScaler 12.0

12
13 $vmConfig=Set-AzureRMVMOperatingSystem -VM $vmConfig -Linux -
ComputerName $vmName -Credential $cred
14
15
16 $vmConfig=Set-AzureRMVMSourceImage -VM $vmConfig -PublisherName
$publisher -Offer $offer -Skus $sku -Version $version
17
18
19 $vmConfig=Add-AzureRMVMNetworkInterface -VM $vmConfig -Id $nic1.Id -
Primary
20
21
22 $vmConfig=Add-AzureRMVMNetworkInterface -VM $vmConfig -Id $nic2.Id
23
24
25 $vmConfig=Add-AzureRMVMNetworkInterface -VM $vmConfig -Id $nic3.Id
26
27
28 $osDiskName=$vmName + ”-” + $osDiskSuffix1
29
30
31 $osVhdUri=$prmStorageAccount.PrimaryEndpoints.Blob.ToString() + ”vhds/”
+ $osDiskName + ”.vhd”
32
33
34 $vmConfig=Set-AzureRMVMOSDisk -VM $vmConfig -Name $osDiskName -VhdUri
$osVhdUri -CreateOption fromImage
35
36
37 Set-AzureRmVMPlan -VM $vmConfig -Publisher $publisher -Product $offer -
Name $sku
38
39
40 New-AzureRMVM -VM $vmConfig -ResourceGroupName $rgName -Location
$locName

Create VPX2.

1 $suffixNumber=2
2
3
4 $vmName=$vmNamePrefix + $suffixNumber
5
6

© 1999-2018 Citrix Systems, Inc. All rights reserved. 717

NetScaler 12.0

7 $vmConfig=New-AzureRMVMConfig -VMName $vmName -VMSize $vmSize -

AvailabilitySetId $avSet.Id
8
9
10 $cred=Get-Credential -Message ”Type the name and password for VPX login
.”
11
12
13 $vmConfig=Set-AzureRMVMOperatingSystem -VM $vmConfig -Linux -
ComputerName $vmName -Credential $cred
14
15
16 $vmConfig=Set-AzureRMVMSourceImage -VM $vmConfig -PublisherName
$publisher -Offer $offer -Skus $sku -Version $version
17
18
19 $vmConfig=Add-AzureRMVMNetworkInterface -VM $vmConfig -Id $nic4.Id -
Primary
20
21
22 $vmConfig=Add-AzureRMVMNetworkInterface -VM $vmConfig -Id $nic5.Id
23
24
25 $vmConfig=Add-AzureRMVMNetworkInterface -VM $vmConfig -Id $nic6.Id
26
27
28 $osDiskName=$vmName + ”-” + $osDiskSuffix2
29
30
31 $osVhdUri=$prmStorageAccount.PrimaryEndpoints.Blob.ToString() + ”vhds/”
+ $osDiskName + ”.vhd”
32
33
34 $vmConfig=Set-AzureRMVMOSDisk -VM $vmConfig -Name $osDiskName -VhdUri
$osVhdUri -CreateOption fromImage
35
36
37 Set-AzureRmVMPlan -VM $vmConfig -Publisher $publisher -Product $offer -
Name $sku
38
39
40 New-AzureRMVM -VM $vmConfig -ResourceGroupName $rgName -Location
$locName

To view private and public IP addresses assigned to the NICs, type the following commands:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 718

NetScaler 12.0

1 $nic1.IPConfig
2
3
4 $nic2.IPConfig
5
6
7 $nic3.IPConfig
8
9
10 $nic4.IPConfig
11
12
13 $nic5.IPConfig
14
15
16 $nic6.IPConfig

Create Azure load balance (ALB).

This step includes the following substeps:
• Create frontend IP config
• Create health probe
• Create backend address pool
• Create load-balancing rules (HTTP and SSL)
• Create ALB with frontend IP config, backend address pool, and LB rule
• Associate IP config with backend pools

1 $frontEndIP1=New-AzureRmLoadBalancerFrontendIpConfig -Name
$frontEndConfigName1 -PublicIpAddress $pip3
2
3
4 $healthProbe=New-AzureRmLoadBalancerProbeConfig -Name $healthProbeName
-Protocol Tcp -Port 9000 ‒ IntervalInSeconds 5 -ProbeCount 2
5
6
7 $beAddressPool1=New-AzureRmLoadBalancerBackendAddressPoolConfig -Name
$backendPoolName1
8
9
10 $lbRule1=New-AzureRmLoadBalancerRuleConfig -Name $lbRuleName1 -
FrontendIpConfiguration $frontEndIP1 -BackendAddressPool
$beAddressPool1 -Probe $healthProbe -Protocol Tcp -FrontendPort 80 -
BackendPort 80 -EnableFloatingIP
11

© 1999-2018 Citrix Systems, Inc. All rights reserved. 719

NetScaler 12.0

12
13 $lb=New-AzureRmLoadBalancer -ResourceGroupName $rgName -Name $lbName -
Location $locName -FrontendIpConfiguration $frontEndIP1 -
LoadBalancingRule $lbRule1 -BackendAddressPool $beAddressPool1 -
Probe $healthProbe
14
15
16 $nic2.IpConfigurations[0].LoadBalancerBackendAddressPools.Add($lb.
BackendAddressPools[0])
17
18
19 $nic5.IpConfigurations[0].LoadBalancerBackendAddressPools.Add($lb.
BackendAddressPools[0])
20
21
22 $lb=$lb |Set-AzureRmLoadBalancer
23
24
25 $nic2=$nic2 | Set-AzureRmNetworkInterface
26
27
28 $nic5=$nic5 | Set-AzureRmNetworkInterface

After you’ve successfully deployed the NetScaler VPX pair, log on to each VPX instance to configure
HA-INC, and SNIP and VIP addresses.

1. Type the following command to add HA nodes.

1 add ha node 1 PeerNodeNSIP -inc Enabled

2. Add private IP addresses of client-side NICs as SNIPs for VPX1 (NIC2) and VPX2 (NIC5)

1 add nsip privateIPofNIC2 255.255.255.0 -type SNIP

2
3
4 add nsip privateIPofNIC5 255.255.255.0 -type SNIP

3. Add load-balancing vserver on the primary node with front-end IP address (public IP) of ALB.

1 add lb vserver v1 HTTP FrontEndIPofALB 80

Related resources:

Configuring GSLB on Active-Standby HA Deployment on Azure

1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 720

NetScaler 12.0

2. Citrix ADC
3. NetScaler 12.0

Configure a high-availability setup with a single IP address and a single

NIC

January 6, 2019

Contributed by:
C

In a Microsoft Azure deployment, a high-availability configuration of two NetScaler VPX instances is

achieved by using the Azure load balancer, which distributes the client traffic across the virtual servers
configured on both the VPX instances.

Note

For a Citrix VPX high availability deployment on Azure cloud to work, you need a floating public IP
(PIP) that can be moved between the two NetS high availability nodes. The Azure Load Balancer
(ALB) provides that floating PIP, which is moved to the second node automatically in the event
of a failover.

Two types of Azure load balancers are available for high availability:

• Azure external load balancer: If the client traffic originates from the Internet, you have to de-
ploy the external load balancer between the Internet and the NetScaler VPX instances to dis-
tribute client traffic.
• Azure internal load balancer: If the client traffic originates from within the virtual network, or
is forwarded by a gateway or firewall within the virtual network, you have to deploy the internal
load balancer to distribute client traffic.

To achieve high availability on Azure, you must add the two VPX instances as a load balanced set and
configure the NSG.

When two NetScaler VPX instances are configured in active-active mode, both instances must have the
same configuration. The client traffic is distributed across the virtual servers in both the instances by
the Azure load balancer. The VIP addresses in both the instances are different and should match the
NSIP of that VPX instance.

The active-passive mode provides failover capability. In this mode, the VPX instances synchronize
their configuration states. When the primary instance fails, the secondary instance takes over.

For information about high availability in NetScaler appliances, see High availability.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 721

NetScaler 12.0

Before you begin

Note the following before you begin configuring the VPX instances in high availability mode in the
Azure virtual network.

• The two NetScaler VPX instances that you want to add to a load balanced set should be provi-
sioned in the same virtual network.
• A load balanced set applies only to a VM’s default NIC. Therefore the VIP has to be configured on
the default NIC of the VPX instance.
• In an active-passive deployment, the Azure load balancer monitors both the primary and the
secondary VPX instance by sending them TCP probes. These TCP probes are sent on port 9000.

Summary of steps to configure a NetScaler VPX instance in a high-availability Mode

1. Configure a resource group

2. Configure a network security group
3. Configure virtual network and its subnets
4. Configure a storage account
5. Configure an availability set
6. Configure a NetScaler VPX instance
7. Configure internal and external load balancers
8. Configure health probes
9. Configure backend pools
10. Configure NAT rules
11. Configure load balancing rules

After configuring all the resources, you can configure the VMs in high availability mode with either an
external load balancer or with an internal load balancer.

This article provides procedures to configure resources specific to high availability mode. For proce-
dures to configure the other resources, see Configure a NetScaler VPX standalone instance.

You need to set up two NetScaler VPX instances for high availability mode. To set up a NetScaler VPX
instance, see the “Configuring a NetScaler VPX Instance” section in Configure a NetScaler standalone
instance.

Configure internal and external load balancers

Create a load balancer to distribute traffic between the vidtaul machines that are part of the same
virtual network. The load balancing features can load balance level 4 traffic and support only TCP
and UDP traffic.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 722

NetScaler 12.0

Configure an internal load balancer

1. Click +New > Networking > Load Balancer.

2. In the Create load balancer pane, enter the following details:
• Name of the load balancer
• Scheme - select Internal to configure an internal load balancer
• Virtual network - select the newly created virtual network from the drop-down list
• Subnet - select the associated subnet
• IP address assignment - select Static
• Private IP address - assign a private IP address for the internal load balancer
• Resource group - select the newly created resource group from the drop-down list
3. Click Create.

Configuring an external load balancer

1. To create an external load balancer, follow similar steps as creating an internal load balancer
with the following differences:
• Schema - select Public
• Public IP address - assign a public IP address to the external load balancer
2. Click Create.

Configure a health probe on the load balancer

Create custom TCP or HTTP probes to monitor the health of the various server instances. When the
VM fails to respond to the probe for three consecutive times, the Azure load balancer will not send the
traffic to the nonresponsive VM.

1. Click All resources and search for the load balancer that you created by typing the name in the
search box.
2. In the Settings pane, click Probes.

3. Click +Add and in the Add probe pane, enter the following details:

• Name of the health probe

• Protocol - select TCP
• Port - type 9000
• Set the Interval and Unhealthy threshold limits

4. Click OK.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 723

NetScaler 12.0

Configure a backend pool on the load balancer

Create backend pools, that is, a pool of IP addresses associated with the virtual machine Network
Interface Cards (NIC) to which the load is distributed.

1. Click All resources and search for the load balancer that you have created by typing the name
in the search box.
2. In the Settings pane, select Backend pools.
3. Click +Add and in the Add backend pool pane, enter the following details:
• Name of the backend pool
• Availability set - select the availability set created earlier
• Virtual machines - select the NetScaler VPX instances that are in high availability deploy-
ment. Press <Ctrl> to select multiple instances.
4. Click OK.

Configure a NAT rule on the load balancer

Create custom NAT rules on LB to define the inbound traffic flowing through the front end IP address
and distributed to the back end IP address. Make sure that no two NAT rules has the combination of
same service and same target port.

Note

A front end IP address is the external IP address on the load balancer that faces the incoming
traffic and a back end IP address is the VM facing IP address that receives the traffic from the
load balancer.

1. Click All resources and search for the load balancer that you have created by typing the name
in the search box.
2. In the Settings pane, select Inbound NAT rules.
3. Click +Add and in the Add inbound NAT rule pane, add a NAT rule for each type of request. You
can add multiple NAT rules.
4. Enter the following details, and then click OK.
• Name of the rule
• Service - select the required service from the drop-down list
• Port - type the correct port number
• Target - select the NetScaler VPX that will be the target of this rule
• Target port - the target port is automatically populated depending on the service selected

Note

Citrix recommends TCP services for the NetScaler VPX VM on port 9000.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 724

NetScaler 12.0

Configure a load balancing rule on the load balancer

By creating a load balancer rule, you can define a combination of a front end IP address and port, and
back end IP address and port associated with VMs.
For example, create a rule so that all HTTP requests coming on the public IP will be forwarded to the
availability set on their port 80.
1. Click All resources and search for the load balancer that you have created by typing the name
in the search box.
2. In the Settings pane, select Load balancing rules.
3. Click +Add and in the Add load balancing rules pane, create load balancing rules for each type
of incoming network traffic.
4. Enter the following details:
• Name of the rule
• Protocol - select the protocol
• Port - type the port number based on the port selected
• Backend pool - select the backend pool from the drop-down list
• Probe - select the health probe from the drop-down list
5. Click OK.

Configure NetScaler VPX high availability with the Azure external load balancer

If your client traffic originates from the Internet, you have to deploy the external load balancer to
create a high availability configuration of NetScaler VPX instances in a load-balanced set.
The following figure shows how high availability is achieved in active-active mode by using the exter-
nal load balancer. The two VPX instances are in a load-balanced set that accepts client traffic from
the Internet over port 15000. The Azure external load balancer load balances these client requests
between the two virtual machines.
Before you begin configuring the load-balanced set through the Azure portal, do one of the following:
• For an active-passive deployment, configure the NetScaler VPX instances as primary and sec-
ondary nodes by using the following command: add ha node <ID> <IP address>.
• For an active-active deployment, configure the required services on the two NetScaler VPX in-
stances.

Configure NetScaler VPX high availability with the Azure internal load balancer

If your client traffic originates from within the virtual network with a regional scope, you have to de-
ploy the internal load balancer to achieve high availability of NetScaler VPX instances added to a load-
balanced set.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 725

NetScaler 12.0

The following figure shows how high availability is achieved in an active-active mode by using the
internal load balancer. The two NetScaler VPX instances are in a load-balanced set that accepts client
traffic from the Internet at port 15001. The Azure internal load balancer load balances these client
requests between the two virtual machines.

Before you begin configuring the load-balanced set by using Azure PowerShell, do one of the follow-
ing:

• For an active-passive deployment, configure the NetScaler VPX instances as primary and sec-
ondary nodes by using the following command: add ha node <ID> <IP address>.
• For an active-active deployment, configure the required services on the two NetScaler VPX in-
stances.

You can configure the load-balanced set only by using Azure PowerShell.

Access the NetScaler VPX instance

You can access the VPX instance either through its graphical user interface (GUI) or through the com-
mand line interface (CLI). You can use the PIP to access the NetScaler VPX instance instance.

To log on to the virtual machine, use your username and password specified while creating the virtual
machine.

You can change the password after you log on to the instance.

Access the VPX instance through the GUI

In a browser’s address field, type the virtual network public IP address provided by Azure during virtual
machine provisioning, or type the PIP address.

Note

Make sure you have created NSG inbound or outbound rules to allow access to the private port
80 or 443 when accessing the GUI by using the virtual network IP.

Access the VPX instance through the CLI

Use any command line access tool (for example, Putty). Specify either the virtual network public IP
address provided by Azure during NetScaler VPX provisioning, or specify the PIP address. Use SSH
protocol with port 22.
Note

Make sure that you have created NSG inbound or outbound rules to allow access to private port

© 1999-2018 Citrix Systems, Inc. All rights reserved. 726

NetScaler 12.0

22 when accessing the CLI by using the virtual network IP.

For information about getting started with a NetScaler appliance, see the Getting started with
NetScaler.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure GSLB on NetScaler VPX instances

January 6, 2019

Contributed by:
C

NetScaler appliances configured for global server load balancing (GSLB) provide disaster recovery and
continuous availability of applications by protecting against points of failure in a wide area network
(WAN). GSLB can balance the load across data centers by directing client requests to the closest or
best performing data center, or to surviving data centers in case of an outage.

This section describes how to enable GSLB on VPX instances on two sites in a Microsoft Azure environ-
ment, by using Windows PowerShell commands.

Note

For more information about GSLB, see Global Server Load Balancing.

You can configure GSLB on a NetScaler VPX instances on Azure, in two steps:

1. Create a VPX instance with multiple NICs and multiple IP addresses, on each site.
2. Enable GSLB on the VPX instances.
Note

For more information about configuring multiple NICs and IP addresses see:

• Configure multiple IP addresses for a NetScaler VPX instance in standalone mode by using
PowerShell commands

Scenario

This scenario includes two sites - Site 1 and Site 2. Each site has a VM (VM1 and VM2) configured with
multiple NICs, multiple IP addresses, and GSLB.

Figure. GSLB setup implemented across two sites - Site 1 and Site 2.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 727

NetScaler 12.0

In this scenario, each VM has three NICs - NIC 0/1, 1/1, and 1/2. Each NIC can have multiple private and
public IP addresses. The NICs are configured for the following purposes.

• NIC 0/1: to serve management traffic

• NIC 1/1: to serve client-side traffic
• NIC 1/2: to communicate with back-end servers

For information about the IP addresses configured on each NIC in this scenario, see the
IP configuration details section.

Parameters

Following are sample parameters settings for this scenario in this document. You can use different
settings if you wish.

$location=”West Central US”

$vnetName=”NSVPX-vnet”

$RGName=”multiIP-RG”

$prmStorageAccountName=”multiipstorageaccnt”

$avSetName=”MultiIP-avset”

$vmSize=”Standard_DS3_V2”

Note: The minimum requirement for a VPX instance is 2 vCPUs and 2GB RAM.

$publisher=”citrix”

$offer=”netscalervpx111”

$sku=”netscalerbyol”

$version=”latest”

$vmNamePrefix=”MultiIPVPX”

$nicNamePrefix=”MultiipVPX”

$osDiskSuffix=”osdiskdb”

$numberOfVMs=1

$ipAddressPrefix=”10.0.0.”

$ipAddressPrefix1=”10.0.1.”

$ipAddressPrefix2=”10.0.2.”

$pubIPName1=”MultiIP-pip1”

© 1999-2018 Citrix Systems, Inc. All rights reserved. 728

NetScaler 12.0

$pubIPName2=”MultiIP-pip2”

$IpConfigName1=”IPConfig1”

$IPConfigName2=”IPConfig-2”

$IPConfigName3=”IPConfig-3”

$IPConfigName4=”IPConfig-4”

$frontendSubnetName=”default”

$backendSubnetName1=”subnet_1”

$backendSubnetName2=”subnet_2”

$suffixNumber=10

Create a VM

Follow steps 1-10 to create VM1 with multiple NICs and multiple IP addresses, by using PowerShell
commands:

1. Create resource group

2. Create storage account

3. Create availability set

4. Create virtual network

5. Create public IP address

6. Create NICs

7. Create VM config object

8.Get credentials and set OS properties for the VM

9. Add NICs

10. Specify OS disk and create VM

After you complete all the steps and commands to create VM1, repeat these steps to create VM2 with
parameters specific to it.

Create resource group

1 New-AzureRMResourceGroup -Name $RGName -Location $location

© 1999-2018 Citrix Systems, Inc. All rights reserved. 729

NetScaler 12.0

Create storage account

1 $prmStorageAccount=New-AzureRMStorageAccount -Name
$prmStorageAccountName -ResourceGroupName $RGName -Type Standard_LRS
-Location $location

Create availability set

1 $avSet=New-AzureRMAvailabilitySet -Name $avSetName -ResourceGroupName

$RGName -Location $location

Create virtual network

1. Add subnets.

1 $subnet1=New-AzureRmVirtualNetworkSubnetConfig -Name
$frontendSubnetName -AddressPrefix ”10.0.0.0/24”
2 $subnet2=New-AzureRmVirtualNetworkSubnetConfig -Name
$backendSubnetName1 -AddressPrefix ”10.0.1.0/24”
3 $subnet3=New-AzureRmVirtualNetworkSubnetConfig -Name
$backendSubnetName2 -AddressPrefix ”10.0.2.0/24”

2. Add virtual network object.

1 $vnet=New-AzureRmVirtualNetwork -Name $vnetName -ResourceGroupName

$RGName -Location $location -AddressPrefix 10.0.0.0/16 -Subnet
$subnet1, $subnet2, $subnet3

3. Retrieve subnets.

1 $frontendSubnet=$vnet.Subnets|?{
2 $_.Name -eq $frontendSubnetName }
3
4 $backendSubnet1=$vnet.Subnets|?{
5 $_.Name -eq $backendSubnetName1 }
6
7 $backendSubnet2=$vnet.Subnets|?{
8 $_.Name -eq $backendSubnetName2 }

© 1999-2018 Citrix Systems, Inc. All rights reserved. 730

NetScaler 12.0

Create public IP address

1 $pip1=New-AzureRmPublicIpAddress -Name $pubIPName1 -ResourceGroupName

$RGName -Location $location -AllocationMethod Dynamic
2 $pip2=New-AzureRmPublicIpAddress -Name $pubIPName2 -ResourceGroupName
$RGName -Location $location -AllocationMethod Dynamic

Create NICs

Create NIC 0/1

1 $nic1Name=$nicNamePrefix + $suffixNumber + ”-Mgmnt”

2 $ipAddress1=$ipAddressPrefix + $suffixNumber
3 $IPConfig1=New-AzureRmNetworkInterfaceIpConfig -Name $IPConfigName1 -
SubnetId $frontendSubnet.Id -PublicIpAddress $pip1 -PrivateIpAddress
$ipAddress1 -Primary
4 $nic1=New-AzureRMNetworkInterface -Name $nic1Name -ResourceGroupName
$RGName -Location $location -IpConfiguration $IpConfig1

Create NIC 1/1

1 $nic2Name $nicNamePrefix + $suffixNumber + ”-frontend”

2 $ipAddress2=$ipAddressPrefix1 + ($suffixNumber)
3 $ipAddress3=$ipAddressPrefix1 + ($suffixNumber + 1)
4 $IPConfig2=New-AzureRmNetworkInterfaceIpConfig -Name $IPConfigName2 -
PublicIpAddress $pip2 -SubnetId $backendSubnet1.Id  -
PrivateIpAddress $ipAddress2  -Primary
5 $IPConfig3=New-AzureRmNetworkInterfaceIpConfig -Name $IPConfigName3 -
SubnetId $backendSubnet1.Id  -PrivateIpAddress $ipAddress3  
6 nic2=New-AzureRMNetworkInterface -Name $nic2Name -ResourceGroupName
$RGName -Location $location -IpConfiguration $IpConfig2, $IpConfig3

Create NIC 1/2

1 $nic3Name=$nicNamePrefix + $suffixNumber + ”-backend”

2 $ipAddress4=$ipAddressPrefix2 + ($suffixNumber)
3 $IPConfig4=New-AzureRmNetworkInterfaceIpConfig -Name $IPConfigName4 -
SubnetId $backendSubnet2.Id -PrivateIpAddress $ipAddress4 -Primary
4 $nic3=New-AzureRMNetworkInterface -Name $nic3Name -ResourceGroupName
$RGName -Location $location -IpConfiguration $IpConfig4

Create VM config object

© 1999-2018 Citrix Systems, Inc. All rights reserved. 731

NetScaler 12.0

1 $vmName=$vmNamePrefix
2 $vmConfig=New-AzureRMVMConfig -VMName $vmName -VMSize $vmSize -
AvailabilitySetId $avSet.Id

Get credentials and set OS properties

1 $cred=Get-Credential -Message ”Type the name and password for VPX login
.”
2 $vmConfig=Set-AzureRMVMOperatingSystem -VM $vmConfig -Linux -
ComputerName $vmName -Credential $cred
3 $vmConfig=Set-AzureRMVMSourceImage -VM $vmConfig -PublisherName
$publisher -Offer $offer -Skus $sku -Version $version

Add NICs

1 $vmConfig=Add-AzureRMVMNetworkInterface -VM $vmConfig -Id $nic1.Id -

Primary
2 $vmConfig=Add-AzureRMVMNetworkInterface -VM $vmConfig -Id $nic2.Id
3 $vmConfig=Add-AzureRMVMNetworkInterface -VM $vmConfig -Id $nic3.Id

Specify OS disk and create VM

1 $osDiskName=$vmName + ”-” + $osDiskSuffix

2 $osVhdUri=$prmStorageAccount.PrimaryEndpoints.Blob.ToString() + ”vhds/”
+$osDiskName + ”.vhd”
3 $vmConfig=Set-AzureRMVMOSDisk -VM $vmConfig -Name $osDiskName -VhdUri
$osVhdUri -CreateOption fromImage
4 Set-AzureRmVMPlan -VM $vmConfig -Publisher $publisher -Product $offer -
Name $sku
5 New-AzureRMVM -VM $vmConfig -ResourceGroupName $RGName -Location
$location

Note

Repeat steps 1-10 listed in “Create Multi-NIC VMs by Using PowerShell Commands” to create VM2
with parameters specific to VM2.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 732

NetScaler 12.0

IP configuration details

The following IP addresses are used.

Table 1. IP addresses used in VM1

NIC Private IP Public IP (PIP) Description

0/1 10.0.0.10 PIP1 Configured as

NSIP
(management
IP)
1/1 10.0.1.10 PIP2 Configured as
SNIP/GSLB Site
IP
- 10.0.1.11 - Configured as LB
server IP
Public IP is not
mandatory
1/2 10.0.2.10 - Configured as
SNIP for sending
monitor probes
to services;
public IP is not
mandatory

Table 2. IP addresses used in VM2

NIC Internal IP Public IP (PIP) Description

0/1 20.0.0.10 PIP4 Configured as NSIP

(management IP)
1/1 20.0.1.10 PIP5 Configured as
SNIP/GSLB Site IP
- 20.0.1.11 - Configured as LB
server IP
Public IP is not
mandatory

© 1999-2018 Citrix Systems, Inc. All rights reserved. 733

NetScaler 12.0

NIC Internal IP Public IP (PIP) Description

1/2 20.0.2.10 - Configured as SNIP

for sending monitor
probes to services;
public IP is not
mandatory

Here are sample configurations for this scenario, showing the IP addresses and intial LB configurations
as created through the NetScaler VPX CLI for VM1 and VM2.

Here’s an example confiruation on VM1.

1 add ns ip 10.0.1.10 255.255.255.0 -mgmtAccess ENABLED

2 Add nsip 10.0.2.10 255.255.255.0
3 add service svc1 10.0.1.10 ADNS 53
4 add lb vserver v1 HTTP 10.0.1.11 80
5 add service s1 10.0.2.120 http 80
6 Add service s2 10.0.2.121 http 80
7 Bind lb vs v1 s[1-2]

Here’s an example confiruation on VM2.

1 add ns ip 20.0.1.10 255.255.255.0  -mgmtAccess ENABLED

2 Add nsip 20.0.2.10 255.255.255.0
3 add service svc1 20.0.1.10 ADNS 53
4 add lb vserver v1 HTTP 20.0.1.11 80
5 Add service s1 20.0.2.90 http 80
6 Add service s2 20.0.2.91 http 80
7 Bind lb vs v1 s[1-2]

Configure GSLB sites and other settings

Perform the tasks described in the following topic to configure the two GSLB sites and other necessary
settings:

Global Server Load Balancing

For more information, see this support article:

https://support.citrix.com/article/CTX110348

Here’s an example GSLB confiruation on VM1 and VM2.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 734

NetScaler 12.0

1 enable ns feature LB GSLB

2 add gslb site site1 10.0.1.10 -publicIP PIP2
3 add gslb site site2 20.0.1.10 -publicIP PIP5
4 add gslb service site1_gslb_http_svc1 10.0.1.11 HTTP 80 -publicIP PIP3
-publicPort 80 -siteName site1
5 add gslb service site2_gslb_http_svc1 20.0.1.11 HTTP 80 -publicIP PIP6
-publicPort 80 -siteName site2
6 add gslb vserver gslb_http_vip1 HTTP
7 bind gslb vserver gslb_http_vip1 -serviceName site2_gslb_http_svc1
8 bind gslb vserver gslb_http_vip1 -serviceName site1_gslb_http_svc1
9 bind gslb vserver gslb_http_vip1 -domainName www.gslbindia.com -TTL 5

You’ve configured GSLB on NetScaler VPX instances running on Azure.

For additional information about how to configure GSLB on NetScaler VPX instances, click the follow-
ing image to watch the video about Configuring NetScaler GSLB in Microsoft Azure.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 735

NetScaler 12.0

Configure GSLB on an active-standby high-availability setup

January 6, 2019

Contributed by:
C

You can configure global server load balancing (GSLB) on active-standby HA deployment on Azure in
three steps:

1. Create a VPX HA pair on each GSLB site. See Configure a high-availability setup with multiple IP
addresses and NICs for information about how to create an HA pair.

2. Configure the Azure Load Balancer (ALB) with the front-end IP address and rules to allow GSLB and
DNS traffic.

This step involves the following substeps. See the scenario in this section for the PowerShell com-
mands used to complete these substeps.

1 a. Create a front-end IPconfig for GSLB site.

2
3 b. Create back-end address pool with IP address of NIC 1/1 of nodes in
HA.
4
5 c. Create load-balancing rules for following:
6
7 TCP/3011 ‒ gslb communication
8 TCP/3010 - gslb communication
9 UDP/53 - DNS communication
10
11 d. Associate back-end address pool with the LB rules created in step c.

3. Enable GSLB on each HA pair.

Scenario

This scenario includes two sites - Site 1 and Site 2. Each site has an HA pair (HA1 and HA2) configured
with multiple NICs, multiple IP addresses, and GSLB.

Figure: GLSB on Active-Standy HA Deployment on Azure

In this scenario, each VM has three NICs - NIC 0/1, 1/1, and 1/2. The NICs are configured for the following
purposes.

NIC 0/1: to serve management traffic

© 1999-2018 Citrix Systems, Inc. All rights reserved. 736

NetScaler 12.0

NIC 1/1: to serve client-side traffic

NIC 1/2: to communicate with back-end servers

Parameter Settings

Following are sample parameters settings for the ALB. You can use different settings if you want.

$locName=”South east Asia”

$rgName=”MulitIP-MultiNIC-RG”

$pubIPName4=”PIPFORGSLB1”

$domName4=”vpxgslbdns”

$lbName=”MultiIPALB”

$frontEndConfigName2=”FrontEndIP2”

$backendPoolName1=”BackendPoolHttp”

$lbRuleName2=”LBRuleGSLB1”

$lbRuleName3=”LBRuleGSLB2”

$lbRuleName4=”LBRuleDNS”

$healthProbeName=”HealthProbe”

Configure ALB with the front-end IP address and rules to allow GSLB and DNS traffic

Step 1. Create a public IP for GSLB site IP

1 $pip4=New-AzureRmPublicIpAddress -Name $pubIPName4 -ResourceGroupName

$rgName -DomainNameLabel $domName4 -Location $locName -
AllocationMethod Dynamic
2
3
4 Get-AzureRmLoadBalancer -Name $lbName -ResourceGroupName $rgName | Add-
AzureRmLoadBalancerFrontendIpConfig -Name $frontEndConfigName2 -
PublicIpAddress $pip4 | Set-AzureRmLoadBalancer

Step 2. Create LB rules and update the existing ALB.

1 $alb = get-AzureRmLoadBalancer -Name $lbName -ResourceGroupName $rgName

2
3

© 1999-2018 Citrix Systems, Inc. All rights reserved. 737

NetScaler 12.0

4 $frontendipconfig2=Get-AzureRmLoadBalancerFrontendIpConfig -
LoadBalancer $alb -Name $frontEndConfigName2
5
6
7 $backendPool=Get-AzureRmLoadBalancerBackendAddressPoolConfig -
LoadBalancer $alb -Name $backendPoolName1
8
9
10 $healthprobe=Get-AzureRmLoadBalancerProbeConfig -LoadBalancer $alb -
Name $healthProbeName
11
12
13 $alb | Add-AzureRmLoadBalancerRuleConfig -Name $lbRuleName2 -
BackendAddressPool $backendPool -FrontendIPConfiguration
 $frontendipconfig2 -Protocol ”Tcp” -FrontendPort 3011 -BackendPort
3011 -Probe $healthprobe -EnableFloatingIP  | Set-
AzureRmLoadBalancer
14
15
16 $alb | Add-AzureRmLoadBalancerRuleConfig -Name $lbRuleName3 -
BackendAddressPool $backendPool -FrontendIPConfiguration
 $frontendipconfig2 -Protocol ”Tcp” -FrontendPort 3010 -BackendPort
3010 -Probe $healthprobe -EnableFloatingIP  | Set-
AzureRmLoadBalancer
17
18
19 $alb | Add-AzureRmLoadBalancerRuleConfig -Name $lbRuleName4 -
BackendAddressPool $backendPool -FrontendIPConfiguration
 $frontendipconfig2 -Protocol ”Udp” -FrontendPort 53 -BackendPort 53
-Probe $healthprobe -EnableFloatingIP  | Set-AzureRmLoadBalancer

Enable GSLB on each high availability pair

Now you’ve two front-end IP addresses for each ALB: ALB 1 and ALB 2. One IP address is for the LB
virtual server and the other for the GSLB site IP.

HA 1 has the following front-end IP addresses:

• FrontEndIPofALB1 (for LB vserver)

• PIPFORGSLB1 (GSLB IP)

HA 2 has the following front-end IP addresses:

• FrontEndIPofALB2 (for LB vserver)

• PIPFORGSLB2 (GSLB IP)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 738

NetScaler 12.0

The following commands are used for this scenario.

1 enable ns feature LB GSLB

2
3
4 add service dnssvc PIPFORGSLB1 ADNS 53
5
6
7 add gslb site site1 PIPFORGSLB1 -publicIP PIPFORGSLB1
8
9
10 add gslb site site2 PIPFORGSLB2 -publicIP PIPFORGSLB2
11
12
13 add gslb service site1_gslb_http_svc1 FrontEndIPofALB1 HTTP 80 -
publicIP FrontEndIPofALB1 -publicPort 80 -siteName site1
14
15
16 add gslb service site2_gslb_http_svc1 FrontEndIPofALB2 HTTP 80 -
publicIP FrontEndIPofALB2 -publicPort 80 -siteName site2
17
18
19 add gslb vserver gslb_http_vip1 HTTP
20
21
22 bind gslb vserver gslb_http_vip1 -serviceName site2_gslb_http_svc1
23
24
25 bind gslb vserver gslb_http_vip1 -serviceName site1_gslb_http_svc1
26
27
28 bind gslb vserver gslb_http_vip1 -domainName www.gslbindia.com -TTL 5

Related resources:

Configure GSLB on NetScaler VPX instances

Global Server Load Balancing

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 739

NetScaler 12.0

Configure address pools (IIP) for a Citrix Gateway appliance

January 6, 2019

Contributed by:
C

In some situations, users who connect with the Citrix Gateway Plug-in need a unique IP address for a
NetScaler Gateway appliance. When you enable address pools (also known as IP pooling) for a group,
the Citrix Gateway appliance can assign a unique IP address alias to each user. You configure address
pools by using intranet IP (IIP) addresses.

You can configure address pools on a Citrix Gateway appliance deployed on Azure by following this
2-step procedure:

• Registering the private IP addresses that will be used in the address pool, in Azure
• Configuring address pools in the Citrix Gateway appliance

Register a private IP address in the Azure portal

In Azure, you can deploy a NetScaler VPX instance with multiple IP addresses. You can add IP ad-
dresses to a VPX instance in two ways:

a. While provisioning a VPX instance

For more information about how to add multiple IP addresses while provisioning a VPX instance, see
Configure multiple IP addresses for a NetScaler standalone instance. To add IP addresses by using
PowerShell commands while provisioning a VPX instance, see Configure multiple IP addresses for a
NetScaler VPX instance in standalone mode by using PowerShell commands.

b. After provisioning a VPX instance

After you’ve provisioned a VPX instance, follow these steps to register a private IP address in the Azure
portal, which you configure as an address pool in the Citrix Gateway appliance.

1. From Azure Resource Manager (ARM), go to the already created NetScaler VPX instance > Network
interfaces. Choose the network interface which is bound to a subnet to which the IIP that you want
to register belongs.

2. Click IP Configurations, and then click Add.

3. Provide the required details as shown in the example below and click OK.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 740

NetScaler 12.0

Configure address pools in the Citrix Gateway appliance

For more information about how to configure address pools on the Citrix Gateway, see this Configuring
Address Pools.

Limitation: You can not bind a range of IIP addresses to users. Every IIP address that is used in an
address pool should be registered.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure multiple IP addresses for a NetScaler VPX instance in

standalone mode by using PowerShell commands

January 6, 2019

Contributed by:
C

In an Azure environment, a NetScaler VPX virtual appliance can be deployed with multiple NICs. Each
NIC can have multiple IP addresses. This section describes how to deploy a NetScaler VPX instance
with a single NIC and multiple IP addresses, by using PowerShell commands. You can use the same
script for multi-NIC and multi-IP deployment.

Note

In this document, IP-Config refers to a pair of IP addresses, public IP and private IP, that is asso-
ciated with an inidivual NIC. For more information, see the Azure terminology section.

Use case

In this use case, a single NIC is connected to a virtual network (VNET). The NIC is associated with three
IP configurations, as shown in the following table.

IPConfig Assocaited with

IPConfig-1 Static public IP address; static private IP

address
IPConfig-2 Static public IP address; static private address
IPConfig-3 Static private IP addres

© 1999-2018 Citrix Systems, Inc. All rights reserved. 741

NetScaler 12.0

Note

IPConfig-3 is not associated with any public IP address.

Diagram: Topology

Here is the visual representation of the use case.

Note

In a multi-NIC, multi-IP Azure NetScaler VPX deployment, the private IP address associated with
the primary (first) IPConfig of the primary (first) NIC is automatically added as the management
NSIP address of the appliance. The remaining private IP addresses associated with IPConfigs
must be added in the VPX instance as VIPs or SNIPs by using the “add ns ip” command, as deter-
mined by your requirements.

Here is the summary of the steps required for configuring multiple IP addresses for a NetScaler VPX
virtual appliance in standalone mode:

1. Create Resource Group

2. Create Storage Account
3. Create Availability Set
4. Create NSG
5. Create Virtual Network
6. Create Public IP Address
7. Assign IP Configuration
8. Create NIC
9. Create NetScaler VPX Instance
10. Check NIC Configurations
11. Check VPX-side Configurations

Script

Parameters

Following are sample parameters settings for the use case in this document. You can use different
settings if you wish.

$locName=”westcentralus”

$rgName=”Azure-MultiIP”

$nicName1=”VM1-NIC1”

$vNetName=”Azure-MultiIP-vnet”

$vNetAddressRange=”11.6.0.0/16”

© 1999-2018 Citrix Systems, Inc. All rights reserved. 742

NetScaler 12.0

$frontEndSubnetName=”frontEndSubnet”

$frontEndSubnetRange=”11.6.1.0/24”

$prmStorageAccountName=”multiipstorage”

$avSetName=”multiip-avSet”

$vmSize=”Standard_DS4_V2” (This parameter creates a VM with upto four NICs.)

Note: The minimum requirement for a VPX instance is 2 vCPUs and 2GB RAM.

$publisher=”citrix”

$offer=”netscalervpx110-6531” (You can use different offers.)

$sku=”netscalerbyol” (According to your offer, the SKU can be different.)

$version=”latest”

$pubIPName1=”PIP1”

$pubIPName2=”PIP2”

$domName1=”multiipvpx1”

$domName2=”multiipvpx2”

$vmNamePrefix=”VPXMultiIP”

$osDiskSuffix=”osmultiipalbdiskdb1”

Network Security Group (NSG)-related information:

$nsgName=”NSG-MultiIP”

$rule1Name=”Inbound-HTTP”

$rule2Name=”Inbound-HTTPS”

$rule3Name=”Inbound-SSH”

$IpConfigName1=”IPConfig1”

$IPConfigName2=”IPConfig-2”

$IPConfigName3=”IPConfig-3”

1. Create Resource Group

1 New-AzureRmResourceGroup -Name $rgName -Location $locName

© 1999-2018 Citrix Systems, Inc. All rights reserved. 743

NetScaler 12.0

2. Create Storage Account

1 $prmStorageAccount = New-AzureRMStorageAccount -Name

$prmStorageAccountName -ResourceGroupName $rgName -Type Standard_LRS
-Location $locName

3. Create Availability Set

1 $avSet = New-AzureRMAvailabilitySet -Name $avSetName -ResourceGroupName

$rgName -Location $locName

4. Create Network Security Group (NSG)

1. Add rules. You must add a rule to the NSG for any port that serves traffic.

1 $rule1=New-AzureRmNetworkSecurityRuleConfig -Name $rule1Name -

Description ”Allow HTTP” -Access Allow -Protocol Tcp -Direction
Inbound -Priority 101  -SourceAddressPrefix Internet -
SourcePortRange * -DestinationAddressPrefix * -DestinationPortRange
80
2 $rule2=New-AzureRmNetworkSecurityRuleConfig -Name $rule2Name -
Description ”Allow HTTPS” -Access Allow -Protocol Tcp -Direction
Inbound -Priority 110  -SourceAddressPrefix Internet -
SourcePortRange * -DestinationAddressPrefix * -DestinationPortRange
443
3 $rule3=New-AzureRmNetworkSecurityRuleConfig -Name $rule3Name -
Description ”Allow SSH” -Access Allow -Protocol Tcp -Direction
Inbound -Priority 120 -SourceAddressPrefix Internet -SourcePortRange
* -DestinationAddressPrefix * -DestinationPortRange 22

2. Create NSG object.

1 $nsg=New-AzureRmNetworkSecurityGroup -ResourceGroupName $rgName -

Location $locName -Name $nsgName -SecurityRules $rule1,$rule2,$rule3

5. Create Virtual Network

1. Add subnets.

1 $frontendSubnet=New-AzureRmVirtualNetworkSubnetConfig -Name
$frontEndSubnetName -AddressPrefix $frontEndSubnetRange

© 1999-2018 Citrix Systems, Inc. All rights reserved. 744

NetScaler 12.0

2. Add virtual network object.

1 $vnet=New-AzureRmVirtualNetwork -Name $vNetName -ResourceGroupName

$rgName -Location $locName -AddressPrefix $vNetAddressRange -Subnet
$frontendSubnet

3. Retrieve subnets.

1 $subnetName=”frontEndSubnet”
2 $subnet1=$vnet.Subnets|?{
3 $_.Name -eq $subnetName }

6. Create Public IP Address

1 $pip1=New-AzureRmPublicIpAddress -Name $pubIPName1 -ResourceGroupName

$rgName -DomainNameLabel $domName1 -Location $locName -
AllocationMethod Static
2 $pip2=New-AzureRmPublicIpAddress -Name $pubIPName2 -ResourceGroupName
$rgName -DomainNameLabel $domName2 -Location $locName -
AllocationMethod Static

Note

Check availability of domain names before using.

Allocation method for IP addresses can be dynamic or static.

7. Assign IP Configuration

In this use case, consider the following points before assigning IP addresses:

• IPConfig-1 belongs to subnet1 of VPX1.

• IPConfig-2 belongs to subnet 1 of VPX1.
• IPConfig-3 belongs to subnet 1 of VPX1.

Note

When you assign multiple IP configurations to a NIC, one configuration must be assigned as pri-
mary.

1 $IPAddress1=”11.6.1.27”
2 $IPConfig1=New-AzureRmNetworkInterfaceIpConfig -Name $IPConfigName1 -
Subnet $subnet1 -PrivateIpAddress $IPAddress1 -PublicIpAddress $pip1
‒ Primary

© 1999-2018 Citrix Systems, Inc. All rights reserved. 745

NetScaler 12.0

3 $IPAddress2=”11.6.1.28”
4 $IPConfig2=New-AzureRmNetworkInterfaceIpConfig -Name $IPConfigName2 -
Subnet $subnet1 -PrivateIpAddress $IPAddress2 -PublicIpAddress $pip2
5 $IPAddress3=”11.6.1.29”
6 $IPConfig3=New-AzureRmNetworkInterfaceIpConfig -Name $IPConfigName3 -
Subnet $subnet1 -PrivateIpAddress $IPAddress3 -Primary

Use a valid IP address that meets your subnet requirements and check its availability.

8. Create NIC

1 $nic1=New-AzureRmNetworkInterface -Name $nicName1 -ResourceGroupName

$rgName -Location $locName -IpConfiguration $IpConfig1,$IpConfig2,
$IPConfig3 -NetworkSecurityGroupId $nsg.Id

9. Create NetScaler VPX Instance

1. Initialize variables.

1 $suffixNumber = 1
2 $vmName = $vmNamePrefix + $suffixNumber

2. Create VM config object.

1 $vmConfig=New-AzureRMVMConfig -VMName $vmName -VMSize $vmSize -

AvailabilitySetId $avSet.Id

3. Set credentials, OS, and image.

1 $cred=Get-Credential -Message ”Type the name and password for VPX login
.”
2 $vmConfig=Set-AzureRMVMOperatingSystem -VM $vmConfig -Linux -
ComputerName $vmName -Credential $cred
3 $vmConfig=Set-AzureRMVMSourceImage -VM $vmConfig -PublisherName
$publisher -Offer $offer -Skus $sku -Version $version

4. Add NIC.

1 $vmConfig=Add-AzureRMVMNetworkInterface -VM $vmConfig -Id $nic1.Id -

Primary

© 1999-2018 Citrix Systems, Inc. All rights reserved. 746

NetScaler 12.0

Note

In a multi-NIC VPX deployment, one NIC should be primary. So, “-Primary” needs to be appended
while adding that NIC to the VPX instance.

5. Specify OS disk and create VM.

1 $osDiskName=$vmName + ”-” + $osDiskSuffix1

2 $osVhdUri=$prmStorageAccount.PrimaryEndpoints.Blob.ToString() + ”vhds/”
+ $osDiskName + ”.vhd”
3 $vmConfig=Set-AzureRMVMOSDisk -VM $vmConfig -Name $osDiskName -VhdUri
$osVhdUri -CreateOption fromImage
4 Set-AzureRmVMPlan -VM $vmConfig -Publisher $publisher -Product $offer -
Name $sku
5 New-AzureRMVM -VM $vmConfig -ResourceGroupName $rgName -Location
$locName

10. Check NIC Configurations

After the VPX instance starts, you can check the IP addresses allocated to IPConfigs of the VPX NIC by
using the following command.

1 $nic.IPConfig

11. Check VPX-side Configurations

When the NetScaler VPX instance starts, a private IP address associated with primary IPconfig of the
primary NIC is added as the NSIP address. The remaining private IP addresses must be added as VIP
or SNIP addresses, as determined by your requirements. Use the following command.

1 add nsip <Private IPAddress><netmask> -type VIP/SNIP

You’ve now configured multiple IP addresses for a NetScaler VPX instance in standalone mode. For
additional information about how to configure multiple IP addresses for a NetScaler VPX instance in
standalone mode, see the NetScaler VPX deployments in Microsoft Azure video.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 747

NetScaler 12.0

Configure multiple Azure VIPs for a standalone or high availability VPX

instance

January 6, 2019
Contributed by:
C
In Azure Resource Manager (ARM), configure multiple public virtual IP addresses (VIPs) for both single
NetScaler VPX deployment, and also for high availability (HA) deployment.
Note: Multiple VIPs can be configured for external load balancers only.
For deploying NetScaler VPX instances in both single mode and high availability mode, you have to
use PowerShell commands alone, as you can create multiple front-end IP addresses (FIP) through
PowerShell only.

Deploy a NetScaler VPX in standalone mode

This section provides PowerShell commands to deploy a NetScaler VPX in a standalone mode with
multiple front-end IPs mapped to a single back-end pool.
Configure multiple FIPs, back-end pools, LB rules, and inbound NAT rules as part of configuring Azure
load balancer.
Make sure that the following conditions are met in a single NetScaler VPX deployment:
1. A back-end pool contains only one NetScaler VPX instance.
2. Two load balancer rules are defined and are mapped to the following two VIPs:
a) VIP1:80 > Back-end Pool 1:10080
b) VIP2:80 > Back-end Pool 1:10081
3. A load balancer rule is defined to map VIP1:10080 > Back-end Pool 1:80, to access NetScaler VPX
user interface.
4. An inbound NAT rule is defined to map VIP1:22 > Back-end Pool 1:22 to access NetScaler VPX
through SSH.
The following image illustrates how you can configure multiple cloud service IP addresses on Azure
Resource Manager for NetScaler virtual servers.
Run the following PowerShell commands to deploy a NetScaler VPX instance in a standalone mode:

1. Create resource group

$rgName=”<resource group name>”

© 1999-2018 Citrix Systems, Inc. All rights reserved. 748

NetScaler 12.0

$locName=”<location name, such as West US>”

Command:

New-AzureRmResourceGroup -Name $rgName -Location $locName

For example:

1 $rgName = ”ARM-LB-NS”
2
3 $locName = ”East Asia”
4
5 New-AzureRmResourceGroup -Name $rgName -Location $locName

2. Create storage account

You must select a globally unique name for your storage account that contains only lowercase letters
and numbers.

$saName=”<storage account name>”

$saType=”<storage account type, specify one: Standard_LRS, Standard_GRS, Standard_RAGRS, or

Platinum_LRS>”

Command

1 New-AzureRmStorageAccount -Name $saName -ResourceGroupName $rgName -

Type $saType -Location $locName

For example:

1 $saName=”vpxstorage”
2
3 $saType=”Standard\_LRS”
4
5 New-AzureRmStorageAccount -Name $saName -ResourceGroupName $rgName -
Type $saType -Location $locName

3. Create availability set

$avName=”<availability set name>”

Command:

1 New-AzureRmAvailabilitySet -Name $avName -ResourceGroupName $rgName -

Location $locName

© 1999-2018 Citrix Systems, Inc. All rights reserved. 749

NetScaler 12.0

For example:

1 $avName=”avNSSet”

4. Create virtual network and subnet

Add new virtual network with at least one subnet, if it is not created previously.

$vnetName = “LBVnet”

Commands:

Create subnets:

1 $frontendSubnet=New-AzureRmVirtualNetworkSubnetConfig -Name  
frontendSubnet -AddressPrefix 10.0.1.0/24

(Configure this parameter value as per your requirement)

1 $backendSubnet=New-AzureRmVirtualNetworkSubnetConfig -Name
backendSubnet -AddressPrefix 10.0.2.0/24

Create virtual network:

1 New-AzureRmVirtualNetwork -Name $vnetName -ResourceGroupName $rgName -

Location $locName -AddressPrefix 10.0.0.0/16 -Subnet $frontendSubnet
,$backendSubnet

5. Create public IP address

The number of public IPs created should be equal to number of External VIPs required.

• Before using, check for the availability of the value for DomainNameLabel.
• Create two VIPs.

Commands:

1 $pubName1 =”PublicIp1”
2
3 $dnsName1=”nsvpx1”
4
5 $pubName2 =”PublicIp2”
6
7 $dnsName2=”nsvpx2”
8

© 1999-2018 Citrix Systems, Inc. All rights reserved. 750

NetScaler 12.0

9 $publicIP1 = New-AzureRmPublicIpAddress -Name $pubName1 -

ResourceGroupName $rgName -Location $locName -AllocationMethod
Static -DomainNameLabel $dnsName1
10
11 $publicIP2 = New-AzureRmPublicIpAddress -Name $pubName2 -
ResourceGroupName $rgName -Location $locName -AllocationMethod
Static -DomainNameLabel $dnsName2

6. Create front-end IP for specified public IP addresses

$FIPName1 =”VIP1”

$FIPName2=”VIP2”

Commands:

1 $frontendIP1 = New-AzureRmLoadBalancerFrontendIpConfig -Name $FIPName1

-PublicIpAddress $publicIP1
2
3 $frontendIP2 = New-AzureRmLoadBalancerFrontendIpConfig -Name $FIPName2
-PublicIpAddress $publicIP2

7. Create back-end pool

$BEPool1 = “backend-Pool1”

Command:

1 $beaddresspool1= New-AzureRmLoadBalancerBackendAddressPoolConfig -Name

$BEPool1

8. Create health probe

Create TCP health probe with port 9000 and interval 5 seconds.

Command:

1 $healthProbe = New-AzureRmLoadBalancerProbeConfig -Name HealthProbe -

Protocol Tcp -Port 9000 -IntervalInSeconds 5 -ProbeCount 2

© 1999-2018 Citrix Systems, Inc. All rights reserved. 751

NetScaler 12.0

9. Create load balancer rule

For each frond end IP and service, we need to create lbRule.

Here back-end address pool can contain set of virtual machines. For single VPX deployment only
single VPX instance will be part of this pool.
Note: Combined values for front-end IP configuration, back-end address pool, front-end port, back-
end port parameters should not be same for any two rules.
For example, every FIP/VIP access, and HTTP service uses front-end port 80. As back-end pool is same,
back-end port needs to be used differently for each load balancer rule.
Commands:

1 $lbrule1 = New-AzureRmLoadBalancerRuleConfig -Name ”HTTP1” -

FrontendIpConfiguration $frontendIP1 -BackendAddressPool 
$beAddressPool1 -Probe $healthProbe -Protocol Tcp -FrontendPort 80 -
BackendPort 10080
2
3 $lbrule2 = New-AzureRmLoadBalancerRuleConfig -Name ”HTTP2” -
FrontendIpConfiguration $frontendIP2 -BackendAddressPool 
$beAddressPool1 -Probe $healthProbe -Protocol Tcp -FrontendPort 80 -
BackendPort 10081

LB rule to access http service of NS can be added in the following way:

Command:

1 $lbrule3 = New-AzureRmLoadBalancerRuleConfig -Name ”HTTPNS” -

FrontendIpConfiguration $frontendIP1 -BackendAddressPool 
$beAddressPool1 -Probe $healthProbe -Protocol Tcp -FrontendPort
10080 -BackendPort 80

10. Create Inbound NAT Rules

Create NAT rules for services that does not require to be load balanced.
For example, create an ssh access to VPX instance.
Protocol - FrontEndPort - BackendPort triplet should not be same for two NAT rules belonging to same
front-end IP.
Command:

1 $inboundNATRule1= New-AzureRmLoadBalancerInboundNatRuleConfig -Name

SSH1 -FrontendIpConfiguration $frontendIP1 -Protocol TCP -
FrontendPort 22 -BackendPort 22

© 1999-2018 Citrix Systems, Inc. All rights reserved. 752

NetScaler 12.0

11. Create Load Balancer

Create load balancer with all of the above defined rules, front-end IPs, and a back-end pool.

Command:

1 $lbName = ”NSALB”
2
3 $NRPLB = New-AzureRmLoadBalancer -ResourceGroupName $rgName -Name
$lbName -Location $locName -InboundNatRule $inboundNATRule1 -
FrontendIpConfiguration $frontendIP1, $frontendIP2 -
LoadBalancingRule $lbrule1, $lbrule2, $lbrule3 -BackendAddressPool
$beAddressPool1  -Probe $healthProbe

12. Create NIC

Create a NIC and associate it with the NetScaler VPX instance.

Commands:

1 $nicName=”NIC1”
2
3 $lbName=”NSALB”
4
5 $bePoolIndex=0
6
7 $natRuleIndex=0
8
9 $subnetIndex=0 ß Frontend subnet index
10
11 $lb=Get-AzureRmLoadBalancer -Name $lbName -ResourceGroupName $rgName
12
13 $nic1=New-AzureRmNetworkInterface -Name $nicName -ResourceGroupName
$rgName -Location $locName -Subnet $vnet.Subnets\[$subnetIndex\] -
LoadBalancerBackendAddressPool $lb.BackendAddressPools\[$bePoolIndex
\] -LoadBalancerInboundNatRule $lb.InboundNatRules\[$natRuleIndex\]

13. Create NetScaler VPX Instance

Create NetScaler VPX instance from MarketPlace image and attach the NIC to the virtual instance.

Commands:

1 $vmName=”VPX1”

© 1999-2018 Citrix Systems, Inc. All rights reserved. 753

NetScaler 12.0

2
3 $vmSize=”Standard\_A3” / ”Standard\_DS4”
4
5 $pubName=”citrix”
6
7 $skuName = ”netscalerbyol”
8
9 $offerName=”netscalervpx110-6531”
10
11 $avSet=Get-AzureRmAvailabilitySet -Name $avName -ResourceGroupName
$rgName
12
13 $vm1=New-AzureRmVMConfig -VMName $vmName -VMSize $vmSize -
AvailabilitySetId $avset.Id
14
15 $cred=Get-Credential -Message ”Type Credentials which will be used to
login to VPX instance”
16
17 $vm1=Set-AzureRmVMOperatingSystem -VM $vm1 -Linux -ComputerName $vmName
-Credential $cred -Verbose
18
19 $vm1=Set-AzureRmVMSourceImage -VM $vm1 -PublisherName $pubName -Offer
$offerName -Skus $skuName -Version ”latest”
20
21 $vm1=Add-AzureRmVMNetworkInterface -VM $vm1 -Id $nic1.Id
22
23 $diskName=”dynamic”
24
25 $storageAcc=Get-AzureRmStorageAccount -ResourceGroupName $rgName -Name
$saName
26
27 $osDiskUri1=$storageAcc.PrimaryEndpoints.Blob.ToString() + ”vhds1/” +
$diskName  + ”.vhd”
28
29 $vm1=Set-AzureRmVMOSDisk -VM $vm1 -Name $diskName -VhdUri $osDiskUri1 -
CreateOption fromImage
30
31 Set-AzureRmVMPlan -VM $vm1 -Publisher $pubName -Product $offerName -
Name $skuName
32
33 New-AzureRmVM -ResourceGroupName $rgName -Location $locName -VM $vm1

The above commands creates a NetScaler VPX instance, then add virtual servers to the NetScaler VPX
instance for the specified front end services.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 754

NetScaler 12.0

Deploying NetScaler VPX in High Availability Mode

This section provides PowerShell commands to deploy a NetScaler VPX in HA deployment with multi-
ple front-end IPs mapped to a single back-end pool.

Configure multiple FIPs, backend pools, load balance rules, and inbound NAT rules as part of the Azure
load balancer.

Make sure that the following conditions are met in HA deployment of NetScaler VPX instances:

1. A back-end pool contains two NetScaler VPX instances, which are part of HA.
2. Two load balancer rules are defined and are mapped to following two VIPs:
a) VIP1:80 > Back-end Pool 1:10080
b) VIP2:80 > Back-end Pool 1:10081
3. A load balancer rule is defined, which maps VIP1:10080 > Back-end Pool 1:80, to access NetScaler
VPX GUI.
4. Two inbound NAT rules are defined to map the following two VIPS:
a) VIP1:22 > Back-end Pool 1:22 to access NetScaler VPX Primary
b) VIP1:10022 > Back-end Pool-1:22 to access NetScaler VPX Secondary through SSH

All services that are defined as part of Azure load balancer rules will get load balanced. That is, if the
primary VPX fails, the secondary VPX will take care of all of the services in Active-Passive HA deploy-
ment.

The following image illustrates how you can configure multiple cloud service IP addresses on Azure
Resource Manager for NetScaler virtual servers in HA mode.

1. Create Resource Group

$rgName=”<resource group name>”

$locName=”<location name, such as West US>”

Commands:

1 New-AzureRmResourceGroup -Name $rgName -Location $locName

For example:

1 $rgName = ”ARM-Mult-VIP-HA”
2
3 $locName = ”East Asia”
4
5 New-AzureRmResourceGroup -Name $rgName -Location $locName

© 1999-2018 Citrix Systems, Inc. All rights reserved. 755

NetScaler 12.0

2. Create Storage Account

You must select a globally unique name for your storage account that contains only lowercase letters
and numbers.

$saName=”<storage account name>”

$saType=”<storage account type, specify one: Standard_LRS, Standard_GRS, Standard_RAGRS, or

Platinum_LRS>”

Commands:

1 New-AzureRmStorageAccount -Name $saName -ResourceGroupName $rgName -

Type $saType -Location $locName

For example:

1 $saName=”vpxstorage1”
2
3 $saType=”Standard\_LRS”
4
5 New-AzureRmStorageAccount -Name $saName -ResourceGroupName $rgName -
Type $saType -Location $locName

3. Create Availability Set

$avName=”<availability set name>”

Command:

1 New-AzureRmAvailabilitySet -Name $avName -ResourceGroupName $rgName -

Location $locName

For example:

$avName=”avNSSetARM”

4. Create Virtual Network and Subnet

Add new virtual network with at least one subnet if it is not created previously.

$vnetName = “LBVnet”

Commands:

Create subnets:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 756

NetScaler 12.0

1 $frontendSubnet=New-AzureRmVirtualNetworkSubnetConfig -Name  
frontendSubnet -AddressPrefix 10.0.7.0/24

(this parameter value should be as per your requirement)

1 $backendSubnet=New-AzureRmVirtualNetworkSubnetConfig -Name
backendSubnet -AddressPrefix 10.0.8.0/24

Create Virtual Network:

1 New-AzureRmVirtualNetwork -Name $vnetName -ResourceGroupName $rgName -

Location $locName -AddressPrefix 10.0.0.0/16 -Subnet $frontendSubnet
,$backendSubnet

5. Create Public IP Address

The number of public IP addresses created should be equal to the number of external VIPs required.
• Before using, check for the availability of the value for Domain.Name.Label.
• Create two VIPs.
Commands:
$pubName1 =”PublicIp1”
$dnsName1=”nsvpx1”
$pubName2 =”PublicIp2”
$dnsName2=”nsvpx2”

1 $publicIP1 = New-AzureRmPublicIpAddress -Name $pubName1 -

ResourceGroupName $rgName -Location $locName -AllocationMethod
Static -DomainNameLabel $dnsName1
2
3 $publicIP2 = New-AzureRmPublicIpAddress -Name $pubName2 -
ResourceGroupName $rgName -Location $locName -AllocationMethod
Static -DomainNameLabel $dnsName2

6. Create Front-end IP Addresses

$FIPName1 = “VIP1”
$FIPName2=”VIP2”
Commands:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 757

NetScaler 12.0

1 $frontendIP1 = New-AzureRmLoadBalancerFrontendIpConfig -Name $FIPName1

-PublicIpAddress $publicIP1
2
3 $frontendIP2 = New-AzureRmLoadBalancerFrontendIpConfig -Name $FIPName2
-PublicIpAddress $publicIP2

7. Create back-end pool

$BEPool1 = “backend-Pool1”

Command:

1 $beaddresspool1= New-AzureRmLoadBalancerBackendAddressPoolConfig -Name

$BEPool1

8. Create health probe

Create TCP health probe with port 9000 and interval 5 seconds.

Command:

1 $healthProbe = New-AzureRmLoadBalancerProbeConfig -Name HealthProbe -

Protocol Tcp -Port 9000 -IntervalInSeconds 5 -ProbeCount 2

9. Create Load Balancer Rules

For each frond end IP and service, you have to create a separate load balancer rule.

Back-end address pool can contain set of virtual machines. For a single NetScaler VPX deployment,
only single NetScaler VPX instance will be part of this pool.

Note: Combined values for front-end IP configuration, back-end address pool, front-end port, back-
end port parameters should not be the same for any two rules.

Examples:

Each FIP/VIP access and HTTP service uses front-end port 80. As back-end pool is same, back-end port
has to be used differently for each load balancer rule.

Command:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 758

NetScaler 12.0

1 $lbrule1 = New-AzureRmLoadBalancerRuleConfig -Name ”HTTP1” -

FrontendIpConfiguration $frontendIP1 -BackendAddressPool 
$beAddressPool1 -Probe $healthProbe -Protocol Tcp -FrontendPort 80 -
BackendPort 10080
2
3 $lbrule2 = New-AzureRmLoadBalancerRuleConfig -Name ”HTTP2” -
FrontendIpConfiguration $frontendIP2 -BackendAddressPool 
$beAddressPool1 -Probe $healthProbe -Protocol Tcp -FrontendPort 80 -
BackendPort 10081

Load balancer configuration rule to access the HTTP service of a NetScaler VPX instance can be added
in the following way:

Command:

1 $lbrule3 = New-AzureRmLoadBalancerRuleConfig -Name ”HTTPNS” -

FrontendIpConfiguration $frontendIP1 -BackendAddressPool 
$beAddressPool1 -Probe $healthProbe -Protocol Tcp -FrontendPort
10080 -BackendPort 80

10. Create Inbound NAT Rules

Create NAT rules for services that does not require to be load balanced.

For example, create an ssh access to VPX instance.

Note: Protocol - Front-end Port - Back-end Port triplet should not be the same for two NAT rules be-
longing to the same front-end IP address.

Commands:

1 $inboundNATRule1= New-AzureRmLoadBalancerInboundNatRuleConfig -Name

SSH1 -FrontendIpConfiguration $frontendIP1 -Protocol TCP -
FrontendPort 22 -BackendPort 22
2 $inboundNATRule2= New-AzureRmLoadBalancerInboundNatRuleConfig -Name
SSH2 -FrontendIpConfiguration $frontendIP1 -Protocol TCP -
FrontendPort 10022 -BackendPort 22

11. Create Load Balancer

Create load balancer with all of the above defined rules, front-end IPs, and a back-end pool.

Command:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 759

NetScaler 12.0

1 $lbName =”NSALB”
2
3 $NRPLB = New-AzureRmLoadBalancer -ResourceGroupName $rgName -Name
$lbName -Location $locName -InboundNatRule $inboundNATRule1,
$inboundNATRule2 -FrontendIpConfiguration $frontendIP1, $frontendIP2
-LoadBalancingRule $lbrule1, $lbrule2, $lbrule3 -BackendAddressPool
$beAddressPool1  -Probe $healthProbe

12. Create NIC

Create a NIC and associate it with the NetScaler VPX instance.

Commands:

1 $nicName=”NIC1”
2
3 $lbName=”NSALB”
4
5 $bePoolIndex=0
6
7 $natRuleIndex=0
8
9 $subnetIndex=0 ß Frontend subnet index
10
11 $lb=Get-AzureRmLoadBalancer -Name $lbName -ResourceGroupName $rgName
12
13 $nic1=New-AzureRmNetworkInterface -Name $nicName -ResourceGroupName
$rgName -Location $locName -Subnet $vnet.Subnets\[$subnetIndex\] -
LoadBalancerBackendAddressPool $lb.BackendAddressPools\[$bePoolIndex
\] -LoadBalancerInboundNatRule $lb.InboundNatRules\[$natRuleIndex\]
14
15 $nicName=”NIC2 ”
16
17 $lbName=”NSALB”
18
19 $bePoolIndex=0
20
21 $natRuleIndex=1ß 2nd SSH rule
22
23 $subnetIndex=0
24
25 $nic2=New-AzureRmNetworkInterface -Name $nicName -ResourceGroupName
$rgName -Location $locName -Subnet $vnet.Subnets\[$subnetIndex\] -

© 1999-2018 Citrix Systems, Inc. All rights reserved. 760

NetScaler 12.0

LoadBalancerBackendAddressPool $lb.BackendAddressPools\[$bePoolIndex
\] -LoadBalancerInboundNatRule $lb.InboundNatRules\[$natRuleIndex\]

13. Create NetScaler VPX Instances

Create a NetScaler VPX instance from MarketPlace image and attach a NIC to it.

Commands:

1 $vmName=”VPX1”
2
3 $vmSize=”Standard\_A3”
4
5 $pubName=”citrix”
6
7 $skuName = ”netscalerbyol”
8
9 $offerName=”netscalervpx110-6531”
10
11 $avSet=Get-AzureRmAvailabilitySet -Name $avName -ResourceGroupName
$rgName
12
13 $vm1=New-AzureRmVMConfig -VMName $vmName -VMSize $vmSize -
AvailabilitySetId $avset.Id
14
15 $cred=Get-Credential -Message ”Type Credentials which will be used to
login to VPX instance”
16
17 $vm1=Set-AzureRmVMOperatingSystem -VM $vm1 -Linux -ComputerName $vmName
-Credential $cred -Verbose
18
19 $vm1=Set-AzureRmVMSourceImage -VM $vm1 -PublisherName $pubName -Offer
$offerName -Skus $skuName -Version ”latest”
20
21 $vm1=Add-AzureRmVMNetworkInterface -VM $vm1 -Id $nic1.Id
22
23 $diskName=”dynamic”
24
25 $storageAcc=Get-AzureRmStorageAccount -ResourceGroupName $rgName -Name
$saName
26
27 $osDiskUri1=$storageAcc.PrimaryEndpoints.Blob.ToString() + ”vhds1/” +
$diskName  + ”.vhd”
28

© 1999-2018 Citrix Systems, Inc. All rights reserved. 761

NetScaler 12.0

29 $vm1=Set-AzureRmVMOSDisk -VM $vm1 -Name $diskName -VhdUri $osDiskUri1 -

CreateOption fromImage
30
31 Set-AzureRmVMPlan -VM $vm1 -Publisher $pubName -Product $offerName -
Name $skuName
32
33 New-AzureRmVM -ResourceGroupName $rgName -Location $locName -VM $vm1
34
35 $vmName=”VPX2”
36
37 $vmSize=”Standard\_A3”
38
39 $pubName=”citrix”
40
41 $skuName = ”netscalerbyol”
42
43 $offerName=”netscalervpx110-6531”
44
45 $avSet=Get-AzureRmAvailabilitySet ‒ Name $avName ‒ ResourceGroupName
$rgName
46
47 $vm2=New-AzureRmVMConfig -VMName $vmName -VMSize $vmSize -
AvailabilitySetId $avset.Id
48
49 $cred=Get-Credential -Message ”Type Credentials which will be used to
login to VPX instance”
50
51 $vm2=Set-AzureRmVMOperatingSystem -VM $vm2 -Linux -ComputerName $vmName
-Credential $cred -Verbose
52
53 $vm2=Set-AzureRmVMSourceImage -VM $vm2 -PublisherName $pubName -Offer
$offerName -Skus $skuName -Version ”latest”
54
55 $vm2=Add-AzureRmVMNetworkInterface -VM $vm2 -Id $nic2.Id
56
57 $diskName=”dynamic ”
58
59 $storageAcc=Get-AzureRmStorageAccount -ResourceGroupName $rgName -Name
$saName
60
61 $osDiskUri2=$storageAcc.PrimaryEndpoints.Blob.ToString() + ”vhds2/” +
$diskName  + ”.vhd”
62
63 $vm1=Set-AzureRmVMOSDisk -VM $vm2 -Name $diskName -VhdUri $osDiskUri2 -
CreateOption fromImage

© 1999-2018 Citrix Systems, Inc. All rights reserved. 762

NetScaler 12.0

64
65 Set-AzureRmVMPlan -VM $vm2 -Publisher $pubName -Product $offerName -
Name $skuName
66
67 New-AzureRmVM -ResourceGroupName $rgName -Location $locName -VM $vm2

14. Create high availability

When both NetScaler VPX instances are running, connect to both VPX instances through SSH to con-
figure the virtual machines.

1. To configure Active-Passive HA, run “add HA node #nodeID” command on both nodes, and then
run configuration commands on Primary VPX instance.

2. To configure Active-Active HA, run same set of configuration commands on both nodes.

Azure ARM components

This table lists those of the Azure Resource Manager (ARM) components that can be created using
PowerShell, and those that can be created using the Azure Resource Manager portal.

- PowerShell ARM Portal

Resource group Yes Yes

Storage account Yes Yes
Availability set Yes Yes
Virtual network and subnet Yes Yes
Public IP Yes Yes
Multiple front-end IP Yes No
Backend pool Yes Yes
Health probes Yes Yes
LB rules with each rule using Yes Yes
only one front-end IP
LB rules with each rule using Yes No
different front-end IP
Inbound NAT Rules with same Yes Yes
front-end IP for all

© 1999-2018 Citrix Systems, Inc. All rights reserved. 763

NetScaler 12.0

- PowerShell ARM Portal

Inbound NAT rules with Yes No

different front-end IP
External load balancer Yes Yes
Internal load balancer Yes Yes
Load balancer with front-end Yes Yes
IP
Load balancer with multiple Yes No
front-end IP
Network security group (NSG) Yes Yes
NIC Yes Yes
Virtual machine Yes Yes

1.
2. Citrix ADC
3. NetScaler 12.0

Additional PowerShell scripts for Azure deployment

November 2, 2018

Contributed by:
C

This section provides the PowerShell cmdlets with which you can perform the following configura-
tions in Azure PowerShell:

• Provision a NetScaler VPX standalone instance

• Provision a NetScaler VPX pair in a high availabilty setup with an Azure external load balancer
• Provision a NetScaler VPX pair in a high availability setup with Azure internal load balancer

Also see the following topics for configurations that you can perform by using PowerShell commands:

• Configure a high-availability setup with multiple IP addresses and NICs by using PowerShell
commands
• Configure GSLB on NetScaler VPX instances
• Configure GSLB on a NetScaler active-standby high-availability setup

© 1999-2018 Citrix Systems, Inc. All rights reserved. 764

NetScaler 12.0

• Configure multiple IP addresses for a NetScaler VPX instance in standalone mode by using Pow-
erShell commands
• Configure multiple Azure VIPs for a standalone VPX instance

Provision a NetScaler VPX standalone instance

1. Create a resource group

The resource group can include all the resources for the solution, or only those resources that you
want to manage as a group. The location specified here is the default location for resources in that
resource group. Make sure all commands to create a load balancer use the same resource group.

$rgName=”<resource group name>”

$locName=”<location name, such as West US>”

New-AzureRmResourceGroup -Name $rgName -Location $locName

For example:

1 $rgName = ”ARM-VPX”
2
3 $locName = ”West US”
4
5 New-AzureRmResourceGroup -Name $rgName -Location $locName

2. Create a storage account

Choose a unique name for your storage account that contains only lowercase letters and numbers.

$saName=”<storage account name>”

$saType=”<storage account type, specify one: Standard_LRS, Standard_GRS, Standard_RAGRS, or

Platinum_LRS>”

New-AzureRmStorageAccount -Name $saName -ResourceGroupName $rgName -Type $saType

-Location $locName

For example:

1 $saName=”vpxstorage”
2
3 $saType=”Standard\_LRS”
4
5 New-AzureRmStorageAccount -Name $saName -ResourceGroupName $rgName -
Type $saType -Location $locName

3. Create an availability set

© 1999-2018 Citrix Systems, Inc. All rights reserved. 765

NetScaler 12.0

Availability set helps to keep your virtual machines available during downtime, such as during main-
tenance. A load balancer configured with an availability set ensures that your application is always
available.

$avName=”<availability set name>”

New-AzureRmAvailabilitySet -Name $avName -ResourceGroupName $rgName -Location $locName

4. Create a virtual network

Add a new virtual network with at least one subnet, if the subnet was not created previously.

$FrontendAddressPrefix=”10.0.1.0/24”

$BackendAddressPrefix=”10.0.2.0/24”

$vnetAddressPrefix=”10.0.0.0/16”

$frontendSubnet=New-AzureRmVirtualNetworkSubnetConfig -Name frontendSubnet -AddressPrefix

$FrontendAddressPrefix

$backendSubnet=New-AzureRmVirtualNetworkSubnetConfig -Name backendSubnet -AddressPrefix $Back-

endAddressPrefix

New-AzureRmVirtualNetwork -Name TestNet -ResourceGroupName $rgName -Location $locName -

AddressPrefix $vnetAddressPrefix -Subnet $frontendSubnet,$backendSubnet

For example:

1 $frontendSubnet=New-AzureRmVirtualNetworkSubnetConfig -Name
frontendSubnet -AddressPrefix $FrontendAddressPrefix
2
3 $backendSubnet=New-AzureRmVirtualNetworkSubnetConfig -Name
backendSubnet -AddressPrefix $BackendAddressPrefix
4
5 New-AzureRmVirtualNetwork -Name TestNet -ResourceGroupName $rgName -
Location $locName -AddressPrefix $vnetAddressPrefix -Subnet
$frontendSubnet,$backendSubnet

5. Create a NIC

Create a NIC and associate the NIC with the NetScaler VPX instance. The front end Subnet created in
the above procedure is indexed at 0 and the back end Subnet is indexed at 1. Now create NIC in one
of the three following ways:

a) NIC with Public IP address

$nicName=”<name of the NIC of the VM>”

$pip = New-AzureRmPublicIpAddress -Name $nicName -ResourceGroupName $rgName -Location

$locName -AllocationMethod Dynamic

© 1999-2018 Citrix Systems, Inc. All rights reserved. 766

NetScaler 12.0

$nic = New-AzureRmNetworkInterface -Name $nicName -ResourceGroupName $rgName -Location

$locName -SubnetId $vnet.Subnets[$subnetIndex].Id -PublicIpAddressId $pip.Id

b) NIC with Public IP and DNS label

$nicName=”<name of the NIC of the VM>”

$domName=”<domain name label>”

$pip = New-AzureRmPublicIpAddress -Name $nicName -ResourceGroupName $rgName -DomainNameLabel

$domName -Location $locName -AllocationMethod Dynamic

Before assigning $domName, check it is available or not by using command:

Test-AzureRmDnsAvailability -DomainQualifiedName $domName -Location $locName

$nic = New-AzureRmNetworkInterface -Name $nicName -ResourceGroupName $rgName -Location

$locName -SubnetId $vnet.Subnets[$subnetIndex].Id -PublicIpAddressId $pip.Id

For example:

1 $nicName=”frontendNIC”
2
3 $domName=”vpxazure”
4
5 $pip = New-AzureRmPublicIpAddress -Name $nicName -ResourceGroupName
$rgName -DomainNameLabel $domName -Location $locName -
AllocationMethod Dynamic
6
7 $nic = New-AzureRmNetworkInterface -Name $nicName -ResourceGroupName
$rgName -Location $locName -SubnetId $vnet.Subnets\[0\].Id -
PublicIpAddressId $pip.Id

c) NIC with Dynamic Public Address and Static Private IP address

Make sure that the private (static) IP address you add to the VM should be the same range as that of
the subnet specified.

$nicName=”<name of the NIC of the VM>”

$staticIP=”<available static IP address on the subnet>”

$pip = New-AzureRmPublicIpAddress -Name $nicName -ResourceGroupName $rgName -Location

$locName -AllocationMethod Dynamic

$nic = New-AzureRmNetworkInterface -Name $nicName -ResourceGroupName $rgName -Location

$locName -SubnetId $vnet.Subnets[$subnetIndex].Id -PublicIpAddressId $pip.Id -PrivateIpAddress
$staticIP

6. Create a virtual object

© 1999-2018 Citrix Systems, Inc. All rights reserved. 767

NetScaler 12.0

$vmName=”<VM name>”

$vmSize=”<VM size string>”

$avSet=Get-AzureRmAvailabilitySet -Name $avName -ResourceGroupName $rgName

$vm=New-AzureRmVMConfig -VMName $vmName -VMSize $vmSize -AvailabilitySetId $avset.Id

7. Get the NetScaler VPX image

$pubName=”<Image publisher name>”

$offerName=”<Image offer name>”

$skuName=”<Image SKU name>”

$cred=Get-Credential -Message “Type the name and password of the local administrator account.”

Provide your credentials that is used to login into VPX

$vm=Set-AzureRmVMOperatingSystem -VM $vm -Linux -ComputerName $vmName -Credential $cred

-Verbose

$vm=Set-AzureRmVMSourceImage -VM $vm -PublisherName $pubName -Offer $offerName -Skus

$skuName -Version “latest”

$vm=Add-AzureRmVMNetworkInterface -VM $vm -Id $nic.Id

For example:

1 $pubName=”citrix”

The following command is used for displaying all offers from Citrix:

1 Get-AzureRMVMImageOffer -Location $locName -Publisher $pubName | Select

Offer
2
3 $offerName=”netscalervpx110-6531”

The following command is used to know sku offered by publisher for specific offer name:

Get-AzureRMVMImageSku -Location $locName Select Skus

-Publisher $pubName -Offer $offerName

8. Create a virtual machine

$diskName=”<name identifier for the disk in Azure storage, such as OSDisk>”

For example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 768

NetScaler 12.0

1 $diskName=”dynamic”
2
3 $pubName=”citrix”
4
5 $offerName=”netscalervpx110-6531”
6
7 $skuName=”netscalerbyol”
8
9 $storageAcc=Get-AzureRmStorageAccount -ResourceGroupName $rgName -Name
$saName
10
11 $osDiskUri=$storageAcc.PrimaryEndpoints.Blob.ToString() + ”vhds/” +
$diskName  + ”.vhd”
12
13 $vm=Set-AzureRmVMOSDisk -VM $vm -Name $diskName -VhdUri $osDiskUri -
CreateOption fromImage

When you create VM from Images present in marketplace, use the following command to specify the
VM plan:

Set-AzureRmVMPlan -VM $vm -Publisher $pubName -Product $offerName -Name $skuName

New-AzureRmVM -ResourceGroupName $rgName -Location $locName -VM $vm

Provision a NetScaler VPX pair in a high availabilty setup with an Azure external load
balancer

Log on to AzureRmAccount using your Azure user credentials.

1) Create a resource group

The location specified here is the default location for resources in that resource group. Make sure that
all commands used to create a load balancer use the same resource group.

$rgName=”<resource group name>”

$locName=”<location name, such as West US>”

New-AzureRmResourceGroup -Name $rgName -Location $locName

For example:

1 $rgName = ”ARM-LB-NS”
2
3 $locName = ”West US”
4
5 New-AzureRmResourceGroup -Name $rgName -Location $locName

© 1999-2018 Citrix Systems, Inc. All rights reserved. 769

NetScaler 12.0

2) Create a storage account

Choose a unique name for your storage account that contains only lowercase letters and numbers.
$saName=”<storage account name>”
$saType=”<storage account type, specify one: Standard_LRS, Standard_GRS, Standard_RAGRS, or
Platinum_LRS>”
New-AzureRmStorageAccount -Name $saName -ResourceGroupName $rgName -Type $saType
-Location $locName
For example:

1 $saName=”vpxstorage”
2
3 $saType=”Standard\_LRS”
4
5 New-AzureRmStorageAccount -Name $saName -ResourceGroupName $rgName -
Type $saType -Location $locName

3) Create an availability set

A load balancer configured with an availability set ensures that your application is always available.
$avName=”<availability set name>”
New-AzureRmAvailabilitySet -Name $avName -ResourceGroupName $rgName -Location $locName
4) Create a virtual network
Add a new virtual network with at least one subnet, if the subnet was not created previously.

1 $vnetName = ”LBVnet”
2
3 $FrontendAddressPrefix=”10.0.1.0/24”
4
5 $BackendAddressPrefix=”10.0.2.0/24”
6
7 $vnetAddressPrefix=”10.0.0.0/16”
8
9 $frontendSubnet=New-AzureRmVirtualNetworkSubnetConfig -Name
frontendSubnet -AddressPrefix $FrontendAddressPrefix
10
11 $backendSubnet=New-AzureRmVirtualNetworkSubnetConfig -Name
backendSubnet -AddressPrefix $BackendAddressPrefix
12
13 $vnet=New-AzureRmVirtualNetwork -Name $vnetName -ResourceGroupName
$rgName -Location $locName -AddressPrefix $vnetAddressPrefix -Subnet
$frontendSubnet,$backendSubnet

© 1999-2018 Citrix Systems, Inc. All rights reserved. 770

NetScaler 12.0

Note: Choose the AddressPrefix parameter value as per your requirement.

Assign front end and back end subnet to the virtual network that you created earlier in this step.

If the front end subnet is the first element of array vnet, subnetId should be $vnet.Subnets[0].Id.

If the front end subnet is the second element in the array, the subnetId should be $vnet.Subnets[1].Id,
and so on..

5) Configure front end IP address and create back end address pool

Configure a front end IP address for the incoming load balancer network traffic and create a back end
address pool to receive the load balanced traffic.

1 $pubName=”PublicIp1”
2
3 $publicIP1 = New-AzureRmPublicIpAddress -Name $pubName -
ResourceGroupName $rgName -Location $locName -AllocationMethod
Static -DomainNameLabel nsvpx

Note: Check for the availability of the value for DomainNameLabel.

1 $FIPName = ”ELBFIP”
2
3 $frontendIP1 = New-AzureRmLoadBalancerFrontendIpConfig -Name $FIPName -
PublicIpAddress $publicIP1
4
5 $BEPool = ”LB-backend-Pool”
6
7 $beaddresspool1= New-AzureRmLoadBalancerBackendAddressPoolConfig -Name
$BEPool

8) Create a health probe

Create a TCP health probe with port 9000 and interval 5 seconds.

1 $healthProbe = New-AzureRmLoadBalancerProbeConfig -Name HealthProbe -

Protocol Tcp -Port 9000 -IntervalInSeconds 5 -ProbeCount 2

9) Create a load balancing rule

Create a LB rule for each service that you are load balancing.

For example:

You can use the following example to load balance http service.

1 $lbrule1 = New-AzureRmLoadBalancerRuleConfig -Name ”HTTP-LB” -

FrontendIpConfiguration $frontendIP1 -BackendAddressPool 

© 1999-2018 Citrix Systems, Inc. All rights reserved. 771

NetScaler 12.0

$beAddressPool1 -Probe $healthProbe -Protocol Tcp -FrontendPort 80 -

BackendPort 80

10) Create inbound NAT rules

Create NAT rules for services that you are not load balancing.

For example, when creating a SSH access to a NetScaler VPX instance.

Note: Protocol-FrontEndPort-BackendPort triplet should not be the same for two NAT rules.

1 $inboundNATRule1= New-AzureRmLoadBalancerInboundNatRuleConfig -Name

SSH1 -FrontendIpConfiguration $frontendIP1 -Protocol TCP -
FrontendPort 22 -BackendPort 22
2
3 $inboundNATRule2= New-AzureRmLoadBalancerInboundNatRuleConfig -Name
SSH2 -FrontendIpConfiguration $frontendIP1 -Protocol TCP -
FrontendPort 10022 -BackendPort 22

11) Create a load balancer entity

Create the load balancer adding all objects (NAT rules, load balancer rules, probe configurations) to-
gether.

1 $lbName=”ELB”
2
3 $NRPLB = New-AzureRmLoadBalancer -ResourceGroupName $rgName -Name
$lbName -Location $locName -InboundNatRule $inboundNATRule1,
$inboundNATRule2 -FrontendIpConfiguration $frontendIP1 -
LoadBalancingRule $lbrule1 -BackendAddressPool $beAddressPool1 -
Probe $healthProbe

12) Create a NIC

Create two NICs and associate each NIC with each VPX instance

a) NIC1 with VPX1

For example:

1 $nicName=”NIC1”
2
3 $lbName=”ELB”
4
5 $bePoolIndex=0  
6
7 \* Rule indexes starts from 0.
8

© 1999-2018 Citrix Systems, Inc. All rights reserved. 772

NetScaler 12.0

9 $natRuleIndex=0
10
11 $subnetIndex=0
12
13 \* Frontend subnet index
14
15 $lb=Get-AzureRmLoadBalancer -Name $lbName -ResourceGroupName $rgName
16
17 $nic1=New-AzureRmNetworkInterface -Name $nicName -ResourceGroupName
$rgName -Location $locName -Subnet $vnet.Subnets\[$subnetIndex\] -
LoadBalancerBackendAddressPool $lb.BackendAddressPools\[$bePoolIndex
\] -LoadBalancerInboundNatRule $lb.InboundNatRules\[$natRuleIndex\]

b) NIC2 with VPX2

For example:

1 $nicName=”NIC2”
2
3 $lbName=”ELB”
4
5 $bePoolIndex=0
6
7 $natRuleIndex=1

* Second Inbound NAT (SSH) rule we need to use

$subnetIndex=0

* Frontend subnet index

1 $lb=Get-AzureRmLoadBalancer -Name $lbName -ResourceGroupName $rgName

2
3 $nic2=New-AzureRmNetworkInterface -Name $nicName -ResourceGroupName
$rgName -Location $locName -Subnet $vnet.Subnets\[$subnetIndex\] -
LoadBalancerBackendAddressPool $lb.BackendAddressPools\[$bePoolIndex
\] -LoadBalancerInboundNatRule  $lb.InboundNatRules\[$natRuleIndex\]

13) Create NetScaler VPX instances

Create two NetScaler VPX instances as part of the same resource group and availability set, and attach
it to the external load balancer.

a) NetScaler VPX instance 1

For example:

1 $vmName=”VPX1”

© 1999-2018 Citrix Systems, Inc. All rights reserved. 773

NetScaler 12.0

2
3 $vmSize=”Standard\_A3”
4
5 $pubName=”citrix”
6
7 $offerName=”netscalervpx110-6531”
8
9 $skuName=”netscalerbyol”
10
11 $avSet=Get-AzureRmAvailabilitySet -Name $avName -ResourceGroupName
$rgName
12
13 $vm1=New-AzureRmVMConfig -VMName $vmName -VMSize $vmSize -
AvailabilitySetId $avset.Id
14
15 $cred=Get-Credential -Message ”Type Credentials which will be used to
login to VPX instance”
16
17 $vm1=Set-AzureRmVMOperatingSystem -VM $vm1 -Linux -ComputerName $vmName
-Credential $cred -Verbose
18
19 $vm1=Set-AzureRmVMSourceImage -VM $vm1 -PublisherName $pubName -Offer
$offerName -Skus $skuName -Version ”latest”
20
21 $vm1=Add-AzureRmVMNetworkInterface -VM $vm1 -Id $nic1.Id
22
23 $diskName=”dynamic”
24
25 $storageAcc=Get-AzureRmStorageAccount -ResourceGroupName $rgName -Name
$saName
26
27 $osDiskUri1=$storageAcc.PrimaryEndpoints.Blob.ToString() + ”vhds1/” +
$diskName  + ”.vhd”
28
29 $vm1=Set-AzureRmVMOSDisk -VM $vm1 -Name $diskName -VhdUri $osDiskUri1 -
CreateOption fromImage
30
31 Set-AzureRmVMPlan -VM $vm1 -Publisher $pubName -Product $offerName -
Name $skuName
32
33 New-AzureRmVM -ResourceGroupName $rgName -Location $locName -VM $vm1

b) NetScaler VPX instance 2

For example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 774

NetScaler 12.0

1 $vmName=”VPX2”
2
3 $vmSize=”Standard\_A3”
4
5 $avSet=Get-AzureRmAvailabilitySet -Name $avName -ResourceGroupName
$rgName
6
7 $vm2=New-AzureRmVMConfig -VMName $vmName -VMSize $vmSize -
AvailabilitySetId $avset.Id
8
9 $cred=Get-Credential -Message ” Type Credentials which will be used to
login to VPX instance ”
10
11 $vm2=Set-AzureRmVMOperatingSystem -VM $vm2 -Linux -ComputerName $vmName
-Credential $cred -Verbose
12
13 $vm2=Set-AzureRmVMSourceImage -VM $vm2 -PublisherName $pubName -Offer
$offerName -Skus $skuName -Version ”latest”
14
15 $vm2=Add-AzureRmVMNetworkInterface -VM $vm2 -Id $nic2.Id
16
17 $diskName=”dynamic”
18
19 $storageAcc=Get-AzureRmStorageAccount -ResourceGroupName $rgName -Name
$saName
20
21 $osDiskUri1=$storageAcc.PrimaryEndpoints.Blob.ToString() + ”vhds2/” +
$diskName  + ”.vhd”
22
23 $vm2=Set-AzureRmVMOSDisk -VM $vm2 -Name $diskName -VhdUri $osDiskUri1 -
CreateOption fromImage
24
25 Set-AzureRmVMPlan -VM $vm2 -Publisher $pubName -Product $offerName -
Name $skuName
26
27 New-AzureRmVM -ResourceGroupName $rgName -Location $locName -VM $vm2

14) Configure the virtual machines

When both the NetScaler VPX instances start, then connect to both NetScaler VPX instances using the
SSH protocol to configure the virtual machines.

a) Active-Active: Run the same set of configuration commands on the command line of both the
NetScaler VPX instances.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 775

NetScaler 12.0

b) Active-Passive: Run this command on the command line of both the NetScaler VPX instances.

1 add ha node #nodeID <nsip of other NetScaler VPX>

In Active-Passive mode, run configuration commands on the primary node only.

Provision a NetScaler VPX pair in a high availability setup with Azure internal load
balancer

Log on to AzureRmAccount using your Azure user credentials.

1) Create a resource group

The location specified here is the default location for resources in that resource group. Make sure all
commands to create a load balancer use the same resource group.

$rgName=”<resource group name>”

$locName=”<location name, such as West US>”

New-AzureRmResourceGroup -Name $rgName -Location $locName

For example:

1 $rgName = ”ARM-LB-NS”
2
3 $locName = ”West US”
4
5 New-AzureRmResourceGroup -Name $rgName -Location $locName

2) Create a storage account

Choose a unique name for your storage account that contains only lowercase letters and numbers.

$saName=”<storage account name>”

$saType=”<storage account type, specify one: Standard_LRS, Standard_GRS, Standard_RAGRS, or

Platinum_LRS>”

New-AzureRmStorageAccount -Name $saName -ResourceGroupName $rgName -Type $saType

-Location $locName

For example:

1 $saName=”vpxstorage”
2
3 $saType=”Standard\_LRS”
4

© 1999-2018 Citrix Systems, Inc. All rights reserved. 776

NetScaler 12.0

5 New-AzureRmStorageAccount -Name $saName -ResourceGroupName $rgName -

Type $saType -Location $locName

3) Create an availability set

A load balancer configured with an availability set ensures that your application is always available..
$avName=”<availability set name>”
New-AzureRmAvailabilitySet -Name $avName -ResourceGroupName $rgName -Location $locName
4) Create a virtual network
Add a new virtual network with at least one subnet, if the subnet was not created previously.

1 $vnetName = ”LBVnet”
2
3 $vnetAddressPrefix=”10.0.0.0/16”
4
5 $FrontendAddressPrefix=”10.0.1.0/24”
6
7 $BackendAddressPrefix=”10.0.2.0/24”
8
9 $vnet=New-AzureRmVirtualNetwork -Name $vnetName -ResourceGroupName
$rgName -Location $locName -AddressPrefix $vnetAddressPrefix -Subnet
$frontendSubnet,$backendSubnet\‘
10
11 $frontendSubnet=New-AzureRmVirtualNetworkSubnetConfig -Name
frontendSubnet -AddressPrefix $FrontendAddressPrefix
12
13 $backendSubnet=New-AzureRmVirtualNetworkSubnetConfig -Name
backendSubnet -AddressPrefix $BackendAddressPrefix

Note: Choose the AddressPrefix parameter value as per your requirement.

Assign front end and back end subnet to the virtual network that you created earlier in this step.
If the front end subnet is the first element of array vnet, subnetId should be $vnet.Subnets[0].Id.
If the front end subnet is the second element in the array, the subnetId should be $vnet.Subnets[1].Id,
and so on..
5) Create an back end address pool

1 $beaddresspool= New-AzureRmLoadBalancerBackendAddressPoolConfig -Name ”

LB-backend”

6) Create NAT rules

Create NAT rules for services that you are not load balancing.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 777

NetScaler 12.0

1 $inboundNATRule1= New-AzureRmLoadBalancerInboundNatRuleConfig -Name ”

Inboundnatrule1” -FrontendIpConfiguration $frontendIP -Protocol TCP
-FrontendPort 3441 -BackendPort 3389
2
3 $inboundNATRule2= New-AzureRmLoadBalancerInboundNatRuleConfig -Name ”
RDP2” -FrontendIpConfiguration $frontendIP -Protocol TCP -
FrontendPort 3442 -BackendPort 3389

Use front end and back end ports as per your requirement.

7) Create a health probe

Create a TCP health probe with port 9000 and interval 5 seconds.

1 $healthProbe = New-AzureRmLoadBalancerProbeConfig -Name ”HealthProbe”  

” -Protocol tcp -Port 9000 -IntervalInSeconds 5 -ProbeCount 2

8) Create a load balancing rule

Create a LB rule for each service that you are load balancing.

For example:

You can use the following example to load balance http service.

1 $lbrule = New-AzureRmLoadBalancerRuleConfig -Name ”lbrule1” -

FrontendIpConfiguration $frontendIP -BackendAddressPool
$beAddressPool -Probe $healthProbe -Protocol Tcp -FrontendPort 80 -
BackendPort 80

Use front end and back end ports as per your requirement.

9) Create a load balancer entity

Create the load balancer adding all objects (NAT rules, load balancer rules, probe configurations) to-
gether.

1 $NRPLB = New-AzureRmLoadBalancer -ResourceGroupName $rgname -Name ”

InternalLB” -Location $locName -FrontendIpConfiguration $frontendIP
-InboundNatRule $inboundNATRule1,$inboundNatRule2 -LoadBalancingRule
$lbrule -BackendAddressPool $beAddressPool -Probe $healthProbe

10) Create a NIC

Create two NICs and associate each NIC with each NetScaler VPX instance

© 1999-2018 Citrix Systems, Inc. All rights reserved. 778

NetScaler 12.0

1 $backendnic1= New-AzureRmNetworkInterface -ResourceGroupName $rgName -

Name lb-nic1-be -Location $locName -PrivateIpAddress 10.0.2.6 -
Subnet $backendSubnet -LoadBalancerBackendAddressPool $nrplb.
BackendAddressPools\[0\] -LoadBalancerInboundNatRule $nrplb.
InboundNatRules\[0\]

This NIC is for NetScaler VPX 1. The Private IP should be in same subnet as that of subnet added.

1 $backendnic2= New-AzureRmNetworkInterface -ResourceGroupName $rgName -

Name lb-nic2-be -Location $locName -PrivateIpAddress 10.0.2.7 -
Subnet $backendSubnet -LoadBalancerBackendAddressPool $nrplb.
BackendAddressPools\[0\] -LoadBalancerInboundNatRule $nrplb.
InboundNatRules\[1\].

This NIC is for NetScaler VPX 2.The parameter Private IPAddress can have any private IP as per your
requirement.

11) Create NetScaler VPX instances

Create two VPX instances part of same resource group and availability set and attach it to the internal
load balancer.

a) NetScaler VPX instance 1

For example:

1 $vmName=”VPX1”
2
3 $vmSize=”Standard\_A3”
4
5 $avSet=Get-AzureRmAvailabilitySet -Name $avName -ResourceGroupName
$rgName
6
7 $vm1=New-AzureRmVMConfig -VMName $vmName -VMSize $vmSize -
AvailabilitySetId $avset.Id
8
9 $cred=Get-Credential -Message ”Type Credentials which will be used to
login to VPX instance”
10
11 $vm1=Set-AzureRmVMOperatingSystem -VM $vm1 -Linux -ComputerName $vmName
-Credential $cred -Verbose
12
13 $vm1=Set-AzureRmVMSourceImage -VM $vm1 -PublisherName $pubName -Offer
$offerName -Skus $skuName -Version ”latest”
14
15 $vm1=Add-AzureRmVMNetworkInterface -VM $vm1 -Id $backendnic1.Id
16

© 1999-2018 Citrix Systems, Inc. All rights reserved. 779

NetScaler 12.0

17 $diskName=”dynamic”
18
19 $storageAcc=Get-AzureRmStorageAccount -ResourceGroupName $rgName -Name
$saName
20
21 $osDiskUri1=$storageAcc.PrimaryEndpoints.Blob.ToString() + ”vhds1/” +
$diskName  + ”.vhd”
22
23 $vm1=Set-AzureRmVMOSDisk -VM $vm1 -Name $diskName -VhdUri $osDiskUri1 -
CreateOption fromImage
24
25 Set-AzureRmVMPlan -VM $vm1 -Publisher $pubName -Product $offerName -
Name $skuName
26
27 New-AzureRmVM -ResourceGroupName $rgName -Location $locName -VM $vm1

b) NetScaler VPX instance 2

For example:

1 $vmName=”VPX2”
2
3 $vmSize=”Standard\_A3”
4
5 $avSet=Get-AzureRmAvailabilitySet -Name $avName -ResourceGroupName
$rgName
6
7 $vm2=New-AzureRmVMConfig -VMName $vmName -VMSize $vmSize -
AvailabilitySetId $avset.Id
8
9 $cred=Get-Credential -Message ” Type Credentials which will be used to
login to VPX instance ”
10
11 $vm2=Set-AzureRmVMOperatingSystem -VM $vm2 -Linux -ComputerName $vmName
-Credential $cred -Verbose
12
13 $vm2=Set-AzureRmVMSourceImage -VM $vm2 -PublisherName $pubName -Offer
$offerName -Skus $skuName -Version ”latest”
14
15 $vm2=Add-AzureRmVMNetworkInterface -VM $vm2 -Id $backendnic2.Id
16
17 $diskName=”dynamic”
18
19 $storageAcc=Get-AzureRmStorageAccount -ResourceGroupName $rgName -Name
$saName

© 1999-2018 Citrix Systems, Inc. All rights reserved. 780

NetScaler 12.0

20
21 $osDiskUri1=$storageAcc.PrimaryEndpoints.Blob.ToString() + ”vhds2/” +
$diskName  + ”.vhd”
22
23 $vm2=Set-AzureRmVMOSDisk -VM $vm2 -Name $diskName -VhdUri $osDiskUri1 -
CreateOption fromImage
24
25 Set-AzureRmVMPlan -VM $vm2 -Publisher $pubName -Product $offerName -
Name $skuName
26
27 New-AzureRmVM -ResourceGroupName $rgName -Location $locName -VM $vm2

12) Configure the virtual machines

When both the NetScaler VPX instances start, then connect to both NetScaler VPX instances using the
SSH protocol to configure the virtual machines.

a) Active-Active: Run the same set of configuration commands on the command line of both the
NetScaler VPX instances.

b) Active-Passive: Run this command on the command line of both the NetScaler VPX instances.

add ha node #nodeID <nsip of other NetScaler VPX>

In Active-Passive mode, run configuration commands on the primary node only.

1.
2. Citrix ADC
3. NetScaler 12.0

Azure terminology

January 6, 2019

Contributed by:
C

Some of the Azure terms that are used in the NetScaler VPX Azure documentation are listed below.

1. Azure Load Balancer – Azure load balancer is a resource that distributes incoming traffic among
computers in a network. Traffic is distributed among virtual machines defined in a load-balancer set.
A load balancer can be external or internet-facing, or it can be internal.

2. Azure Resource Manager (ARM) – ARM is the new management framework for services in Azure.
Azure Load Balancer is managed using ARM-based APIs and tools.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 781

NetScaler 12.0

3. Back-End Address Pool – These are IP addresses associated with the virtual machine Network
Interface Card (NIC) to which load will be distributed.

4. BLOB - Binary Large Object – Any binary object like a file or an image that can be stored in Azure
storage.

5. Front-End IP Configuration – An Azure Load balancer can include one or more front-end IP ad-
dresses, also known as a virtual IPs (VIPs). These IP addresses serve as ingress for the traffic.

6. Instance Level Public IP (ILPIP) – An ILPIP is a public IP address that you can assign directly to
your virtual machine or role instance, rather than to the cloud service that your virtual machine or
role instance resides in. This does not take the place of the VIP (virtual IP) that is assigned to your
cloud service. Rather, it’s an additional IP address that you can use to connect directly to your virtual
machine or role instance.

Note: In the past, an ILPIP was referred to as a PIP, which stands for public IP.

7. Inbound NAT Rules – This contains rules mapping a public port on the load balancer to a port for
a specific virtual machine in the back end address pool.

8. IP-Config - It can be defined as an IP address pair (public IP and private IP) associated with an indi-
vidual NIC. In an IP-Config, the public IP address can be NULL. Each NIC can have multiple IP-Config
associated with it, which can be upto 255.

9. Load Balancing Rules – A rule property that maps a given front-end IP and port combination
to a set of back-end IP addresses and port combination. With a single definition of a load balancer
resource, you can define multiple load balancing rules, each rule reflecting a combination of a front
end IP and port and back end IP and port associated with virtual machines.

10. Network Security Group (NSG) – NSG contains a list of Access Control List (ACL) rules that allow
or deny network traffic to your virtual machine instances in a virtual network. NSGs can be associated
with either subnets or individual virtual machine instances within that subnet. When a NSG is associ-
ated with a subnet, the ACL rules apply to all the virtual machine instances in that subnet. In addition,
traffic to an individual virtual machine can be restricted further by associating a NSG directly to that
virtual machine.

11. Private IP addresses – Used for communication within an Azure virtual network, and your on-
premises network when you use a VPN gateway to extend your network to Azure. Private IP addresses
allow Azure resources to communicate with other resources in a virtual network or an on-premises
network through a VPN gateway or ExpressRoute circuit, without using an Internet-reachable IP ad-
dress. In the Azure Resource Manager deployment model, a private IP address is associated with the
following types of Azure resources – virtual machines, internal load balancers (ILBs), and application
gateways.

12. Probes – This contains health probes used to check availability of virtual machines instances in
the back end address pool. If a particular virtual machine does not respond to health probes for some

© 1999-2018 Citrix Systems, Inc. All rights reserved. 782

NetScaler 12.0

time, then it is taken out of traffic serving. Probes enable you to keep track of the health of virtual
instances. If a health probe fails, the virtual instance will be taken out of rotation automatically.

13. Public IP Addresses (PIP) – PIP is used for communication with the Internet, including Azure
public-facing services and is associated with virtual machines, Internet-facing load balancers, VPN
gateways, and application gateways.

14. Region - An area within a geography that does not cross national borders and that contains
one or more datacenters. Pricing, regional services, and offer types are exposed at the region level. A
region is typically paired with another region, which can be up to several hundred miles away, to form
a regional pair. Regional pairs can be used as a mechanism for disaster recovery and high availability
scenarios. Also referred to generally as location.

15. Resource Group - A container in Resource Manager holds related resources for an application.
The resource group can include all of the resources for an application, or only those resources that are
logically grouped together

16. Storage Account – An Azure storage account gives you access to the Azure blob, queue, table, and
file services in Azure Storage. Your storage account provides the unique namespace for your Azure
storage data objects.

17. Virtual Machine – The software implementation of a physical computer that runs an operating
system. Multiple virtual machines can run simultaneously on the same hardware. In Azure, virtual
machines are available in a variety of sizes.

18. Virtual Network - An Azure virtual network is a representation of your own network in the cloud.
It is a logical isolation of the Azure cloud dedicated to your subscription. You can fully control the IP
address blocks, DNS settings, security policies, and route tables within this network. You can also
further segment your VNet into subnets and launch Azure IaaS virtual machines and cloud services
(PaaS role instances). Additionally, you can connect the virtual network to your on-premises network
using one of the connectivity options available in Azure. In essence, you can expand your network to
Azure, with complete control on IP address blocks with the benefit of enterprise scale Azure provides.

1.
2. Citrix ADC
3. NetScaler 12.0

Jumbo frames on NetScaler VPX instances

November 2, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 783

NetScaler 12.0

NetScaler VPX appliances support receiving and transmitting jumbo frames containing up to 9216
bytes of IP data. Jumbo frames can transfer large files more efficiently than it is possible with the
standard IP MTU size of 1500 bytes.

A NetScaler appliance can use jumbo frames in the following deployment scenarios:

• Jumbo to Jumbo. The appliance receives data as jumbo frames and sends it as jumbo frames.
• Non-Jumbo to Jumbo. The appliance receives data as regular frames and sends it as jumbo
frames.
• Jumbo to Non-Jumbo. The appliance receives data as jumbo frames and sends it as regular
frames.

For more information, seeConfiguring Jumbo Frames Support on a NetScaler Appliance.

Jumbo Frames support is available on NetScaler VPX appliances running on the following virtualiza-
tion platforms:

• VMware ESX
• Linux-KVM Platform
• Citrix XenServer
• Amazon Web Services (AWS)

Jumbo frames on VPX appliances works similar to Jumbo frames on MPX appliances. For more infor-
mation on Jumbo Frames and its use cases, see Configuring Jumbo Frames on MPX appliances. The
use cases of Jumbo Frames on MPX appliances also apply to VPX appliances.

Configure jumbo frames for a VPX instance running on VMware ESX

Perform the following tasks for configuring Jumbo Frames on a NetScaler VPX appliance running on
VMware ESX server:

1. Set the MTU of the interface or channel of the VPX appliance to a value in the range 1501-9000.
Use the CLI or GUI to set the MTU size. Note that NetScaler VPX appliances running on VMware
ESX support receiving and transmitting jumbo frames containing up to only 9000 bytes of IP
data.
2. Set the same MTU size on the corresponding physical interfaces of the VMware ESX server by
using its management applications. For more information about setting the MTU size on the
physical interfaces of VMware ESX, see http://vmware.com/.

Configure jumbo frames for a VPX instance running on Linux-KVM server

Perform the following tasks for configuring Jumbo Frames on a NetScaler VPX appliance running on
a Linux-KVM Server:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 784

NetScaler 12.0

1. Set the MTU of the interface or channel of the VPX appliance to a value in the range 1501-9216.
Use the NetScaler VPX CLI or GUI to set the MTU size.
2. Set the same MTU size on the corresponding physical interfaces of a Linux-KVM Server by using
its management applications. For more information about setting the MTU size on the physical
interfaces of Linux-KVM, see http://www.linux-kvm.org/.

Configure jumbo frames for a VPX instance running on Citrix XenServer

Perform the following tasks for configuring Jumbo Frames on a NetScaler VPX appliance running on
Citrix XenServer:

1. On the Networking tab, select the network - network 0/1/2.

2. Select Properties and edit MTU. The drop-down selection menu for MTU is unavailable unless
all the VPXs that use the network are shutdown )

Configure jumbo frames for a VPX instance running on AWS

Host-level configuration is not required for VPX on Azure. To configure Jumbo Frames on VPX, follow
the steps given in Configuring Jumbo Frames Support on a NetScaler Appliance.

1.
2. Citrix ADC
3. NetScaler 12.0

Licensing

September 17, 2018

Contributed by:
C

The following topics describe the migration instructions for setting up a new version of a NetScaler
appliance with a list of all new and deprecated commands, parameters, and SNMP OIDs.

This document includes the following information:

• NetScaler Licensing Overview

• NetScaler Gateway Universal License

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 785

NetScaler 12.0

NetScaler licensing overview

March 6, 2019

Contributed by:
C

The process of allocating your NetScaler licenses has been greatly simplified. The new licensing frame-
work allows you to focus on getting maximum value from Citrix products.

In the NetScaler GUI, you can use your hardware serial number (HSN) or your license access code to
allocate your licenses. Alternatively, if a license is already present on your local computer, you can
upload it to the appliance.

For all other functionality, such as returning or reallocating your license, you must use the licensing
portal. Optionally, you can still use the licensing portal for license allocation. For more information
about the licensing portal, see http://support.citrix.com/article/CTX131110.

Note: Purchase separate licenses for each appliance in a high availability pair. Ensure that the same
types of licenses are installed on both the appliances. For example, if you purchase a platinum license
for one appliance, you must purchase another platinum license for the other appliance.

Prerequisites

To use the hardware serial number or license access code to allocate your licenses:

• You must be able to access public domains through the appliance. For example, the appliance
should be able to access www.citrix.com. The license allocation software internally accesses
the Citrix licensing portal for your license. To access a public domain:

– Use a proxy server or set up a DNS server.

– Configure a NetScaler IP (NSIP) address or a subnet IP (SNIP) address on your NetScaler
appliance.

• Your license must be linked to your hardware, or you must have a valid license access code.
Citrix sends your license access code by email when you purchase a license.

Allocate a license by using the GUI

If your license is already linked to your hardware, the license allocation process can use the hardware
serial number. Otherwise, you must type the license access code.

You can partially allocate licenses as required for your deployment. For example, if your license file
contains 10 licenses, but your current requirement is for only six licenses, you can allocate six licenses

© 1999-2018 Citrix Systems, Inc. All rights reserved. 786

NetScaler 12.0

now, and allocate more licenses later. You cannot allocate more than the total number of licenses
present in your license file.

To allocate your license

1. In a web browser, type the IP address of the NetScaler appliance (for example, http://
192.168.100.1).

2. In User Name and Password, type the administrator credentials.

3. On the Configuration tab, navigate to System \ > Licenses.

4. In the details pane, click Manage Licenses, click Add New License, and then select one of the
following options:

• Use Serial Number. The software internally fetches the serial number of your appliance
and uses this number to display your licenses.

• Use license access code. Citrix emails the license access code for the license that you pur-
chased. Enter the license access code in the text box.

If you do not want to configure internet connectivity on the NetScaler appliance, you can
use a proxy server. Select the Connect through Proxy Server check box and specify the
IP address and port of your proxy server.

5. Click Get Licenses. Depending on the option that you selected, one of the following dialog
boxes appears.

• The following dialog box appears if you selected Hardware Serial Number.

• The following dialog box appears if you selected license access code.

6. Select the license file that you want to use to allocate your licenses.

7. In the Allocate column, enter the number of licenses to be allocated. Then click Get.

• If you selected Hardware Serial Number, enter the number of licenses, as shown in the
following screenshot.

• If you selected license access code, enter the number of licenses, as shown in the following
screenshot.

8. Click restart for the license to take effect.

9. In the restart dialog box, click OK to proceed with the changes, or click Close to cancel the
changes.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 787

NetScaler 12.0

Install a license

If you downloaded your license file to your local computer by accessing the licensing portal, you must
upload the license to the appliance.

To install a license file by using the GUI

1. In a web browser, type the IP address of the NetScaler appliance (for example, http://
192.168.100.1).
2. In User Name and Password, type the administrator credentials.
3. On the Configuration tab, navigate to System Licenses.
4. In the details pane, click Manage Licenses.
5. Click Add New License, then select Upload license files from a local computer.
6. Click Browse. Navigate to the location of the license files, select the license file, and then click
Open.
7. Click restart to apply the license.
8. In the restart dialog box, click OK to proceed with the changes, or click Close to cancel the
changes.

To install the licenses by using the CLI:

1. Open an SSH connection to the ADC appliance by using an SSH client, such as PuTTY.

2. Log on to the ADC appliance by using the administrator credentials.

3. Switch to the shell prompt, create a license subdirectory in the nsconfig directory, if it does not
exist, and copy one or more new license files to this directory.

Example

1 login: nsroot
2 Password: nsroot
3 Last login: Mon Aug 4 03:37:27 2008 from 10.102.29.9
4 Done
5 > shell
6 Last login: Mon Aug 4 03:51:42 from 10.103.25.64
7 root@ns# mkdir /nsconfig/license
8 root@ns# cd /nsconfig/license

Copy one or more new license files to this directory.

Note: The NetScaler appliance does not prompt for a reboot option when you use the command
line interface to install the licenses. Run the
reboot -w command to warm restart the system, or run the
restart command to restart the system normally.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 788

NetScaler 12.0

Verify licensed features

Before using a feature, ensure that your license supports the feature.

To verify the licensed features by using the CLI

1. Open an SSH connection to the ADC appliance by using an SSH client, such as PuTTY.
2. Log on to the ADC appliance by using the administrator credentials.
3. At the command prompt, enter the sh ns license command to display the features supported by
the license.
Example

1 sh ns license
2 License status:
3 Web Logging: YES
4 Surge Protection: YES
5 .......
6
7 HTML Injection: YES
8 Done

To verify the licensed features by using the GUI

1. In a web browser, type the IP address of the ADC appliance, such as http://192.168.100.1.
2. In User Name and Password, type the administrator credentials.
3. Provide the User name and Password and click Login.
4. In the navigation pane, expand System, and then click Licenses. You see a green check mark
next to the licensed features.

Enable or disable a feature

When you use the NetScaler appliance for the first time, you must enable a feature before you can
use its functionality. If you configure a feature before it is enabled, a warning message appears. The
configuration is saved but it applies only after the feature is enabled.

To enable a feature by using the CLI

At the command prompt, type the following commands to enable a feature and verify the configura-
tion:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 789

NetScaler 12.0

• enable feature <FeatureName>

• show feature

Example

1 enable feature lb cs
2 done
3 >show feature
4
5 Feature Acronym
Status
6 ------- -------
------
7 1) Web Logging WL OFF
8 2) Surge Protection SP ON
9 3) Load Balancing LB ON
10 4) Content Switching CS ON
11 5) Cache Redirection CR ON
12 .
13 .
14 .
15 24) NetScaler Push push OFF
16 Done

The example shows how to enable load balancing (lb) and content switching (cs).

If the license key is not available for a particular feature, the following error message appears
for that feature:

ERROR: feature(s) not licensed

Note: To enable an optional feature, you must have a feature-specific license. For example, you
have purchased and installed the Citrix NetScaler Enterprise Edition license. However, to enable
the Integrated Caching feature, you must purchase and install the AppCache license.

To disable a feature by using the CLI

At the command prompt, type the following commands to disable a feature and verify the configura-
tion:

• disable feature <FeatureName>

• show feature

Example

The following example shows how to disable load balancing (LB).

© 1999-2018 Citrix Systems, Inc. All rights reserved. 790

NetScaler 12.0

1 > disable feature lb

2 Done
3 > show feature
4
5 Feature Acronym
Status
6 ------- -------
------
7 1) Web Logging WL OFF
8 2) Surge Protection SP ON
9 3) Load Balancing LB OFF
10 4) Content Switching CS ON
11 .
12 .
13 .
14 24) NetScaler Push push OFF
15 Done
16 >

NetScaler VPX Express license

Starting with NetScaler release 12.0 56.20, VPX Express for on-premise and cloud deployments does
not require a license file and it comes with the following features:

• 20 Mbps bandwidth
• All ADC standard license features, except Citrix Gateway
• Maximum 250 SSL sessions
• 20 Mbps SSL throughput

You can upgrade the VPX Express License to the following two options:

1. A standalone NetScaler VPX license

2. NetScaler Pooled Capacity license for VPX instances. For more information, see NetScaler Pooled
Capacity.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 791

NetScaler 12.0

Citrix Gateway Universal License

September 21, 2018

Contributed by:
C
The Citrix Gateway universal license limits the number of concurrent user sessions to the number of
licenses purchased. If you purchase 100 licenses, you can have 100 concurrent sessions at any time.
When a user ends a session, that license is released for the next user. A user who logs on to the Citrix
Gateway from more than one computer occupies a license for each session.
If all licenses are occupied, no additional connections can be opened until a user ends a session or
the administrator terminates the session using the configuration utility. When a connection is closed,
the license is released and can be used for a new user.
This document includes the following information:
• Obtaining the Universal License
• Installing the Universal License
• Verifying Installation of the Universal License

Obtaining the Universal License

You need the following information before going to the Citrix Web site for the universal license.
• Your user ID and password for My Citrix
Register at My Citrix (www.mycitrix.com) to receive your user ID and password.
Note: If you cannot locate either the license code or your user ID and password, contact Citrix
Customer Service.
• The host name of the
Citrix Gateway
The entry field for this name on My Citrix is case-sensitive, so make sure that you copy the host
name exactly as it is configured on the NetScaler appliance.
• The number of licenses you want to include in the license file
You do not have to download all of the licenses you are entitled to at once. For example, if your
company purchased 100 licenses, you can choose to download 50. You can allocate the rest in
another license file at a later time. Multiple license files can be installed on the
Citrix Gateway.
Note: Before obtaining your licenses, make sure you configure the host name of the NetScaler
appliance using the Setup Wizard and then restart the appliance.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 792

NetScaler 12.0

To obtain your universal license

1. In a Web browser, go to http://www.citrix.com/ and click My Citrix.

2. Enter your user name and password. If this is the first time you are logging on to the site, you
are asked for additional background information.
3. Under My Tools, point to Choose a toolbox, and click Activation System/Manage Assets.
4. In the Current Tool drop-down menu, select Activate/Allocate and follow the directions to obtain
your license file.

Installing the Universal License

To install the license, see “

Installing the License”. After installation, verify that the license was installed correctly.

Verifying Installation of the Universal License

Before proceeding, verify that your universal license is installed correctly.

To verify installation of the universal license by using the command line interface

1. Open an SSH connection to the NetScaler appliance by using an SSH client, such as PuTTY.
2. Log on to the NetScaler appliance by using the administrator credentials.
3. Use the show license command to verify that “SSL VPN = YES” and that Maximum Users has
increased from 5 to the expected number of concurrent users.

To verify installation of the universal license by using the configuration utility

1. In a Web browser, type the IP address of the NetScaler appliance, such as http://
192.168.100.1.
2. In User Name and Password, type the administrator credentials.
3. In the navigation pane, expand System, and then click Licenses.
4. In the Licenses pane, you will see a green check mark next to NetScaler Gateway. The field Max-
imum Citrix Gateway Users Allowed displays the number of concurrent user sessions licensed
on the NetScaler appliance.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 793

NetScaler 12.0

NetScaler Pooled Capacity

September 21, 2018

Contributed by:
C
NetScaler pooled capacity is a licensing framework that comprises a common bandwidth and instance
pool that is hosted on and served by Citrix Application Delivery Management.
For complete information, see NetScaler Pooled Capacity “NetScaler Pooled Capacity”.
1.
2. Citrix ADC
3. NetScaler 12.0

Upgrade and downgrade a NetScaler appliance

November 2, 2018
Contributed by:
C
NetScaler 12.0 offers new and updated features with increased functionality. A comprehensive list
of enhancements is listed in the release notes accompanying the release announcement. Read the
release notes document before you upgrade your software.
This section provides information about upgrading and downgrading a NetScaler appliance (MPX and
VPX) firmware. It includes the following topics:
• Before you begin
• Upgrade a NetScaler standalone appliance
• Downgrade a NetScaler standalone appliance
• Upgrade a high availability pair
• Downgrade a high availability Pair
• Troubleshooting
• FAQs
• New and Deprecated Commands, Parameters, and SNMP OIDs
For information about upgrading a NetScaler SDX appliance, see Single Bundle Upgrade.
1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 794

NetScaler 12.0

Before you begin

November 15, 2018

Contributed by:
C
Before you start the upgrade or downgrade process, make sure you check the following:
• The licensing framework and types of licenses. A software edition upgrade might require new
licenses, such as upgrading from the standard edition to the enterprise edition, the standard
edition to the platinum edition, or the enterprise edition to the platinum edition. Existing Citrix
NetScaler licenses continue to work when you upgrade to version 12.0. For more information,
see Licensing
• Check for New and deprecated commands, parameters, and SNMP OIDs.
• Check forCitrix NetScaler Hardware and Software Compatibility Matrix.
• If the Citrix NetScaler Gateway logon page is customized, then make sure that the UI theme is
set to default.
• Review the LOM Firmware Upgrade page, if you are upgrading LOM.
• Download the Citrix NetScaler firmware from the download page. For the detailed steps to
download the Citrix NetScaler firmware, see the “How to download and update the NetScaler
Firmware” section in this article CTX205476.
• Perform a back up of the configuration file, customization file, certificates, monitor scripts, li-
cense files, and so on either manually or refer to the following documentation for back up using
Citrix NetScaler CLI or GUI - Backup and restore.
• Validate the integrity of the Citrix NetScaler and check available space before performing an
upgrade. For more information about how to free up storage space, see https://support.citrix.
com/article/CTX133588
• Check the Citrix ADC VPX Support matrix and usage guidelines.
• Check the FAQ section.
For more information about prerequisites for upgrading or downgrading the Citrix NetScaler
firmware, see these support articles:
• CTX126793: Best Practices for Upgrading Citrix NetScaler or Citrix NetScaler Gateway Appliances
• CTX220371: Must Read Articles Before and After Upgrading Citrix NetScaler
1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 795

NetScaler 12.0

Upgrade a Citrix NetScaler standalone appliance

January 6, 2019

Contributed by:
C

Before upgrading the system software, make sure that you read the Before you begin section and
complete the necessary prerequisites such as backing up the necessary files and downloading the
Citrix NetScaler firmware.

When upgrading from 10.0 and higher releases you have the option to use the GUI or the CLI.

You cannot upgrade to release 12.0 from the following builds by using the Upgrade Wizard of the GUI:

• All builds of release 10.1

• Any build before Build 57.x of release 10.5

If your Citrix NetScaler runs any 9.x or lower release, visit the Product matrix site for more information.
.

Upgrade a Citrix NetScaler standalone appliance by using the GUI

Follow these steps to upgrade a standalone Citrix NetScaler to release 12.0 by using the GUI.

1. In a web browser, type the IP address of the Citrix NetScaler, for example http://
10.102.29.50.
2. In User Name and Password, type the administrator credentials (nsroot/nsroot) and then click
Log On.
3. From the GUI, click System Upgrade.

4. From the Choose File drop-down menu choose the appropriate option: Local or Appliance. If
you want to use the Appliance option, the firmware needs to be uploaded to the Citrix NetScaler first.
You can use any file tranfer method such as WinSCP to upload the Citrix NetScaler firmware to the
appliance.

5. Select the correct file and click Upgrade.

6. Follow the instructions to upgrade the software.

7. When prompted, select Reboot.

After the upgrade, close all browser instances and clear your computer’s cache before accessing the
appliance.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 796

NetScaler 12.0

Upgrade a Citrix NetScaler standalone appliance by using the CLI

Follow these steps to upgrade a standalone Citrix NetScaler to release 12.0 by using the CLI:

In the following procedure, <release> and <releasenumber> represent the release version you are up-
grading to, and <targetbuildnumber> represents the build number that you are upgrading to. The
procedure includes optional steps to avoid losing any updates that are pushed to the /etc directory
during the upgrade.

1. Use an SSH client, such as PuTTy, to open an SSH connection to the appliance.

2. Log on to the appliance by using the administrator credentials. Save the running configuration.
At the prompt, type:save config

3. Create a copy of the ns.conf file. At the shell prompt, type:

a) cd /nsconfig
b) cp ns.conf ns.conf.NS<currentreleasenumber><currentbuildnumber>

You should backup the configuration file to another computer.

4. (Optional) If you have modified some of the following files in the /etc directory, and copied them
to /nsconfig to maintain persistency, any updates that are pushed to the /etc directory during
the upgrade might be lost:

• ttys
• resolv.conf
• sshd_config
• host.conf
• newsyslog.conf
• host.conf
• httpd.conf
• rc.conf
• syslog.conf
• crontab
• monitrc

To avoid losing these updates, create a /var/nsconfig_backup directory, and move the cus-
tomized files to this directory. That is, move any files that you modified in /etc directory and
copied to /nsconfig by running the following command:

cp /nsconfig/<filename> /var/nsconfig_backup

Example:

cp /nsconfig/syslog.conf /var/nsconfig_backup

5. Create a location for the installation package. At the shell prompt type:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 797

NetScaler 12.0

• cd /var/nsinstall
• mkdir <releasenumber>nsinstall
• cd <releasenumber>nsinstall
• mkdir build_<targetbuildnumber>
• cd build_<targetbuildnumber>

6. Copy the already downloaded Citrix NetScaler firmware to the directory that you created for it in
step 5, by using any file transferring method such as WinSCP. See the Before You Begin section for
more information about downloading the Citrix NetScaler firmware.

7. Extract the contents of the installation package. Example:

tar –xvzf build-12.0-32.2_nc_32.tgz

8. Run the installns script to install the new version of the system software. The script updates the /etc
directory. Example: ./installns

9. When prompted, restart the Citrix NetScaler.

10. (Optionally) If you’ve created a copy of the ns.conf file in the Before You Begin section, do the
following:

1 1. Manually compare the files in /var/nsconfig\_backup and /etc and

make appropriate changes in /etc.
2 2. To maintain persistency, move the updated files in /etc to /nsconfig
.
3 3. Restart the appliance to put the changes into effect.

Below is an example of Citrix NetScaler firmware upgrade.

1 login: nsroot
2
3
4 Password: nsroot
5
6
7 Last login: Mon Apr 17 15:05:05 2018 from 10.252.243.134
8
9
10 Done
11
12
13 > save config
14
15
16 > shell
17

© 1999-2018 Citrix Systems, Inc. All rights reserved. 798

NetScaler 12.0

18
19 Last login: Mon Apr 17 15:05:05 2018 from 10.252.243.134
20
21
22 root@NSnnn# cd /var/nsinstall
23
24
25 root@NSnnn# cd 12.0nsinstall
26
27
28 root@NSnnn# mkdir build_41.16
29
30
31 root@NSnnn# cd build_41.16
32
33
34 root@NSnnn# ftp <FTP server IP address>
35
36
37 ftp> mget build-12.0-41.16_nc.tgz
38
39
40 ftp> bye
41
42
43 root@NSnnn# tar xzvf build-12.0-41.16_nc.tgz
44
45
46 root@NSnnn# ./installns
47
48
49 installns version (12.0-41.16) kernel (ns-12.0-41.16_nc.gz)
50
51
52 ...
53
54
55 ...
56
57
58 ...
59
60
61 Copying ns-12.0-41.16_nc.gz to /flash/ns-12.0-41.16_nc.gz ...
62

© 1999-2018 Citrix Systems, Inc. All rights reserved. 799

NetScaler 12.0

63
64
65
66
67 ...
68
69
70 Installation has completed.
71
72
73
74
75
76 Reboot NOW? [Y/N] Y

Upgrade a Citrix NetScaler standalone appliance by using NITRO API

To use NITRO API to upgrade or downgrade a Citrix NetScaler, see Automate Citrix NetScaler Upgrade
and Downgrade with a Single API.

Directory locations of script files for user monitors

In release 10.1 build 122.17, the script files for user monitors are at a new location. If you upgrade an
appliance or virtual appliance to release 10.1 build 122.17 or later, the changes are as follows:

• A new directory named conflicts is created in /nsconfig/monitors/ and all the built-in scripts of
the previous builds are moved to this directory.
• All new built-in scripts are available in the /netscaler/monitors/ directory. All custom scripts are
available in the /nsconfig/monitors/ directory.
• You must save a new custom script in the /nsconfig/monitors/ directory.
• After the upgrade is completed, if a custom script is created and saved in the /nsconfig/moni-
tors/ directory with the same name as that of a built-in script, the script in the /netscaler/moni-
tors/ directory takes priority. That is, the custom script is not run.

If you provision a virtual appliance running release 10.1 build 122.17 or later, the changes are as follows:

• All built-in scripts are available in the /netscaler/monitors/ directory

• The directory /nsconfig/monitors/ is empty.
• If you create a new custom script, you must save it in the /nsconfig/monitors/ directory.

For more information about user monitors, see “Understanding user monitors.”

© 1999-2018 Citrix Systems, Inc. All rights reserved. 800

NetScaler 12.0

Check and install Citrix NetScaler 12.0 software update

Update the Citrix NetScaler software when an update is available, for better performance. A Citrix
NetScaler update can include feature improvements, performance fixes, or enhancements. Make sure
you read the release notes to see what fixes and enhancements are available in the update. To check
and install a software update, do the following.
1. In the Citrix NetScaler home page, click Check for Update from the nsroot drop-down menu at
the top right corner of the page.
2. In the Latest System Software Updates Available page, check the available software update
that you can install.
3. Click Download to download the installation package from the Citrix download website.
4. After you have downloaded the software package, install the update through either CLI or GUI
procedure.
Note

The Check for Update link is accessible only if you log into the GUI through HTTP protocol and
not through HTTPS protocol.

1.
2. Citrix ADC
3. NetScaler 12.0

Downgrade a Citrix NetScaler standalone appliance

January 6, 2019
Contributed by:
C
You can downgrade to any earlier release on a standalone Citrix NetScaler by using the CLI. Downgrad-
ing using the GUI is not supported.
Note

Loss in configuration might occur when downgrading. You should compare the configurations
before and after the downgrade, and then manually reenter any missing entries.

Procedure to downgrade a standalone Citrix NetScaler

Follow the steps given below to downgrade a Citrix NetScaler standalone appliance running release
12.0 to an earlier release.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 801

NetScaler 12.0

In this procedure, <release> and <releasenumber> represent the release version you are downgrading
to, and <targetbuildnumber> represents the build number that you are downgrading to.

1. Open an SSH connection to the Citrix NetScaler by using an SSH client, such as PuTTY.

2. Log on to the Citrix NetScaler by using the administrator credentials. Save the running configu-
ration. At the prompt, type:

save config

3. Create a copy of the ns.conf file. At the shell prompt, type:

a) cd /nsconfig
b) cp ns.conf ns.conf.NS<currentbuildnumber>

You should backup a copy of the configuration file on another computer.

4. Copy the <releasenumber> configuration file (ns.conf.NS<releasenumber>) to ns.conf. At the

shell prompt, type:

cp ns.conf.NS<releasenumber> ns.conf

Note: ns.conf.NS<releasenumber> is the backup configuration file that is automatically created

when the system software is upgraded from release version <releasenumber> to the current re-
lease version. There may be some loss in configuration when downgrading. After the appliance
restarts, compare the configuration saved in step 3 with the running configuration, and make
any adjustments for features and entities configured before the downgrade. Save the running
configuration after making the changes.

Important: If routing is enabled, perform step 5. Otherwise, skip to step 6.

5. If routing is enabled, the ZebOS.conf file will contain the configuration. At the shell prompt,
type:

a) cd /nsconfig
b) cp ZebOS.conf ZebOS.conf.NS
c) cp ZebOS.conf.NS<targetreleasenumber> ZebOS.conf

6. Change directory to /var/nsinstall/<releasenumber>nsinstall, or create one if it does not exist.

7. Change directory to build_<targetbuildnumber>, or create one if it does not exist.

8. Download or copy the installation package (build-<release>-<targetbuildnumber>.tgz) to this

directory and extract the contents of the installation package.

9. Run the installns script to install the new version of the system software. The script updates the
/etc directory.

If the configuration file for the build that you are downgrading to exists on the appliance, you
are prompted to load that configuration, as shown in the following figure.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 802

NetScaler 12.0

Figure 1. Downgrade menu if configuration file exists

If the free space available on the flash drive is insufficient to install the new build, the Citrix
NetScaler aborts the installation. Manually clean up the flash drive and restart the installation.

Example:

1 login: nsroot
2
3 Password: nsroot
4
5 Last login: Mon Apr 24 02:06:52 2017 from 10.102.29.9
6
7 Done
8
9 > save config
10
11 > shell
12
13 root@NSnnn# cp ns.conf.NS10.5 ns.conf
14
15 root@NSnnn# cd /var/nsinstall
16
17 root@NSnnn# mkdir 10.5nsinstall
18
19 root@NSnnn# cd 10.5nsinstall
20
21 root@NSnnn# mkdir build_57
22
23 root@NSnnn# cd build_57
24
25 root@NSnnn# ftp 10.102.1.1
26
27 ftp> mget build-10.5-57_nc.tgz
28
29 ftp> bye
30
31 root@NSnnn# tar -xzvf build-10.1-125_nc.tgz
32
33 root@NSnnn# ./installns
34
35 installns version (10.5-57) kernel (ns-10.5-57.gz)
36
37 ...
38
39 ...

© 1999-2018 Citrix Systems, Inc. All rights reserved. 803

NetScaler 12.0

40
41 ...
42
43 Copying ns-10.5-57.gz to /flash/ns-10.5-57_nc.gz ...
44
45 Changing /flash/boot/loader.conf for ns-10.5-57 ...
46
47
48
49 Installation has completed.
50
51
52
53 Reboot NOW? [Y/N] Y

1.
2. Citrix ADC
3. NetScaler 12.0

Upgrade a high availability pair

January 6, 2019

Contributed by:
C

One of the requirements of Citrix NetScaler appliances in a high availability setup is to install the same
Citrix NetScaler software release on both appliances of the setup. Therefore, when software on one
appliance is upgraded, ensure that the software is upgraded on both the appliances.

You can follow the same procedure to upgrade a standalone appliance or each appliance in a high
availability pair, although additional considerations apply to upgrading a high availability pair.

Before you start a Citrix NetScaler firmware upgrade on an HA pair, read the prerequisites mentioned
in the Before you begin section. Also, you need to consider a few HA-specific points.

Points to note

• First upgrade the secondary node, and then the primary node. Upgrading software on the sec-
ondary appliance before the primary appliance ensures that the upgrade process is completed
without any issues.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 804

NetScaler 12.0

• If the two nodes in an HA configuration are running different Citrix NetScaler software releases,
the following information does not get synchronized on the primary and secondary nodes:

– Configuration propagation and synchronization

– States of the services
– Connection failover sessions
– Persistence sessions

• The above information might not get synchronized on the primary and secondary nodes if the
two nodes are running different builds of the same release. Refer to the Known Issues section
of the release notes to check if your Citrix NetScaler build has this issue.

• Synchronization of the files in the All mode of the Sync HA files command works successfully if
the two nodes in an HA configuration are running different Citrix NetScaler software releases,
or the two nodes are running different builds of the same release. For more information, see
Synchronising Configuration Files in High Availability Setup.

Figure. Upgrade a high availability pair

You can upgrade using the Citrix NetScaler CLI or GUI.

Upgrade a high availability pair by using the CLI

The upgrade process includes the following steps:

1. Upgrade software on the secondary appliance

2. Upgrade software on the upgrade appliance
3. Synchronize secondary appliance

Upgrade software on the secondary appliance

The following illustration depicts the procedure to upgrade software on the secondary appliance:

1. Log on to the secondary NetScaler appliance using an SSH utility, such as PuTTY and specifying
the NetScaler IP (NSIP). Use the nsroot credentials to log on to the appliance.

2. From the command line interface of the appliance, type the following command to save the
existing configuration: save config

3. Switch to the shell prompt.

1 login as: username

2 Using keyboard-interactive authentication.
3 Password:
4 Last login: Wed Jun 24 14:59:16 2015 from 10.252.252.65
5 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 805

NetScaler 12.0

6 > shell
7 Copyright (c) 1992-20

4. Run the following command to change to the default installation directory: # cd /var/nsinstall

5. Run the following command to create a temporary subdirectory of the nsinstall directory: #
mkdir x_xnsinstall

Note: The text x_x is used to name the NetScaler version for future configurations. For
example, the directory for the installation files of NetScaler 9.3 us called 9_3nsinstall. Do
not use a period (.) in the folder name, it can cause failed upgrades.

6. Change to the x_xnsinstall directory.

7. Download the required installation package and documentation bundle, such as “ns-x.0-xx.x-
doc.tgz,” to the temporary directory created in Step 4.

Notes:

• Some builds do not have a documentation bundle as it does not have to be installed.
• Click the Documentation tab from the GUI to access the documentation.

8. Before you run the install script, the files must be extracted and placed on the appliance. Use
the following command to uncompress the bundle downloaded from Citrix website: tar -zxvf
ns-x.0-xx.x-doc.tgz. The following is a quick explanation of the parameters used.

x: Extract files

v: Print the file names as they are extracted one by one

z: The file is a “gzipped” file

f: Use the following tar archive for the operation

9. Run the following command to install the downloaded software: # ./installns

Note: If the appliance does not have sufficient disk space to install the new kernel files, the
installation process performs an automatic cleanup of the flash drive.

10. After the installation process is complete, the process prompts to restart the appliance. Press y
to restart the appliance.

11. Log on to the appliance Command Line Interface using the nsroot credentials.

12. Run the following command from to display the state of the NetScaler appliance: show ha node
The output of the preceding command should indicate that the appliance is a secondary node
and synchronization is disabled.

13. Run the following command to disable synchronization on the appliance if synchronization is
not disabled: set ha node -hasync disabled

© 1999-2018 Citrix Systems, Inc. All rights reserved. 806

NetScaler 12.0

14. Ensure that the configuration is complete and as expected.

15. Run the following command to perform a force failover and takeover as primary appliance:
force failover

Here’s a sample configuration in the new primary node.

1 login: nsroot
2 Password: nsroot
3 Last login: Monday Apr 17 08:37:26 2017 from 10.102.29.9
4 Done
5 show ha node
6 2 nodes:
7 1) Node ID: 0
8 IP: 10.0.4.2
9 Node State: UP
10 Master State: Primary
11 ...
12 Sync State: AUTO DISABLED
13 Propagation: AUTO DISABLED
14 ...
15 Done

Upgrade software on the primary appliance

The following illustration depicts the procedure to upgrade software on the primary appliance:

Note: After completing the “Upgrade software on the secondary appliance” procedure, the orig-
inal primary appliance is now a secondary appliance.

1. Log on to the secondary NetScaler appliance using an SSH utility, such as PuTTY. Use the nsroot
credentials to log on to the appliance. Follow the same steps as mentioned in the above section
to complete the installation process. We have to follow the same steps as mentioned in step 2
to step 9 in the previous section(Upgrade software of the secondary appliance)

2. After the installation process is complete, the process prompts to restart the appliance. Press y
to restart the appliance.

3. Log on to the appliance Command Line Interface using the nsroot credentials.

4. Run the following command to display the state of the NetScaler appliance: show ha node. The
output of the preceding command should indicate that the appliance is a primary node and the
status of the node state is marked as UP.

5. If the appliance is not a primary appliance, run the following command to perform a force
failover to ensure that the appliance is a primary appliance: force failover

© 1999-2018 Citrix Systems, Inc. All rights reserved. 807

NetScaler 12.0

6. Verify that the appliance is a primary appliance.

Enable synchronization on the secondary appliance

To enable synchronization on the secondary appliance, complete the following procedure:

1. Run the following command to verify that the appliance is a secondary appliance: show node

2. Run the following command to enable synchronization on the appliance: set ha node -hasync
enabled

3. Run the following command to verify that the configuration of the secondary appliance is syn-
chronized with that of the primary appliance: show ns runningconfig

Here’s an example configuration of the new primary node and the new secondary node.

1 show ha node
2 Node ID: 0
3 IP: 10.0.4.11
4 Node State: UP
5 Master State: Primary
6 ...
7 ...
8 INC State: DISABLED
9 Sync State: ENABLED
10 Propagation: ENABLED
11 Enabled Interfaces : 1/1
12 Disabled Interfaces : None
13 HA MON ON Interfaces : 1/1
14 ...
15 ...
16 Local node information
17 Critical Interfaces: 1/1
18 Done
19
20 Show ha node
21 Node ID: 0
22 IP: 10.0.4.2
23 Node State: UP
24 Master State: Secondary
25 ..
26 ..
27 INC State: DISABLED
28 Sync State: SUCCESS
29 Propagation: ENABLED
30 Enabled Interfaces : 1/1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 808

NetScaler 12.0

31 Disabled Interfaces : None

32 HA MON ON Interfaces : 1/1
33 . . .
34 . . .
35 Local node information:
36 Critical Interfaces: 1/1
37 Done

Upgrade a high availability pair by using the GUI

Follow these steps to upgrade a Citrix NetScaler pair in a high availability setup, by using the GUI:

1. Log on to the secondary node and perform the upgrade as described in the section “Upgrade
a Citrix NetScaler standalone appliance by using the GUI” in Upgrade a Citrix NetScaler stan-
dalone appliance.

2. Log on to the primary node and perform the upgrade as described in the section “Upgrade a Cit-
rix NetScaler standalone appliance by using the GUI” in Upgrade a Citrix NetScaler standalone
appliance.

1.
2. Citrix ADC
3. NetScaler 12.0

Downgrade a high availability pair

January 6, 2019

Contributed by:
C

You can downgrade to any release on a high availability pair by using the command line interface. The
GUI does not support the downgrade process.

To downgrade the system software on a Citrix NetScaler pair in a high availability pair, you need to
downgrade the software first on the secondary node and then on the primary node. For instructions
on downgrading each node separately, see Downgrade a Citrix NetScaler standalone appliance.

Important

Loss in configuration might occur when downgrading. You should compare the configurations
before and after the downgrade, and then manually re-enter any missing entries.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 809

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0

Troubleshooting

February 11, 2019

Contributed by:
C
If the appliance does not work as expected after you complete the installation, upgrade, or downgrade
process, the first thing to do is to check for the most common causes of the problem.

Resources for troubleshooting

For best results, use the following resources to troubleshoot an issue related to installing, upgrading,
or downgrading a Citrix NetScaler:
• The configuration files from the appliance. In case of a High Availability pair, the configuration
files from both appliances.
• The following files from the appliance(s):
– The relevant newnslog files.
– The ns.log file.
– The messages file.
• A network topology diagram.

Troubleshooting issues related to the installation, upgrade, and downgrade processes

Following are the most common installation, upgrade, and downgrade issues, and tips for resolving
them:
• Issue
The Citrix NetScaler is not accessible after the software downgrade
Cause
During the software downgrade process, if the configuration file of the existing release and build
does not match the configuration file of the earlier release and build, the appliance cannot load
the configuration, and the default IP address is assigned to the appliance.
Resolution

© 1999-2018 Citrix Systems, Inc. All rights reserved. 810

NetScaler 12.0

– Verify that the appliance is accessible from the console.

– Verify the NSIP address and the routes on the appliance.
* If the IP address has changed to the default 192.168.100.1 IP address, change the IP
address as required.
* Verify that the appliance is accessible.

• Issue

Configuration of the appliance is lost after you upgrade the software across multiple releases.

Cause

Some migration commands are built in for upgrading to the next release. Such commands
might not be available across releases.

Resolution

– Verify the path of the upgrade process. Citrix recommends upgrading by one release at a
time. For example, if the software needs to be upgraded from Citrix NetScaler (previously
NetScaler) release 9.2 to release 10.1, the following is the recommended path for the up-
grade:
* Release 9.2 to release 9.3
* Release 9.3 to release 10
* Release 10 to release 10.1
– Verify that the appliance has appropriate license files.
– Verifying the configuration at each step of the upgrade process can give you pointers to
the issue.

• Issue

During an upgrade, if I run the command for synchronizing, the following message appears:

Command failed on the secondary node but succeeded on the primary node.

Resolution

Do not run any dependent commands (set /unset /bind /unbind) when High Availability (HA)
synchronization is in progress.

• Issue

During an upgrade process, traffic does not pass through the new primary node when you run
the force failover command.

Resolution

– Check for problems with the network topology and the switch configurations.
– Run the set L2param -garpreply ENABLED command to enable the GARP reply.
– Try using VMAC if not already used.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 811

NetScaler 12.0

– Run the sendarp –a command from the primary node.

• Issue

In an HA pair, after you run the force HA failover command the devices keep rebooting. The
secondary device does not come up after an upgrade.

Resolution

Check to see if the /var directory is full. If so, remove the old installation files. Run the df –h
command to show the available disk space.

• Issue

After upgrading an HA pair, one of the nodes is listed as state UNKNOWN.

Resolution

– Check to see if both nodes are running the same build. If the builds are not same and HA
nodes have a version mismatch, some of the fields are shown as UNKNOWN when you run
the show ha node command.
– Check to see if the secondary appliance is reachable.

• Issue

After you upgrade the Citrix NetScaler, the interface shows most of the load balancing virtual
servers and services are DOWN.

Resolution

Verify that the SNIP address is active on the secondary appliance. Also, type the show service
command to see if the service is running.

• Issue

After performing an upgrade, all virtual servers are down on the secondary appliance.

Resolution

Enable the HA state and HA synchronization by running the following commands:

– set node hastate enable

– set node hasync enable

Disabling HA is not recommended.

• Issue

After performing a downgrade, the Citrix NetScaler does not boot up properly.

Resolution

Check to see if the correct license has been installed.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 812

NetScaler 12.0

• Issue
In an HA pair, some features do not get synchronized after an upgrade is performed.
Resolution
Run the sync ha file misc command to synchronize the configurations files from the primary
node to secondary node.
• Issue
During reboot, the following error message appears:
One or more commands in ns.conf failedWhat should I do?
Resolution
Make sure that no command in the ns.conf file exceeds the 255 byte limit. In commands that
create policies that are too long for the 255-byte limit, you can use pattern sets to shorten the
policies.
Example:

1 add cs policy p11 -rule ’HTTP.REQ.URL.ENDSWITH_ANY(”

ctx_file_extensions”)’

ctx_file_extensions is a default patset that covers a large number of extensions. In addition to

the default pattern sets, you can create user-defined pattern sets. Add a patset by running the
following command:

1 add patset <name>

Note: Patsets are supported only in release 9.3 or later.

• Issue
When upgrading a Citrix NetScaler VPX appliance, I am told to free up space in /var. What files
do I remove?
Resolution
Remove the old installation files from /var/tmp/ directory. Also remove unwanted files from
/flash.
• Issue
There is no connectivity to the graphical user interface (GUI) when you run the force HA failover
command on the secondary appliance.
Resolution
Log on to the secondary appliance using the command line interface and enable the access to
GUI by running the set ns ip <IP> -gui enabled command.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 813

NetScaler 12.0

• Issue
After performing an upgrade, and when I click on any link on the GUI that has to load a java
applet (Upgrade Wizard or license Wizard), the following error message appears: GUI version
does not match with the kernel version. Please close this instance, clear java plug-in cache
and reopen.
Resolution
– Log on to the Citrix NetScaler using the GUI.
– Navigate to Citrix NetScaler Gateway > Global Settings.
– Click Change Global Settings under Settings.
– In the details pane, under Client Experience, select Default from the UI theme list.
– Click OK.
Note

These troubleshooting steps also apply to issues with configuration loss when downgrading the
software across multiple releases.

For any other issue, see the release notes, Knowledge Center articles, and FAQs.

1.
2. Citrix ADC
3. NetScaler 12.0

FAQs

November 15, 2018

Contributed by:
C
For answers to the questions that you might have about upgrading the Citrix NetScaler firmware, see
the Installing, Upgrading, and Downgrading FAQs.
1.
2. Citrix ADC
3. NetScaler 12.0

New and deprecated commands, parameters, and SNMP OIDs

May 17, 2019

© 1999-2018 Citrix Systems, Inc. All rights reserved. 814

NetScaler 12.0

Contributed by:
C

This section lists the new and deprecated commands, parameters, and SNMP OIDs.

New commands

The following table lists the new commands in release 12.0.

Command group Command

GSLB rename gslb seviceGroup

LSN stat lsn pool
Network stat rnat6 and stat MapBmr
User enable user vserver and disable user vserver

New parameters

Command goup: AAA

Command:

• show aaa session [-sessionKey]

• kill aaa session [-sessionKey]
• set aaa radiusParams {-tunnelEndpointClientIP]
• show aaa radiusParams [-tunnelEndpointClientIP]
• set aaa parameter [-maxSamlDeflateSize] [-persistentLoginAttempts] [-pwdExpiryNotificationDays]
• unset aaa parameter [-maxSamlDeflateSize] [-persistentLoginAttempts] [pwdExpiryNotifica-
tionDays]
• show aaa parameter [maxSamlDeflateSize] [persistentLoginAttempts][pwdExpiryNotificationDays]

Command goup: AppFlow

Command:

• set appflow param [-lsnLogging] [-emailAddress]

• show appflow param [lsnLogging] [-emailAddress]

Command goup: Application Firewall

Command:

• bind appfw [-logExpression]

• unbind appfw profile [-logExpression]

© 1999-2018 Citrix Systems, Inc. All rights reserved. 815

NetScaler 12.0

• show appfw profile [-logExpression] [expression]

• show appfw xmlerrorpage [-src]
• show appfw signatures [-src]
Command goup: Audit
Command:
• add audit syslogAction [-urlFiltering]
• set audit syslogAction [-urlFiltering]
• unset audit syslogAction [-urlFiltering]
• show audit syslogAction [-urlFiltering]
• add audit nslogAction [-urlFiltering]
• set audit nslogAction [-urlFiltering]
• unset audit nslogAction [-urlFiltering]
• show audit nslogAction [-urlFiltering]
• set audit syslogParams [-urlFiltering]
• unset audit syslogParams [-urlFiltering]
• show audit syslogParams [-urlFiltering]
• set audit nslogParams [-urlFiltering]
• unset audit nslogParams [-urlFiltering]
• show audit nslogParams [-urlFiltering]
Command goup: Authentication
Command:
• dd authentication radiusAction [-tunnelEndpointClientIP]
• set authentication radiusAction [-tunnelEndpointClientIP]
• show authentication radiusAction [-tunnelEndpointClientIP]
• add authentication ldapAction [-Attributes] [-sshPublicKey] [-email]
• set authentication ldapAction [-Attributes] [-sshPublicKey] [-pushService] [-email]
• show authentication ldapAction [-Attributes] [-sshPublicKey] [-pushService] [-email]
• add authentication samlAction [-groupNameField] [-audience] [-metadataUrl] [-metadataRefreshInterval]
• set authentication samlAction [-groupNameField] [-audience] [-metadataUrl][-metadataRefreshInterval]
• show authentication samlAction [-groupNameField] [-audience] [-metadataUrl] [-metadataRefreshInterval]
[-metadataImportStatus]
• add authentication samlIdPProfile [-metadataUrl] [-metadataRefreshInterval]
• set authentication samlIdPProfile [-metadataUrl] [-metadataRefreshInterval]
• set authentication samlIdPProfile [-metadataUrl] [-metadataRefreshInterval]
• show authentication samlIdPProfile [-metadataUrl] [-metadataRefreshInterval][-metadataImportStatus]
• add authentication OAuthAction [-UserInfoURL] [-CertFilePath] [-grantType]
• set authentication OAuthAction [-UserInfoURL] [-CertFilePath] [-grantType]
• show authentication OAuthAction [-UserInfoURL] [-CertFilePath] [-grantType]

© 1999-2018 Citrix Systems, Inc. All rights reserved. 816

NetScaler 12.0

• add authentication OAuthIDPProfile [-relyingPartyMetadataURL] [-refreshInterval][-encryptToken]

• set authentication OAuthIDPProfile [-relyingPartyMetadataURL] [-refreshInterval][-encryptToken]
• how authentication OAuthIDPProfile [-relyingPartyMetadataURL] [-refreshInterval][-encryptToken]
[-OAuthStatus]

Command goup: Cache Redirection

Command:

• show cr vserver [-ipset]

Command goup: Content Switching

Command:

• add cs vserver [-ipset]

• set cs vserver [-ipset]
• bind cs vserver [-analyticsProfile]
• unbind cs vserver [-analyticsProfile]
• show cs vserver [-ipset] [-analyticsProfile]

Command goup: GSLB

Command:

• show gslb site [-svcitmnum] [-svcgrnm]

• bind gslb vserver [-serviceGroupName]
• unbind gslb vserver [-serviceGroupName]
• show gslb vserver [-svcitmnum] [-svcgrnm] [-serverName] [-serviceGroupName]
• show gslb domain [-serviceGroupName]
• show gslb syncStatus [-summary]
• add gslb serviceGroup [-sitePersistence]
• set gslb serviceGroup [-sitePersistence]
• unset gslb serviceGroup [-sitePersistence]
• bind gslb serviceGroup [-sitePrefix]
• show gslb serviceGroup [-sitePersistence] [-sitePrefix]

Command goup: Load Balancing

Command:

• add lb vserver [-ipset]

• set lb vserver [-ipset]
• bind lb vserver [-analyticsProfile]
• unbind lb vserver [-analyticsProfile]
• show lb vserver [-ipset] [-analyticsProfile]

Command goup: LSN

© 1999-2018 Citrix Systems, Inc. All rights reserved. 817

NetScaler 12.0

Command:

• add lsn pool [-totalpoolipsbound]

• bind lsn pool [-ownerNode] [-lastip]
• unbind lsn pool [-ownerNode] [-firstip] [-lastip]
• show lsn pool [-ownerNode] [-firstip] [-lastip] [-totalpoolipsbound]
• add lsn client [-clientType]
• show lsn client [-clientType]
• add lsn logprofile [-logipfix]
• set lsn logprofile [-logipfix]
• show lsn logprofile [-logipfix]
• bind lsn appsprofile [-firstport] [-lastport]
• unbind lsn appsprofile [-firstport] [-lastport]
• show lsn appsprofile [-firstport] [-lastport]

Command goup: Network

Command:

• add netProfile [-MBF]

• set netProfile [-MBF]
• show netProfile [-MBF]
• set L3Param [-allowClassEIPv4]
• show L3Param [-allowClassEIPv4]

Command goup: Network

Command:

• add ns acl [-type] [-dfdhash] [-stateful]

• set ns acl [-dfdhash] [-stateful]
• unset ns acl [-stateful]
• show ns acl [-type] [-dfdhash] [-stateful]
• add ns acl6 [-type] [-dfdhash] [-dfdprefix] [-stateful] [-logstate] [-ratelimit]
• set ns acl6 [-logstate] ratelimit] [-dfdhash] [-dfdprefix] [-stateful]
• unset ns acl6 [-logstate] [-ratelimit] [-stateful]
• show ns acl6 [-type] [-logstate] [-ratelimit] [-dfdhash] [-dfdprefix] [-stateful]
• add ns ip6 [-decrementHopLimit]
• set ns ip6 [-decrementHopLimit]
• show ns ip6 [-decrementHopLimit]
• add ns ip [-decrementTTL]
• set ns ip [-decrementTTL]
• show ns ip [-decrementTTL]
• add ns tcpProfile [-tcpFastOpenCookieSize]

© 1999-2018 Citrix Systems, Inc. All rights reserved. 818

NetScaler 12.0

• set ns tcpProfile [-tcpFastOpenCookieSize]

• show ns tcpProfile [-tcpFastOpenCookieSize]
• renumber ns acls [-type]
• clear ns acls [-type]
• apply ns acls [-type]
• show ns license [-isSWGLic] [-RemoteContentInspection]
• show ns config [-primaryIP6]
• clear ns acls6 [-type]
• apply ns acls6 [-type]
• renumber ns acls6 [-type]
• show ns feature [-CI]
• set ns diameter [-ownerNode]
• show ns diameter [-ownerNode]
• show ns hardware [-bmcRevision]
• set ns capacity [-vcpu]
• unset ns capacity [-vcpu]
• show ns capacity [-vcpuCount] [-maxVcpuCount]

Command goup: RDP

Command:

• add rdp clientprofile [-randomizeRDPFilename] [-rdpLinkAttribute]

• set rdp clientprofile [-randomizeRDPFilename] [-rdpLinkAttribute]
• show rdp clientprofile [-randomizeRDPFilename] [-rdpLinkAttribute]
• add rdp serverprofile [-rdpRedirection]
• set rdp serverprofile [-rdpRedirection]
• show rdp serverprofile [-rdpRedirection]

Command goup: SSL

Command:

• show ssl certKey [-ocspBindReferences]

• add ssl action [-ssllogProfile]
• show ssl action [-ssllogProfile]
• add ssl ocspResponder [-ocspUrlResolveTimeout] [-httpMethod]
• set ssl ocspResponder [-ocspUrlResolveTimeout] [-httpMethod]
• show ssl ocspResponder [-ocspUrlResolveTimeout] [-httpMethod]
• create ssl certReq [-subjectAltName]
• create ssl cert [-subjectAltName]
• set ssl vserver [-zeroRttEarlyData] [-tls13SessionTicketsPerAuthContext][-dheKeyExchangeWithPsk]
• show ssl vserver [-zeroRttEarlyData] [-tls13SessionTicketsPerAuthContext][-dheKeyExchangeWithPsk]

© 1999-2018 Citrix Systems, Inc. All rights reserved. 819

NetScaler 12.0

• add ssl profile [-ssllogProfile] [-zeroRttEarlyData] [-tls13SessionTicketsPerAuthContext][-

dheKeyExchangeWithPsk]
• set ssl profile [-ssllogProfile] [-zeroRttEarlyData] [-tls13SessionTicketsPerAuthContext][-
dheKeyExchangeWithPsk]
• show ssl profile [-ssllogProfile] [-zeroRttEarlyData][-tls13SessionTicketsPerAuthContext]
[-dheKeyExchangeWithPsk]

Command goup: Stream

Command:

• add stream identifier [-trackAckOnlyPackets]

• set stream identifier [-trackAckOnlyPackets]
• show stream identifier [-trackAckOnlyPackets]

Command goup: System

Command:

• set system parameter [-allowDefaultPartition] [-reauthOnAuthParamChange][-removeSensitiveFiles]

• show system parameter [-allowDefaultPartition] [-reauthOnAuthParamChange][-removeSensitiveFiles]

Command goup: Subscriber

Command:

• add subscriber profile [-vlan]

• set subscriber profile [-vlan]
• rm subscriber profile [-vlan]
• show subscriber profile [-vlan]
• clear subscriber sessions [-vlan]
• show subscriber sessions [-vlan]

Command goup: Tunnel

Command:

• show tunnel trafficPolicy [-piTxBytes] [-piRxBytes] [-piCltTTLB] [-piCltTransactions][-piSvrTTLB]

[-piSvrTransactions]

Command goup: User

Command:

• add user vserver [-state]

• enable user vserver [-state]
• disable user vserver [-state]
• show user vserver [-state]

© 1999-2018 Citrix Systems, Inc. All rights reserved. 820

NetScaler 12.0

Command goup: User

Command:

• bind vpn vserver [-analyticsProfile]

• unbind vpn vserver [-analyticsProfile]
• show vpn vserver [-ipset] [-analyticsProfile]
• show vpn trafficPolicy [-piHits]
• add vpn samlSSOProfile [-signatureService]
• set vpn samlSSOProfile [-signatureService]
• show vpn samlSSOProfile [-signatureService]
• add vpn url [-appJson]
• set vpn url [-appJson]
• show vpn url [-appJson]
• show vpn sessionPolicy [-piHits]
• bind vpn global [-certkeyName] [-cacert]
• unbind vpn global [-certkeyName] [-cacert]
• show vpn global [-certkeyName] [-cacert] [-crlCheck] [-ocspCheck]
• set vpn parameter [-backendServerSni] [-backendCertValidation]
• show vpn parameter [-backendServerSni] [-backendCertValidation][-vpnsessionpolicyBindtype]
[-vpnsessionpolicyCount]

New SNMP OIDs

For more information, see the SNMP OID Reference guide.

1.
2. Citrix ADC
3. NetScaler 12.0

Deprecated features and functionalities

February 15, 2019

Contributed by:
C

Some of the NetScaler functionalities are deprecated in 12.0 and in its subsequent releases. Citrix
recommends that you do not use these features through the NetScaler command interface, NetScaler
GUI, or Nitro automation. However, to ease the transition to new alternatives, the deprecated features

© 1999-2018 Citrix Systems, Inc. All rights reserved. 821

NetScaler 12.0

are usable for a limited time and will be removed in future releases. Citrix recommends you to use the
below alternatives for the following set of deprecated functionalities.

Deprecated features and Its alternatives in NetScaler 12.0

A list of NetScaler features and functionalities are deprecated. For complete information, You can refer
to Deprecated List pdf.

Using NSPEPI conversion tool

You can use the nspepi tool to convert commands, expressions, and configurations. For more infor-
mation, see Converting Expressions by Using NSPEPI Tool topic.
Here is a list of conversion from Classic expressions to Advanced expressions.

• ns_true -> true

• ns_false -> false
• REQ.HTTP -> HTTP.REQ
• RES.HTTP -> HTTP.RES
• HEADER “foo” -> HEADER(“foo”)
• CONTAINS ”bar” -> .CONTAINS(“bar”) [Note use of “.”.]
• REQ.IP -> CLIENT.IP
• RES.IP -> SERVER.IP
• SOURCEIP -> SRC
• DESTIP -> DST
• REQ.TCP -> CLIENT.TCP
• RES.TCP -> SERVER.TCP
• SOURCEPORT -> SRCPORT
• DESTPORT -> DSTPORT
• STATUSCODE -> STATUS
• REQ.SSL.CLIENT.CERT -> CLIENT.SSL.CLIENT_CERT

AppQoE Use Cases

When using AppQoE as an alternative for SureConnect feature, you can refer to the following use case
configurations.

Use Case 1: To limit simultaneous download of huge files and display loading screen:

1 add appqoe action NS_RESP -respondWith NS -maxConn 50

2

© 1999-2018 Citrix Systems, Inc. All rights reserved. 822

NetScaler 12.0

3 add appqoe policy POL_DWN_PKG -rule “ HTTP.REQ.URL.CONTAINS(\ “ tar.gz\

” ) ” -action NS_RESP
4
5 bind lb vserver v1 -policyName POL_DWN_PKG -priority 8

Use Case 2: To limit simultaneous download of huge files and display loading screen with alter-
nate content:

1 add appqoe action ACS_RESP -respondWith ACS -altContentsvcName s2 -

altContentPath /netscaler/alt.html -maxConn 50
2
3 add appqoe policy POL_DWN_ACS -rule “ HTTP.REQ.URL.CONTAINS(\ “ tar.gz\
” ) ” -action ACS_RESP
4
5 bind lb vserver v1 -policyName POL_DWN_ACS -priority 9

Use Case 3: Custom loading screen:

1 import appqoCe customResp [http://<location>]|[local:<file>]

simple_custom_resp
2
3 add appqoe action CUST_RESP -respondWith NS simple_custom_resp -maxConn
50
4
5 add appqoe policy POL_CRESP -rule “ HTTP.REQ.URL.CONTAINS(\ “ tar.gz\ ” )
” -action CUST_RESP
6
7 bind lb vserver v1 -policyName POL_CRESP -priority 10

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

AAA application traffic

September 28, 2018

Contributed by:
C
Many companies restrict web site access to valid users only, and control the level of access permitted
to each user. The AAA feature allows a site administrator to manage access controls with the NetScaler

© 1999-2018 Citrix Systems, Inc. All rights reserved. 823

NetScaler 12.0

appliance instead of managing these controls separately for each application. Doing authentication
on the appliance also permits sharing this information across all web sites within the same domain
that are protected by the appliance.

The AAA feature supports authentication, authorization, and auditing for all application traffic. To
use AAA, you must configure authentication virtual servers to handle the authentication process and
traffic management virtual servers to handle the traffic to web applications that require authentica-
tion. You also configure your DNS to assign FQDNs to each virtual server. After configuring the virtual
servers, you configure a user account for each user that will authenticate via the NetScaler appliance,
and optionally you create groups and assign user accounts to groups. After creating user accounts
and groups, you configure policies that tell the appliance how to authenticate users, which resources
to allow users to access, and how to log user sessions. To put the policies into effect, you bind each
policy globally, to a specific virtual server, or to the appropriate user accounts or groups. After con-
figuring your policies, you customize user sessions by configuring session settings and binding your
session policies to the traffic management virtual server. Finally, if your intranet uses client certs, you
set up the client certificate configuration.

Before configuring AAA, you should be familiar with and understand how to configure load balancing,
content switching, and SSL on the NetScaler appliance.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

How AAA works

January 6, 2019

Contributed by:
C

AAA provides security for a distributed internet environment by allowing any client with the proper
credentials to connect securely to protected application servers from anywhere on the Internet. This
feature incorporates the three security features of AAA. Authentication enables the NetScaler appli-
ance to verify the client’s credentials, either locally or with a third-party authentication server, and
allow only approved users to access protected servers. Authorization enables the ADC to verify which
content on a protected server it should allow each user to access. Auditing enables the ADC to keep a
record of each user’s activity on a protected server.

To understand how AAA works in a distributed environment, consider an organization with an intranet
that its employees access in the office, at home, and when traveling. The content on the intranet is

© 1999-2018 Citrix Systems, Inc. All rights reserved. 824

NetScaler 12.0

confidential and requires secure access. Any user who wants to access the intranet must have a valid
user name and password. To meet these requirements, the ADC does the following:
• Redirects the user to the login page if the user accesses the intranet without having logged in.
• Collects the user’s credentials, delivers them to the authentication server, and caches them in
a directory that is accessible through LDAP.
• Verifies that the user is authorized to access specific intranet content before delivering the user’s
request to the application server.
• Maintains a session timeout after which users must authenticate again to regain access to the
intranet. (You can configure the timeout.)
• Logs the user accesses, including invalid login attempts, in an audit log.
Authentication requires that several entities: the client, the
NetScaler appliance, the external authentication server if one is used, and the application server, re-
spond to each other when prompted by performing a complex series of tasks in the correct order. If
you are using an external authentication server, this process can be broken down into the following
fifteen steps.
1. The client sends a GET request for a URL on the application server.
2. The NetScaler appliance’s traffic management virtual server redirects the request to the appli-
cation server.
3. The application server determines that the client has not been authenticated, and therefore
sends an HTTP 200 OK response via the TM vserver to the client. The response contains a hidden
script that causes the client to issue a POST request for /cgi/tm.
4. The client sends a POST request for /cgi/tm.
5. The NetScaler appliance’s authentication virtual server redirects the request to the authentica-
tion server.
6. The authentication server creates an authentication session, sets and caches a cookie that con-
sists of the initial URL and the domain of the traffic management virtual server, and then sends
an HTTP 302 response via the authentication virtual server, redirecting the client to /vpn/in-
dex.html.
7. The client sends a GET request for /vpn/index.html.
8. The authentication virtual server redirects the client to the authentication server login page.
9. The client sends a GET request for the login page, enters credentials, and then sends a POST
request with the credentials back to the login page.
10. The authentication virtual server redirects the POST request to the authentication server.
11. If the credentials are correct, the authentication server tells the authentication virtual server to
log the client in and redirect the client to the URL that was in the initial GET request.
12. The authentication virtual server logs the client in and sends an HTTP 302 response that redi-
rects the client to the initially requested URL.
13. The client sends a GET request for their initial URL.
14. The traffic management virtual server redirects the GET request to the application server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 825

NetScaler 12.0

15. The application server responds via the traffic management virtual server with the initial URL.

If you use local authentication, the process is similar, but the authentication virtual server handles
all authentication tasks instead of forwarding connections to an external authentication server. The
following figure illustrates the authentication process.

Figure 1. Authentication Process Traffic Flow

When an authenticated client requests a resource, the ADC, before sending the request to the applica-
tion server, checks the user and group policies associated with the client account, to verify that the
client is authorized to access that resource. The ADC handles all authorization on protected applica-
tion servers. You do not need to do any special configuration of your protected application servers.

AAA traffic management handles password changes for users by using the protocol-specific method
for the authentication server. For most protocols, neither the user nor the administrator needs to do
anything different than they would without AAA traffic management. Even when an LDAP authenti-
cation server is in use, and that server is part of a distributed network of LDAP servers with a single
designated domain administration server, password changes are usually handled seamlessly. When
an authenticated client of an LDAP server changes his or her password, the client sends a credential
modify request to AAA traffic management, which forwards it to the LDAP server. If the user’s LDAP
server is also the domain administration server, that server responds appropriately and AAA traffic
management then performs the requested password change. Otherwise, the LDAP server sends AAA
traffic management an LDAP_REFERRAL response to the domain administration server. AAA traffic
management follows the referral to the indicated domain administration server, authenticates to that
server, and performs the password change on that server.

When configuring AAA traffic management with an LDAP authentication server, the system adminis-
trator must keep the following conditions and limitations in mind:

• AAA traffic management assumes that the domain administration server in the referral accepts
the same bind credentials as the original server.
• AAA traffic management only follows LDAP referrals for password change operations. In other
cases AAA traffic management refuses to follow the referral.
• AAA traffic management only follows one level of LDAP referrals. If the second LDAP server also
returns a referral, AAA traffic management refuses to follow the second referral.

The ADC supports auditing of all states and status information, so you can see the details of what each
user did while logged on, in chronological order. To provide this information, the appliance logs each
event, as it occurs, either to a designated audit log file on the appliance or to a syslog server. Auditing
requires configuring the appliance and any syslog server that you use.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

© 1999-2018 Citrix Systems, Inc. All rights reserved. 826

NetScaler 12.0

Enabling AAA

September 14, 2018

Contributed by:
C

To use the AAA - Application Traffic feature, you must enable it. You can configure AAA entities—such
as the authentication and traffic management virtual servers—before you enable the AAA feature, but
the entities will not function until the feature is enabled.

To enable AAA by using the command line interface

At the command prompt, type the following commands to enable AAA and verify the configuration:

• enable ns feature AAA

• show ns feature

Example

• enable feature AAA

Done

• show ns feature

1 Feature Acronym Status

2 ------- ------- ------
3 1) Web Logging WL OFF
4 2) Surge Protection SP ON
5 .
6 .
7 .
8 15) AAA AAA ON
9 .
10 .
11 .
12 23) HTML Injection HTMLInjection ON
13 24) NetScaler Push push OFF Done

To enable AAA by using the configuration utility

1. Navigate to System > Settings.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 827

NetScaler 12.0

2. In the details pane, under Modes and Features, click Change basic features.
3. In the Configure Basic Features dialog box, select the Authentication, Authorization and Audit-
ing check box.
4. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Setting up an authentication virtual server

December 21, 2018

Contributed by:
C

All authentication requests are redirected by the traffic management virtual server (load balancing
or content switching) to the authentication virtual sever. This virtual server processes the associated
authentication policies and accordingly provides access to the application.

Note

You cannot bind traffic management policies to AAA virtual servers.

To set up an authentication virtual server by using the CLI

1. Enable the AAA feature.

ns-cli-prompt>enable ns feature AAA

2. Configure an authentication virtual server. It must be of type SSL and make sure to bind SSL
certificate-key pair to the virtual server.

ns-cli-prompt> add authentication vserver <name> SSL <ipaddress> <port>

ns-cli-prompt> bind ssl certkey <auth-vserver-name> <certkey>

3. Specify the FQDN of the domain for the authentication virtual server.

ns-cli-prompt> set authentication vserver <name> -authenticationDomain <FQDN>

4. Associate the authentication virtual server to the relevant traffic management virtual server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 828

NetScaler 12.0

Note:

The FQDN of the traffic management virtual server must be in the same domain as the FQDN of
the authentication virtual server for the domain session cookie to function correctly.

On the traffic management virtual server:

• Enable authentication.
• Specify the FQDN of the authentication virtual server as the authentication host of the traffic
management virtual server.
• [Optional] Specify the authentication domain on the traffic management virtual server.

Note:

If you do not configure the authentication domain, the appliance assigns an FQDN that con-
sists of the FQDN of the authentication virtual server without the hostname portion. For ex-
ample, if domain name of the authentication virtual server is tm.xyz.bar.com, the appliance
assigns xyz.bar.com as the authentication domain.

For load balancing:\

ns-cli-prompt> set lb vserver <name> -authentication ON -authenticationhost <FQDN> [-
authenticationdomain <authdomain>]

For content switching:\

ns-cli-prompt> set cs vserver <name> <protocol> <IPAddress> <port>

1. Verify that both the virtual servers are UP and configure correctly.

ns-cli-prompt> show authentication vserver <name>

To set up an authentication virtual server by using the GUI

1. Enable the AAA feature.

Navigate to System > Settings, click Configure Basic features, and enable Authentication,
Authorization and Auditing.

2. Configure the authentication virtual server.

Navigate to Security > AAA - Application Traffic > Virtual Servers, and configure as required
(refer to the configurations provided in the CLI procedure provided above).

3. Configure the traffic management virtual server for authentication.

For load balancing:

Navigate to Traffic Management > Load Balancing > Virtual Servers, and configure the virtual
server as required (refer to the configurations provided in the CLI procedure provided above).

© 1999-2018 Citrix Systems, Inc. All rights reserved. 829

NetScaler 12.0

For content switching:

Navigate to Traffic Management > Content Switching > Virtual Servers, and configure the
virtual server as required (refer to the configurations provided in the CLI procedure provided
above).

4. Verify the authentication setup.

Navigate to Security > AAA - Application Traffic > Virtual Servers, and check the details of the
relevant authentication virtual server.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Configuring the authentication virtual server

September 21, 2018

Contributed by:
C

To configure AAA, first configure an authentication virtual server to handle authentication traffic. Next,
bind an SSL certificate-key pair to the virtual server to enable it to handle SSL connections.
For additional information about configuring SSL and creating a certificate-key pair, see SSL certifi-
cates.

To configure an authentication virtual server by using the command line interface

To configure an authentication virtual server and verify the configuration, at the command prompt
type the following commands in the order shown:

• add authentication vserver <name> ssl <ipaddress>

• show authentication vserver <name>

• bind ssl certkey <certkeyName>

• show authentication vserver <name>

• set authentication vserver <name> -authenticationDomain <FQDN>

• show authentication vserver <name>

Example

© 1999-2018 Citrix Systems, Inc. All rights reserved. 830

NetScaler 12.0

1> add authentication vserver Auth-Vserver-2 SSL 10.102.29.77 443

2 Done
3> show authentication vserver Auth-Vserver-2
4 Auth-Vserver-2 (10.102.29.77:443) - SSL Type: CONTENT
5 State: DOWN[Certkey not bound]
6 Client Idle Timeout: 180 sec
7 Down state flush: DISABLED
8 Disable Primary Vserver On Down : DISABLED
9 Authentication : ON
10 Current AAA Users: 0
11 Done
12 > bind ssl certkey Auth-Vserver-2 Auth-Cert-1
13 Done
14 > show authentication vserver Auth-Vserver-2
15 Auth-Vserver-2 (10.102.29.77:443) - SSL Type: CONTENT
16 State: UP
17 Client Idle Timeout: 180 sec
18 Down state flush: DISABLED
19 Disable Primary Vserver On Down : DISABLED
20 Authentication : ON
21 Current AAA Users: 0
22 Authentication Domain: myCompany.employee.com
23 Done
24 > set authentication vserver Auth-Vserver-2 -AuthenticationDomain
myCompany.employee.com
25 Done
26 > show authentication vserver Auth-Vserver-2
27 Auth-Vserver-2 (10.102.29.77:443) - SSL Type: CONTENT
28 State: DOWN[Certkey not bound]
29 Client Idle Timeout: 180 sec
30 Down state flush: DISABLED
31 Disable Primary Vserver On Down : DISABLED
32 Authentication : ON
33 Current AAA Users: 0
34 Authentication Domain: myCompany.employee.com
35 Done

To configure an authentication virtual server by using the configuration utility

1. Navigate to Security > AAA - Application Traffic > Virtual Servers.

2. In the details pane, do one of the following:
• To create a new authentication virtual server, click Add.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 831

NetScaler 12.0

• To modify an existing authentication virtual server, select the virtual server, and then click
Edit. The Configuration dialog opens with the Basic Settings area expanded.

3. Specify values for the parameters as follows (asterisk indicates a required parameter):

• Name*—name (Cannot be changed for a previously created virtual server)

• IP Address*—ipaddress
• Domain*—authenticationDomain
• Failed login timeout—failedLoginTimeout (Seconds allowed before login fails and user
must start login process again.)
• Max login attempts—maxLoginAttempts (Number of login attempts allowed before user is
locked out)

Note: The authentication virtual server uses only the SSL protocol and port 443, so those
options are greyed out. Any options that are not mentioned are not relevant and should
be ignored.

4. Click Continue to display the Certificates area.

5. In the Certificates area, configure any SSL certificates you want to use with this virtual server.

• To configure a CA certificate, click the arrow on the right of CA Certificate to display the CA
Cert Key dialog box, select the certificate you want to bind to this virtual server, and click
Save.
• To configure a server certificate, click the arrow on the right of Server Certificate, and fol-
low the same process as for CA certificate.

6. Click Continue to display the Advanced Authentication Policies area.

7. If you want to bind an advanced authentication policy to the virtual server, click the arrow on
the right side of the line to display the Authentication Policy dialog box, choose the policy that
you want to bind to the server, set the priority, and then click OK.

8. Click Continue to display the Basic Authentication Policies area.

9. If you want to create a basic authentication policy and bind it to the virtual server, click the plus
sign to display the Policies dialog box, and follow the prompts to configure the policy and bind
it to this virtual server.

10. Click Continue to display the 401-Based Virtual Servers area.

11. In the 401-Based Virtual Servers area, configure any load balancing or content switching virtual
servers that you want to bind to this virtual server.

• To bind a load balancing virtual server, click the arrow to the right of LB virtual server to
display the LB Virtual Servers dialog box, and follow the prompts.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 832

NetScaler 12.0

• To bind a content switching virtual server, click the arrow to the right of CS virtual server
to display the CS Virtual Servers dialog box, and follow the same process as to bind an LB
virtual server.

12. If you want to create or configure a group, in the Groups area click the arrow to display the
Groups dialog box, and follow the prompts.

13. Review your settings, and when you are finished, click Done. The dialog box closes. If you cre-
ated a new authentication virtual server, it now appears in the Configuration window list.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Configuring a traffic management virtual server

September 21, 2018

Contributed by:
C

After you have created and configured your authentication virtual server, you next create or configure
a traffic management virtual server and associate your authentication virtual sever with it. You can
use either a load balancing or content switching virtual server for a traffic management virtual server.
For more information about creating and configuring either type of virtual server, see the Citrix Traffic
Management Guide at Traffic Management.

Note

The FQDN of the traffic management virtual server must be in the same domain as the FQDN of
the authentication virtual server for the domain session cookie to function correctly.

You configure a traffic management virtual server for AAA by enabling authentication and then as-
signing the FQDN of the authentication server to the traffic management virtual server. You can also
configure the authentication domain on the traffic management virtual server at this time. If you do
not configure this option, the NetScaler appliance assigns the traffic management virtual server an
FQDN that consists of the FQDN of the authentication virtual server without the hostname portion.
For example, if domain name of the authentication virtual server is tm.xyz.bar.com, the appliance
assigns xyz.bar.com. as the authentication domain.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 833

NetScaler 12.0

To configure a TM virtual server for AAA by using the command line interface

At the command prompt, type one of the following sets of commands to configure a TM virtual server
and verify the configuration:

• set lb vserver <name> ‒authentication ON -authenticationhost <FQDN> [-

authenticationdomain <authdomain>]

• show lb vserver <name>

• set cs vserver <name> ‒authentication ON -authenticationhost <FQDN> [-

authenticationdomain <authdomain>]

• show cs vserver <name>

Example

1> set lb vserver vs-cont-sw -Authentication ON -AuthenticationHost

mywiki.index.com
2 Done
3 > show lb vserver vs-cont-sw
4 vs-cont-sw (0.0.0.0:0) - TCP Type: ADDRESS
5 State: DOWN
6 Last state change was at Wed Aug 19 10:03:15 2009 (+410 ms)
7 Time since last state change: 5 days, 20:00:40.290
8 Effective State: DOWN
9 Client Idle Timeout: 9000 sec
10 Down state flush: ENABLED
11 Disable Primary Vserver On Down : DISABLED
12 No. of Bound Services : 0 (Total) 0 (Active)
13 Configured Method: LEASTCONNECTION
14 Mode: IP
15 Persistence: NONE
16 Connection Failover: DISABLED
17 Authentication: ON Host: mywiki.index.com
18 Done

To configure a TM virtual server for AAA by using the configuration utility

1. In the navigation pane, do one of the following.

• Navigate to Traffic Management > Load Balancing > Virtual Servers.
• Navigate to Traffic Management > Content Switching > Virtual Servers
• In the details pane, select the virtual server on which you want to enable authentication,
and then click Edit.
• In the Domain text box, type the authentication domain.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 834

NetScaler 12.0

• In the Advanced menu on the right, select Authentication.

• Choose either Form Based Authentication or 401 Based Authentication, and fill in the
Authentication information.
– For Form Based Authentication, enter the Authentication FQDN (the fully-qualified do-
main name of the authentication server), the Authentication VServer (the IP address
of the authentication virtual server), and the Authentication Profile (the profile to use
for authentication).
– For 401 Based Authentication, enter the Authentication VServer and the Authentica-
tion Profile only.
• Click OK. A message appears in the status bar, stating that the vserver has been configured
successfully.

Simplified login protocol support for AAA

The login protocol between AAA traffic management virtual servers and AAA virtual servers is simpli-
fied to use internal mechanisms as opposed to sending the encrypted data through query parameters.
By leveraging this feature, the replay of requests is prevented.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Configuring DNS

September 14, 2018

Contributed by:
C

For the domain session cookie used in the authentication process to function correctly, you must con-
figure DNS to assign both the authentication and the traffic management virtual servers to FQDNs
in the same domain. For information about how to the configure DNS address records, see Domain
Name System.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

© 1999-2018 Citrix Systems, Inc. All rights reserved. 835

NetScaler 12.0

Verifying your setup for AAA

September 21, 2018

Contributed by:
C

After you configure authentication and traffic management virtual servers and before you create user
accounts, you should verify that both virtual servers are configured correctly and are in the UP state.

To verify authentication virtual server setup by using the command line interface

At the command prompt, type the following command:

show authentication vserver <name>

1 > show authentication vserver Auth-Vserver-2

2 Auth-Vserver-2 (10.102.29.77:443) - SSL Type: CONTENT
3 State: UP
4 Client Idle Timeout: 180 sec
5 Down state flush: DISABLED
6 Disable Primary Vserver On Down : DISABLED
7 Authentication : ON
8 Current AAA Users: 0
9 Authentication Domain: myCompany.employee.com
10 Done

To verify your AAA virtual server setup by using the configuration utility

1. Navigate to Security > AAA - Application Traffic > Virtual Servers.

2. Review the information in the AAA Virtual Servers pane to verify that your configuration is correct
and your authentication virtual server is accepting traffic. You can select a specific virtual server
to view detailed information in the details pane.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

© 1999-2018 Citrix Systems, Inc. All rights reserved. 836

NetScaler 12.0

Creating an authentication profile

September 14, 2018

Contributed by:
C

When you want the same authentication settings to be used by multiple traffic management virtual
servers, you can create an authentication profile which specifies the authentication virtual server, the
authentication host, the authentication domain, and authentication level.

This authentication profile can be associated with the relevant traffic management virtual servers.

To configure an authentication profile by using the CLI

• Create the authentication profile and set the required parameters.

For example, to create a profile with an authentication virtual server named “authVS”.

ns-cli-prompt> add authentication authnProfile authProfile1 -authnVsName authVS -

authenticationHost authnVS.example.com -authenticationDomain example.com -authenticationLevel

Note:

The authentication weight or level will depend on the virtual server to which the traffic
will bound. A session that is created by authenticating against traffic management virtual
server at given level cannot be used to access traffic management virtual server at a higher level.

• Bind the authentication profile to the relevant traffic management virtual servers.

For example, to bind authProfile1 to a load balancing virtual server named “vserver1”.

ns-cli-prompt> set lb vserver vserver1 -authnProfile authProfile1

To configure an authentication profile by using the GUI

In the Configuration tab, navigate to Security > AAA - Application Traffic > Authentication Profile,
and configure the authentication profile as required.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

© 1999-2018 Citrix Systems, Inc. All rights reserved. 837

NetScaler 12.0

Configuring users and groups

September 21, 2018

Contributed by:
C

After configuring the AAA basic setup, you create users and groups. You first create a user account for
each person who will authenticate via the NetScaler appliance. If you are using local authentication
controlled by the NetScaler appliance itself, you create local user accounts and assign passwords to
each of those accounts.

You also create user accounts on the NetScaler appliance if you are using an external authentication
server. In this case, however, each user account must exactly match an account for that user on the
external authentication server, and you do not assign passwords to the user accounts that you create
on the NetScaler appliance. The external authentication server manages the passwords for users that
authenticate with the external authentication server.

If you are using an external authentication server, you can still create local user accounts on the
NetScaler appliance if, for example, you want to allow temporary users (such as visitors) to log in but
do not want to create entries for those users on the authentication server. You assign a password to
each local user account, just as you would if you were using local authentication for all user accounts.

Each user account must be bound to policies for authentication and authorization. To simplify this
task, you can create one or more groups and assign user accounts to them. You can then bind policies
to groups instead of individual user accounts.

To create a local AAA user account by using the command line interface

At the command prompt, type the following commands to create a local AAA user account and verify
the configuration:

• add aaa user <username> [‒password <password>]

• show aaa user

Example

1 > add aaa user user-2 -password emptybag

2 Done
3 > show aaa user
4 1) UserName: user-1
5 2) UserName: user-2
6 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 838

NetScaler 12.0

To change the password for an existing AAA local user account by using the command
line interface

At the command prompt, type the following command and, when prompted, type the new password:

1 set aaa user <username>

Example

1 > set aaa user user-2

2 Enter password:
3 Done

To configure AAA local users by using the configuration utility

1. Navigate to Security > AAA - Application Traffic > Users

2. In the details pane, do one of the following:
• To create a new user account, click Add.
• To modify an existing user account, select the user account, and then click Open.
3. In the Create AAA User dialog box, in the User Name text box, type a name for the user.
4. If creating a locally authenticated user account, clear the External Authentication check box
and provide a local password that the user will use to log on
5. Click Create or OK, and then click Close. A message appears in the status bar, stating that the
user has been configured successfully.

To create AAA local groups and add users to them by using the command line interface

At the command prompt, type the following commands. Type the first command one time, and type
the second command once for each user:

• add aaa group <groupname>

• show aaa group

Example

1 > add aaa group group-2

2 Done
3 > show aaa group
4 1) GroupName: group-1
5 2) GroupName: group-2
6 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 839

NetScaler 12.0

• bind aaa group <groupname> -username <username>

Example

1 > bind aaa group group-2 -username user-2

2 Done
3 > show aaa group group-2
4 GroupName: group-2
5
6 UserName: user-2
7 Done

To remove users from an AAA group by using the command line interface

At the command prompt, unbind users from the group by typing the following command once for
each user account that is bound to the group:

• unbind aaa group <groupname> -username <username>

Example

1 unbind aaa group group-hr -username user-hr-1

2 Done

To remove an AAA group by using the command line interface

First remove all users from the group. Then, at the command prompt, type the following command
to remove an AAA group and verify the configuration:

• rm aaa group <groupname>

• show aaa group

Example

1 rm aaa group group-hr

2 Done
3 show aaa group
4 1) GroupName: group-1
5 2) GroupName: group-finance
6 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 840

NetScaler 12.0

To configure AAA local groups and add users to them by using the configuration utility

1. Navigate to Security > AAA - Application Traffic > Groups

2. In the details pane, do one of the following:

• To create a new group, click Add.

• To modify an existing group, select the group, and then click Edit.

3. If you are creating a new group, in the Create AAA Group dialog box, in the Group Name text
box, type a name for the group.

4. In the Advanced area to the right, click AAA Users.

• To add a user to the group, select the user, and then click Add.
• To remove a user from the group, select the user, and then click Remove.
• To create a new user account and add it to the group, click the Plus icon, and then follow
the instructions in “To configure AAA local users by using the configuration utility.”

5. Click Create or OK. The group that you created appears in the AAA Groups page.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Configuring AAA policies

September 14, 2018

Contributed by:
C

After you set up your users and groups, you next configure authentication policies, authorization poli-
cies, and audit policies to define which users are allowed to access your intranet, which resources
each user or group is allowed to access, and what level of detail AAA will preserve in the audit logs.
An authentication policy defines the type of authentication to apply when a user attempts to log on.
If external authentication is used, the policy also specifies the external authentication server. Autho-
rization policies specify the network resources that users and groups can access after they log on.
Auditing policies define the audit log type and location.

You must bind each policy to put it into effect. You bind authentication policies to authentication
virtual servers, authorization policies to one or more user accounts or groups, and auditing policies
both globally and to one or more user accounts or groups.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 841

NetScaler 12.0

When you bind a policy, you assign a priority to it. The priority determines the order in which the
policies you define are evaluated. You can set the priority to any positive integer. In the NetScaler
appliance operating system, policy priorities work in reverse order: the higher the number, the lower
the priority. For example, if you have three policies with priorities of 10, 100, and 1000, the policy
assigned a priority of 10 is performed first, then the policy assigned a priority of 100, and finally the
policy assigned an order of 1000. The AAA feature implements only the first of each type of policy that
a request matches, not any additional policies of that type that a request might also match, so policy
priority is important for getting the results you intend.

You can leave yourself plenty of room to add other policies in any order, and still set them to evaluate
in the order you want, by setting priorities with intervals of 50 or 100 between each policy when you
bind the policies. You can then add additional policies at any time without having to reassign the
priority of an existing policy.

For additional information about binding policies on the NetScaler appliance, see the Citrix Traffic
Management Guide at Traffic Management.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Authentication policies

September 21, 2018

Contributed by:
C

The NetScaler appliance can authenticate users with local user accounts or by using an external au-
thentication server. The appliance supports the following authentication types:

• LOCAL

Authenticates to the NetScaler appliance by using a password, without reference to an external

authentication server. User data is stored locally on the NetScaler appliance.

• RADIUS

Authenticate to an external Radius server.

• LDAP

Authenticates to an external LDAP authentication server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 842

NetScaler 12.0

• TACACS
Authenticates to an external Terminal Access Controller Access-Control System (TACACS) au-
thentication server.
After a user authenticates to a TACACS server, the NetScaler appliance connects to the same
TACACS server for all subsequent authorizations. When a primary TACACS server is unavailable,
this feature prevents delays while the ADC waits for the first TACACS server to time out before
resending the authorization request to the second TACACS server.
Note

When authenticating through a TACACS server, AAA traffic management logs only success-
fully executed TACACS commands, to prevent the logs from showing TACACS commands
that were entered by users who were not authorized to execute them.

Starting from NetScaler 12.0 Build 57.x, the Terminal Access Controller Access-Control System
(TACACS) is not blocking the AAA daemon while sending the TACACS request. The AAA daemon allows
LDAP, and RADIUS authentication to proceed with the request. The TACACS authentication request
resumes once TACACS server acknowledges the TACACS request.
• CERT
Authenticates to the NetScaler appliance by using a client certificate, without reference to an
external authentication server.
• NEGOTIATE
Authenticates to a Kerberos authentication server. If there is an error in Kerberos authentica-
tion, NetScaler appliance uses NTLM authentication.
• SAML
Authenticates to a server that supports the Security Assertion Markup Language (SAML).
• SAML IDP
Configures the NetScaler appliance to serve as a Security Assertion Markup Language (SAML)
Identity Provider (IdP).
• WEB
Authenticates to a web server, providing the credentials that the web server requires in an HTTP
request and analyzing the web server response to determine that user authentication was suc-
cessful.
An authentication policy is comprised of an expression and an action. Authentication policies use
NetScaler appliance expressions.
After creating an authentication action and an authentication policy, bind it to an authentication vir-
tual server and assign a priority to it. When binding it, also designate it as either a primary or a sec-

© 1999-2018 Citrix Systems, Inc. All rights reserved. 843

NetScaler 12.0

ondary policy. Primary policies are evaluated before secondary policies. In configurations that use
both types of policy, primary policies are normally more specific policies while secondary policies are
normally more general policies intended to handle authentication for any user accounts that do not
meet the more specific criteria.

To add an authentication action by using the command line interface

If you do not use LOCAL authentication, you need to add an explicit authentication action. To do this,
at the command prompt, type the following command:

add authentication tacacsAction <name> -serverip <IP> [-serverPort <port

>][-authTimeout <positive_integer>][ ... ]

Example

1 > add authentication tacacsaction Authn-Act-1 -serverip 10.218.24.65 -

serverport 1812 -authtimeout 15 -tacacsSecret ”
minotaur” -authorization OFF -accounting ON -auditFailedCmds OFF -
defaultAuthenticationGroup ”users”
2 Done

To configure an authentication action by using the command line interface

To configure an existing authentication action, at the command prompt, type the following command:

set authentication tacacsAction <name> -serverip <IP> [-serverPort <port

>][-authTimeout <positive_integer>][ ... ]

Example

1 > set authentication tacacsaction Authn-Act-1 -serverip 10.218.24.65 -

serverport 1812 -authtimeout 15 -tacacsSecret ”
minotaur” -authorization OFF -accounting ON -auditFailedCmds OFF -
defaultAuthenticationGroup ”users”
2 Done

To remove an authentication action by using the command line interface

To remove an existing RADIUS action, at the command prompt, type the following command:

rm authentication radiusAction <name>

Example

© 1999-2018 Citrix Systems, Inc. All rights reserved. 844

NetScaler 12.0

1 > rm authentication tacacsaction Authn-Act-1

2 Done

To configure an authentication server by using the configuration utility

Note

In the configuration utility, the term server is used instead of action, but refers to the same task.

1. Navigate to Security > AAA - Application Traffic > Policies > Authentication.
2. In the details pane, on the Servers tab, do one of the following:
• To create a new authentication server, click Add.
• To modify an existing authentication server, select the server, and then click Open.
3. In the Create Authentication Server or Configure Authentication Server dialog box, type or
select values for the parameters.
• Name*—radiusActionName (Cannot be changed for a previously configured action)
• Authentication Type*—authtype (Set to RADIUS, cannot be changed)
• IP Address*—serverip </IP>
• IPV6*—Select the checkbox if the server IP is an IPv6 IP. (No command line equivalent.)
• Port*—serverPort
• Time-out (seconds)*—authTimeout
4. Click Create or OK, and then click Close. The policy that you created appears in the Authenti-
cation Policies and Servers page.

To create and bind an authentication policy by using the command line interface

At the command prompt, type the following commands in the order shown to create and bind an
authentication policy and verify the configuration:

• add authentication negotiatePolicy <name> <rule> <reqAction>

• “‘show authentication localPolicy
• “‘bind authentication vserver -policy [-priority ][-secondary]]
• show authentication vserver <name>

Example

1 > add authentication localPolicy Authn-Pol-1 ns_true Done

2 > show authentication localPolicy
3 1) Name: Authn-Pol-1 Rule: ns_true Request action
: LOCAL Done
4 > bind authentication vserver Auth-Vserver-2 -policy Authn-Pol-1
5 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 845

NetScaler 12.0

6 > show authentication vserver Auth-Vserver-2 Auth-Vserver-2

(10.102.29.77:443) - SSL Type: CONTENT State: UP Client Idle
Timeout: 180 sec Down state flush: DISABLED Disable
Primary Vserver On Down : DISABLED Authentication : ON
Current AAA Users: 0 Authentication Domain:
myCompany.employee.com
7 1) Primary authentication policy name: Authn-Pol-1 Priority: 0
8 Done

To modify an existing authentication policy by using the command line interface

At the command prompt, type the following commands to modify an existing authentication policy:

set authentication localPolicy <name> <rule> [-reqaction <action>]

Example

1 > set authentication localPolicy Authn-Pol-1 ’ns_true’ Done

To remove an authentication policy by using the command line interface

At the command prompt, type the following command to remove an authentication policy:

rm authentication localPolicy <name>

Example

1 > rm authentication localPolicy Authn-Pol-1

2 Done

To configure and bind authentication policies by using the configuration utility

1. Navigate to Security > AAA - Application Traffic > Policies > Authentication, and then select
the type of policy that you want to create.
2. In the details pane, on the Policies tab, do one of the following:
• To create a new policy, click Add.
• To modify an existing policy, select the action, and then click Edit.
3. In the Create Authentication Policy or Configure Authentication Policy dialog, type or select val-
ues for the parameters.
• Name*—policyname (Cannot be changed for a previously configured action)
• Authentication Type*—authtype

© 1999-2018 Citrix Systems, Inc. All rights reserved. 846

NetScaler 12.0

• Server*—authVsName
• Expression*—rule (You enter expressions by first choosing the type of expression in the left-
most drop-down list beneath the Expression window, and then by typing your expression
directly into the expression text area, or by clicking Add to open the Add Expression dialog
box and using the drop-down lists in it to construct your expression.)
4. Click Create or OK. The policy that you created appears in the Policies page.
5. Click the Servers tab, and in the details pane do one of the following:
• To use an existing server, select it, and then click .
• To create a new server, click Add, and follow the instructions.
6. If you want to designate this policy as a secondary authentication policy, on the Authentication
tab, click Secondary. If you want to designate this policy as a primary authentication policy,
skip this step.
7. Click Insert Policy.
8. Choose the policy you want to bind to the authentication virtual server from the drop-down list.
9. In the Priority column to the left, modify the default priority as needed to ensure that the policy
is evaluated in the proper order.
10. Click OK. A message appears in the status bar, stating that the policy has been configured suc-
cessfully.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

LDAP authentication policies

September 14, 2018

Contributed by:
C

As with other types of authentication policies, a Lightweight Directory Access Protocol (LDAP) authen-
tication policy is comprised of an expression and an action. After creating an authentication policy,
you bind it to an authentication virtual server and assign a priority to it. When binding it, you also
designate it as either a primary or a secondary policy. In addition to standard authentication func-
tions, LDAP can search other active directory (AD) servers for user accounts for users that do not exist
locally. This function is called referral support or referral chasing.

Normally you configure the NetScaler appliance to use the IP address of the authentication server dur-
ing authentication. With LDAP authentication servers, you can also configure the ADC to use the FQDN

© 1999-2018 Citrix Systems, Inc. All rights reserved. 847

NetScaler 12.0

of the LDAP server instead of its IP address to authenticate users. Using an FQDN can simplify an other-
wise much more complex AAA configuration in environments where the authentication server might
be at any of several IP addresses, but always uses a single FQDN. To configure authentication by using
a server’s FQDN instead of its IP address, you follow the normal configuration process except when
creating the authentication action. When creating the action, you use the serverName parameter
instead of the serverIP parameter, and substitute the server’s FQDN for its IP address.
Before you decide whether to configure the ADC to use the IP or the FQDN of your LDAP server to
authenticate users, consider that configuring AAA to authenticate to an FQDN instead of an IP address
adds an extra step to the authentication process. Each time the ADC authenticates a user, it must
resolve the FQDN. If a great many users attempt to authenticate simultaneously, the resulting DNS
lookups might slow the authentication process.
LDAP referral support is disabled by default and cannot be enabled globally. It must be explicitly en-
abled for each LDAP action. You must also make sure that the AD server accepts the same binddn
credentials that are used with the referring (GC) server. To enable referral support, you configure an
LDAP action to follow referrals, and specify the maximum number of referrals to follow.
If referral support is enabled, and the NetScaler appliance receives an LDAP_REFERRAL response to
a request, AAA follows the referral to the active directory (AD) server contained in the referral and
performs the update on that server. First, AAA looks up the referral server in DNS, and connects to
that server. If the referral policy requires SSL/TLS, it connects via SSL/TLS. It then binds to the new
server with the binddn credentials that it used with the previous server, and performs the operation
which generated the referral. This feature is transparent to the user.
Note

These instructions assume that you are already familiar with the LDAP protocol and have already
configured your chosen LDAP authentication server.

For more information about setting up authentication policies in general, see Authentication Poli-
cies. For more information about NetScaler appliance expressions, which are used in the policy rule,
see Policies and Expressions.

To enable LDAP referral support by using the command line interface

At the command prompt, type the following commands:

• set authentication ldapAction <name> -followReferrals ON
• set authentication ldapAction <name> -maxLDAPReferrals <integer>
Example

1 > set authentication ldapAction ldapAction-1 -followReferrals ON

2 > set authentication ldapAction ldapAction-1 -maxLDAPReferrals 2

© 1999-2018 Citrix Systems, Inc. All rights reserved. 848

NetScaler 12.0

To enable LDAP referral support by using the configuration utility

Note

In the configuration utility, the term server is used instead of action, but refers to the same task.

1. Navigate to Security > AAA - Application Traffic > Policies > LDAP.
2. In the details pane, on the Servers tab, select the LDAP server that you want to configure, and
then click Edit.
3. In the Configure Authentication Server dialog, scroll down to the Referrals check box, and
select it.
4. In the Maximum Referral Level text box, type the maximum number of referrals to allow.
5. Click OK, and then click Close.

Key-based authentication support for LDAP users

With key-based authentication, you can now fetch the list of public keys that are stored on the user
object in LDAP server through SSH. The NetScaler appliance during role-based authentication (RBA)
process must extract public SSH keys from the LDAP server. The retrieved public key, which is com-
patible with SSH, must allow you to log in through RBA method.

A new attribute “sshPublicKey” is introduced in the “add authentication ldapAction” and “set authen-
tication ldapAction” commands. By using this attribute, you can obtain the following benefits:

• Can store the retrieved public key, and the LDAP action uses this attribute to retrieve SSH key
information from LDAP server.
• Can extract attribute names of up to 24 KB.

Note

The external authentication server, such as LDAP is used only to retrieve SSH key information. It
is not used for authentication purpose.

Following is an example of the flow of events through SSH:

• SSH daemon sends an AAA_AUTHENTICATE request with password field empty to AAA daemon
port.
• If LDAP is configured to store the SSH public key, AAA responds with “sshPublicKey” attribute
along with other attributes.
• SSH daemon verifies these keys with the client keys.
• SSH daemon passes user name in the request payload, and AAA returns the keys specific to this
user along with generic keys.

To configure the sshPublicKey attribute, at the command prompt type the following commands:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 849

NetScaler 12.0

• With add operation, you can add “sshPublicKey” attribute while configuring ldapAction com-
mand.

add authentication ldapAction <name> { -serverIP <ip_addr|ipv6_addr

|*> | { -serverName <string> } } [-serverPort <port>] … [-Attribute1 <
string>] … [-Attribute16 <string>][-sshPublicKey <string>][-authentication
off]

• With set operation, you can configure “sshPublicKey” attribute to an already added ldapAction
command.

set authentication ldapAction <name> [-sshPublicKey <string>][-authentication

off]

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Negotiate authentication policies

September 14, 2018

Contributed by:
C

As with other types of authentication policies, a Negotiate authentication policy is comprised of an

expression and an action. After creating an authentication policy, you bind it to an authentication
virtual server and assign a priority to it. When binding it, you also designate it as either a primary or a
secondary policy.

In addition to standard authentication functions, the Negotiate Action command can now extract user
information from a keytab file instead of requiring you to enter that information manually. If a keytab
has more than one SPN, AAA selects the correct SPN. You can configure this feature at the command
line, or by using the configuration utility.

Note: These instructions assume that you are already familiar with the LDAP protocol and have already
configured your chosen LDAP authentication server.

To configure AAA to extract user information from a keytab file by using the command
line interface

At the command prompt, type the appropriate command:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 850

NetScaler 12.0

• add authentication negotiateAction <name> [-keytab <string>]

• set authentication negotiateAction <name> [-keytab <string>]

Example

1 > set authentication negotiateAction negotiateAction-1 -keytab keytab-1

To configure AAA to extract user information from a keytab file by using the
configuration utility

Note

In the configuration utility, the term server is used instead of action, but refers to the same task.

1. Navigate to Security > AAA - Application Traffic > Policies > Negotiate.
2. In the details pane, on the Servers tab, do one of the following:
• If you want to create a new Negotiate action, click Add.
• If you want to modify an existing Negotiate action, in the data pane select the action, and
then click Edit.
3. If you are creating a new Negotiate action, in the Name text box, type a name for your new
action. The name can be from one to 127 characters in length and can consist of upper- and low-
ercase letters, numbers, and the hyphen (-) and underscore (_) characters. If you are modifying
an existing Negotiate action, skip this step. The name is read-only; you cannot change it.
4. Under Negotiate, if the Use Keytab file check box is not already checked, check it.
5. In the Keytab file path text box, type the full path and filename of the keytab file that you want
to use.
6. In the Default authentication group text box, type the authentication group that you want to set
as default for this user.
7. Click Create or OK to save your changes.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

RADIUS authentication policies

September 14, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 851

NetScaler 12.0

As with other types of authentication policies, a Remote Authentication Dial In User Service (RADIUS)
authentication policy is comprised of an expression and an action. After creating an authentication
policy, you bind it to an authentication virtual server and assign a priority to it. When binding it, you
also designate it as either a primary or a secondary policy. However, setting up a RADIUS authentica-
tion policy has certain special requirements that are described below.

Normally you configure the NetScaler appliance to use the IP address of the authentication server
during authentication. With RADIUS authentication servers, you can now configure the ADC to use the
FQDN of the RADIUS server instead of its IP address to authenticate users. Using an FQDN can simplify
an otherwise much more complex AAA configuration in environments where the authentication server
might be at any of several IP addresses, but always uses a single FQDN. To configure authentication
by using a server’s FQDN instead of its IP address, you follow the normal configuration process except
when creating the authentication action. When creating the action, you substitute the serverName
parameter for the serverIP parameter.

Before you decide whether to configure the NetScaler appliance to use the IP or the FQDN of your
RADIUS server to authenticate users, consider that configuring AAA to authenticate to an FQDN instead
of an IP address adds an extra step to the authentication process. Each time the ADC authenticates
a user, it must resolve the FQDN. If a great many users attempt to authenticate simultaneously, the
resulting DNS lookups might slow the authentication process.

Note

These instructions assume that you are already familiar with the RADIUS protocol and have al-
ready configured your chosen RADIUS authentication server.

For more information about setting up authentication policies in general, see Authentication Poli-
cies. For more information about NetScaler appliance expressions, which are used in the policy rule,
see Policies and Expressions.

To add an authentication action for a RADIUS server by using the command line
interface

If you authenticate to a RADIUS server, you need to add an explicit authentication action. To do this,
at the command prompt, type the following command:

add authentication radiusAction <name> [-serverip <IP> | -serverName] <

FQDN>][-serverPort <port>] [-authTimeout <positive_integer>] { -radKey }
[-radNASip ( ENABLED | DISABLED )][-radNASid <string>] [-radVendorID <
positive_integer>][-radAttributeType <positive_integer>][-radGroupsPrefix
<string>] [-radGroupSeparator <string>][-passEncoding <passEncoding>][-
ipVendorID <positive_integer>] [-ipAttributeType <positive_integer>][-
accounting ( ON | OFF )][-pwdVendorID <positive_integer> [-pwdAttributeType

© 1999-2018 Citrix Systems, Inc. All rights reserved. 852

NetScaler 12.0

<positive_integer>]] [-defaultAuthenticationGroup <string>] [-callingstationid

( ENABLED | DISABLED )]

The following example adds a RADIUS authentication action named Authn-Act-1, with the server IP
10.218.24.65, the server port 1812, the authentication timeout 15 minutes, the radius key WareTh-
eLorax, NAS IP disabled, and NAS ID NAS1.

1 > add authentication radiusaction Authn-Act-1 -serverip 10.218.24.65 -

serverport 1812 -authtimeout 15 -radkey WareTheLorax -radNASip
DISABLED -radNASid NAS1
2 Done

The following example adds the same RADIUS authentication action, but using the server FQDN
rad01.example.com instead of the IP.

1 > add authentication radiusaction Authn-Act-1 -serverName rad01.example

.com -serverport 1812 -authtimeout 15 -radkey WareTheLorax -radNASip
DISABLED -radNASid NAS1
2 Done

To configure an authentication action for an external RADIUS server by using the

command line

To configure an existing RADIUS action, at the command prompt, type the following command:

set authentication radiusAction <name> [-serverip <IP> | -serverName] <

FQDN>][-serverPort <port>] [-authTimeout <positive_integer>] { -radKey }
[-radNASip ( ENABLED | DISABLED )][-radNASid <string>] [-radVendorID <
positive_integer>][-radAttributeType <positive_integer>][-radGroupsPrefix
<string>] [-radGroupSeparator <string>][-passEncoding <passEncoding>][-
ipVendorID <positive_integer>] [-ipAttributeType <positive_integer>][-
accounting ( ON | OFF )][-pwdVendorID <positive_integer> [-pwdAttributeType
<positive_integer>]] [-defaultAuthenticationGroup <string>] [-callingstationid
( ENABLED | DISABLED )]

To remove an authentication action for an external RADIUS server by using the

command line interface

To remove an existing RADIUS action, at the command prompt, type the following command:

rm authentication radiusAction <name>

Example

© 1999-2018 Citrix Systems, Inc. All rights reserved. 853

NetScaler 12.0

1 > rm authentication radiusaction Authn-Act-1

2 Done

To configure a RADIUS server by using the configuration utility

Note

In the configuration utility, the term server is used instead of action, but refers to the same task.

1. Navigate to Security > AAA - Application Traffic > Policies > Authentication > Radius
2. In the details pane, on the Servers tab, do one of the following:
• To create a new RADIUS server, click Add.
• To modify an existing RADIUS server, select the server, and then click Edit.
3. In the Create Authentication RADIUS Server or Configure Authentication RADIUS Server di-
alog, type or select values for the parameters. To fill out parameters that appear beneath Send
Calling Station ID, expand Details.
• Name*—radiusActionName (Cannot be changed for a previously configured action)
• Authentication Type*—authtype (Set to RADIUS, cannot be changed)
• Server Name / IP Address*—Choose either Server Name or Server IP
– Server Name*—serverName <FQDN>
– IP Address*—serverIp <IP> If the server is assigned an IPv6 IP address, select the IPv6
check box.
• Port*—serverPort
• Time-out (seconds)*—authTimeout
• Secret Key*—radKey (RADIUS shared secret.)
• Confirm Secret Key*—Type the RADIUS shared secret a second time. (No command line
equivalent.)
• Send Calling Station ID—callingstationid
• Group Vendor Identifier—radVendorID
• Group Attribute Type—radAttributeType
• IP Address Vendor Identifier—ipVendorID
• pwdVendorID—pwdVendorID
• Password Encoding—passEncoding
• Default Authentication Group—defaultAuthenticationGroup
• NAS ID—radNASid
• Enable NAS IP address extraction—radNASip
• Group Prefix—radGroupsPrefix
• Group Separator—radGroupSeparator
• IP Address Attribute Type—ipAttributeType
• Password Attribute Type—pwdAttributeType

© 1999-2018 Citrix Systems, Inc. All rights reserved. 854

NetScaler 12.0

• Accounting—accounting
4. Click Create or OK. The policy that you created appears in the Servers page.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

SAML authentication policies

September 14, 2018

Contributed by:
C

For information on NetScaler appliance as a SAML SP and IdP, see SAML Authentication.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Web authentication policies

September 21, 2018

Contributed by:
C

AAA is now able to authenticate a user to a web server, providing the credentials that the web server
requires in an HTTP request and analyzing the web server response to determine that user authenti-
cation was successful. As with other types of authentication policies, a Web authentication policy is
comprised of an expression and an action. After creating an authentication policy, you bind it to an
authentication virtual server and assign a priority to it. When binding it, you also designate it as either
a primary or a secondary policy.

To set up web-based authentication with a specific web server, first you create a web authentication
action. Since authentication to web servers does not use a rigid format, you must specify exactly
which information the web server requires and in which format when creating the action. To do this,
you create an expression in NetScaler appliance default syntax that contains the following items:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 855

NetScaler 12.0

• Server IP—The IP address of the authentication Web server.

• Server Port—The port of the authentication Web server.
• Authentication Rule—An expression in NetScaler appliance default syntax that contains the
user’s credentials in the format that the Web server expects.
• Scheme—HTTP (for unencrypted web authentication) or HTTPS (for encrypted web authenti-
cation).
• Success Rule—An expression in NetScaler appliance default syntax that matches the web server
response string that signifies that the user authenticated successfully.

For all other parameters, follow the normal rules for the add authentication action command.

Next you create a policy associated with that action. The policy is similar to an LDAP policy, and like
LDAP policies uses NetScaler appliance syntax.

Note

These instructions assume that you are already familiar with the authentication requirements
of the web server(s) to which you want to authenticate, and have already configured the web
authentication server.

To configure a Web authentication action by using the command line interface

To create a web authentication action at the command line, at the command line type the following
command:

add authentication webAuthAction <name> -serverIP <ip_addr|ipv6_addr|*>

-serverPort <port|*> [-fullReqExpr <string>] -scheme ( http | https )-
successRule <expression> [-defaultAuthenticationGroup <string>][-Attribute1
<string>][-Attribute2 <string>] [-Attribute3 <string>][-Attribute4 <
string>] [-Attribute5 <string>][-Attribute6 <string>] [-Attribute7 <string
>][-Attribute8 <string>] [-Attribute9 <string>][-Attribute10 <string>]
[-Attribute11 <string>][-Attribute12 <string>] [-Attribute13 <string>][-
Attribute14 <string>] [-Attribute15 <string>][-Attribute16 <string>]

Example

1 > add authentication webAuthAction webauth1 -serverIP 10.214.56.31 -

serverPort 80 -

To configure a Web authentication action by using the configuration utility

© 1999-2018 Citrix Systems, Inc. All rights reserved. 856

NetScaler 12.0

Note

In the configuration utility, the term server is used instead of action, but refers to the same task.

1. Navigate to Security > AAA - Application Traffic > Policies > LDAP.
2. In the details pane, on the Servers tab, do one of the following:
• If you want to create a new web authentication action, click Add.
• If you want to modify an existing web authentication action, in the data pane select the
action, and then click Edit.
3. If you are creating a new web authentication action, in the Create Authentication Web server
dialog box, Name text box, type a name for the new web authentication action. The name can
be from one to 127 characters in length, and can consist of upper- and lowercase letters, num-
bers, and the hyphen (-) and underscore (_) characters. If you are modifying an existing web
authentication action, skip this step. The name is read-only; you cannot change it.
4. In the Web Server IP Address text box, type the IPv4 or IPv6 IP address of the authentication
web server. If the address is an IPv6 IP address, select the IPv6 check box first.
5. In the Port text box, type the port number on which the web server accepts connections.
6. Select HTTP or HTTPS in the Protocol drop-down list.
7. In the HTTP Request Expression text area, type a PCRE-format regular expression that creates
the web server request that contains the user’s credentials in the exact format expected by the
authentication web server.
8. In the Expression to validate the Authentication text area, type a NetScaler appliance default
syntax expression that describes the information in the web server response that indicates that
user authentication was successful.
9. Fill out the remaining fields as described in the general authentication action documentation.
10. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Configuring advanced authentication policies

September 14, 2018

Contributed by:
C

If you know exactly how you want an authentication policy to be configured, you can use the advanced
authentication policy dialog to create the policy quickly.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 857

NetScaler 12.0

To configure an advanced authentication policy by using the configuration utility

1. Navigate to Security > AAA - Application Traffic > Policies > Authentication > Advanced Poli-
cies, and then select Policy.
2. In the details pane do one of the following:
• To create a new policy, click Add.
• To modify an existing policy, select the policy, and then click Edit.
3. In the Create Authentication Policy or Configure Authentication Policy dialog box, type or
select values for the parameters.
• Name*—The policy name. Cannot be changed for a previously configured policy.
• Action Type*—The policy type: Cert, Negotiate, LDAP, RADIUS, SAML, SAMLIDP, TACACS, or
WEBAUTH.
• Action*—The authentication action (profile) to associate with the policy. You can choose
an existing authentication action, or click the plus and create a new action of the proper
type.
• Log Action—The audit action to associate with the policy. You can choose an existing audit
action, or click the plus and create a new action.
• Expression*—The rule that selects connections to which you want to apply the action that
you specified. The rule can be simple (“true” selects all traffic) or complex. You enter ex-
pressions by first choosing the type of expression in the leftmost drop-down list beneath
the Expression window, and then by typing your expression directly into the expression
text area, or by clicking Add to open Add Expression dialog box and using the drop-down
lists in it to construct your expression.)
• Comment—You can type a comment that describes the type of traffic that this authentica-
tion policy will apply to. Optional.
4. Click Create or OK, and then click Close. If you created a policy, that policy appears in the Au-
thentication Policies and Servers page.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Authorizing user access to application resources

November 6, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 858

NetScaler 12.0

You can control the resources that an authenticated user can access within an application.

To do this, associate an authorization policy to each of the users, either individually or by associating
the policy to a group of users. The authorization policy must specify the following:

• Rule. The resource to which access must be authorized. This can be specified by using basic or
advanced expressions.
• Action. Whether access to the resource must be allowed or denied.

By default, access to all resources within an application is DENIED to all users. However, you can
change this default authorization action to ALLOW access to all users (by setting the session parame-
ters in session profile or by setting the global session parameters).

Warning

For optimum security, Citrix recommends that you do not to change the default authorization
action from DENY to ALLOW. Instead, it is advised to create specific authorization policies for
users who need access to specific resources.

To configure authorization by using the CLI

1. Configure the authorization policy.

ns-cli-prompt> add authorization policy <name> <rule> <action>

2. Associate the policy with the appropriate user or group.

• Bind the policy to a specific user.

ns-cli-prompt> bind aaa user <username> -policy <policyname>

• Bind the policy to a specific group.

ns-cli-prompt> bind aaa group <groupName> -policy <policyname>

To configure authorization by using the GUI (Configuration tab)

1. Create the authorization policy.

Navigate to Security > AAA - Application Traffic > Policies > Authorization, click Add and then
define the policy as required.

2. Associate the policy with the appropriate user or group.

Navigate to Security > AAA - Application Traffic > Users or Groups, and edit the relevant user
or group to associate it with the authorization policy.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 859

NetScaler 12.0

Sample authorization configurations

Here are some example configurations to authorize user access to some application resources. Note
that these are CLI commands. You can do similar configurations using the GUI, although you must not
enclose the expression within quotes (“).

• add authorization policy authzpol1 ”HTTP.REQ.URL.SUFFIX.EQ(\”gif\”)”

ALLOW

• bind aaa user user1 -policy authzpol1

• add authorization policy authzpol2 ”HTTP.REQ.URL.SUFFIX.EQ(\”png\”)”

DENY

• bind aaa group group1 -policy authzpol2

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Auditing authenticated sessions

September 14, 2018

Contributed by:
C

You can configure the NetScaler appliance to keep a log of all the events that are triggered in an au-
thenticated session. Using this information, you can audit state and status information, to see the
history for users in chronological order.

To do this, define an audit policy that specifies the following:

• Log type. The logs can be stored remotely (syslog) or locally on the NetScaler appliance (nslog).
• Rule. The conditions on which the logs are stored.
• Action. Details of the log server and other details for creating the log entries.

This audit policy can be configured at different levels: user-level, group-level, AAA virtual server, and
global system level. The policies configured at the user-level have the highest priority.

Note

This topic details steps for using syslog. Make necessary changes to use nslog.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 860

NetScaler 12.0

To configure syslog auditing by using the CLI

1. Configure the audit server with the relevant log settings.

ns-cli-prompt> add audit syslogAction <name> <serverIP> …

2. Configure the audit policy by associating the audit server.

ns-cli-prompt> add audit syslogPolicy <name> <rule> <action>

3. Associate the audit policy with one of the following entities:

• Bind the policy to a specific user.

ns-cli-prompt> bind aaa user <userName>-policy <policyname> …

• Bind the policy to a specific group.

ns-cli-prompt> bind aaa group <groupName>-policy <policyname> …

• Bind the policy to a AAA virtual server.

ns-cli-prompt> bind authentication vserver <name> -policy <policyname> …

• Bind the policy globally to the NetScaler appliance.

ns-cli-prompt> bind tm global -policyName <policyname> …

To configure syslog auditing by using the GUI (Configuration tab)

1. Configure the audit server and policy.

Navigate to Security > AAA - Application Traffic > Policies > Auditing > Syslog, and configure
the server and the policy in the relevant tabs.

2. Associate the policy with one of the following:

• Bind the policy to a specific user.

Navigate to Security > AAA - Application Traffic > Users, and associate the authorization
policy with the relevant user.

• Bind the policy to a specific group.

Navigate to Security > AAA - Application Traffic > Groups, and associate the authorization
policy with the relevant group.

• Bind the policy to a AAA virtual server.

Navigate to Security > AAA - Application Traffic > Virtual Servers, and associate the au-
thorization policy with the relevant virtual server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 861

NetScaler 12.0

• Bind the policy globally to the NetScaler appliance.

Navigate to Security > AAA - Application Traffic > Policies > Auditing > Syslog or Nslog,
select the authorization policy, and click Action > Global Bindings to bind the policy glob-
ally.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Session settings

September 14, 2018

Contributed by:
C

After you configure your AAA profiles, you configure session settings to customize your user sessions.
The session settings are:

• The session timeout.

Controls the period after which the user is automatically disconnected and must authenticate
again to access your intranet.

• The default authorization setting.

Determines whether the

NetScaler appliance will by default allow or deny access to content for which there is no specific
authorization policy.

• The single sign-on setting.

Determines whether the

NetScaler appliance will log users onto all web applications automatically after they authenti-
cate, or will pass users to the web application logon page to authenticate for each application.

• The credential index setting.

Determines whether the

NetScaler appliance will use primary or the secondary authentication credentials for single
signon.

To configure the session settings, you can take one of two approaches. If you want different settings
for different user accounts or groups, you create a profile for each user account or group for which you

© 1999-2018 Citrix Systems, Inc. All rights reserved. 862

NetScaler 12.0

want to configure custom sessions settings. You also create policies to select the connections to which
to apply particular profiles, and you bind the policies to users or groups. You can also bind a policy to
the authentication virtual server that handles the traffic to which you want to apply the profile.

If you want the same settings for all sessions, or if you want to customize the default settings for ses-
sions that do not have specific profiles and policies configured, you can simply configure the global
session settings.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Session profiles

September 21, 2018

Contributed by:
C

To customize your user sessions, you first create a session profile. The session profile allows you to
override global settings for any of the session parameters.

Note

The terms “session profile” and “session action” mean the same thing.

To create a session profile by using the command line interface

At the command prompt, type the following commands to create a session profile and verify the con-
figuration:

• add tm sessionAction <name> [-sessTimeout <mins>] [-defaultAuthorizationAction

( ALLOW | DENY )][-SSO ( ON | OFF )][-ssoCredential ( PRIMARY |
SECONDARY )] [-ssoDomain <string>][-httpOnlyCookie ( YES | NO )] [-
persistentCookie ( ENABLED | DISABLED )] [-persistentCookieValidity <
minutes>]

• show tm sessionAction <name>

Example

1 > add tm sessionAction session-profile -sessTimeout 30 -

defaultAuthorization ALLOW

© 1999-2018 Citrix Systems, Inc. All rights reserved. 863

NetScaler 12.0

2 Done
3 > show tm sessionAction session-profile
4 1) Name: session-profile
5 Authorization action : ALLOW
6 Session timeout: 30 minutes
7 Done

To modify a session profile by using the command line interface

At the command prompt, type the following commands to modify a session profile and verify the con-
figuration:

• set tm sessionAction <name> [-sessTimeout <mins>] [-defaultAuthorizationAction

( ALLOW | DENY )][-SSO ( ON | OFF )][-ssoCredential ( PRIMARY |
SECONDARY )] [-ssoDomain <string>][-httpOnlyCookie ( YES | NO )] [-
persistentCookie ( ENABLED | DISABLED )] [-persistentCookieValidity <
minutes>]

• show tm sessionAction

Example

1 > set tm sessionAction session-profile -sessTimeout 30 -

defaultAuthorization ALLOW
2 Done
3 > show tm sessionAction session-profile
4 1) Name: session-profile
5 Authorization action : ALLOW
6 Session timeout: 30 minutes
7 Done

To remove a session profile by using the command line interface

At the command prompt, type the following command to remove a session profile:

rm tm sessionAction <name>

To configure session profiles by using the configuration utility

1. Navigate to Security > AAA - Application Traffic > Session.

2. Navigate to Security > AAA - Application Traffic > Policies > Session.
3. In the details pane, click the Profiles tab.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 864

NetScaler 12.0

4. On the Profiles tab, do one of the following:

• To create a new session profile, click Add.
• To modify an existing session profile, select the profile, and then click Edit.
5. In the Create TM Session Profile or Configure TM Session Profile dialog, type or select values for
the parameters.
• Name*—actionname (Cannot be changed for a previously configured session action.)
• Session Time-out—sesstimeout
• Single Signon to Web Applications—sso
• Default Authorization Action—defaultAuthorizationAction
• Credential Index—ssocredential
• Single Sign-on Domain—ssoDomain
• HTTPOnly Cookie—httpOnlyCookie
• Enable Persistent Cookie—persistentCookie
• Persistent Cookie Validity—persistentCookieValidity
6. Click Create or OK. The session profile that you created appears in the Session Policies and
Profiles pane.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Session policies

September 21, 2018

Contributed by:
C

After you create one or more session profiles, you create session policies and then bind the policies
globally or to an authentication virtual server to put them into effect.

To create a session policy by using the command line interface

At the command prompt, type the following commands to create a session policy and verify the con-
figuration:

1 - add tm sessionPolicy <name> <rule> <action>

2 - show tm sessionPolicy <name>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 865

NetScaler 12.0

Example

1 > add tm sessionPolicy session-pol ”URL == /*.gif” session-profile

2 Done
3 > show tm sessionPolicy session-pol
4 1) Name: session-pol Rule: URL == ’/*.gif’
5 Action: session-profile
6 Done

To modify a session policy by using the command line interface

At the command prompt, type the following commands to modify a session policy and verify the con-
figuration:

1 - set tm sessionPolicy <name> [-rule <expression>] [-action <action>]

2 - show tm sessionPolicy <name>

Example

1 > set tm sessionPolicy session-pol ”URL == /*.gif” session-profile

2 Done
3 > show tm sessionPolicy session-pol
4 1) Name: session-pol Rule: URL == ’/*.gif’
5 Action: session-profile
6 Done

To globally bind a session policy by using the command line interface

At the command prompt, type the following commands to globally bind a session policy and verify
the configuration:
bind tm global -policyName <policyname> [-priority <priority>]

Example

1 > bind tm global -policyName session-pol

2 Done
3
4 > show tm sessionPolicy session-pol
5 1) Name: session-pol Rule: URL == ’/*.gif’
6 Action: session-profile
7 Policy is bound to following entities
8 1) TM GLOBAL PRIORITY : 0
9 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 866

NetScaler 12.0

To bind a session policy to an authentication virtual server by using the command line
interface

At the command prompt, type the following command to bind a session policy to an authentication
virtual and verify the configuration:
bind authentication vserver <name> -policy <policyname> [-priority <priority
>]

Example

1 > bind authentication vserver auth-vserver-1 -policyName Session-Pol-1

-priority 1000
2 Done

To unbind a session policy from an authentication virtual server by using the

command line interface

At the command prompt, type the following commands to unbind a session policy from an authenti-
cation virtual server and verify the configuration:
unbind authentication vserver <name> -policy <policyname>

Example

1 > unbind authentication vserver auth-vserver-1 -policyName Session-Pol

-1
2 Done

To unbind a globally bound session policy by using the command line interface

At the command prompt, type the following commands to unbind a globally-bound session policy:
unbind tm global -policyName <policyname>

Example

1 > unbind tm global -policyName Session-Pol-1

2 Done

To remove a session policy by using the command line interface

First unbind the session policy from global, and then, at the command prompt, type the following
commands to remove a session policy and verify the configuration:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 867

NetScaler 12.0

rm tm sessionPolicy <name>

Example

1 > rm tm sessionPolicy Session-Pol-1

2 Done

To configure and bind session policies by using the configuration utility

1. Navigate to Security > AAA - Application Traffic > Session.

2. Navigate to Security > AAA - Application Traffic > Policies > Session.
3. In the details pane, on the Policies tab, do one of the following:
• To create a new session policy, click Add.
• To modify an existing session policy, select the policy, and then click Edit.
4. In the Create Session Policy or Configure Session Policy dialog, type or select values for the
parameters.
• Name*—policyname (Cannot be changed for a previously configured session policy.)
• Request Profile*—actionname
• Expression*—rule (You enter expressions by first choosing the type of expression in the
leftmost drop-down list beneath the Expression text area and then typing your expression
directly into the expression text area, or by clicking Add to open the Add Expression dialog
box and using the drop-down lists in it to construct your expression.)
5. Click Create or OK. The policy that you created appears in the details pane of the Session Poli-
cies and Profiles page.
6. To globally bind a session policy, in the details pane, select Global Bindings from the Action
drop-down list, and fill in the dialog.
• Select the name of the session policy you want to globally bind.
• Click OK.
7. To bind a session policy to an authentication virtual server, in the navigation pane, click Virtual
Servers, and add that policy to the policies list.
• In the details pane, select the virtual server, and then click Edit.
• In the Advanced Selections to the right of the detail area, click Policies.
• Select a policy, or click the plus icon to add a policy.
• In the Priority column to the left, modify the default priority as needed to ensure that the
policy is evaluated in the proper order.
• Click OK.
A message appears in the status bar, stating that the policy has been configured success-
fully.

1.
2. Citrix ADC

© 1999-2018 Citrix Systems, Inc. All rights reserved. 868

NetScaler 12.0

3. NetScaler 12.0
4. AAA application traffic

Global session settings

September 21, 2018

Contributed by:
C

In addition to or instead of creating session profiles and policies, you can configure global session
settings. These settings control the session configuration when there is no explicit policy overriding
them.

To configure the session settings by using the command line interface

At the command prompt, type the following commands to configure the global session settings and
verify the configuration:

set tm sessionParameter [-sessTimeout <mins>][-defaultAuthorizationAction

( ALLOW | DENY )][-SSO ( ON | OFF )][-ssoCredential ( PRIMARY | SECONDARY
)][-ssoDomain <string>][-httpOnlyCookie ( YES | NO )][-persistentCookie (
ENABLED | DISABLED )] [-persistentCookieValidity <minutes>]

Example

1 > set tm sessionParameter -sessTimeout 30

2 Done
3 > set tm sessionParameter -defaultAuthorizationAction DENY
4 Done
5 > set tm sessionParameter -SSO ON
6 Done
7 > set tm sessionParameter -ssoCredential PRIMARY
8 Done

To configure the session settings by using the configuration utility

1. Navigate to Security > AAA - Application Traffic

2. In the details pane, under Settings, click Change global settings.
3. In the Global Session Settings dialog, type or select values for the parameters.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 869

NetScaler 12.0

• Session Time-out—sessTimeout
• Default Authorization Action—defaultAuthorizationAction
• Single Sign-on to Web Applications—sso
• Credential Index—ssoCredential
• Single Sign-on Domain—ssoDomain
• HTTPOnly Cookie—httpOnlyCookie
• Enable Persistent Cookie—persistentCookie
• Persistent Cookie Validity (minutes)—persistentCookieValidity
• Home Page—homepage
4. Click OK.
1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Traffic Settings

September 14, 2018

Contributed by:
C
If you use forms-based or SAML single sign-on (SSO) for your protected applications, you configure
that feature in the Traffic settings. SSO enables your users to log on once to access all protected ap-
plications, rather than requiring them to log on separately to access each one.
Forms-based SSO allows you to use a web form of your own design as the sign-on method instead of
a generic pop-up window. You can therefore put you company logo and other information you might
want your users to see on the logon form. SAML SSO allows you to configure one NetScaler appliance
or virtual appliance instance to authenticate to another NetScaler appliance on behalf of users who
have authenticated with the first appliance.
To configure either type of SSO, you first create a forms or SAML SSO profile. Next, you create a traffic
profile and link it to the SSO profile you created. Next, you create a policy, link it to the traffic profile.
Finally, you bind the policy globally or to an authentication virtual server to put your configuration
into effect.
1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

© 1999-2018 Citrix Systems, Inc. All rights reserved. 870

NetScaler 12.0

Traffic profiles

September 21, 2018

Contributed by:
C

After creating at least one forms or SAML sso profile, you must next create a traffic profile.

Note

In this feature, the terms “profile” and “action” mean the same thing.

To create a traffic profile by using the command line interface

At the command prompt, type:

add tm trafficAction <name> [-appTimeout <mins>][-SSO ( ON | OFF )[-formSSOAction

<string>]][-persistentCookie ( ENABLED | DISABLED )][-InitiateLogout ( ON
| OFF )]

Example

1 add tm trafficAction Traffic-Prof-1 ‒ appTimeout 10 -SSO ON -

formSSOAction SSO-Prof-1

To modify a session profile by using the command line interface

At the command prompt, type:

set tm trafficAction <name> [-appTimeout <mins>] [-SSO ( ON | OFF )[-

formSSOAction <string>]] [-persistentCookie ( ENABLED | DISABLED )] [-
InitiateLogout ( ON | OFF )]

Example

1 set tm trafficAction Traffic-Prof-1 ‒ appTimeout 10 -SSO ON -

formSSOAction SSO-Prof-1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 871

NetScaler 12.0

To remove a session profile by using the command line interface

At the command prompt, type:

rm tm trafficAction <name>

Example

1 rm tm trafficAction Traffic-Prof-1

To configure traffic profiles by using the configuration utility

1. Navigate to Security > AAA - Application Traffic > Traffic.

2. Navigate to Security > AAA - Application Traffic > Policies > Traffic.
3. In the details pane, click the Profiles tab.
4. On the Profiles tab, do one of the following:
• To create a new traffic profile, click Add.
• To modify an existing traffic profile, select the profile, and then click Edit.
5. In the Create Traffic Profile or Configure Traffic Profile dialog box, specify values for the pa-
rameters.
• Name*—name (Cannot be changed for a previously configured session action.)
• AppTimeout—appTimeout
• Single Sign-On—SSO
• Form SSO Action—formSSOAction
• SAML SSO Action—samlSSOAction
• Enable Persistent Cookie—persistentCookie
• Initiate Logout—InitiateLogout
6. Click Create or OK. The traffic profile that you created appears in the Traffic Policies, Profiles,
and either the Form SSO Profiles or SAML SSO Profiles pane, as appropriate.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Traffic policies

September 21, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 872

NetScaler 12.0

Contributed by:
C

After you create one or more form SSO and traffic profiles, you create traffic policies and then bind the
policies, either globally or to a traffic management virtual server, to put them into effect.

To create a traffic policy by using the command line interface

At the command prompt, type:

add tm trafficPolicy <name> <rule> <action>

Example

1 add tm trafficPolicy Traffic-Pol-1 ”HTTP.REQ.HEADER(”Cookie”).CONTAINS(

”login=true”)” Traffic-Prof-1

To modify a traffic policy by using the command line interface

At the command prompt, type:

set tm trafficPolicy <name> <rule> <action>

Example

1 set tm trafficPolicy Traffic-Pol-1 ”HTTP.REQ.HEADER(”Cookie”).CONTAINS(

”login=true”)” Traffic-Prof-1

To globally bind a traffic policy by using the command line interface

At the command prompt, type:

bind tm global -policyName <string> [-priority <priority>]

Example

bind tm global -policyName Traffic-Pol-1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 873

NetScaler 12.0

To bind a traffic policy to a load balancing or content switching virtual server by using
the command line interface

At the command prompt, type one of the following commands:

• bind lb vserver <name> -policy <policyName> [-priority <priority>]

• bind cs vserver <name> -policy <policyName> [-priority <priority>]

Example

1 bind authentication vserver auth-vserver-1 -policyName Traffic-Pol-1 -

priority 1000

To unbind a globally bound traffic policy by using the command line interface

At the command prompt, type:

unbind tm global -policyName <policyname>

Example

1 unbind tm global -policyName Traffic-Pol-1

To unbind a traffic policy from a load balancing or content switching virtual server by
using the command line interface

At the command prompt, type one of the following commands:

• unbind lb vserver <name> -policy <policyname>

• unbind cs vserver <name> -policy <policyname>

Example

1 unbind authentication vserver auth-vserver-1 -policyName Traffic-Pol-1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 874

NetScaler 12.0

To remove a traffic policy by using the command line interface

First unbind the session policy from global, and then, at the command prompt, type:

rm tm trafficPolicy <name>

Example

1 rm tm trafficPolicy Traffic-Pol-1

To configure and bind traffic policies by using the configuration utility

1. Navigate to Security > AAA - Application Traffic > Traffic.

2. Navigate to Security > AAA - Application Traffic > Policies > Traffic.
3. In the details pane, do one of the following:
• To create a new session policy, click Add.
• To modify an existing session policy, select the policy, and then click Edit.
4. In the Create Traffic Policy or Configure Traffic Policy dialog, specify values for the parame-
ters.
• Name*—policyName (Cannot be changed for a previously configured session policy.)
• Profile*—actionName
• Expression—rule (You enter expressions by first choosing the type of expression in the left-
most drop-down list beneath the Expression text area and then typing your expression
directly into the expression text area, or by clicking Add to open the Add Expression dialog
box and using the drop-down lists in it to construct your expression.)
5. Click Create or OK. The policy that you created appears in the details pane of the Session Poli-
cies and Profiles page.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Form SSO profiles

September 21, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 875

NetScaler 12.0

To enable and configure forms-based SSO, you first create an SSO profile.

Note

• Forms-based single sign-on does not work if the form is customized to include Javascript.
• In this feature, the terms “profile” and “action” mean the same thing.

To create a form SSO profile by using the command line interface

At the command prompt, type:

• add tm formSSOAction <name> -actionURL <URL> -userField <string> -

passwdField <string> -ssoSuccessRule <expression> [-nameValuePair <
string>] [-responsesize <positive_integer>][-nvtype ( STATIC | DYNAMIC
)][-submitMethod ( GET | POST )]
• show tm formSSOAction [<name>]

Example

1 add tm formSSOAction SSO-Prof-1 -actionURL ”/logon.php”

2 -userField ”loginID” -passwdField ”passwd”
3 -nameValuePair ”loginID passwd” -responsesize ”9096”
4 -ssoSuccessRule ”HTTP.RES.HEADER(”Set-Cookie”).CONTAINS(”LogonID”)”
5 -nvtype STATIC -submitMethod GET
6 ‒ sessTimeout 10 -defaultAuthorizationAction ALLOW

To modify a form SSO by using the command line interface

At the command prompt, type:

set tm formSSOAction <name> -actionURL <URL> -userField <string> -passwdField

<string> -ssoSuccessRule <expression> [-nameValuePair <string>] [-responsesize
<positive_integer>][-nvtype ( STATIC | DYNAMIC )][-submitMethod ( GET |
POST )]

Example

1 set tm formSSOAction SSO-Prof-1 -actionURL ”/logon.php”

2 -userField ”loginID” -passwdField ”passwd”
3 -ssoSuccessRule ”HTTP.RES.HEADER(”Set-Cookie”).CONTAINS(”LogonID”)”
4 -nameValuePair ”loginID passwd” -responsesize ”9096”

© 1999-2018 Citrix Systems, Inc. All rights reserved. 876

NetScaler 12.0

5 -nvtype STATIC -submitMethod GET

6 ‒ sessTimeout 10 -defaultAuthorizationAction ALLOW

To remove a form SSO profile by using the command line interface

At the command prompt, type:

rm tm formSSOAction <name>

Example

1 rm tm sessionAction SSO-Prof-1

To configure form SSO profiles by using the configuration utility

1. Navigate to Security > AAA - Application Traffic > Policies > Traffic.
2. In the details pane, click the Form SSO Profiles tab.
3. On the Form SSO Profiles tab, do one of the following:
• To create a new form SSO profile, click Add.
• To modify an existing form SSO profile, select the profile, and then click Edit.
4. In the Create Form SSO Profile or Configure Form SSO Profile dialog, specify values for the
parameters:
• Name*—name (Cannot be changed for a previously configured session action.)
• Action URL*—actionURL
• User Name Field*—userField
• Password Field*—passField
• Expression*—ssoSuccessRule
• Name Value Pair—nameValuePair
• Response Size—responsesize
• Extraction—nvtype
• Submit Method—submitMethod
5. Click Create or OK, and then click Close. The form SSO profile that you created appears in the
Traffic Policies, Profiles, and Form SSO Profiles pane.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

© 1999-2018 Citrix Systems, Inc. All rights reserved. 877

NetScaler 12.0

SAML SSO profiles

September 21, 2018

Contributed by:
C

To enable and configure SAML-based SSO, you first create a SAML SSO profile.

To create a SAML SSO profile by using the command line interface

At the command prompt, type:

add tm samlSSOProfile <name> -samlSigningCertName <string> -assertionConsumerServiceUR

<URL> -relaystateRule <expression> -sendPassword (ON | OFF)[-samlIssuerName
<string>]

Example

1 add tm samlSSOProfile saml-SSO-Prof-1 -samlSigningCertName ”Example,

Inc.” -assertionConsumerServiceURL ”https://service.example.com” -
relaystateRule ”true” -sendPassword ”ON” -samlIssuerName ”Example,
Inc.”

To modify a SAML SSO by using the command line interface

At the command prompt, type:

set tm samlSSOProfile <name> -samlSigningCertName <string> -assertionConsumerServiceUR

<URL> -relaystateRule <expression> -sendPassword (ON | OFF)[-samlIssuerName
<string>]

Example

1 set tm samlSSOProfile saml-SSO-Prof-1 -samlSigningCertName ”Example,

Inc.” -assertionConsumerServiceURL ”https://service.example.com” -
relaystateRule ”true” -sendPassword ”ON” -samlIssuerName ”Example,
Inc.”

© 1999-2018 Citrix Systems, Inc. All rights reserved. 878

NetScaler 12.0

To remove a SAML SSO profile by using the command line interface

At the command prompt, type:

rm tm samlSSOProfile <name>

Example

1 rm tm sessionAction saml-SSO-Prof-1

To configure a SAML SSO profile by using the configuration utility

1. Navigate to Security > AAA - Application Traffic > Policies > Traffic.
2. In the details pane, click the SAML SSO Profiles tab.
3. On the SAML SSO Profiles tab, do one of the following:
• To create a new SAML SSO profile, click Add.
• To modify an existing SAML SSO profile, select the profile, and then click OpenEdit.
4. In the Create SAML SSO Profiles or the Configure SAML SSO Profiles dialog box, set the fol-
lowing parameters:
• Name*
• Signing Certificate Name*
• ACS URL*
• Relay State Rule*
• Send Password
• Issuer Name
5. Click Create or OK, and then click Close. The SAML SSO profile that you created appears in the
Traffic Policies, Profiles, and SAML SSO Profiles pane.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Session timeout for OWA 2010

September 21, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 879

NetScaler 12.0

You can now force OWA 2010 connections to time out after a specified period of inactivity. OWA sends
repeated keepalive requests to the server to prevent timeouts. Keeping the connections open can
interfere with single sign-on.

To force OWA 2010 to timeout after a specified period by using the command line
interface

At the command prompt, type the following commands:

• add tm trafficAction <actname> [-forcedTimeout <forcedTimeout> -forcedTimeoutVal

<mins>]

For <actname>, substitute a name for your traffic policy. For <mins>, substitute the number
of minutes after which to initiate a forced timeout. For <forcedTimeout>, substitute one of the
following values:

– START—Starts the timer for forced timeout if a timer has not already been started. If a
running timer exists, has no effect.
– STOP—Stops a running timer. If no running timer is found, has no effect.
– RESET—Restarts a running timer. If no running timer is found, starts a timer just as if the
START option had been used.

• add tm trafficPolicy <polname> <rule> <actname>

For <polname>, substitute a name for your traffic policy. For <rule>, substitute a rule in
NetScaler appliance default syntax.

• bind lb vserver <vservername> ‒policyName <name> -priority <number>

For <vservername>, substitute the name of the AAA traffic management virtual server. For
<priority>, substitute an integer that designates the policy’s priority.

Example

1 add tm trafficAction act-owa2010timeout -forcedTimeout RESET -

forcedTimeoutVal 10
2 add tm trafficPolicy pol-owa2010timeout true act-owa2010timeout
3 bind lb vserver vs-owa2010 -policyName pol-owa2010timeout -priority 10

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

© 1999-2018 Citrix Systems, Inc. All rights reserved. 880

NetScaler 12.0

Authenticating with client certificates

September 14, 2018

Contributed by:
C

Web sites that contain sensitive content, such as online banking websites or websites with employee
personal information, sometimes require client certificates for authentication. To configure AAA to
authenticate users on the basis of client-side certificate attributes, you first enable client authentica-
tion on the traffic management virtual server and bind the root certificate to the authentication virtual
server. Then, you implement one of two options. You can configure the default authentication type
on the authentication virtual server as CERT, or you can create a certificate action that defines what
the NetScaler appliance must do to authenticate users on the basis of a client certificate. In either
case, your authentication server must support CRLs. You configure the ADC to extract the user name
from the SubjectCN field or another specified field in the client certificate.

When the user tries to log on to an authentication virtual server for which an authentication policy is
not configured, and a global cascade is not configured, the user name information is extracted from
the specified field of the certificate. If the required field is extracted, the authentication succeeds. If
the user does not provide a valid certificate during the SSL handshake, or if the user name extraction
fails, authentication fails. After it validates the client certificate, the ADC presents a logon page to the
user.

The following procedures assume that you have already created a functioning AAA configuration, and
therefore they explain only how to enable authentication by using client certificates. These proce-
dures also assume that you have obtained your root certificate and client certificates and have placed
them on the ADC in the /nsconfig/ssl directory.

To configure the AAA client certificate parameters by using the command line interface

At the command prompt, type the following commands, in the order shown, to configure the certifi-
cate and verify the configuration:

• add ssl certKey <certkeyName> -cert <certFile> -key <keyFile> -password

-inform <inform> -expiryMonitor <expiryMonitor> -notificationPeriod <
notificationPeriod>

• bind ssl certKey <certkeyName> -vServer <certkeyName> -CA -crlCheck

Mandatory

• show ssl certKey [<certkeyName>]

© 1999-2018 Citrix Systems, Inc. All rights reserved. 881

NetScaler 12.0

• set aaa parameter -defaultAuthType CERT

• show aaa parameter

• set aaa certParams -userNameField ”Subject:CN”

• show aaa certParams

To configure the AAA client certificate parameters by using the configuration utility

1. Navigate to Security > AAA - Application Traffic > Virtual Servers.

2. In the details pane, select the virtual server that you want to configure to handle client certificate
authentication, and then click Edit.
3. On the Configuration page, under Certificates, click the right arrow (>) to open the CA Cert Key
installation dialog.
4. In the CA Cert Key dialog box, click Insert.
5. In the CA Cert Key - SSL Certificates dialog box, click Install.
6. In the Install Certificate dialog box, set the following parameters, whose names correspond to
the CLI parameter names as shown:
• Certificate-Key Pair Name*—certkeyName
• Certificate File Name—certFile
• Key File Name—keyFile
• Certificate Format—inform
• Password—password
• Certificate Bundle—bundle
• Notify When Expires—expiryMonitor
• Notification Period—notificationPeriod
7. Click Install, and then click Close.
8. In the CA Cert Key dialog box, in the Certificate list, select the root certificate.
9. Click Save.
10. Click Back to return to the main configuration screen.
11. Navigate to Security > AAA - Application Traffic > Policies > Authentication > CERT.
12. In the details pane, select the policy you want to configure to handle client certificate authenti-
cation, and then click Edit.
13. In the Configure Authentication CERT Policy dialog, Server drop-down list, select the virtual
server you just configured to handle client certificate authentication.
14. Click OK. A message appears in the status bar, stating that the configuration completed success-
fully.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 882

NetScaler 12.0

Support to notify number of unsuccessful login attempts

The NetScaler appliance can now log the number of unsuccessful login attempts made from the last
successful log on. The feature works only if the persistentLoginAttempts option is enabled on the
appliance. By default, the option is disabled on the NetScaler appliance.
A NetScaler administrator can use this information to verify if any unauthorized attempts have oc-
curred on a secured external user account.
To use this feature, at the NetScaler appliance command prompt, type:
set aaa parameter [‒maxloginAttempts <value> [-failedLoginTimeout <value>]]
-persistentLoginAttempts (ENABLED | DISABLED)

Example:
set aaa parameter ‒maxLoginAttempts 4 ‒failedLoginTimeout 3 ‒persistentLoginAttempts

ENABLED

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Client certificate pass-through

September 21, 2018

Contributed by:
C
The NetScaler appliance can now be configured to pass client certificates through to protected appli-
cations that require client certificates for user authentication. The ADC first authenticates the user,
then inserts the client certificate into the request and sends it to the application. This feature is con-
figured by adding appropriate SSL policies.
The exact behavior of this feature when a user presents a client certificate depends upon the configu-
ration of the VPN virtual server.
• If the VPN virtual server is configured to accept client certificates but not require them, the ADC
inserts the certificate into the request and then forwards the request to the protected applica-
tion.
• If the VPN virtual server has client certificate authentication disabled, the ADC renegotiatiates
the authentication protocol and reauthenticates the user before it inserts the client certificate
in the header and forwards the request to the protected application.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 883

NetScaler 12.0

• If the VPN virtual server is configured to require client certificate authentication, the ADC uses
the client certificate to authenticate the user, then inserts the certificate in the header and for-
wards the request to the protected application.

In all of these cases, you configure client certificate pass-through as follows.

To create and configure client certificate pass-through by using the command line
interface

At the command prompt, type the following commands:

• add vpn vserver <name> SSL <IP> 443

For name, substitute a name for the virtual server. The name must contain from one to 127 ASCII
characters, beginning with a letter or underscore (_), and containing only letters, numbers, and
the underscore, hash (#), period (.), space, colon (:), at (@), equals (=), and hyphen (-) characters.
For <IP>, substitute the IP address assigned to the virtual server.“‘

• set ssl vserver <name> -clientAuth ENABLED -clientCert <clientcert>

For <name>, substitute the name of the virtual server that you just created. For <clientCert>,
substitute one of the following values:

– disabled—disables client certificate authentication on the VPN virtual server.

– mandatory—configures the VPN virtual server to require client certificates to authenticate.
– optional—configures the VPN virtual server to allow client certificate authentication, but
not to require it.

• bind vpn vserver \<name\> -policy local

For <name>, substitute the name of the VPN virtual server that you created.

• bind vpn vserver \<name> -policy cert

For <name>, substitute the name of the VPN virtual server that you created.

• bind ssl vserver \<name> -certkeyName \<certkeyname>

For <name>, substitute the name of the virtual server that you created. For <certkeyName>,
substitute the client certificate key.

• bind ssl vserver \<name> -certkeyName \<cacertkeyname> -CA -ocspCheck

Optional
For <name>, substitute the name of the virtual server that you created. For <cacertkeyName>,
substitute the CA certificate key.

• add ssl action \<actname\> -clientCert ENABLED -certHeader CLIENT-CERT

For <actname>, substitute a name for the SSL action.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 884

NetScaler 12.0

• add ssl policy \<polname\> -rule true -action \<actname\>

For <polname>, substitute a name for your new SSL policy. For <actname>, substitute the name
of the SSL action that you just created.

• bind ssl vserver \<name\> -policyName \<polname\> -priority 10

For <name>, substitute the name of the VPN virtual server.

Example

1 add vpn vserver vs-certpassthru SSL 10.121.250.75 443

2 set ssl vserver vs-certpassthru -clientAuth ENABLED -clientCert
optional
3 bind vpn vserver vs-certpassthru -policy local
4 bind vpn vserver vs-certpassthru -policy cert
5 bind ssl vserver vs-certpassthru -certkeyName mycertKey
6 bind ssl vserver vs-certpassthru -certkeyName mycertKey -CA -ocspCheck
Optional
7 add ssl action act-certpassthru -clientCert ENABLED -certHeader CLIENT-
CERT
8 add ssl policy pol-certpassthru -rule true -action act-certpassthru
9 bind ssl vserver vs-certpassthru -policyName pol-certpassthru -priority
10

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Configuring AAA with commonly used protocols

September 14, 2018

Contributed by:
C

Configuring the NetScaler appliance for AAA needs a specific setup on the NetScaler appliance and
clients’ browsers. The configuration varies with the protocol used for AAA.

For more information about configuring the NetScaler appliance for Kerberos authentication, see Han-
dling Authentication, Authorization and Auditing with Kerberos/NTLM.

1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 885

NetScaler 12.0

2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Handling authentication, authorization and auditing with

Kerberos/NTLM

January 6, 2019

Contributed by:
C

Kerberos, a computer network authentication protocol, provides secure communication over the In-
ternet. Designed primarily for client-server applications, it provides for mutual authentication by
which the client and server can each ensure the other’s authenticity. Kerberos uses a trusted third
party, referred to as Key Distribution Center (KDC). A KDC consists of an Authentication Server (AS),
which authenticates a user, and a Ticket Granting Server (TGS).

Each entity on the network (client or server) has a secret key that is known only to itself and the KDC.
The knowledge of this key implies authenticity of the entity. For communication between two entities
on the network, the KDC generates a session key, referred to as the Kerberos ticket or service ticket.
The client makes a request to the AS for credentials for a specific server. The client then receives a
ticket, referred to as Ticket Granting Ticket (TGT). The client then contacts the TGS, using the TGT it
received from the AS to prove its identity, and asks for a service. If the client is eligible for the service,
the TGS issues a Kerberos ticket to the client. The client then contacts the server hosting the service
(referred to as the service server), using the Kerberos ticket to prove that it is authorized to receive
the service. The Kerberos ticket has a configurable lifetime. The client authenticates itself with the AS
only once. If it contacts the physical server multiple times, it reuses the AS ticket.

The following figure shows the basic functioning of the Kerberos protocol.

Figure 1. Functioning of Kerberos

Kerberos authentication has the following advantages:

• Faster authentication. When a physical server gets a Kerberos ticket from a client, the server
has enough information to authenticate the client directly. It does not have to contact a domain
controller for client authentication, and therefore the authentication process is faster.
• Mutual authentication. When the KDC issues a Kerberos ticket to a client and the client uses
the ticket to access a service, only authenticated servers can decrypt the Kerberos ticket. If
the virtual server on the NetScaler appliance is able to decrypt the Kerberos ticket, you can

© 1999-2018 Citrix Systems, Inc. All rights reserved. 886

NetScaler 12.0

conclude that both the virtual server and client are authenticated. Thus, the authentication of
the server happens along with the authentication of the client.
• Single sign-on between Windows and other operating systems that support Kerberos.

Kerberos authentication may have the following disadvantages:

• Kerberos has strict time requirements; the clocks of the involved hosts must be synchronized
with the Kerberos server clock to ensure that the authentication does not fail. You can miti-
gate this disadvantage by using the Network Time Protocol daemons to keep the host clocks
synchronized. Kerberos tickets have an availability period, which you can configure.
• Kerberos needs the central server to be available continuously. When the Kerberos server is
down, no one can log on. You can mitigate this risk by using multiple Kerberos servers and
fallback authentication mechanisms.
• Because all the authentication is controlled by a centralized KDC, any compromise in this infras-
tructure, such as the user’s password for a local workstation being stolen, can allow an attacker
to impersonate any user. You can mitigate this risk to some extent by using only a desktop ma-
chine or laptop that you trust, or by enforcing preauthentication by means of a hardware-token.

To use Kerberos authentication, you must configure it on the NetScaler appliance and on each client.

Optimizing Kerberos authentication on AAA

The NetScaler appliance now optimizes and improves the system performance while Kerberos authen-
tication. The AAA daemon remembers the outstanding Kerberos request for the same user to avoid
load on Key Distribution Center (KDC), which will avoid duplicate requests.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

How NetScaler appliance implements Kerberos for client authentication

January 28, 2019

Contributed by:
C
Important

© 1999-2018 Citrix Systems, Inc. All rights reserved. 887

NetScaler 12.0

Kerberos/NTLM authentication is supported only in the NetScaler 9.3 nCore release or later, and
it can be used only for AAA traffic management virtual servers.

NetScaler appliance handles the components involved in Kerberos authentication in the following
way:

Key Distribution Center (KDC)

In the Windows 2000 Server or later versions, the Domain Controller and KDC are part of the Windows
Server. If the Windows Server is UP and running, it indicates that the Domain Controller and KDC are
configured. The KDC is also the Active Directory server.

Note

All Kerberos interactions are validated with the Windows Kerberos Domain Controller.

Authentication service and protocol negotiation

A NetScaler appliance supports Kerberos authentication on the AAA traffic management authentica-
tion virtual servers. If the Kerberos authentication fails, the NetScaler appliance uses the NTLM au-
thentication.

By default, Windows 2000 Server and later Windows Server versions use Kerberos for AAA. If you cre-
ate an authentication policy with NEGOTIATE as the authentication type, the NetScaler appliance at-
tempts to use the Kerberos protocol for AAA and if the client’s browser fails to receive a Kerberos ticket,
the NetScaler appliance uses the NTLM authentication. This process is referred to as negotiation.

The client may fail to receive a Kerberos ticket in any of the following cases:

• Kerberos is not supported on the client.

• Kerberos is not enabled on the client.
• The client is in a domain other than that of the KDC.
• The Access Directory on the KDC is not accessible to the client.

For Kerberos/NTLM authentication, the NetScaler appliance does not use the data that is present lo-
cally on the NetScaler appliance.

Authorization

The traffic management virtual server can be a load balancing virtual server or a content switching
virtual server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 888

NetScaler 12.0

Auditing

The NetScaler appliance supports auditing of Kerberos authentication with the following audit log-
ging:

• Complete audit trail of the traffic management end-user activity

• SYSLOG and high performance TCP logging
• Complete audit trail of system administrators
• All system events
• Scriptable log format

Supported Environment

Kerberos authentication does not need any specific environment on the NetScaler appliance. The
client (browser) must provide support for Kerberos authentication.

High Availability

In a high availability setup, only the active NetScaler appliance joins the domain. In case of a failover,
the NetScaler appliance lwagent daemon joins the secondary NetScaler appliance to the domain. No
specific configuration is required for this functionality.

Kerberos authentication process

The following figure shows a typical process for Kerberos authentication in the NetScaler appliance
environment.

Figure 1. Kerberos Authentication Process on NetScaler appliance

The Kerberos authentication occurs in the following stages:

Client authenticates itself to the KDC

1. The NetScaler appliance receives a request from a client.

2. The traffic management (load balancing or content switching) virtual server on the NetScaler
appliance sends a challenge to the client.
3. To respond to the challenge, the client gets a Kerberos ticket.
• The client sends the Authentication Server of the KDC a request for a ticket-granting ticket
(TGT) and receives the TGT. (See 3, 4 in the figure, Kerberos Authentication Process.)
• The client sends the TGT to the Ticket Granting Server of the KDC and receives a Kerberos
ticket. (See 5, 6 in the figure, Kerberos Authentication Process.)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 889

NetScaler 12.0

Note

The above authentication process is not necessary if the client already has a Kerberos ticket
whose lifetime has not expired. In addition, clients such as Web Services, .NET, or J2EE, which
support SPNEGO, get a Kerberos ticket for the target server, create an SPNEGO token, and insert
the token in the HTTP header when they send an HTTP request. They do not go through the client
authentication process.

Client requests a service.

1. The client sends the Kerberos ticket containing the SPNEGO token and the HTTP request to
the traffic management virtual server on the NetScaler appliance. The SPNEGO token has the
necessary GSSAPI data.
2. The NetScaler appliance establishes a security context between the client and the NetScaler
appliance. If the NetScaler appliance cannot accept the data provided in the Kerberos ticket,
the client is asked to get a different ticket. This cycle repeats till the GSSAPI data is acceptable
and the security context is established. The traffic management virtual server on the NetScaler
appliance acts as an HTTP proxy between the client and the physical server.

NetScaler appliance completes the authentication.

1. After the security context is complete, the traffic management virtual server validates the SP-
NEGO token.
2. From the valid SPNEGO token, the virtual server extracts the user ID and GSS credentials, and
passes them to the authentication daemon.
3. A successful authentication completes the Kerberos authentication.

Note

The NetScaler appliance can only support Kerberos (NEGOTIATE) SSO with backend.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Configuring kerberos authentication on the NetScaler appliance

April 16, 2019

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 890

NetScaler 12.0

This topic provides the detailed steps to configure Kerberos authentication on the NetScaler appliance
by using the CLI and the GUI.

Configuring Kerberos authentication on the CLI

1. Enable the AAA feature to ensure the authentication of traffic on the appliance.

ns-cli-prompt> enable ns feature AAA

2. Add the keytab file to the NetScaler appliance. A keytab file is necessary for decrypting the
secret received from the client during Kerberos authentication. A single keytab file contains au-
thentication details for all the services that are bound to the traffic management virtual server
on the NetScaler appliance.

First generate the keytab file on the Active Directory server and then transfer it to the NetScaler
appliance.

• Log on to the Active Directory server and add a user for Kerberos authentication. For ex-
ample, to add a user named “Kerb-SVC-Account”:

net user Kerb-SVC-Account freebsd!@#456 /add

Note

In the User Properties section, ensure that the “Change password at next logon op-
tion” is not selected and the “Password does not expire” option is selected.

• Map the HTTP service to the above user and export the keytab file. For example, run the
following command on the Active Directory server:

ktpass /out keytabfile /princ HTTP/[email protected] /pass freebsd!@#456

/mapuser newacp\dummy /ptype KRB5_NT_PRINCIPAL
Note

You can map more than one service if authentication is required for more than one
service. If you want to map more services, repeat the above command for every ser-
vice. You can give the same name or different names for the output file.

• Transfer the keytab file to the NetScaler appliance by using the unix ftp command or any
other file transfer utility of your choice.

3. The NetScaler appliance must obtain the IP address of the domain controller from the fully qual-
ified domain name (FQDN). Therefore, Citrix recommends configuring the NetScaler appliance
with a DNS server.

ns-cli-prompt> add dns nameserver <ip-address>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 891

NetScaler 12.0

Note

Alternatively, you can add static host entries or use any other means so that the NetScaler
appliance can resolve the FQDN name of the domain controller to an IP address.

4. Configure the authentication action and then associate it to an authentication policy.

a) Configure the negotiate action.

ns-cli-prompt> add authentication negotiateAction <name> -domain <domainName> -

domainUser <domainUsername> -domainUserPasswd <domainUserPassword> -keytab
<string>

b) Configure the negotiate policy and associate the negotiate action to this policy.

ns-cli-prompt> add authentication negotiatePolicy <name> <rule> <reqAction>

5. Create an authentication virtual server and associate the negotiate policy with it.

a) Create an authentication virtual server.

ns-cli-prompt> add authentication vserver <name> SSL <ipAuthVserver> 443 -

authenticationDomain <domainName>

b) Bind the negotiate policy to the authentication virtual server.

ns-cli-prompt> bind authentication vserver <name> -policy <negotiatePolicyName>

6. Associate the authentication virtual server with the traffic management (load balancing or con-
tent switching) virtual server.

ns-cli-prompt> set lb vserver <name> -authn401 ON -authnVsName <string>

Note

Similar configurations can also be done on the content switching virtual server.

7. Verify the configurations by doing the following:

a) Access the traffic management virtual server, using the FQDN. For example, Sample

b) View the details of the session on the CLI.

ns-cli-prompt> show aaa session

Configuring Kerberos authentication on the GUI

1. Enable the AAA feature.

Navigate to System > Settings, click Configure Basic Features and enable the AAA feature.

2. Add the keytab file as detailed in step 2 of the CLI procedure mentioned above.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 892

NetScaler 12.0

3. Add a DNS server.

Navigate to Traffic Management > DNS > Name Servers, and specify the IP address for the DNS
server.

4. Configure the Negotiate action and policy.

Navigate to Security > AAA - Application Traffic > Policies > Authentication > Advanced Poli-
cies > Policy, and create a policy with Negotiate as the action type.

5. Bind the negotiate policy to the authentication virtual server.

Navigate to Security > AAA - Application Traffic > Virtual Servers, and associate the Negotiate
policy with the authentication virtual server.

6. Associate the authentication virtual server with the traffic management (load balancing or con-
tent switching) virtual server.

Navigate to Traffic Management > Load Balancing > Virtual Servers, and specify the relevant
authentication settings.
Note

Similar configurations can also be done on the content switching virtual server.

7. Verify the configurations as detailed in step 7 of the CLI procedure mentioned above.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Configuring kerberos authentication on a client

September 14, 2018

Contributed by:
C

Kerberos support must be configured on the browser to use Kerberos for authentication. You can use
any Kerberos-compliant browser. Instructions for configuring Kerberos support on Internet Explorer
and Mozilla Firefox follow. For other browsers, see the documentation of the browser.

To configure Internet Explorer for Kerberos authentication

1. In the Tools menu select Internet Options.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 893

NetScaler 12.0

2. On the Security tab, click Local Intranet, and then click Sites.
3. In the Local Intranet dialog box, make sure that the Automatically detect intranet network op-
tion is selected, and then click Advanced.
4. In the Local Intranet dialog box, add the web sites of the domains of the traffic management
virtual server on the NetScaler appliance. The specified sites become local intranet sites.
5. Click Close or OK to close the dialog boxes.

To configure Mozilla Firefox for Kerberos authentication

1. Make sure that you have Kerberos properly configured on your computer.

2. Type about:config in the URL bar.

3. In the filter text box, type network.negotiate.

4. Change network.negotiate-auth.delegation-uris to the domain that you want to add.

5. Change network.negotiate-auth.trusted-uris to the domain that you want to add.

Note: If you are running Windows, you also need to enter sspi in the filter text box and
change the network.auth.use-sspi option to False.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Offloading Kerberos authentication from physical servers

April 16, 2019

Contributed by:
C

The NetScaler appliance can offload authentication tasks from servers. Instead of the physical servers
authenticating the requests from clients, the NetScaler appliance authenticates all the client requests
before it forwards them to any of the physical servers bound to it. The user authentication is based
on Active Directory tokens.

There is no authentication between the NetScaler appliance and the physical server, and the authen-
tication offload is transparent to the end users. After the initial logon to a Windows computer, the end
user does not have to enter any additional authentication information in a pop-up or on a logon page.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 894

NetScaler 12.0

In the current NetScaler appliance release, Kerberos authentication is available only for AAA traffic
management virtual servers. Kerberos authentication is not supported for SSL VPN in the Citrix Gate-
way Enterprise Edition appliance or for NetScaler appliance management.

Kerberos authentication requires configuration on the NetScaler appliance and on client browsers.

To configure Kerberos authentication on the NetScaler appliance

1. Create a user account on Active Directory. When creating a user account, verify the following
options in the User Properties section:

• Make sure that you do not select the Change password at next logon option.
• Be sure to select the Password does not expire option.

2. On the AD server, at the CLI command prompt, type:

• ktpass -princ HTTP/[email protected] -ptype KRB5_NT_PRINCIPAL

-mapuser [email protected] -mapop set -pass Citrix1 -out C:\kerbtabfile.txt

Note

Be sure to type the above command on a single line. The output of the above command is
written into the C:\kerbtabfile.txt file.

3. Upload the kerbtabfile.txt file to the /etc directory of the NetScaler appliance by using a Secure
Copy (SCP) client.

4. Run the following command to add a DNS server to the NetScaler appliance.

• add dns nameserver 1.2.3.4

The NetScaler appliance cannot process Kerberos requests without the DNS server. Be sure to
use the same DNS server that is used in the Microsoft Windows domain.

5. Switch to the command line interface of NetScaler appliance.

6. Run the following command to create a Kerberos authentication server:

• add authentication negotiateAction KerberosServer -domain “crete.lab.net” -domainUser

kerbuser -domainUserPasswd Citrix1 -keytab /var/mykcd.keytab

Note

If keytab is not available, you can specify the parameters: domain, domainUser, and -
domainUserPasswd.

7. Run the following command to create a negotiation policy:

• add authentication negotiatePolicy Kerberos-Policy ”REQ.IP.DESTIP

== 192.168.17.200”KerberosServer

© 1999-2018 Citrix Systems, Inc. All rights reserved. 895

NetScaler 12.0

8. Run the following command to create an authentication virtual server.

• add authentication vserver Kerb-Auth SSL 192.168.17.201 443 -

AuthenticationDomain crete.lab.net

9. Run the following command to bind the Kerberos policy to the authentication virtual server:

• bind authentication vserver Kerb-Auth -policy Kerberos-Policy -

priority 100

10. Run the following command to bind an SSL certificate to the authentication virtual server. You
can use one of the test certificates, which you can install from the GUI NetScaler appliance. Run
the following command to use the ServerTestCert sample certificate.

• bind ssl vserver Kerb-Auth -certkeyName ServerTestCert

11. Create an HTTP load balancing virtual server with the IP address, 192.168.17.200.

Ensure that you create a virtual server from the command line interface for NetScaler 9.3 re-
leases if they are older than 9.3.47.8.

12. Run the following command to configure an authentication virtual server:

• set lb vserver <name>-authn401 ON -authnVsName Kerb-Auth

13. Enter the host name Example in the address bar of the Web browser.

The Web browser displays an authentication dialog box because the Kerberos authentication is
not set up in the browser.
Note

Kerberos authentication requires a specific configuration on the client. Ensure that the
client can resolve the hostname, which results in the Web browser connecting to an HTTP
virtual server.

14. Configure Kerberos on the Web browser of the client computer.

• For configuring on Internet Explorer, see Configuring Internet Explorer for Kerberos au-
thentication.
• For configuring on Mozilla Firefox, see Configuring Internet Explorer for Kerberos authen-
tication.

15. Verify whether you can access the backend physical server without authentication.

To configure Internet Explorer for Kerberos authentication

1. Select Internet Options from the Tools menu.

2. Activate the Security tab.
3. Select Local Intranet from the Select a zone to view change security settings section.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 896

NetScaler 12.0

4. Click Sites.
5. Click Advanced.
6. Specify the URL, Example and click Add.
7. Restart Internet Explorer.

To configure Mozilla Firefox for Kerberos authentication

1. Enter about:config in the address bar of the browser.

2. Click the warning disclaimer.

3. Type Network.Negotiate-auth.trusted-uris in the Filter box.

4. Double click Network.Negotiate-auth.trusted-uris. A sample screen is shown below.

5. In the Enter String Value dialog box, specify www.crete.lab.net.

6. Restart Firefox.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic
5. NetScaler Kerberos single sign-on

NetScaler appliance kerberos single sign-on

September 14, 2018

Contributed by:
C

NetScaler appliances now support single sign-on (SSO) using the Kerberos 5 protocol. Users log on to
a proxy, the Application Delivery Controller (ADC), which then provides access to protected resources.

The NetScaler appliance Kerberos SSO implementation requires the user’s password for SSO meth-
ods that rely on basic, NTLM, or forms-based authentication. The user’s password is not required for
Kerberos SSO, although if Kerberos SSO fails and the NetScaler appliance has the user’s password, it
uses the password to attempt NTLM SSO.

If the user’s password is available, the KCD account is configured with a realm, and no delegated user
information is present, the NetScaler AD Kerberos SSO engine impersonates the user to obtain access
to authorized resources. Impersonation is also called unconstrained delegation.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 897

NetScaler 12.0

The NetScaler appliance Kerberos SSO engine can also be configured to use a delegated account to
obtain access to protected resources on the user’s behalf. This configuration requires delegated user
credentials, a keytab, or a delegated user certificate and matching CA certificate. Configuration that
uses a delegated account is called constrained delegation.
1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic
5. NetScaler Kerberos single sign-on

An overview of NetScaler appliance kerberos SSO

January 6, 2019
Contributed by:
C
To use the NetScaler appliance Kerberos SSO feature, users first authenticate with Kerberos or a sup-
ported third-party authentication server. Once authenticated, the user requests access to a protected
web application. The web server responds with a request for proof that the user is authorized to ac-
cess that web application. The user’s browser contacts the Kerberos server, which verifies that the
user is authorized to access that resource, and then provides the user’s browser with a service ticket
that provides proof. The browser resends the user’s request to the web application server with the ser-
vice ticket attached. The web application server verifies the service ticket, and then allows the user
to access the application.
AAA traffic management implements this process as shown in the following diagram. The diagram
illustrates the flow of information through the NetScaler appliance and AAA traffic management, on a
secure network with LDAP authentication and Kerberos authorization. AAA traffic management envi-
ronments that use other types of authentication have essentially the same information flow, although
they might differ in some details.
Figure 1. A Secure Network with LDAP and Kerberos
The AAA traffic management with authentication and authorization in a Kerberos environment re-
quires that the following actions take place.
1. The client sends a request for a resource to the traffic management virtual server on the
NetScaler appliance.
2. The traffic management virtual server passes the request to the authentication virtual server,
which authenticates the client and then passes the request back to the traffic management vir-
tual server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 898

NetScaler 12.0

3. The traffic management virtual server sends the client’s request to the web application server.
4. The web application server responds to the traffic management virtual server with a 401 Unau-
thorized message that requests Kerberos authentication, with fallback to NTLM authentication
if the client does not support Kerberos.
5. The traffic management virtual server contacts the Kerberos SSO daemon.
6. The Kerberos SSO daemon contacts the Kerberos server and obtains a ticket-granting ticket
(TGT) allowing it to request service tickets authorizing access to protected applications.
7. The Kerberos SSO daemon obtains a service ticket for the user and sends that ticket to the traffic
management virtual server.
8. The traffic management virtual server attaches the ticket to the user’s initial request and sends
the modified request back to the web application server.
9. The web application server responds with a 200 OK message.

These steps are transparent to the client, which just sends a request and receives the requested re-
source.

Integration of NetScaler appliance Kerberos SSO with authentication methods

All AAA traffic management authentication mechanisms support NetScaler appliance Kerberos SSO.
AAA traffic management supports the Kerberos SSO mechanism with the Kerberos, CAC (Smart Card)
and SAML authentication mechanisms with any form of client authentication to the NetScaler ap-
pliance. It also supports the HTTP-Basic, HTTP-Digest, Forms-based, and NTLM (versions 1 and 2)
SSO mechanisms if the client uses either HTTP-Basic or Forms-Based authentication to log on to the
NetScaler appliance.

The following table shows each supported client-side authentication method, and the supported
server-side authentication method for that client-side method.

Table 1. Supported Authentication Methods

Kerberos Constrained
Basic/Digest/NTLM Delegation User Impersonation

CAC (Smart Card): at X X

SSL/T LS Layer
Forms-Based X X X
(LDAP/RADIUS/TA-
CACS)
HTTP Basic (LDAP/RA- X X X
DIUS/TACACS)
Kerberos X

© 1999-2018 Citrix Systems, Inc. All rights reserved. 899

NetScaler 12.0

Kerberos Constrained
Basic/Digest/NTLM Delegation User Impersonation

NT LM v1/v2 X X
SAML X
SAML Two-Factor X X X
Certificate X X X
Two-Factor

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic
5. NetScaler Kerberos single sign-on

Setting up NetScaler appliance SSO

September 14, 2018

Contributed by:
C

You can configure NetScaler appliance SSO to work in one of two ways: by impersonation or by del-
egation. SSO by impersonation is a simpler configuration than SSO by delegation, and is therefore
usually preferable when your configuration allows it. To configure NetScaler appliance SSO by imper-
sonation, you must have the user’s user name and password.

To configure NetScaler appliance SSO by delegation, you must have the delegated user’s credentials
in one of the following formats: the user’s user name and password, the keytab configuration that in-
cludes the user name and an encrypted password, or the delegated user certificate and the matching
CA certificate.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic
5. NetScaler Kerberos single sign-on

© 1999-2018 Citrix Systems, Inc. All rights reserved. 900

NetScaler 12.0

Prerequisites

September 21, 2018

Contributed by:
C

Before you configure NetScaler appliance SSO, you need to have your NetScaler appliance fully con-
figured to manage traffic to and authentication for your web application servers. Therefore, you must
configure either load balancing or content switching, and then AAA, for these web application servers.
You should also verify routing between the appliance, your LDAP server, and your Kerberos server.

If your network is not already configured in this manner, perform the following configuration tasks:

• Configure a server and service for each web application server.

• Configure a traffic management virtual server to handle traffic to and from your web application
server.

Following are brief instructions and examples for performing each of these tasks from the NetScaler
appliance command line. For further assistance, see Setting up an Authentication Virtual Server.

To create a server and service by using the command line

For NetScaler appliance SSO to obtain a TGS (service ticket) for a service, either the FQDN assigned
to the server entity on the NetScaler appliance must match the FQDN of the web application server,
or the server entity name must match the NetBios name of the web application server. You can take
either of the following approaches:

• Configure the NetScaler appliance server entity by specifying the FQDN of the web application
server.
• Configure the NetScaler appliance server entity by specifying the IP address of the web applica-
tion server, and assign the server entity the same name as the NetBios name of the web appli-
cation server.

At the command prompt, type the following commands:

1 - add server name <serverFQDN>

2
3 - add service name serverName serviceType port

For the variables, substitute the following values:

• serverName. A name for the NetScaler appliance to use to refer to this server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 901

NetScaler 12.0

• serverFQDN. The FQDN of the server. If the server has no domain assigned to it, use the server’s
IP address and make sure that the server entity name matches the NetBios name of the web
application server.
• serviceName. A name for the NetScaler appliance to use to refer to this service.
• type. The protocol used by the service, either HTTP or MSSQLSVC.
• port. The port on which the service listens. HTTP services normally listen on port 80. Secure
HTTPS services normally listen on port 443.

Example

The following examples add server and service entries on the NetScaler appliance for the web appli-
cation server was1.example.com. The first example uses the FQDN of the web application server; the
second uses the IP address.

To add the server and service using the web application server FQDN, was1.example.com, you would
type the following commands:

1 add server was1 was1.example.com

2 add service was1service was1 HTTP 80

To add the server and service using the web application server IP and NetBios name, where the web
application server IP is 10.237.64.87 and its NetBios name is WAS1, you would type the following com-
mands:

1 add server WAS1 10.237.64.87

2 add service was1service WAS1 HTTP 8

To create a traffic management virtual server by using the command line

The traffic management virtual server manages traffic between the client and the web application
server. You can use either a load balancing or a content switching virtual server as the traffic manage-
ment server. The SSO configuration is the same for either type.

To create a load balancing virtual server, at the command prompt, type the following command:

add lb vserver <vserverName> <type> <IP> <port>

For the variables, substitute the following values:

• vserverName—A name for the NetScaler appliance to use to refer to this virtual server.
• type—The protocol used by the service, either HTTP or MSSQLSVC.
• IP—The IP address assigned to the virtual server. This would normally be an IANA-reserved,
non-public IP address on your LAN.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 902

NetScaler 12.0

• port—The port on which the service listens. HTTP services normally listen on port 80. Secure
HTTPS services normally listen on port 443.

Example

To add a load balancing virtual server called tmvserver1 to a configuration that manages HTTP traffic
on port 80, assigning it a LAN IP address of 10.217.28.20 and then binding the load balancing virtual
server to the wasservice1 service, you would type the following commands:

1 add lb vserver tmvserver1 HTTP 10.217.28.20 80

2 bind lb vserver tmvserv1 wasservice1

To create an authentication virtual server by using the command line

The authentication virtual server manages authentication traffic between the client and the authen-
tication (LDAP) server. To create an authentication virtual server, at the command prompt type the
following commands:

1 - add authentication vserver <authvserverName> SSL <IP> 443

2 - set authentication vserver <authvservername> ‒ authenticationdomain
<domain>

For the variables, substitute the following values:

• authvserverName —A name for the NetScaler appliance to use to refer to this authentication
virtual server. Must begin with a letter, number, or the underscore character (_), and must con-
tain only letters, numbers, and the hyphen (-), period (.) pound (#), space ( ), at (@), equals (=),
colon (:), and underscore characters. Can be changed after the authentication virtual server is
added by using the rename authentication vserver command.
• IP—The IP address assigned to the authentication virtual server. As with the traffic management
virtual server, this address would normally be an IANA-reserved, non-public IP on your LAN.
• domain—The domain assigned to the virtual server. This would usually be the domain of your
network. It is customary, though not required, to enter the domain in all capitals when config-
uring the authentication virtual server.

Example

To add an authentication virtual server called authverver1 to your configuration and assign it the LAN
IP 10.217.28.21 and the domain EXAMPLE.COM, you would type the following commands:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 903

NetScaler 12.0

1 add authentication vserver authvserver1 SSL 10.217.28.21 443

2 set authentication vserver authvserver1 ‒ authenticationdomain EXAMPLE.
COM

To configure a traffic management virtual server to use an authentication profile

The authentication virtual server can be configured to handle authentication for a single domain or
for multiple domains. If it is configured to support authentication for multiple domains, you must
also specify the domain for NetScaler appliance SSO by creating an authentication profile, and then
configuring the traffic management virtual server to use that authentication profile.

Note

The traffic management virtual server can be either a load balancing (lb) or content switching
(cs) virtual server. The following instructions assume that you are using a load balancing virtual
server. To configure a content switching virtual server, simply substitute
set cs vserver for set lb vserver. The procedure is otherwise the same.

To create the authentication profile, and then configure the authentication profile on a traffic man-
agement virtual server, type the following commands:

1 - add authentication authnProfile <authnProfileName> {

2 -authvserverName <string> }
3 {
4 -authenticationHost <string> }
5 {
6 -authenticationDomain <string> }
7
8 - set lb vserver \<vserverName\> -authnProfile <authnprofileName>

For the variables, substitute the following values:

• authnprofileName—A name for the authentication profile. Must begin with a letter, number,
or the underscore character (_), and must consist of from one to thirty-one alphanumeric or
hyphen (-), period (.) pound (#), space ( ), at (@), equals (=), colon (:), and underscore characters.
• authvserverName—The name of the authentication virtual server that this profile uses for au-
thentication.
• authenticationHost—Host name of the authentication virtual server.
• authenticationDomain—Domain for which NetScaler appliance SSO handles authentication.
Required if the authentication virtual server performs authentication for more than one do-
main, so that the correct domain is included when the NetScaler appliance sets the traffic man-
agement virtual server cookie.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 904

NetScaler 12.0

Example

To create an authentication profile named authnProfile1 for authentication of the example.com do-
main, and to configure the load balancing virtual server vserver1 to use the authentication profile
authnProfile1, you would type the following commands:

1 add authentication authnProfile authnProfile1 -authnvsName

authvsesrver1
2 -authenticationHost authvsesrver1 -authenticationDomain example.
com
3 set lb vserver vserver1 -authnProfile authnProfile1

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic
5. NetScaler Kerberos single sign-on

Configuring SSO

September 14, 2018

Contributed by:
C

Configuring NetScaler appliance SSO to authenticate by impersonation is simpler than configuring

than SSO to authenticate by delegation, and is therefore usually preferable when your configuration
allows it. You just create a KCD account. You can use the user’s password.

If you do not have the user’s password, you can configure NetScaler appliance SSO to authenticate
by delegation. Although somewhat more complex than configuring SSO to authenticate by imperson-
ation, the delegation method provides flexibility in that a user’s credentials might not be available to
the NetScaler appliance in all circumstances.

For either impersonation or delegation, you must also enable integrated authentication on the web
application server.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic
5. NetScaler Kerberos single sign-on

© 1999-2018 Citrix Systems, Inc. All rights reserved. 905

NetScaler 12.0

Enabling integrated authentication on the web application server

September 14, 2018

Contributed by:
C

To set up NetScaler appliance Kerberos SSO on each web application server that Kerberos SSO will
manage, use the configuration interface on that server to configure the server to require authentica-
tion. Select Kerberos (negotiate) authentication by preference, with fallback to NTLM for clients that
do not support Kerberos.

Following are instructions for configuring Microsoft Internet Information Server (IIS) to require authen-
tication. If your web application server uses software other than IIS, consult the documentation for
that web server software for instructions.

To configure Microsoft IIS to use integrated authentication

1. Log on to the IIS server and open Internet Information Services Manager.
2. Select the web site for which you want to enable integrated authentication. To enable inte-
grated authentication for all IIS web servers managed by IISM, configure authentication settings
for the Default Web Site. To enable integrated authentication for individual services (such as
Exchange, Exadmin, ExchWeb, and Public), configure these authentication settings for each ser-
vice individually.
3. Open the Properties dialog box for the default web site or for the individual service, and click
the Directory Security tab.
4. Beside Authentication and Access Control, select Edit.
5. Disable anonymous access.
6. Enable Integrated Windows authentication (only). Enabling integrated Windows authentication
should automatically set protocol negotiation for the web server to Negotiate, NTLM, which
specifies Kerberos authentication with fallback to NTLM for non-Kerberos capable devices. If
this option is not automatically selected, manually set protocol negotiation to Negotiate, NTLM.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic
5. NetScaler Kerberos single sign-on

© 1999-2018 Citrix Systems, Inc. All rights reserved. 906

NetScaler 12.0

Setting up SSO by impersonation

December 5, 2018

Contributed by:
C

You can configure the KCD account for NetScaler appliance SSO by impersonation. In this configura-
tion, the NetScaler appliance obtains the user’s username and passwordwhen the user authenticates
to the authentication server and uses those credentials to impersonate the user to obtain a ticket-
granting ticket (TGT). If the user’s name is in UPN format, the appliance obtains the user’s realm from
UPN. Otherwise, it obtains the user’s name and realm by extracting it from the SSO domain used dur-
ing initial authentication, or from the session profile.

When configuring the KCD account, you must set the realm parameter to the realm of the service that
the user is accessing. The same realm is also used as the user’s realm if the user’s realm cannot be
obtained from authentication with the NetScaler appliance or from the session profile.

To create the KCD account for SSO by impersonation with a password

At the command prompt, type the following command:

add aaa kcdaccount <accountname> -realmStr <realm>

For the variables, substitute the following values:

• accountname. The KCD account name.

• realm. The domain assigned to NetScaler appliance SSO.

Example

To add a KCD account named kcdccount1, and use the keytab named kcdvserver.keytab, you would
type the following command:

1 add aaa kcdAccount kcdaccount1 -keytab kcdvserver.keytab

For information on configuring Kerberos impersonation through Citrix ADC GUI, see Citrix Support.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic
5. NetScaler Kerberos single sign-on

© 1999-2018 Citrix Systems, Inc. All rights reserved. 907

NetScaler 12.0

Configuring SSO by delegation

January 10, 2019

Contributed by:
C

To configure SSO by Delegation, you need to perform the following tasks:

• If you are configuring delegation by delegated user certificate, install the matching CA certifi-
cates on the NetScaler appliance and add them to the NetScaler appliance configuration.
• Create the KCD account on the appliance. The appliance uses this account to obtain service
tickets for your protected applications.
• Configure the Active Directory server.

Note

For more information on creating KCD account and configuring on the NetScaler appliance, refer
to the following topics:

• Handling authentication, authorization and auditing with Kerberos/NTLM

• How NetScaler appliance implements Kerberos for client authentication

• Configuring kerberos authentication on the NetScaler appliance

Installing the client CA certificate on the NetScaler appliance

If you are configuring NetScaler appliance SSO with a client certificate, you must copy the matching
CA certificate for the client certificate domain (the client CA certificate) to the NetScaler appliance,
and then install the CA certificate. To copy the client CA certificate, use the file transfer program of
your choice to transfer the certificate and private-key file to the NetScaler appliance, and store the
files in /nsconfig/ssl.

To install the client CA certificate on the NetScaler appliance

At the command prompt, type the following command:

add ssl certKey <certkeyName> -cert <cert> [(-key <key> [-password])|

-fipsKey <fipsKey>][-inform ( DER | PEM )][-expiryMonitor ( ENABLED |
DISABLED | UNSET )[-notificationPeriod <positive_integer>]] [-bundle (
YES | NO )]

For the variables, substitute the following values:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 908

NetScaler 12.0

• certkeyName. A name for the client CA certificate. Must begin with an ASCII alphanumeric or
underscore (_) character, and must consist of from one to thirty-one characters. Allowed char-
acters include the ASCII alphanumerics, underscore, hash (#), period(.), space, colon (:), at (@),
equals (=), and hyphen (-) characters. Cannot be changed after the certificate-key pair is cre-
ated. If the name includes one or more spaces, enclose the name in double or single quotation
marks (for example, “my cert” or ‘my cert’).

• cert. Full path name and file name of the X509 certificate file used to form the certificate-key
pair. The certificate file must be stored on the NetScaler appliance, in the /nsconfig/ssl/ direc-
tory.

• key. Full path name and file name of the file that contains the private key to the X509 certificate
file. The key file must be stored on the NetScaler appliance in the /nsconfig/ssl/ directory.

• password. If a private key is specified, the passphrase used to encrypt the private key. Use this
option to load encrypted private keys in PEM format.

• fipsKey. Name of the FIPS key that was created inside the Hardware Security Module (HSM) of
a FIPS appliance, or a key that was imported into the HSM.

Note

You can specify either a key or a fipsKey, but not both.

• inform. Format of the certificate and private-key files, either PEM or DER.

• passplain. Pass phrase used to encrypt the private key. Required when adding an encrypted
private-key in PEM format.

• expiryMonitor. Configure the NetScaler appliance to issue an alert when the certificate is about
to expire. Possible values: ENABLED, DISABLED, UNSET.

• notificationPeriod. If expiryMonitor is ENABLED, number of days before the certificate expires

to issue an alert.

• bundle. Parse the certificate chain as a single file after linking the server certificate to its issuer’s
certificate within the file. Possible values: YES, NO.

Example

The following example adds the specified delegated user certificate customer-cert.pem to the
NetScaler appliance configuration along with the key customer-key.pem, and sets the password,
certificate format, expiration monitor, and notification period.

To add the delegated user certificate, you would type the following commands:

1 ‘‘‘add ssl certKey customer -cert ”/nsconfig/ssl/customer-cert.pem”

© 1999-2018 Citrix Systems, Inc. All rights reserved. 909

NetScaler 12.0

2 -key ”/nsconfig/ssl/customer-key.pem” -password ”

dontUseDefaultPWs!”
3 -inform PEM -expiryMonitor ENABLED [-notificationPeriod 14]

Creating the KCD account

If you are configuring NetScaler appliance SSO by delegation, you can configure the KCD account to
use the user’s log-on name and password, to use the user’s log-on name and keytab, or to use the
user’s client certificate. If you configure SSO with user name and password, the NetScaler appliance
uses the delegated user account to obtain a Ticket Granting Ticket (TGT), and then uses the TGT to
obtain service tickets for the specific services that each user requests. If you configure SSO with keytab
file, the NetScaler appliance uses the delegated user account and keytab information. If you configure
SSO with a delegated user certificate, the NetScaler appliance uses the delegated user certificate.

To create the KCD account for SSO by delegation with a password

At the command prompt, type the following commands:

add aaa kcdaccount <accountname> -delegatedUser root -kcdPassword <password

> -realmStr <realm>

For the variables, substitute the following values:

• accountname. A name for the KCD account.

• password. A password for the KCD account.
• realm. The realm of the KCD account, usually the domain for which SSO is active.

Example (UPN Format)

To add a KCD account named kcdaccount1 to the NetScaler appliance configuration with a password
of password1 and a realm of EXAMPLE.COM, specifying the delegated user account in UPN format (as
root), you would type the following commands:

1 add aaa kcdaccount kcdaccount1 ‒ delegatedUser root

2 -kcdPassword password1 -realmStr EXAMPLE.COM

Example (SPN Format)

To add a KCD account named kcdaccount1 to the NetScaler appliance configuration with a password
of password1 and a realm of EXAMPLE.COM, specifying the delegated user account in SPN format, you
would type the following commands:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 910

NetScaler 12.0

1 add aaa kcdAccount kcdaccount1 -realmStr EXAMPLE.COM

2 -delegatedUser ”host/kcdvserver.example.com” -kcdPassword password1

Creating the KCD account for SSO by delegation with a keytab

If you plan to use a keytab file for authentication, first create the keytab. You can create the keytab
file manually by logging onto the AD server and using the ktpass utility, or you can use the NetScaler
appliance configuration utility to create a batch script, and then run that script on the AD server to
generate the keytab file. Next, use FTP or another file transfer program to transfer the keytab file to
the NetScaler appliance and place it in the /nsconfig/krb directory. Finally, configure the KCD account
for NetScaler appliance SSO by delegation and provide the path and file name of the keytab file to the
NetScaler appliance.

To create the keytab file manually

Log on to the AD server command line and, at the command prompt, type the following command:

ktpass princ <SPN> ptype KRB5_NT_PRINCIPAL mapuser <DOMAIN><username> pass

<password> -out <File_Path>

For the variables, substitute the following values:

• SPN. The service principal name for the KCD service account.
• DOMAIN. The domain of the Active Directory server.
• username. The KSA account username.
• password. The KSA account password.
• path. The full path name of the directory in which to store the keytab file after it is generated.

To use the NetScaler appliance configuration utility to create a script to generate the keytab file

1. Navigate to Security > AAA - Application Traffic.

2. In the data pane, under Kerberos Constrained Delegation, click Batch file to generate Keytab.
3. In the Generate KCD (Kerberos Constrained Delegation) Keytab Script dialog box, set the
following parameters:
• Domain User Name. The KSA account username.
• Domain Password. The KSA account password.
• Service Principal. The service principal name for the KSA.
• Output File Name. The full path and file name to which to save the keytab file on the AD
server.
4. Clear the Create Domain User Account check box.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 911

NetScaler 12.0

5. Click Generate Script.

6. Log on to the Active Directory server and open a command line window.
7. Copy the script from the Generated Script window and paste it directly into the Active Directory
server command-line window. The keytab is generated and stored in the directory under the file
name that you specified as Output File Name.
8. Use the file transfer utility of your choice to copy the keytab file from the Active Directory server
to the NetScaler appliance and place it in the /nsconfig/krb directory.

To create the KCD account

At the command prompt, type the following command:

add aaa kcdaccount <accountname> ‒keytab <keytab>

Example

To add a KCD account named kcdccount1, and use the keytab named kcdvserver.keytab, you would
type the following commands:

1 add aaa kcdaccount kcdaccount1 ‒ keytab kcdvserver.keytab

To create the KCD account for SSO by delegation with a delegated user cert

At the command prompt, type the following command:

add aaa kcdaccount <accountname> -realmStr <realm> -delegatedUser <user_nameSPN

> -usercert <cert> -cacert <cacert>

For the variables, substitute the following values:

• accountname. A name for the KCD account.

• realmStr. The realm for the KCD account, usually the domain for which SSO is configured.
• delegatedUser. The delegated user name, in SPN format.
• usercert. The full path and name of the delegated user certificate file on the NetScaler appli-
ance. The delegated user certificate must contain both the client certificate and the private key,
and must be in PEM format. If you use smart card authentication, you might need to create a
smart card certificate template to allow certificates to be imported with the private key.
• cacert. The full path to and name of the CA certificate file on the NetScaler appliance.

Example

To add a KCD account named kcdccount1, and use the keytab named kcdvserver.keytab, you would
type the following command:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 912

NetScaler 12.0

1 add aaa kcdaccount kcdaccount1 -realmStr EXAMPLE.COM

2 -delegatedUser ”host/kcdvserver.example.com” -usercert /certs/
usercert
3 -cacert /cacerts/cacert

Setting up Active Directory for NetScaler appliance SSO

When you configure SSO by delegation, in addition to creating the KCDAccount on the NetScaler appli-
ance, you must also create a matching Kerberos Service Account (KSA) on your LDAP active directory
server, and configure the server for SSO. To create the KSA, use the account creation process on the
active directory server. To configure SSO on the active directory server, open the properties window
for the KSA. In the Delegation tab, enable the following options: Trust this user for delegation to spec-
ified services only and Use any Authentication protocol. (The Kerberos only option does not work,
because it does not enable protocol transition or constrained delegation.) Finally, add the services
that NetScaler appliance SSO will manage.
Note

If the Delegation tab is not visible in the KSA account properties dialog box, before you can con-
figure the KSA as described, you must use the Microsoft
setspn command-line tool to configure the active directory server so that the tab is visible.

To configure delegation for the Kerberos service account

1. In the LDAP account configuration dialog box for the Kerberos service account that you created,
click the Delegation tab.
2. Choose “Trust this user for delegation to the specified services only”.
3. Under “Trust this user for delegation to the specified services only,” choose “Use any authenti-
cation protocol”.
4. Under “Services to which this account can present delegated credentials,” click Add.
5. In the Add Services dialog box, click Users or Computers, choose the server that hosts the
resources to be assigned to the service account, and then click OK.
Note

• Constrained delegation does not support services hosted in domains other than the
domain assigned to the account, even though Kerberos might have a trust relation-
ship with other domains.
• Use the following command to create the setspn if a new user is created in active di-

© 1999-2018 Citrix Systems, Inc. All rights reserved. 913

NetScaler 12.0

rectory: setspn -A host/kcdvserver.example.com example\kcdtest

6. Back in the Add Services dialog box, in the Available Services list, choose the services assigned
to the service account. NetScaler appliance SSO supports the HTTP and MSSQLSVC services.

7. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic
5. NetScaler Kerberos single sign-on

Generating the KCD keytab script

September 14, 2018

Contributed by:
C

The KCD Keytab Script dialog box generates the keytab script, which in turn generates the keytab file
necessary to configure KCD on the NetScaler appliance.

To generate the KCD keytab script by using the configuration utility

1. Navigate to Security > AAA - Application Traffic.

2. In the details pane, under Kerberos Constrained Delegation, click Batch file to generate
keytab.
3. In the Generate KCD (Kerberos Constrained Delegation) Keytab Script dialog box, fill out the
fields as described below.
• Domain User Name: The name of the domain user.
• Domain Password: The password for the domain user.
• Service Principal: The service principal.
• Output File Name: A filename for the KCD script file.
• Create Domain User Account: Select this check box to create the specified domain user
account.
4. Click Generate Script to generate the script. The script is generated, and appears in the Gen-
erated Script text box below the Generate Script button.
5. Copy the script, and save it as a file on your AD domain controller. You must now run this script
on the domain controller to generate the keytab file, and then copy the keytab file to the /nscon-
fig/krb/ directory on the NetScaler appliance.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 914

NetScaler 12.0

6. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

SAML authentication

February 4, 2019

Contributed by:
C

Security Assertion Markup Language (SAML) is an XML-based authentication mechanism that provides
single sign-on capability and is defined by the OASIS Security Services Technical Committee.

Why SAML?

Consider a scenario in which a service provider (LargeProvider) hosts a number of applications for a
customer (BigCompany). BigCompany has users that must seamlessly access these applications. In
a traditional setup, LargeProvider would need to maintain a database of users of BigCompany. This
raises some concerns for each of the following stakeholders:

• LargeProvider must ensure security of user data.

• BigCompany must validate the users and keep the user data up-to-date, not just in its own
database, but also in the user database maintained by LargeProvider. For example, a user re-
moved from the BigCompany database must also be removed from the LargeProvider database.
• A user has to log on individually to each of the hosted applications.

The SAML authentication mechanism provides an alternative approach. The following deployment
diagram shows how SAML works.

The concerns raised by traditional authentication mechanisms are resolved as follows:

• LargeProvider does not have to maintain a database for BigCompany users. Freed from identity
management, LargeProvider can concentrate on providing better services.
• BigCompany does not bear the burden of making sure the LargeProvider user database is kept
in sync with its own user database.
• A user can log on once, to one application hosted on LargeProvider, and be automatically logged
on to the other applications that are hosted there.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 915

NetScaler 12.0

The NetScaler appliance can be deployed as a SAML Service Provider (SP) and a SAML Identity Provider
(IdP). Read through the relevant topics to understand the configurations that must be performed on
the NetScaler appliance.

A NetScaler appliance configured as a SAML service provider can now enforce an audience restriction
check. The audience restriction condition evaluates to “Valid” only if the SAML replying party is a
member of at least one of the specified audiences.

You can configure a NetScaler appliance to parse attributes in SAML assertions as group attributes.
Parsing them as group attributes enables the appliance to bind policies to the groups.

Note

A NetScaler appliance MPX FIPS appliance used as a SAML service provider now supports en-
crypted assertions. Also, a NetScaler appliance MPX FIPS appliance functioning as a SAML ser-
vice provider or a SAML identity provider can now be configured to use the SHA2 algorithms on
FIPS hardware.

Configuring FIPS offload support using the command line interface:

1. Add SSL FIPS

add ssl fipsKey fips-key

2. Create a CSR and use it at CA server to generate a certificate. You can then copy the certificate
in /nsconfig/ssl. Let’s assume that the file is fips3cert.cer.

add ssl certKey fips-cert -cert fips3cert.cer -fipsKey fips-key

3. Specify this certificate in the SAML action for SAML SP module

set samlAction <name> -samlSigningCertName fips-cert

4. Use the certificate in samlIdpProfile for SAML IDP module

set samlidpprofile fipstest ‒samlIdpCertName fips-cert

The following table lists some articles that are specific to deployments where the NetScaler appliance
is used as a SAML SP or a SAML IdP.

SAML SP SAML IdP Information Link

NetScaler Citrix AppController Z3 Citrix Support

NetScaler CloudGateway Citrix Support
NetScaler Microsoft AD FS 3.0 Citrix Support
NetScaler Shibboleth Citrix Support
NetScaler Shibboleth (With SAML single Citrix Support
logout configuration)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 916

NetScaler 12.0

SAML SP SAML IdP Information Link

Siteminder NetScaler Citrix Support

ShareFile NetScaler Citrix Support

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

NetScaler appliance as a SAML SP

September 14, 2018

Contributed by:
C

The SAML Service Provider (SP) is a SAML entity that is deployed by the service provider. When a user
tries to access a protected application, the SP evaluates the client request. If the client is unauthen-
ticated (does not have a valid NSC_TMAA or NSC_TMAS cookie), the SP redirects the request to the
SAML Identity Provider (IdP).

The SP also validates SAML assertions that are received from the IdP.

When the NetScaler appliance is configured as an SP, all user requests are received by a traffic man-
agement virtual server (load balancing or content switching) that is associated with the relevant SAML
action.

The NetScaler appliance also supports POST and Redirect bindings during logout.

Note

A NetScaler appliance can be used as a SAML SP in a deployment where the SAML IdP is config-
ured either on the appliance or on any external SAML IdP.

When used as a SAML SP, a NetScaler appliance:

• Can extract the user information (attributes) from the SAML token. This information can then
be used in the policies that are configured on the NetScaler appliance. For example, if you want
to extract the GroupMember and emailaddress attributes, in the SAMLAction, specify the At-
tribute2 parameter as GroupMember and the Attribute3 parameter as emailaddress.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 917

NetScaler 12.0

Note

Default attributes such as username, password, and logout URL must not be extracted in
attributes 1 to 16, because they as are implicitly parsed and stored in the session.

• Can extract attribute names of upto 127 bytes from an incoming SAML assertion. The previous
limit was 63 bytes. Support introduced in NetScaler 11.0 Build 64.x.

• Supports post, redirect, and artifact bindings. Support for redirect and artifact bindings is intro-
duced in NetScaler 11.0 Build 55.x.
Note

Redirect binding should not be used for large amount of data, when the assertion after
inflate or decoding is greater than 10K.

• Can decrypt assertions. Support introduced in NetScaler 11.0 Build 55.x.

• Can extract multi-valued attributes from a SAML assertion. These attributes are sent is nested
XML tags such as:

<AttributeValue> <AttributeValue>Value1</AttributeValue>
<AttributeValue>Value2</AttributeValue>
</AttributeValue>

When presented with above XML, the NetScaler appliance can extract both Value1 and Value2
as values of a given attribute, as opposed to the old firmware that extracts only Value1.

Note

Support introduced in NetScaler 11.0 Build 64.x.

• Can specify the validity of a SAML assertion.

If the system time on NetScaler appliance SAML IdP and the peer SAML SP is not in sync, the
messages might get invalidated by either party. To avoid such cases, you can now configure the
time duration for which the assertions will be valid.

This duration, called the “skew time,” specifies the number of minutes for which the message
should be accepted. The skew time can be configured on the SAML SP and the SAML IdP.

Note

Support introduced in NetScaler 11.0 Build 64.x.

• Can send additional attribute called ‘ForceAuth’ in the authentication request to external IDP
(Identity Provider). By default, the ForceAuthn is set to ‘False’. It can be set to ‘True’ to suggest
IDP to force authentication despite existing authentication context. Additionally, NetScaler ap-
pliance SP does authentication request in query parameter when configured with artifact bind-
ing.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 918

NetScaler 12.0

To configure the NetScaler appliance as a SAML SP by using the command line interface

1. Configure a SAML SP action.

Example

The following command adds a SAML action that redirects unauthenticated user requests.

add authentication samlAction SamlSPAct1 -samlIdPCertName nssp ‒samlRedirectUrl

https://auth1.example.com

2. Configure the SAML policy.

Example

The following command defines a SAML policy that applies the above defined SAML action to
all traffic.

add authentication samlPolicy SamlSPPol1 ns_true SamlSPAct1

3. Bind the SAML policy to the authentication virtual server.

Example

The following command binds the SAML policy to a authentication virtual server named
“av_saml”.

bind authentication vserver av_saml -policy SamlSPPol1

4. Bind the authentication virtual server to the appropriate traffic management virtual server.

Example

The following command adds a load balancing virtual server named “lb1_ssl” and associates
the authentication virtual server named “av_saml” to the load balancing virtual server.
add lb vserver lb1_ssl SSL 10.217.28.224 443 -persistenceType NONE -
cltTimeout 180 -AuthenticationHost auth1.example.com -Authentication ON
-authnVsName av_saml

To configure a NetScaler appliance as a SAML SP by using the graphical user interface

1. Configure the SAML action and policy.

Navigate to Security > AAA - Application Traffic > Policies > Authentication > Advanced Poli-
cies > Policy, create a policy with SAML as the action type, and associate the required SAML
action with the policy.

2. Associate the SAML policy with an authentication virtual server.

Navigate to Security > AAA - Application Traffic > Virtual Servers, and associate the SAML
policy with the authentication virtual server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 919

NetScaler 12.0

3. Associate the authentication server with the appropriate traffic management virtual server.

Navigate to Traffic Management > Load Balancing (or Content Switching) > Virtual Servers,
select the virtual server, and associate the authentication virtual server with it.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

NetScaler appliance as a SAML IdP

September 14, 2018

Contributed by:
C

The SAML IdP (Identity Provider) is a SAML entity that is deployed on the customer network. The IdP
receives requests from the SAML SP and redirects users to a logon page, where they must enter their
credentials. The IdP authenticates these credentials with the user directory (external authentication
server, such as LDAP) and then generates a SAML assertion that is sent to the SP.

The SP validates the token, and the user is then granted access to the requested protected application.

When the NetScaler appliance is configured as an IdP, all requests are received by an authentication
virtual server that is associated with the relevant SAML IdP profile.
Note

A NetScaler appliance can be used as a IdP in a deployment where the SAML SP is configured
either on the appliance or on any external SAML SP.

When used as a SAML IdP, a NetScaler appliance:

• Supports all authentication methods that it supports for traditional logons.

• Digitally signs assertions. Support for the SHA256 algorithm is introduced in NetScaler 11.0 Build
55.x.

• Supports single-factor and two-factor authentication. SAML must not be configured as the sec-
ondary authentication mechanism.

• Can encrypt assertions by using the public key of the SAML SP. This is recommended when the
assertion includes sensitive information. Support introduced in NetScaler 11.0 Build 55.x.

• Can be configured to accept only digitally signed requests from the SAML SP. Support introduced
in NetScaler 11.0 Build 55.x.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 920

NetScaler 12.0

• Can log on to the SAML IdP by using the following 401-based authentication mechanisms: Ne-
gotiate, NTLM, and Certificate. Support introduced in NetScaler 11.0 Build 55.x.

• Can be configured to send 16 attributes in addition to the NameId attribute. The attributes must
be extracted from the appropriate authentication server. For each of them, you can specify the
name, the expression, the format, and a friendly name in the SAML IdP profile. Support intro-
duced in NetScaler 11.0 Build 55.x.

• If the NetScaler appliance is configured as a SAML IdP for multiple SAML SP, a user can gain
access to applications on the different SPs without explicitly authenticating every time. The
NetScaler appliance creates a session cookie for the first authentication, and every subsequent
request uses this cookie for authentication. Support introduced in NetScaler 11.0 Build 55.x.

• Can send multi-valued attributes in a SAML assertion. Support introduced in NetScaler 11.0 Build
64.x.

• Supports post and redirect bindings. Support for redirect bindings is introduced in NetScaler
11.0 Build 64.x.

• Can specify the validity of a SAML assertion.

If the system time on NetScaler appliance SAML IdP and the peer SAML SP is not in sync, the
messages might get invalidated by either party. To avoid such cases, you can now configure the
time duration for which the assertions will be valid.

This duration, called the “skew time,” specifies the number of minutes for which the message
should be accepted. The skew time can be configured on the SAML SP and the SAML IdP.

Note

Support introduced in NetScaler 11.0 Build 64.x.

• Can be configured to serve assertions only to SAML SPs that are pre-configured on or trusted by
the IdP. For this configuration, the SAML IdP must have the service provider ID (or issuer name)
of the relevant SAML SPs. Support introduced in NetScaler 11.0 Build 64.x.

Note

Before proceeding, make sure that you have an authentication virtual server that is linked
to an LDAP authentication server.

To configure a NetScaler appliance as a SAML IdP by using the command line interface

1. Configure a SAML IdP profile.

Example

Adding NetScaler appliance as an IdP with SiteMinder as the SP.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 921

NetScaler 12.0

add authentication samlIdPProfile samlIDPProf1 -samlSPCertName siteminder

-cert -encryptAssertion ON -samlIdPCertName ns-cert -assertionConsumerServiceURL
http://sm-proxy.nsi-test.com:8080/affwebservices/public/saml2assertionconsumer
-rejectUnsignedRequests ON -signatureAlg RSA-SHA256 -digestMethod
SHA256

2. Configure the SAML authentication policy and associate the SAML IdP profile as the action of
the policy.

add authentication samlIdPPolicy samlIDPPol1 -rule ns\\_true -action

samlIDPProf1

3. Bind the policy to the authentication virtual server.

bind authentication vserver saml-auth-vserver -policy samlIDPPol1 -

priority 100

To configure a NetScaler appliance as a SAML IdP by using the graphical user interface

1. Configure the SAML IdP profile and policy.

Navigate to Security > AAA - Application Traffic > Policies > Authentication > Advanced Poli-
cies > Policy, and create a policy with SAML IdP as the action type, and associate the required
SAML IdP profile with the policy.

2. Associate the SAML IdP policy with an authentication virtual server.

Navigate to Security > AAA - Application Traffic > Virtual Servers, and associate the SAML IdP
policy with the authentication virtual server.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Configuring SAML single sign-on

September 14, 2018

Contributed by:
C

To provide single sign-on capabilities across applications that are hosted on the service provider, you
can configure SAML single sign-on on the SAML SP.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 922

NetScaler 12.0

Configuring SAML single sign-on by using the command line interface

1. Configure the SAML SSO profile.

Example

In the following command, Example is the load balancing virtual server that has a web link from
the SharePoint portal. Nssp.example.com is the Traffic Management virtual server that is load
balancing the SharePoint server.

add tm samlSSOProfile tm-saml-sso -samlSigningCertName nssp -assertionConsumerSer

”https://nssp2.example.com/cgi/samlauth”-relaystateRule ”\\”https://
nssp2.example.com/samlsso.html\\”” -sendPassword ON -samlIssuerName
nssp.example.com

2. Associate the SAML SSO profile with the traffic action.

Example

The following command enables SSO and binds the SAML SSO profile created above to a traffic
action.

add tm trafficAction html\\_act -SSO ON -samlSSOProfile tm-saml-sso

3. Configure the traffic policy that specifies when the action must be executed.

Example

The following command associates the traffic action with a traffic policy.

add tm trafficPolicy html_pol ”HTTP.REQ.URL.CONTAINS(\\”abc.html\\”)”

html_act

4. Bind the traffic policy created above to a traffic management virtual server (load balancing or
content switching). Alternatively, the traffic policy can be associated globally.

Note

This traffic management virtual server must be associated with the relevant authentication
virtual sever that is associated with the SAML action.

bind lb vserver lb1_ssl -policyName html_pol -priority 100 -gotoPriorityExpressio

END -type REQUEST

Configuring SAML single sign-on by using the graphical user interface

1. Define the SAML SSO profile, the traffic profile, and the traffic policy.

Navigate to Security > AAA - Application Traffic > Policies > Traffic, select the appropriate tab,
and configure the settings.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 923

NetScaler 12.0

2. Bind the traffic policy to a traffic management virtual server or globally to the NetScaler appli-
ance.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

OAuth authentication

March 22, 2019

Contributed by:
C

The AAA traffic management feature now supports OAuth and OpenID-Connect mechanisms for au-
thenticating and authorizing users to applications that are hosted on applications such as Google,
Facebook, and Twitter.

The authentication mehanism facilitates the inline verification of OpenID tokens. The NetScaler ap-
pliance can be configured to obtain certificates and verify signatures on the token.

A major advantage of using the OAuth and OpenID-Connect mechanisms is that the user information
is not sent to the hosted applications and therefore the risk of identity theft is considerably reduced.

The NetScaler appliance configured for AAA now accepts incoming tokens that are signed using HMAC
HS256 algorithm. In addition, the public keys of the SAML Identity Provider (IdP) are read from a file,
instead of learning from an URL endpoint.

In the NetScaler appliance implementation, the application to be accessed is represented by the AAA
traffic management virtual server. So, to configure OAuth, you must configure an OAuth policy which
must then be associated with a AAA traffic management virtual server.

Note

OAuth on NetScaler appliance is currently qualified for all SAML IdPs that are compliant with
“OpenID connect 2.0”.

To configure OAuth by using the configuration utilty:

1. Configure the OAuth action and policy.

Navigate to Security > AAA - Application Traffic > Policies > Authentication > Advanced Poli-
cies > Policy, and create a policy with OAuth as the action type, and associate the required
OAuth action with the policy.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 924

NetScaler 12.0

2. Associate the OAuth policy with an authentication virtual server.

Navigate to Security > AAA - Application Traffic > Virtual Servers, and associate the OAuth
policy with the authentication virtual server.

Note

Attributes (1 to 16) can be extracted in the OAuth response. Currently these attributes are not
evalauted. They are added for the future reference.

To configure OAuth by using the command line interface:

1. Define an OAuth action.

add authentication OAuthAction <name> -authorizationEndpoint <URL>
-tokenEndpoint <URL> [-idtokenDecryptEndpoint <URL>] -clientID <
string> -clientSecret <string> [-defaultAuthenticationGroup <string
>][-tenantID <string>][-GraphEndpoint <string>][-refreshInterval
<positive_integer>] [-CertEndpoint <string>][-audience <string>][-
userNameField <string>][-skewTime <mins>][-issuer <string>][-Attribute1
<string>][-Attribute2 <string>][-Attribute3 <string>]...

2. Associate the action with an advanced authentication policy.

add authentication Policy** <name> -rule <expression> -action <string>

Example
preblock add authentication oauthAction a -authorizationEndpoint https
://example.com/ -tokenEndpoint https://example.com/ -clientiD sadf -
clientsecret df

For more information on authentication OAuthAction parameters, see “authentication OAuthAction”.

Note

When a certEndpoint is specified, the NetScaler appliance polls that endpoint at the configured
frequency to learn the keys. To configure a NetScaler appliance to read the local file and parse
keys from that file, a new configuration option is introduced as follows.

set authentication OAuthAction <> -**CertFilePath** <path to local file

with jwks>

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

© 1999-2018 Citrix Systems, Inc. All rights reserved. 925

NetScaler 12.0

Multi-Factor (nFactor) authentication

September 14, 2018

Contributed by:
C
Important

Supported from NetScaler 11.0 Build 62.x onwards.

Starting from NetScaler 12.0 Build 51.x, NetScaler appliance used as a SAML Service Provider (SP)
with Multi-Factor (nFactor) authentication now prepopulates the user-name field on the login
page. The appliance sends a NameID attribute as part of a SAML authorization request, retrieves
the NameID attribute value from the NetScaler appliance SAML Identity Provider (IdP), and pre-
populates the user-name field.

Multi-factor authentication enhances the security of an application by requiring users to provide mul-
tiple proofs of identify to gain access. The NetScaler appliance provides an extensible and flexible
approach to configuring multi-factor authentication. This approach is called nFactor authentication.

With nFactor authentication you can:

• Configure any number of authentication factors.

• Base the selection of the next factor on the result of executing the previous factor.
• Customize the login interface. For example, you can customize the label names, error messages,
and help text.
• Extract user group information without doing authentication.
• Configure pass-through for an authentication factor. This means that no explicit login interac-
tion is required for that factor.
• Configure the order in which different types of authentication are applied. Any of the authen-
tication mechanisms that are supported on the NetScaler appliance can be configured as any
factor of the nFactor authentication setup. These factors are executed in the order in which they
are configured.
• Configure the NetScaler appliance to proceed to an authentication factor that must be executed
when authentication fails. To do so, you configure another authentication policy with the exact
same condition, but with the next highest priority and with the action set to “NO_AUTH”. You
must also configure the next factor, which must specify the alternative authentication mecha-
nism to apply.

For a nFactor benefit, see One Public IP for AAA-TM Deployments on NetScaler.

Sample deployments using nFactor authentication:

• Getting two passwords up-front, pass-through in next factor. Read

© 1999-2018 Citrix Systems, Inc. All rights reserved. 926

NetScaler 12.0

• Group extraction followed by certificate or LDAP authentication, based on group member-

ship. Read
• SAML followed by LDAP or certificate authentication, based on attributes extracted during
SAML. Read
• SAML in first factor, followed by group extraction, and then LDAP or certificate authentication,
based on groups extracted. Read
• Prefilling user name from certificate. Read
• Certificate authentication followed by group extraction for 401 enabled traffic management vir-
tual servers. Read
• Username and 2 passwords with group extraction in third factor. Read
• Certificate fallback to LDAP in same cascade; one virtual server for both certificate and LDAP
authentication. Read
• LDAP in first factor and WebAuth in second factor. Read
• Domain drop down in first factor, then different policy evaluations based on group. Read

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

How to configure nFactor authentication

January 6, 2019

Contributed by:
C

The primary entity used for nFactor authentication is called a login schema.

A login schema specifies an authentication schema XML file that defines the manner in which the login
form will be rendered. Considering the interaction that the user must have when logging in to the
application, you can create a single file for multiple factors or different files for different factors. View
sample XML file.

• Single file for multiple factors. User will be provided a single form in which to provide creden-
tials for multiple authentication factors.

• Different files for different factors. User will be provided a different form for each authentica-
tion factor.

Next, you must associate the XML file(s) with login schema(s). You can also specify expressions to ex-
tract the user name and the password from the login form.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 927

NetScaler 12.0

Tip

You can configure an authentication factor to be pass-through. This means that the user is not re-
quired to provide credentials explicitly and there is no login form for that factor. The credentials
are either taken from the previous factor or the user name and/or password are dynamically ex-
tracted by using the username/password expressions that are configured for that login schema.
You must set the login schema to “NOSCHEMA”, instead of an XML file.

Now that the login schemas are configured, you must specify the manner in which they must be in-
voked. A login schema can be invoked by using either a login schema policy or an authentication
policy label. The decision depends on the following:

• Login schema policy.

– Specifies the condition on which the login form must be presented to the user.
– Must be bound to an authentication virtual server.
– In an authentication virtual server that has multiple login schema policies, the policy with
the highest priority that evaluates to true is executed. That is, the login form associated
with that policy is presented to the user.
– The login schema policy is only used to present the first login form.
• Authentication policy label.
– Specifies a collection of authentication policies for a particular factor. Each policy label
corresponds to a single factor.
– Specifies the login form that must be presented to the user.
– Must be bound as the next factor of an authentication policy or of another authentication
policy label.
– Typically, a policy label includes authentication policies for a specific authentication
mechanism. However, you can also have a policy label that has authentication policies
for different authentication mechanisms.

To summarize, the configurations you must perform to set up nFactor authentication are as follows:

1. Create the authentication schema XML files.

2. Associate each XML file with a login schema.
3. Associate each login schema with a login schema policy or authentication policy label.
4. Bind login schema policy to an authentication virtual server.
5. Bind authentication policy label, as next factor, to an authentication policy.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

© 1999-2018 Citrix Systems, Inc. All rights reserved. 928

NetScaler 12.0

How nFactor authentication works

September 14, 2018

Contributed by:
C

Imagine a user requesting access to an application that requires user credentials. As is the case in
NetScaler appliance deployments, the request arrives at the NetScaler appliance through a traffic
management virtual server (in this case, a load balancing virtual server). Since the user must provide
authentication credentials, the load balancing virtual server redirects the request to the authentica-
tion virtual server, which does the following:

1. Checks to determine whether any login schema policies are associated with the authentication
virtual server.

- If yes, the user is presented the login form associated with the login schema policy with the
highest priority that evaluates to true.

- If no, the default login form is presented to the user.

Note

The default login schema files are available in the /nsconfig/loginschema/LoginSchema/

directory of the NetScaler appliance. Citrix recommends that you copy these files to the
/nsconfig/loginschema/ directory before using them, so that changes made to the files are
preserved post reboot.

2. The authentication policies that are associated with the authentication virtual server are eval-
uated. For the policies that are evaluated to true, the actions are executed in order of priority
until one of the actions succeeds.

3. The policy label that is associated as the next factor is invoked.

4. The authentication policies that are associated with the authentication policy label are evalu-
ated. For the policies that are evaluated to true, the actions are executed in order of priority until
one of the actions succeeds.

5. The policy label that is associated as the next factor is invoked.

6. Steps 4 and 5 are performed repetitively till all the configured next factors are executed.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

© 1999-2018 Citrix Systems, Inc. All rights reserved. 929

NetScaler 12.0

Configuring nFactor authentication

June 3, 2019

Contributed by:
C

The following diagram illustrates the high-level steps involved in nfactor configuration.

To understand the step-wise configurations for nFactor authentication, let us consider a 2-factor au-
thentication deployment where the 1st factor is LDAP authentication and the 2nd factor is RADIUS
authentication.

This sample deployment requires the user to login to both factors using a single login form. There-
fore, we define a single login form that accepts two passwords. The first password is used for LDAP
authentication and the other for RADIUS authentication. View XML file.

Here are the configurations that are performed.

1. Configure the load balancing virtual server for authentication

add lb vserver lbvs55 HTTP 1.217.193.55 80 -AuthenticationHost auth56.aaatm.com -

Authentication ON

2. Configure the authentication virtual server.

add authentication vserver auth56 SSL 1.217.193.56 443 -AuthenticationDomain aaatm.com

3. Configure the login schema for the login form and bind it to a login schema policy.

add authentication loginSchema login1 -authenticationSchema login-2passwd.xml -

userCredentialIndex 1 -passwordCredentialIndex 2

add authentication loginSchemaPolicy login1 -rule true -action login1

4. Configure a login schema for the pass-through and bind it to a policy label

add authentication loginSchema login2 -authenticationSchema noschema

add authentication policylabel label1 -loginSchema login2

5. Configure the LDAP and RADIUS policies.

add authentication ldapAction ldapAct1 -serverIP 1.217.28.180 -ldapBase “dc=aaatm, dc=com”

-ldapBindDn [email protected] -ldapBindDnPassword 71ca2b11ad800ce2787fb7deb54842875b8f3c
-encrypted -encryptmethod ENCMTHD_3 -ldapLoginName samAccountName -groupAttrName
memberOf -subAttributeName CN

add authentication Policy ldap -rule true -action ldapAct1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 930

NetScaler 12.0

add authentication radiusAction radius -serverIP 1.217.22.20 -radKey a740d6a0aeb3288fa0a6fbe932d329ac

-encrypted -encryptmethod ENCMTHD_3 -radNASip ENABLED -radNASid NS28.50 -radAttributeType
11 -ipAttributeType 8

add authentication Policy radius -rule true -action radius

6. Bind the login schema policy to the authentication virtual server

bind authentication vserver auth56 -policy login1 -priority 1 -gotoPriorityExpression END

7. Bind the LDAP policy (first factor) to the authentication virtual server.

bind authentication vserver auth56 -policy ldap -priority 1 -nextFactor label1 -gotoPriorityExpression
next

8. Bind the RADIUS policy (second factor) to the authentication policy label.

bind authentication policylabel label1 -policyName radius -priority 2 -gotoPriorityExpression

end

1.
2. Citrix ADC
3. NetScaler 12.0
4. AAA application traffic

Configuring the OpenID connect protocol

September 14, 2018

Contributed by:
C

A NetScaler appliance can now be configured as an identity provider by using OpenID Connect proto-
col. OpenID connect protocol strengthens identity providing capabilities of the NetScaler appliance.
You can now access enterprise wide hosted application with a single sign-on as OpenID connect offers
more security by not transferring user password but works with tokens with specific lifetime. OpenID
also is designed to integrate with non-browser clients such as apps and services. Therefore, OpenID
connect has been widely adopted by many implementations.

Advantages of having the OpenID connect support

• OpenID eliminates overhead of maintaining multiple authentication passwords as the user has
a single identity across organization.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 931

NetScaler 12.0

• OpenID provides a robust security for your password as the password is shared only with your
identity provider and not with any application you access.
• OpenID has vast interoperability with various systems making it easier for the hosted applica-
tions to accept OpenID.
• OpenID is a simple protocol that enables native clients to easily integrate with servers.

To configure NetScaler appliance as an IdP using the OpenID Connect protocol with the GUI**

1. Navigate to Configuration > Security > AAA-Application Traffic > Policies > Authentication > Ad-
vanced Policies > OAuth IdP.

2. Click Profile and click Add.

On the Create Authentication OAuth IDP Profile screen, set values for the following parame-
ters and click Create.

• Name – Name of the authentication profile.

• Client ID – Unique string that identifies SP.
• Client Secret – Unique secret that identifies SP.
• Redirect URL – Endpoint on SP to which code/token has to be posted.
• Issuer Name – String that identifies IdP.
• Audience – Target recipient for the token being sent by IdP. This might be checked by the
recipient.
• Skew Time – The time for which the token remains valid.
• Default Authentication Group – A group added to the session for this profile to simplify
policy evaluation and help in customizing policies.

3. Click Policies and click Add.

4. On the Create Authentication OAuth IDP Policy screen, set values for the following parameters
and click Create.

• Name – The name of the authentication policy.

• Action – Name of profile created above.
• Log Action –Name of messagelog action to use when a request matches this policy. This
is not mandatory filed.
• Undefined-Result Action – Action to perform if the result of policy evaluation is unden-
fined(UNDEF). This is not mandatory field.
• Expression – Default syntax expression that the policy uses to respond to specific request.
For example, true.
• Comments – Any comments about the policy.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 932

NetScaler 12.0

Binding the OAuthIDP policy and LDAP policy to the authentication virtual server

1. Navigate to Configuration > Security > AAA-Application Traffic > Policies >Authentication >
Advanced Policies > Actions > LDAP.

2. On LDAP Actions screen, click Add.

3. On Create Authentication LDAP Server screen, set the values for the following parameters,
and click Create.

• Name – The name of the ldap action**

• ServerName/ServerIP – Provide FQDN or IP of the LDAP server**
• Choose appropriate values for Security Type, Port, Server Type, Time-Out
• Make sure Authentication is checked
• Base DN – Base from which to start LDAP search. For example, dc=aaa,dc=local.
• Administrator Bind DN: Username of the bind to LDAP server. For example, ad-
[email protected].
• Administrator Password/Confirm Password: **Password to bind LDAP
• Click Test Connection to test your settings.
• Server Logon Name Attribute: Choose “sAMAccountName”
• Other fields are not mandatory and hence can be configured as required.

4. Navigate to Configuration > Security > AAA-Application Traffic > Policies >Authentication >
Advanced Policies > Policy.

5. On Authentication Policies screen, click Add.

6. On Create Authentication Policy page, set the values for the following parameters and click
Create.

• Name – Name of the LDAP Authentication Policy.**

• Action Type – Choose LDAP.
• Action – Choose the LDAP action created above.**
• Expression – Default syntax expression that the policy uses to respond to specific request.
For example, true.

To configure the NetScaler appliance as an IdP using the OpenID Connect protocol with the
command line

At the command prompt, type the following commands:

• add authentication OAuthIDPProfile <name> [-clientID <string>][-clientSecret

][-redirectURL <URL>][-issuer <string>][-audience <string>][-skewTime
<mins>] [-defaultAuthenticationGroup <string>]

© 1999-2018 Citrix Systems, Inc. All rights reserved. 933

NetScaler 12.0

• add authentication OAuthIdPPolicy <name> -rule <expression> [-action <

string> [-undefAction <string>] [-comment <string>][-logAction <string
>]

• add authentication ldapAction aaa-ldap-act -serverIP 10.0.0.10 -ldapBase

”dc=aaa,dc=local”

• ldapBindDn <[email protected]> -ldapBindDnPassword <password> -

ldapLoginName

sAMAccountName

• add authentication policy aaa-ldap-adv-pol -rule true -action aaa-ldap-

act

• bind authentication vserver auth_vs -policy <ldap_policy_name> -priority

100 -gotoPriorityExpression NEXT

• bind authentication vserver auth_vs -policy <OAuthIDPPolicyName> -

priority 5 -gotoPriorityExpression END

• bind vpn global ‒certkey <>

Note

You can bind more than one key. Public parts of certificates bound are sent in response to
jwks_uri query (https://gw/oauth/idp/certs)).

1.
2. Citrix ADC
3. NetScaler 12.0

Admin Partitioning

January 6, 2019

Contributed by:
C

A NetScaler appliance can be partitioned into logical entities called admin partitions, where each par-
tition can be configured and used as a separate NetScaler appliance. The following figure shows the
partitions of a NetScaler being used by different customers and departments:

A partitioned NetScaler appliance has a single default partition and one or more admin partitions.
The following table provides further details on the two partition types:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 934

NetScaler 12.0

Note

In a partitioned appliance, the mode BridgeBPDUs can be enabled only in the default partition
and not in the administrative partitions.

Default Partition

Admin Partitions

Availability:

The NetScaler appliance ships with a single partition, which is called a default partition. The default
partition is retained even after the NetScaler appliance is partitioned.

Must be explicitly created as described in Configure admin partitions.

Number of Partitions:

One

A NetScaler appliance can have one or more (maximum of 512) admin partitions.

User Access and Roles:

The default partition can be accessed and configured by all NetScaler users who are not associated
with a partition-specific command policy. As always, the operations that a user can perform are re-
stricted by the associated command policy.

Can be created only by NetScaler superusers who also specify the users for that partition. Only supe-
rusers and associated users of the partition can access and configure the admin partition.

Note: Partition users do not have shell access.

File Structure:

All files in a default partition are stored in the default NetScaler file structure.

For example, the NetScaler configuration file is stored in the /nsconfig directory and NetScaler logs
are stored in the /var/log/ directory.

All files in an admin partition are stored in directory paths that have the name of the admin partition.

For example, the NetScaler configuration file (ns.conf) is stored in the /nsconfig/partitions/<partitionName> di-
rectory. Other partition-specific files are stored in the /var/partitions/<partitionName> directories.

Some other paths in an admin partition:

• Downloaded files: /var/partitions/<partitionName>/download/

• Log files: /var/partitions/<partitionName>/log/

Note: Currently, logging is not supported at partition-level. Therefore, this directory is empty and all
logs are stored in the /var/log/ directory.

• SSL CRL certificate related files: /var/partitions/<partitionName>/netscaler/ssl

© 1999-2018 Citrix Systems, Inc. All rights reserved. 935

NetScaler 12.0

Resources Available:
All NetScaler resources.
NetScaler resources that are explicitly assigned to the admin partition.

User access and roles

In authenticating and authorizing a partitioned NetScaler appliance, a root administrator can assign
a partition administrator to one or more partitions. The partition administrator can authorize users
to that partition without affecting other partitions. These are partition users and they are authorized
to access only that partition using SNIP address. Both the root administrator and the partition admin-
istrator can configure role based access (RBA by authorizing users to access different applications.
Administrators and user roles can be described as follows:
Root Administrator. Accesses the partitioned appliance through its NSIP address and can grant user
access to one or more partitions. The administrator can also assign partition administrators to one
or more partitions. The administrator can create a partition administrator from the default partition
using a NSIP address or switch to a partition and then create a user and assign partition admin access
using a SNIP address.
Partition Administrator. Accesses the specified partition through a NSIP address assigned by the
root administrator. The administrator can assign role-based access to partition user access to that
partition and also configure external server authentication using partition specific configuration.
System User. Accesses partitions through the NSIP address. Has access to the partitions and re-
sources specified by the root administrator.
Partition User. Accesses a partition through a SNIP address. This user account is created by the par-
tition administrator and the user has access to resources, only within the partition.

Points to remember

Following are some points to remember when providing role-based access in a partition.
1. NetScaler users accessing the GUI through NSIP address will use default partition authentica-
tion configuration to log on to the appliance.
2. Partition system users accessing the GUI through partition SNIP address will use partition spe-
cific authentication configuration to log on to the appliance.
3. Partition user created in a partition cannot login using NSIP address.
4. NetScaler user bound to a partition cannot login using partition SNIP address.
5. External users accessing a partition through external server configuration as LDAP, Radius, or
TACACS added in the partition. The user must access using SNIP address to directly log onto the
partition.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 936

NetScaler 12.0

Use case for managing role Based access in an partitioned setup

Consider a scenario where an enterprise organization, www.example.com has multiple business units
and a centralized administrator who manages all instances in their network. However, they want to
provide exclusive user privileges and environment for each business unit.

Following are the administrators and users managed by default partition authentication configuration
and partition specific configuration in a partitioned appliance.

John: Root Administrator

George: Partition Administrator

Adam: System User

Jane: Partition User

John, is the root administrator of a partitioned NetScaler appliance. John manages all user accounts
and administrative user accounts across partitions (for example, P1, P2, P3, P4, and P5) within the
appliance. He provides granular role-based access to entities from the default partition of the appli-
ance. John creates user accounts and assigns partition access to each account. George being a net-
work engineer within the organization prefers to have a role based access to few applications running
on partition P2. Based on user management, John creates a partition administrator role for George
and associates his user account with partition-admin command policy in P2 partition. Adam being
another network engineer prefers to access an application running on P2. John creates a system user
account for Adam and associates his user account to P2 partition. Once his account is created, Adam
can log into the appliance to access the NetScaler Management interface through NSIP address and
can switch to partition P2 based on user/group binding.

Suppose, Jane who is another network engineer wants to directly access an application running only
on partition P2, George (partition administrator) can create a partition user account for her and as-
sociate her account with command policies for authorization privileges. Jane’s user account created
within the partition is now directly associated with P2. Now Jane can access the NetScaler Manage-
ment interface through SNIP address and cannot switch to any other partition.

Note

If Jane’s user account is created by a partition administrator in partition P2, she can access the
NetScaler Management interface only through SNIP address (created within the partition) and
not permitted to access the interface through NSIP address. Similarly, if Adam’s user account is
created by a root administrator in the default partition and is bound to P2 partition, he can access
the NetScaler Management interface only through NSIP address or SNIP address created in the
default partition (with management access enabled) and not permitted to access the partition
interface through SNIP address created in the administrative partition.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 937

NetScaler 12.0

Configure roles and responsibilities for partition administrators

Following are the configurations performed by a root administrator in a default partition.

Creating administrative partitions and system users – A root administrator creates administrative par-
titions and system users in the default partition of the appliance. The administrator then associates
the users to different partitions. If you are bound to one or more partitions, you can switch from one
partition to another based on user bindings. Also, your access to one or more bound partitions is
authorized only by the root administrator.

Authorizing system user as partition administrator for a specific partition – Once a user account is
created, the root administrator switches to a specific partition and authorizes the user as the partition
administrator. This is done by assigning partition-admin command policy to the user account. Now,
the user can access the partition as partition administrator and manage entities within the partition.

Following are the configurations perform by a partition administrator in an administrative partition.

Configuring SNIP address in an administrative partition- The partition administrator logs on to the
partition and creates a SNIP address and provides management access to the address.

Creating and Binding a Partition System User with Partition Command Policy -The partition adminis-
trator creates partition users and defines the scope of user access. This is done by binding the user
account to partition command policies.

Creating and Binding a Partition System User Groups with Partition Command Policy -The partition
administrator creates partition user groups and defines the scope of user group access. This is done
by binding the user group account to partition command policies.

Configuring External Server authentication for external users (optional)-This configuration is done for
authenticating external TACACS users accessing the partition using SNIP address.

Following are the tasks performed in configuring role-based access for partition users in an Adminis-
trative Partition.

1. Creating an Administrative Partition – Before you create partition users in an administrative par-
tition, you must first create the partition. As a root administrator, you can create a partition from
the default partition using the configuration utility or a command line interface.
2. Switching user access from default partition to partition P2 – If you are partition administrator
accessing the appliance from the default partition, you can switch from default partition to a
specific partition (for example, partition P2) based on user binding.
3. Adding SNIP address to the Partition user account with Management access enabled-Once you
have switched your access to an administration partition, you must create a SNIP address and
provide management access to the address.
4. Creating and Binding a Partition System User with Partition Command Policy-If you are a parti-
tion administrator, you can create partition users and define the scope of user access. This is
done by binding the user account to partition command policies.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 938

NetScaler 12.0

5. Creating and Binding Partition user group with Partition Command Policy-If you are a partition
administrator, you can create partition user groups and define the scope of user access control.
This is done by bind the user group account to partition command policies.

Configuring External Server authentication for external users (optional)-This configuration is done for
authenticating external TACACS users accessing the partition using SNIP address.

Benefits of using admin partitions

You can avail the following benefits by using admin partitions for your deployment:

• Allows delegation of administrative ownership of an application to the customer.

• Reduces the cost of ADC ownership without compromising on performance and ease-of-use.
• Safeguards from unwarranted configuration changes. In a non-partitioned NetScaler appliance,
authorized users of other application could intentionally or unintentionally change configura-
tions that are required for your application. This could lead to undesirable behavior. This pos-
sibility is reduced in a partitioned NetScaler appliance.
• Isolates traffic between different applications by the use of dedicated VLANs for each partition.
• Accelerates and allows to scale application deployments.
• Allows application-level or localized management and reporting.

Let us analyze a couple of cases to understand the scenarios in which you can use admin partitions.

User case 1: How Admin partition is used in an enterprise network

Let us consider a scenario faced by a company named Foo.com.

• Foo.com has a single NetScaler.

• There are five departments and each department has one application that requires to be de-
ployed with the NetScaler.
• Each application must be managed independently by a different set of users or administrators.
• Other users must be restricted from accessing the configurations.
• The application or back-end must be able to share resources like IP addresses.
• The global IT department must be able to control NetScaler-level settings which must be com-
mon to all partitions.
• Applications must be independent of one another. An error in configuration of one application
must not affect the other.

A non-partitioned NetScaler would not be able to satisfy these requirements. However, you can
achieve all these requirements by partitioning a NetScaler.

Simply create a partition for each of the applications, assign the required users to the partitions, spec-
ify a VLAN for each partition, and define global settings on the default partition.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 939

NetScaler 12.0

Use case 2: How an admin partition is used by a service provider

Let us consider a scenario faced by a service provider named BigProvider:

• BigProvider has 5 customers: 3 small enterprises and 2 large enterprises.
• SmallBiz, SmallerBiz, and StartupBiz need only the most basic NetScaler functionality.
• BigBiz and LargeBiz are larger enterprises and have applications that attract a lot of traffic.
They would like to use some of the more complex NetScaler functionality.
In a non-partitioned approach, the NetScaler administrator would typically use a NetScaler SDX ap-
pliance and provision a NetScaler instance for each customer.
This solution suits BigBiz and LargeBiz because their applications need the undiminished power of
the entire non-partitioned NetScaler appliance. However, this solution might not be as cost effective
for servicing SmallBiz, SmallerBiz, and StartupBiz.
Therefore, BigProvider decides on the following solution:
• Using a NetScaler SDX appliance to bring up dedicated NetScaler instances for Big-
Biz and LargeBiz.
• Using a single NetScaler which is partitioned into three partitions, one each for SmallBiz, Small-
erBiz, and StartupBiz.
The NetScaler administrator (superuser) creates an admin partition for each of these customers, spec-
ifies the users for the partitions, specifies the NetScaler resources for the partitions, and specifies the
VLAN to be used by the traffic that is destined for each of the partitions.
1.
2. Citrix ADC
3. NetScaler 12.0

Supported NetScaler configurations

January 6, 2019
Contributed by:
C
Depending on the NetScaler configuration and the partition in which the configuration is performed,
NetScaler configurations can be categorized into three types of configurations as given below.
Note

• Admin partitions cannot be set up on a NetScaler cluster. This means that a NetScaler clus-
ter cannot be partitioned.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 940

NetScaler 12.0

• Admin partitions cannot be set up on a NetScaler MPX-FIPS appliance.

• Case 3 lists the NetScaler features that are not supported in admin partitions.

Case 1 (global configurations)

Configurations that can be performed ONLY in the default partition and which are available or impact
all the admin partitions.

• Updates to built-in entities for monitors, TCP profiles, HTTP profiles, and so on.
• Updates to global parameters for syslog, nslog, weblog, content switching, IPSEC, SIP, DHCP,
Surge protection, TCP buffering, and system collection.
• High availability (HA) configurations
• Interface and VLAN changes
• User configurations

Case 2 (partition-specific configurations)

Configurations that can be performed independently in default and admin partitions. These configu-
rations are applicable only to the partition in which they are performed.

• Getting traffic level statistics for a partition.

• Partition admin can update IP bindings for VLAN which is bound to that partition. But cannot
update the interface bindings.
• Clearing NetScaler configurations.
• Feature-specific parameters for the following features: AppFlow, AppQoE, HTTP compression,
DNS, TCP, HTTP, encryption, responder, rewrite, and SSL.
• Feature-specific configurations such as virtual servers, services, monitors, and so on.

Case 3

Configurations that cannot be performed on admin partitions. These features can be configured in
the default partition, but there is no impact on admin partitions.

Note

Configurations that are supported on admin partitions for a particular release are marked as Yes.

Feature NetScaler NetScaler NetScaler

Component Feature 10.5 NetScaler 11.0 NetScaler 11.1 12.0

Policy Extensibility No Yes Yes Yes

© 1999-2018 Citrix Systems, Inc. All rights reserved. 941

NetScaler 12.0

Feature NetScaler NetScaler NetScaler

Component Feature 10.5 NetScaler 11.0 NetScaler 11.1 12.0

Load DBS No Yes Yes Yes

Balancing AutoScale
Load DNSSEC No No No No
Balancing
Load Diameter No No Yes Yes
Balancing
Load RTSP No No No No
Balancing
Load Sure Connect No Yes Yes Yes
Balancing
Load Autoscale No No Yes Yes
Balancing Service Group
Manageability RBA External No No No No
Authentica-
tion
Manageability RISE Cisco No No No No
Manageability ACI-Cisco No No Yes Yes
Manageability AppExpert Yes Yes Yes Yes
Manageability HDX Insight No No No No
Manageability Insight No No No No
VPN Cloudbridge No No No No
Connector
VPN NetScaler No No No No
Gateway or
SSL VPN
VPN SSL VPN ICA No No No No
Proxy
VPN Web Interface No No No No
on NetSCaler
SSL SSL Profile No No Yes Yes
SSL SSL-FIPS No No No No
SSL External-HSM No No No No

© 1999-2018 Citrix Systems, Inc. All rights reserved. 942

NetScaler 12.0

Feature NetScaler NetScaler NetScaler

Component Feature 10.5 NetScaler 11.0 NetScaler 11.1 12.0

Infra Cache No No No No
Re-direction
Infra Integrated No Yes Yes Yes
Caching
(Restricted
Feature)
Network VXLAN No No Yes Yes
Network Graceful No Yes Yes Yes
Shutdown
Network LSN No No No No
Network IPv6 Ready No No Yes Yes
Logo
Network Vpath No No Yes Yes
Load Datastream No Yes Yes Yes
Balancing
Logging Web logging No Yes Yes Yes
Network L2 Param/L3 No Yes Yes Yes
Param
Network GRE Tunnel No No Yes Yes
Loading Scriptable No Yes Yes Yes
Balancing Monitoring
Load GSLB No Yes Yes Yes
Balancing
Infra Connection No Yes Yes Yes
Mirroring
Infra FEO No Yes Yes Yes
Infra Nstrace No Yes Yes Yes
Load Priority No No Yes Yes
Balancing Queuing
Network HDOSP No No Yes Yes

© 1999-2018 Citrix Systems, Inc. All rights reserved. 943

NetScaler 12.0

Feature NetScaler NetScaler NetScaler

Component Feature 10.5 NetScaler 11.0 NetScaler 11.1 12.0

Network Netprofile No No Yes Yes

(Restricted
Feature)
Network Networking No No Yes Yes
(Restricted
Feature)
Network VRRP No No Yes Yes
(Restricted
Feature)
Logging Audit Logging No No Yes Yes
(SYSLOG-TCP,
LB of syslog
servers, SNIP
support and
FQDN
support for
syslog)
VPN NetScaler No No No No
Gateway
VPN AAA-TM No Yes (except Yes Yes
RBA authenti-
cation
feature.)
AppFlow Application No No No No
Firewall
Load TCP Buffering No No No No
Balancing (Restricted
Feature)
Policies OCSP No Yes Yes Yes
Responder
Audit Log SYSLOG-TCP No No No Yes
Optimization Front-end- No No No Yes
optimization
AppQoE AppQoE No Yes Yes Yes

© 1999-2018 Citrix Systems, Inc. All rights reserved. 944

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0

Configure admin partitions

December 5, 2018

Contributed by:
C
Important

• Only superusers are authorized to create and configure admin partitions.

• Unless specified otherwise, configurations to set up an admin partition must be done from
the default partition.

By partitioning a NetScaler appliance, you are in-effect creating multiple instances of a single
NetScaler appliance. Each instance has its own configurations and the traffic of each of these
partitions is isolated from the other by assigning each partition a dedicated VLAN or a shared VLAN.

A partitioned NetScaler has one default partition and the admin partitions that are created. To set up
an admin partition, you must first create a partition with the relevant resources (memory, maximum
bandwidth, and connections). Then, specify the users that can access the partition and the level of
authorization for each of the users on the partition.

Accessing a partitioned NetScaler is the same as accessing a non-partitioned NetScaler: through the
NSIP address or any other management IP address. As a user, after you provide your valid logon cre-
dentials, you are taken to the partition to which you are bound. Any configurations that you create
are saved to that partition. If you are associated with more than one partition, you are taken to the
first partition with which you were associated. If you want to configure entities on one of your other
partitions, you must explicitly switch to that partition.

After accessing the appropriate partition, configurations that you perform are saved to that partition
and are specific to that partition.

Note

• NetScaler superusers and other non-partition users are taken to the default partition.
• Users of all the 512 partitions can log in simultaneously.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 945

NetScaler 12.0

Tip

To access a partitioned NetScaler appliance over HTTPS by using the SNIP (with management access
enabled), make sure that each partition has the certificate of its partition administrator. Within the
partition, the partition admin must do the following:

1. Add the certificate to the NetScaler.

add ssl certKey ns-server-certificate -cert ns-server.cert -key ns-server.key

2. Bind it to a service named “nskrpcs-<SNIP>-3009”, where <SNIP> must be replaced with the
SNIP address, in this case 100.10.10.1.

bind ssl service nskrpcs-100.10.10.1-3009 -certkeyName ns-server-certificate

Partition resource limiting

In a partitioned NetScaler appliance, a network administrator can create a partition with partition
resources such as memory, bandwidth, and connection limit configured as unlimited. This is done by
specifying Zero as the partition resource value, where Zero indicates the resource is unlimited on the
partition and it can be consumed up to system limits. Partition resource configuration is useful when
you migrate a traffic domain deployment to an administrative partition or if you do not know about
resource allocation limit for a partition in a given deployment.

Resource limit for an administrative partition is as follows:

1. Partition memory. This is the maximum allocated memory for a partition. You must make sure
to specify the values when creating a partition.

Note

From NetScaler 12.0 onwards, when you create a partition, you must the set the memory
limit as Zero or if a partition is already created with a specific memory limit, you can reduce
the limit to any value or set the limit as Zero.

Parameter: maxMemLimit

Maximum memory is allocated in megabytes in a partition. A zero value indicates the memory
is unlimited on the partition and it can consume up to the system limits.

Default value: 10

2. Partition bandwidth. Maximum allocated bandwidth for a partition. If you specify a limit, make
sure it is within the appliance’s licensed throughput. Otherwise, you are not limiting the band-
width that can be used by the partition. The specified limit is accountable for the bandwidth
that the application requires. If the application bandwidth exceeds the specified limit, packets
are dropped.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 946

NetScaler 12.0

Note

From NetScaler 12.0 onwards, when you can create a partition, you can set the partition
bandwidth limit to Zero or if a partition is already created with a specific bandwidth, you
can reduce bandwidth or set the limit as Zero.

Parameter: maxBandwidth

Maximum bandwidth is allocated in Kbps in a partition. A zero value indicates the bandwidth is
unrestricted. That is, the partition can consume up to the system limits.

Default value: 10240

Maximum Value: 4294967295

3. Partition connection. Maximum number of concurrent connections that can be open in a parti-
tion. The value must accommodate the maximum simultaneous flow expected within the par-
tition. The partition connections are accounted from the partition quota memory. Previously,
the connections were accounted from the default partition quota memory. It is configured only
on the client-side, not on the back-end server-side TCP connections. New connections cannot
be established beyond this configured value.

Note

From NetScaler 12.0 onwards, you can create a partition with number of open connections
set to Zero or if you have already created a partition with a specific number of open con-
nections, you can reduce the connection limit or set the limit as Zero.

Parameter: maxConnections

Maximum number of concurrent connections that can be open in the partition. A zero value
indicates no limit on number of open connections.

Default value: 1024

Minimum value: 0

Maximum Value: 4294967295

Configure an admin partition

To configure an admin partition, complete the following tasks.

Access an admin partition

To access in an admin partition by using the command line interface

1. Log on to the NetScaler appliance.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 947

NetScaler 12.0

2. Check if you are in the correct partition. The command prompt displays the name of the cur-
rently selected partition.

3. If yes, skip to the next step.

4. If no, get a list of the partitions with which you are associated and switch over to the appropriate
partition.

• show system user <username>

• switch ns partition <partitionName>

5. Now, you can perform the required configurations just as a non-partitioned NetScaler.

To access an admin partition by using the configuration utility

1. Log on to the NetScaler appliance.

2. Check if you are in the correct partition. The top bar of the graphical user interface displays the
name of the currently selected partition.

• If yes, skip to the next step.

• If no, navigate to Configuration > System > Administrative Partitions > Partitions, right-
click the partition to which you want to switch, and select Switch.

3. Now, you can perform the required configurations just as a non-partitioned NetScaler.

Add an admin partition

The root administrator adds an administrative partition from the default partition and binds the par-
tition with VLAN 2.

To create an administrative partition by using the command line interface**

At the command prompt, type:

1 add partition <partitionname>

Switch user access from default partition to an admin partition

Now switch user access from default partition to partition Par1.

To switch a user account from default partition to an admin partition by using the command line
interface:

At the command prompt, type:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 948

NetScaler 12.0

1 Switch ns partition <pname>

Adding SNIP address to a partition user account with management access enabled

In the partition, create SNIP address with management access enabled.

To add SNIP address to the partition user account with management access enabled by using the
command line interface:

At the command prompt, type:

1 > add ns ip <ip address> <subnet mask> -mgmtAccess enabled

Create and Bind a partition user with partition command policy

In partition, create a partition system user and bind the user with partition-admin command policies.

To create and bind a partition system user with partition command policy by using the command
line interface:

At the command prompt, type:

1 > add system user <username> <password>

2 Done

Creating and binding partition user group with partition command policy

In Partition Par1, create a partition system user group and bind the group with partition command
policy such as partition admin, partition read-only, partition-operator, or partition-network.

To create and bind a partition user group with partition command policy by using the command
line interface:

1 > add system group <groupName>

2 > bind system group <groupname> (-userName | -policyName <cmdpolicy> <
priority> | -partitionName)

Configuring external server authentication for external users

In partition Par1 you can configure an external server authentication to authenticate external TACACS
users accessing the partition through SNIP address.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 949

NetScaler 12.0

To configure external server authentication for external users by using the command line inter-
face:

At the command prompt, type:

1 add authentication tacacsaction <name> -serverip <IP> -tacacsSecret <

secret key> -authorization ON -accounting ON
2 add authentication policy <policname> -rule true -action <name>
3 bind system global <policyname> -priority <value>1

Configure a Partition System User Accounts in a Partition by using the GUI

To configure a partition user account in an administrative partition, you must create a partition user
or a partition user group and bind it partition command policies. Also, you can configure the external
server authentication for an external user.

To create a partition user account in a partition by using the GUI

Navigate to System > User Administration, click Users to add a partition system user and bind the
user to command policies (partitionadmin/partitionread-only/partition-operator/partition-network).

To create a partition user group account in a partition by using the GUI

Navigate to System > User Administration, click Groups to add a partition system user group
and bind the user group to command policies (partitionadmin/partitionread-only/partition-
operator/partition-network).

To configure External server authentication for external users by using the GUI

Navigate to System > Authentication > Basic Actions and click TACACS to configure TACACS server
for authenticating external users accessing the partition.

Sample Configuration

The following configuration shows how to create a partition user or a partition user group and bind
it partition command policies. Also, how to configure the external server authentication for authenti-
cating an external user.

1 add partition Par1

2 switch ns partition Par1
3 > add ns ip 10.102.29.203 255.255.255.0 -mgmtAccessenabled
4 > add system user John Password
5 > bind system user Jane partition-read-only -priority 1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 950

NetScaler 12.0

6 > add system group Retail

7 > bind system group Retail -policyname partition-network 1 (where 1 is
the priority number)
8 > bind system group Retail ‒ username Jane
9 > add authentication tacacssaction tacuser ‒ serverip 10.102.29.200 ‒
tacacsSecret Password ‒ authorization ON ‒ accounting ON
10 > add authentication policy polname ‒ rule true ‒ action tacacsAction
11 > bind system global polname ‒ priority 1

Command Policies for a Partition Users and Partition User Groups in Administrative
Partition

Commands to authorize an Command policies available

user account inside inside an administrative
administrative partition partition (built-in policies) User account access type

add system user Partition-admin SNIP (with management

access enabled)
add system group Partition-network SNIP (with management
access enabled)
add authentication <action, Partition-read-only SNIP (with management
policy>, bind system global access enabled)
<policy name>
remove system user Partition-admin SNIP(with management
access enabled)
remove system group Partition-admin SNIP (with management
access enabled)
bind system cmdpolicy to Partition-admin SNIP (with management
system user; bind system access enabled)
cmdpolicy to system group

Configure an LACP ethernet channel on the default admin partition

With Link Aggregation Control Protocol (LACP), you can combine multiple ports into a single, high-
speed link (also called a channel). An LACP-enabled appliance exchanges LACP Data Units (LACPDU)
over the channel.

There are three LACP configuration modes that you can enable in the default partition of a NetScaler
appliance:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 951

NetScaler 12.0

1. Active. A port in active mode sends LACPDUs. Link aggregation is formed if the other end of the
Ethernet link is in the LACP active or passive mode.
2. Passive. A port in passive mode sends LACPDUs only when it receives LACPDUs. The link aggre-
gation is formed if the other end of the Ethernet link is in the LACP active mode.
3. Disable. Link aggregation is not formed.

Note

By default, the link aggregation is disabled in the default partition of the appliance.

LACP exchanges LACPDU between devices connected by an Ethernet link. These devices are typically
referred as an actor or partner.

A LACPDU data unit contains the following parameters:

• LACP Mode. Active, passive or disable.

• LACP timeout. The waiting period before timing out the partner or actor. Possible values: Long
and Short. Default: Long.
• Port Key. To distinguish between the different channel. When key is 1, LA/1 is created. When
key is 2, LA/2 is created. Possible values: Integer from 1 through 8. 4 through 8 is for cluster
CLAG.
• Port Priority. Minimum value: 1. Maximum value: 65535. Default: 32768.
• System Priority. Uses this priority along with system MAC to form the system ID to uniquely
identify the system during LACP negotiation with the partner. Sets system priority from 1 and
65535. The default value is set to 32768.
• Interface. Supports 8 interfaces per channel on NetScaler 10.1 appliance and supports 16 inter-
faces per channel on NetScaler 10.5 and 11.0 appliances.

After exchanging LACPDUs, the actor and partner negotiate the settings and decide whether to add
the ports to the aggregation.

Configure and verify LACP

To configure and verify LACP on a NetScaler appliance by using the command line

1. Enable LACP on each interface.

At the command prompt, type:

set interface <Interface_ID> -lacpMode PASSIVE -lacpKey 1

When you enable LACP on an interface, the channels are dynamically created. Additionally,
when you enable LACP on an interface and set lacpKey to 1, the interface is automatically bound
to channel LA/1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 952

NetScaler 12.0

Note

When you bind an interface to a channel, the channel parameters take precedence over
the interface parameters, so the interface parameters are ignored. If a channel was cre-
ated dynamically by LACP, you cannot perform add, bind, unbind, or remove operations
on the channel. A channel dynamically created by LACP is automatically deleted when you
disable LACP on all interfaces of the channel.

2. Set the system priority.

At the command prompt, type:

set lacp -sysPriority <Positive_Integer>

3. Verify that LACP is working as expected.

show interface <Interface_ID>

show channel

show LACP
Note

In some versions of Cisco IOS, running the switchport trunk native vlan <VLAN_ID> com-
mand causes the Cisco switch to tag LACP PDUs. This causes the LACP channel between
the Cisco switch and the NetScaler appliance to fail. However, this issue does not affect
the static link aggregation channels configured in the above procedure.

1.
2. Citrix ADC
3. NetScaler 12.0

VLAN configuration for admin partitions

April 24, 2019

Contributed by:
C

VLANs can be bound to a partition as a “Dedicated” VLAN or a “Shared” VLAN. Based on your deploy-
ment, you can bind a VLAN to a partition to isolate its network traffic from other partitions.

Dedicated VLAN – A VLAN bound only to one partition with “Sharing” option disabled and must be a
tagged VLAN. For example, in a client-server deployment, for security reasons a system administrator
creates a dedicated VLAN for each partition on the server side.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 953

NetScaler 12.0

Shared VLAN – A VLAN bound (shared across) to multiple partitions with “Sharing” option enabled.
For example, in a client-server deployment, if the system administrator does not have control over
the client side network, a VLAN is created and shared across multiple partitions.
Shared VLAN can be used across multiple partitions. It is created in the default partition and you can
bind a shared VLAN to multiple partitions. By default, a shared VLAN is bound to the default partition
implicitly and hence it cannot be bound explicitly.
Note

If a NetScaler Virtual Appliance is deployed on an ESX platform, you must enable the Promiscu-
ous mode for shared VLANs with partition. Otherwise, if the traffic is through a dedicated VLAN,
you must enable the VLAN with Portgroup properties of the virtual switch.

In a partitioned (multi-tenant) NetScaler appliance, a system administrator can isolate the traffic
flowing to a particular partition or partitions by binding one or more VLANs to each partition. A
VLAN can be dedicated to one partition or Shared across multiple partitions.

Dedicated VLANs

To isolate the traffic flowing into a partition, create a VLAN and associate it with the partition. The
VLAN is then visible only to the associated partition, and the traffic flowing through the VLAN is classi-
fied and processed only in the associated partition.
To implement a dedicated VLAN for a particular partition, do the following.
1. Add a VLAN (100).
2. Bind a network interface to VLAN as a tagged network interface.
3. Create a partition (P1).
4. Bind partition (P1) to the dedicated VLAN (100).

To add a VLAN by using the command line interface

At the command prompt, type:

add vlan <id>

add vlan 100

To bind a VLAN by using the command line interface

At the command prompt, type:

bind vlan <id> -ifnum <interface> -tagged

bind vlan 100 ‒ifnum 1/8 -tagged

© 1999-2018 Citrix Systems, Inc. All rights reserved. 954

NetScaler 12.0

To create a partition by using the command line interface

At the command prompt, type:

1 Add ns partition <partition name> [-maxBandwidth <positive_integer>][-

maxConn <positive_integer>] [-maxMemLimit <positive_integer>]
2
3 Add ns partition P1 ‒ maxBandwidth 200 ‒ maxconn 50 ‒ maxmemlimit 90
4
5 Done

To bind a partition to a VLAN by using the NetScaler CLI

At the command prompt, type:

bind partition <partition-id> -vlan <vlan>

bind partition P1 ‒vlan 100

To configure a dedicated VLAN by using the NetScaler GUI

1. Navigate to Configuration > System > Network > VLANs* and click Add to create a VLAN.
2. On the Create VLAN page, set the following parameters:
• VLAN ID
• Alias Name
• Maximum Transmission Unit
• Dynamic Routing
• IPv6 Dynamic Routing
• Partitions Sharing
3. In the Interface Bindings section, select one or more interfaces and bind it to the VLAN.
4. In the IP Bindings section, select one or more IP addresses and bind to the VLAN.
5. Click OK and Done.

Shared VLAN

In a shared VLAN configuration, each partition has a MAC address, and traffic received on the shared
VLAN is classified by MAC address. Only a Layer3 VLAN is recommended because it can restrict the sub-
net traffic. A partition MAC address is applicable and important only for a shared VLAN deployment.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 955

NetScaler 12.0

Note

Shared VLAN in a partitioned appliance does not support dynamic routing protocol.

The following diagram shows how a VLAN (VLAN 10) is shared across two partitions.

To deploy a shared VLAN configuration, do the following:

1. Create a VLAN with the sharing option ‘enabled’, or enable the sharing option on an existing
VLAN. By default, the option is ‘disabled’.
2. Bind partition interface to shared VLAN.
3. Create the partitions, each with its own PartitionMAC address.
4. Bind the partitions to the shared VLAN.

To configure a shared VLAN by using the command line interface

At the command prompt, type one of the following commands to add a new VLAN or set the sharing
parameter of an existing VLAN:

1 add vlan <id> [-sharing (ENABLED | DISABLED)]

2 set vlan <id> [-sharing (ENABLED | DISABLED)]
3 add vlan 100 ‒ sharing ENABLED
4 set vlan 100 ‒ sharing ENABLED

To bind a partition to a Shared VLAN by using the command line interface

At the command prompt, type:

1 bind partition <partition-id> -vlan <id>

2 bind partition P1 ‒ vlan
3 Add ns partition P1 ‒ maxBandwidth 200 ‒ maxconn 50 ‒ maxmemlimit
90 -partitionMAC<mac_addr
4 Done

To configure a Partition MAC Address

At the command prompt, type:

1 set ns partition <partition name> [-partitionMAC<mac_addr>]

2 set ns partition P1 ‒ partitionMAC 22:33:44:55:66:77

© 1999-2018 Citrix Systems, Inc. All rights reserved. 956

NetScaler 12.0

To bind partitions to a shared VLAN by using the command line interface

At the command prompt, type:

1 bind partition <partition-id> -vlan <id>

2 bind partition <partition-id> -vlan <id>
3 bind partition P1 ‒ vlan 100
4 bind partition P2 ‒ vlan 100
5 bind partition P3 ‒ vlan 100
6 bind partition P4 ‒ vlan 100

To configure Shared VLAN by using the NetScaler GUI

1. Navigate to Configuration > System > Network > VLANs and then select a VLAN profile and
click Edit to set the partition sharing parameter.
2. On the Create VLAN page, select the Partitions Sharing checkbox.
3. Click OK and then Done.

Shared VLAN with admin partition on Citrix ADC SDX appliance

On SDX appliance, you must generate and configure the PMAC address by using the Management Ser-
vice user interface, before using the admin partitions with shared VLANs. Management Service en-
ables you to generate partition MAC addresses by:

• Using a base MAC address

• Specifying custom MAC addresses
• Randomly generating MAC addresses

Note:

• The randomly generating MAC addresses are used for other deployments other than high
availability.
• After generating the partition MAC addresses, you must restart the Citrix ADC instance be-
fore configuring the admin partitions. For more information on generating partition MAC
addresses from SDX appliance, see Generating Partition MAC Addresses to Configure Admin
Partition on a Citrix NetScaler instance in the SDX Appliance.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 957

NetScaler 12.0

VXLAN support for admin partitions

November 6, 2018

Contributed by:
C

In a partitioned NetScaler appliance, similar to configuring a VLAN, you can configure a VXLAN in the
default partition. After configuring a VXLAN, you can bind it to an administrative partition or if a VXLAN
is extending a VLAN that is bound to a partition, the appliance binds the VXLAN to the partition under
the same broadcasting domain. This is applicable in unbinding a VLAN that unbinds a VXLAN from the
partition.

For more information about how VXLAN works in a NetScaler appliance, see VXLAN.

Also, for more information on how VLAN works in a partitioned NetScaler appliance, see Configure
admin partitions.

Points to remember before configuring a VXLAN

Remember the following points before you configure a VXLAN in a partitioned NetScaler appliance:

• When you extend a VLAN over VXLAN, make sure VLAN is bound to the partition.
• Only a partition administrator must configure the IP and dynamic routing for the VXAN in the
administrative partition.

A shared VXLAN is not supported in a partitioned appliance and so a VXLAN cannot be tagged to a
shared VLAN or you cannot make a VLAN a shared one when it is tagged to a VXLAN.

Supportable VXLAN configurations

Following are the supportable VXLAN configurations.

Case 1: Extending VLAN over a VXLAN in the same broadcast domain**

Follow the steps given below to extend a VLAN over a VXLAN and vice versa within the same broadcast
domain:

1. Add a VLAN in the default partition

At the command prompt, type:

Add vlan <id>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 958

NetScaler 12.0

2. Extend VLAN over a VXLAN within the same broadcast domain.

At the command prompt, type:

Add vxlan <vxlan id> ‒vlan <id>

3. Configure a peer vtep to carry all BUM (broadcast unknown multicast) traffic.

Note

The vtep address can be a multicast address.

At the command prompt, type:

add bridgetable -mac <mac_addr> -vxlan <positive_integer> -vtep <

ip_addr> [-vni <positive_integer>][-deviceVlan <positive_integer>]

4. Bind IP addresses to VXLAN.

At the command prompt, type:

Bind vxlan <id> [-srcIP <ip_addr>][-IPAddress <ip_addr|ipv6_addr|*> [<

netmask>]]

5. Bind VLAN to an administrative partition.

At the command prompt, type:

1 Bind partition <partition-id> -vxlan <id>

2
3 Add vlan 3000
4 Add vxlan 3000 ‒ vlan 10
5 Add bridgetable ‒ mac 00:00:00:00:00:00 ‒ vxlan 3000 -vtep
10.102.58.8 ‒ vni 11
6 Bind vxlan 3000 ‒ srcIP 10.102.101.15
7 Bind partition p1 ‒ vlan 10

1.
2. Citrix ADC
3. NetScaler 12.0

SNMP support for admin partitions

September 18, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 959

NetScaler 12.0

A partitioned NetScaler appliance uses SNMP infrastructure for partition rate limiting and for monitor-
ing partition resource utilization details.

SNMP traps for admin partition rate limiting

On a partitioned NetScaler appliance, a PARTITION-RATE-LIMIT alarm can generate nine SNMP traps
for notifying a partition resource (such as bandwidth, connection, or memory) has reached its limit or
returned to normal.

The following nine SNMP traps are generated when:

• partitionCONNThresholdReached. The number of active connections for a partition exceeds

its high threshold percentage.
• partitionCONNThresholdNormal. The number of active connections is less than or equal to
the normal threshold percentage.
• partitionBWThresholdReached. The partition’s bandwidth usage reaches its high threshold
percentage.
• partitionMEMThresholdReached. The current memory usage of the partition exceeds its high
threshold percentage.
• partitionMEMThresholdNormal. The current memory usage of the partition becomes less
than or equal to the normal threshold percentage.
• partitionMEMLimitExceeded. The current memory usage of the partition exceeds its memory
limit percentage.
• partitionCONNLimitExceeded. The number of active connections for a partition exceeds its
configured limit and new connections are being dropped.
• partitionCONNLimitNormal. The number of active connections for a partition goes below its
configured limit and the partition can now accept a new connection.
• partitionBWLimitExceeded. The current bandwidth usage for a partition has exceeded its con-
figured limit.

The threshold values for the SNMP traps are non-configurable and are as follows are:

• High threshold = 80% (applicable for all partition rate limit traps)
• Low threshold = 60 % (applicable for all partition rate limit traps)
• Memory limit = 95% (applicable only for partition memory traps)

Configuring PARTITION-RATE-LIMIT alarm

To configure PARTITION-RATE-LIMIT alarm in a specific partition and enable generation of the SNMP
trap messages.

1. Enable PARTITION-RATE-LIMIT Alarm

© 1999-2018 Citrix Systems, Inc. All rights reserved. 960

NetScaler 12.0

2. Configure PARTITION-RATE-LIMIT Alarm

3. Configure SNMP Trap Destination

To enable PARTITION-RATE-LIMIT alarm by using the NetScaler CLI

At the command prompt, type the following commands:

1 enable snmp alarm PARTITION-RATE-LIMIT

2
3 show snmp alarm PARTITION-RATE-LIMIT

To configure PARTITION-RATE-LIMIT Alarm by using the NetScaler CLI

At the command prompt, type the following command

1 set snmp alarm PARTITION-RATE-LIMIT [-state ( ENABLED | DISABLED )] [-

severity <severity>] [-logging ( ENABLED | DISABLED )]

To configure SNMP trap destination by using the NetScaler CLI

At the command prompt, type the following command:

1 add snmp trap <trapClass> <trapDestination> [-version <version>] [-td <

positive_integer>] [-destPort <port>] [-communityName <string>] [-
srcIP <ip_addr|ipv6_addr>] [-severity <severity>] [-allPartitions (
 ENABLED | DISABLED )]

To configure PARTITION-Rate-Limit alarm by using the NetScaler GUI

Navigate to System > SNMP > Alarms, select PARTITION-RATE-LIMIT alarm and configure the alarm
parameters.

To configure SNMP trap destination by using the NetScaler GUI

Navigate to System > SNMP > Trap, specify the IP address of the destination device.

SNMP monitoring for partition resource utilization

Using SNMP, you can monitor a partition’s resource (such as bandwidth, connection, and memory)
utilization details at real time on a NetScaler appliance. This is done by sending a SNMP request (such
as SNMP GET, SNMP GET BULK, SNMP GETNEXT, or SNMP WALK) from the SNMP Manager.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 961

NetScaler 12.0

Note

In order to monitor partition resources, you must configure the SNMP community in the default
partition. Wherein, the partitionTable is maintained in the default partition, and the SNMP com-
munication is done through the NSIP address of the appliance.

Consider a scenario where a NetScaler administrator wants to know the bandwidth usage of partition
P1 on the appliance. The SNMP Manager retrieves this information by sending an SNMP GET request
on the corresponding OID (partitionCurrentBandwidth) to the NSIP address of the appliance. The
SNMP agent on the default partition retrieves and sends the current bandwidth usage of P1 to the
SNMP Manager through the NSIP address.

The following table lists the SNMP counters which are part of partitionTable and its description:

SNMP Parameter SNMP OID Description

partitionName 1.3.6.1.4.1.5951.4.1.1.88.1.1 Partition name

partitionCurrentBandwidth 1.3.6.1.4.1.5951.4.1.1.88.1.2 Current bandwidth usage of
the partition.
partitionCurrentConnections 1.3.6.1.4.1.5951.4.1.1.88.1.3 Current number of active
connections of the partition.
partitionMemoryUsagePcnt 1.3.6.1.4.1.5951.4.1.1.88.1.4 Current Memory usage (in
percentage) of the partition.

1.
2. Citrix ADC
3. NetScaler 12.0

Audit log support for admin partitions

September 18, 2018

Contributed by:
C

On a partitioned NetScaler appliance, for enhanced data security, you can configure audit logging in
an administrative partition by using advanced policies. For example, you might want to view logs
(states and status information) of a specific partition that has multiple users accessing different sets
of features on the basis of their levels of authorization in the partition.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 962

NetScaler 12.0

Points to remember

1. The audit logs generated from the partition will be stored as a single log file (/var/log/ns.log).
2. You must configure the audit log server’s (syslog or nslog) subnet address as the source IP ad-
dress in the partition for sending the audit-log messages.
3. The default partition uses the NSIP as the source IP address for the audit log messages by de-
fault.
4. You can display the audit-log message by using the “show audit messages” command.

For information on audit-log configuration, see Configuring the NetScaler Appliance for Audit Logging.

Configuring audit logging in partitioned NetScaler appliance

Complete the following tasks to configure audit logging in an administrative partition.

1. Configure partition subnet IP address. An IPv4 SNIP address of an administrative partition.

2. Configure audit-log (syslog and nslog) action. An Audit action is a collection of information that
specifies the messages to be logged and how to log the messages on the external log server.
3. Configure audit-log (syslog and nslog) policies. Audit-log policies define log messages for the
source partition to the syslog or nslog server.
4. Bind audit-log policy to sysGlobal and nsGlobal entity. You must bind an audit-log policy to a
system global entity.
5. Review audit-log statistics. Display the audit-log statistics and evaluate the configuration.

To configure the partition’s subnet IP address by using the command line interface

At the command prompt, type:

1 add ns ip <ip address> <subnet mask>

To configure a syslog action by using the command line interface

At the command prompt, type:

1 add audit syslogAction <name> <serverIP> [-serverPort <port>] -

logLevel <logLevel> [-dateFormat (MMDDYYYY | DDMMYYYY )] [-
transport ( TCP | UDP )]

To configure an nslog action by using the command line interface

At the command prompt, type:

1 add audit nslogAction <name> <serverIP> [-serverPort <port>] -logLevel 

<logLevel> [-dateFormat (MMDDYYYY | DDMMYYYY )]

© 1999-2018 Citrix Systems, Inc. All rights reserved. 963

NetScaler 12.0

To configure syslog audit-log policies by using the command line interface

At the command prompt, type:

1 add audit syslogpolicy syslog-pol1 true audit-action1

To configure nslog audit-log policies by using the command line interface.

At the command prompt, type:

1 add audit nslogpolicy nslog-pol1 true audit-action1

To bind audit-log policy to syslogGlobal entity by using the command line interface.

1 bind audit syslogglobal -policyName <name> -priority <priority_integer>

-globalBindType SYSTEM_GLOBAL

To bind audit-log policy to nslogGlobal entity by using the command line interface.
At the command prompt, type:

1 bind audit nslogglobal -policyName <name> -priority <priority_integer>

-globalBindType SYSTEM_GLOBAL

To display audit-log statistics by using the command line interface.

At the command prompt, type:

1 stat audit -detail

Example

1 add ns ip 10.102.1.1 255.255.255.0

2 add audit syslogAction syslog_action1 10.102.1.2 ‒ logLevel
INFORMATIONAL ‒ dateFormat MMDDYYYY ‒ transport UDP
3 add audit syslogpolicy syslog-pol1 true syslog_action1
4 bind audit syslogglobal ‒ policyName syslog-pol1 ‒ priority 1 ‒
globalBindType SYSTEM_GLOBAL

Configuring audit-log by using the NetScaler GUI

Storing logs

When SYSLOG or NSLOG server collects log information from all partitions, it is stored as log messages
in ns.log file. The log messages contain the following information:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 964

NetScaler 12.0

• Partition Name.
• The IP address.
• A time stamp.
• The message type
• The predefined log levels (Critical, Error, Notice, Warning, Informational, Debug, Alert, and
Emergency)
• The message information.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

AppExpert

September 17, 2018

Contributed by:
C

The following topics provide a conceptual reference and configuration instructions for the AppExpert
and other features of the NetScaler appliance.

Note

For information about policy extensions, see Policy Extensions.

• Action Analytics: Collects run-time statistics on the basis of pre-defined criteria. When used with
policies, the feature also provides you with the infrastructure for automatic, real-time traffic
optimization.

• AppExpert Applications and Templates: Simplify configuration steps for the Citrix® NetScaler®
appliance by using applications, application templates, Citrix Gateway applications, and entity
templates.

• AppQoE: Application level Quality of Experience (AppQoE) integrates several existing policy-
based security features of the NetScaler appliance into a single integrated feature that takes
advantage of a new queuing mechanism, fair queuing.

• Entity Template: Describes how to use entity templates to set up and configure individual
NetScaler entities, such as a policy or virtual server. An entity template provides a specification
and a set of defaults for the object.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 965

NetScaler 12.0

• HTTP Callouts: An HTTP request that the NetScaler appliance generates and sends to an exter-
nal application when certain criteria are met during policy evaluation.

• Pattern Sets: Allow string matching during the evaluation of a default syntax policy.

• Policies and Expressions: Rules that determine the operations that the NetScaler appliance
must perform.

• Rate Limiting: Defines the maximum load for a given network entity or virtual entity on the
NetScaler appliance.

• Responder: Bases responses on who sends the request, where it is sent from, and other criteria
with security and system management implications.

• Rewrite: Rewrites information in the requests or responses handled by the NetScaler appliance.

• String Maps: Perform pattern matching in all NetScaler features that use the default policy syn-
tax.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Action analytics

September 24, 2018

Contributed by:
C

The performance of your website or application depends on how well you optimize the delivery of the
most frequently requested content. Techniques such as caching and compression help accelerate the
delivery of services to clients, but you need to be able to identify the resources that are requested most
frequently, and then cache or compress those resources. You can identify the most frequently used re-
sources by aggregating real-time statistics about website or application traffic. Statistics such as how
frequently a resource is accessed relative to other resources and how much bandwidth is consumed
by those resources help you determine whether those resources need to be cached or compressed
to improve server performance and network utilization. Statistics such as response times and the
number of concurrent connections to the application help you determine whether you must enhance
server-side resources.

If the website or application does not change frequently, you can use products that collect statistical
data, and then manually analyze the statistics and optimize the delivery of content. However, if you

© 1999-2018 Citrix Systems, Inc. All rights reserved. 966

NetScaler 12.0

do not want to perform manual optimizations, or if your website or application is dynamic in nature,
you need infrastructure that can not only collect statistical data but can also automatically optimize
the delivery of resources on the basis of the statistics. On the NetScaler appliance, this functionality
is provided by the action analytics feature. The feature operates on a single NetScaler appliance and
collects run-time statistics on the basis of criteria that you define. When used with NetScaler policies,
the feature also provides you with the infrastructure that you need for automatic, real-time traffic
optimization.

When configuring the action analytics feature, you specify the request attributes for which you want
to collect statistical data, for example, URLs and HTTP methods by configuring default syntax expres-
sions in an entity called a selector. Then, you configure an identifier to configure settings such as the
sampling interval and sample count. You also configure a policy that enables the appliance to eval-
uate traffic as specified by the selector-identifier pair. Finally, you bind the policy to a bind point to
begin collecting statistics.

The appliance also provides you with a set of built-in selectors, identifiers, and responder policies that
you can use to get started with the feature.

The appliance aggregates the following statistics:

• The number of requests.

• The bandwidth consumed by the requests.
• The response time.
• The number of concurrent connections.

You can configure the feature to perform run-time sorting of the records on an attribute of your choice.
You can view the statistical data by using either the command-line interface or the Stream Sessions
tool in the GUI.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configure a selector

January 6, 2019

Contributed by:
C

A selector is a filter for identifying requests. It consists of up to five individual default syntax expres-
sions that identify request attributes such as the client IP address and the URL in the request. Each

© 1999-2018 Citrix Systems, Inc. All rights reserved. 967

NetScaler 12.0

expression is a non-compound default syntax expression and is considered to be in an AND relation-

ship with the other expressions. Following are some examples of selector expressions:

• HTTP.REQ.URL
• CLIENT.IP.SRC
• HTTP.RES.BODY(1000).AFTER_STR(”<string>”).BEFORE_STR(”<string>”)”
• CLIENT.IP.SRC.SUBNET(24)

Selectors are used in rate limiting and action analytics configurations. A selector is optional in a rate
limiting configuration but is required in an action analytics configuration.

The order in which you specify parameters is significant. For example, if you configure an IP address
and a domain (in that order) in one selector, and then specify the domain and the IP address (in the
reverse order) in another selector, the NetScaler considers these values to be unique. This can lead
to the same transaction being counted twice. Also, if multiple policies invoke the same selector, the
NetScaler, again, can count the same transaction more than once.

If you modify an expression in a selector, you may get an error if any policy that invokes it is bound to
a new policy label or bind point. For example, suppose that you create a selector named myLimitSe-
lector1, invoke it from myLimitID1, and invoke the identifier from a DNS policy named dnsRateLimit1.
If you change the expression in myLimitSelector1, you might receive an error when binding dnsRate-
Limit1 to a new bind point. The workaround is to modify these expressions before creating the policies
that invoke them.

The NetScaler appliance provides built-in selectors for some of the most common use cases. Refer to
the pdf.

You can also configure a selector with expressions that identify the request attributes of your choice.
For example, you might want to create a record for a request that arrives with a specific header. To
evaluate the header, you can add HTTP.REQ.HEADER(“”) to the selector that you intend to use.

To configure a selector by using the command line interface:

At the command prompt, type the following commands to configure a selector and verify the config-
uration:

• add stream selector <name> <rule> ...

• show stream selector

Example

1 > add stream selector myselector HTTP.REQ.URL CLIENT.IP.SRC

2 Done
3 > show stream selector myselector
4 Name: myselector

© 1999-2018 Citrix Systems, Inc. All rights reserved. 968

NetScaler 12.0

5 Expressions:
6 1) HTTP.REQ.URL
7 2) CLIENT.IP.SRC
8 Done
9 >

To modify or remove a selector by using the command line interface:

• To modify a selector, type the set stream selector command, the name of the selector, and the
rule parameter with the expressions. Enter the existing expressions that you want to retain,
along with the new expressions that you want to add.
• To remove a selector, type the rm stream selector command and the name of the selector.
To configure a selector by using the GUI:
1. Navigate to AppExpert > Action Analytics > Selectors.
2. In the details pane, do one of the following:
• To create a selector, click Add.
• To modify a selector, select the selector, and then click Edit.
3. In the Create Selector or Configure Selector page, set the following parameters:
• Name
• Expressions
To add the expression to the selector configuration, click
Add. To remove an expression from the selector configuration, in the
Expression box, select the expression, and then click
Delete.
Note: In the
Expressions box, enter a valid parameter. For example, enter HTTP. Then, enter a period
after this parameter. A drop-down menu appears. The contents of this menu provide the
keywords that can follow the initial keyword that you entered. To select the next keyword
in this expression prefix, double-click the selection in the drop-down menu. The
Expressions text box displays both the first and second keywords for the expression prefix,
for example,
HTTP.REQ. Continue adding expression components until the complete expression is
formed.
4. Click Add.
5. Continue adding up to five non-compound expressions.
6. Click OK and then Close.
1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 969

NetScaler 12.0

Configure a stream identifier

September 24, 2018

Contributed by:
C

You configure a stream identifier to specify parameters for collecting statistical data from requests
identified by a given selector. An identifier specifies the selector to be used, the statistics collection
interval, the sample count, and the field on which the records are to be sorted.

The NetScaler appliance includes the following built-in stream identifiers for common use cases. All
the built-in identifiers specify a sample count of 1 and an interval of 1 minute. Additionally, they sort
the data on the
REQUESTS attribute. They differ only in being associated with different built-in selectors. Each built-
in identifier is associated with a built-in selector of the same name (for example, the built in identifier
Top_URL is associated with the built-in selector
Top_URL). Following are the built-in identifiers:

• Top_URL
• Top_CLIENTS
• Top_URL_CLIENTS_LBVSERVER
• Top_URL_CLIENTS_CSVSERVER
• Top_MSSQL_QUERY_DB_LBVSERVER
• Top_MYSQL_QUERY_DB_LBVSERVER

For more information about the built-in selectors, see Configuring a Selector.

Note: The maximum length for storing string results of selectors (for example, HTTP.REQ.URL) is 60
characters. If the string (for example, URL) is 1000 characters long, of which 50 characters are enough
to uniquely identify a string, use an expression to extract only the required 50 characters.

You cannot modify a built-in identifier’s configuration. However, you can create an identifier with a
configuration of your choice.

To configure a stream identifier by using the command line interface

At the command prompt, type the following commands to configure a stream identifier and verify the
configuration:

• add stream identifier <name> <selectorName> [-interval <positive_integer

>] [-SampleCount <positive_integer>] [-sort <sort>]
• show stream identifier <name>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 970

NetScaler 12.0

Example

1 > add stream identifier myidentifier Top_URL -interval 10 -sampleCount

100
2 Done

To configure a stream identifier by using the GUI

1. Navigate to AppExpert > Action Analytics > Stream Identifiers.

2. In the details pane, do one of the following:
• To create a stream identifier, click Add.
• To modify a stream identifier, select the identifier, and then click Edit.
3. In the Configure Stream Identifier page, set the following parameters:
• Name
• Selector
• Interval
• Sample Count
• Sort
4. Click OK, and then click Close.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

View statistics

September 24, 2018

Contributed by:
C

You can view the collected statistics in tabular format in the command-line interface and in graphical
format in the GUI.

The following table describes the collected statistics:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 971

NetScaler 12.0

Column name in the output

of the stat stream identifier
<identifier name>
tistics command Description

Number of requests Req The number of requests for

which records were created in
the last <interval> number
of minutes.
Bandwidth consumed BandW The total bandwidth
consumed by the requests
that were received in the
last <interval> number of
minutes. The total bandwidth
of a request is the bandwidth
consumed by the request and
its response. The value is
rounded off to the next higher
or next lower integer value.
Consequently, it might differ
slightly from the expected
value. For example, if a
request’s total bandwidth
consumption is 2.2 KB, one
instance of the request might
be shown as having
consumed 2 KB and two
instances might be shown as
having consumed 4 KB, but
three instances might be
shown as having consumed 7
KB.
Response time RspTime The average response time for
all the requests received in
the last <interval> number
of minutes.
Concurrent connections Conn The total number of
concurrent connections that
are currently open.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 972

NetScaler 12.0

To view the statistical data collected for a stream identifier by using the command line
At the command prompt, type:
stat stream identifier <name> [<pattern> ...] [-detail] [-fullValues] [-
ntimes <positive_integer>] [-logFile <input_filename>] [-sortBy <sortBy> [<
sortOrder>]

Examples

Example 1 sorts the output on the BandW column, in the descending order. Example 2 sorts the output
in Example 1, on the Req column, and in the ascending order
Example 1

1 > stat stream identifier myidentifier -sortBy BandW Descending -

fullValues
2 Stream Session statistics
3 Req BandW
4 User1 508 125924
5 User2 5020 12692
6 User3 2025 4316
7
8 RspTime Conn
9 User1 5694 0
10 User2 109 0
11 User3 3 0
12 Done

Example 2

1 > stat stream identifier myidentifier -sortBy Req Ascending ‒

fullValues
2 Stream Session statistics
3 Req BandW
4 User1 508 125924
5 User3 2025 4316
6 User2 5020 12692
7
8 RspTime Conn
9 User1 5694 0
10 User3 3 0
11 User2 109 0
12 Done

To view the statistical data collected for a stream identifier by using the GUI

© 1999-2018 Citrix Systems, Inc. All rights reserved. 973

NetScaler 12.0

1. Navigate to AppExpert > Action Analytics > Stream Identifiers.

2. Select the stream identifier whose sessions you want to view, and then click Statistics For in-
formation about how you can group the output on the basis of the values collected for various
selector expressions.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Grouping records on attribute values

September 26, 2018

Contributed by:
C

Statistical information such as the number of times a particular URL has been accessed overall and
per client, and the total number of GET and POST requests per client can provide valuable insights
into whether any of your resources need to be expanded to meet the demand or be optimized for
delivery. To obtain such statistics, you must use an appropriate set of selector expressions, and then
use the pattern parameter in the stat stream identifier command. The grouping is based on the pattern
that is specified in the command. Grouping can be performed concurrently on the values of multiple
expressions.

In the command-line interface, you can group the output by using patterns of your choice. In the
GUI, the pattern depends on the choices you make when drilling down through the values of vari-
ous selector expressions. For example, consider a selector that has the expressions HTTP.REQ.URL,
CLIENT.IP.SRC, and HTTP.REQ.LB_VSERVER.NAME, in that order. The statistics home page displays
icons for each of these expressions. If you click the icon for CLIENT.IP.SRC, the output is based on the
patterns ?. The output displays statistics for each client IP address. If you click an IP address, the out-
put is based on the patterns * <IP address> ? and ? <IP address> * where <IP address> is the
IP address you selected. In the resulting output, if you click a URL, the pattern used is <URL> <IP
address> ?.

To group the records on the values of selector expressions by using the command line
interface

At the command prompt, enter the following command to group the records on the basis of a selector
expression:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 974

NetScaler 12.0

stat stream identifier <name> [<pattern> ...]

Examples

Each example uses a different pattern to demonstrate the effect of the pattern on the out-
put of the stat stream identifier command. The selector expressions are HTTP.REQ.URL and
HTTP.REQ.HEADER(“UserHeader”), in that order. The requests contain a custom header whose name
is UserHeader. Note that in the examples, a given statistical value changes as determined by the
grouping, but the sum total of the values for a given field remains the same.

Example 1

In the following command, the pattern used is ? ?. The appliance groups the output on the values
collected for both selector expressions. The row headers consist of the expression values separated by
a question mark (?). The row with the header /mysite/mypage1.html?Ed displays statistics for requests
made by user Ed for the URL /mysite/mypage1.html.

1 > stat stream identifier myidentifier ? ? -fullValues

2 Stream Session statistics
3 Req BandW
4 /mysite/mypage2.html?Grace 1 2553
5 /mysite/mypage1.html?Grace 2 4
6 /mysite/mypage1.html?Ed 8 16
7 /mysite/mypage2.html?Joe 1 2554
8 /mysite/mypage1.html?Joe 5 10
9 /mysite/?Joe 1 4
10
11 RspTime Conn
12 /mysite/mypage2.html?Grace 0 0
13 /mysite/mypage1.html?Grace 0 0
14 /mysite/mypage1.html?Ed 0 0
15 /mysite/mypage2.html?Joe 0 0
16 /mysite/mypage1.html?Joe 0 0
17 /mysite/?Joe 6 0
18 Done

Example 2

In the following command, the pattern used is * ?. The appliance groups the output on the values
accumulated for the second expression HTTP.REQ.HEADER(“UserHeader”). The rows display statistics
for all requests made by users Grace, Ed, and Joe.

1 > stat stream identifier myidentifier * ?

2 Stream Session statistics
3 Req BandW RspTime Conn
4 Grace 3 2557 0 0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 975

NetScaler 12.0

5 Ed 8 16 0 0
6 Joe 7 2568 6 0
7 Done

Example 3

In the following command, the pattern used is ? *, which is the default pattern. The output is grouped
on the values collected for the first selector expression. Each row displays statistics for one URL.

1 > stat stream identifier myidentifier ? * -fullValues

2 Stream Session statistics
3 Req BandW
4 /mysite/mypage2.html 2 5107
5 /mysite/mypage1.html 15 30
6 /mysite/ 1 4
7
8 RspTime Conn
9 /mysite/mypage2.html 0 0
10 /mysite/mypage1.html 0 0
11 /mysite/ 6 0
12 Done

Example 4

In the following command, the pattern used is * *. The appliance displays one set of collective statistics
for all the requests received, with no row title.

1 > stat stream identifier myidentifier * *

2 Stream Session statistics
3 Req BandW RspTime Conn
4 18 5141 6 0
5 Done

Example 5

In the following command, the pattern is /mysite/mypage1.html *. The appliance displays one set of
collective statistics for all the requests received for the URL /mysite/mypage1.html, with no row title.

1 > stat stream identifier myidentifier /mysite/mypage1.html *

2 Stream Session statistics
3 Req BandW RspTime Conn
4 15 30 0 0
5 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 976

NetScaler 12.0

To group the records on the values of selector expressions by using the GUI

1. Navigate to AppExpert > Action Analytics > Stream Identifiers.

2. In the details pane, click the stream identifier for which you want to view statistics, and then
click Stream Sessions.
3. On the Home page, click the icon for the stream selector by which you want to group the output.
4. To return to the Home page from the statistics page for a selector expression, click Home.
5. To view statistics for the value of a given selector expression, click the value. You can repeat this
step for a selector expression value in each subsequent output until you obtain the statistics
you want.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Clearing a stream session

September 24, 2018

Contributed by:
C

You can flush all the records that have been accumulated for a stream identifier.

To clear a stream session by using the command line interface

At the command prompt, enter the following commands to clear a stream session and verify the re-
sults:

• clear stream session

• stat stream identifier

Example

This example uses the stat stream identifier command first, so that a comparison can be made with
the stat stream identifier command that is used for verifying the result of the clear stream session
command.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 977

NetScaler 12.0

1 >stat stream identifier myidentifier

2 Stream Session statistics
3 Req BandW RspTime Conn
4 /aed....html 2 0 0 0
5 / 636 303 12 0
6 Done
7 >clear stream session myidentifier
8 Done
9 >stat stream identifier myidentifier
10 Done

To clear a stream session by using the GUI

1. Navigate to AppExpert > Action Analytics > Stream Identifiers.

2. Select the stream identifier whose sessions you want to clear, and then click Clear Sessions.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configure policy for optimizing traffic

September 24, 2018

Contributed by:
C

To put the selector-identifier pair in your action analytics configuration into effect, you must associate
the pair with the point in the traffic flow at which you want to collect statistics. You can do so by
configuring a default syntax policy and referencing the stream identifier from the policy rule. You can
use compression policies, caching policies, rewrite policies, application firewall policies, responder
policies, and any other policies whose action is based on a Boolean expression.

The action analytics feature introduces a set of default syntax expressions and functions for collecting
and evaluating data. The expression ANALYTICS.STREAM(<identifier_name>) is used for refer-
encing the identifier that you want to use. The expression COLLECT_STATS is used to collect statistical
data. Functions such as IS_TOP(<uint>) and IS_TOP_FREQUENTS(<uint>) are used for making
automatic, real-time traffic optimization decisions.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 978

NetScaler 12.0

• **IS_TOP().** Finds if a given object is in the top of elements. For example, is the element among
the top 10 elements. When multiple elements have the count, they are considered to be similar
in nature. The sort function must be turned on to avoid an undef condition.

• **IS_TOP_FREQUENTS().** Finds if a given object is in the top of the elements that are in the top
elements. For example, is the element among the top 50% of all the top elements maintained.
Elements having the same values are considered similar in nature. The sort function must be
turned on to avoid an undef condition.

It is your policy configuration that determines whether the NetScaler appliance must only collect data
from traffic or also perform an action. If the appliance must only collect statistical data, you can con-
figure a policy with the rule ANALYTICS.STREAM().COLLECT_STATS and the action NOOP. The NOOP
policy must be the policy with the highest priority at the bind point. This policy is sufficient if you are
only collecting statistics. Traffic optimization decisions, such as what to compress or cache, must be
based on manual, periodic evaluation of the statistical data.

If, in addition to collecting statistics, the appliance must also perform an action on the traffic, you must
configure the gotoPriorityExpression parameter of the NOOP policy such that another policy that has
the desired rule and action is evaluated subsequently. This second policy must have a rule that begins
with the ANALYTICS.STREAM() prefix and a function that evaluates the data.

Following is an example of two responder policies that are configured and bound globally. The policy
responder_stat_collection enables the appliance to collect statistics based on the identifier, myiden-
tifier. The policy responder_notify evaluates the data that is collected.

Example

1 > add responder action send_notification respondwith ’”You are in the

Top 10 list for bandwidth consumption”’
2 Done
3 > add responder policy responder_stat_collection’ ANALYTICS.STREAM(”
myidentifier”).COLLECT_STATS’ NOOP
4 Done
5 > add responder policy responder_notify ’ANALYTICS.STREAM(”myidentifier
”).BANDWIDTH.IS_TOP(10)’ send_notification
6 Done
7 > bind responder global responder_stat_collection 10 NEXT
8 Done
9 > bind responder global responder_notify 20 END
10 Done

1.
2. Citrix ADC

© 1999-2018 Citrix Systems, Inc. All rights reserved. 979

NetScaler 12.0

3. NetScaler 12.0
4. AppExpert

How to limit bandwidth consumption per user or client device

March 7, 2019

Contributed by:
C

Your web site, application, or file hosting service has finite network and server resources available to it
to serve all its users. One of the most important resources is bandwidth. Substantial bandwidth con-
sumption by only a subset of the user base can result in network congestion and reduced resource
availability to other users. To prevent network congestion, you might have to limit a client’s band-
width consumption by using temporary service denial techniques such as responding to a client re-
quest with an HTML page if it has exceeded a preconfigured bandwidth value over a fixed time period
leading up to the request.

In general, you can regulate bandwidth consumption either per client device or per user. This use
case demonstrates how you can limit bandwidth consumption per client to 100 MB over a time period
of one hour. The use case also demonstrates how you can regulate bandwidth consumption per user
to 100 MB over a time period of one hour, by using a custom header that provides the user name. In
both cases, the tracking of bandwidth consumption over a moving time period of one hour is achieved
by setting the interval parameter in the stream identifier to 60 minutes. The use cases also demon-
strate how you can import an HTML page to send to a client that has exceeded the limit. Importing an
HTML page not only simplifies the configuration of the responder action in these use cases, but also
simplifies the configuration of all responder actions that need the same response.

To limit bandwidth consumption per user or client device by using the command line interface

In the command-line interface, perform the following tasks to configure action analytics for limiting a
client’s or user’s bandwidth consumption. Each step includes sample commands and their output.

1. Set up your load balancing configuration. Configure load balancing virtual server mysitevip,
and then configure all the services that you need. Bind the services to the virtual server. The
following example creates ten services and binds the services to mysitevip.

1 > add lb vserver mysitevip HTTP 192.0.2.17 80

2 Done
3 > add service service[1-10] 192.0.2.[240-249] HTTP 80
4 service ”service1” added
5 service ”service2” added
6 service ”service3” added

© 1999-2018 Citrix Systems, Inc. All rights reserved. 980

NetScaler 12.0

7 .
8 .
9 .
10 service ”service10” added
11 Done
12 > bind lb vserver vserver1 service[1-10]
13 service ”service1” bound
14 service ”service2” bound
15 service ”service3” bound
16 .
17 .
18 .
19 service ”service10” bound
20 Done

2. Configure the stream selector. Configure one of the following stream selectors:

• To limit bandwidth consumption per client, configure a stream selector that identifies the
client IP address.

1 > add stream selector myselector CLIENT.IP.SRC

2 Done

• To limit bandwidth consumption per user on the basis of the value of a request header
that provides the user name, configure a stream selector that identifies the header. In the
following example, the name of the header is UserHeader.

1 > add stream selector myselector HTTP.REQ.HEADER( “ UserHeader

”)
2 Done

3. Configure a stream identifier. Configure a stream identifier that uses the stream selector. Set
the interval parameter to 60 minutes.

1 > add stream identifier myidentifier myselector -interval 60 -

sampleCount 1 -sort BANDWIDTH
2 Done

4. Configure the responder action. Import the HTML page that you want to send to users or
clients that have exceeded the bandwidth consumption limit, and then use the page in respon-
der action crossed_limits.

1 > import responder htmlpage http://192.0.2.20:80/stdpages/wait.

html crossed-limits.html
2 This operation may take some time, Please wait...

© 1999-2018 Citrix Systems, Inc. All rights reserved. 981

NetScaler 12.0

3
4 Done
5 > add responder action crossed_limits respondwithhtmlpage crossed-
limits.html
6 Done

5. Configure the responder policies. Configure responder policy myrespol1 with the rule ANA-
LYTICS.STREAM(“myidentifier”).COLLECT_STATS and the action NOOP. Then, configure policy
myrespol2 for determining whether a client or user has crossed the 100 MB limit. The policy
myrespol2 is configured with the responder action crossed_limits.

1> add responder policy myrespol1 ’ANALYTICS.STREAM(”myidentifier”)

.COLLECT_STATS’ NOOP
2 Done
3 > add responder policy myrespol2 ’ANALYTICS.STREAM(”myidentifier”)
.BANDWIDTH.GT(1048576)’ crossed_limits
4 Done

6. Bind the responder policies to the load balancing virtual server. The policy myrespol1, which
only collects statistical data, must have the higher priority and a GOTO expression of NEXT.

1> bind lb vserver mysitevip -policyName myrespol1 -priority 1 -

gotoPriorityExpression NEXT
2 Done
3 > bind lb vserver mysitevip -policyName myrespol2 -priority 2 -
gotoPriorityExpression END
4 Done

7. Test the configuration. Test the configuration by sending test HTTP requests, from multiple
clients or users, to the load balancing virtual server and using the stat stream identifier com-
mand to view the statistics that are collected for the specified identifier. The following output
displays statistics for clients.

1 > stat stream identifier myidentifier -sortBy BandW ‒ fullValues

2 Stream Session statistics
3 Req BandW
4 192.0.2.30 5000 3761
5 192.0.2.31 29 2602
6 192.0.2.32 25 51
7
8 RspTime Conn
9 192.0.2.30 2 0
10 192.0.2.31 0 0
11 192.0.2.32 0 0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 982

NetScaler 12.0

12 Done
13 >

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

AppExpert applications and templates

September 24, 2018

Contributed by:
C

An AppExpert application is a collection of configuration information that you set up on the NetScaler
appliance for securing and optimizing traffic for a Web application, such as Microsoft SharePoint. Man-
aging AppExpert applications is simplified by a graphical user interface (GUI) that allows you to specify
application traffic subsets and a distinct set of security and optimization policies for processing each
traffic subset. Additionally, it consolidates all deployment tasks in one view, so you can quickly con-
figure target IP addresses for clients and specify host servers.

Prebuilt application templates for widely used Web applications, such as Microsoft Outlook Web Ac-
cess and Microsoft SharePoint, are available on the AppExpert Templates page of the Citrix Commu-
nity website at “http://community.citrix.com/display/ns/AppExpert+Templates.”

Each prebuilt template provides you with an initial configuration for managing the associated Web
application. You can customize prebuilt application templates for your organization. If a prebuilt
application template does not suit your requirements, you can create a custom application without
using a template.

Regardless of whether you use a prebuilt application template or you create a custom application,
you can export the configuration to a template file. You can then share the template with other ad-
ministrators or import the template to other NetScaler appliances that require a similar AppExpert
application configuration.

To get started with an AppExpert application, you must first obtain the appropriate application tem-
plate and import the template to the NetScaler appliance. After the AppExpert application is set up,
you must verify that the application is working correctly. If required, you can customize the configu-
ration to suit your requirements.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 983

NetScaler 12.0

Periodically, you can verify and monitor the configuration by viewing the hit counters for various appli-
cation components, statistics, and the Application Visualizer. You can also configure authentication,
authorization, and auditing (AAA) policies for the application.

AppExpert application terminology

Following are the terms used in the AppExpert applications feature and the descriptions of the entities
for which the terms are used:

Public endpoint. The IP address and port combination at which the NetScaler appliance receives
client requests for the associated web application. A public endpoint can be configured to receive
either HTTP or secure HTTP (HTTPS) traffic. All client requests for the web application must be sent
to a public endpoint. An AppExpert application can be assigned multiple endpoints. You configure
public endpoints after you import a template.

Application unit. An AppExpert application entity that processes a subset of web application traffic
and load balances a set of services that host the associated content. The subset of traffic that an appli-
cation unit must manage is defined by a rule. Each application unit also defines its own set of traffic
optimization and security policies for the requests and responses that it manages. The NetScaler ser-
vices associated with these policies are Compression, Caching, Rewrite, Responder, and application
firewall.

By default, every AppExpert application with at least one application unit includes a default applica-
tion unit, which cannot be deleted. The default application unit is not associated with a rule for iden-
tifying requests and is always placed last in the order of application units. It defines a set of policies
for processing any request that does not match the rules that are configured for the other application
units, thereby ensuring that all client requests are processed.

Application units and their associated rules, policies, and actions are included in AppExpert applica-
tion templates.

Service. The combination of the IP address of the server that hosts the web application instance and
the port to which the application is mapped on the server, in the format <IP address>:<Port>. A web
application that serves a large number of requests is usually hosted on multiple servers. Each server
is said to host an instance of the web application, and each such instance of the web application is rep-
resented by a service on the NetScaler appliance. Services are deployment-specific and are therefore
not included in templates. You must configure services after you import a template.

Application unit rule. Either a classic expression or a default syntax expression that defines the char-
acteristics of a traffic subset for an application unit. The following example rule is a default syntax
expression that identifies a traffic subset that consists of four image types:

HTTP.REQ.URL.SUFFIX.EQ(“bmp”)
HTTP.REQ.URL.SUFFIX.EQ(“gif”)
HTTP.REQ.URL.SUFFIX.EQ(“png”)
HTTP.REQ.URL.SUFFIX.EQ

© 1999-2018 Citrix Systems, Inc. All rights reserved. 984

NetScaler 12.0

For more information about default syntax expressions and classic policy expressions, see Policies
and Expressions.

Traffic Subset. A set of client requests that require a common set of traffic optimization and security
policies. A traffic subset is managed by an application unit and is defined by a rule.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

How AppExpert Application Works

January 6, 2019

Contributed by:
C

When the endpoint receives a client request, the NetScaler appliance evaluates the request against the
rule that is configured for the topmost application unit. If the request satisfies this rule, the request is
processed by the policies that are configured for the application unit, and then forwarded to a service.
The choice of service depends on which services are configured for the application, and on settings
such as the load balancing algorithm and persistence method configured for the application unit.

If the request does not satisfy the rule, the request is evaluated against the rule for the next topmost
application unit. In this order, the request is evaluated against each application unit rule until the
request satisfies a rule. If the request does not satisfy any of the configured rules, it is processed by
the default application unit, which is always the last application unit.

You can configure multiple public endpoints for an AppExpert application. In such a configuration,
by default, each application unit processes requests received by all the public endpoints and load
balances all the services that are configured for the application. However, you can specify that an
application unit processes traffic from only a subset of the public endpoints and load balances only a
subset of the services that are configured for the AppExpert application.

The following flow diagram illustrates the AppExpert Application flow sequence for using a built-in
application template.

If you prefer to create a customized application without using a template, do the following:

1. Create a custom application.

2. Configure application and deployment settings.
3. Export the configuration to new template files (optional).

© 1999-2018 Citrix Systems, Inc. All rights reserved. 985

NetScaler 12.0

4. Import the template files to other NetScaler appliances that require a similar AppExpert appli-
cation configuration

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Get started with AppExpert

September 24, 2018

Contributed by:
C

To get started with an AppExpert application, you must first obtain an application template and im-
port the template to a NetScaler appliance. After the AppExpert application is set up, you must verify
that the application is working correctly. If required, you can customize the configuration to suit your
requirements.

Periodically, you can verify and monitor the configuration by viewing the hit counters for various appli-
cation components. You can also configure authentication, authorization, and auditing (AAA) policies
for the application.

The process of setting up an application can be done in two ways:

• Using a prebuilt application template

• Creating a custom application without using a template.

If you prefer to set up the application by using a prebuilt application template, do the following:

1. Download an application template.

2. Import template files to NetScaler appliance.
3. Verify application setup.
4. Configure application and deployment settings.
5. Export the configuration to new template files (optional).
6. Import the template files to other NetScaler appliances that require a similar AppExpert appli-
cation configuration.

NetScaler’s video tutorials enable you to understand NetScaler features in easy and simple way. Watch
https://www.youtube.com/watch?v=aqayflvCR_0 video to learn how to set up an application using
AppExpert Application template.

1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 986

NetScaler 12.0

2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Downloading an Application Template

September 24, 2018

Contributed by:
C

AppExpert application setup begins with downloading an application template from the Citrix Com-
munity Web site at http://community.citrix.com/display/ns/AppExpert+Templates to your local com-
puter or NetScaler appliance. The application templates are designed to be imported and exported,
so that you can easily share application-specific configurations within an organization or across orga-
nizations. An application template includes the following set of entities:

1. Application components (for example, web pages, files, archives, and web services)
2. Traffic management entities (for example, virtual server IP addresses and associated load-
balancing algorithms, and SSL offload settings) for the application components.
3. NetScaler policies used for optimizing the application traffic.

Note: Application templates are available in different versions for configuring different types of
NetScaler appliances.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Importing an Application Template

September 24, 2018

Contributed by:
C

For NetScaler software version 9.3 or later, each AppExpert template has two XML files: a Template file
and a Deployment file. You must import both files from your local computer to a NetScaler appliance.
You can either import the template files from your computer to the AppExpert application templates

© 1999-2018 Citrix Systems, Inc. All rights reserved. 987

NetScaler 12.0

directory in NetScaler appliance or upload files to a NetScaler appliance and then import them from
the appliance.

Note: When you import a template from an appliance, you have to provide the variable value
available in the template. By default, the pre-configured value is display https://docs.citrix.
com/en-us/netscaler//11/appexpert/appexpert-application-templates/creating-
managing-templates/netscaler-application-template-deployment-files.html

After you import the template files, the application-configuration and deployment information popu-
lates the target application automatically. The appliance imports all the configuration from the tem-
plate files through the NITRO API. If you do not import the deployment file, the system generates an ap-
plication populated with content switching virtual server configuration. For more information about
the format of application templates and deployment files, see Understanding NetScaler Application
Templates and Deployment Files.

When you import a template, if you do not include a deployment file, you have to configure the public
endpoints in the application that the system automatically generates from the template. One end-
point for HTTP and another endpoint for HTTPS. When configuring a public endpoint of type HTTPS,
make sure you enable the SSL feature, bind the server certificate, and include the server-certificate
and certificate-key files.

For more information about configuring endpoints after you import a template, see Configuring Public
Endpoints.

To import AppExpert application template files to a NetScaler appliance by using the GUI:

1. Navigate to AppExpert > Applications.

2. In the details pane, click Import Template.
3. On the Import page, set the following parameters:
a) Application Name (mandatory)
b) Template File (mandatory)
c) Use deployment file
4. Click Continue to auto populate application-configuration and deployment information into an
application.

NetScaler’s video tutorials enable you to understand NetScaler features in an easy and simply way.
Watch https://www.youtube.com/watch?v=AR9TwSD9uJM video to learn how to import an applica-
tion template.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 988

NetScaler 12.0

Verifying and Testing Application Configuration

January 6, 2019

Contributed by:
C

The GUI includes icons that indicate the states of the entities in the AppExpert application. These
icons are displayed for applications and application units and are based on the health checks that the
NetScaler appliance performs periodically on services and entities. The following table lists the icons
and describes their meanings.

Icon Entity Indicates that

Application At least one public endpoint is

up. The application will
accept client requests from
the public endpoints that are
up.
Application unit The application unit is up.
The application unit is up
when at least one service or
service group is up.
Application The public endpoint is out of
service (disabled). This
indicator is displayed when
only one public endpoint is
configured for the AppExpert
application.
Application All the endpoints that are
configured for the application
are out of service. This
indicator is displayed only
when multiple endpoints are
configured for the
application.
Application unit All the services configured for
the application unit are down.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 989

NetScaler 12.0

You must ensure that the icons for each application and its application units are green at all times. If
the icon that is displayed for an application is not green, verify that you have configured the public
endpoints correctly. If the icon that is displayed for an application unit is not green, verify that the
services are configured correctly. However, note that a green indicator does not mean that the state
of all associated entities is UP. It only means that the application has sufficient resources (endpoints
and services) to serve client requests. To verify that the state of all associated entities is UP, check the
health of all the entities on the statistics page for the application.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Customizing the configuration

September 24, 2018

Contributed by:
C

After you verify that the AppExpert application is working correctly, you can customize the configura-
tion to suit your requirements.

After you verify that the AppExpert application configuration is working correctly, you can configure
the application and the deployment settings to suit your requirements. When you import an applica-
tion template and deployment file, the system automatically populates the target application with the
available configuration settings (such as application units, application unit rules, policies, persistence
settings, load balancing methods, profiles, and traffic settings). In this application, you can configure
deployment settings such as public endpoints, services, and service groups for each traffic subset. If
you want the AppExpert application to manage a traffic subset that is not included in the template,
you can either add an application unit for a traffic subset or modify the existing application unit. After
you customize the configuration, you can also specify the order of evaluation for each traffic subset
that the application manages.

Configuring an AppExpert application consists of the following steps:

1. Configuring Public Endpoints

2. Configuring Application Units
3. Specifying the Order of Evaluation
4. Viewing Application Configuration using Visualizer

Also, you can configure the policies that the template provided. If the AppExpert application template

© 1999-2018 Citrix Systems, Inc. All rights reserved. 990

NetScaler 12.0

does not include policies for a particular NetScaler feature, such as Rewrite or application firewall, you
can configure your own policies.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configure public endpoints

September 24, 2018

Contributed by:
C

If you did not specify a public endpoint when importing an AppExpert application, you can specify
public endpoints after you create the application. You can configure one public endpoint of type HTTP
and one public endpoint of type HTTPS for your AppExpert application.

If endpoints are already configured for the application, you can dissociate endpoints from the AppEx-
pert application and delete any endpoints that you no longer need. Note that when you dissociate
a public endpoint from the AppExpert application, the endpoint is automatically unbound from the
associated application unit, but it is not deleted from the system.

To configure public endpoints for an AppExpert application:

1. Navigate to AppExpert > Applications.

2. In the details pane, right-click the application for which you want to configure public endpoints,
and then click Edit.
3. In the Applications page, go to Public Endpoint section and click the pencil icon.
4. In the Public Endpoint slider, set the following parameters.
a) Public endpoint type. Select the radio button to define the endpoint type.
b) Name. Name of the public endpoint.
c) IP address. IP address of the public endpoint.
d) Port. Port number of the public endpoint.
e) Protocol. Select a protocol type as HTTP or HTTPS.
5. Click Continue.
6. In the Application Units section, select an application unit from the list.
7. Click Continue to set the policy and server details.
8. Click OK and then Done.
9. Click Close.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 991

NetScaler 12.0

For more information about the parameters in the Configure Public Endpoint dialog box, see Content
Switching.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configure services and service groups for an application unit

September 24, 2018

Contributed by:
C

When you configure a service or service group, you either modify an existing service or service group,
or add new services to the AppExpert application. You add services or service groups if you did not
specify them when you imported the application template. You also add services and service groups
when you increase the number of servers that host instances of the application. You can configure a
service and service group for an application unit only after you configure the service or service group
for the AppExpert application.

To configure a service or service group for the AppExpert application:

1. Navigate to AppExpert > Applications.

2. In the details pane, right-click the application and then click Edit.
3. In the Applications page, select an application unit and then click Continue.
4. In the Services and Service Groups section, do the following:
a) In the Service Binding slider, set the following parameters.
i. Service. Select a load balancing service from the list or create a new service.
ii. Weight. Provide a weight value for the service.
b) Click Bind and then Done.
c) In the ServiceGroup Binding slider, set the following parameters:
i. Service Group Name. Select a load balancing service group or create a new service
group.
ii. Click Bind and then Done.
d) Click Done.
5. Click Continue to set other configurations.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 992

NetScaler 12.0

4. AppExpert

Create application units

September 24, 2018

Contributed by:
C

You might need to add application units for traffic subsets that are either specific to your web appli-
cation implementation or not defined in the template. When creating an application unit, you must
configure a rule for the application unit.

To create an application unit for the AppExpert application:

1. Navigate to AppExpert > Applications.

2. In the details pane, right-click the application for which you want to add an application unit,
and then click Add.
3. In the Applications page, go to Application Units section and click the pencil icon.

To configure policy expressions for an application unit:

1. Navigate to AppExpert > Applications.

2. In the details pane, right-click the application for which you want to add an application unit,
and then click Add.
3. In the Applications **page, go to Application Units** section and click the **+ **icon. to create
a unit and add policy expressions.
4. To specify the format of the new expression, do one of the following:
a) To specify that you want to configure a classic expression in the Rule box, click Classic
Syntax.
b) To specify that you want to configure an advanced expression in the Rule box, click Default
Syntax.
c) In the Rule box, configure the expression.
5. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 993

NetScaler 12.0

Configuring application unit rules

September 24, 2018

Contributed by:
C

You might want to configure an application unit rule to include or exclude certain types of traffic. When
you configure the rule, you can also define the syntax of the expression.

To configure an application unit rule:

1. In the navigation pane of the GUI, expand AppExpert, and then click Applications.
2. In the details pane, right-click the application unit for which you want to modify the rule, and
then click Open.
3. In the Configure Application Unit dialog box, do the following:
a) To specify the format of the new expression, do one of the following:
• To specify that you want to configure a classic expression in the Rule box, click Classic
Syntax.
• To specify that you want to configure an advanced expression in the Rule box, click
Default Syntax.
b) In the Rule box, configure the expression.
4. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring policies for application units

September 24, 2018

Contributed by:
C

For an AppExpert application, you can configure policies for Compression, Caching, Rewrite, Respon-
der, and Application Firewall. The templates that you download from the Citrix Community web site
provide you with a set of policies that fulfill the most common application management requirements.
You might want to fine-tune or customize these policies. If the set of policies provided for a given ap-

© 1999-2018 Citrix Systems, Inc. All rights reserved. 994

NetScaler 12.0

plication unit does not include policies for a particular feature, you can create and bind your own
policies for that feature.
If you create an AppExpert application without using a template, you must configure all the policies
that the web application needs.
The GUI uses various icons to indicate whether or not policies are configured for a feature. For an
application unit, if a policy is configured for a given feature, an icon that represents the feature is
displayed. For example, if a compression policy is configured for an application unit, a compression
icon is displayed in the Compression column for the application unit. For features for which no policy
is configured, an icon depicting a plus sign (+) is displayed.
Note: When configuring policies for application units, you might need to configure policies and ex-
pressions that are either in the classic or
default syntax. Additionally, when you configure
default syntax policies, you might need to specify parameters such as Goto expressions and invoke
policy banks.
For information about configuring policies and expressions in both formats, see Policies and Expres-
sions.

Configuring compression policies

You can use either classic policies or advanced policies to configure compression, but you cannot bind
compression policies of both types to the same application unit.
To configure a compression policy for an application unit:
1. Navigate to AppExpert > Applications.
2. In the details pane, in the row for the application unit you want to configure, click the icon pro-
vided in the Compression column.
3. In the Configure Compression Policies dialog box, do one or more of the following, depending
on the configuration tasks you want to perform:
• Click Switch to Default Syntax if you want to configure a default syntax compression policy.
If you want to bind or configure classic compression policies, and if you are in the default
syntax view, you can click Switch to Classic Syntax to return to the classic policy view and
begin modifying bound classic policies or create and bind new classic compression poli-
cies.
Important: This setting also determines what policies are displayed when you want to in-
sert a policy. For example, if you are in the
default syntax view, when you click
Insert Policy, the list that appears in the
Policy Name column will include only
default syntax policies. You cannot bind policies of both types to an application unit.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 995

NetScaler 12.0

• If you want to configure classic policies, click either Request or Response, depending on
whether you want the policy to be evaluated at request-time or at response-time.
You can configure both request-time and response-time classic compression policies for
an application unit. After evaluating all of the request-time policies, if no match is found,
the appliance evaluates response-time policies.
• To modify a compression policy that is already bound to the application unit, click the
name of the policy, and then click Modify Policy. Then, in the Configure Compression Pol-
icy dialog box, modify the policy, and then click OK.
For information about modifying a compression policy, see Compression.
• To unbind a policy, click the name of the policy, and then click Unbind Policy.
• To modify the priority assigned to a policy, double-click the priority value, and then enter
a new value.
• To regenerate assigned priorities, click Regenerate Priorities.
• To insert a new policy, click Insert Policy and, in the list that is displayed in the Policy
Name column, click New Policy. Then, in the Create Compression Policy dialog box,
configure the policy, and then click Create.
For information about modifying a compression policy, see Compression.
• If you are configuring a default syntax expression, do the following:
– In the Goto Expression column, select a Goto expression.
– In the Invoke column, specify the policy bank that you want to invoke if the current
policy evaluates to TRUE.
4. Click Apply Changes, and then click Close.

Configuring Caching Policies

You can use only default syntax policies and expressions to configure Caching policies.

To configure Caching policies for an application unit:

1. Navigate to AppExpert > Applications.

2. In the details pane, in the row for the application unit you want to configure, click the icon pro-
vided in the Caching column.
3. In the Configure Cache Policies dialog box, do one or more of the following, depending on the
configuration tasks you want to perform:
• Click either Request or Response, depending on whether you want the policy to be evalu-
ated at request-time or at response-time.
You can configure both request-time and response-time Caching policies for an applica-
tion unit. After evaluating all of the request-time policies, if no match is found, the appli-
ance evaluates response-time policies.
• To modify a Caching policy that is already bound to the application unit, click the name of
the policy, and then click Modify Policy. Then, in the Configure Cache Policy dialog box,

© 1999-2018 Citrix Systems, Inc. All rights reserved. 996

NetScaler 12.0

modify the policy, and then click OK.

For information about modifying a Caching policy, see Integrated Caching.
• To unbind a policy, click the name of the policy, and then click Unbind Policy.
• To modify the priority assigned to a policy, double-click the priority value, and then enter
a new value.
• To regenerate assigned priorities, click Regenerate Priorities.
• To insert a new policy, click Insert Policy and, in the list that is displayed in the Policy
Name column, click New Policy. Then, in the Create Cache Policy dialog box, configure
the policy, and then click Create.
For information about modifying a Caching policy, see Integrated Caching.
• In the Goto Expression column, select a Goto expression.
• In the Invoke column, specify the policy bank that you want to invoke if the current policy
evaluates to TRUE.
4. Click Apply Changes, and then click Close.

Configuring Rewrite policies

You can use only default syntax policies and expressions to configure Rewrite policies.

To configure Rewrite policies for an application unit:

1. Navigate to AppExpert > Applications.

2. In the details pane, in the row for the application unit you want to configure, click the icon pro-
vided in the Rewrite column.
3. In the Configure Rewrite Policies dialog box, do one or more of the following, depending on
the configuration tasks you want to perform:
• Click either Request or Response, depending on whether you want the policy to be evalu-
ated at request-time or at response-time.
You can configure both request-time and response-time Rewrite policies for an application
unit. After evaluating all of the request-time policies, if no match is found, the appliance
evaluates response-time policies.
• To modify a Rewrite policy that is already bound to the application unit, click the name of
the policy, and then click Modify Policy. Then, in the Configure Rewrite Policy dialog box,
modify the policy, and then click OK.
For information about modifying a Rewrite policy, see Rewrite.
• To unbind a policy, click the name of the policy, and then click Unbind Policy.
• To modify the priority assigned to a policy, double-click the priority value, and then enter
a new value.
• To regenerate assigned priorities, click Regenerate Priorities.
• To insert a new policy, click Insert Policy and, in the list that is displayed in the Policy
Name column, click New Policy. Then, in the Create Rewrite Policy dialog box, configure

© 1999-2018 Citrix Systems, Inc. All rights reserved. 997

NetScaler 12.0

the policy, and then click Create.

For information about modifying a Rewrite policy, see Rewrite.
• In the Goto Expression column, select a Goto expression.
• In the Invoke column, specify the policy bank that you want to invoke if the current policy
evaluates to TRUE.
4. Click Apply Changes, and then click Close.

Configuring Responder policies

You can use only default syntax policies and expressions to configure Responder policies.

To configure Responder policies for an application unit:

1. Navigate to AppExpert > Applications.

2. In the details pane, in the row for the application unit you want to configure, click the icon pro-
vided in the Responder column.
3. In the Configure Responder Policies dialog box, do one or more of the following, depending
on the configuration tasks you want to perform:
• To modify a Filter policy that is already bound to the application unit, click the name of
the policy, and then click Modify Policy. Then, in the Configure Responder Policy dialog
box, modify the policy, and then click OK.
For information about modifying a Responder policy, see Responder.
• To unbind a policy, click the name of the policy, and then click Unbind Policy.
• To modify the priority assigned to a policy, double-click the priority value, and then enter
a new value.
• To regenerate assigned priorities, click Regenerate Priorities.
• To insert a new policy, click Insert Policy and, in the list that is displayed in the Policy
Name column, click New Policy. Then, in the Create Responder Policy dialog box, con-
figure the policy, and then click Create.
For information about modifying a Responder policy, see Responder.
• In the Goto Expression column, select a Goto expression.
• In the Invoke column, specify the policy bank that you want to invoke if the current policy
evaluates to TRUE.
4. Click Apply Changes, and then click Close.

Configuring Application Firewall policies

You can configure both classic and default syntax policies and expressions for Application Firewall.
However, if a policy of one type is already bound globally or to a virtual server that is configured on
the appliance, you cannot bind a policy of the other type to an application unit. For example, if a

© 1999-2018 Citrix Systems, Inc. All rights reserved. 998

NetScaler 12.0

default syntax policy is already bound either globally or to a virtual server, you cannot bind a classic
policy to an application unit.

To configure Application Firewall policies for an application unit:

1. Navigate to AppExpert > Applications.

2. In the details pane, in the row for the application unit you want to configure, click the icon pro-
vided in the Application Firewall column.
3. In the Configure Application Firewall Policies dialog box, do one or more of the following,
depending on the configuration tasks you want to perform:
• Click either Classic Expression or Advanced Expression depending on the type of expres-
sion you want to configure for the Application Firewall policy.
Important: This setting also determines what policies are displayed when you want to
insert a policy. For example, if you select
Advanced Expression, when you click
Insert Policy, the list that appears in the
Policy Name column will include only
default syntax policies. You cannot bind policies of both types to an application unit. This
option is not available if a policy of either type is already bound either globally or to a
virtual server.
• To modify an application firewall policy that is already bound to the application unit, click
the name of the policy, and then click Modify Policy. Then, in the Configure Application
Firewall Policy dialog box, modify the policy, and then click OK.
For information about modifying a application firewall policy, see Policies.
• To unbind a policy, click the name of the policy, and then click Unbind Policy.
• To modify the priority assigned to a policy, double-click the priority value, and then enter
a new value.
• To regenerate assigned priorities, click Regenerate Priorities.
• To insert a new policy, click Insert Policy and, in the list that is displayed in the Policy
Name column, click New Policy. Then, in the Create Application Firewall Policy dialog
box, configure the policy, and then click Create.
For information about modifying a application firewall policy, see Policies.
4. Click Apply Changes, and then click Close.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 999

NetScaler 12.0

Configuring Application Units

September 24, 2018

Contributed by:
C
To configure an application unit by using the GUI:
1. Navigate to AppExpert > Applications > Application Unit section and then click the plus icon
to add a new application unit for a traffic subset.
2. In the Application Unit slider, set the following parameters:
• Name
• Expression
You can insert an expression either by adding the expression components manually or by using
the Expression Editor link. To manually add an expression, enter a selector component and then
type a period (.) to display a list from which you can select the next component. For example,
type HTTP and then type a period. A drop-down menu appears. The contents of this menu
provide the keywords that can follow the initial keyword that you entered. Select a component
from the drop-down menu. The Expression* text box now displays the components that you
have added to the expression (for example, HTTP.REQ). Continue adding components until the
complete expression is formed.
If you prefer assistance to form the expression, you can use the Expression Editor link. On the
Expression Editor page, you can form an expression by selecting components from the drop-
down boxes. Select the components and click Done to insert the expression on the Application
Unit page.
3. Click Continue to bind services and service groups.
4. Click the Service section to select or add a virtual service and bind it to the application unit.
5. Click Continue and click the Service Group section to select or add a virtual service group and
bind it to the application unit.
6. Click Bind and Continue to configure Advanced Settings (such as Policies, Method, Persistence,
Protection, Profiles, Push, Authentication, and Traffic Settings) for the application unit.
7. Click the plus icon in each section to set the configuration parameters.
8. Click OK and then Done.
To edit an application unit for an application by using the GUI:
Navigate to AppExpert > Applications, select an application and click Edit. In the Application Unit
section, select an entity, click the edit icon and modify the application unit settings.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1000

NetScaler 12.0

Note: You cannot modify the name and rule expression for an existing application unit.
NetScaler’s video tutorials enable you to understand NetScaler features in an easy and simple way.
Watch <https://www.youtube.com/watch?v=bJ5_i8fV2hc> video to learn how configure an
application unit.
1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring public endpoints for an application

September 24, 2018

Contributed by:
C
To configure public endpoints for an application by using the GUI:
1. Navigate to AppExpert > Applications, select an application entity, and then click Edit.
2. In the Public Endpoint section, click + to configure a new public endpoint.
3. In the Public Endpoint slider, do one of the following:
a) Click New to create a new endpoint.
b) Click Existing Public Endpoint to select an endpoint from the drop-down list.
4. Set the following endpoint parameters:
a) Name
b) IP address
c) Protocol
d) Port
5. Click Continue to configure additional settings such as application units, GSLB server bindings,
policies, profiles, push, traffic settings, and authentication.
6. Click OK and then Done.
7. Click Continue and then Done.
To edit a public endpoint for an application by using the GUI:
Navigate to AppExpert > Applications, select an application, and click Edit. In the Public Endpoint
section, select an endpoint, click the pen icon, and modify the endpoint settings.
To delete a public endpoint for an application by using the GUI:
Navigate to AppExpert > Applications > Public Endpoint, click the pen icon to view the delete icon
next to the entity.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1001

NetScaler 12.0

NetScaler’s video tutorials enable you to understand NetScaler features in an easy and simply way.
Watch <https://www.youtube.com/watch?v=z4v-edQiVpw> video to learn how to configure a
public endpoint.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Specifying the Order of Evaluation of Application Units

September 24, 2018

Contributed by:
C

Application unit rules are evaluated in the order in which they are placed in the GUI. The rule that
is configured for the topmost application unit is always configured first, followed by the rule that is
configured for the second topmost application unit, and so on. The default application unit is always
evaluated last.

When a request matches the rule that is configured for an application unit, the request is processed
by the application unit, and no further matching is performed. Therefore, the order of evaluation of
application units becomes an important factor if the traffic subsets for two or more application units
overlap. If the traffic subsets for two or more application units overlap, you must specify the order in
which an incoming request is matched against the application unit rules.

To specify the order of evaluation of application units:

1. Navigate to AppExpert > Applications, select an application and click Edit. In the Application
Unit section, click the Pencil icon and then hover the cursor over the check box to the left of the
name of the application unit. Click the icon that appears next to the check box and hold down
the mouse to drag the application up or down to a new location in the priority list.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1002

NetScaler 12.0

Configuring Persistency Groups for Application Units

September 24, 2018

Contributed by:
C

You can configure a persistency group for the application units in an AppExpert application. In the
context of an AppExpert application, a persistency group is a group of application units that you can
treat as a single entity for the purpose of applying common persistence settings. When the application
is exported to an application template file, the persistency group settings are included, and they are
automatically applied to the application units when you import the AppExpert application.

To configure a persistency group for an application by using the GUI:

1. Navigate to AppExpert > Applications.

2. In the Applications View dialog box, click the name of the application for whose application
units you want to configure a persistency group, and then click Configure Persistency Groups.
3. In the Configure Persistency Groups dialog box, do one of the following:
• To add a persistency group, click Add.
• To modify a persistency group, click Open.
4. In the Create Persistency Group or Configure Persistency Group dialog box, set the following
parameters:
• Group Name—Name of the persistency group. For the NetScaler appliance to recognize
the persistency group as part of the application’s configuration, the name of the AppEx-
pert application must be included in the name of the persistency group, as a prefix. There-
fore, by default, the appliance displays the prefix in the Group Name box, and you cannot
remove that prefix. Enter a name of your choice after the prefix.
• Persistence—Type of persistence for the virtual server. If you select SOURCEIP, in the IPv4
Netmask box, enter a network mask that specifies the number of bits that the appliance
must consider when creating persistence sessions. If you select COOKIEINSERT, in the
Cookie Domain and Cookie Name boxes, specify a domain attribute to send in the Set-
Cookie directive, and a name for the cookie, respectively.
• Timeout—Time period for which a persistence session is in effect.
• Backup Persistence—Type of backup persistence for the group.
• Backup Timeout—Time period, in minutes, for which backup persistence is in effect.
• Application Units—To add an application unit to the persistency group, in the Available
Application Units box, click the application unit, and then click Add. To remove an appli-
cation unit from the persistency group, in the Configured Application Units box, click the
application unit, and then click Remove.
5. Click OK.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1003

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Viewing AppExpert Applications and Configuring Entities by Using the

Application Visualizer

September 24, 2018

Contributed by:
C

The Visualizer feature shows you a graphical representation of an application’s configuration. It in-
cludes the name of the public endpoint, application units assigned to the public endpoint, and the
number of policies and services bound to the application. You can use the Visualizer to obtain a visual
overview of an AppExpert application’s configuration and configure some of the displayed entities. By
default, the Visualizer displays application units, services, and monitors for the selected application.

To view an AppExpert application by using the Application Visualizer:

1. Navigate to AppExpert > Applications, select an application entity, and click Visualizer.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring User Authentication, Authorization, and Auditing

September 24, 2018

Contributed by:
C

You can configure authorization for users and groups to enable then to access an AppExpert appli-
cation. If the AAA user or group for which you want to configure permissions has not already been
created, you can create it from AppExpert and then configure permissions for application access.

To configure AAA users and AAA user groups for an application by using the configuring utility

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1004

NetScaler 12.0

1. Navigate to AppExpert > Applications, select an application entity, and then click Edit.
2. In the Advanced Settings section, click Authorization, and configure authorized users and user
groups.
3. Click the AAA user section to bind authorized users to the application.
4. In the AAA User slider, set the parameters .
5. Click Continue, and then click Authorization Policies in the Advanced Settings section.
6. In the Authorization Policy slider, bind an authorization policy to the application.
7. Click Continue, and then click the Authorization Group section in the Advanced Settings sec-
tion.
8. In the AAA Group Binding slider, bind an authorization user group to the application.
9. Click Continue, and then click Policies in the Advanced Settings section.
10. In the Policies **slider, bind an **Audit Syslog or** Audit NSlog** policy to the application.
11. Click Continue and then Done.

To edit AAA users and AAA user groups for an application by using the GUI:

Navigate to AppExpert > Applications > Advanced Settings and click Authorization. Then click the
edit icon and specify values for user or user-group authorization settings.

To delete AAA users and AAA user groups by using the GUI:

Navigate to AppExpert > Applications, select an application and click Edit. In the Applications page,
click Advanced Settings and click Authorization. Click the delete icon next to the entity.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Monitoring a NetScaler Application

September 24, 2018

Contributed by:
C

After you customize the AppExpert application, you can view application statistics to make sure that
the application and all its entities are working correctly. You can also use the Application Visualizer to
monitor statistics associated with certain entities such as policies and virtual servers.

You can also view the hit counters for various entities at regular intervals to make sure that counters
are being updated.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1005

NetScaler 12.0

Viewing Application Statistics

In the Applications node, you can select an application and view the Statistics page for the applica-
tion. On the Statistics page, you can monitor the health and states of public endpoints and application
units, and view the following statistical information:

• Requests and responses per second for each of the public endpoints and application units.
• Bytes per second, at each endpoint, for incoming and outgoing traffic.
• Application unit hit counters and the number of client and server connections for each applica-
tion unit.
• Statistics for the services that are bound to the application units.

On the Statistics page, you can also view CPU usage, memory usage, and system logs.

To view statistics for an application:

1. Navigate to AppExpert > Applications.

2. In the details pane, click the application for which you want to view statistics, and then click
Statistics.

Monitoring an Application by Using the Application Visualizer

You can use the Application Visualizer to monitor the number of requests received per second at a
given point in time by the vservers and the number of hits per second at a given point in time for
Rewrite, Responder, and Cache policies.

To view statistical information for vservers, Rewrite policies, Responder policies, and Cache policies
in the Visualizer:

1. Navigate to AppExpert > Applications.

2. In the details pane, select the application for which you want to view statistical information, and
then click Visualizer.
3. In the Application Visualizer window, do the following:
• To view the statistics, click Show Stats.
The statistical information is displayed on the respective nodes in the Visualizer. This in-
formation is not updated in real time and has to be refreshed manually.
• To refresh the statistical information, click Refresh Stats.

Viewing Hits

The hit counters that are provided for various AppExpert application entities enable you to monitor the
functioning of public endpoints and application units. For an application, the Hits dialog box displays
the total number of requests received by each configured public endpoint. For an application unit,

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1006

NetScaler 12.0

the Hits dialog box displays the number of requests that the application unit processed from each of
the public endpoints and the total hit count. For instructions on viewing hit counters, see Verifying
and Testing the Configuration.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Deleting an Application

September 24, 2018

Contributed by:
C

If you no longer need an application and its application units, you can delete it. When you delete an
AppExpert application, backend services are not deleted, and any public endpoints that the applica-
tion used become available for use by other applications.

When deleting an application, you are also prompted to specify whether you want to delete any bound
policies and actions that are not used elsewhere.

To delete an application unit for an application by using the GUI:

Navigate to AppExpert > Applications, select an application and click Edit. In the Application Unit
section, click the delete icon next to the entity

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configure application authentication, authorization, and auditing

September 24, 2018

Contributed by:
C

You can configure Authentication, Authorization, and Auditing (AAA) for the applications that you con-
figure on the appliance. An authentication policy that is configured for an application defines the type

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1007

NetScaler 12.0

of authentication to apply when a user or group attempts to access the application. If external authen-
tication is used, the policy also specifies the external authentication server. Authorization policies
configured for an application specify whether a particular user or group can access the application.
Auditing policies define the audit log type, the level at which logging is performed, and other audit
server settings. Authentication and auditing policies use the classic policy format.

Authentication policies, authorization policies, and auditing policies can be configured in any order.
However, before you configure AAA for an application, you must configure a public endpoint for the
application.

Configuring authentication for an application involves specifying an authentication FQDN, an authen-

tication virtual server, a server certificate, and authentication and session policies. Authentication
policies are automatically bound to the authentication virtual server specified for the application.

To configure authentication for an AppExpert application:

1. Navigate to AppExpert > Applications.

2. In the details pane, do one of the following:
a) Click Add to add an authentication for a new application.
b) Click Edit to modify an existing application.
3. In the Applications page, select an Application Unit.
4. In the Application Unit slider page, click Authentication from the Advanced Settings section.
5. In the Authentication section, select the authentication type as follows:
a) Form based authentication
b) 401 based authentication
c) None
6. Click OK and then click Done.

Configure application authorization

You can configure authorization for users and groups to enable then to access an AppExpert appli-
cation. If the AAA user or group for which you want to configure permissions has not already been
created, you can create it from AppExpert and then configure permissions for application access.

To configure permissions for a AAA user or group to access an AppExpert application:

1. Navigate to AppExpert > Applications.

2. In the details pane, click the AppExpert application for which you want to configure a user or
group access.
3. In the Applications page, and then click Authorization. from the Advanced Settings section.
4. Do one of the following:
• If the AAA user or group for which you want to configure permissions are already in the
Groups/Users tree, drag the user or group from the Groups/Users tree to the Users or

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1008

NetScaler 12.0

Groups node in the application tree. Then, right-click the user or group and click Allow.
• If the AAA user or group for which you want to configure permissions is not configured on
the appliance, in the application tree, right-click Users or Groups, and then click Add. In
the Create AAA Group or Create AAA User dialog box, fill in the values, click Create, and then
click Close.
The user or group is created with the permission set to Allow. To change the permission
setting, right-click the group or user, and then click the permission setting.
5. Click Done and then click Close.

Configure application auditing

When you configure auditing policies for an application, you must specify the server to which the log
messages must be directed, the format of the messages logged, and the log level. Optionally, you can
configure other settings, such as the log facility and date format. Auditing policies are automatically
bound to all the AppExpert application’s public endpoints.

To configure auditing policies for an application:

1. Navigate to AppExpert > Applications.

2. In the details pane, click the application for which you want to configure auditing policies.
3. In the Application Unit slider page, click + icon in the Policies section to configure the auditing
policies.
4. In the Policies slider page, select policy type as Syslog auditing or Nslog auditing and click Con-
tinue.
5. In the Policy binding section, set the following parameters.
a) Select a policy for binding. If you do not have a policy for binding. click + to create a new
policy.
b) To create a new auditing policy, under Policy Name, click New Policy, and then, in the**
Polic**y page do the following:
i. In the Name box, type a name for the policy.
ii. The Name box already contains the string that is required at the beginning of the
server name. You cannot modify the string.
iii. From the Auditing Type list, select the auditing type (either SYSLOG or NSLOG).
iv. If the audit server you want to specify is already listed in the Server list, select the
server from the list, and then, if you want to modify the server settings, click Modify. In
the Configure Auditing Server dialog box, modify the settings as appropriate, and then
click OK. For more information about the settings in the Configure Auditing Server
dialog box, see Auditing Authenticated Sessions.
v. If you want to configure a new audit server, click New, and then, in the Create Audit-
ing Server dialog box, type a name for the server, specify the server IP address, port
number, and other settings as appropriate. When finished, click OK.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1009

NetScaler 12.0

vi. Click Create.

c) To change the priorities for the new auditing policies you created, under Priority, for each
policy for which you want to change the priority, double-click the priority value and type
new priority value.
d) To regenerate priorities, click Regenerate Priorities.
e) To unbind a policy, click the policy, and then click Unbind Policy.
f) To modify a policy, click the policy, and then click Modify Policy.
6. Click Apply Changes, and then click Close.

Disabling AAA for an Application

After you configure AAA for an application, you can disable the AAA configuration for that application.
When you disable AAA for an application, the configuration is not lost. You can enable AAA for the
application when you want to reapply the configuration.
To enable or disable AAA for an application:
1. Navigate to AppExpert > Applications.
2. In the details pane, click the application for which you want to enable or disable AAA, and then
do one of the following:
3. To disable AAA for the application, click Turn Off AAA.
4. To enable AAA for the application, click Turn On AAA.
1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Setting Up a Custom NetScaler Application

November 13, 2018

Contributed by:
C
If an AppExpert application template is not available for the Web application that you want to man-
age through the NetScaler appliance, or if available AppExpert application templates do not suit your
requirements, you can create an AppExpert application without a template.
To create an AppExpert application without a template, you must first create an application and ap-
plication units. Then, you configure public endpoints, services, and service groups. Finally, you con-
figure the policies that determine how application traffic is evaluated and processed.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1010

NetScaler 12.0

After you create the application and application units and configure policies, you must verify the con-
figuration and test it to make sure that it is working correctly, just as you would when you configure
an application by using a prebuilt AppExpert application template. Then, you must monitor the appli-
cation to make sure that the application and its entities are working correctly.

Creating an Application

When you create an AppExpert application, the appliance creates a container to which you can add
application units. The default application unit is not created until you create the first application unit.

To create an AppExpert application by using the GUI:

1. Navigate to AppExpert > Applications.

2. In the details pane, right-click Applications, and then click Add.
3. In the Create Application dialog box, in Name, enter a name for the application, and then click
OK.

Creating Application Units

For each subset of traffic associated with your web application, you must create an application unit.

To create an application unit for the AppExpert application by using the GUI:

1. Navigate to AppExpert > Applications.

2. In the details pane, right-click the application for which you want to add an application unit,
and then click Add.
3. Click Create.

Configuring Public Endpoints for an AppExpert Application

After you have created all the application units that you require, you must configure one or more public
endpoints to enable clients to access the web application through the NetScaler appliance.

To configure public endpoints for an AppExpert application by using the GUI:

1. Navigate to AppExpert > Applications.

2. In the details pane, right-click the application for which you want to configure public endpoints,
and then click Configure Public Endpoints.
3. In the Choose Public Endpoints dialog box for the application, do one of the following:
• If the endpoints you want are listed in the dialog box, click the corresponding check boxes.
• If you want to specify all the public endpoints, click Activate All.
• If you want to dissociate endpoints from the AppExpert application, clear the correspond-
ing check boxes.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1011

NetScaler 12.0

• If you want to create a new public endpoint, click Add. Then, in the Create public endpoint
dialog box, configure endpoint settings, and then click OK.
In the Create public endpoint dialog box, you can specify only the name, IP address, port,
and protocol for the endpoint. You can specify additional endpoint settings after you cre-
ate the public endpoint. To specify additional endpoint settings, after you create the end-
point, in the Choose Public Endpoints dialog box, click the endpoint, and then click Open.
Then, in the Configure Public Endpoint dialog box, provide additional settings, and then
click OK.
For more information about the parameters in the Create public endpoint and Configure
Public Endpoint dialog boxes, see Content Switching.
• If you want to modify a public endpoint, click the endpoint, and then click Open. Then, in
the Configure Public Endpoint dialog box, modify settings for the endpoint, and then click
OK.
For more information about the parameters in the Configure Public Endpoint dialog box,
see Content Switching.
4. Click Close.

Configuring Public Endpoints for an Application Unit

For an application unit, you specify public endpoints in the same way as you would specify public
endpoints for an application that is created from an AppExpert application template. For more infor-
mation about specifying a subset of the endpoints for an application unit, see Configuring Endpoints
for an Application Unit.
To configure endpoints for an application unit by using the GUI:
1. Navigate to AppExpert > Applications.
2. In the details pane, right-click the application unit for which you want to specify public end-
points, and then click Configure Public Endpoints.
3. In the Choose Public Endpoints dialog box for the application unit, do one of the following:
• If you are specifying endpoints for the application unit for the first time, clear the check
boxes that correspond to the endpoints that you do not want to be bound to the applica-
tion unit.
• If you want to specify endpoints that are listed in the dialog box but not currently bound
to the application unit, click the corresponding check boxes.
4. Click OK.

Configuring Services and Service Groups for an AppExpert Application

Services and service groups are available for application units only after you configure the services
and service groups for the AppExpert application. Therefore, you must configure services and service

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1012

NetScaler 12.0

groups for the AppExpert application before you configure the services for the application units. All
the services and service groups that you configure for an AppExpert application must use the same
protocol (either HTTP or HTTPS). The procedure for configuring services and service groups for an
AppExpert application that is not created from a template is the same as that for an application created
from a template.
To configure a service or service group for the AppExpert application by using the GUI:
1. Navigate to AppExpert > Applications.
2. In the details pane, right-click the application for which you want to configure services or service
groups, and then click Configure Backend Services.
3. In the Configure Backend Services dialog box, do one of the following:
• To configure services, click the Services tab.
• To configure service groups, click the Service Groups tab.
4. On the Service or Service Groups tab, do one of the following:
• If the services or service groups that you want are listed on the tab, click the corresponding
check boxes.
• If you want to specify all the services or service groups, click Activate All.
• If you want to create a new service or service group, click Add. Then, in the Create Service
dialog box or Create Service Group dialog box, configure settings for the service or service
group, respectively, and then click Create.
• If you want to modify a service, click the service, and then click Open. Then, in the Config-
ure Service dialog box or Create Service Group dialog box, configure settings for the service
or service group, respectively, and then click OK.
For information about the settings in the Create Service, Configure Service, and Create Service Group
dialog boxes, see Load Balancing.

Configuring services and service groups for an application Unit

After you configure services and service groups, you must configure services and service groups for
each application unit. However, this step is not necessary if each backend service hosts all the content
associated with the web application. You configure services and service groups for an application unit
if the content associated with the application unit is hosted on only a subset of the backend servers.
To configure services or service groups for an application unit by using the GUI:
1. Navigate to AppExpert > Applications.
2. In the details pane, right-click the application unit for which you want to configure a service or
service group, and then click Configure Backend Services.
3. In the Configure Backend Services dialog box, do one of the following:
• To configure services, click the Services tab.
• To configure service groups, click the Service Groups tab.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1013

NetScaler 12.0

4. In the Services or Service Groups tab, do one of the following:

• Clear the check boxes that correspond to the services or service groups that you do not
want configured for the application unit. Make sure that the check boxes that correspond
to the services or service groups that you want configured for the application unit are se-
lected. Then, in the Weight column, specify the weight that you want to assign to each
configured service.
• To specify all services or service groups, click Activate All.
5. On the Method and Persistence and Advanced tabs, specify the desired parameters.
6. Click OK.

Configuring Policies

The procedures for configuring policies for an AppExpert application that is created without using a
template are the same as those for an AppExpert application that was created from a template. For
more information, see Configuring Policies for Application Units.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Creating and managing template files

September 24, 2018

Contributed by:
C

After you set up an AppExpert application and customize it to suit your requirements, you can create
a template from the configuration and then share the template with other administrators. Or, you can
create a template and then import the template to other NetScaler appliances that require a similar
AppExpert application configuration. This simplifies and expedites the process of setting up similar
applications on other appliances.

AppExpert application template files can be exported either to the template directory on the NetScaler
appliance or to a folder on your local computer. You can then upload and download the templates to
and from the NetScaler appliance and rename the templates that are stored in the AppExpert applica-
tion templates directory on your appliance.

AppExpert application template files can be exported either to the template directory on the NetScaler
appliance or to a folder on your local computer. You can then upload and download the templates to

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1014

NetScaler 12.0

and from the NetScaler appliance and rename the templates that are stored in the AppExpert applica-
tion templates directory on your appliance.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Exporting an appExpert application to a template file

September 24, 2018

Contributed by:
C

When you export an appExpert application, all application-configuration information is exported to

a template file, and all deployment-specific information is exported to a deployment file. The string
_deployment is automatically appended to the name of the template file to create the name of the de-
ployment file. Both files are in XML format. If you choose to export the application template file to the
NetScaler appliance, the template file is stored in the /nsconfig/nstemplates/applications directory
and the deployment file is stored in the /nsconfig/nstemplates/applications/deployment_files/ direc-
tory. If you have configured a NetScaler Gateway application, you can choose to include the NetScaler
Gateway policies in the template.

To export an AppExpert application to a template file by using the GUI:

1. Navigate to AppExpert > Application, select an application entity, and then click Edit.
2. On the Applications page, click the Export as a Template link to export the application config-
uration and deployment settings as a template.
3. In the Export Application slider, set the following parameters:
a) Template Filename
b) Deployment Filename
4. Click Continue and Done.
5. Navigate to AppExpert > Application and click Manage Templates to show the exported con-
figuration as files on the Template File and Deployment File tabs.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1015

NetScaler 12.0

Exporting a Content Switching Virtual Server Configuration to a

Template File

September 24, 2018

Contributed by:
C

You can also export a content switching configuration as an application template. You can export
a content switching virtual server configuration to an application template either from the Content
Switching Virtual Servers pane or from the Content Switching Visualizer. Configuration information,
which includes the content switching virtual server, all associated load balancing virtual servers, ser-
vices, service groups, and policies, is exported to a template file and all deployment-specific infor-
mation is exported to a deployment file. The string “_deployment” is automatically appended to the
name of the template file to create the name of the deployment file. Both files are in XML format. If you
choose to export the application template file to the NetScaler appliance, the template file is stored
in the /nsconfig/nstemplates/applications directory on the NetScaler appliance and the deployment
file is stored in the /nsconfig/nstemplates/applications/deployment_files/ directory.

For more information about the format of application templates and deployment files, see Under-
standing NetScaler Application Templates and Deployment Files. The configuration information that
is exported includes the content switching virtual server, all associated load balancing virtual servers,
services, service groups, and policies.

However, if the content switching virtual server is already configured as the public endpoint for an
AppExpert application, you cannot export the configuration to a template file . In this scenario, you
must export the associated AppExpert application to a template.

For more information about exporting an AppExpert application to a template file, see Exporting an
AppExpert Application to a Template File.

To export a content switching configuration to an application template file from the Content Switching
Visualizer by using the GUI:

1. Navigate to Traffic Management > Content Switching > Virtual Servers.

2. In the details pane, click the name of the content switching virtual server whose configuration
you want to export as a template file, and then click Visualizer.
3. In the Content Switching Visualizer, click the icon for the content switching vserver, click Re-
lated Tasks, and then click Create Template.
4. In the Export…as Template dialog box, enter a name for the template file, and then do one of
the following:
• To export the template file to the appliance, make sure that Browse (Appliance) is dis-
played.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1016

NetScaler 12.0

• To export the template file to your computer, click the Browse (Appliance) drop-down
menu, click Local, browse to the location to which you want to save the file, and then
click Save.
5. Provide the following information:
• Introduction Description—Any text that introduces the AppExpert application template
during import. This text is displayed on the Specify Application Name page of the AppEx-
pert Template Wizard when the template is imported.
• Summary Description—Any summary that you might want to display on the Summary
page of the AppExpert Template Wizard when the template is imported.
• Author—The name of the author of the template.
• Major—The major version number of the template.
• Minor—The minor version number of the template. This number is appended to the major
version number and displayed on the Summary page of the AppExpert Template Wizard,
during import, in the format Major.Minor.
6. Click OK.

To export a content switching configuration to an application template file from the Content Switching
Virtual Servers pane by using the GUI:

1. Navigate to Traffic Management > Content Switching > Virtual Servers.

2. In the details pane, click the name of the content switching virtual server whose configuration
you want to export as a template file, and then click Create AppExpert Template.
3. Perform steps 4 through 6 described in To export a content switching configuration to an
application template file from the Content Switching Visualizer procedure.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Creating Variables in Application Templates

January 6, 2019

Contributed by:
C

Application templates support the declaration of variables in the policy expressions and actions that
are configured for an application. The ability to declare variables in policy expressions and actions en-
ables you to replace preconfigured values in expressions (for example, configurable parameters such
as the host name of a server or the target for a Rewrite action) with values that suit the environment

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1017

NetScaler 12.0

into which you are importing the template. If variables have been configured for an AppExpert ap-
plication template, the AppExpert Template Wizard, which appears when you import an AppExpert
application template, includes a Specify Variable Values page on which you can specify appropriate
values for the variables that are configured for the template.
As an example, consider the following policy expression that is configured to evaluate the value of the
Host header in an HTTP request:

1 HTTP.REQ.HEADER(”Host”).CONTAINS(”server1”)

If you want the server name to be configurable at import time, you can specify the string “server1” as
a variable. When importing the template, you can specify a new value for the variable on the Variables
tab.
After you create a variable, you can do the following:
• Assign additional strings to an existing variable. After you create a variable for a string, you can
select and assign other parts of the same or different expression to the variable. The strings you
assign to a variable need not be the same. At import time, all the strings that are assigned to
the variable are replaced with the value that you provide.
• View the string or strings that are assigned to the variable.
• View a list of all the entities and parameters that use the variable.
In the export application template wizard, you can define variables in certain fields (fields with an
adjacent button) for the following entities:
• Cache policies
• Rewrite policies
• Rewrite actions
• Responder policies
• Responder actions
To configure a variable in a policy expression or action by using the GUI:
1. Navigate to AppExpert > Applications.
2. In the details pane, right-click the application that you want to export to a template file, and
then click Export.
3. In the Export…as Template dialog box, modify the default template file name if required, specify
the location where you want to save the template, and then click Configure Variables.
4. In the Configure Variables dialog box, click the tab that lists the policy expression or action for
which you want to configure a variable, select the expression, and then click Configure Vari-
ables.
5. In the Variables dialog box, click the button next to the expression or value in which you want
to create a variable.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1018

NetScaler 12.0

6. In the Variables dialog box, do the following:

• To create a variable, in the text box that displays the configured expression or value, se-
lect the string that you want to be configurable at import time, and then click Add. In the
Add Variable dialog box, specify a name and a description for the variable, and then click
Create.

• The name of the variable, its value, and the description you provided appear in the Avail-
able Variables listing in the dialog box. The name you provide will be the name of the
associated field in the template import wizard, and the description will appear as alt text
when the user positions the mouse pointer over the field.

• To modify a variable, in the Available Variables list, click the variable, and then click Open.
In the Add Variable dialog box, modify the value and the description, and then click OK.

• To view all the strings that are assigned to a given variable, in the Available Variables listing,
click the name of the variable. The strings that are assigned to the variable are highlighted.

• To view a list of all the entities and parameters in which the variable is used, in the Available
Variables listing, click the variable whose references you want to view, and then click Show
References.

• To assign a string to an existing variable, in the text box that displays the expression you
configured, select the string you want to assign to an existing variable, right-click the se-
lection, click Use Existing Selection, and then click the name of the variable to which you
want to assign the string.

If a variable has multiple strings assigned to it, when you specify a new value for the vari-
able during import, all strings assigned to the variable are replaced with the new value.

7. Click Close.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Uploading and downloading template files

September 24, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1019

NetScaler 12.0

Template files can be uploaded from your local computer to the NetScaler appliance or downloaded
from the appliance to your local computer. On the appliance, AppExpert application templates are
always stored in the AppExpert application templates directory, which is
/nsconfig/nstemplates/applications/.

To upload an AppExpert application template from your local computer to the NetScaler appliance:
1. Navigate to AppExpert > Templates.
2. In the details pane, click Manage Templates.
3. In the Manage Application Templates dialog box, click Application Templates, and then click
Upload.
4. In the Upload Application Template dialog box, browse to the directory in which the template
file is stored, click the template file, and then click Select.
The template file is uploaded to the AppExpert application template directory on the appliance.
To download an AppExpert application template from the NetScaler appliance to your local computer:
1. Navigate to AppExpert > Templates.
2. In the details pane, click Manage Templates.
3. In the Manage Application Templates dialog box, click the AppExpert application template that
you want to download, and click Download.
4. In the Download Application Template dialog box, browse to the location to which you want
to save the file, and then click Save.
1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Understanding NetScaler application templates and deployment files

September 24, 2018

Contributed by:
C
When you export a NetScaler application, the following two files are automatically created:
• NetScaler application template file. Contains application-configuration information such as
application units, rules, and configured policies.
• Deployment file. Contains deployment-specific information such as public endpoints,
services, associated IP addresses, and configured variables.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1020

NetScaler 12.0

In a template file or deployment file, each unit of application-configuration information is encapsu-

lated in a specific XML element that is meant for that unit type. For example, each public endpoint
and associated endpoint details are encapsulated within the <appendpoint> and <appendpoint>
tags, and all the endpoint elements are encapsulated within the <appendpoint_list> and
<appendpoint_list> tags.

Note: After you export a NetScaler application, you can add elements, remove elements, and modify
existing elements before importing the application to a NetScaler appliance.

Example of a NetScaler Application Template

Following is an example of a template file that was created from a NetScaler application called Share-
Point_Team_Site:

1 <?xml version=”1.0” encoding=”UTF-8” ?>

2 <template>
3 <template_info>
4 <application_name>SharePoint_Team_Site</application_name>
5 <templateversion_major>1</templateversion_major>
6 <templateversion_minor>1</templateversion_minor>
7 <author>Ed</author>
8 <introduction>An application for managing a SharePoint team site
with images, reports, and, XML content.</introduction>
9 <summary>This template includes variables</summary>
10 <version_major>9</version_major>
11 <version_minor>3</version_minor>
12 <build_number>38</build_number>
13 </template_info>
14 <apptemplate>
15 <rewrite>
16 <rewriteaction_list>
17 <rewriteaction>
18 <name>Rw_name</name>
19 <type>replace</type>
20 <target>HTTP.REQ.BODY(10000).AFTER_REGEX(re/number/).
BEFORE_REGEX(re/address/)</target>
21 <stringbuilderexpr>”NA”</stringbuilderexpr>
22 <allow_unsafe_pi1>NO</allow_unsafe_pi1>
23 </rewriteaction>
24 <rewriteaction>
25 .
26 .
27 .
28 </rewriteaction>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1021

NetScaler 12.0

29 .
30 .
31 .
32 </rewriteaction_list>
33 <rewritepolicy_list>
34 <rewritepolicy>
35 <name>Rw_number_NA</name>
36 <rule>HTTP.REQ.BODY(100000).CONTAINS(”admin”)</rule>
37 <action>Rw_name</action>
38 </rewritepolicy>
39 <rewritepolicy>
40 .
41 .
42 .
43 </rewritepolicy>
44 .
45 .
46 .
47 </rewritepolicy_list>
48 </rewrite>
49 <appunit_list>
50 <appunit>
51 <name>SharePoint_Team_Sitedefault</name>
52 <rule />
53 <expressiontype>PE</expressiontype>
54 <servicetype>HTTP</servicetype>
55 <ipv46>0.0.0.0</ipv46>
56 <ipmask>*</ipmask>
57 <port>0</port>
58 <range>1</range>
59 <persistencetype>NONE</persistencetype>
60 <timeout>2</timeout>
61 <persistencebackup>NONE</persistencebackup>
62 <backuppersistencetimeout>2</backuppersistencetimeout>
63 <lbmethod>LEASTCONNECTION</lbmethod>
64 <persistmask>255.255.255.255</persistmask>
65 <v6persistmasklen>128</v6persistmasklen>
66 <pq>OFF</pq>
67 <sc>OFF</sc>
68 <m>IP</m>
69 <datalength>0</datalength>
70 <dataoffset>0</dataoffset>
71 <sessionless>DISABLED</sessionless>
72 <state>ENABLED</state>
73 <connfailover>DISABLED</connfailover>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1022

NetScaler 12.0

74 <clttimeout>180</clttimeout>
75 <somethod>NONE</somethod>
76 <sopersistence>DISABLED</sopersistence>
77 <redirectportrewrite>DISABLED</redirectportrewrite>
78 <downstateflush>DISABLED</downstateflush>
79 <gt2gb>DISABLED</gt2gb>
80 <ipmapping>0.0.0.0</ipmapping>
81 <disableprimaryondown>DISABLED</disableprimaryondown>
82 <insertvserveripport>OFF</insertvserveripport>
83 <authentication>OFF</authentication>
84 <authn401>OFF</authn401>
85 <push>DISABLED</push>
86 <pushlabel>none</pushlabel>
87 <l2conn>OFF</l2conn>
88 </appunit>
89 <appunit>
90 .
91 .
92 .
93 </appunit>
94 .
95 .
96 .
97 </appunit_list>
98 </apptemplate>
99 <parameters>
100 <property_list>
101 <property>
102 <variable_definition_list>
103 <variable_definition>
104 <name>body_size</name>
105 <defaultvalue>10000</defaultvalue>
106 <description>Evaluation Scope</description>
107 <startindex>14</startindex>
108 <length>5</length>
109 </variable_definition>
110 .
111 .
112 .
113 </variable_definition_list>
114 <object_type>rewriteaction</object_type>
115 <object_name>Rw_name</object_name>
116 <name>target</name>
117 </property>
118 .

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1023

NetScaler 12.0

119 .
120 .
121 </property_list>
122 </parameters>
123 </template>

Example of a deployment file

Following is the deployment file associated with the SharePoint_Team_Site application in the pre-
ceding example:

1 <?xml version=”1.0” encoding=”UTF8” ?>

2 <template_deployment>
3 <template_info>
4 <application_name>SharePoint_Team_Site</application_name>
5 <templateversion_major>1</templateversion_major>
6 <templateversion_minor>1</templateversion_minor>
7 <author>Ed</author>
8 <introduction>An application for managing a SharePoint team site
with images, reports, and, XML content.</introduction>
9 <summary>This template includes variables</summary>
10 <version_major>9</version_major>
11 <version_minor>3</version_minor>
12 <build_number>38</build_number>
13 </template_info>
14 <appendpoint_list>
15 <appendpoint>
16 <ipv46>10.111.111.1</ipv46>
17 <port>80</port>
18 <servicetype>HTTP</servicetype>
19 </appendpoint>
20 </appendpoint_list>
21 <service_list>
22 <service>
23 <ip>10.102.29.5</ip>
24 <port>80</port>
25 <servicetype>HTTP</servicetype>
26 </service>
27 <service>
28 .
29 .
30 .
31 </service>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1024

NetScaler 12.0

32 .
33 .
34 .
35 </service_list>
36 <variable_list>
37 <variable>
38 <name>body_size</name>
39 <description>Evaluation Scope</description>
40 <value>10000</value>
41 </variable>
42 <variable>
43 .
44 .
45 .
46 </variable>
47 .
48 .
49 .
50 </variable_list>
51 </template_deployment>

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Deleting a Template File

September 24, 2018

Contributed by:
C

If you no longer need an application template and its configuration, you can delete it. When you delete
a template, the template XML file that is stored in the application template directory gets deleted.
When you delete a template file, you are prompted to confirm the deletion. Click Yes to confirm and
delete the selected file from the directory.

To delete a template file from the application template directory by using the GUI:

1. Navigate to AppExpert > Applications and then click Manage Template. Select a file from Tem-
plate Files tab page or Deployment Files tab page and click Delete.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1025

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

NetScaler Gateway Applications

September 24, 2018

Contributed by:
C

When you configure an AppExpert application to manage a web application through the Citrix®
NetScaler® appliance, you also create a set of application units and configure a set of traffic opti-
mization and security policies for each unit. The policies that you configure for each application
unit (policies for features such as Compression, Caching, and Rewrite) evaluate traffic that is meant
only for that unit. In addition to these policies, you might want to configure Access Gateway policies
for the application as a whole to optimize the application traffic when accessed through the Access
Gateway. The Access Gateway Applications feature enables you to configure Access Gateway policies
(Authorization, Traffic, Clientless Access, and TCP Compression) for an AppExpert application. After
you configure NetScaler Gateway policies for AppExpert applications, you can include the policy
configuration in the AppExpert application templates that you create.

You can also configure NetScaler Gateway policies for intranet subnets, file shares, and other network
resources. Finally, you can create bookmarks for AppExpert applications and certain resources if you
want users to be able to access them from the NetScaler Gateway home page.

You can configure the entities in the NetScaler Gateway Applications feature only by using the GUI.

How an NetScaler Gateway Application Works

When you create an AppExpert application in the Applications node in the GUI, a corresponding Access
Gateway application is automatically created in the Access Gateway Applications node. Additionally, a
rule that uses the AppExpert application’s configured public endpoint is automatically created for the
Access Gateway application entry. If multiple endpoints are configured for the AppExpert application,
the rule includes all the configured public endpoints. The NetScaler appliance uses this rule to apply
any configured Access Gateway policies to the traffic received at the AppExpert application’s public
endpoint. Traffic received at the AppExpert application’s public endpoint is first evaluated against the
NetScaler Gateway policies and then evaluated against the policies configured for AppExpert applica-
tion’s application units.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1026

NetScaler 12.0

The rule that is created for the Clientless Access policies for an Access Gateway application is an ad-
vanced expression that also uses the public endpoint that is configured for the AppExpert application.
Therefore, before you configure NetScaler Gateway policies for an AppExpert application, you must
configure public endpoints for the AppExpert application.
When you include the NetScaler Gateway configuration in an application template, deployment-
specific information, such as IP address and port information, and the rule that is created from this
information are not included in the template.

How a NetScaler Configuration for a File Share Works

On the NetScaler appliance, you can configure Authorization policies for a file share that is hosted on
your organization’s network.
When you create a file share, you specify a name for the file share and the network path to the file
share. In the network path, you can specify either the name of the server or the server IP address. A
rule that uses the components of the file share path is automatically created for the file share. This rule
enables the appliance to identify requests for files hosted on the file share server. Any Authorization
policies that are configured for the file share are applied to incoming requests.
The NetScaler configuration for a file share cannot be saved in AppExpert application templates.

How a NetScaler Configuration for an Intranet Subnet Works

For the intranet subnets that form a part of your network, you can configure policies for Authoriza-
tion, Traffic, and TCP Compression on the NetScaler appliance. When adding an intranet subnet, you
specify the IP address and the netmask of the intranet subnet. A rule that uses these two parameters
is automatically created for the intranet subnet. The appliance applies the configured policies to any
request that has a destination IP address and netmask set to the subnet’s IP address and netmask,
respectively.
The NetScaler configuration for an intranet subnet cannot be saved in AppExpert application tem-
plates.

How the Other Resources Category Works

The Other Resources category enables you to configure Access Gateway policies for any network re-
source by using a rule of your choice. When you configure the NetScaler appliance to process requests
for the network resource, you configure a classic expression to identify the requests that are associ-
ated with the network resource. You can configure Authorization, Traffic, Clientless Access, and TCP
Compression policies for a network resource in Other Resources. The NetScaler appliance applies the
configured NetScaler Gateway policies to any requests that match the configured rule.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1027

NetScaler 12.0

The NetScaler configuration for a network resource in Other Resources cannot be saved in AppExpert
application templates.

Entity Naming Conventions

The NetScaler Gateway Applications feature enforces a naming convention for some of the entities
that you create in this feature. For example, the names of the profiles that you create for Traffic poli-
cies for an intranet subnet always begin with a string that consists of the name of the intranet subnet
followed by an underscore (_). The name that you provide for the entity is appended to this string. If
the name of a subnet is “subnet1,” the name of the profile begins with “subnet1_.” When such a nam-
ing convention is required (in the text box in which you type the name of an entity, for example), the
user interface automatically inserts the string with which the name of the entity must begin and does
not allow you to modify it.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Adding Intranet Subnets

September 24, 2018

Contributed by:
C

You can specify authorization and Traffic policies for traffic that is bound for the intranet subnets that
are configured in your network. The rules for these policies are automatically created by using the
parameters you specify for the subnet.

To configure an intranet subnet by using the GUI:

1. In the navigation pane of the GUI, expand AppExpert, and then click Access Gateway Applica-
tions.
2. In the details pane, do one of the following:
• To add an intranet subnet, click Intranet Subnets, and then click Add.
• To modify an intranet subnet, click an intranet subnet, and then click Open.
3. In the Create Intranet Subnet or Configure Intranet Subnet dialog box, do the following:
a) In the Name box, type a name for the intranet subnet you are adding. This parameter
cannot be changed for an existing intranet subnet.
b) In the IP Address box, type the IP address of the intranet subnet.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1028

NetScaler 12.0

c) In the Netmask box, type the netmask that will be used for the intranet subnet.
d) Click Create or OK, and then click Close.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Adding Other Resources

September 24, 2018

Contributed by:
C

For a network resource that you add to Other Resources, you must configure a classic expression that
identifies the subset of traffic associated with the resource. For more information about configuring
a classic expression, see the .

To configure a resource in Other Resources by using the GUI:

1. In the navigation pane of the GUI, expand AppExpert, and then click Access Gateway Applica-
tions.
2. In the details pane, do one of the following:
• To add a resource, click Other Resources, and then click Add.
• To modify a resource, click a resource, and then click Open.
3. In the Create Resource or Configure Resource dialog box, do the following:
a) In the Name box, type a name for the resource you are adding. This parameter cannot be
changed for an existing resource.
b) In the Rule box, type the rule that will identify the subset of traffic that is associated with
the resource you are adding.
Alternatively, click Configure, and then create the rule in the Create Expression dialog box.
c) Click Create or OK, and then click Close.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1029

NetScaler 12.0

Configuring Authorization Policies

September 26, 2018

Contributed by:
C
You can configure NetScaler Gateway authorization policies for AAA users and groups to access a re-
source.
To configure permissions for a AAA user or group to access a resource by using the GUI:
1. In the navigation pane of the GUI, expand AppExpert, and then click Access Gateway Applica-
tions.
2. In the details pane, in the Authorization column, click the icon for the application, file share,
intranet subnet, or resource for which you want to configure authorization policies for AAA users
and groups.
3. Do one of the following:
• If the AAA user or group for which you want to configure permissions is already in the
Groups/Users tree, drag the user or group from the Groups/Users tree to the Users or
Groups node in the <application name> tree. Then, right-click the user or group and
click Allow.
• If the AAA user or group for which you want to configure permissions is not configured on
the appliance, in the <application name> tree, right-click Users or Groups, and then
click Add. In the Create AAA Group or Create AAA User dialog box, fill in the values, click
Create, and then click Close.
The user or group is created with the permission set to Allow. To change the permission
setting, right-click the group or user, and then click the permission setting.
4. Click Close.
1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring Traffic Policies

September 24, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1030

NetScaler 12.0

The traffic policies that you configure for the resources in the NetScaler Gateway Applications node
control client connections to the application. You do not have to configure a rule for the resource. The
rule created automatically when you create the resource. You only need to associate a request profile
with the traffic policy. In the traffic profile, you specify parameters such as the protocol, application
time-out, and file type association.

To configure traffic policies for a resource

1. In the navigation pane of the GUI, expand AppExpert, and then click Access Gateway Applica-
tions.
2. In the details pane, in the Traffic column, click the icon provided for the application, file share,
intranet subnet, or resource for which you want to configure traffic policies.
3. In the Configure Traffic Policies dialog box, do the following:
• To specify an existing traffic policy, click Insert Policy, and then, in the Policy Name col-
umn, click the name of the policy.
• To configure a new policy, click Insert Policy, and then, in the Policy Name column, click
New Policy. In the Create Traffic Policy dialog box, in the Name box, after the underscore
(_), type a name for the policy. Then, in Request Profile, either select an existing request
profile or click New to configure a new request profile. You can also select an existing pro-
file and then click Modify to modify the profile.
For more information about configuring a traffic policy or profile, see NetScaler Gateway.
• To modify a policy that you have inserted, in the Policy Name column, click the policy
name, and then click Modify Policy. To modify only the associated profile, in the Profile
column, click the name of the profile, and then click Modify Profile.
• To regenerate the priorities assigned to the policies, click Regenerate Priorities.
• To specify a new priority value for a policy, in the Priority column, double-click the as-
signed priority, and then enter the value you want.
• To unbind a policy, click the policy, and then click Unbind Policy.
4. Click Apply Changes, and then click Close.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring Clientless Access Policies

September 24, 2018

Contributed by:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1031

NetScaler 12.0

Clientless access, when configured for a resource on the NetScaler appliance, allows end-users to
access the resource without using the NetScaler Gateway client software. Users can use web browsers
to access resources such as Outlook Web Access. You configure clientless access for a resource by
configuring a clientless access policy that is associated with a clientless access profile.

To configure a clientless access policy for a resource in the NetScaler Gateway Applications node:

1. In the navigation pane of the GUI, expand AppExpert, and then click Access Gateway Applica-
tions.
2. In the details pane, in the **Clientless Access **column, click the icon for the application, file
share, intranet subnet, or resource for which you want to configure a clientless access policy.
3. In the Configure Clientless Access Policies dialog box, do the following:
• To specify an existing clientless access policy, click Insert Policy, and then, in the Policy
Name column, click the name of the policy.
• To configure a new clientless access policy, click Insert Policy, and then, in the Policy Name
column, click New Policy. In the Create Clientless Access Policy dialog box, in the Name
box, after the underscore (_), type a name for the policy. Then, in Profile, either select
an existing profile or click New to configure a new profile. You can also select an existing
profile and then click Modify to modify the profile.
For more information about configuring a clientless access policy or profile, see NetScaler
Gateway.
• To modify a policy that you have inserted, in the Policy Name column, click the policy
name, and then click Modify Policy. To modify only the associated profile, in the Profile
column, click the name of the profile, and then click Modify Profile.
• To specify a new priority value for a policy, in the Priority column, double-click the as-
signed priority, and then enter the value you want.
• To unbind a policy, click the policy, and then click Unbind Policy.
4. Click Apply Changes, and then click Close.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring TCP Compression Policies

September 24, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1032

NetScaler 12.0

Contributed by:
C

You can configure TCP compression policies for an application to increase the performance of the
application. TCP compression reduces network latency, reduces bandwidth requirements, and in-
creases the speed of transmission. When configuring a TCP compression policy, you associate a com-
pression action with the policy. The compression action specifies either Compress, GZIP, Deflate, or
NoCompress as the compression type. For more information about the compression policies, and
compression actions, see NetScaler Gateway.

To configure a TCP compression policy for a resource in the NetScaler Gateway Applications node

1. In the navigation pane of the GUI, expand AppExpert, and then click Access Gateway Applica-
tions.
2. In the details pane, in the TCP Compression column, click the icon for the application, file share,
intranet subnet, or resource for which you want to configure a TCP compression policy.
3. In the Configure TCP Compression Policies dialog box, do the following:
• To specify an existing TCP compression policy, click Insert Policy, and then, in the **Policy
Name **column, click the name of the policy.
• To create a new TCP compression policy, click Insert Policy, and then, in the Policy Name
column, click New Policy. In the Create TCP Compression Policy dialog box, in the Policy
Name box, after the underscore (“_”), type a name for the policy. Then, in Action, either
select an existing action or click New and configure a new action. You can also click View
to view the configured compression type.
For more information about configuring a TCP compression policy or action, see NetScaler
Gateway , Enterprise Edition at NetScaler Gateway.
• To modify a policy that you have inserted, in the Policy Name column, click the policy
name, and then click Modify Policy.
• To regenerate the priorities assigned to the policies, click Regenerate Priorities.
• To specify a new priority value for a policy, in the Priority column, double-click the as-
signed priority, and then enter the value you want.
• To unbind a policy, click the policy, and then click Unbind Policy.
4. Click Apply Changes, and then click Close.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1033

NetScaler 12.0

Configuring Bookmarks

September 24, 2018

Contributed by:
C
You can configure bookmarks for an application or for a resource that you configure in the Other Re-
sources category if you want the application or resource to be accessible from the NetScaler Gateway
home page.
To configure a bookmark for an NetScaler Gateway application or a resource in the Other Resources
category:
1. In the navigation pane of the GUI, expand AppExpert, and then click Access Gateway Applica-
tions.
2. In the details pane, click the application or resource for which you want to configure a book-
mark, and then click Configure Bookmark.
3. In the Create Bookmark dialog box, configure values for the parameters.
For more information about the parameters in the Create Bookmark dialog box, see NetScaler
Gateway.
4. Click Create, and then click Close.
1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Customizing the configuration

September 24, 2018

Contributed by:
C
After you verify that the AppExpert application is working correctly, you can customize the configura-
tion to suit your requirements.
After you verify that the AppExpert application configuration is working correctly, you can configure
the application and the deployment settings to suit your requirements. When you import an applica-
tion template and deployment file, the system automatically populates the target application with the

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1034

NetScaler 12.0

available configuration settings (such as application units, application unit rules, policies, persistence
settings, load balancing methods, profiles, and traffic settings). In this application, you can configure
deployment settings such as public endpoints, services, and service groups for each traffic subset. If
you want the AppExpert application to manage a traffic subset that is not included in the template,
you can either add an application unit for a traffic subset or modify the existing application unit. After
you customize the configuration, you can also specify the order of evaluation for each traffic subset
that the application manages.

Configuring an AppExpert application consists of the following steps:

1. Configuring Public Endpoints

2. Configuring Application Units
3. Specifying the Order of Evaluation
4. Viewing Application Configuration using Visualizer

Also, you can configure the policies that the template provided. If the AppExpert application template
does not include policies for a particular NetScaler feature, such as Rewrite or application firewall, you
can configure your own policies.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configure public endpoints

September 24, 2018

Contributed by:
C

If you did not specify a public endpoint when importing an AppExpert application, you can specify
public endpoints after you create the application. You can configure one public endpoint of type HTTP
and one public endpoint of type HTTPS for your AppExpert application.

If endpoints are already configured for the application, you can dissociate endpoints from the AppEx-
pert application and delete any endpoints that you no longer need. Note that when you dissociate
a public endpoint from the AppExpert application, the endpoint is automatically unbound from the
associated application unit, but it is not deleted from the system.

To configure public endpoints for an AppExpert application:

1. Navigate to AppExpert > Applications.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1035

NetScaler 12.0

2. In the details pane, right-click the application for which you want to configure public endpoints,
and then click Edit.
3. In the Applications page, go to Public Endpoint section and click the pencil icon.
4. In the Public Endpoint slider, set the following parameters.
a) Public endpoint type. Select the radio button to define the endpoint type.
b) Name. Name of the public endpoint.
c) IP address. IP address of the public endpoint.
d) Port. Port number of the public endpoint.
e) Protocol. Select a protocol type as HTTP or HTTPS.
5. Click Continue.
6. In the Application Units section, select an application unit from the list.
7. Click Continue to set the policy and server details.
8. Click OK and then Done.
9. Click Close.

For more information about the parameters in the Configure Public Endpoint dialog box, see Content
Switching.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring Endpoints for an Application Unit

September 24, 2018

Contributed by:
C

When you configure multiple public endpoints for an AppExpert application, by default, all endpoints
are bound to each application unit, and each application unit processes the requests received by all
the endpoints. However, you can specify that a given application unit manages the traffic that is re-
ceived by only a subset of the endpoints that are configured for the AppExpert application.

To configure endpoints for an application unit:

1. Navigate to AppExpert > Applications.

2. In the details pane, right-click the application unit for which you want to specify public end-
points, and then click Configure Public Endpoints.
3. In the Choose Public Endpoints dialog box for the application unit, do one of the following:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1036

NetScaler 12.0

• If you are specifying endpoints for the application unit for the first time, clear the check
boxes that correspond to the endpoints that you do not want to be bound to the applica-
tion unit.
• If you want to specify endpoints that are listed in the dialog box but not currently bound
to the application unit, click the corresponding check boxes.
4. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configure services and service groups for an application unit

September 24, 2018

Contributed by:
C

When you configure a service or service group, you either modify an existing service or service group,
or add new services to the AppExpert application. You add services or service groups if you did not
specify them when you imported the application template. You also add services and service groups
when you increase the number of servers that host instances of the application. You can configure a
service and service group for an application unit only after you configure the service or service group
for the AppExpert application.

To configure a service or service group for the AppExpert application:

1. Navigate to AppExpert > Applications.

2. In the details pane, right-click the application and then click Edit.
3. In the Applications page, select an application unit and then click Continue.
4. In the Services and Service Groups section, do the following:
a) In the Service Binding slider, set the following parameters.
i. Service. Select a load balancing service from the list or create a new service.
ii. Weight. Provide a weight value for the service.
b) Click Bind and then Done.
c) In the ServiceGroup Binding slider, set the following parameters:
i. Service Group Name. Select a load balancing service group or create a new service
group.
ii. Click Bind and then Done.
d) Click Done.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1037

NetScaler 12.0

5. Click Continue to set other configurations.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring services, service groups, and load balancing Parameters for

an application unit

September 24, 2018

Contributed by:
C

When you configure services and service groups for an AppExpert application, by default, all the ser-
vices and service groups are bound to each application unit. However, depending on how you have
configured your web application, the application resources that are managed by an application unit
might be hosted on only some of the servers that are configured as services for the AppExpert appli-
cation. Or, a set of servers might host content that is meant for the requests received at one or more
specific public endpoints. In such scenarios, if all the services and service groups that are configured
for the AppExpert application are associated with the application unit, a request that is forwarded to
a server that does not host the requested content might not be served or might be served incorrect
content. Therefore, you must ensure that each application unit is configured to manage only those
services that can serve the requested content.

When configuring services and service groups for an application unit, you might choose to specify load
balancing settings such as the weights that services must be assigned and the desired load balancing,
persistence, and spillover methods. For more information about these settings, see Load Balancing.

To configure services or service groups for an application unit

1. Navigate to AppExpert > Applications.

2. In the details pane, right-click the application unit for which you want to configure a service or
service group, and then click Configure Backend Services.
3. In the Configure Backend Services dialog box, do one of the following:
• To configure services, click the Services tab.
• To configure service groups, click the Service Groups tab.
4. In the Services or **Service Groups **tab, do one of the following:
• Clear the check boxes that correspond to the services or service groups that you do not
want configured for the application unit. Make sure that the check boxes that correspond

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1038

NetScaler 12.0

to the services or service groups that you want configured for the application unit are se-
lected. Then, in the Weight column, specify the weight that you want to assign to each
configured service.
• To specify all services or service groups, click Activate All.
5. On the Method and Persistence and Advanced tabs, specify the desired parameters.
6. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Create application units

September 24, 2018

Contributed by:
C

You might need to add application units for traffic subsets that are either specific to your web appli-
cation implementation or not defined in the template. When creating an application unit, you must
configure a rule for the application unit.

To create an application unit for the AppExpert application:

1. Navigate to AppExpert > Applications.

2. In the details pane, right-click the application for which you want to add an application unit,
and then click Add.
3. In the Applications page, go to Application Units section and click the pencil icon.

To configure policy expressions for an application unit:

1. Navigate to AppExpert > Applications.

2. In the details pane, right-click the application for which you want to add an application unit,
and then click Add.
3. In the Applications **page, go to Application Units** section and click the **+ **icon. to create
a unit and add policy expressions.
4. To specify the format of the new expression, do one of the following:
a) To specify that you want to configure a classic expression in the Rule box, click Classic
Syntax.
b) To specify that you want to configure an advanced expression in the Rule box, click Default
Syntax.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1039

NetScaler 12.0

c) In the Rule box, configure the expression.

5. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring application unit rules

September 24, 2018

Contributed by:
C

You might want to configure an application unit rule to include or exclude certain types of traffic. When
you configure the rule, you can also define the syntax of the expression.

To configure an application unit rule:

1. In the navigation pane of the GUI, expand AppExpert, and then click Applications.
2. In the details pane, right-click the application unit for which you want to modify the rule, and
then click Open.
3. In the Configure Application Unit dialog box, do the following:
a) To specify the format of the new expression, do one of the following:
• To specify that you want to configure a classic expression in the Rule box, click Classic
Syntax.
• To specify that you want to configure an advanced expression in the Rule box, click
Default Syntax.
b) In the Rule box, configure the expression.
4. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring policies for application units

September 24, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1040

NetScaler 12.0

Contributed by:
C

For an AppExpert application, you can configure policies for Compression, Caching, Rewrite, Respon-
der, and Application Firewall. The templates that you download from the Citrix Community web site
provide you with a set of policies that fulfill the most common application management requirements.
You might want to fine-tune or customize these policies. If the set of policies provided for a given ap-
plication unit does not include policies for a particular feature, you can create and bind your own
policies for that feature.

If you create an AppExpert application without using a template, you must configure all the policies
that the web application needs.

The GUI uses various icons to indicate whether or not policies are configured for a feature. For an
application unit, if a policy is configured for a given feature, an icon that represents the feature is
displayed. For example, if a compression policy is configured for an application unit, a compression
icon is displayed in the Compression column for the application unit. For features for which no policy
is configured, an icon depicting a plus sign (+) is displayed.

Note: When configuring policies for application units, you might need to configure policies and ex-
pressions that are either in the classic or
default syntax. Additionally, when you configure
default syntax policies, you might need to specify parameters such as Goto expressions and invoke
policy banks.
For information about configuring policies and expressions in both formats, see Policies and Expres-
sions.

Configuring compression policies

You can use either classic policies or advanced policies to configure compression, but you cannot bind
compression policies of both types to the same application unit.

To configure a compression policy for an application unit:

1. Navigate to AppExpert > Applications.

2. In the details pane, in the row for the application unit you want to configure, click the icon pro-
vided in the Compression column.
3. In the Configure Compression Policies dialog box, do one or more of the following, depending
on the configuration tasks you want to perform:
• Click Switch to Default Syntax if you want to configure a default syntax compression policy.
If you want to bind or configure classic compression policies, and if you are in the default
syntax view, you can click Switch to Classic Syntax to return to the classic policy view and

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1041

NetScaler 12.0

begin modifying bound classic policies or create and bind new classic compression poli-
cies.
Important: This setting also determines what policies are displayed when you want to in-
sert a policy. For example, if you are in the
default syntax view, when you click
Insert Policy, the list that appears in the
Policy Name column will include only
default syntax policies. You cannot bind policies of both types to an application unit.
• If you want to configure classic policies, click either Request or Response, depending on
whether you want the policy to be evaluated at request-time or at response-time.
You can configure both request-time and response-time classic compression policies for
an application unit. After evaluating all of the request-time policies, if no match is found,
the appliance evaluates response-time policies.
• To modify a compression policy that is already bound to the application unit, click the
name of the policy, and then click Modify Policy. Then, in the Configure Compression Pol-
icy dialog box, modify the policy, and then click OK.
For information about modifying a compression policy, see Compression.
• To unbind a policy, click the name of the policy, and then click Unbind Policy.
• To modify the priority assigned to a policy, double-click the priority value, and then enter
a new value.
• To regenerate assigned priorities, click Regenerate Priorities.
• To insert a new policy, click Insert Policy and, in the list that is displayed in the Policy
Name column, click New Policy. Then, in the Create Compression Policy dialog box,
configure the policy, and then click Create.
For information about modifying a compression policy, see Compression.
• If you are configuring a default syntax expression, do the following:
– In the Goto Expression column, select a Goto expression.
– In the Invoke column, specify the policy bank that you want to invoke if the current
policy evaluates to TRUE.
4. Click Apply Changes, and then click Close.

Configuring Caching Policies

You can use only default syntax policies and expressions to configure Caching policies.

To configure Caching policies for an application unit:

1. Navigate to AppExpert > Applications.

2. In the details pane, in the row for the application unit you want to configure, click the icon pro-
vided in the Caching column.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1042

NetScaler 12.0

3. In the Configure Cache Policies dialog box, do one or more of the following, depending on the
configuration tasks you want to perform:
• Click either Request or Response, depending on whether you want the policy to be evalu-
ated at request-time or at response-time.
You can configure both request-time and response-time Caching policies for an applica-
tion unit. After evaluating all of the request-time policies, if no match is found, the appli-
ance evaluates response-time policies.
• To modify a Caching policy that is already bound to the application unit, click the name of
the policy, and then click Modify Policy. Then, in the Configure Cache Policy dialog box,
modify the policy, and then click OK.
For information about modifying a Caching policy, see Integrated Caching.
• To unbind a policy, click the name of the policy, and then click Unbind Policy.
• To modify the priority assigned to a policy, double-click the priority value, and then enter
a new value.
• To regenerate assigned priorities, click Regenerate Priorities.
• To insert a new policy, click Insert Policy and, in the list that is displayed in the Policy
Name column, click New Policy. Then, in the Create Cache Policy dialog box, configure
the policy, and then click Create.
For information about modifying a Caching policy, see Integrated Caching.
• In the Goto Expression column, select a Goto expression.
• In the Invoke column, specify the policy bank that you want to invoke if the current policy
evaluates to TRUE.
4. Click Apply Changes, and then click Close.

Configuring Rewrite policies

You can use only default syntax policies and expressions to configure Rewrite policies.

To configure Rewrite policies for an application unit:

1. Navigate to AppExpert > Applications.

2. In the details pane, in the row for the application unit you want to configure, click the icon pro-
vided in the Rewrite column.
3. In the Configure Rewrite Policies dialog box, do one or more of the following, depending on
the configuration tasks you want to perform:
• Click either Request or Response, depending on whether you want the policy to be evalu-
ated at request-time or at response-time.
You can configure both request-time and response-time Rewrite policies for an application
unit. After evaluating all of the request-time policies, if no match is found, the appliance
evaluates response-time policies.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1043

NetScaler 12.0

• To modify a Rewrite policy that is already bound to the application unit, click the name of
the policy, and then click Modify Policy. Then, in the Configure Rewrite Policy dialog box,
modify the policy, and then click OK.
For information about modifying a Rewrite policy, see Rewrite.
• To unbind a policy, click the name of the policy, and then click Unbind Policy.
• To modify the priority assigned to a policy, double-click the priority value, and then enter
a new value.
• To regenerate assigned priorities, click Regenerate Priorities.
• To insert a new policy, click Insert Policy and, in the list that is displayed in the Policy
Name column, click New Policy. Then, in the Create Rewrite Policy dialog box, configure
the policy, and then click Create.
For information about modifying a Rewrite policy, see Rewrite.
• In the Goto Expression column, select a Goto expression.
• In the Invoke column, specify the policy bank that you want to invoke if the current policy
evaluates to TRUE.
4. Click Apply Changes, and then click Close.

Configuring Responder policies

You can use only default syntax policies and expressions to configure Responder policies.

To configure Responder policies for an application unit:

1. Navigate to AppExpert > Applications.

2. In the details pane, in the row for the application unit you want to configure, click the icon pro-
vided in the Responder column.
3. In the Configure Responder Policies dialog box, do one or more of the following, depending
on the configuration tasks you want to perform:
• To modify a Filter policy that is already bound to the application unit, click the name of
the policy, and then click Modify Policy. Then, in the Configure Responder Policy dialog
box, modify the policy, and then click OK.
For information about modifying a Responder policy, see Responder.
• To unbind a policy, click the name of the policy, and then click Unbind Policy.
• To modify the priority assigned to a policy, double-click the priority value, and then enter
a new value.
• To regenerate assigned priorities, click Regenerate Priorities.
• To insert a new policy, click Insert Policy and, in the list that is displayed in the Policy
Name column, click New Policy. Then, in the Create Responder Policy dialog box, con-
figure the policy, and then click Create.
For information about modifying a Responder policy, see Responder.
• In the Goto Expression column, select a Goto expression.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1044

NetScaler 12.0

• In the Invoke column, specify the policy bank that you want to invoke if the current policy
evaluates to TRUE.
4. Click Apply Changes, and then click Close.

Configuring Application Firewall policies

You can configure both classic and default syntax policies and expressions for Application Firewall.
However, if a policy of one type is already bound globally or to a virtual server that is configured on
the appliance, you cannot bind a policy of the other type to an application unit. For example, if a
default syntax policy is already bound either globally or to a virtual server, you cannot bind a classic
policy to an application unit.

To configure Application Firewall policies for an application unit:

1. Navigate to AppExpert > Applications.

2. In the details pane, in the row for the application unit you want to configure, click the icon pro-
vided in the Application Firewall column.
3. In the Configure Application Firewall Policies dialog box, do one or more of the following,
depending on the configuration tasks you want to perform:
• Click either Classic Expression or Advanced Expression depending on the type of expres-
sion you want to configure for the Application Firewall policy.
Important: This setting also determines what policies are displayed when you want to
insert a policy. For example, if you select
Advanced Expression, when you click
Insert Policy, the list that appears in the
Policy Name column will include only
default syntax policies. You cannot bind policies of both types to an application unit. This
option is not available if a policy of either type is already bound either globally or to a
virtual server.
• To modify an application firewall policy that is already bound to the application unit, click
the name of the policy, and then click Modify Policy. Then, in the Configure Application
Firewall Policy dialog box, modify the policy, and then click OK.
For information about modifying a application firewall policy, see Policies.
• To unbind a policy, click the name of the policy, and then click Unbind Policy.
• To modify the priority assigned to a policy, double-click the priority value, and then enter
a new value.
• To regenerate assigned priorities, click Regenerate Priorities.
• To insert a new policy, click Insert Policy and, in the list that is displayed in the Policy
Name column, click New Policy. Then, in the Create Application Firewall Policy dialog
box, configure the policy, and then click Create.
For information about modifying a application firewall policy, see Policies.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1045

NetScaler 12.0

4. Click Apply Changes, and then click Close.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Create application units

September 24, 2018

Contributed by:
C

You might need to add application units for traffic subsets that are either specific to your web appli-
cation implementation or not defined in the template. When creating an application unit, you must
configure a rule for the application unit.

To create an application unit for the AppExpert application:

1. Navigate to AppExpert > Applications.

2. In the details pane, right-click the application for which you want to add an application unit,
and then click Add.
3. In the Applications page, go to Application Units section and click the pencil icon.

To configure policy expressions for an application unit:

1. Navigate to AppExpert > Applications.

2. In the details pane, right-click the application for which you want to add an application unit,
and then click Add.
3. In the Applications **page, go to Application Units** section and click the **+ **icon. to create
a unit and add policy expressions.
4. To specify the format of the new expression, do one of the following:
a) To specify that you want to configure a classic expression in the Rule box, click Classic
Syntax.
b) To specify that you want to configure an advanced expression in the Rule box, click Default
Syntax.
c) In the Rule box, configure the expression.
5. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1046

NetScaler 12.0

4. AppExpert

Configuring public endpoints for an application

September 24, 2018

Contributed by:
C
To configure public endpoints for an application by using the GUI:
1. Navigate to AppExpert > Applications, select an application entity, and then click Edit.
2. In the Public Endpoint section, click + to configure a new public endpoint.
3. In the Public Endpoint slider, do one of the following:
a) Click New to create a new endpoint.
b) Click Existing Public Endpoint to select an endpoint from the drop-down list.
4. Set the following endpoint parameters:
a) Name
b) IP address
c) Protocol
d) Port
5. Click Continue to configure additional settings such as application units, GSLB server bindings,
policies, profiles, push, traffic settings, and authentication.
6. Click OK and then Done.
7. Click Continue and then Done.
To edit a public endpoint for an application by using the GUI:
Navigate to AppExpert > Applications, select an application, and click Edit. In the Public Endpoint
section, select an endpoint, click the pen icon, and modify the endpoint settings.
To delete a public endpoint for an application by using the GUI:
Navigate to AppExpert > Applications > Public Endpoint, click the pen icon to view the delete icon
next to the entity.
NetScaler’s video tutorials enable you to understand NetScaler features in an easy and simply way.
Watch <https://www.youtube.com/watch?v=z4v-edQiVpw> video to learn how to configure a
public endpoint.
1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1047

NetScaler 12.0

Specifying the Order of Evaluation of Application Units

September 24, 2018

Contributed by:
C

Application unit rules are evaluated in the order in which they are placed in the GUI. The rule that
is configured for the topmost application unit is always configured first, followed by the rule that is
configured for the second topmost application unit, and so on. The default application unit is always
evaluated last.

When a request matches the rule that is configured for an application unit, the request is processed
by the application unit, and no further matching is performed. Therefore, the order of evaluation of
application units becomes an important factor if the traffic subsets for two or more application units
overlap. If the traffic subsets for two or more application units overlap, you must specify the order in
which an incoming request is matched against the application unit rules.

To specify the order of evaluation of application units:

1. Navigate to AppExpert > Applications, select an application and click Edit. In the Application
Unit section, click the Pencil icon and then hover the cursor over the check box to the left of the
name of the application unit. Click the icon that appears next to the check box and hold down
the mouse to drag the application up or down to a new location in the priority list.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring Persistency Groups for Application Units

September 24, 2018

Contributed by:
C

You can configure a persistency group for the application units in an AppExpert application. In the
context of an AppExpert application, a persistency group is a group of application units that you can
treat as a single entity for the purpose of applying common persistence settings. When the application
is exported to an application template file, the persistency group settings are included, and they are
automatically applied to the application units when you import the AppExpert application.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1048

NetScaler 12.0

To configure a persistency group for an application by using the GUI:

1. Navigate to AppExpert > Applications.

2. In the Applications View dialog box, click the name of the application for whose application
units you want to configure a persistency group, and then click Configure Persistency Groups.
3. In the Configure Persistency Groups dialog box, do one of the following:
• To add a persistency group, click Add.
• To modify a persistency group, click Open.
4. In the Create Persistency Group or Configure Persistency Group dialog box, set the following
parameters:
• Group Name—Name of the persistency group. For the NetScaler appliance to recognize
the persistency group as part of the application’s configuration, the name of the AppEx-
pert application must be included in the name of the persistency group, as a prefix. There-
fore, by default, the appliance displays the prefix in the Group Name box, and you cannot
remove that prefix. Enter a name of your choice after the prefix.
• Persistence—Type of persistence for the virtual server. If you select SOURCEIP, in the IPv4
Netmask box, enter a network mask that specifies the number of bits that the appliance
must consider when creating persistence sessions. If you select COOKIEINSERT, in the
Cookie Domain and Cookie Name boxes, specify a domain attribute to send in the Set-
Cookie directive, and a name for the cookie, respectively.
• Timeout—Time period for which a persistence session is in effect.
• Backup Persistence—Type of backup persistence for the group.
• Backup Timeout—Time period, in minutes, for which backup persistence is in effect.
• Application Units—To add an application unit to the persistency group, in the Available
Application Units box, click the application unit, and then click Add. To remove an appli-
cation unit from the persistency group, in the Configured Application Units box, click the
application unit, and then click Remove.
5. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Viewing AppExpert Applications and Configuring Entities by Using the

Application Visualizer

September 24, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1049

NetScaler 12.0

Contributed by:
C

The Visualizer feature shows you a graphical representation of an application’s configuration. It in-
cludes the name of the public endpoint, application units assigned to the public endpoint, and the
number of policies and services bound to the application. You can use the Visualizer to obtain a visual
overview of an AppExpert application’s configuration and configure some of the displayed entities. By
default, the Visualizer displays application units, services, and monitors for the selected application.

To view an AppExpert application by using the Application Visualizer:

1. Navigate to AppExpert > Applications, select an application entity, and click Visualizer.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

AppQoE

September 24, 2018

Contributed by:
C

Application level Quality of Experience (AppQoE) integrates several existing policy-based security fea-
tures of the NetScaler appliance into a single integrated feature that takes advantage of a new queuing
mechanism, fair queuing. Fair queuing manages requests to load-balanced web servers and applica-
tions at the virtual server level instead of at the service level, allowing it to handle queuing of all re-
quests to a web site or application as one group before load balancing, instead of as separate streams
after load balancing.

The features that are integrated into AppQoE are HTTP Denial-of-Service Protection (HDOSP), Priority
Queuing (PQ), and SureConnect. Collectively these services provide protection against a number of
problems:

• Simple overload. Any server, no matter how robust, can accept only a limited number of con-
nections at one time. When a protected web site or application receives too many requests at
once, the Surge Protection feature detects the overload and queues the excess connections til
the server can accept them. The Priority Queuing feature ensures that whoever most needs
access to a resource is provided access without having to wait behind other lower-priority re-
quests. The SureConnect feature displays an alternate web page that notifies users that the
resource that they requested is not available.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1050

NetScaler 12.0

• Denial-of-Service (DOS) attacks. Any public-facing resource is vulnerable to attacks whose

purpose is to bring that service down and deny legitimate users access to it. The Surge Pro-
tection, Priority Queuing, and SureConnect features help manage DOS attacks as well as other
types of high load. In addition, the HTTP Denial-of-Service Protection feature targets DOS at-
tacks against your web sites, sending challenges to suspected attackers and dropping connec-
tions if the clients do not send an appropriate response.

Until the current version of the NetScaler operating system, these features were implemented at the
service level, which means that each service was assigned its own queues. While service-level queues
work, they also have some disadvantages, most of which are due to the NetScaler appliance having
to load balance requests before implementing any of the protection features that rely on queuing.
Implementing protection features before queuing has a number of advantages, some of which are
listed below:

• Absolute priority of connections as configured in the priority queuing feature can be main-
tained.
• Connections are not flushed if a service transitions state, as they are in a service-level queue.
• During periods of high load, such as a denial-of-service attack, HTTP DoS and SureConnect
come into play before load balancing, allowing these features to detect and divert unwanted
or lower-priority traffic from the load balancer before the load balancer must cope with it.

In addition to implementing fair queuing, AppQoE integrates a set of features that each provide a
different set of tools to achieve a common goal: protecting your networked resources from excessive
or inappropriate demand. Putting these features into a common framework enables you to configure
and implement them more easily.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Enabling AppQoE

September 24, 2018

Contributed by:
C

To configure AppQoE, you must first enable the feature.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1051

NetScaler 12.0

To enable AppQoE by using the command line

At the command prompt, type the following commands:

• enable ns feature appqoe

• show ns feature

Example:

1 > enable ns feature appqoe

2 Done
3 > show ns feature
4
5 Feature Acronym Status
6 ------- ------- ------
7 1) Web Logging WL ON
8 2) Surge Protection SP ON
9 3) Load Balancing LB ON
10 ...
11 1) AppQoE AppQoE ON
12 Done

To enable AppQoE by using the GUI

1. Navigate to System > Settings.

2. In the details pane, click Configure Advanced Features.
3. In the Configure Advanced Features dialog box, select the AppQoE check box.
4. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

AppQOE actions

September 24, 2018

Contributed by:
C

After enabling the AppQoE feature, you must configure one or more actions for handling requests.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1052

NetScaler 12.0

Important: No specific individual parameters are required to create an action, but you must
include at least one parameter or you cannot create the action.

To configure an AppQoE action by using the command line

At the command prompt, type the following commands:

• add appqoe action <name> [-priority <priority>] [-respondWith (ACS|

NS)[<customfile>] [-altContentSvcName <string>] [-altContentPath <
string>] [-maxConn <positive_integer>] [-delay <usecs>] [-polqDepth <
positive_integer>] [-priqDepth <positive_integer>] [-dosTrigExpression
<expression>] [-dosAction ( **SimpleResponse** | **HICResponse** )]
• show appqoe action

Example

To configure priority queuing with policy queue depths of 10 and 1000 for medium and lowest priority
queues, respectively:

1 > add appqoe action appqoe-act-basic-prhigh -priority HIGH

2 Done
3
4 > add appqoe action appqoe-act-basic-prmedium -priority MEDIUM -
polqDepth 10
5 Done
6
7 > add appqoe action appqoe-act-basic-prlow -priority LOW -polqDepth
1000
8 Done
9
10 > show appqoe action
11 1) Name: appqoe-act-basic-prhigh
12 ActionType: PRIORITY_QUEUING
13 Priority: HIGH
14 PolicyQdepth: 0
15 Qdepth: 0
16
17 2) Name: appqoe-act-basic-prmedium
18 ActionType: PRIORITY_QUEUING
19 Priority: MEDIUM
20 PolicyQdepth: 10
21 Qdepth: 0
22
23 3) Name: appqoe-act-basic-prlow

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1053

NetScaler 12.0

24 ActionType: PRIORITY_QUEUING
25 Priority: LOW
26 PolicyQdepth: 1000
27 Qdepth: 0
28 Done

To modify an existing AppQoE action by using the command line

At the command prompt, type the following commands:

• set appqoe action <name> [-priority <priority>] [-altContentSvcName <

string>] [-altContentPath <string>] [-polqDepth <positive_integer>] [-
priqDepth <positive_integer>] [-maxConn <positive_integer>] [-delay <
usecs>] [-dosTrigExpression <expression>] [-dosAction ( SimpleResponse
| HICResponse )]
• show appqoe action

To remove an AppQoE action by using the command line

At the command prompt, type the following commands:

• rm appqoe action <name>

• show appqoe action

Parameters for configuring an AppQoE action

• name

A name for the new action, or the name of the existing action that you want to modify. The
name can begin with a letter, number, or the underscore symbol, and can consist of from one to
letters, numbers, and the hyphen (-), period (.) pound (#), space ( ), at sign (@), equals (=), colon
(:), and underscore (_) symbols.

• priority

The priority queue to which the request is assigned. When a protected web server or application
is heavily loaded and cannot accept additional requests, specifies the order in which waiting
requests are to be fulfilled when resources are available. The choices are:

1. HIGH. Fulfills the request as soon as resources are available.

2. MEDIUM. Fulfills the request after it has fulfilled all requests in the HIGH priority queue.
3. LOW. Fulfills the request after it has fulfilled all requests in the HIGH and MEDIUM priority
queues.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1054

NetScaler 12.0

4. LOWEST. Fulfills the request only after it has fulfilled all requests in higher-priority queues.

If priority is not configured, then the NetScaler appliance assigns the request to the LOWEST
priority queue by default.

• respondWith

Configures the NetScaler to take the specified Responder action when the specified threshold
is reached. Must be used with one of the following settings:

– ACS: Serves content from an alternate content service. Threshold: maxConn (maximum
connections) or delay.
– NS: Serves a built-in response from the NetScaler. Threshold: maxConn (maximum con-
nections) or delay.
– NO ACTION: Serves no alternative content. Assigns connections to the LOWEST priority
queue if the maxConn (maximum connections) or delay threshold is reached.

• altContentSvcName

If
-responseWith ACS is specified, the name of the alternative content service, usually an absolute
URL to the web server that hosts the alternate content.

• altContentPath

If
-responseWith ( ACS | NS ) is specified, the path to the alternative content.

• polqDepth

Policy queue depth threshold value for the policy queue associated with this action. When the
number of connections in the policy queue associated with this action increases to the speci-
fied number, subsequent requests are assigned to the LOWEST policy queue. Minimum value:
1 Maximum value: 4,294,967,294

• priqDepth

Policy queue depth threshold value for the specified priority queue. If the number of requests in
the specified queue on the virtual server to which the policy associated with the current action
is bound increases to the specified number, subsequent requests are assigned to the LOWEST
priority queue. Minimum value: 1 Maximum value: 4,294,967,294

• maxConn

The maximum number of connections that can be open for requests that match the policy rule.
Minimum value: 1 Maximum value: 4,294,967,294

• delay

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1055

NetScaler 12.0

The delay threshold, in microseconds, for requests that match the policy rule. If a matching
request has been delayed for longer than the threshold, the
NetScaler appliance performs the specified action. If NO ACTION is specified, then the appliance
assigns requests to the LOWEST priority queue. Minimum value: 1 Maximum value: 599999,999
• dosTrigExpression
Adds an optional second-level check to trigger DoS actions.
• dosAction
Action to take when the ADC determines that it or a protected server is under DoS attack. Possi-
ble values: SimpleResponse, HICResponse.
These values specify HTTP challenge-response methods for validating the authenticity of incoming
requests to mitigate an HTTP-DDoS attack.
In the HTTP challenge-response generation and validation process, AppQoE uses cookies to validate
the client’s response and verify that the client seems to be genuine. When sending a challenge, a
NetScaler appliance generates two cookies:
Header cookie (_DOSQ). Contains client-specific information, so that the NetScaler appliance can ver-
ify the response.
Body cookie (_DOSH). Information used to validate the client machine. The client’s browser (or the
user, in the case of HIC) computes a value for this cookie. The NetScaler appliance compares that
value with the expected value to verify the client.
The information that the appliance sends to the client for computing the _DOSH value is based on the
DoS Action configuration.
1. SimpleResponse: In this case, a NetScaler appliance splits the value and generates a JavaScript
code to combine the final value. A client machine capable of computing the original value is
considered genuine.
2. HICResponse: in this case, a NetScaler appliance generates two single-digit numbers and gen-
erates images for those numbers. Then, using a backpatch framework, the appliance inserts
those images as base64 strings.
Limitations:
1. This is not a trivial CAPTCHA implementation, which is why that term not used.
2. The validation number is based on a NetScaler-generated number that does not change for 120s.
This number should be dynamic or client specific.

To configure an AppQoE action by using the GUI

1. Navigate to App-Expert > AppQoE > Actions.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1056

NetScaler 12.0

2. In the details pane, do one of the following:

• To create a new action, click Add.
• To modify an existing action, select the action, and then click Edit.
3. In the Create AppQoE Action or the Configure AppQoE Action screen, type or select values
for the parameters. The contents of the dialog box correspond to the parameters described in
“Parameters for configuring the AppQoE Action” as follows (asterisk indicates a required param-
eter):
• Name—name
• Action type—respondWith
• Priority—priority
• Policy Queue Depth—polqDepth
• Queue Depth—priqDepth
• DOS Action—dosAction
4. Click Create or OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

AppQoE parameters

September 24, 2018

Contributed by:
C

In the AppQoE parameters, you configure the session life of an AppQoE session, the file name of the
file containing the customized response, and the number of client connections that can be placed in
a queue.

To configure the AppQoE parameter settings by using the command line

At the command prompt, type the following commands:

• set appqoe parameter [-sessionLife <secs>] [-avgwaitingclient <positive_integer

>] [-MaxAltRespBandWidth <positive_integer>] [-dosAttackThresh <positive_integer
>]
• show appqoe parameter

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1057

NetScaler 12.0

Parameters for configuring the AppQoE parameters

• sessionLife

Number of seconds to wait after displaying alternate content before the ADC displays the same
content again. Default value: 300 Maximum Minimum value: 1 Maximum value: 4,294,967,294

• avgwaitingclient

The average number of client requests that can be in the service waiting queue. Default value:
1000000 Maximum value: 4,294,967,294

• MaxAltRespBandWidth

The maximum bandwidth to consume when sending alternate responses. If the maximum is
reached, the ADC quits sending the alternate content til bandwidth consumption drops. Default
value: 100 Minimum value: 1 Maximum value: 4,294,967,294

• dosAtckThrsh

The denial-of-service attack threshold. The number of connections that must be waiting in
queues before the ADC responds with DoS protection measures. Default value: 2000 Minimum
value: 0 Maximum value: 4,294,967,294

To configure the AppQoE parameter settings by using the GUI

1. Navigate to AppExpert > AppQoE.

2. In the details pane, click Configure AppQoE Parameters.
3. In the Configure AppQoE params screen, type or select values for the parameters. The contents
of the dialog box correspond to the parameters described in “Parameters for configuring the
AppQoE Parameters” as follows (asterisk indicates a required parameter):
• Session Life (secs)
• sessionLife
• Average waiting client—avgwaitingclient
• Alternate Response Bandwidth Limit(Mbps) —MaxAltRespBandWidth
• DOS Attack Threshold —dosAttackThresh
4. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1058

NetScaler 12.0

AppQoE Policies

September 24, 2018

Contributed by:
C

To implement AppQoE, you must configure at least one policy to tell your NetScaler how to distinguish
the connections to be queued in a specific queue.

To configure an AppQoE policy by using the command line

At the command prompt, type the following command:

add appqoe policy <name> -rule <expression> -action <string>

Example:

The following example selects requests with a User-Agent header that contains “Android”, and assigns
them to the medium priority queue. These requests come from smartphones and tablets that run the
Google Android operating system.

1 > add appqoe action appqoe-act-primd -priority MEDIUM

2 Done
3 > add appqoe policy appqoe-pol-primd -rule ”HTTP.REQ.HEADER(”User-Agent
”).CONTAINS(”Android”)” -action appqoe-act-primd
4 Done
5 > sh appqoe policy appqoe-pol-primd
6 Name: appqoe-pol-primd
7 Rule: HTTP.REQ.HEADER(”User-Agent”).CONTAINS(”Android”)
8 Action: appqoe-act-primd
9 Hits: 0
10
11 Done

Parameters for configuring an AppQoE policy

• name

A name for the AppQoE policy. The name can begin with a letter, number, or the underscore
symbol, and can consist of from one to
127 letters, numbers, and the hyphen (-), period (.) pound (#), space ( ), at sign (@), equals (=),

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1059

NetScaler 12.0

colon (:), and underscore (_) symbols. You should chose a name that helps identify the type of
action.
• rule
A
NetScaler expression that tells the appliance which connections it should handle. For complete
information about policy expressions, see the
NetScaler Policy Configuration and Reference Guide at .
• action
The AppQoE action to perform when a connection matches the policy.

To configure an AppQoE policy by using the GUI

1. Navigate to App-Expert > AppQoE > Policies.

2. In the details pane, do one of the following:
• To create a new policy, click Add.
• To modify an existing policy, select the policy, and then click Edit.
3. If you are creating a new policy, in the Create AppQoE Policy dialog, in the Name text box, type
a name for your new policy.
The name can begin with a letter, number, or the underscore symbol, and can consist of from
one to 127 letters, numbers, and the hyphen (-), period (.) pound (#), space ( ), at sign (@), equals
(=), colon (:), and underscore (_) symbols. You should chose a name that helps identify the pur-
pose and effect of this policy.
If you are modifying an existing policy, skip this step. You cannot change the name of an existing
policy.
4. In the Action drop-down list, choose the AppQoE action to perform when the policy matches a
connection. Click the plus (+) to open the Add AppQoE Action dialog and add a new action.
5. In the Rule text box, either enter the policy expression directly, or click New to create a policy
expression. If you click New, perform the following steps:
a) In the Create Expression dialog box, click Add.
b) In the Add Expression dialog box, select a common expression from the Frequently Used
Expressions drop-down list, or use the Construct Expression drop-down lists to create the
expression that defines which traffic to filter.
If you choose to create your own expression, you start by selecting the first term from the
first drop-down list on the left side of the Construct Expression area. The choices in that
list are:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1060

NetScaler 12.0

• HTTP: All traffic to port 80 and port 443.

• SYS:
• CLIENT:
• SERVER:
• ANALYTICS:
• TEXT:

The default choice is HTTP. After you make a choice in the first drop-down list (or accept
the default), you can choose the next term in your expression from the drop-down list to
the right of it. The terms in that list and other lists that follow change depending on your
previous choices; the lists offer only terms that are valid choices. Continue to select terms
until you have finished the expression.

Use the Help and Preview Expression areas for assistance when creating the expression.
For a complete description of the available choices, see the NetScaler Policy Configuration
and Reference Guide at .

c) When you have created the expression that you want, click OK. The expression is added in
the Expression text box.

6. Click Create. The expression appears in the Rule text box.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Entity templates

September 24, 2018

Contributed by:
C

An entity template is a collection of configuration information for an individual entity on a NetScaler®

appliance. It provides a specification and a set of defaults for a configurable NetScaler entity, such
as a policy, virtual server, service, or action. By using a template that defines a set of defaults, you
can quickly configure multiple entities that require a similar configuration while eliminating several
configuration steps.

Entity templates are available only in the GUI. You use the NetScaler GUI to create, manage, and use
any type of entity template. You can share entity templates with other administrators and manage

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1061

NetScaler 12.0

local folders that contain the templates. You can also import entity templates from and export entity
templates to your local computer.

Before creating a template, you should be familiar with the configuration of the entity.

Note: You use entity templates to configure individual entities. To configure multiple entities related
to a particular Web application, you must use an application template. For more information, see “
AppExpert Applications and Templates.”

How Entity Templates Work:

When you create a template for a NetScaler entity, you specify default values for the entity. You specify
what values must be read-only, what values must not be displayed, and what values users can config-
ure. You also configure the pages that compose the template import wizard. All the information and
settings you provide are stored in the template file.

When a user imports the entity template to a NetScaler appliance, a wizard guides the user through
the various pages that you configured for the template. The wizard displays the read-only parameter
values and prompts the user to specify values for the configurable parameters. After the user follows
the instructions in the wizard, the appliance creates the entity with the configured values.

For example, you can create an entity template for HTTP services that provides a text box for a service
name and assigns preset values for the service protocol, timeouts, thresholds, and monitors. Later,
when you use the template to create new HTTP services, a wizard prompts you for a service name and
supplies the preset values that you would otherwise have configured manually.

The procedure for creating entity templates for load balancing virtual servers is different than the App-
Expert procedure for creating other entity templates. For more information, see “Creating an Entity
Template.”

In addition, the procedure for using the template to create the load balancing virtual server entity is
different. For more information, see “Creating an Entity from a Template.”

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring an entity template

September 24, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1062

NetScaler 12.0

You can create or modify an entity template either from the AppExpert feature node or from the asso-
ciated NetScaler feature node for the entity. For example, you can create a content switching virtual
server entity template in either the AppExpert feature node or the content switching feature node in
the GUI.
If you create a template that is not based on an existing entity, you can specify the following options
and settings for the template:
• The default value of a parameter.
• Whether the default values are visible to users.
• Whether the default values can be changed by users.
• The number of pages in the entity import wizard, including the page names, text, and available
parameters.
• The entities that must be bound to the entity for which the template is being created.
For example, when you are creating a cache redirection virtual server template, you can specify
the policies that you want to bind to the cache redirection virtual servers that you create from
the template. However, only binding information is included in the template. The bound en-
tities are not included. If the entity template is imported to another NetScaler appliance, the
bound entities must exist on the appliance at import time for the binding to succeed. If none of
the bound entities exist on the target appliance, the entity (for which the template was config-
ured) is created without any bindings. If only a subset of the bound entities exist on the target
appliance, they are bound to the entity that is created from the template.
When you create a template based on an existing entity, the configuration settings of the entity appear
in the template. All bound entities are selected by default, but you can modify bindings as necessary.
As in the case of a template that is not based on an existing entity, only binding information is included
and not the entities. You can either save the template with the existing configuration settings or use
the settings as a basis for creating a new configuration for a template.
1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring variables in load balancing virtual server templates

January 6, 2019
Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1063

NetScaler 12.0

Load balancing virtual server templates support the declaration of variables in the configured load
balancing parameters and in bound policies and actions. The ability to declare variables enables you
to replace preconfigured values with values that suit the environment into which you are importing
the template. The Entity Template Wizard, which appears when you import a template, includes a
Specify Variable Values page on which you can specify appropriate values for the variables that are
configured for the entity template. This wizard page appears only when you import a template that is
configured with existing variables.

As an example, consider the following expression configured for a policy that is bound to a load bal-
ancing virtual server for which you are creating a template. The expression evaluates the value of the
Accept-Language header in an HTTP request.

HTTP.REQ.HEADER(”Accept-Language”).CONTAINS(”en-us”)

If you want the value of the header to be configurable at import time, you can specify the string en-
us as a variable. When importing the template, you can specify a new value for the variable on the
Specify Variable Values page.

After you create a variable, you can do the following:

• Assign additional strings to an existing variable. After you create a variable for a string, you can
select and assign other parts of the same or different expression to the variable. The strings you
assign to a variable need not be the same. At import time, all the strings that are assigned to
the variable are replaced with the value that you provide.
• View the string or strings that are assigned to the variable.
• View a list of all the entities and parameters that use the variable.

To configure variables in a load balancing virtual server template

1. Navigate to Traffic Management > Load Balancing > Virtual Servers

2. In the details pane, right-click the virtual server that you want to export to a template file, and
then click Create Template.

3. In the Create Template dialog box, modify the default template file name if required, specify
the location where you want to save the template, and then click Configure Variables.

4. In the Configure Variables dialog box, click the tab that lists the entity for which you want to
configure a variable, select the entity, and then click Configure Variables.

5. In the Variables for Entity Type: Entity Name dialog box, click the button next to the parameter
value or expression in which you want to create a variable.

6. In the variables for Field Name dialog box, do the following:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1064

NetScaler 12.0

• To create a variable, in the text box that displays the configured expression or value, select
the string that you want to be configurable at import time, and then click Add. In the Cre-
ate Variable dialog box, specify a name and a description for the variable, and then click
Create.

The name of the variable, its value, and the description you provided appear in the Avail-
able Variables listing in the dialog box. The name you provide will be the name of the
associated field in the template import wizard, and the description will appear as alt text
when the user positions the mouse pointer over the field.

• To modify a variable, in the Available Variables list, click the variable, and then click Open.
In the Create Variable dialog box, modify the value and the description, and then click OK.

The new value that you specify will not replace the text selected in the text box that dis-
plays the configured expression or value. However, when you import the template, the
new value will be displayed as the default value for the variable in the template import
wizard.

• To view all the strings that are assigned to a given variable, in the Available Variables listing,
click the name of the variable. The strings that are assigned to the variable are highlighted.

• To view a list of all the parameters, expressions, and actions in which the variable is used,
in the Available Variables listing, click the variable whose references you want to view, and
then click Show References.

• To assign a string to an existing variable, in the text box that displays the expression you
configured, select the string you want to assign to an existing variable, right-click the se-
lection, click Use existing Variable, and then click the name of the variable to which you
want to assign the string.

If a variable has multiple strings assigned to it, when you specify a new value for the vari-
able during import, all strings assigned to the variable are replaced with the new value.

7. Click Close.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Modifying an entity template

September 24, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1065

NetScaler 12.0

Contributed by:
C

You can modify only the parameters, bindings, and pages configured for a template. The name and
location of the template specified when the template was created cannot be changed. The NetScaler
appliance does not provide you with the option of modifying a load balancing virtual server template.

To modify an entity template by using the AppExpert feature node

1. Navigate to AppExpert > Templates.

2. In the details pane, on the Entity Templates tab, select the template you want to change, and
then click Open.
3. In the Modify…Template dialog box, follow the instructions to modify a template.
4. Click Finish, and then click Exit.

To modify an entity template by using its corresponding feature node

1. Navigate to Traffic Management, select the feature (for example, Content Switching), and then
select the entity (for example, Virtual Servers) for which you want to modify the entity template.
2. At the top of the details pane, click Entity Templates, and then click Manage Template.
3. In the** Manage <feature entity name> Entity Templates** dialog box, select the template
that you want to modify, and then click Modify.
4. In the Modify <template name> Template dialog box, follow the instructions to modify a tem-
plate.
5. Click Finish, and then click Exit.
6. Click Close.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Deleting an entity template

September 24, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1066

NetScaler 12.0

Deleting an entity template does not affect any objects that have been created by using the template.
You can delete a load balancing virtual server template only from the AppExpert feature node.

To delete an entity template by using the AppExpert feature node

1. Navigate to AppExpert > Templates.

2. In the details pane, on the Entity Templates tab, click the template you want to delete, and
then click Remove.

To delete an entity template by using its corresponding feature node

1. Navigate to Traffic Management, and select the feature (for example, Content Switching) and
then select the entity (for example, Virtual Servers), for which you want to delete the entity tem-
plate.
2. At the top of the details pane, click Entity Templates, and then click Manage Template.
3. In the Manage…Entity Templates dialog box, select the template that you want to delete, and
then click Delete.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Creating an entity from a template

September 24, 2018

Contributed by:
C

You can create an entity from an entity template either from the AppExpert feature node in the
NetScaler GUI or from the NetScaler feature node that corresponds to the type of entity that you
want to create. For example, you can create a content switching virtual server from a template with
either the AppExpert feature node or the content switching feature node in the GUI.

The procedure for creating a load balancing virtual server from a template is different than the App-
Expert procedure for creating other entities from templates.

After you create an instance of an entity using an entity template, you can configure it in the same way
that you would any other object of that type, such as by using the GUI or the command line.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1067

NetScaler 12.0

To create an entity from a template by using the AppExpert feature node

1. Navigate to AppExpert > Templates.

2. In the details pane, do one of the following:
a) To create any entity other than a load balancing virtual server from a template, on the En-
tity Templates tab, click the template that you want to use, and then click Use Template.
b) To create a load balancing virtual server from a template, on the LB Templates tab, click
the template that you want to use, and then click Use Template.
3. In the <Entity Template Name> wizard, follow the instructions to create the entity on the
NetScaler.
4. Click Finish, and then click Exit.

To create an entity from a template by using its corresponding feature node

1. Navigate to Traffic Management, and expand a feature node (for example, Content Switching),
and then click an entity subnode (for example, Virtual Servers).

2. At the top of the details pane, click Entity Templates, and then click Use Template.

3. Click the name of the template that you want to use.

4. In the Use <template name> Template wizard, follow the instructions to create the entity.

Only templates that match the current context are displayed. For example, in the details pane
for content switching virtual servers, only entity templates for content switching virtual servers
appear, if configured.

5. Click Finish, and then click Exit.

To create a load balancing virtual server by using a load balancing virtual server
template

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.

2. In the details pane, click Use Template.

3. In the Entity Template Wizard, follow the instructions to create a load balancing virtual server
on the NetScaler.

Only templates that match the current context are displayed. For example, when you click
Browse (Appliance), only entity templates for load balancing virtual servers appear, if config-
ured.

4. Click Finish, and then click Exit.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1068

NetScaler 12.0

Note: The Entity Template Wizard includes a Specify Variable Values page on which you
can specify new values for variables. For more information about configuring variables in
load balancing virtual server templates, see Configuring Variables in Load Balancing Vir-
tual Server Templates.”

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Managing entity template folders

September 24, 2018

Contributed by:
C

You can organize only load balancing virtual server template folders.

To organize load balancing virtual server template folders

1. Navigate to AppExpert > Templates > LB Templates.

2. In the Manage LB Templates dialog box do one of the following:

• To change the name of a folder, select the folder and click Rename.

You can also click the folder that you want to rename, and then press F2. You cannot re-
name the top-level default folder.

To remove the folder, select the folder and click Delete.

1 You can also click the folder that you want to remove, and then
press the Delete key. You cannot remove the top-level default
folder.

3. Click Close.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1069

NetScaler 12.0

Uploading and downloading entity templates

September 28, 2018

Contributed by:
C

You can import the entity templates that are stored on your local computer. You can also download
entity templates from the NetScaler appliance to your local computer and then import them to other
NetScaler appliances.

To upload an entity template to the NetScaler appliance

1. Navigate to Traffic Management, and expand a feature node (for example, Content Switching),
and then click a subnode (for example, Virtual Servers) for which you want to upload an entity
template.
2. At the top of the details pane, click Entity Templates, and then click Manage Template.
3. In the Manage…Entity Templates dialog box, click the top-level folder, and then click Upload.
4. In the Upload Entity Template dialog box, navigate to the template file that you want to upload,
and then click Select.
5. Click Close.

To download an entity template from the NetScaler appliance

1. Navigate to Traffic Management, and expand a feature node (for example, Content Switching),
and then click a subnode (for example, Virtual Servers) for which you want to upload an entity
template.
2. At the top of the details pane, click Entity Templates, and then click Manage Template.
3. In the Manage…Entity Templates dialog box, click the template that you want to download,
and then click Download.
4. In the Download Entity Template dialog box, navigate to the location at which you want to
save the template on your local computer, enter a file name, and then click Save.
5. Click Close.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1070

NetScaler 12.0

Understanding load balancing entity templates and deployment files

September 24, 2018

Contributed by:
C

Load balancing entity templates are created in the same way that NetScaler application templates are
created. When you export a load balancing virtual server to a template file, the following two files are
automatically created:

• Load balancing virtual server template file. Contains XML elements that store the values of
the parameters that are configured for the load balancing virtual server. The file also contains
XML elements for storing information about bound policies.
• Deployment file. Contains XML elements that store deployment-specific information such as
services, service groups, and configured variables.

In the template and deployment files, each unit of configuration information is encapsulated in a spe-
cific XML element that is meant for that unit type. For example, the load balancing method parameter,
lbMethod, is encapsulated within the
<lbmethod> and
<lbmethod> tags.

Note: After you export a load balancing virtual server, you can add elements, remove elements, and
modify existing elements before importing the configuration information to a NetScaler appliance.

Example of a load balancing virtual server template

Following is an example of a template file that was created from a load balancing virtual server called
“Lbvip”:

1 <?xml version=”1.0” encoding=”UTF-8” ?>

2 <template>
3 <template_info>
4 <entity_name>Lbvip</entity_name>
5 <version_major>10</version_major>
6 <version_minor>0</version_minor>
7 <build_number>40.406</build_number>
8 </template_info>
9 <entitytemplate>
10 <lbvserver_list>
11 <lbvserver>
12 <name>Lbvip</name>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1071

NetScaler 12.0

13 <servicetype>HTTP</servicetype>
14 <ipv46>0.0.0.0</ipv46>
15 <ipmask>*</ipmask>
16 <port>0</port>
17 <range>1</range>
18 <persistencetype>NONE</persistencetype>
19 <timeout>2</timeout>
20 <persistencebackup>NONE</persistencebackup>
21 <backuppersistencetimeout>2</backuppersistencetimeout>
22 <lbmethod>LEASTCONNECTION</lbmethod>
23 <persistmask>255.255.255.255</persistmask>
24 <v6persistmasklen>128</v6persistmasklen>
25 <pq>OFF</pq>
26 <sc>OFF</sc>
27 <m>IP</m>
28 <datalength>0</datalength>
29 <dataoffset>0</dataoffset>
30 <sessionless>DISABLED</sessionless>
31 <state>ENABLED</state>
32 <connfailover>DISABLED</connfailover>
33 <clttimeout>180</clttimeout>
34 <somethod>NONE</somethod>
35 <sopersistence>DISABLED</sopersistence>
36 <sopersistencetimeout>2</sopersistencetimeout>
37 <redirectportrewrite>DISABLED</redirectportrewrite>
38 <downstateflush>DISABLED</downstateflush>
39 <gt2gb>DISABLED</gt2gb>
40 <ipmapping>0.0.0.0</ipmapping>
41 <disableprimaryondown>DISABLED</disableprimaryondown>
42 <insertvserveripport>OFF</insertvserveripport>
43 <authentication>OFF</authentication>
44 <authn401>OFF</authn401>
45 <push>DISABLED</push>
46 <pushlabel>none</pushlabel>
47 <l2conn>OFF</l2conn>
48 <appflowlog>DISABLED</appflowlog>
49 <icmpvsrresponse>PASSIVE</icmpvsrresponse>
50 <lbvserver_cmppolicy_binding_list>
51 <lbvserver_cmppolicy_binding>
52 <name>Lbvip</name>
53 <policyname>NOPOLICY-COMPRESSION</policyname>
54 <priority>100</priority>
55 <gotopriorityexpression>END</gotopriorityexpression>
56 <bindpoint>REQUEST</bindpoint>
57 </lbvserver_cmppolicy_binding>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1072

NetScaler 12.0

58 </lbvserver_cmppolicy_binding_list>
59 </lbvserver>
60 </lbvserver_list>
61 </entitytemplate>
62 </template>

Example of a deployment file

Following is the deployment file associated with the virtual server in the preceding example:

1 <?xml version=”1.0” encoding=”UTF-8” ?>

2 <template_deployment>
3 <template_info>
4 <entity_name>Lbvip</entity_name>
5 <version_major>10</version_major>
6 <version_minor>0</version_minor>
7 <build_number>40.406</build_number>
8 </template_info>
9 <service_list>
10 <service>
11 <ip>1.2.3.4</ip>
12 <port>80</port>
13 <servicetype>HTTP</servicetype>
14 </service>
15 </service_list>
16 <servicegroup_list>
17 <servicegroup>
18 <name>svcgrp</name>
19 <servicetype>HTTP</servicetype>
20 <servicegroup_servicegroupmember_binding_list>
21 <servicegroup_servicegroupmember_binding>
22 <ip>1.2.3.90</ip>
23 <port>80</port>
24 </servicegroup_servicegroupmember_binding>
25 <servicegroup_servicegroupmember_binding>
26 <ip>1.2.8.0</ip>
27 <port>80</port>
28 </servicegroup_servicegroupmember_binding>
29 <servicegroup_servicegroupmember_binding>
30 <ip>1.2.8.1</ip>
31 <port>80</port>
32 </servicegroup_servicegroupmember_binding>
33 <servicegroup_servicegroupmember_binding>
34 <ip>1.2.9.0</ip>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1073

NetScaler 12.0

35 <port>80</port>
36 </servicegroup_servicegroupmember_binding>
37 </servicegroup_servicegroupmember_binding_list>
38 </servicegroup>
39 </servicegroup_list>
40 </template_deployment>

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

HTTP callouts

September 24, 2018

Contributed by:
C

For certain types of requests, or when certain criteria are met during policy evaluation, you might want
to stall policy evaluation briefly, retrieve information from a server, and then perform a specific action
that depends on the information that is retrieved. At other times, when you receive certain types of
requests, you might want to update a database or the content hosted on a Web server. HTTP callouts
enable you to perform all these tasks.

An HTTP callout is an HTTP or HTTPS request that the NetScaler appliance generates and sends to an
external application when certain criteria are met during policy evaluation. The information that is
retrieved from the server can be analyzed by default syntax policy expressions, and an appropriate
action can be performed. You can configure HTTP callouts for HTTP content switching, TCP content
switching, rewrite, responder, and for the token-based method of load balancing.

Before you configure an HTTP callout, you must set up an application on the server to which the call-
out will be sent. The application, which is called the HTTP callout agent , must be configured to re-
spond to the HTTP callout request with the required information. The HTTP callout agent can also
be a Web server that serves the data for which the NetScaler appliance sends the callout. You must
make sure that the format of the response to an HTTP callout does not change from one invocation
to another.

After you set up the HTTP callout agent, you configure the HTTP callout on the NetScaler appliance.
Finally, to invoke the callout, you include the callout in a default syntax policy in the appropriate
NetScaler feature and then bind the policy to the bind point at which you want the policy to be evalu-
ated.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1074

NetScaler 12.0

After you have configured the HTTP callout, you must verify the configuration to make sure that the
callout is working correctly.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

How an HTTP callout works

January 6, 2019

Contributed by:
C

When the NetScaler appliance receives a client request, the appliance evaluates the request against
the policies bound to various bind points. During this evaluation, if the appliance encounters the
HTTP callout expression, SYS.HTTP_CALLOUT(<name>), it stalls policy evaluation briefly and sends a
request to the HTTP callout agent by using the parameters configured for the specified HTTP callout.
Upon receiving the response, the appliance inspects the specified portion of the response, and then
either performs an action or evaluates the next policy, depending on whether the evaluation of the
response from the HTTP callout agent evaluates to TRUE or FALSE, respectively. For example, if the
HTTP callout is included in a responder policy, if the evaluation of the response evaluates to TRUE,
the appliance performs the action associated with the responder policy.

If the HTTP callout configuration is incorrect or incomplete, or if the callout invokes itself recursively,
the appliance raises an UNDEF condition, and updates the undefined hits counter.

The following figure illustrates the working of an HTTP callout that is invoked from a globally bound
responder policy. The HTTP callout is configured to include the IP address of the client that is asso-
ciated with an incoming request. When the NetScaler appliance receives a request from a client, the
appliance generates the callout request and sends it to the callout server, which hosts a database of
blacklisted IP addresses and an HTTP callout agent that checks whether the client’s IP address is listed
in the database. The HTTP callout agent receives the callout request, checks whether the client’s IP ad-
dress is listed, and sends a response that the NetScaler appliance evaluates. If the response indicates
that the client’s IP address is not blacklisted, the appliance forwards the response to the configured
service. If the client’s IP address is blacklisted, the appliance resets the client connection

Figure 1. HTTP Callout Entity Model

1.
2. Citrix ADC

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1075

NetScaler 12.0

3. NetScaler 12.0
4. AppExpert

Notes on the format of HTTP requests and responses

September 24, 2018

Contributed by:
C

The NetScaler appliance does not check for the validity of the HTTP callout request. Therefore, before
you configure HTTP callouts, you must know the format of an HTTP request. You must also know the
format of an HTTP response, because configuring an HTTP callout involves configuring expressions
that evaluate the response from the HTTP callout agent.

This section includes the following sections:

• Format of an HTTP Request

• Format of an HTTP Response

Format of an HTTP request

An HTTP request contains a series of lines that each end with a carriage return and a line feed, repre-
sented as either <CR><LF> or \r\n.

The first line of a request (the message line ) contains the HTTP method and target. For example, a
message line for a GET request contains the keyword GET and a string that represents the object that
is to be fetched, as shown in the following example:

1 GET /mysite/mydirectory/index.html HTTP/1.1\r\n

The rest of the request contains HTTP headers, including a required Host header and, if applicable, a
message body.

The request ends with a bank line (an extra <CR><LF> or \r\n).

Following is an example of a request:

1 Get /mysite/index.html HTTP/1.1\r\n

2 Host: 10.101.101.10\r\n
3 Accept: */*\r\n
4 \r\n

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1076

NetScaler 12.0

Format of an HTTP Response

An HTTP response contains a status message, response HTTP headers, and the requested object or, if
the requested object cannot be served, an error message.

Following is an example of a response:

1 HTTP/1.1 200 OK\r\n

2 Content-Length: 55\r\n
3 Content-Type: text/html\r\n
4 Last-Modified: Wed, 12 Aug 1998 15:03:50 GMT\r\n
5 Accept-Ranges: bytes\r\n
6 ETag: “ 04f97692cbd1:377 ” \r\n
7 Date: Thu, 19 Jun 2008 19:29:07 GMT\r\n
8 \r\n
9 <55-character response>

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring an HTTP callout

November 2, 2018

Contributed by:
C

When configuring an HTTP callout, you specify the type of request (HTTP or HTTPS), destination and
format of the request, the expected format of the response, and, finally, the portion of the response
that you want to analyze.

For the destination, you either specify the IP address and port of the HTTP callout agent or engage
a load balancing, content switching, or cache redirection virtual server to manage the HTTP callout
requests. In the first case, the HTTP callout requests will be sent directly to the HTTP callout agent. In
the second case, the HTTP callout requests will be sent to the virtual IP address (VIP) of the specified
virtual server. The virtual server will then process the request in the same way as it processes a client
request. For example, if you expect a large number of callouts to be generated, you can configure
instances of the HTTP callout agent on multiple servers, bind these instances (as services) to a load
balancing virtual server, and then specify the load balancing virtual server in the HTTP callout con-

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1077

NetScaler 12.0

figuration. The load balancing virtual server then balances the load on those configured instances as
determined by the load balancing algorithm.

For the format of the HTTP callout request, you can specify the individual attributes of the HTTP call-
out request (an attribute-based HTTP callout), or you can specify the entire HTTP callout request as
a default syntax expression (an expression-based HTTP callout).

Note: The appliance does not check for the validity of the request. You must make sure that the re-
quest is a valid request. An incorrect or incomplete HTTP callout configuration results in a runtime
UNDEF condition that is not associated with an action. The UNDEF condition merely updates the Un-
defined Hits counter, which enables you to troubleshoot an incorrectly configured HTTP callout. How-
ever, the appliance parses the HTTP callout request to enable you to configure certain
NetScaler features for the callout. This can lead to an HTTP callout invoking itself. For information
about callout recursion and how you can avoid it, see “
Avoiding HTTP Callout Recursion.”

Finally, regardless of whether you use HTTP request attributes or an expression to define the format
of the HTTP callout request, you must specify the format of the response from the HTTP callout agent
and the portion of the response that you want to evaluate. The response can be a Boolean value, a
number, or text. The portion of the response that you want to evaluate is specified by an expression.
For example, if you specify that the response contains text, you can use HTTP.RES.BODY(<unit>) to
specify that the appliance must evaluate only the first <unit> bytes of the response from the callout
agent.

At the command line, you first create an HTTP callout by using the
add command. When you add a callout, all parameters are set to a default value of NONE, except the
HTTP method, which is set to a default value of GET. You then configure the callout’s parameters by
using the set command. The
set command is used to configure both types of callouts (attribute-based and expression-based). The
difference lies in the parameters that are used for configuring the two types of callouts. Accordingly,
the command-line instructions that follow include a
set command for configuring an attribute-based callout and a
set command for configuring an expression-based callout. In the GUI, all of these configuration tasks
are performed in a single dialog box.

Note: Before you put an HTTP callout into a policy, you can modify all configured parameters except
the return type. Once an HTTP callout is in a policy, you cannot completely modify an expression that
is configured in the callout. For example, you cannot change

1 HTTP.REQ.HEADER(”myval”) to
2 CLIENT.IP.SRC. However, you can modify the operators and arguments that
are passed to the expression. For example, you can change
3 HTTP.REQ.HEADER(”myVal1”) to
4 HTTP.REQ.HEADER(”myVal2”), or

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1078

NetScaler 12.0

5 HTTP.REQ.HEADER(”myVal”) to
6 HTTP.REQ.HEADER(”myVal”).AFTER_STR(<string>). If the set command fails,
create a new HTTP callout.

HTTP callout configuration involves configuring default syntax expressions.

To configure an HTTP callout by using the command line interface

At the command prompt, do the following:

1. Create a HTTP callout.

add policy httpCallout <name>

1 **Example**

1 add policy httpCallout mycallout

1. Configure the details of the HTTP callout.

• To configure an attribute-based HTTP callout, type:

1 set policy httpCallout <name> [-IPAddress <ip_addr|ipv6_addr|*>] [-port

<port|*>] [-vServer <string>] [-returnType <returnType>] [-
httpMethod ( GET | POST )] [-hostExpr <string>] [-urlStemExpr <
string>] [-headers <name(value)> ...] [-parameters <name(value)>
...] [-resultExpr <string>]

Example:

1 > set policy httpCallout mycallout -vserver lbv1 -returnType num -

httpMethod GET -hostExpr ’http.req.header(”Host”)’
2 -urlStemExpr ”http.req.url” -parameters Name(”My Name”) -headers Name(”
MyHeader”)
3 -resultExpr ”http.res.body(10000).length”

To configure an expression-based HTTP callout, type:

1 set policy httpCallout <name> [-vServer <string>] [-returnType <

returnType>] [-httpMethod ( GET | POST )] [-fullReqExpr <string>] [-
resultExpr <string>]

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1079

NetScaler 12.0

1 > set policy httpCallout mycallout1 -vserver lbv1 -returnType num -

httpMethod GET
2 -fullReqExpr q{
3 ”GET ” + http.req.url + ”HTTP/” + http.req.version.major + ”.” + http.
req.version.minor.sub(1)+
4 ”r\nHost:10.101.10.10\r\nAccept: */*\r\n\r\n” }

3. Verify the configurations of the HTTP callout.

1 show policy httpCallout <name>

To configure an HTTP callout by using the GUI

1. Navigate to AppExpert > HTTP Callouts.

2. In the details pane, click Add.
3. In the Create HTTP Callout dialog box, configure the parameters of the HTTP callout. For a
description of the parameter, hover the mouse cursor over the check box.
4. Click Create and then click Close.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Verifying the Configuration

January 6, 2019

Contributed by:
C

For an HTTP callout to work correctly, all the HTTP callout parameters and the entities associated
with the callout must be configured correctly. While the NetScaler appliance does not check the va-
lidity of the HTTP callout parameters, it indicates the state of the bound entities, namely the server or
virtual server to which the HTTP callout is sent. The following table lists the icons and describes the
conditions under which the icons are displayed.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1080

NetScaler 12.0

Icon Indicates that

The state of the server that hosts the HTTP

callout agent, or the load balancing, content
switching, or cache redirection virtual server to
which the HTTP callout is sent is UP.
The state of the server that hosts the HTTP
callout agent, or the load balancing, content
switching, or cache redirection virtual server to
which the HTTP callout is sent is OUT OF
SERVICE.
The state of the server that hosts the HTTP
callout agent, or the load balancing, content
switching, or cache redirection virtual server to
which the HTTP callout is sent is DOWN.

Table 1. Icons That Indicate the States of Entities Bound to an HTTP Callout

For an HTTP callout to function correctly, the icon must be green at all times. If the icon is not green,
check the state of the callout server or virtual server to which the HTTP callout is sent. If the HTTP
callout is not working as expected even though the icon is green, check the parameters configured for
the callout.

You can also verify the configuration by sending test requests that match the policy from which the
HTTP callout is invoked, checking the hits counter for the policy and the HTTP callout, and verifying
the responses that the NetScaler appliance sends to the client.

Note: An HTTP callout can sometimes invoke itself recursively a second time. If this happens, the hits
counter is incremented by two counts for each callout that is generated by the appliance. For the hits
counter to display the correct value, you must configure the HTTP callout in such a way that it does not
invoke itself a second time. For more information about how you can avoid HTTP callout recursion,
see
Avoiding HTTP Callout Recursion.

To view the hits counter for an HTTP callout

1. Navigate to AppExpert > HTTP Callouts.

2. In the details pane, click the HTTP callout for which you want to view the hits counter, and then
view the hits in the Details area.

1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1081

NetScaler 12.0

2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Invoking an HTTP Callout

September 24, 2018

Contributed by:
C

After you configure an HTTP callout, you invoke the callout by including the SYS.HTTP_CALLOUT(<
name>) expression in a default syntax policy rule. In this expression, <name> is the name of the HTTP
callout that you want to invoke.

You can use default syntax expression operators with the callout expression to process the response
and then perform an appropriate action. The return type of the response from the HTTP callout agent
determines the set of operators that you can use on the response. If the part of the response that you
want to analyze is text, you can use a text operator to analyze the response. For example, you can use
the CONTAINS(<string>) operator to check whether the specified portion of the response contains a
particular string, as in the following example:

1 SYS.HTTP_CALLOUT(mycallout).contains(”Good IP address”)

If you use the preceding expression in a responder policy, you can configure an appropriate responder
action.

Similarly, if the part of the response that you want to evaluate is a number, you can use a numeric
operator such as GT(int). If the response contains a Boolean value, you can use a Boolean operator.

Note: An HTTP callout can invoke itself recursively. HTTP callout recursion can be avoided by com-
bining the HTTP callout expression with a default syntax expression that prevents recursion. For in-
formation about how you can avoid HTTP callout recursion, see
Avoiding HTTP Callout Recursion.

You can also cascade HTTP callouts by configuring policies that each invoke a callout after evaluating
previously generated callouts. In this scenario, after one policy invokes a callout, when the NetScaler
appliance is parsing the callout before sending the callout to the callout server, a second set of policies
can evaluate the callout and invoke additional callouts, which can in turn be evaluated by a third set
of policies, and so on. Such an implementation is described in the following example.

First, you could configure an HTTP callout called myCallout1, and then configure a responder policy,
Pol1, to invoke myCallout1. Then, you could configure a second HTTP callout, myCallout2, and a re-

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1082

NetScaler 12.0

sponder policy, Pol2. You configure Pol2 to evaluate myCallout1 and invoke myCallout2. You bind
both responder policies globally.
To avoid HTTP callout recursion, myCallout1 is configured with a unique custom HTTP header called
“Request1.” Pol1 is configured to avoid HTTP callout recursion by using the default syntax expression,

1 HTTP.REQ.HEADER(”Request1”).EQ(”Callout Request”).NOT.

Pol2 uses the same default syntax expression, but excludes the .NOT operator so that the policy eval-
uates myCallout1 when the NetScaler appliance is parsing it. Note that myCallout2 identifies its own
unique header called “Request2,” and Pol2 includes a default syntax expression to prevent myCallout2
from invoking itself recursively.
Example:

1 > add policy httpCallout myCallout1

2
3 Done
4
5 > set policy httpCallout myCallout1 -IPAddress 10.102.3.95 -port 80 -
returnType TEXT -hostExpr
6 ””10.102.3.95”” -urlStemExpr ”\”/cgi-bin/check_clnt_from_database.pl\”
” -headers Request1
7 (”Callout Request”) -parameters cip(CLIENT.IP.SRC) -resultExpr ”HTTP.
RES.BODY(100)”
8
9 Done
10
11 > add responder policy Pol1 ”HTTP.REQ.HEADER(\”Request1\”).EQ(\”Callout
Request\”).NOT &&
12 SYS.HTTP_CALLOUT(myCallout1).CONTAINS(\”IP Matched\”)” RESET
13
14 Done
15
16 > bind responder global Pol1 100 END -type OVERRIDE
17
18 Done
19
20 > add policy httpCallout myCallout2
21
22 Done
23
24 > set policy httpCallout myCallout2 -IPAddress 10.102.3.96 -port 80 -
returnType TEXT -hostExpr
25 ”\”10.102.3.96\”” -urlStemExpr ”\”/cgi-bin/
check_clnt_location_from_database.pl\”” -headers Request2

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1083

NetScaler 12.0

26 (”Callout Request”) -parameters cip(CLIENT.IP.SRC) -resultExpr ”HTTP.

RES.BODY(200)”
27
28 Done
29
30 > add responder policy Pol2 ”HTTP.REQ.HEADER(\”Request2\”).EQ(\”Callout
Request\”).NOT &&
31 HTTP.REQ.HEADER(\”Request1\”).EQ(\”Callout Request\”) && SYS.
HTTP_CALLOUT(myCallout2).CONTAINS
32 (\”APAC\”)” RESET
33
34 Done
35
36 > bind responder global Pol2 110 END -type OVERRIDE
37
38 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Avoiding HTTP callout recursion

September 24, 2018

Contributed by:
C

Even though the NetScaler appliance does not check for the validity of the HTTP callout request, it
parses the request once before it sends the request to the HTTP callout agent. This parsing allows
the appliance to treat the callout request as any other incoming request, which in turn allows you
to configure several useful NetScaler features (such as integrated caching, SureConnect, and Priority
Queuing) to work on the callout request.

However, during this parsing, the HTTP callout request can hit the same policy and therefore invoke
itself recursively. The appliance detects the recursive invocation and raises an undefined (UNDEF)
condition. However, the recursive invocation results in the policy and HTTP callout hit counters being
incremented by two counts each instead of one count each.

To prevent a callout from invoking itself, you must identify at least one unique characteristic of the
HTTP callout request, and then exclude all requests with this characteristic from being processed by

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1084

NetScaler 12.0

the policy rule that invokes the callout. You can do so by including another default syntax expression
in the policy rule. The expression must precede the
SYS.HTTP_CALLOUT(<name>) expression so that it is evaluated before the callout expression is eval-
uated. For example:

1 <Expression that prevents callout recursion> && SYS.HTTP_CALLOUT(<name

>)

When you configure a policy rule in this way, when the appliance generates the request and parses it,
the compound rule evaluates to FALSE, the callout is not generated a second time, and the hit counters
are incremented correctly.

One way by which you can assign a unique characteristic to an HTTP callout request is to include a
unique custom HTTP header when you configure the callout. Following is an example of an HTTP
callout called “myCallout.” The callout generates an HTTP request that checks whether a client’s IP
address is present in a database of blacklisted IP addresses. The callout includes a custom header
called “Request,” which is set to the value “Callout Request.” A globally bound responder policy,
“Pol1,” invokes the HTTP callout but excludes all requests whose Request header is set to this value,
thus preventing a second invocation of myCallout. The expression that prevents a second invocation
is HTTP.REQ.HEADER(\“Request\”).EQ(\“Callout Request\”).NOT.

Example:

1 > add policy httpCallout myCallout

2 Done
3
4 > set policy httpCallout myCallout -IPAddress 10.102.3.95 -port 80 -
returnType TEXT -hostExpr ”\”10.102.3.95\”” -urlStemExpr ”\”/cgi-bin
/check_clnt_from_database.pl\”” -headers Request(”Callout Request”)
-parameters cip(CLIENT.IP.SRC) -resultExpr ”HTTP.RES.BODY(100)”
5 Done
6
7 > add responder policy Pol1 ”HTTP.REQ.HEADER(\”Request\”).EQ(\”Callout
Request\”).NOT && SYS.HTTP_CALLOUT(myCallout).CONTAINS(\”IP Matched
\”)” RESET
8 Done
9
10 > bind responder global Pol1 100 END -type OVERRIDE
11 Done

Note:
You can also configure an expression to check whether the URL of the request includes the URL
stem expression that is configured for the HTTP callout. If you want to implement this scenario,

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1085

NetScaler 12.0

make sure that the HTTP callout agent is dedicated to respond only to HTTP callouts and not to
other client requests directed through the appliance. If the HTTP callout agent is an application
or Web server that serves other client requests, such an expression will prevent the appliance
from processing those client requests. Instead, use a unique custom header as described earlier.
1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Caching HTTP Callout Responses

September 24, 2018

Contributed by:
C

For improved performance while using callouts, you can use the integrated caching feature to cache
callout responses. The responses are stored in an integrated caching content group named callout-
ContentGroup for a specified time duration.

Note: To cache callout responses, make sure that the integrated caching feature is enabled.

To set the cache duration by using the command line interface

At the command prompt, type:

set policy httpCallout <name> -cacheForSecs <secs>

Example:

1 > set httpcallout httpcallout1 -cacheForSecs 120

To set the cache duration by using the GUI

1. Navigate to AppExpert > **HTTP Callouts.

2. In the details pane, select the HTTP callout for which you want to set the cache duration and
click Open.
3. In the Configure HTTP Callout dialog box, specify the Cache Expiration Time.
4. Verify that you have entered the correct time duration, and then click OK.

1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1086

NetScaler 12.0

2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Use Case: Filtering Clients by Using an IP Blacklist

January 6, 2019

Contributed by:
C

May 24, 2018

HTTP callouts can be used to block requests from clients that are blacklisted by the administrator.
The list of clients can be a publicly known blacklist, a blacklist that you maintain for you organization,
or a combination of both.

The NetScaler appliance checks the IP address of the client against the pre-configured blacklist and
blocks the transaction if the IP address has been blacklisted. If the IP address is not in the list, the
appliance processes the transaction.

To implement this configuration, you must perform the following tasks:

1. Enable responder on the NetScaler appliance.

2. Create an HTTP callout on the NetScaler appliance and configure it with details about the exter-
nal server and other required parameters.
3. Configure a responder policy to analyze the response to the HTTP callout, and then bind the
policy globally.
4. Create an HTTP callout agent on the remote server.

Enabling Responder

You must enable responder before you can use it.

To enable responder by using the GUI

1. Make sure that you have installed the responder license.

2. In the GUI, expand AppExpert, and right-click Responder, and then click Enable Responder fea-
ture.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1087

NetScaler 12.0

Creating an HTTP Callout on the NetScaler Appliance

Create an HTTP callout, HTTP_Callout, with the parameter settings shown in the following table. For
more information about creating an HTTP callout, see
Configuring an HTTP Callout pdf.

Configuring a Responder Policy and Binding it Globally

After you configure the HTTP callout, verify the callout configuration, and then configure a responder
policy to invoke the callout. While you can create a responder policy in the
Policies sub-node and then bind it globally by using the
Responder Policy Manager, this demonstration uses the
Responder Policy Manager to create the responder policy and bind the policy globally.

To create a responder policy and bind it globally by using the GUI

1. Navigate to AppExpert > Responder.

2. In the details pane, under Policy Manager, click Policy Manager.
3. In the Responder Policy Manager dialog box, click Override Global.
4. Click Insert Policy, and then, under Policy Name, click **New Policy.
5. In the Create Responder Policy dialog box, do the following:
a) In Name, type PolicyResponder1.
b) In Action, select RESET.
c) In Undefined-Result Action, select Global undefined-result action.
d) In Expression, type the following default syntax expression:

1 ”HTTP.REQ.HEADER(\”Request\”).EQ(\”Callout Request\”).NOT &&

SYS.HTTP_CALLOUT(HTTP_Callout).CONTAINS(\”IP Matched\”)”

e) Click Create, and then click Close.

6. Click Apply Changes, and then click Close.

Creating an HTTP Callout Agent on the Remote Server

You must now create an HTTP callout agent on the remote callout server that will receive callout re-
quests from the NetScaler appliance and respond appropriately. The HTTP callout agent is a script
that is different for each deployment and must be written with the server specifications in mind, such
as the type of database and the scripting language supported.

Following is a sample callout agent that verifies whether the given IP address is part of an IP blacklist.
The agent has been written in the Perl scripting language and uses a MYSQL database.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1088

NetScaler 12.0

The following CGI script checks for a given IP address on the callout server.

1 #!/usr/bin/perl -w
2 print ”Content-type: text/html\n\n”;
3 use DBI();
4 use CGI qw(:standard);
5 #Take the Client IP address from the request query
6 my $ip_to_check = param(’cip’);
7 # Where a MYSQL database is running
8 my $dsn = ’DBI:mysql:BAD_CLIENT:localhost’;
9 # Database username to connect with
10 my $db_user_name = ‘ dbuser ’ ;
11 # Database password to connect with
12 my $db_password = ’dbpassword’;
13 my ($id, $password);
14 # Connecting to the database
15 my $dbh = DBI->connect($dsn, $db_user_name, $db_password);
16 my $sth = $dbh->prepare(qq{
17 select * from bad_clnt }
18 );
19 $sth->execute();
20 while (my ($ip_in_database) = $sth->fetchrow_array()) {
21
22 chomp($ip_in_database);
23 # Check for IP match
24 if ($ip_in_database eq $ip_to_check) {
25
26 print ”\n IP Matched\n”;
27 $sth->finish();
28 exit;
29 }
30
31 }
32
33 print ”\n IP Failed\n”;
34 $sth->finish();
35 exit;

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1089

NetScaler 12.0

Use Case: ESI Support for Fetching and Updating Content Dynamically

January 6, 2019

Contributed by:
C

Edge Side Includes (ESI) is a markup language for edge-level dynamic Web content assembly. It helps
in accelerating dynamic Web-based applications by defining a simple markup language to describe
cacheable and non-cacheable Web page components that can be aggregated, assembled, and deliv-
ered at the network edge. By using HTTP callouts on the NetScaler appliance, you can read through
the ESI constructs and aggregate or assemble content dynamically.

To implement this configuration, you must perform the following tasks:

1. Enable rewrite on the NetScaler appliance.

2. Create an HTTP callout on the appliance and configure it with details about the external server
and other required parameters.
3. Configure a rewrite action to replace the ESI content with the callout response body.
4. Configure a rewrite policy to specify the conditions under which the action is performed, and
then bind the rewrite policy globally.

Enabling Rewrite

Rewrite must be enabled before it is used on the NetScaler appliance. The following procedure de-
scribes the steps to enable the rewrite feature.

To enable rewrite by using the GUI

1. Make sure that you have installed the rewrite license.

2. In the GUI, expand AppExpert, and right-click Rewrite, and then click Enable Rewrite feature.

Creating an HTTP Callout on the NetScaler Appliance

For more information about creating an HTTP callout, see

Configuring an HTTP Callout.
For more information about the parameter values, see Parameters and Values for HTTP-Callout-2 pdf.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1090

NetScaler 12.0

Configuring the rewrite action

Create a rewrite action, Action-Rewrite-1, to replace the ESI content with the callout response body.
Use the parameter settings shown in the following table.

Table 2. Parameters and Values for Action-Rewrite-1

Parameter Value

Name Action-Rewrite-1
Type Replace
Expression to choose target text reference “HTTP.RES.BODY(500).AFTER_STR (\”
<example>\”).BEFORE_STR (\”</example>\”)”
String expression for replacement text “SYS.HTTP_CALLOUT(HTTP-Callout-2)”

To configure the rewrite action by using the GUI

1. Navigate to AppExpert > Rewrite > Actions.

2. In the details pane, click Add.

3. In the Create Rewrite Action dialog box, in Name, type Action-Rewrite-1.

4. In Type, select REPLACE.

5. In Expression to choose target text reference, type the following default syntax expression:

1 ”HTTP.RES.BODY(500).AFTER_STR(\”<example>\”).BEFORE_STR(\”</example>\”)
”

1. In the String expression for replacement text, type the following string expression:

1 ”SYS.HTTP_CALLOUT(HTTP-Callout-2)”

1. Click Create, and then click Close.

Creating the rewrite policy and binding it globally

Create a rewrite policy, Policy-Rewrite-1, with the parameter settings shown in the following table.
You can create a rewrite policy in the
Policies subnode and then bind it globally by using the
Rewrite Policy Manager. Alternatively, you can use the

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1091

NetScaler 12.0

Rewrite Policy Manager to perform both these tasks simultaneously. This demonstration uses the
Rewrite Policy Manager to perform both tasks.

Parameter Value

Name Policy-Rewrite-1
Action Action_Rewrite-1
Undefined Result Action -Global undefined-result action-
Expression “HTTP.REQ.HEADER(”Name”).CONTAINS
(”Callout”).NOT”

Table 3. Parameters and Values for Policy-Rewrite-1

To configure a rewrite policy and bind it globally by using the GUI

1. Navigate to AppExpert > Rewrite.

2. In the details pane, under Policy Manager, click Rewrite Policy Manager.
3. In the Rewrite Policy Manager dialog box, click Override Global.
4. Click Insert Policy, and then, in the Policy Name column, click New Policy.
5. In the Create Rewrite Policy dialog box, do the following:
1.In Name, type Policy-Rewrite-1.
a) In Action, select Action-Rewrite-1.
b) In Undefined-Result Action, select Global undefined-result action.
c) In Expression, type the following default syntax expression:

1 ”HTTP.REQ.HEADER(\”Name\”).CONTAINS(\”Callout\”).NOT”

5. Click Create, and then click Close.

6. Click Apply Changes, and then click Close.
1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Use Case: Access control and authentication

September 24, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1092

NetScaler 12.0

Contributed by:
C

In high security zones, it is mandatory to externally authenticate the user before a resource is accessed
by clients. On the NetScaler appliance, you can use HTTP callouts to externally authenticate the user
by evaluating the credentials supplied. In this example, the assumption is that the client is sending
the user name and password through HTTP headers in the request. However, the same information
could be fetched from the URL or the HTTP body.

To implement this configuration, you must perform the following tasks:

1. Enable the responder feature on the NetScaler appliance.

2. Create an HTTP callout on the appliance and configure it with details about the external server
and other required parameters.
3. Configure a responder policy to analyze the response, and then bind the policy globally.
4. Create a callout agent on the remote server.

Enabling responder

The responder feature must be enabled before it is used on the NetScaler appliance.

To enable responder by using the GUI

1. Make sure that the responder license is installed.

2. In the GUI, expand AppExpert, and right-click Responder, and then click Enable Responder
feature.

Creating an HTTP Callout on the NetScaler Appliance

Create an HTTP callout, HTTP-Callout-3, with the parameter settings shown in the following table. For
more information about creating an HTTP callout, see Configuring an HTTP Callout.

Table 1. Parameters and Values for HTTP-Callout-3

Parameter

Value

Name

HTTP-Callout-3

Server to receive callout request:

IP Address

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1093

NetScaler 12.0

10.103.9.95

Port

80

Request to send to the server:

Method

GET

Host Expression

10.102.3.95

URL Stem Expression

“/cgi-bin/authenticate.pl”

Headers:

Name

Request

Value-expression

Callout Request

Parameters:

Name

Username

Value-expression

HTTP.REQ.HEADER(“Username”).VALUE(0)

Name

Password

Value-expression

HTTP.REQ.HEADER(“Password”).VALUE(0)

Server Response:

Return Type

TEXT

Expression to extract data from the response

HTTP.RES.BODY(100)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1094

NetScaler 12.0

Creating a Responder policy to analyze the response

Create a responder policy, Policy-Responder-3, that will check the response from the callout server
and RESET the connection if the source IP address has been blacklisted. Create the policy with the
parameters settings shown in the following table. While you can create a responder policy in the
Policies subnode and then bind it globally by using the
Responder Policy Manager, this demonstration uses the
Responder Policy Manager to create the responder policy and bind the policy globally.

Parameter Value

Name Policy-Responder-3
Action RESET
Undefined-Result-Action -Global undefined-result action-
Expression “HTTP.REQ.HEADER(\“Request\”).EQ(\“Callout
Request\”).NOT && SYS.HTTP_CALLOUT(HTTP-
Callout-3).CONTAINS(\“Authentication
Failed\”)”

Table 2. Parameters and Values for Policy-Responder-3

To create a responder policy and bind it globally by using the GUI

1. Navigate to AppExpert > Responder.

2. In the details pane, under Policy Manager, click Responder Policy Manager.
3. In the Responder Policy Manger dialog box, click Override Global.
4. Click Insert Policy, and then, in the Policy Name column, click New Policy.
5. In the Create Responder Policy dialog box, do the following:
a) In Name, type Policy-Responder-3.
b) In Action, select RESET.
c) In Undefined-Result Action , select Global undefined-result action.
d) In the Expression text box, type:

1 ”HTTP.REQ.HEADER(\”Request\”).EQ(\”Callout Request\”).NOT &&

SYS.HTTP_CALLOUT(HTTP-Callout-3).CONTAINS(\”Authentication
Failed\”)”

e) Click Create, and then click Close.

6. Click Apply Changes, and then click Close.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1095

NetScaler 12.0

Creating an HTTP Callout agent on the remote server

You now need to create an HTTP callout agent on the remote callout server. The HTTP callout agent
receives callout requests from the NetScaler appliance and responds appropriately. The callout agent
is a script that is different for each deployment and must be written with server specifications in mind,
such as the type of database and the scripting language supported.

Following is sample callout agent pseudo-code that verifies whether the supplied user name and pass-
word are valid. The agent can be implemented in any programming language of your choice. The
pseudo-code is to be used only as a guideline for developing the callout agent. You can build addi-
tional functionality into the program.

To verify the supplied user name and password by using pseudo-code

1. Accept the user name and password supplied in the request and format them appropriately.
2. Connect to the database that contains all the valid user names and passwords.
3. Check the supplied credentials against your database.
4. Format the response as required by the HTTP callout.
5. Send the response to the NetScaler appliance.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Use Case: OWA-Based Spam Filtering

January 6, 2019

Contributed by:
C

Spam filtering is the ability to dynamically block emails that are not from a known or trusted source or
that have inappropriate content. Spam filtering requires an associated business logic that indicates
that a particular kind of message is spam. When the NetScaler appliance processes Outlook Web Ac-
cess (OWA) messages based on the HTTP protocol, HTTP callouts can be used to filter spam.

You can use HTTP callouts to extract any portion of the incoming message and check with an external
callout server that has been configured with rules that are meant for determining whether a message
is legitimate or spam. In case of spam email, for security reasons, the NetScaler appliance does not
notify the sender that the email is marked as spam.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1096

NetScaler 12.0

The following example conducts a very basic check for various listed keywords in the email subject.
These checks can be more complex in a production environment.

To implement this configuration, you must perform the following tasks:

1. Enable the responder feature on the NetScaler appliance.

2. Create an HTTP callout on the NetScaler appliance and configure it with details about the exter-
nal server and other required parameters.
3. Create a responder policy to analyze the response, and then bind the policy globally.
4. Create a callout agent on the remote server.

Enabling Responder

The responder feature must be enabled before it can be used on the NetScaler appliance.

To enable responder by using the GUI

1. Make sure that the responder license is installed.

2. In the GUI, expand AppExpert, and right-click Responder, and then click Enable Responder fea-
ture.

Creating an HTTP Callout on the NetScaler Appliance

Create an HTTP callout, HTTP-Callout-4, with the parameter settings shown in the following table. For
more information about creating an HTTP callout, see
Configuring an HTTP Callout.

For more information, see Parameters and Values for HTTP-Callout-4 pdf.

Creating a Responder Action

Create a responder action, Action-Responder-4. Create the action with the parameter settings shown
in the following table.

Parameter Value

Name Action-Responder-4
Type Respond with

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1097

NetScaler 12.0

Parameter Value

Target ””HTTP/1.1 200 OK\r\nServer:

Microsoft-IIS/6.0\r\nX-Powered-By:
ASP.NET\r\nContent-Length:
0\r\nMS-WebStorage:
6.5.6944\r\nCache-Control:
no-cache\r\n\r\n””

Table 2. Parameters and Values for Action-Responder-4

To create a responder action by using the GUI

1. Navigate to AppExpert > Responder > Actions.

2. In the details pane, click Add.

3. In the Create Responder Action dialog box, in Name, type Action-Responder-4.

4. In Type, click Respond with.

5. In Target, type:

1 ”\”HTTP/1.1 200 OK\r\nServer: Microsoft-IIS/6.0\r\nX-Powered-By:

ASP.NET\r\nContent-Length: 0\r\nMS-WebStorage: 6.5.6944\r\
nCache-Control: no-cache\r\n\r\n\””

6. Click Create, and then click Close.

Creating a Responder Policy to Invoke the HTTP Callout

Create a responder policy, Policy-Responder-4, that will check the request body and, if the body con-
tains the word “
subject,” invoke the HTTP callout to verify the email. Create the policy with the parameter settings
shown in the following table. While you can create a responder policy in the
Policies subnode and then bind it globally by using the
Responder Policy Manager, this demonstration uses the
Responder Policy Manager to create the responder policy and bind it globally.

Parameter Value

Name Policy-Responder-4

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1098

NetScaler 12.0

Parameter Value

Action Action-Responder-4
Undefined-Result-Action -Global undefined-result action-
Expression “HTTP.REQ.BODY(1000).CONTAINS(”urn:schemas:httpmail:su
&& SYS.HTTP_CALLOUT(HTTP-Callout-4)”

To create a responder policy by using the GUI

1. Navigate to AppExpert > Responder.

2. In the details pane, under Policy Manager, click Responder policy manager.
3. In the Responder Policy Manger dialog box, click Override Global.
4. Click Insert Policy, and then, in the Policy Name column, click New Policy.
5. In the Create Responder Policy dialog box, do the following:
a) In Name, type Policy-Responder-4.
b) In Action, click Action-Responder-4.
c) In Undefined-Result Action, click Global undefined-result action.
d) In the Expression text box, type:

1 ”HTTP.REQ.BODY(1000).CONTAINS(\”urn:schemas:httpmail:subject
\”) && SYS.HTTP_CALLOUT(HTTP-Callout-4)”

e) Click Create, and then click Close.

6. Click Apply Changes, and then click Close.

Creating an HTTP Callout Agent on the Remote Server

You will now need to create an HTTP callout agent on the remote callout server. The HTTP callout
agent receives callout requests from the NetScaler appliance and responds accordingly. The callout
agent is a script that is different for each deployment and must be written with server specifications
in mind, such as the type of database and the scripting language supported.
The following pseudo-code provides instructions for creating a callout agent that checks a list of words
that are generally understood to indicate spam mails. The agent can be implemented in any program-
ming language of your choice. The pseudo-code is to be used only as a guideline for developing the
callout agent. You can build additional functionality into the program.

To identify spam email by using pseudo-code

1. Accept the email subject provided by the NetScaler appliance.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1099

NetScaler 12.0

2. Connect to the database that contains all the terms against which the email subject is checked.
3. Check the words in the email subject against the spam word list.
4. Format the response as required by the HTTP callout.
5. Send the response to the NetScaler appliance.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Use Case: Dynamic Content Switching

September 24, 2018

Contributed by:
C

May 24, 2018

This use case provides dynamic content switching by using an HTTP callout to get the name of the
load balancing virtual server to which the request is forwarded.

1. Add a content switching virtual server.

1 > add cs vserver cs_vserver1 HTTP 10.102.29.196 80

2. Create an HTTP callout.

1 > add policy httpCallout http_callout1

3. Configure the HTTP callout to respond with the name of the load balancing virtual server from
a request that contains the client IP address in the HTTP header “X-CLIENT-IP”.

1 > set policy httpCallout http_callout1 -IPAddress 10.217.14.23 -

port 80 -returnType TEXT -hostExpr ”\”www.get-lbvip.com\”” -
urlStemExpr ”\”/index.html\”” -headers X-CLIENT-IP(CLIENT.IP.
SRC) -resultExpr ”HTTP.RES.BODY(1000).AFTER_STR(\”<lbvip>\”).
BEFORE_STR(\”</lbvip\”)”

4. Configure the content switching action to retrieve the callout response.

1 > add cs action cs_action1 -targetVserverExpr ’SYS.HTTP_CALLOUT(

http_callout1)’

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1100

NetScaler 12.0

Note: You must bind a load balancing virtual server to the content switching virtual server to
account for:

• The non-availability of the load balancing virtual server that the callout resolves to.
• A UNDEF condition that results from the execution of the callout.

1 > bind cs vserver cs_vserver1 -lbvserver default_lbvip

5. Configure the content switching policy.

1 > add cs policy cs_policy1 -rule true -action cs_action1

6. Binding the content switching policy to the content switching virtual server.

1 > bind cs vserver cs_vserver1 -policyName cs_policy1 -priority 10

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Pattern sets and data sets

September 24, 2018

Contributed by:
C

Policy expressions for string matching operations on a large set of string patterns tend to become long
and complex. Resources consumed by the evaluation of such complex expressions are significant in
terms of processing cycles, memory, and configuration size. You can create simpler, less resource-
intensive expressions by using pattern matching.

Depending on the type of patterns that you want to match, you can use one of the following features
to implement pattern matching:

• A pattern set is an array of indexed patterns used for string matching during default syntax policy
evaluation. Example of a pattern set: imagetypes {svg, bmp, png, gif, tiff, jpg}.
• A data set is a specialized form of pattern set. It is an array of patterns of types number (integer),
IPv4 address, or IPv6 address.

In many cases, you can use either pattern sets or data sets. However, in cases where you want specific
matches for numerical data or IPv4 and IPv6 addresses, you must use data sets.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1101

NetScaler 12.0

Note:
Pattern sets
and data sets can be used only in default syntax policies.

To use pattern sets or data sets, first create the pattern set or data set and bind patterns to it. Then,
when you configure a policy for comparing a string in a packet, use an appropriate operator and pass
the name of the pattern set or data set as an argument.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

How string matching works with pattern sets and data sets

January 6, 2019

Contributed by:
C

A pattern set or data set contains a set of patterns, and each pattern is assigned a unique index. When
a policy is applied to a packet, an expression identifies a string to be evaluated, and the operator
compares the string to the patterns defined in the pattern set or data set until a match is found or all
patterns have been compared. Then, depending on its function, the operator returns either a boolean
value that indicates whether or not a matching pattern was found or the index of the pattern that
matches the string.

Note: This topic explains the working of a pattern set. Data sets work the same way. The only differ-
ence between pattern sets and data sets is the type of patterns defined in the set.

Consider the following use case to understand how patterns can be used for string matching.

You want to determine whether the URL suffix (target text) contains any of the image file extensions.
Without using pattern sets, you would have to define a complex expression, as follows:

1 HTTP.REQ.URL.SUFFIX.CONTAINS(”svg”) ¦¦ HTTP.REQ.URL.SUFFIX.CONTAINS(”
bmp”) ¦¦ HTTP.REQ.URL.SUFFIX.CONTAINS(”png”) ¦¦
2 HTTP.REQ.URL.SUFFIX.CONTAINS(”gif”) ¦¦ HTTP.REQ.URL.SUFFIX.CONTAINS(”
tiff”) ¦¦ HTTP.REQ.URL.SUFFIX.CONTAINS(”jpg”)

If the URL has a suffix of “jpg,” with the above compound expression, the Citrix ADC appliance has to
iterate through the entire compound expression sequentially, from one sub expression to the next, to
determine that the request refers to a jpg image. The following figure shows the steps in the process.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1102

NetScaler 12.0

When a compound expression includes hundreds of sub expressions, the above process is resource
intensive. A better alternative is an expression that invokes a pattern set, as shown in the following
figure.

During policy evaluation as shown above, the operator (CONTAINS_ANY) compares the string identi-
fied in the request with the patterns defined in the pattern set until a match is found. With the Sam-
ple_Patset expression, the multiple iterations through six sub expressions are reduced to just one.

By eliminating the need to configure compound expressions that perform string matching with mul-
tiple OR operations, pattern sets or data sets simplify configuration and accelerate processing of re-
quests and responses.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring a Pattern Set

October 26, 2018

Contributed by:
C

To configure a pattern set, you must specify the strings that are to serve as patterns. You can manually
assign a unique index value to each of these patterns, or you can allow the index values to be assigned
automatically.

Note: Pattern sets are case sensitive (unless you specify the expression to ignore case). Therefore, the
string pattern “product1,” for example, is not the same as the string pattern “Product1.”

Points to remember about index values:

• You cannot bind the same index value to more than one pattern.
• An automatically assigned index value is one number larger than the highest index value of the
existing patterns within the pattern set. For example, if the highest index value of existing pat-
terns in a pattern set is 104, the next automatically assigned index value will be 105.
• If you do not specify an index for the first pattern, index value 1 is automatically assigned to that
pattern.
• Index values are not regenerated automatically if one or more patterns are deleted or modified.
For example, if the set contains five patterns, with indexes from 1 through 5, and if the pattern
with an index of 3 is deleted, the other index values in the pattern set are not automatically
regenerated to produce values from 1 through 4.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1103

NetScaler 12.0

• The maximum index value that can be assigned to a pattern is 4294967290. If that value is
already assigned to a pattern in the set, you must manually assign index values to any newly
added patterns. An unused index value that is lower than a currently used value cannot be as-
signed automatically.

To configure a pattern set by using the command line interface

At the command prompt, do the following:

1. Create a pattern set.

add policy patset <name>

Example:

1 > add policy patset samplepatset

2. Bind patterns to the pattern set.

bind policy patset <name> <string> [-index <positive_integer>]

Example:

1 > bind policy patset samplepatset product1 -index 1

Note: Repeat this step for all the patterns you want to bind to the pattern set.

3. Verify the configuration.

show policy patset <name>

To configure a pattern set by using the configuration utility

1. Navigate to AppExpert > Pattern Sets.

2. In the details pane, click Add to open the Create Pattern Set dialog box.
3. Specify a name for the pattern set in the Name text box.
4. Under Specify Pattern, type the first pattern and, optionally, specify values for the following
parameters:
• Treat back slash as escape character—Select this check box to specify that any backslash
characters that you might include in the pattern are to be treated as escape characters.
• Index—A user assigned index value, from 1 through 4294967290.
5. Verify that you have entered the correct characters, and then click Add.
6. Repeat steps 4 and 5 to add additional patterns, and then click Create.

1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1104

NetScaler 12.0

2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring a data set

October 26, 2018

Contributed by:
C

To configure a data set, you must specify the strings that are to serve as patterns, and assign a type
(number, IPv4 address, or IPv6 address) to each pattern. You can manually assign a unique index value
to each of these patterns, or you can allow the index values to be assigned automatically. Dataset is
not related to HTTP or any 7 layer protocol. It works only on text/string. There are different types
of dataset such as num, ulong, ipv4, and ipv6. To use a dataset on IP, we have to convert the input into
text/string.

Note: Data sets are case sensitive (unless you specify the expression to ignore case). Therefore, the
string pattern “product1,” for example, is not the same as the string pattern “Product1.”

The rules applied for index values of data sets are the same as those applied for pattern sets. For
information about index values, see Configuring a Pattern Set.

To configure a data set by using the command line interface

At the command prompt, do the following:

1. Create a data set.

add policy dataset <name> <type>

1 **Example:**
2
3 ‘‘‘
4 > add policy dataset sampledataset ipv4
5 ‘‘‘

1. Bind patterns to the data set.

bind policy dataset <name> <value> [-index <positive_integer>]

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1105

NetScaler 12.0

1 > bind policy dataset sampledataset 10.102.29.1 -index 1

Note: Repeat this step for all the patterns you want to bind to the data set.

2. add policy expression sampleexpression client.ip.src.typecast_text_t.equals_any(“sampledataset”)

3. Verify the configuration.

show policy dataset <name>

To configure a data set by using the configuration utility

Navigate to AppExpert > Data Sets, click Add and specify the relevant details.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Using pattern sets and data sets

January 6, 2019

Contributed by:
C

Default syntax policy expressions that take pattern sets or data sets as an argument can be used to
perform string matching operations.

The usage is as follows:

1 <text>.<operator>(”<name>”)

where,

• <text> is the expression that identifies a string in a packet. Example: HTTP.REQ.HEADER(“Host”).

• <operator> is one of the operators described in the Pattern Set Types table pdf.

For sample usage, see Sample Usage.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1106

NetScaler 12.0

Sample usage

October 26, 2018

Contributed by:
C

To understand the usage of pattern sets in expressions, consider the example of a pattern set named
“imagetypes.”

Patterns Index value

svg 1
bmp 2
png 3
gif 4
tiff 5
jpg 6

Table 1. Pattern set “imagetypes”

Example 1: Determine whether the suffix of an HTTP request is one of the file extensions defined in
the “imagetypes” pattern set.

• Expression. HTTP.REQ.URL.SUFFIX.EQUALS_ANY(“imagetypes”)
• Sample URL. http://www.example.com/homepageicon.jpg
• Result. TRUE

Example 2: Determine whether the suffix of an HTTP request is one of the file extensions defined in
the “imagetypes” pattern set, and return the index of that pattern.

• Expression. HTTP.REQ.URL.SUFFIX.EQUALS_INDEX(“imagetypes”)
• Sample URL. http://www.example.com/mylogo.gif
• Result. 4 (The index value of the pattern “gif”.)

Example 3: Use the index value of a pattern to determine whether the URL suffix is within a specified
index-value range.

• Expression. HTTP.REQ.URL.SUFFIX.EQUALS_INDEX(“imagetypes”).GE(3) && HTTP.REQ.URL.SUFFIX.EQUALS

• Sample URL. http://www.example.com/mylogo.gif
• Result. TRUE (The index value of gif file types is 4.)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1107

NetScaler 12.0

Example 4: Implement one set of policies for file extensions bmp, jpg, and png, and a different set of
policies for gif, tiff, and svg files.
An expression that returns the index of a matched pattern can be used to define traffic subsets for
a web application. The following two expressions could be used in content switching policies for a
content switching virtual server:
• HTTP.REQ.URL.SUFFIX.EQUALS_INDEX(“imagetypes”).LE(3)
• HTTP.REQ.URL.SUFFIX.EQUALS_INDEX(“imagetypes”).GE(4)
1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Variables

September 24, 2018

Contributed by:
C
Variables are named objects that store information in the form of tokens. These tokens are used within
and across different transactions on the NetScaler Appliance for internal computation and policy pro-
cessing.
The NetScaler appliance supports creation of variables of the following types:
• Singleton variables. Can have a single value of one of the following types: ulong and text (max-
size). The ulong type is an unsigned 64-bit integer, the text type is a sequence of bytes, and
max-size is the maximum number of bytes in the sequence.
• Map variables. Maps hold values associated with keys: each key-value pair is called a map
entry. The key for each entry is unique within the map. Maps are specified as follows:
map (key_type, value_type, max-values).
where,
– key_type is the data type of the key. It is of type text (max-size).
–
1 *value_type* is the data type of the values of the map. It can
be of type ulong or text (max-size).

1 *max-values* is the maximum number of entries that the map can

contain. It is of type ulong.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1108

NetScaler 12.0

Values for these variables are set using assignments which must be invoked on policy actions.

– Note: Variables are not yet supported in a high-availability setup or in a cluster.

Variables Scope

A map variable or a singleton variable can have a global scope. Alternatively, the scope of a singleton
variable can be limited to a single transaction.

• Global Scope Variable - A variable with global scope (the default) has only one instance, and
that instance has the same value(s) across all cores of a NetScaler appliance and across all nodes
of a cluster or HA configuration. Global variable values exist until they are explicitly deleted,
until they expire, or until a standalone appliance is restarted or all nodes of a cluster or HA con-
figuration are restarted.
• Transaction Scope Variable - A variable with transaction scope has a separate instance, with
its own value, for each transaction processed by the NetScaler appliance. When the transaction
processing is complete, the transaction variable value is deleted.

Note: Transaction scope variables are available in NetScaler release 10.5.e or later.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring and using Variables

September 24, 2018

Contributed by:
C

You must first create a variable and then assign a value or specify the operation that must be per-
formed on the variable. After performing these operations, you can use the assignment as a policy
action.

Note: Once configured, a variable’s settings cannot be modified or reset. If the variable needs to
be changed, the variable and all references to the variable (expressions and assignments) must be
deleted. The variable can then be re-added with new settings, and the references (expressions and
assignments) can be re-added.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1109

NetScaler 12.0

To configure variables by using the command line interface

1. Create a variable.

1 add ns variable <name> -type <string> [-scope global] [-ifFull ( undef

| lru )] [-ifValueTooBig ( undef | truncate )] [-ifNoValue ( undef |
init )] [-init <string>] [-expires <positive_integer>] [-comment <
string>]

Note: Refer to the man page “man add ns variable” for description of the command parameters.

Example 1: Create a ulong variable named “my_counter” and initialize it to 1.

1 add ns variable my_counter ‒ type ulong -init 1

Example 2: Create a map named “user_privilege_map”. The map will contain keys of maximum length
15 characters and text values of maximum length 10 characters, with a maximum of 10000 entries.

1 add ns variable user_privilege_map -type map(text(15),text(10),10000)

Note: If the map contains 10000 unexpired entries, assignments for new keys reuse one of the least
recently used entries. By default, an expression trying to get a value for a non-existent key will initialize
an empty text value.

Assign the value or specify the operation to be performed on the variable. This is done by creating an
assignment.

1 add ns assignment <name> -variable <expression> [-set <expression> | -

add <expression> | -sub <expression> | -append <expression> | -clear
] [-comment <string>]

Note: A variable is referenced by using the variable selector ($). Therefore,

$variable1 is used to refer to text or ulong variables. Similarly,
$variable2[key-expression] is used to refer to map variables.

Example 1: Define an assignment named “inc_my_counter” that automatically adds 1 to the

“my_counter” variable.

1 add ns assignment inc_my_counter -variable $my_counter -add 1

Example 2: Define an assignment named “set_user_privilege” that adds to the “user_privilege_map”

variable an entry for the client’s IP address with the value returned by the “get_user_privilege” HTTP
callout.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1110

NetScaler 12.0

1 add ns assignment set_user_privilege -variable $user_privilege_map[

client.ip.src.typecast_text_t] -set sys.http.callout(
get_user_privilege)

Note: If an entry for that key already exists, the value will be replaced. Otherwise a new entry for the
key and value will be added. Based on the previous declaration for user_privilege_map, if the map
already has 10000 entries, one of the least recently used entries will be reused for the new key and
value.

1. Invoke the variable assignment in a policy.

There are two functions that can operate on map variables.

• $name.valueExists(key-expression). Returns true if there is a value in the map selected

by the key-expression. Otherwise returns false. This function will update the expiration
and LRU information if the map entry exists, but will not create a new map entry if the
value does not exist.

• $name.valueCount. Returns the number of values currently held by the variable. This is
the number of entries in a map. For a singleton variable, this is 0 if the variable is uninitial-
ized or 1 otherwise.

Example: Invoke the assignment named “set_user_privilege” with a compression policy.

1 add cmp policy set_user_privilege_pol -rule $user_privilege_map.

valueExists(client.ip.src.typecast_text_t).not -resAction
set_user_privilege

Use Case to insert HTTP header in the response side

The following example shows an example of a singleton variable.

Add a singleton variable of type text. This variable can hold maximum 100 Bytes data.

1 add ns variable http_req_data -type text(100) -scope transaction

Add an assignment action, which will be used to store the HTTP request data into the variable.

1 add ns assignment set_http_req_data -variable $http_req_data -set http.

req.body(100)

Add a rewrite action to insert HTTP header, whose value will be fetched from the variable.

1 add rewrite action act_ins_header insert_http_header user_name

$http_req_data.after_str(”user_name”).before_str(”password”)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1111

NetScaler 12.0

Add a rewrite policy which will evaluate in the request time, and take assignment action to store
data. When we hit this policy, we’ll take assignment action and store the data into the ns variable
(http_req_data)

1 add rewrite policy pol_set_variable true set_http_req_data

2
3 bind rewrite global pol_set_variable 10 -type req_dEFAULT

Add a rewrite policy which will evaluate in the response time, and add an HTTP header in the response.

1 add rewrite policy pol_ins_header true act_ins_header

2
3 bind rewrite global pol_ins_header 10 -type res_dEFAULT

To configure variables by using the GUI

1. Navigate to AppExpert > NS Variables, to create a variable.

2. Navigate to AppExpert > NS Assignments, to assign value(s) to the variable.
3. Navigate to the appropriate feature area where you want to configure the assignment as an
action.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Use Case: Caching User Privileges

September 24, 2018

Contributed by:
C

In this use case, user privileges (“GOLD”, “SILVER”, and so on) must be retrieved from an external web
service.

To achieve this use case, perform the following operations

Create an HTTP callout to fetch the user privileges from the external web service.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1112

NetScaler 12.0

1 add policy httpcallout <name> [-IPAddress <ip_addr|ipv6_addr>] [-port <

port>] [-vServer <string>] [-returnType <returnType>] [-httpMethod (
GET | POST )] [-hostExpr <string>] [-urlStemExpr <string>] [-headers
<name(value)> ...] [-parameters <name(value)> ...] [-bodyExpr <
string>][-fullReqExpr <string>] [-scheme ( http | https )] [-
resultExpr <string>] [-cacheForSecs <secs>] [-comment <string>]
2
3 add policy httpcallout get_user_privilege -ipaddress 10.217.193.84 -
port 80 -returnType text -httpMethod GET -hostExpr ’”/
get_user_privilege”’ -resultExpr ’http.res.body(5)’

Store the privileges in a variable.

1 add ns variable <name> -type <string> [-scope ( global | transaction )

][-ifFull ( undef | lru )] [-ifValueTooBig ( undef | truncate )][-
ifNoValue ( undef | init )] [-init <string>] [-expires <
positive_integer>] [-comment <string>]
2
3 add ns variable user_privilege_map -type map(text(15),text(10),10000) -
expires 1200
4
5 add ns assignment set_user_privilege -variable $user_privilege_map[
client.ip.src] -set sys.http_callout(get_user_privilege)

Create a policy to check if there is already a cached entry for the client’s IP address; if not, it calls the
HTTP callout to set a map entry for the client.

1 add cmp policy <name> -rule <expression> -resAction <string>

2
3 add cmp policy set_user_privilege_pol -rule $user_privilege_map.
valueExists(client.ip.src).not -resAction set_user_privilege>

Create a policy that compresses if the cached privilege entry for the client is “GOLD”.

1 add cmp policy <name> -rule <expression> -resAction <string>

2
3 add cmp policy compress_if_gold_privilege_pol -rule ’
$user_privilege_map[client.ip.src].eq(”GOLD”)’ -resAction compress

Bind the compression policies globally.

1 bind cmp global <policyName> [-priority <positive_integer>] [-state (

ENABLED | DISABLED )] [-gotoPriorityExpression <expression>] [-type
<type>] [-invoke (<labelType> <labelName>) ]

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1113

NetScaler 12.0

2
3 bind cmp global set_user_privilege_pol -priority 10 NEXT
4
5 bind cmp global compress_if_gold_privilege_pol -priority 20 END

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Use Case: Limiting the Number of Sessions

September 24, 2018

Contributed by:
C

In this use case, the requirement is to limit the number of active backend sessions. In the deployment,
each session login has login in the URL and each session logout has logout in the URL. On successful
login, the backend sets a sessionid cookie with a unique 10 character value.

To achieve this use case, perform the following operations:

1. Create a map variable that can store each active session. The key of the map is the sessionid.
The expiry time for the variable is set to 600 seconds (10 minutes).</span>

1 > add ns variable session_map -type map(text(10),ulong,100) -

expires 600

2. Create the following assignments for the map variable:</span>

• Create an entry for the sessionid and set that value to 1 (this value is not actually
used).</span>

1 > add ns assignment add_session -variable ’$session_map[http.

req.cookie.value(”sessionid”)]’ -set 1

• Deallocate the entry for a session ID, which implicitly decrements the value count for ses-
sion_map.</span>

1 > add ns assignment delete_session -variable ’$session_map[

http.req.cookie.value(”sessionid”)]’ -clear

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1114

NetScaler 12.0

3. Create responder policies for the following:</span>

• To check if a map entry exists for that sessionid in the HTTP request. The add_session
assignment is executed if the map entry does not exist.</span>

1 > add responder policy add_session_pol ’http.req.url.contains

(”twbkwbis.P_SabanciLogin”) || $session_map.valueExists(
http.req.cookie.value(”netsuis”))’ add_session

Note: The
valueExists() function in the
add_session_pol policy counts as a reference to the session’s map entry, so each request
resets the expiration timeout for its session. If no requests for a session are received after
10 minutes, the session’s entry will be deallocated.

• To check when the session is logged out. The delete_session assignment is exe-
cuted.</span>

1 add responder policy delete_session_pol ”http.req.url.

contains(\”Logout\”)” delete_session

• To check for login requests and if the number of active sessions exceed 100. If these condi-
tions are satisfied, in order to limit the number of sessions, the user is redirected to a page
that indicates that the server is busy.</span>

1 add responder action redirect_too_busy redirect ”/too_busy.

html”
2 add responder policy check_login_pol ”http.req.url.contains
(\”twbkwbis.P_SabanciLogin\”) && $session_map.valueCount >
100” redirect_too_busy

4. Bind the responder policies globally.</span>

1 bind responder global add_session_pol 30 next

2 bind responder global delete_session_pol 10
3 bind responder global check_login_pol 20

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1115

NetScaler 12.0

Policies and expressions

September 24, 2018

Contributed by:
C

The following topics provide the conceptual and reference information that you require for configur-
ing advanced policies on the Citrix® NetScaler® appliance.

You can also download a list of all the expressions supported on the NetScaler appliance and the hi-
erarchical order in which they can be invoked. The reference is in a zip file which you can download
from:

• For more information, see Citrix support article CTX137705

• For NetScaler 10.1, see Citrix support article CTX137705

Introduction to Policies and Expressions Describes the purpose of expressions, policies,

and actions, and how different NetScaler
applications make use of them.
Configuring Advanced Policies Describes the structure of advanced policies
and how to configure them individually and as
policy banks.
Configuring Advanced Expressions: Getting Describes expression syntax and semantics,
Started and briefly introduces how to configure
expressions and policies.
Advanced Expressions: Evaluating Text Describes expressions that you configure when
you want to operate on text (for example, the
body of an HTTP POST request or the contents
of a user certificate).
Advanced Expressions: Working with Dates, Describes expressions that you configure when
Times, and Numbers you want to operate on any type of numeric
data (for example, the length of a URL, a
client’s IP address, or the date and time that an
HTTP request was sent).
Advanced Expressions: Parsing HTTP, TCP, and Describes expressions for parsing IP and IPv6
UDP Data addresses, MAC addresses, and data that is
specific to HTTP and TCP traffic.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1116

NetScaler 12.0

Advanced Expressions: Parsing SSL Certificates Describes how to configure expressions for SSL
traffic and client certificates, for example, how
to retrieve the expiration date of a certificate or
the certificate issuer.
Advanced Expressions: IP and MAC Addresses, Describes expressions that you can use to work
Throughput, VLAN IDs with any other client- or server-related data not
discussed in other chapters.
Typecasting Data Describes expressions for transforming data of
one type to another.
Regular Expressions Describes how to pass regular expressions as
arguments to operators in advanced
expressions.
Configuring Classic Policies and Expressions Provides details on how to configure the
simpler policies and expressions known as
classic policies and classic expressions.
Expressions Reference A reference for classic and advanced
expression arguments.
Summary Examples of Advanced Expressions Examples of classic and advanced expressions
and Policies and policies, in both quick reference and
tutorial format, that you can customize for
your own use.
Tutorial Examples of Advanced Policies for Examples of advanced policies for use in the
Rewrite Rewrite feature.
Tutorial Examples of Classic Policies Examples of classic policies for NetScaler
features such as application firewall and SSL.
Migration of Apache mod_rewrite Rules to Examples of functions that were written using
Advanced Policies the Apache HTTP Server mod_rewrite engine,
with examples of these functions after
translation into Rewrite and Responder
policies on the NetScaler.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1117

NetScaler 12.0

Introduction to policies and expressions

September 24, 2018

Contributed by:
C

For many NetScaler features, policies control how a feature evaluates data, which ultimately deter-
mines what the feature does with the data. A policy uses a logical expression, also called a rule, to
evaluate requests, responses, or other data, and applies one or more actions determined by the out-
come of the evaluation. Alternatively, a policy can apply a profile, which defines a complex action.

Some NetScaler features use default syntax policies, which provide greater capabilities than do the
older, classic, policies. If you migrated to a newer release of the NetScaler software and have con-
figured classic policies for features that now use default syntax policies, you might have to manually
migrate policies to the default syntax.

This document contains the following details:

• Classic and Default Syntax Policies

• Classic and Default Syntax Expressions
• Converting Classic Expressions to the Newer Default Expression Syntax
• Before You Proceed

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Classic and advanced policies

September 24, 2018

Contributed by:
C
Warning

Classic policy expressions are no longer supported from NetScaler 12.0 build 56.20 onwards and
as an alternative, Citrix recommends you to use Advanced policies. For more information, see
Advanced Policies

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1118

NetScaler 12.0

Classic policies evaluate basic characteristics of traffic and other data. For example, classic policies
can identify whether an HTTP request or response contains a particular type of header or URL.
Advanced policies can perform the same type of evaluations as classic policies. In addition, default
syntax policies enable you to analyze more data (for example, the body of an HTTP request) and to
configure more operations in the policy rule (for example, transforming data in the body of a request
into an HTTP header).
In addition to assigning a policy an action or profile, you bind the policy to a particular point in the
processing associated with the NetScaler features. The bind point is one factor that determines when
the policy will be evaluated.

Benefits of using advanced policies

Default syntax policies use a powerful expression language that is built on a class-object model, and
they offer several options that enhance your ability to configure the behavior of various NetScaler
features. With default syntax policies, you can do the following:
• Perform fine-grained analyses of network traffic from layers 2 through 7.
• Evaluate any part of the header or body of an HTTP or HTTPS request or response.
• Bind policies to the multiple bind points that the default syntax policy infrastructure supports
at the default, override, and virtual server levels.
• Use goto expressions to transfer control to other policies and bind points, as determined by the
result of expression evaluation.
• Use special tools such as pattern sets, policy labels, rate limit identifiers, and HTTP callouts,
which enable you to configure policies effectively for complex use cases.
Additionally, the GUI extends robust graphical user interface support for default syntax policies and
expressions and enables users who have limited knowledge of networking protocols to configure poli-
cies quickly and easily. The GUI also includes a policy evaluation feature for default syntax policies.
You can use this feature to evaluate a default syntax policy and test its behavior before you commit it,
thus reducing the risk of configuration errors.

Basic components of an advanced policy

Following are a few characteristics of an Advanced policy:

• Name.
Each policy has a unique name.
• Rule.
The rule is a logical expression that enables the NetScaler feature to evaluate a piece of traffic
or another object.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1119

NetScaler 12.0

For example, a rule can enable the NetScaler to determine whether an HTTP request originated
from a particular IP address, or whether a Cache-Control header in an HTTP request has the
value “No-Cache.”

Advanced policies can use all of the expressions that are available in a classic policy, with the
exception of classic expressions for the SSL VPN client. In addition, Advanced policies enable
you to configure more complex expressions.

• Bindings.

To ensure that the NetScaler can invoke a policy when it is needed, you associate the policy, or
bind it, to one or more bind points.

You can bind a policy globally or to a virtual server. For more information, see “About policy
bindings.”

• An associated action.

An action is a separate entity from a policy. Policy evaluation ultimately results in the NetScaler
performing an action.

For example, a policy in the integrated cache can identify HTTP requests for .gif or .jpeg files.
An action that you associate with this policy determines that the responses to these types of
requests are served from the cache.

For some features, you configure actions as part of a more complex set of instructions known
as a profile.

How different NetScaler features use policies

The NetScaler supports a variety of features that rely on policies for operation. The following table
summarizes how the NetScaler features use policies.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1120

NetScaler 12.0

How You Use Policies in the

Feature Name Policy Type Feature

System Classic For the Authentication

function, policies contain
authentication schemes for
different authentication
methods. For example, you
can configure LDAP and
certificate-based
authentication schemes. You
also configure policies in the
Auditing function.
DNS Advanced To determine how to perform
DNS resolution for requests.
SSL Classic and Advanced To determine when to apply
an encryption function and
add certificate information to
clear text. To provide
end-to-end security, after a
message is decrypted, the SSL
feature re-encrypts clear text
and uses SSL to communicate
with Web servers.
Compression Classic and Advanced To determine what type of
traffic is compressed.
Integrated Caching Advanced To determine whether HTTP
responses are cacheable.
Responder Advanced To configure the behavior of
the Responder function.
Protection Features Classic To configure the behavior of
the Filter, SureConnect, and
Priority Queuing functions.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1121

NetScaler 12.0

How You Use Policies in the

Feature Name Policy Type Feature

Content Switching Classic and Advanced To determine what server or

group of servers is
responsible for serving
responses, based on
characteristics of an incoming
request. Request
characteristics include device
type, language, cookies,
HTTP method, content type,
and associated cache server.
AAA - Traffic Management Classic. Exceptions: Traffic To check for client-side
policies support only default security before users log in
syntax policies aand and establish a session.
authorization policies Traffic policies, which
support both classic and determine whether single
default syntax policies. sign-on (SSO) is required, use
only the default syntax.
Authorization policies
authorize users and groups
that access intranet resources
through the appliance.
Cache Redirection Classic To determine whether
responses are served from a
cache or from an origin
server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1122

NetScaler 12.0

How You Use Policies in the

Feature Name Policy Type Feature

Rewrite Advanced To identify HTTP data that

you want to modify before
serving. The policies provide
rules for modifying the data.
For example, you can modify
HTTP data to redirect a
request to a new home page,
or a new server, or a selected
server based on the address
of the incoming request, or
you can modify the data to
mask server information in a
response for security
purposes. The URL
Transformer function
identifies URLs in HTTP
transactions and text files for
the purpose of evaluating
whether a URL should be
transformed.
Application Firewall Classic and Advanced To identify characteristics of
traffic and data that should or
should not be admitted
through the firewall.
NetScaler Gateway, Clientless Advanced To define rewrite rules for
Access function general Web access using
the NetScaler Gateway.
NetScaler Gateway Classic To determine how
the NetScaler
Gateway performs
authentication,
authorization, auditing, and
other functions.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1123

NetScaler 12.0

About actions and profiles

Policies do not themselves take action on data. Policies provide read-only logic for evaluating traffic.
To enable a feature to perform an operation based on a policy evaluation, you configure actions or
profiles and associate them with policies.

Note: Actions and profiles are specific to particular features. For information about assigning actions
and profiles to features, see the documentation for the individual features.

About actions

Actions are steps that the NetScaler takes, depending on the evaluation of the expression in the policy.
For example, if an expression in a policy matches a particular source IP address in a request, the action
that is associated with this policy determines whether the connection is permitted.

The types of actions that the NetScaler can take are feature specific. For example, in Rewrite, ac-
tions can replace text in a request, change the destination URL for a request, and so on. In Integrated
Caching, actions determine whether HTTP responses are served from the cache or an origin server.

In some NetScaler features actions are predefined, and in others they are configurable. In some cases,
(for example, Rewrite), you configure the actions using the same types of expressions that you use to
configure the associated policy rule.

About profiles

Some NetScaler features enable you to associate profiles, or both actions and profiles, with a policy.
A profile is a collection of settings that enable the feature to perform a complex function. For example,
in the application firewall, a profile for XML data can perform multiple screening operations, such as
examining the data for illegal XML syntax or evidence of SQL injection.

Use of actions and profiles in particular features

The following table summarizes the use of actions and profiles in different NetScaler features. The
table is not exhaustive. For more information about specific uses of actions and profiles for a feature,
see the documentation for the feature.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1124

NetScaler 12.0

Feature Use of an Action Use of a Profile

Application firewall Synonymous with a profile All application firewall

features use profiles to define
complex behaviors, including
pattern-based learning. You
add these profiles to policies.
NetScaler Gateway The following features of The following features use a
the NetScaler Gateway use profile:
actions: Pre- Pre-Authentication, Ses-
Authentication. Uses Allow sion, Traffic, and Clientless
and Deny actions. You add Access. After configuring the
these actions to a profiles, you add them to
profile., Authorization. Uses policies.
Allow and Deny actions. You
add these actions to a
policy. TCP
Compression. Uses various
actions. You add these
actions to a policy.
Rewrite You configure URL rewrite Not used.
actions and add them to a
policy.
Integrated Caching You configure caching and Not used.
invalidation actions within a
policy
AAA - Traffic Management You select an authentication You can configure session
type, set an authorization profiles with a default
action of ALLOW or DENY, or timeout and authorization
set auditing to SYSLOG or action.
NSLOG.
Protection Features You configure actions within Not used.
policies for the following
functions: Filter, Compres-
sion, Responder,
and SureConnect.
SSL You configure actions within Not used.
SSL policies

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1125

NetScaler 12.0

Feature Use of an Action Use of a Profile

System The action is implied. For the Not used.

Authentication function, it is
either Allow or Deny. For
Auditing, it is Auditing On or
Auditing Off.
DNS The action is implied. It is Not used.
either Drop Packets or the
location of a DNS server.
SSL Offload The action is implied. It is Not used.
based on a policy that you
associate with an SSL virtual
server or a service.
Compression Determine the type of Not used.
compression to apply to the
data
Content Switching The action is implied. If a Not used.
request matches the policy,
the request is directed to the
virtual server associated with
the policy.
Cache Redirection The action is implied. If a Not used.
request matches the policy,
the request is directed to the
origin server.

About policy bindings

A policy is associated with, or bound to, an entity that enables the policy to be invoked. For example,
you can bind a policy to request-time evaluation that applies to all virtual servers. A collection of
policies that are bound to a particular bind point constitutes a policy bank.

Following is an overview of different types of bind points for a policy:

• Request time global.

A policy can be available to all components in a feature at request time.

• Response time global.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1126

NetScaler 12.0

A policy can be available to all components in a feature at response time.

• Request time, virtual server-specific.
A policy can be bound to request-time processing for a particular virtual server. For example,
you can bind a request-time policy to a cache redirection virtual server to ensure that particular
requests are forwarded to a load balancing virtual server for the cache, and other requests are
sent to a load balancing virtual server for the origin.
• Response time, virtual server-specific.
A policy can also be bound to response-time processing for a particular virtual server.
• User-defined policy label.
For default syntax policies, you can configure custom groupings of policies (policy banks) by
defining a policy label and collecting a set of related policies under the policy label.
• Other bind points.
The availability of additional bind points depends on type of policy (classic or default syntax),
and specifics of the relevant NetScaler feature. For example, classic policies that you configure
for the
NetScaler Gateway have user and group bind points.
For additional information about default syntax policy bindings, see “Bind policies that use the de-
fault syntax” and Configure a policy bank for a virtual server. For additional information about classic
policy bindings, see “Configure a classic policy.”

About evaluation order of policies

For classic policies, policy groups and policies within a group are evaluated in a particular order, de-
pending on the following:
• The bind point for the policy, for example, whether the policy is bound to request-time process-
ing for a virtual server or global response-time processing. For example, at request time, the
NetScaler evaluates all request-time classic policies before evaluating any virtual server-specific
policies.
• The priority level for the policy. For each point in the evaluation process, a priority level that
is assigned to a policy determines the order of evaluation relative to other policies that share
the same bind point. For example, when the NetScaler evaluates a bank of request-time, virtual
server-specific policies, it starts with the policy that is assigned to the lowest priority value. In
classic policies, priority levels must be unique across all bind points.
For Advanced policies, as with classic policies, the NetScaler selects a grouping, or bank, of policies
at a particular point in overall processing. Following is the order of evaluation of the basic groupings,
or banks, of Advanced policies:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1127

NetScaler 12.0

1. Request-time global override

2. Request-time, virtual server-specific (one bind point per virtual server)
3. Request-time global default
4. Response-time global override
5. Response-time virtual server-specific
6. Response-time global default

However, within any of the preceding banks of policies, the order of evaluation is more flexible than
in classic policies. Within a policy bank, you can point to the next policy to be evaluated regardless of
the priority level, and you can invoke policy banks that belong to other bind points and user-defined
policy banks.

Order of evaluation based on traffic flow

As traffic flows through the NetScaler and is processed by various features, each feature performs pol-
icy evaluation. Whenever a policy matches the traffic, the NetScaler stores the action and continues
processing until the data is about to leave the NetScaler. At that point, the NetScaler typically applies
all matching actions. Integrated Caching, which only applies a final Cache or NoCache action, is an
exception.

Some policies affect the outcome of other policies. Following are examples:

• If a response is served from the integrated cache, some other NetScaler features do not process
the response or the request that initiated it.
• If the Content Filtering feature prevents a response from being served, no subsequent features
evaluate the response.

If the application firewall rejects an incoming request, no other features can process it.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Classic and advanced policy expressions

September 24, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1128

NetScaler 12.0

One of the most fundamental components of a policy is its rule. A policy rule is a logical expression that
enables the policy to analyze traffic. Most of the policy’s functionality is derived from its expression.
An expression matches characteristics of traffic or other data with one or more parameters and values.
For example, an expression can enable the NetScaler to accomplish the following:
• Determine whether a request contains a certificate.
• Determine the IP address of a client that sent a TCP request.
• Identify the data that an HTTP request contains (for example, a popular spreadsheet or word
processing application).
• Calculate the length of an HTTP request.

About classic expressions

Classic expressions enable you to evaluate basic characteristics of data. They have a structured syntax
that performs string matching and other operations.
Following are a few simple examples of classic expressions:
• An HTTP response contains a particular type of Cache Control header.
res.http.header Cache-Control contains public
• An HTTP response contains image data.
res.http.header Content-Type contains image/
• An SSL request contains a certificate.
req.ssl.client.cert exists

About advanced policy expressions

Any feature that uses default syntax policies also uses Advanced expressions. For information about
which features use Advanced policies, see the table NetScaler Feature, Policy Type, and Policy Usage.
Advanced policy expressions have a few other uses. In addition to configuring Advanced expressions
in policy rules, you configure Advanced
expressions in the following situations:
• Integrated Caching:
You use Advanced policy expressions to configure a selector for a content group in the integrated
cache.
• Load Balancing:
You use Advanced policy expressions to configure token extraction for a load balancing virtual
server that uses the TOKEN method for load balancing.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1129

NetScaler 12.0

• Rewrite:

You use Advanced policy expressions to configure rewrite actions.

• Rate-based policies:

You use Advanced policy expressions to configure limit selectors when configuring a policy to
control the rate of traffic to various servers.

Following are a few simple examples of Advanced policy expressions:

• An HTTP request URL contains no more than 500 characters.

http.req.url.length \<= 500

• An HTTP request contains a cookie that has fewer than 500 characters.

http.req.cookie.length \< 500

• An HTTP request URL contains a particular text string.

http.req.url.contains(”.html”)

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Converting policy expressions using NSPEPI tool

November 5, 2018

Contributed by:
C

You can convert a classic expression to the Advanced policy expression by using the nspepi conversion
tool. You can also use the tool to convert all the classic expressions in the NetScaler configuration
to the Advanced policy (with the exception of NetScaler entities that currently support only classic
expressions).

The conversion tool does not convert policies configured for the following features because the fea-
tures currently support only classic policies:

• Authentication, Pre-authentication
• SSL
• Cache redirection
• VPN (session, traffic, and tunnel traffic)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1130

NetScaler 12.0

• Content filtering (The responder feature not only provides you with functionality that is equiv-
alent to that provided by the content filtering feature but also surpasses the content filtering
feature in the use cases that it supports. Additionally, responder supports the more powerful
default syntax for policy expressions.)

The following NetScaler features support both classic and Advanced policy expression and, therefore,
support the conversion of classic expressions to Advanced policy expressions:

• Application firewall policies

• Authorization policies
• Named expressions
• Compression policies
• Content switching policies
• User-defined, rule-based tokens/persistency (the –rule parameter value that is specified for a
load balancing virtual server)

About the conversion process

When parsing a NetScaler configuration file, the conversion tool performs the following actions:

1. In commands that create classic named expressions, the conversion tool replaces the names of
the classic expressions with Advanced policy expression.
2. In commands that support only the classic policy, if classic named expressions are used, the
conversion tool replaces the names of the classic expressions with the actual classic expressions
they represent. This action ensures that the names of expressions in classic-only features do not
reference the Advanced policy expression created from Step 1.
3. In commands associated with entities that support both the classic syntax and the Advanced
policies, the conversion tool replaces all classic expressions in commands with Advanced policy
expressions.

Example:

Consider the following sample configuration commands:

1 add policy expression ne_c1 ”METHOD == GET”

2 add policy expression ne_c2 ”ne_c1 || URL == /*.htm ”
3 add filter policy pol1 -rule ”ne_c2” -reqAction YES
4 add cmp policy pol2 -rule ”REQ.HTTP.HEADER Accept CONTAINS \’text/html
\’” -resAction COMPRESS
5 add cmp policy pol3 -rule ”ne_c1 || ne_c2” -resAction GZIP

In the commands that create the classic named expressions ne_c1 and ne_c2, the tool replaces the
names of the expressions with actual Advanced policy expression. This action, which corresponds to
Step 1 described earlier, results in the following commands:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1131

NetScaler 12.0

1 add policy expression ne_c2 ”HTTP.REQ.METHOD.EQ(\”GET\”)”

2
3 add policy expression ne_c1 ”HTTP.REQ.URL.SUFFIX.EQ(\”htm\”)”

The filter policy command supports only the classic syntax. Therefore, the conversion tool replaces
the classic named expression ne_c1 with the actual classic expression it represents. Note that the
tool replaces ne_c1 in the expression for ne_c2, and then replaces ne_c2 in the filter policy with the
classic expression. This action, which corresponds to Step 2 described earlier, results in the following
command:

add filter policy pol1 -rule ”METHOD == GET || URL == /\*.htm”-reqAction

YES

The compression feature supports both classic and Advanced policy expression. Therefore, in the
command that creates the compression policy pol2, the conversion tool replaces the expression with
Advanced policy expression. This action, which corresponds to Step 3 described earlier, results in the
following command:

add cmp policy pol2 -rule ”HTTP.REQ.HEADER(\”Accept\”).AFTER_STR(\”text/

html\”).LENGTH.GT(0)”-resAction COMPRESS

The command that creates the compression policy pol3 is unaffected by the conversion process be-
cause, after the conversion process is complete, ne_c1 and ne_c2 reference the Advanced policy ex-
pression that results from Step 1.

Client security messages are not supported in the newer default policy format and, therefore, are lost.
The
SYS.EVAL_CLASSIC_EXPR function is replaced with a Advanced policy expression. The following enti-
ties support the
SYS.EVAL_CLASSIC_EXPR function:

• DNS policies
• Rate limit selectors
• Cache selectors
• Cache policies
• Content switching policies
• Rewrite policies
• URL transformation policies
• Responder policies
• Application firewall policies
• Authorization policies
• Compression policies
• CVPN access policies

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1132

NetScaler 12.0

After performing the conversion, the tool saves the changes in a new configuration file. The new config-
uration file is created in the directory in which the input file exists. The name of the new configuration
file is the same as the name of the input configuration file except for the string new_ used as a prefix.
Conversion warnings are reported in a warning line at the end of the screen output. Additionally, a
warning file is created in the directory in which the input configuration file resides. For more informa-
tion about the warning file and the types of warnings that are reported, see “Conversion warnings.”

Convert expressions

You can use the nspepi tool to convert a single classic expression to the Advanced policy expression.
The nspepi tool must be run from the shell prompt on the NetScaler appliance.

Convert a classic expression to the Advanced policy by using the CLI

At the shell prompt, type:

‘nspepi -e “<classic expression>”

Example:

1 root@NS# nspepi -e ”REQ.HTTP.URL == /*.htm”

2 ”HTTP.REQ.URL.REGEX_MATCH(re#/(.*)\.htm#)”

Convert a NetScaler configuration file

You can use the nspepi tool to convert all the classic expressions in a NetScaler configuration file to the
Advanced policy (except for those commands that do not support the Advanced policy). The nspepi
tool must be run from the shell prompt on the NetScaler appliance.

Convert all the classic expressions in a NetScaler configuration file to the default syntax by
using the CLI

At the shell prompt, type:

nspepi -f “<ns config file>” -v

Example:

1 root@NS# nspepi -f ns.conf

2 OUTPUT: New configuration file created: new_ns.conf
3 OUTPUT: New warning file created: warn_ns.conf
4 WARNINGS: Total number of warnings due to bind commands: 18

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1133

NetScaler 12.0

5 WARNINGS: Line numbers which has bind command issues: 305, 306, 706,
707, 708, 709, 710, 711, 712, 713,
6 714, 715, 767, 768, 774, 775, 776, 777
7 root@NS#

Conversion warnings

When classic expressions that are included in CLI commands are upgraded to the Advanced policy,
the number of characters in the expression might exceed the 1499-character limit. The commands
that include expressions longer than 1499 characters fail when the configuration is being applied. You
must manually update these commands.

In addition, multiple classic policies can be bound to a given bind point with priority 0 or with equal
priority, but the Advanced policy infrastructure does not support a priority value of 0 or policies with
the same priority at a given bind point. These commands fail when the configuration is being applied.
The commands must be updated manually with the correct priority values.

The line numbers of lines that threw a warning during conversion are listed at the end of the output in
a warning line. In addition, a warning file is created in the same directory as the one in which the old
and new configuration files reside. The name of the warning file is the same as the name of the input
configuration file except that the string warn_ is added as a prefix.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Before you proceed

September 24, 2018

Contributed by:
C

Before configuring expressions and policies, be sure you understand the relevant NetScaler feature
and the structure of your data, as follows:

• Read the documentation on the relevant feature.

• Look at the data stream for the type of data that you want to configure.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1134

NetScaler 12.0

You may want to run a trace on the type of traffic or content that you want to configure. This will give
you an idea of the parameters and values, and operations on these parameters and values, that you
need to specify in an expression.

Note: The NetScaler supports either classic or Advanced policy within a feature. You cannot have
both types in the same feature. Over the past few releases, some NetScaler features have migrated
from using classic policies and expressions to Advanced policy and expressions. If a feature of inter-
est to you has changed to the Advanced policy format, you may have to manually migrate the older
information. Following are guidelines for deciding if you need to migrate your policies:

• If you configured classic policies in a version of the Integrated Caching feature prior to release
9.0 and then upgrade to version 9.0 or later, there is no impact. All legacy policies are migrated
to the Advanced policy format.
• For other features, you need to manually migrate classic policies and expressions to the Ad-
vanced syntax if the feature has migrated to the Advanced policy.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configure advanced policy infrastructure

September 24, 2018

Contributed by:
C

You can create advanced policies for various NetScaler features, including DNS, Rewrite, Responder,
and Integrated Caching, and the clientless access function in the NetScaler Gateway. Policies control
the behavior of these features.

When you create a policy, you assign it a name, a rule (an expression), feature-specific attributes, and
an action that is taken when data matches the policy. After creating the policy, you determine when
it is invoked by binding it globally or to either request-time or response-time processing for a virtual
server.

Policies that share the same bind point are known as a policy bank. For example, all policies that are
bound to a virtual server constitute the policy bank for the virtual server. When binding the policy, you
assign it a priority level to specify when it is invoked relative to other policies in the bank. In addition
to assigning a priority level, you can configure an arbitrary evaluation order for policies in a bank by
specifying Goto expressions.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1135

NetScaler 12.0

In addition to policy banks that are associated with a built-in bind point or a virtual server, you can
configure policy labels. A policy label is a policy bank that is identified by an arbitrary name. You
invoke a policy label, and the policies in it, from a global or virtual-server-specific policy bank. A policy
label or a virtual-server policy bank can be invoked from multiple policy banks.
For some features, you can use the policy manager to configure and bind policies.
1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Rules for names in identifiers used in policies

September 24, 2018

Contributed by:
C
The names of identifiers in the named expression, HTTP callout, pattern set, and rate limiting fea-
tures must begin with an ASCII alphabet or an underscore (_). The remaining characters can be ASCII
alphanumeric characters or underscores (_).
The names of these identifiers must not begin with the following reserved words:
• The words ALT, TRUE, or FALSE or the Q or S one-character identifier.
• The special-syntax indicator RE (for regular expressions) or XP (for XPath expressions).
• Expression prefixes, which currently are the following:
– CLIENT
– EXTEND
– HTTP
– SERVER
– SYS
– TARGET
– TEXT
– URL
– MYSQL
– MSSQL
Additionally, the names of these identifiers cannot be the same as the names of enumeration con-
stants used in the policy infrastructure. For example, the name of an identifier cannot be IGNORE-
CASE, YEAR, or LATIN2_CZECH_CS (a MySQL character set).

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1136

NetScaler 12.0

Note: The NetScaler appliance performs a case-insensitive comparison of identifiers with these words
and enumeration constants. For example, names of the identifiers cannot begin with
TRUE,
True, or
true.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Create or modify a policy

September 24, 2018

Contributed by:
C

All policies have some common elements. Creating a policy consists, at minimum, of naming the pol-
icy and configuring a rule. The policy configuration tools for the various features have areas of overlap,
but also differences. For the details of configuring a policy for a particular feature, including associat-
ing an action with the policy, see the documentation for the feature.

To create a policy, begin by determining the purpose of the policy. For example, you may want to
define a policy that identifies HTTP requests for image files, or client requests that contain an SSL
certificate. In addition to knowing the type of information that you want the policy to work with, you
need to know the format of the data that the policy is analyzing.

Next, determine whether the policy is globally applicable, or if it pertains to a particular virtual server.
Also consider the effect that the order in which your policies are evaluated (which will be determined
by how you bind the policies) will have on the policy that you are about to configure.

Create a policy by using the CLI

At the command prompt, type the following commands to create a policy and verify the configuration:

1 - add responder|dns|cs|rewrite|cache policy <policyName> -rule <

expression> [<feature-specific information>]
2
3 - show rewrite policy <name>

Example 1:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1137

NetScaler 12.0

1 add rewrite policy ”pol_remove-ae” true ”act_remove-ae”

2 Done
3 > show rewrite policy pol_remove-ae
4 Name: pol_remove-ae
5 Rule: true
6 RewriteAction: act_remove-ae
7 UndefAction: Use Global
8 Hits: 0
9 Undef Hits: 0
10 Bound to: GLOBAL RES_OVERRIDE
11 Priority: 90
12 GotoPriorityExpression: END
13 Done

Example 2:

1 add cache policy BranchReportsCachePolicy -rule q{

2 http.req.url.query.value(”actionoverride”).contains(”branchReport s”)
}
3 -action cache
4 Done
5 show cache policy BranchReportsCachePolicy
6 Name: BranchReportsCachePolicy
7 Rule: http.req.url.query.value(”actionoverride”).contains(”
branchReports”)
8 CacheAction: CACHE
9 Stored in group: DEFAULT
10 UndefAction: Use Global
11 Hits: 0
12 Undef Hits: 0
13 Done

Note: At the command line, quote marks within a policy rule (the expression) must be escaped or
delimited with the q delimiter. For more information, seeConfigure advanced policy expressions: Get
started.

Create or modify a policy by using the GUI

1. In the navigation pane, expand the name of the feature for which you want to configure a policy,
and then click Policies. For example, you can select Content Switching, Integrated Caching,
DNS, Rewrite, or Responder.
2. In the details pane, click Add, or select an existing policy and click Open. A policy configuration
dialog box appears.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1138

NetScaler 12.0

3. Specify values for the following parameters. (An asterisk indicates a required parameter. For a
term in parentheses, see the corresponding parameter in “Parameters for creating or modifying
a policy.”)
4. Click Create, and then click Close.
5. Click Save. A policy is added.
Note: After you create a policy, you can view the policy’s details by clicking the policy entry in the
configuration pane. Details that are highlighted and underlined are links to the corresponding
entity (for example, a named expression).

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Policy configuration examples

September 24, 2018

Contributed by:
C

These examples show how policies and their associated actions are entered at the command line inter-
face. In the GUI, the expressions would appear in the Expression window of the feature-configuration
dialog box for the integrated caching or rewrite feature.

Following is an example of creating a caching policy. Note that actions for caching policies are built
in, so you do not need to configure them separately from the policy.

1 add cache policy BranchReportsCachePolicy -rule q{

2 http.req.url.query.value(”actionoverride”).contains(”branchReports”) }
3 -action cache

Following is an example of a rewrite policy and action:

1 add rewrite action myAction1 INSERT_HTTP_HEADER ”myHeader” ”

valueForMyHeader”
2 add rewrite policy myPolicy1 ”http.req.url.contains(\”myURLstring\”)”
myAction1

Note: At the command line, quote marks within a policy rule (the expression) must be escaped or
delimited with the q delimiter. For more information, see Configure advanced policy expressions: Get
started.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1139

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Bind policies using advanced policy

September 24, 2018

Contributed by:
C

After defining a policy, you indicate when the policy is to be invoked by binding the policy to a bind
point and specifying a priority level. You can bind a policy to only one bind point. A bind point can
be global, that is, it can apply to all virtual servers that you have configured. Or, a bind point can
be specific to a particular virtual server, which can be either a load balancing or a content switching
virtual server. Not all bind points are available for all features.

The order in which policies are evaluated determines the order in which they are applied, and features
typically evaluate the various policy banks in a particular order. Sometimes, however, other features
can affect the order of evaluation. Within a policy bank, the order of evaluation depends on the values
of parameters configured in the policies. Most features apply all of the actions associated with policies
whose evaluation results in a match with the data that is being processed. The integrated caching
feature is an exception.

Feature-specific differences in policy bindings

You can bind policies to built-in, global bind points (or banks), to virtual servers, or to policy labels.

However, the NetScaler features differ in terms of the types of bindings that are available. The follow-
ing table summarizes how you use policy bindings in various NetScaler features that use policies.

Virtual Servers Policies Bind Points

Configured in Configured in Configured for Use of Policies in
Feature Name the Feature the Feature the Policies the Feature

DNS none DNS policies Global To determine

how to perform
DNS resolution
for requests.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1140

NetScaler 12.0

Virtual Servers Policies Bind Points

Configured in Configured in Configured for Use of Policies in
Feature Name the Feature the Feature the Policies the Feature

Content Content Content Content To determine

Switching Switching (CS) Switching switching or what server or
(Note: This policies cache group of servers
feature can redirection is responsible
support either or virtual server; for serving
classic or Policy label responses,
Advanced based on
policies, but not characteristics
both.) of an incoming
request. Request
characteristics
include device
type, language,
cookies, HTTP
method, content
type, and
associated
cache server.
Integrated none Caching policies Global override, To determine
Caching Global default, whether HTTP
Policy label, load responses can
balancing, be stored in, and
content served from, the
switching, or SSL NetScaler
offload virtual appliance’s
server integrated
cache.
Responder none Responder Global override, To configure the
policies Global default, behavior of the
Policy label, load Responder
balancing, function.
content
switching, or SSL
offload virtual
server

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1141

NetScaler 12.0

Virtual Servers Policies Bind Points

Configured in Configured in Configured for Use of Policies in
Feature Name the Feature the Feature the Policies the Feature

Rewrite none Rewrite policies Global override, To identify HTTP

Global default, data that you
Policy label, load want to modify
balancing, before serving.
content The policies
switching, or SSL provide rules for
offload virtual modifying the
server data. For
example, you
can modify
HTTP data to
redirect a
request to a
selected server
based on the
address of the
incoming
request, or to
mask server
information in a
response for
security
purposes.
URL Transform none Transformation Global override, To identify URLs
function in the policies Global default, in HTTP
Rewrite feature Policy label transactions and
text files for the
purpose of
evaluating
whether a URL
should be
altered.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1142

NetScaler 12.0

Virtual Servers Policies Bind Points

Configured in Configured in Configured for Use of Policies in
Feature Name the Feature the Feature the Policies the Feature

NetScaler Gate- VPN server Clientless Access VPN Global, VPN To determine
way (clientless policies server how
VPN functions the NetScaler
only) Gateway per-
forms
authentication,
authorization,
auditing, and
other functions,
and to define
rewrite rules for
general Web
access using
the NetScaler
Gateway.

Bind points and order of evaluation

For a policy to take effect, you must ensure that the policy is invoked at some point during processing.
To do so, you associate the policy with a bind point. The collection of policies that is bound to a bind
point is known as a policy bank.

Following are the bind points that the NetScaler evaluates, listed in the typical order of evaluation
within a policy bank

1. Request-time override. When a request flows through a feature, the NetScaler first evaluates
request-time override policies for the feature.
2. Request-time Load Balancing virtual server. If policy evaluation cannot be completed after all
the request-time override policies have been evaluated, the NetScaler processes request-time
policies for load balancing virtual servers.
3. Request-time Content Switching virtual server. If policy evaluation cannot be completed
after all the request-time policies for load balancing virtual servers have been evaluated, the
NetScaler processes request-time policies for content switching virtual servers.
4. Request-time default. If policy evaluation cannot be completed after all request-time, virtual
server-specific policies have been evaluated, the NetScaler processes request-time Advanced
policies.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1143

NetScaler 12.0

5. Response-time override. At response time, the NetScaler starts with policies that are bound
to the response-time override bind point.
6. Response-time Load Balancing virtual server. If policy evaluation cannot be completed after
all response-time override policies have been evaluated, the NetScaler process the response-
time policies for load balancing virtual servers.
7. Response-time Content Switching virtual server. If policy evaluation cannot be completed
after all policies have been evaluated for load balancing virtual servers, the NetScaler process
the response-time policies for content switching virtual servers.
8. Response-time default. If policy evaluation cannot be completed after all response-time,
virtual-server-specific policies have been evaluated, the NetScaler processes response-time
Advanced policies.

Policy evaluation across features

In addition to attending to evaluation of policies within a feature, if you have bound policies to a con-
tent switching virtual server, note that these policies are evaluated before other policies. Binding a
policy to a content switching vserver produces a different result in NetScaler versions 9.0.x and later
than in 8.x versions. In NetScaler 9.0 and later versions, evaluation occurs as follows:
• Content switching policies are evaluated before other policies. If a content switching policy
evaluates to TRUE, the target load balancing vserver is selected.
• If all content switching policies evaluate to FALSE, the default load balancing vserver under the
content switching VIP is selected.
After a target load balancing vserver is selected by the content switching process, policies are evalu-
ated in the following order:
1. Policies that are bound to the global override bind point.
2. Policies that are bound to the default load balancing vserver.
3. Policies that are bound to the target content switching vserver.
4. Policies that are bound to the global default bind point.
To be sure that the policies are evaluated in the intended order, follow these guidelines:
• Make sure that the default load balancing vserver is not directly reachable from the outside; for
example, the vserver IP address can be 0.0.0.0.
• To prevent exposing internal data on the load balancing default vserver, configure a policy to re-
spond with a “503 Service Unavailable” status and bind it to the default load balancing vserver.

Entries in a policy bank

Each entry in a policy bank has, at minimum, a policy and a priority level. You can also configure
entries that change the priority-based evaluation order, and you can configure entries that invoke

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1144

NetScaler 12.0

external policy banks.

The following table summarizes each entry in a policy bank.

Policy Bank to
Policy Name Priority Goto Expression Invocation Type Be Invoked

The policy name, An integer. Optional. Optional. Optional. Used

or a “dummy” Identifies the Indicates that an with Invocation
policy named next policy in the external policy Type. This is the
NOPOLICY. The bank to bank will be label for a policy
NOPOLICY entry evaluate, or invoked. This bank or a virtual
controls ends any further field restricts the server name.
evaluation flow evaluation choices to a The NetScaler
without global policy returns to the
processing a label or a virtual current bank
rule. server. after processing
the external
bank.

If the policy evaluates to TRUE, the NetScaler stores the action that is associated with the policy. If
the policy evaluates to FALSE, the NetScaler evaluates the next policy. If the policy is neither TRUE
nor FALSE, the NetScaler uses the associated Undef (undefined) action.

Evaluation order within a policy bank

Within a policy bank, the evaluation order depends on the following items:

• A priority.

The most minimal amount of information about evaluation order is a numeric priority level. The
lower the number, the higher the priority.

• A Goto expression.

If supplied, the Goto expression indicates the next policy to be evaluated, typically within the
same policy bank.. Goto expressions can only proceed forward in a bank. To prevent looping, a
policy bank configuration is not valid if a Goto statement points backwards in the bank.

• Invocation of other policy banks.

Any entry can invoke an external policy bank. The NetScaler provides a built-in entity named
NOPOLICY that does not have a rule. You can add a NOPOLICY entry in a policy bank when you

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1145

NetScaler 12.0

want to invoke another policy bank, but do not want to process any other rules prior to the
invocation. You can have multiple NOPOLICY entries in multiple policy banks.

Values for a Goto expression are as follows:

• NEXT.

This keyword selects the policy with the next higher priority level in the current policy bank.

• An integer.

If you supply an integer, it must match the priority level of another policy in the current policy
bank.

• END.

This keyword stops evaluation after processing the current policy, and no additional policies in
this bank are processed.

• Blank.

If the Goto expression is empty, it is the same as specifying END.

• A numeric expression.

This is an advanced policy expression that resolves to a priority number for another policy in
the current bank.

• USE_INVOCATION_RESULT.

This phrase can be used only if you are invoking an external policy bank. Entering this phrase
causes the NetScaler to perform one of the following actions:

– If the final Goto in the invoked policy bank has a value of END or is empty, the invocation
result is END, and evaluation stops.
– If the final Goto expression in the invoked policy bank is anything other than END, the
NetScaler performs a NEXT.

The following table illustrates a policy bank that uses Goto statements and policy bank invocations.

Policy Bank to
Policy Name Priority Goto Invocation Be Invoked

ClientCertificatePolicy
100 300 None None
(rule: does the
request contain
a client
certificate?)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1146

NetScaler 12.0

Policy Bank to
Policy Name Priority Goto Invocation Be Invoked

SubnetPolicy 200 NEXT None None

(rule: is the
client from a
private subnet?)
NOPOLICY 300 USE Request vserver My_Request_VServer
INVOCATION
RESULT
NOPOLICY 350 USE Policy Label My_Policy_Label
INVOCATION
RESULT
WorkingHoursPolicy400 END None None
(rule: is it
working hours?)

Table 3. Example of a Policy Bank That Uses Gotos and External Bank Invocations

How policy evaluation ends

Evaluation of a policy bank ends when one of the following takes place:

• A policy evaluates to TRUE and its Goto statement value is END.

No further policies or policy banks in this feature are evaluated.

• An external policy bank is invoked, its evaluation returns an END, and the Goto statement uses
a value of USE_INVOCATION_RESULT or END.

Evaluation continues with the next policy bank for this feature. For example, if the current bank
is the request-time override bank, the NetScaler next evaluates request-time policy banks for
the virtual servers.

• The NetScaler has walked through all the policy banks in this feature, but has not encountered
an END.

If this is the last entry to be evaluated in this policy bank, the NetScaler proceeds to the next
feature.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1147

NetScaler 12.0

How features use actions after policy evaluation

After evaluating all relevant policies for a particular data point (for example, an HTTP request), the
NetScaler stores all the actions that are associated with any policy that matched the data.

For most features, all the actions from matching policies are applied to a traffic packet as it leaves the
NetScaler. The Integrated Caching feature only applies one action: CACHE or NOCACHE. This action
is associated with the policy with the lowest priority value in the “highest priority” policy bank (for
example, request-time override policies are applied before virtual server-specific policies).

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Bind a policy globally

September 24, 2018

Contributed by:
C

The following binding procedures are typical. However, refer to the documentation for the feature of
interest to you for complete instructions.

Bind an integrated caching policy globally by using the CLI

At the command prompt, type the following commands to bind an Integrated Caching policy and ver-
ify the configuration:

1 - bind cache global <policy> -priority <positiveInteger> [-type

REQ_OVERRIDE | REQ_DEFAULT | RES_OVERRIDE | RES_DEFAULT]
2
3 - show cache global

Example:

1 > bind cache global _nonPostReq -priority 100 -type req_default

2 Done
3 > show cache global
4 1) Global bindpoint: REQ_DEFAULT
5 Number of bound policies: 2

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1148

NetScaler 12.0

6
7 2) Global bindpoint: RES_DEFAULT
8 Number of bound policies: 1
9 Done

The type argument is optional to maintain backward compatibility. If you omit the type, the policy is
bound to REQ_DEFAULT or RES_DEFAULT, depending on whether the policy rule is a response-time or
a request-time expression.

Bind a rewrite policy globally by using the CLI

At the command prompt, type the following commands to bind a Rewrite policy and verify the config-
uration:

1 - bind rewrite global <policyName> <priority> [-type REQ_OVERRIDE |

REQ_DEFAULT | RES_OVERRIDE | RES_DEFAULT]
2
3 - show rewrite global

Example:

1 bind rewrite global pol_remove-pdf 100

2 Done
3 > show rewrite global
4 1) Global bindpoint: REQ_DEFAULT
5 Number of bound policies: 1
6
7 2) Global bindpoint: REQ_OVERRIDE
8 Number of bound policies: 1
9
10 Done

The type argument is optional for globally bound policies, to maintain backward compatibility. If you
omit the type, the policy is bound to REQ_DEFAULT or RES_DEFAULT, depending on whether the policy
rule is a response-time or a request-time expression.

Bind a compression policy globally by using the CLI

At the command prompt, type the following commands to bind a compression policy and verify the
configuration:

1 - bind cmp global <policyName> -priority <positiveInteger> [-type

REQ_OVERRIDE | REQ_DEFAULT | RES_OVERRIDE | RES_DEFAULT]

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1149

NetScaler 12.0

2
3 - show cmp global

Example:

1 > bind cmp global cmp_pol_1 -priority 100

2 Done
3 > show cmp policy cmp_pol_1
4 Name: cmp_pol_1
5 Rule: HTTP.REQ.URL.SUFFIX.EQ(”BMP”)
6 Response Action: COMPRESS
7 Hits: 0
8
9 Policy is bound to following entities
10 1) GLOBAL REQ_DEFAULT
11 Priority: 100
12 GotoPriorityExpression: END
13 Done

Bind a responder policy globally by using the CLI

At the command prompt, type the following commands to bind a Responder policy and verify the
configuration:

1 - bind responder global <policyName> <priority> [-type OVERRIDE |

DEFAULT ]
2
3 - show responder global

Example:

1 bind responder global pol404Error1 200

2 Done
3 > show responder global
4 1) Global bindpoint: REQ_DEFAULT
5 Number of bound policies: 1
6
7 Done

Bind a DNS policy globally by using the CLI

At the command prompt, type the following commands to bind a DNS policy and verify the configura-
tion:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1150

NetScaler 12.0

1 - bind dns global <policyName> <priority>

2
3 - show dns global

Example:

1 > bind dns global pol_ddos_drop1 150

2 Done
3 > show dns global
4 Policy name : pol_ddos_drop
5 Priority : 100
6 Goto expression : END
7 Policy name : pol_ddos_drop1
8 Priority : 150
9 Done

Bind an integrated caching, responder, rewrite, or compression policy globally by

using the GUI

1. In the navigation pane, click the name of the feature for which you want to bind the policy.
2. In the details pane, click <Feature Name> policy manager.
3. In the Policy Manager dialog box, select the bind point to which you want to bind the policy
(for example, for Integrated Caching, Rewrite, or Compression, you could select Request and
Default Global). The Responder does not differentiate between request-time and response-time
policies.
4. Click Insert Policy and, from the Policy Name pop-up menu, select the policy name. A priority is
assigned automatically to the policy, but you can click the cell in the Priority column and drag it
anywhere within the dialog box if you want the policy to be evaluated after other policies in this
bank. The priority is automatically reset. Note that priority values within a policy bank must be
unique.
5. Click Apply Changes.
6. Click Close. A message in the status bar indicates that the policy is bound successfully.

Bind a DNS policy globally by using the GUI

1. Navigate to Traffic Management > DNS > Policies.

2. In the details pane, click Global Bindings.
3. In the global bindings dialog box, click Insert Policy, and select the policy that you want to bind
globally.
4. Click in the Priority field and enter the priority level.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1151

NetScaler 12.0

5. Click OK. A message in the status bar indicates that the policy is bound successfully.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Bind a policy to a virtual server

September 24, 2018

Contributed by:
C

A globally bound policy applies to all load balancing and content switching virtual servers.

Note that when binding a policy to a virtual server, you must identify it as a request-time or a response-
time policy.

Bind a policy to a load balancing or content switching virtual server by using the CLI

At the command prompt, type the following commands to bind a policy to a load balancing or content
switching virtual server and verify the configuration:

1 - bind lb|cs vserver <virtualServerName> -policyName <policyName> -

priority <positiveInteger> -type REQUEST|RESPONSE
2
3 - show lb vserver <name>

Example:

1 > bind lb vserver lbvip -policyName ns_cmp_msapp -priority 50

2 Done
3 > show lb vserver lbvip
4 lbvip (8.7.6.6:80) - HTTP Type: ADDRESS
5 State: DOWN
6 Last state change was at Wed Jul 15 05:54:24 2009 (+226 ms)
7 Time since last state change: 28 days, 01:57:26.350
8 Effective State: DOWN
9 Client Idle Timeout: 180 sec
10 Down state flush: ENABLED
11 Disable Primary Vserver On Down : DISABLED
12 Port Rewrite : DISABLED

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1152

NetScaler 12.0

13 No. of Bound Services : 0 (Total) 0 (Active)

14 Configured Method: LEASTCONNECTION
15 Mode: IP
16 Persistence: NONE
17 Vserver IP and Port insertion: OFF
18 Push: DISABLED Push VServer:
19 Push Multi Clients: NO
20 Push Label Rule: none
21
22 1) Policy : ns_cmp_msapp Priority:50
23 2) Policy : cf-pol Priority:1 Inherited
24 Done

Bind a policy to an SSL offload virtual server by using the CLI

At the command prompt, type the following commands to bind a policy to an SSL offload virtual server
and verify the configuration:

bind ssl vserver <vServerName>@ -policyName <policyName> -priority <positiveInteger

>

Bind a policy to a virtual server by using the GUI

1. In the navigation pane, expand Traffic Management > Load Balancing, Traffic Management >
Content Switching, Traffic Management > SSL Offload, Security > AAA- Application Traffic, or
NetScaler Gateway, and then click Virtual Servers.
2. In the details pane, double-click the virtual server to which you want to bind the policy, and
then click Open.
3. On the Policies tab, click the icon for the type of policy that you want to bind (the choices are
feature-specific), and then click the name of the policy. Note that for some features, you can
bind both classic policies and policies that use the default syntax to the virtual server.
4. If you are binding a policy to a Content Switching virtual server, in the Target field select a load
balancing virtual server to which traffic that matches the policy is sent.
5. Click OK. A message in the status bar indicates that the policy is bound successfully.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1153

NetScaler 12.0

Display policy bindings

September 24, 2018

Contributed by:
C

You can display policy bindings to verify that they are correct.

Display policy bindings by using the CLI

At the command prompt, type the following commands to display policy bindings and verify the con-
figuration:

show rewrite policy <name>

Example:

1 > show rewrite policy pol_remove-pdf

2 Name: pol_remove-pdf
3 Rule: http.req.url.contains(”.pdf”)
4 RewriteAction: act_remove-ae
5 UndefAction: Use Global
6 Hits: 0
7 Undef Hits: 0
8 Bound to: GLOBAL REQ_DEFAULT
9 Priority: 100
10 GotoPriorityExpression: END
11 Done
12 >

Display global policy bindings for integrated caching, rewrite, or responder by using
the GUI

1. In the navigation pane, expand the feature that contains the policy that you want to view, and
then click Policies.
2. In the details pane, click the policy. Bound policies have a check mark next to them.
3. At the bottom of the page, under Details, next to Bound to, view the entity to which the policy
is bound.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1154

NetScaler 12.0

Display global policy bindings for DNS or clientless access in the NetScaler Gateway by
using the GUI

1. Navigate to Traffic Management > DNS > Policies.

2. In the details pane, click Global Bindings.

Display global policy bindings for content switching by using the GUI

1. Navigate to Traffic Management > Content Switching > Policies.

2. In detailed pane, select policy.
3. In the details pane, click Show Bindings.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Unbind a policy

September 24, 2018

Contributed by:
C

If you want to re-assign a policy or delete it, you must first remove its binding.

Unbind an integrated caching, rewrite, or compression advanced policy globally by

using the CLI

At the command prompt, type the following commands to unbind an integrated caching, rewrite, or
compression Advanced policy globally and verify the configuration:

1 - unbind cache|rewrite|cmp global <policyName> [-type req_override|

req_default|res_override|res_default] [-priority <positiveInteger>]
2
3 - show cache|rewrite|cmp global

Example:

1 > unbind cache global_nonPostReq

2 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1155

NetScaler 12.0

3 > show cache global

4 1) Global bindpoint: REQ_DEFAULT
5 Number of bound policies: 1
6
7 2) Global bindpoint: RES_DEFAULT
8 Number of bound policies: 1
9
10 Done

The priority is required only for the “dummy” policy named NOPOLICY.

Unbind a responder policy globally by using the CLI

At the command prompt, type the following commands to unbind a responder policy globally and
verify the configuration:

1 - unbind responder global <policyName> [-type override|default] [-

priority <positiveInteger>]
2
3 - show responder global

Example:

1 > unbind responder global pol404Error

2 Done
3 > show responder global
4 1) Global bindpoint: REQ_DEFAULT
5 Number of bound policies: 1
6 Done

The priority is required only for the “dummy” policy named NOPOLICY.

Unbind a DNS policy globally by using the CLI

At the command prompt, type the following commands to unbind a DNS policy globally and verify the
configuration:

1 - unbind responder global <policyName>

2
3 - unbind responder global

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1156

NetScaler 12.0

1 unbind dns global dfgdfg

2 Done
3 show dns global
4 Policy name : dfgdfggfhg
5 Priority : 100
6 Goto expression : END
7 Done

Unbind an advanced policy from a virtual server by using the CLI

At the command prompt, type the following commands to unbind an Advanced policy from a virtual
server and verify the configuration:

1 - unbind cs vserver <name> -policyName <policyName> [-priority <

positiveInteger>] [-type REQUEST|RESPONSE]
2
3 - show lb vserver <name>

Example:

1 unbind cs vserver vs-cont-switch -policyName pol1

2 Done
3 > show cs vserver vs-cont-switch
4 vs-cont-switch (10.102.29.10:80) - HTTP Type: CONTENT
5 State: UP
6 Last state change was at Wed Aug 19 08:56:55 2009 (+18 ms)
7 Time since last state change: 0 days, 02:47:55.750
8 Client Idle Timeout: 180 sec
9 Down state flush: ENABLED
10 Disable Primary Vserver On Down : DISABLED
11 Port Rewrite : DISABLED
12 State Update: DISABLED
13 Default: Content Precedence: RULE
14 Vserver IP and Port insertion: OFF
15 Case Sensitivity: ON
16 Push: DISABLED Push VServer:
17 Push Label Rule: none
18 Done

The priority is required only for the “dummy” policy named NOPOLICY.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1157

NetScaler 12.0

Unbind an integrated caching, responder, rewrite, or compression Advanced policy

globally by using the GUI

1. In the navigation pane, click the feature with the policy that you want to unbind (for example,
Integrated Caching).
2. In the details pane, click <Feature Name> policy manager.
3. In the Policy Manager dialog box, select the bind point with the policy that you want to unbind,
for example, Advanced Global.
4. Click the policy name that you want to unbind, and then click Unbind Policy.
5. Click Apply Changes.
6. Click Close. A message in the status bar indicates that the policy is unbound successfully.

Unbind a DNS policy globally by using the GUI

1. Navigate to Traffic Management > DNS > Policies.

2. In the details pane, click Global Bindings.
3. In the Global Bindings dialog box, select policy and click unbind policy.
4. Click OK. A message in the status bar indicates that the policy is unbinded successfully.

Unbind an advanced policy from a load balancing or content switching virtual server
by using the GUI

1. Navigate to Traffic Management, and expand Load Balancing or Content Switching, and then
click Virtual Servers.
2. In the details pane, double-click the virtual server from which you want to unbind the policy.
3. On the Policies tab, in the Active column, clear the check box next to the policy that you want
to unbind.
4. Click OK. A message in the status bar indicates that the policy is unbinded successfully.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Create policy labels

September 24, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1158

NetScaler 12.0

Contributed by:
C

In addition to the built-in bind points where you set up policy banks, you can also configure user-
defined policy labels and associate policies with them.

Within a policy label, you bind policies and specify the order of evaluation of each policy relative to
others in the bank of policies for the policy label. The NetScaler also permits you to define an arbitrary
evaluation order as follows:

• You can use “goto” expressions to point to the next entry in the bank to be evaluated after the
current one.
• You can use an entry in a policy bank to invoke another bank.

Each feature determines the type of policy that you can bind to a policy label, the type of load balanc-
ing virtual server that you can bind the label to, and the type of content switching virtual server from
which the label can be invoked. For example, a TCP policy label can only be bound to a TCP load bal-
ancing virtual server. You cannot bind HTTP policies to a policy label of this type. And you can invoke
a TCP policy label only from a TCP content switching virtual server.

After configuring a new policy label, you can invoke it from one or more banks for the built-in bind
points.

Create a caching policy label by using the CLI

At the command prompt, type the following commands to create a Caching policy label and verify the
configuration:

1 - add cache policylabel <labelName> -evaluates req|res

2
3 - show cache policylabel<labelName>

Example:

1 > add cache policylabel lbl-cache-pol -evaluates req

2 Done
3
4 > show cache policylabel lbl-cache-pol
5 Label Name: lbl-cache-pol
6 Evaluates: REQ
7 Number of bound policies: 0
8 Number of times invoked: 0
9 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1159

NetScaler 12.0

Create a content switching policy label by using the CLI

At the command prompt, type the following commands to create a Content Switching policy label and
verify the configuration:

1 - add cs policylabel <labelName> http|tcp|rtsp|ssl

2
3 - show cs policylabel <labelName>

Example:

1 > add cs policylabel lbl-cs-pol http

2 Done
3 > show cs policylabel lbl-cs-pol
4 Label Name: lbl-cs-pol
5 Label Type: HTTP
6 Number of bound policies: 0
7 Number of times invoked: 0
8 Done

Create a rewrite policy label by using the CLI

At the command prompt, type the following commands to create a Rewrite policy label and verify the
configuration:

1 - add rewrite policylabel <labelName> http_req|http_res|url|text|

clientless_vpn_req|clientless_vpn_res
2
3 - show rewrite policylabel <labelName>

Example:

1 > add rewrite policylabel lbl-rewrt-pol http_req

2 Done
3
4 > show rewrite policylabel lbl-rewrt-pol
5 Label Name: lbl-rewrt-pol
6 Transform Name: http_req
7 Number of bound policies: 0
8 Number of times invoked: 0
9 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1160

NetScaler 12.0

Create a responder policy label by using the CLI

At the command prompt, type the following commands to create a Responder policy label and verify
the configuration:

1 - add responder policylabel <labelName>

2
3 - show responder policylabel <labelName>

Example:

1 > add responder policylabel lbl-respndr-pol

2 Done
3
4 > show responder policylabel lbl-respndr-pol
5 Label Name: lbl-respndr-pol
6 Number of bound policies: 0
7 Number of times invoked: 0
8 Done

Note: Invoke this policy label from a policy bank. For more information, see the “Binding a Policy to
a Policy Label” section.

Create a policy label by using the GUI

1. In the navigation pane, expand the feature for which you want to create a policy label, and then
click Policy Labels. The choices are Integrated Caching, Rewrite, Content Switching, or Respon-
der.
2. In the details pane, click Add.
3. In the Name box, enter a unique name for this policy label.
4. Enter feature-specific information for the policy label. For example, for Integrated Caching, in
the Evaluates drop-down menu, you would select REQ if you want this policy label to contain
request-time policies, or select RES if you want this policy label to contain response-time poli-
cies. For Rewrite, you would select a Transform name.
5. Click Create.
6. Configure one of the built-in policy banks to invoke this policy label. For more information, see
the “Binding a Policy to a Policy Label” section. A message in the status bar indicates that the
policy label is created successfully.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1161

NetScaler 12.0

Bind a policy to a policy label

As with policy banks that are bound to the built-in bind points, each entry in a policy label is a policy
that is bound to the policy label. As with policies that are bound globally or to a vserver, each policy
that is bound to the policy label can also invoke a policy bank or a policy label that is evaluated after
the current entry has been processed. The following table summarizes the entries in a policy label.

• Name. The name of a policy, or, to invoke another policy bank without evaluating a policy, the
“dummy” policy name NOPOLICY.

You can specify NOPOLICY more than once in a policy bank, but you can specify a named policy
only once.

• Priority. An integer. This setting can work with the Goto expression.

• Goto Expression. Determines the next policy to evaluate in this bank. You can provide one of
the following values:

– NEXT. Go to the policy with the next higher priority.

– END. Stop evaluation.
– USE_INVOCATION_RESULT. Applicable if this entry invokes another policy bank. If the
final Goto in the invoked bank has a value of END, evaluation stops. If the final Goto is
anything other than END, the current policy bank performs a NEXT.
– Positive number: The priority number of the next policy to be evaluated.
– Numeric expression. An expression that produces the priority number of the next policy
to be evaluated.

The Goto can only proceed forward in a policy bank.

If you omit the Goto expression, it is the same as specifying END.

• Invocation Type. Designates a policy bank type. The value can be one of the following:

– Request Vserver. Invokes request-time policies that are associated with a virtual server.
– Response Vserver. Invokes response-time policies that are associated with a virtual
server.
– Policy label. Invokes another policy bank, as identified by the policy label for the bank.

• Invocation Name. The name of a virtual server or a policy label, depending on the value that
you specified for the Invocation Type.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1162

NetScaler 12.0

Configure a policy label or virtual server policy bank

September 24, 2018

Contributed by:
C

After you have created policies, and created policy banks by binding the policies, you can perform
additional configuration of policies within a label or policy bank. For example, before you configure
invocation of an external policy bank, you might want to wait until you have configured that policy
bank.

This topic includes the following sections:

• Configure a policy label

• Configure a policy bank for a virtual server

Configure a policy label

A policy label consists of a set of policies and invocations of other policy labels and virtual server-
specific policy banks. An Invoke parameter enables you to invoke a policy label or a virtual server-
specific policy bank from any other policy bank. A special-purpose NoPolicy entry enables you to
invoke an external bank without processing an expression (a rule). The NoPolicy entry is a “dummy”
policy that does not contain a rule.

For configuring policy labels from the NetScaler command line, note the following elaborations of the
command syntax:

• gotoPriorityExpression is configured as described in Table 2. Format of Each Entry in a Policy

Bank of the section “Entries in a Policy Bank” in Bind policies using advanced policy.
• The type argument is required. This is unlike binding a conventional policy, where this argu-
ment is optional.
• You can invoke the bank of policies that are bound to a virtual server by using the same method
as you use for invoking a policy label.

Configure a policy label by using the CLI

At the command prompt, type the following commands to configure a policy label and verify the con-
figuration:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1163

NetScaler 12.0

1 - bind cache|rewrite|responder policylabel <policylabelName> -

policyName <policyName> -priority <priority> [-
gotoPriorityExpression <gotopriorityExpression>] [-invoke reqvserver
|resvserver|policylabel <policyLabelName>|<vserverName>]
2
3 - show cache|rewrite|responder policylabel <policylabelName>

Example:

1bind cache policylabel _reqBuiltinDefaults -policyName _nonGetReq -

priority 100
2 Done
3 show cache policylabel _reqBuiltinDefaults
4 Label Name: _reqBuiltinDefaults
5 Evaluates: REQ
6 Number of bound policies: 3
7 Number of times invoked: 0
8 1) Policy Name: _nonGetReq
9 Priority: 100
10 GotoPriorityExpression: END
11 2) Policy Name: _advancedConditionalReq
12 Priority: 200
13 GotoPriorityExpression: END
14
15 3) Policy Name: _personalizedReq
16 Priority: 300
17 GotoPriorityExpression: END
18 Done

Invoke a policy label from a rewrite policy bank with a NOPOLICY entry by using the CLI

At the command prompt, type the following commands to invoke a policy label from a Rewrite policy
bank with a NOPOLICY entry and verify the configuration:

1 - bind rewrite global <policyName> <priority> <gotoPriorityExpression>

-type REQ_OVERRIDE|REQ_DEFAULT|RES_OVERRIDE|RES_DEFAULT -invoke
reqvserver|resvserver|policylabel <policyLabelName>|<vserverName>
2
3 - show rewrite global

Example:

1 > bind rewrite global NOPOLICY 100 -type REQ_DEFAULT -invoke

policylabel lbl-rewrt-pol

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1164

NetScaler 12.0

2 Done
3 > show rewrite global
4 1) Global bindpoint: REQ_DEFAULT
5 Number of bound policies: 1
6
7 2) Global bindpoint: REQ_OVERRIDE
8 Number of bound policies: 1
9 Done

Invoke a policy label from an Integrated Caching policy bank by using the CLI

At the command prompt, type the following commands to invoke a policy label from an Integrated
Caching policy bank and verify the configuration:

1 - bind cache global NOPOLICY -priority <priority> -

gotoPriorityExpression <gotopriorityExpression> -type REQ_OVERRIDE|
REQ_DEFAULT|RES_OVERRIDE|RES_DEFAULT -invoke reqvserver|resvserver|
policylabel <policyLabelName>|<vserverName>
2
3 - show cache global

Example:

1 bind cache global NOPOLICY -priority 100 -gotoPriorityExpression END -

type REQ_DEFAULT -invoke policylabel lbl-cache-pol
2 Done
3 > show cache global
4 1) Global bindpoint: REQ_DEFAULT
5 Number of bound policies: 2
6
7 2) Global bindpoint: RES_DEFAULT
8 Number of bound policies: 1
9
10 Done

Invoke a policy label from a Responder policy bank by using the CLI

At the command prompt, type the following commands to invoke a policy label from a Responder
policy bank and verify the configuration:

1 - bind responder global NOPOLICY <priority> <gotopriorityExpression> -

type OVERRIDE|DEFAULT -invoke vserver|policylabel <policyLabelName
>|<vserverName>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1165

NetScaler 12.0

2
3 - show responder global

Example:

1 > bind responder global NOPOLICY 100 NEXT -type DEFAULT -invoke
policylabel lbl-respndr-pol
2 Done
3 > show responder global
4 1) Global bindpoint: REQ_DEFAULT
5 Number of bound policies: 2
6
7 Done

Configure a policy label by using the GUI

1. In the navigation pane, expand the feature for which you want to configure a policy label, and
then click Policy Labels. The choices are Integrated Caching, Rewrite, or Responder.

2. In the details pane, double-click the label that you want to configure.

3. If you are adding a new policy to this policy label, click Insert Policy, and in the Policy Name
field, select New Policy. For more information about adding a policy, see Create or modify a
policy. Note that if you are invoking a policy bank, and do not want a rule to be evaluated prior
to the invocation, click Insert Policy, and in the Policy Name field select NOPOLICY.

4. For each entry in this policy label, configure the following:

• Policy Name:

This is already determined by the Policy Name, new policy, or NOPOLICY entry that you
inserted in this bank.

• Priority:

A numeric value that determines either an absolute order of evaluation within the bank,
or is used in conjunction with a Goto expression.

• Expression:

The policy rule. Policy expressions are described in detail in the following chapters. For
an introduction, see
Configure advanced policy expressions: Get started.

• Action:

The action to be taken if this policy evaluates to TRUE.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1166

NetScaler 12.0

• Goto Expression:

Optional. Used to augment the Priority level to determine the next policy or policy bank
to evaluate. For more information on possible values for a Goto expression, see Table 2.
Format of Each Entry in a Policy Bank of the section “Entries in a Policy Bank” in
Bind policies using advanced policy.

• Invoke:

Optional. Invokes another policy bank.

5. Click OK. A message in the status bar indicates that the policy label is configured successfully.

Configure a policy bank for a virtual server

You can configure a bank of policies for a virtual server. The policy bank can contain individual policies,
and each entry in the policy bank can optionally invoke a policy label or a bank of policies that you
configured for another virtual server. If you invoke a policy label or policy bank, you can do so without
triggering an expression (a rule) by selecting a NOPOLICY “dummy” entry instead of a policy name.

Add policies to a virtual server policy bank by using the CLI

At the command prompt, type the following commands to add policies to a virtual server policy bank
and verify the configuration:

1 - bind lb|cs vserver <virtualServerName> <serviceType> [-policyName <

policyName>] [-priority <positiveInteger>] [-gotoPriorityExpression
<expression>] [-type REQUEST|RESPONSE]
2
3 - show lb|cs vserver <virtualServerName>

Example:

1 add lb vserver vs-cont-sw TCP

2 Done
3 show lb vserver vs-cont-sw
4 vs-cont-sw (0.0.0.0:0) - TCP Type: ADDRESS
5 State: DOWN
6 Last state change was at Wed Aug 19 10:04:02 2009 (+279 ms)
7 Time since last state change: 0 days, 00:02:14.420
8 Effective State: DOWN
9 Client Idle Timeout: 9000 sec
10 Down state flush: ENABLED
11 Disable Primary Vserver On Down : DISABLED

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1167

NetScaler 12.0

12 No. of Bound Services : 0 (Total) 0 (Active)

13 Configured Method: LEASTCONNECTION
14 Mode: IP
15 Persistence: NONE
16 Connection Failover: DISABLED
17 Done

Invoke a policy label from a virtual server policy bank with a NOPOLICY entry by using the CLI

At the command prompt, type the following commands to invoke a policy label from a virtual server
policy bank with a NOPOLICY entry and verify the configuration:

1 - bind lb|cs vserver <virtualServerName> -policyName NOPOLICY_REWRITE|

NOPOLICY_CACHE|NOPOLICY_RESPONDER -priority <integer> -type REQUEST|
RESPONSE -gotoPriorityExpression <gotopriorityExpression> -invoke
reqVserver|resVserver|policyLabel <vserverName>|<labelName>
2
3 - show lb vserver

Example:

1 > bind lb vserver vs-cont-sw -policyname NOPOLICY-REWRITE -priority 200

-type REQUEST -gotoPriorityExpression NEXT -invoke policyLabel lbl-
rewrt-pol
2 Done

Configure a virtual server policy bank by using the GUI

1. In the left navigation pane, expand ** **Traffic Management > Load Balancing, Traffic Man-
agement > Content Switching, Traffic Management > SSL Offload, Security > AAA - Applica-
tion Traffic, or NetScaler Gateway, as appropriate, and then click Virtual Servers.
2. In the details pane, select the virtual server that you want to configure, and then click Open.
3. In the Configure Virtual Server dialog box click the Policies tab.
4. To create a new policy in this bank, click the icon for the type of policy or policy label that you
want to add to the virtual server’s bank of policies, click Insert Policy. Note that if you want to
invoke a policy label without evaluating a policy rule, select the NOPOLICY “dummy” policy.
5. To configure an existing entry in this policy bank, enter the following:
• Priority:
A numeric value that determines either an absolute order of evaluation within the bank or
is used in conjunction with a Goto expression.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1168

NetScaler 12.0

• Expression:
The policy rule. Policy expressions are described in detail in the following chapters. For
an introduction, see
Configuring Advanced Policy Expressions: Getting Started.
• Action:
The action to be taken if this policy evaluates to TRUE.
• Goto Expression:
Optional. Determines the next policy or policy bank evaluate. For more information on
possible values for a Goto expression, see the section “Entries in a Policy Bank” in
Bind policies using advanced policy.
• Invoke:
Optional. To invoke another policy bank, select the name of the policy label or virtual
server policy bank that you want to invoke.
6. Click OK. A message in the status bar indicates that the policy is configured successfully.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Invoke or remove a policy label or virtual server policy bank

September 24, 2018

Contributed by:
C

Unlike a policy, which can only be bound once, you can use a policy label or a virtual server’s policy
bank any number of times by invoking it. Invocation can be performed from two places:

• From the binding for a named policy in a policy bank.

• From the binding for a NOPOLICY “dummy” entry in a policy bank.

Typically, the policy label must be of the same type as the policy from which it is invoked. For example,
you would invoke a responder policy label from a responder policy.

Note: When binding or unbinding a global NOPOLICY entry in a policy bank at the command line, you
specify a priority to distinguish one NOPOLICY entry from another.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1169

NetScaler 12.0

Invoke a rewrite or integrated caching policy label by using the CLI

At the command prompt, type the one of the following commands to invoke a rewrite or integrated
caching policy label and verify the configuration:

1 - bind cache global <policy> -priority <positive_integer> [-

gotoPriorityExpression <expression>] -type REQ_OVERRIDE|REQ_DEFAULT|
RES_OVERRIDE|RES_DEFAULT] -invoke reqvserver|resvserver|policylabel
<label_name>
2
3 - bind rewrite global<policy> -priority <positive_integer> [-
gotoPriorityExpression <expression>] -type REQ_OVERRIDE|REQ_DEFAULT|
RES_OVERRIDE|RES_DEFAULT] -invoke reqvserver|resvserver|policylabel
<label_name>
4
5 - show cache global|show rewrite global

Example:

1 > bind cache global _nonPostReq2 -priority 100 -type req_override -

invoke
2 policylabel lbl-cache-pol
3 Done
4 > show cache global
5 1) Global bindpoint: REQ_DEFAULT
6 Number of bound policies: 2
7
8 2) Global bindpoint: RES_DEFAULT
9 Number of bound policies: 1
10
11 3) Global bindpoint: REQ_OVERRIDE
12 Number of bound policies: 1
13
14 Done

Invoke a responder policy label by using the CLI

At the command prompt, type the following commands to invoke a responder policy label and verify
the configuration:

1 - bind responder global <policy_Name> <priority_as_positive_integer>

[<gotoPriorityExpression>] -type REQ_OVERRIDE|REQ_DEFAULT|OVERRIDE|
DEFAULT -invoke vserver|policylabel <label_name>
2

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1170

NetScaler 12.0

3 - show responder global

Example:

1 > bind responder global pol404Error1 300 -invoke policylabel lbl-

respndr-pol
2 Done
3 > show responder global
4 1) Global bindpoint: REQ_DEFAULT
5 Number of bound policies: 2
6
7 Done

Invoke a virtual server policy bank by using the CLI

At the command prompt, type the following commands to invoke a Virtual Server Policy Bank and
verify the configuration:

1 - bind lb vserver <vserver_name> -policyName <policy_Name> -priority <

positive_integer> [-gotoPriorityExpression <expression>] -type
REQUEST|RESPONSE -invoke reqvserver|resvserver|policylabel <
policy_Label_Name>
2
3 - bind lb vserver <vserver_name>

Example:

1 > bind lb vserver lbvip -policyName ns_cmp_msapp -priority 100

2 Done
3
4 > show lb vserver lbvip
5 lbvip (8.7.6.6:80) - HTTP Type: ADDRESS
6 State: DOWN
7 Last state change was at Wed Jul 15 05:54:24 2009 (+166 ms)
8 Time since last state change: 28 days, 06:37:49.250
9 Effective State: DOWN
10 Client Idle Timeout: 180 sec
11 Down state flush: ENABLED
12 Disable Primary Vserver On Down : DISABLED
13 Port Rewrite : DISABLED
14 No. of Bound Services : 0 (Total) 0 (Active)
15 Configured Method: LEASTCONNECTION
16 Mode: IP
17 Persistence: NONE

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1171

NetScaler 12.0

18 Vserver IP and Port insertion: OFF

19 Push: DISABLED Push VServer:
20 Push Multi Clients: NO
21 Push Label Rule: none
22
23 1) CSPolicy: pol-cont-sw CSVserver: vs-cont-sw Priority:
100 Hits: 0
24
25 2) Policy : pol-ssl Priority:0
26 3) Policy : ns_cmp_msapp Priority:100
27 4) Policy : cf-pol Priority:1 Inherited
28 Done

Remove a rewrite or integrated caching policy label by using the CLI

At the command prompt, type one of the following commands to remove a rewrite or integrated
caching policy label and verify the configuration:

1 - unbind rewrite global <policyName> -priority <positiveInteger> -type

REQ_OVERRIDE|REQ_DEFAULT|RES_OVERRIDE|RES_DEFAULT
2
3 - unbind cache global <policyName> -priority <positiveInteger> -type
REQ_OVERRIDE|REQ_DEFAULT|RES_OVERRIDE|RES_DEFAULT
4
5 - show rewrite global|show cache global

Example:

1 > unbind rewrite global NOPOLICY -priority 100 -type REQ_OVERRIDE

2 > show rewrite global
3 Done
4 1) Global bindpoint: REQ_DEFAULT
5 Number of bound policies: 1
6
7 Done

Remove a responder policy label by using the CLI

At the command prompt, type the following commands to remove a responder policy label and verify
the configuration:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1172

NetScaler 12.0

1 - unbind responder global <policyName> -priority <positiveInteger> -

type OVERRIDE|DEFAULT
2
3 - show responder global

Example:

1 > unbind responder global NOPOLICY -priority 100 -type REQ_DEFAULT

2 Done
3 > show responder global
4 1) Global bindpoint: REQ_DEFAULT
5 Number of bound policies: 1
6
7 Done

Remove a virtual server policy label by using the CLI

At the command prompt, type one of the following commands to remove a Virtual Server policy label
and verify the configuration:

1 - unbind lb vserver <virtualServerName> -policyName NOPOLICY-REWRITE|

NOPOLICY-RESPONDER|NOPOLICY-CACHE -type REQUEST|RESPONSE -priority <
positiveInteger>
2
3 - unbind cs vserver <virtualServerName> -policyName NOPOLICY-REWRITE|
NOPOLICY-RESPONDER|NOPOLICY-CACHE -type REQUEST|RESPONSE -priority <
positiveInteger>
4
5 - show lb vserver|show cs vserver

Example:

1 > unbind lb vserver lbvip -policyName ns_cmp_msapp -priority 200

2 Done
3 > show lb vserver lbvip
4 lbvip (8.7.6.6:80) - HTTP Type: ADDRESS
5 State: DOWN
6 Last state change was at Wed Jul 15 05:54:24 2009 (+161 ms)
7 Time since last state change: 28 days, 06:47:54.600
8 Effective State: DOWN
9 Client Idle Timeout: 180 sec
10 Down state flush: ENABLED
11 Disable Primary Vserver On Down : DISABLED
12 Port Rewrite : DISABLED

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1173

NetScaler 12.0

13 No. of Bound Services : 0 (Total) 0 (Active)

14 Configured Method: LEASTCONNECTION
15 Mode: IP
16 Persistence: NONE
17 Vserver IP and Port insertion: OFF
18 Push: DISABLED Push VServer:
19 Push Multi Clients: NO
20 Push Label Rule: none
21
22 1) CSPolicy: pol-cont-sw CSVserver: vs-cont-sw Priority:
100 Hits: 0
23
24 1) Policy : pol-ssl Priority:0
25 2) Policy : cf-pol Priority:1 Inherited
26 Done

Invoke a policy label or virtual server policy bank by using the GUI

1. Bind a policy, as described in Bind a policy globally, Bind a policy to a virtual server, or Bind a
policy to a policy label. Alternatively, you can enter a NOPOLICY “dummy” entry instead of a
policy name. You do this if you do not want to evaluate a policy before evaluating the policy
bank.
2. In the Invoke field, select the name of the policy label or virtual server policy bank that you want
to evaluate if traffic matches the bound policy. A message in the status bar indicates that the
policy label or virtual server policy bank is invoked successfully.

Remove a policy label invocation by using the GUI

1. Open the policy and clear the Invoke field. Unbinding the policy also removes the invocation of
the label. A message in the status bar indicates that the policy label is removed successfully.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configure and bind policies with the policy manager

September 24, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1174

NetScaler 12.0

Contributed by:
C
Warning:

Classic policy expressions are no longer supported from NetScaler 12.0 build 56.20 onwards and
as an alternative, Citrix recommends you to use Advanced policies. For more information, see
Advanced Policies.

Some applications provide a specialized Policy Manager in the NetScaler GUI to simplify configuring
policy banks. It also lets you find and delete policies and actions that are not being used.

The Policy Manager is currently available for the Rewrite, Integrated Caching, Responder, and Com-
pression features.

The following are keyboard equivalents for the procedures in this section:

• For editing a cell in the Policy Manager, you can tab to the cell and click F2 or press the SPACE
bar on the keyboard.
• To select an entry in a drop-down menu, you can tab to the entry, press the space bar to view the
drop-down menu, use the UP and DOWN ARROW keys to navigate to the entry that you want,
and press the space bar again to select the entry.
• To cancel a selection in a drop-down menu, press the Escape key.
• To insert a policy, tab to the row above the insertion point and press Control + Insert, or click
Insert Policy.
• To remove a policy, tab to the row that contains the policy and press Delete.

Note: Note that when you delete the policy, the NetScaler searches the Goto Expression values of
other policies in the bank. If any of these Goto Expression values match the priority level of the deleted
policy, they are removed.

Configure policy bindings by using the policy manager

1. In the navigation pane, click the feature for which you want to configure policies. The choices
are Responder, Integrated Caching, Rewrite or Compression.

2. In the details pane, click Policy Manager.

3. If you are configuring classic policy bindings for compression, in the Compression Policy Man-
ager dialog box, click Switch to Classic Syntax. The dialog box switches to the classic syntax
view and displays the Switch to Advanced Policy button. At any time before you complete con-
figuring policy bindings, if you want to configure bindings for policies that use the Advanced
Policy click the Switch to Advanced Policy button.

4. For features other than Responder, to specify the bind point, click Request or Response, and
then click one of the request-time or response-time bind points. The options are Override

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1175

NetScaler 12.0

Global, LB Virtual Server, CS Virtual Server, Default Global, or Policy Label. If you are configuring
the Responder, the Request and Response flow types are not available.

5. To bind a policy to this bind point, click Insert Policy, and select a previously configured policy,
a NOPOLICY label, or the New policy option. Depending on the option that you select, you have
the following choices:

• New policy: Create the policy as described in “Create or modify a policy,” and then con-
figure the priority level, GoTo expression, and policy invocation as described in the table,
“Format of each entry in a policy bank.”
• Existing policy, NOPOLICY, or NOPOLICY<feature name>: Configure the priority level,
GoTo expression, and policy invocation as described in the table, “Format of each entry in
a policy bank.” The NOPOLICY or NOPOLICY<feature name> options are available only
for policies that use Advanced Policies.

6. Repeat the preceding steps to add entries to this policy bank.

7. To modify the priority level for an entry, you can do any of the following:

• Double-click the Priority field for an entry and edit the value.
• Click and drag a policy to another row in the table.
• Click Regenerate Priorities.

In all three cases, priority levels of all other policies are modified as needed to accommodate the
new value. Goto Expressions with integer values are also updated automatically. For example,
if you change a priority value of 10 to 100, all policies with a Goto Expression value of 10 are
updated to the value 100.

8. To change the policy, action, or policy bank invocation for an row in the table, click the down
arrow to the right of the entry and do one of the following:

• To change the policy, select another policy name or select New Policy and follow the steps
in Create or modify a policy.
• To change the Goto Expression, select Next, End, USE_INVOCATION_RESULT, or select
more and enter an expression whose result returns the priority level of another entry in
this policy bank.
• To modify an invocation, select an existing policy bank, or click New Policy Label and fol-
low the steps in Bind a policy to a policy label.

9. To unbind a policy or a policy label invocation from this bank, click any field in the row that
contains the policy or policy label, and then click Unbind Policy.

10. When you are done, click Apply Changes. A message in the status bar indicates that the policy
is bound successfully.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1176

NetScaler 12.0

Remove unused policies by using the policy manager

1. In the navigation pane, click the feature for which you want to configure the policy bank. The
choices are Responder, Integrated Caching, or Rewrite.
2. In the details pane, click <Feature Name> policy manager.
3. In the <Feature Name> Policy Manager dialog box, click Cleanup Configuration.
4. In the Cleanup Configuration dialog box, select the items that you want to delete, and then
click Remove.
5. In the Remove dialog box, click Yes.
6. Click Close. A message in the status bar indicates that the policy is removed successfully.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring advanced policy expression: getting started

September 24, 2018

Contributed by:
C

Advanced policies evaluate data on the basis of information that you supply in Advanced policy expres-
sions. An Advanced policy expression analyzes data elements (for example, HTTP headers, source
IP addresses, the NetScaler system time, and POST body data). In addition to configuring an Ad-
vanced policy expression in a policy, in some NetScaler features, you configure Advanced policy ex-
pression outside of the context of a policy.

To create an Advanced policy expression, you select a prefix that identifies a piece of data that you
want to analyze, and then you specify an operation to perform on the data. For example, an opera-
tion can match a piece of data with a text string that you specify, or it can transform a text string into
an HTTP header. Other operations match a returned string with a set of strings or a string pattern.
You configure compound expressions by specifying Boolean and arithmetic operators, and by using
parentheses to control the order of evaluation.

Advanced policy expression can also contain classic expressions. You can assign a name to a fre-
quently used expression to avoid having to build the expression repeatedly.

Policies and a few other entities include rules that the NetScaler uses to evaluate a packet in the traffic
flowing through it, to extract data from the NetScaler system itself, to send a request (a “callout”) to an

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1177

NetScaler 12.0

external application, or to analyze another piece of data. A rule takes the form of a logical expression
that is compared against traffic and ultimately returns values of TRUE or FALSE.

The elements of the rule can themselves return TRUE or FALSE, string, or numeric values.

Before configuring an Advanced policy expression, you need to understand the characteristics of the
data that the policy or other entity is to evaluate. For example, when working with the Integrated
Caching feature, a policy determines what data can be stored in the cache. With Integrated Caching,
you need to know the URLs, headers, and other data in the HTTP requests and responses that the
NetScaler receives. With this knowledge, you can configure policies that match the actual data and
enable the NetScaler to manage caching for HTTP traffic. This information helps you determine the
type of expression that you need to configure in the policy.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Basic elements of an advanced policy expression

November 5, 2018

Contributed by:
C

An Advanced policy expression consists of, at a minimum, a prefix (or a single element used in place
of a prefix). Most expressions also specify an operation to be performed on the data that the prefix
identifies. You format an expression of up to 1,499 characters as follows:

<prefix>.<operation> [<compound-operator> <prefix>.<operation>. . .]

where

• <prefix>

is an anchor point for starting an expression.

The prefix is a period-delimited key that identifies a unit of data. For example, the following
prefix examines HTTP requests for the presence of a header named Content-Type:

http.req.header(“Content-Type”)

Prefixes can also be used on their own to return the value of the object that the prefix identifies.

• <operation>

identifies an evaluation that is to be performed on the data identified by the prefix.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1178

NetScaler 12.0

For example, consider the following expression:

http.req.header(“Content-Type”).eq(“text/html”)

In this expression, the following is the operator component:

eq(“text/html”)

This operator causes the NetScaler to evaluate any HTTP requests that contain a Content-Type
header, and in particular, to determine if the value of this header is equal to the string “tex-
t/html.” For more information, see Operations.

• <compound-operator>

is a Boolean or arithmetic operator that forms a compound expression from multiple prefix or
prefix.operation elements.

For example, consider the following expression:

http.req.header(“Content-Type”).eq(“text/html”) && http.req.url.contains(“.html”)

Prefixes

An expression prefix represents a discrete piece of data. For example, an expression prefix can rep-
resent an HTTP URL, an HTTP Cookie header, or a string in the body of an HTTP POST request. An
expression prefix can identify and return a wide variety of data types, including the following:

• A client IP address in a TCP/IP packet

• NetScaler system time
• An external callout over HTTP
• A TCP or UDP record type

In most cases, an expression prefix begins with one of the following keywords:

• CLIENT:

– Identifies a characteristic of the client that is either sending a request or receiving a re-
sponse, as in the following examples:
– The prefix client.ip.dst designates the destination IP address in the request or response.
– The prefix client.ip.src designates the source IP address.

• HTTP:

– Identifies an element in an HTTP request or a response, as in the following examples:

– The prefix http.req.body(integer) designates the body of the HTTP request as a multiline
text object, up to the character position designated in integer.
– The prefix http.req.header(“header_name”) designates an HTTP header, as specified in
header_name.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1179

NetScaler 12.0

– The prefix http.req.url designates an HTTP URL in URL-encoded format.

• SERVER:

Identifies an element in the server that is either processing a request or sending a response.

• SYS:

Identifies a characteristic of the NetScaler that is processing the traffic.

Note: Note that DNS policies support only SYS, CLIENT, and SERVER objects.

In addition, in the NetScaler Gateway, the Clientless VPN function can use the following types
of prefixes:

• TEXT:

Identifies any text element in a request or a response.

• TARGET:

Identifies the target of a connection.

• URL:

Identifies an element in the URL portion of an HTTP request or response.

As a general rule of thumb, any expression prefix can be a self-contained expression. For example, the
following prefix is a complete expression that returns the contents of the HTTP header specified in the
string argument (enclosed in quotation marks):

http.res.header.(”myheader”)

Or you can combine prefixes with simple operations to determine TRUE and FALSE values. For exam-
ple, the following returns a value of TRUE or FALSE:

http.res.header.(”myheader”).exists

You can also use complex operations on individual prefixes and multiple prefixes within an expression,
as in the following example:

http.req.url.length + http.req.cookie.length <= 500

Which expression prefixes you can specify depends on the NetScaler feature. The following table de-
scribes the expression prefixes that are of interest on a per-feature basis

Feature Types of Expression Prefix Used in the Feature

DNS SYS, CLIENT, SERVER

Responder in Protection Features HTTP, SYS, CLIENT
Content Switching HTTP, SYS, CLIENT

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1180

NetScaler 12.0

Feature Types of Expression Prefix Used in the Feature

Rewrite HTTP, SYS, CLIENT, SERVER, URL, TEXT,

TARGET, VPN
Integrated Caching HTTP, SYS, CLIENT, SERVER
NetScaler Gateway, Clientless Access HTTP, SYS, CLIENT, SERVER, URL, TEXT,
TARGET, VPN

Table 1. Permitted Types of Expression Prefixes in Various NetScaler Features

Note: For details on the permitted expression prefixes in a feature, see the documentation for that
feature.

Single-element expressions

The simplest type of Advanced policy expression contains a single element. This element can be one
of the following:

• true. An Advanced policy expression can consist simply of the value true. This type of expres-
sion always returns a value of TRUE. It is useful for chaining policy actions and triggering Goto
expressions.
• false. An Advanced policy expression can consist simply of the value false. This type of expres-
sion always returns a value of FALSE.
• A prefix for a compound expression. For example, the prefix HTTP.REQ.HOSTNAME is a complete
expression that returns a host name and HTTP.REQ.URL is a complete expression that returns
a URL. The prefix could also be used in conjunction with operations and additional prefixes to
form a compound expression.

Operations

In most expressions, you also specify an operation on the data that the prefix identifies. For example,
suppose that you specify the following prefix:

http.req.url

This prefix extracts URLs in HTTP requests. This expression prefix does not require any operators to
be used in an expression. However, when you configure an expression that processes HTTP request
URLs, you can specify operations that analyze particular characteristics of the URL. Following are a
few possibilities:

• Search for a particular host name in the URL.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1181

NetScaler 12.0

• Search for a particular path in the URL.

• Evaluate the length of the URL.
• Search for a string in the URL that indicates a time stamp and convert it to GMT.

The following is an example of a prefix that identifies an HTTP header named Server and an operation
that searches for the string IIS in the header value:

http.res.header(”Server”).contains(”IIS”)

Following is an example of a prefix that identifies host names and an operation that searches for the
string “www.mycompany.com” as the value of the name:

http.req.hostname.eq(”www.mycompany.com”)

Basic operations on expression prefixes

The following table describes a few of the basic operations that can be performed on expression pre-
fixes.

Operation Determines Whether or Not

CONTAINS(<string>) The object matches <string>. Following is an

example: http.req.header(“Cache-
Control”).contains(“no-cache”)
EXISTS A particular item is present in an object.
Following is an
example: http.res.header(“MyHdr”).exists
EQ(<text>) A particular non-numeric value is present in an
object. Following is an
example: http.req.method.eq(post)
EQ(<integer>) A particular numeric value is present in an
object. Following is an
example: client.ip.dst.eq(10.100.10.100)
LT(<integer>) An object’s value is less than a particular value.
Following is an
example: http.req.content_length.lt(5000)
GT(<integer>) An object’s value is greater than a particular
value. Following is an
example: http.req.content_length.gt(5)

The following table summarizes a few of the available types of operations.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1182

NetScaler 12.0

Operation Type Description

Text operations Match individual strings and sets of strings

with any portion of a target. The target can be
an entire string, the start of a string, or any
portion of text in between the start and the end
of the string. For example, you can extract the
string “XYZ” from “XYZSomeText”. Or, you can
compare an HTTP header value with an array
of different strings. You can also transform text
into another type of data. Following are
examples: Transform a string into an integer
value, create a list from the query strings in a
URL, and transform a string into a time value.
Numeric operations Numeric operations include applying
arithmetic operators, evaluating content
length, the number of items in a list, dates,
times, and IP addresses.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Compound advanced policy expressions

September 24, 2018

Contributed by:
C

You can configure an Advanced policy expression that contains Boolean or arithmetic operators and
multiple atomic operations. The following compound expression contains a boolean AND:

http.req.hostname.eq(”mycompany.com”)&& http.req.method.eq(post)

The following expression adds the value of two targets, and compares the result to a third value:

http.req.url.length + http.req.cookie.length \<= 500

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1183

NetScaler 12.0

A compound expression can contain any number of logical and arithmetic operators. The following
expression evaluates the length of an HTTP request on the basis of its URL and cookie, evaluates text
in the header, and performs a Boolean AND on these two results:

http.req.url.length + http.req.cookie.length \<= 500 && http.req.header.

contains(”some text”)

You can use parentheses to control the order of evaluation in a compound expression.

Booleans in compound expressions

You configure compound expressions with the following operators:

• &&.

This operator is a logical AND. For the expression to evaluate to TRUE, all components that are
joined by the And must evaluate to TRUE. Following is an example:

http.req.url.hostname.eq(“myHost”) && http.req.header(“myHeader”).exists

• This operator is a logical OR. If any component of the expression that is joined by the OR evalu-
ates to TRUE, the entire expression is TRUE.

• !.

Performs a logical NOT on the expression.

In some cases, the NetScaler , and ! to configure

GUI offers AND, NOT, and OR compound expressions that
operators in the Add use Boolean logic.
Expression dialog box.
However, these are of limited
use. Citrix recommends that
you use the operators &&,

Parentheses in compound expressions

You can use parentheses to control the order of evaluation of an expression. The following is an ex-
ample:

http.req.url.contains(”myCompany.com”)|| (http.req.url.hostname.eq(”myHost”

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1184

NetScaler 12.0

)&& http.req.header(”myHeader”).exists)

The following is another example:

(http.req.header(”Content-Type”).exists && http.req.header(”Content-Type”).

eq(”text/html”))|| (http.req.header(”Transfer-Encoding”).exists || http.req
.header(”Content-Length”).exists)

Compound operations for strings

The following table describes operators that you can use to configure compound operations on string
data.

Operations that produce a string value Description

str + str Concatenates the value of the expression on

the left of the operator with the value on the
right. Following is an
example: http.req.hostname +
http.req.url.protocol
str + num Concatenates the value of the expression on
the left of the operator with a numeric value on
the right. Following is an
example: http.req.hostname +
http.req.url.content_length
num + str Concatenates the numeric value of the
expression on the left side of the operator with
a string value on the right. Following is an
example: http.req.url.content_length +
http.req.url.hostname
str + ip Concatenates the string value of the expression
on the left side of the operator with an IP
address value on the right. Following is an
example: http.req.hostname + 10.00.000.00
ip + str Concatenates the IP address value of the
expression on the left of the operator with a
string value on the right.Following is an
example: client.ip.dst + http.req.url.hostname

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1185

NetScaler 12.0

Operations that produce a string value Description

str1 ALT str2 Uses the string1 or string2 value that is derived
from the expression on either side of the
operator, as long as neither of these
expressions is a compound expressions.
Following is an example: http.req.hostname alt
client.ip.src

Operations on strings that produce a result of

TRUE or FALSE Description

str == str Evaluates whether the strings on either side of

the operator are the same. Following is an
example: http.req.header(“myheader”) ==
http.res.header(“myheader”)
str <= str Evaluates whether the string on the left side of
the operator is the same as the string on the
right, or precedes it alphabetically.
str >= str Evaluates whether the string on the left side of
the operator is the same as the string on the
right, or follows it alphabetically.
str < str Evaluates whether the string on the left side of
the operator precedes the string on the right
alphabetically.
str > str Evaluates whether the string on the left side of
the operator follows the string on the right
alphabetically.
str !!= str Evaluates whether the strings on either side of
the operator are different.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1186

NetScaler 12.0

Logical operations on
strings Description

bool && bool This operator is a

logical AND. When
evaluating the
components of the
compound
expression, all
components that are
joined by the AND
must evaluate to
TRUE. Following is an
exam-
ple: http.req.method.eq(GET)
&&
http.req.url.query.contains(“viewReport
&& my_pagelabel”)
bool || bool This operator is a http.res.header.(“Content-
logical OR. When Type”).contains(“javascript”)
evaluating the
components of the
compound
expression, if any
component of the
expression that is
joined by the OR
evaluates to TRUE,
the entire expression
is TRUE. Following is
an exam-
ple: http.req.url.contains(“.js”)
bool Performs a logical
NOT on the
expression.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1187

NetScaler 12.0

Compound operations for numbers

You can configure compound numeric expressions. For example, the following expression returns a
numeric value that is the sum of an HTTP header length and a URL length:

http.req.header.length + http.req.url.length

The following tables describes operators that you can use to configure compound expressions for nu-
meric data.

Arithmetic operations
on numbers Description

num + num Add the value of the

expression on the left
of the operator to the
value of the
expression on the
right. Following is an
exam-
ple: http.req.content_length
+ http.req.url.length
num – num Subtract the value of
the expression on the
right of the operator
from the value of the
expression on the left.
num * num Multiply the value of
the expression on the
left of the operator
with the value of the
expression on the
right. Following is an
exam-
ple: client.interface.rxthroughput
*9
num / num Divide the value of
the expression on the
left of the operator by
the value of the
expression on the
right.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1188

NetScaler 12.0

Arithmetic operations
on numbers Description

num % num Calculate the

modulo, or the
numeric remainder
on a division of the
value of the
expression on the left
of the operator by the
value of the
expression on the
right. For example,
the values “15 mod 4”
equals 3, and “12 mod
4” equals 0.
~number Returns a number
after applying a
bitwise logical
negation of the
number. The
following example
assumes that
numeric.expression
returns 12 (binary
1100): ~numeric.expression. The
result of applying the
~ operator is -11 (a
binary 1110011, 32 bits
total with all ones to
the left). Note that all
returned values of
less than 32 bits
before applying the
operator implicitly
have zeros to the left
to make them 32 bits
wide.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1189

NetScaler 12.0

Arithmetic operations
on numbers Description

number ˆ number Compares two bit

patterns of equal
length and performs
an XOR operation on
each pair of
corresponding bits in
each number
argument, returning 1
if the bits are
different, and 0 if they
are the same. Returns
a number after
applying a bitwise
XOR to the integer
argument and the
current number
value. If the values in
the bitwise
comparison are the
same, the returned
value is a 0. The
following example
assumes that
numeric.expression1
returns 12 (binary
1100) and
numeric.expression2
returns 10 (binary
1010): nu-
meric.expression1 ˆ
nu-
meric.expression2The
result of applying the
ˆ operator to the
entire expression is 6
(binary 0110). Note
that all returned
values of less than 32
bits before applying
© 1999-2018 Citrix Systems,the
Inc.operator
All rights reserved. 1190
implicitly have zeros
to the left to make
them 32 bits wide.
NetScaler 12.0

Arithmetic operations
on numbers Description

number | number Returns a number numeric.expression2Theoperator to the entire

after applying a result of applying the expression is 14
bitwise OR to the (binary 1110). Note
number values. If that all returned
either value in the values of less than 32
bitwise comparison is bits before applying
a 1, the returned the operator
value is a 1. The implicitly have zeros
following example to the left to make
assumes that them 32 bits wide.
numeric.expression1
returns 12 (binary
1100) and
numeric.expression2
returns 10 (binary
1010): nu-
meric.expression1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1191

NetScaler 12.0

Arithmetic operations
on numbers Description

number & number Compares two bit

patterns of equal
length and performs
a bitwise AND
operation on each
pair of corresponding
bits, returning 1 if
both of the bits
contains a value of 1,
and 0 if either bits are
0. The following
example assumes
that
numeric.expression1
returns 12 (binary
1100) and
numeric.expression2
returns 10 (binary
1010): nu-
meric.expression1 &
nu-
meric.expression2 The
whole expression
evaluates to 8 (binary
1000). Note that all
returned values of
less than 32 bits
before applying the
operator implicitly
have zeros to the left
to make them 32 bits
wide.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1192

NetScaler 12.0

Arithmetic operations
on numbers Description

num « num Returns a number

after a bitwise left
shift of the number
value by the right-side
number argument
number of bits. Note
that the number of
bits shifted is integer
modulo 32. The
following example
assumes that
numeric.expression1
returns 12 (binary
1100) and
numeric.expression2
returns 3: nu-
meric.expression1
« nu-
meric.expression2 The
result of applying the
LSHIFT operator is 96
(a binary
1100000).Note that all
returned values of
less than 32 bits
before applying the
operator implicitly
have zeros to the left
to make them 32 bits
wide.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1193

NetScaler 12.0

Arithmetic operations
on numbers Description

num » num Returns a number

after a bitwise right
shift of the number
value by the integer
argument number of
bits. Note that the
number of bits shifted
is integer modulo 32.
The following
example assumes
that
numeric.expression1
returns 12 (binary
1100) and
numeric.expression2
returns 3: nu-
meric.expression1 »
nu-
meric.expression2 The
result of applying the
RSHIFT operator is 1
(a binary 0001). Note
that all returned
values of less than 32
bits before applying
the operator
implicitly have zeros
to the left to make
them 32 bits wide.

Numeric operators that produce a result of

TRUE or FALSE Description

num == num Determine if the value of the expression on the

left of the operator is equal to the value of the
expression on the right.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1194

NetScaler 12.0

Numeric operators that produce a result of

TRUE or FALSE Description

num != num Determine if the value of the expression on the

left of the operator is not equal to the value of
the expression on the right.
num > num Determine if the value of the expression on the
left of the operator is greater than the value of
the expression on the right.
num < num Determine if the value of the expression on the
left of the operator is less than the value of the
expression on the right.
num >= num Determine if the value of the expression on the
left of the operator is greater than or equal to
the value of the expression on the right.
num <= num Determine if the value of the expression on the
left of the operator is less than or equal to the
value of the expression on the right

Functions for data types in the policy infrastructure

The NetScaler policy infrastructure supports the following numeric data types:

• Integer (32 bits)

• Unsigned long (64 bits)
• Double (64 bits)

Simple expressions can return all of these data types. Therefore, you can create compound expres-
sions that use arithmetic operators and logical operators to evaluate or return values of these data
types. Additionally, you can use all of these values in policy expressions. Literal constants of type
unsigned long can be specified by appending the string ul to the number. Literal constants of type
double contain a period (.), an exponent, or both.

Arithmetic Operators, Logical Operators, and Type Promotion

In compound expressions, the following standard arithmetic and logical operators can be used for the
double and unsigned long data types:

• +, -, *, and /

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1195

NetScaler 12.0

%, ~, ˆ, &, , <<, and >> (do not apply to double)

•
• ==, !=, >, <, >=, and <=
All of these operators have the same meaning as in the C programming language.
In all cases of mixed operations between operands of type integer, unsigned long, and double, type
promotion is performed so that the operation can be performed on operands of the same type. A
type of lower precedence is automatically promoted to the type of the operand with the highest prece-
dence involved in the operation. The order of precedence (higher to lower) is as follows:
• Double
• Unsigned long
• Integer
Therefore, an operation that returns a numeric result returns a result of the highest type involved in
the operation.
For example, if the operands are of type integer and unsigned long, the integer operand is
automatically converted to type unsigned long. This type conversion is performed even in
simple expressions in which the type of data identified by the expression prefix does not
match the type of data that is passed as the argument to the function. To illustrate such
an example, in the operation HTTP.REQ.CONTENT_LENGTH.DIV(3ul), the integer returned
by the prefix HTTP.REQ.CONTENT_LENGTH is automatically converted to unsigned long (the
type of the data passed as the argument to the DIV() function), and an unsigned long divi-
sion is performed. Similarly, the argument can be promoted in an expression. For example,
HTTP.REQ.HEADER(“myHeader”).TYPECAST_DOUBLE_AT.DIV(5) promotes the integer 5 to type
double and performs double-precision division.
For information about expressions for casting data of one type to data of another type, see Typecasting
data.
1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Specify the character set in expressions

September 24, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1196

NetScaler 12.0

Contributed by:
C
The policy infrastructure on the Citrix® NetScaler® appliance supports the ASCII and UTF-8 character
sets. The default character set is ASCII. If the traffic for which you are configuring an expression con-
sists of only ASCII characters, you need not specify the character set in the expression. However, you
must specify the character set in every simple expression that is meant for UTF-8 traffic. To specify the
UTF-8 character set in a simple expression, you must include the SET_CHAR_SET(<charset>) function,
with <charset> specified as UTF_8, as shown in the following examples:

1 HTTP.REQ.BODY(10).SET_CHAR_SET(UTF_8).CONTAINS(”ß”)
2
3 HTTP.RES.BODY(100).SET_CHAR_SET(UTF_8).BEFORE_STR(”Bücher”).AFTER_STR(”
Wörterbuch”)

In an expression, the SET_CHAR_SET() function must be introduced at the point in the expression
after which data processing must be carried out in the specified character set. For example, in the
expression HTTP.REQ.BODY(1000).AFTER_REGEX(re/following example/).BEFORE_REGEX(re/In the
preceding example/).CONTAINS_ANY(“Greek_ alphabet”), if the strings stored in the pattern set
“Greek_alphabet” are in UTF-8, you must include the SET_CHAR_SET(UTF_8) function immediately
before the CONTAINS_ANY(“<string>”) function, as follows:
HTTP.REQ.BODY(1000).AFTER_REGEX(re/following example/).BEFORE_REGEX(re/In
the preceding example/).SET_CHAR_SET(UTF_8).CONTAINS_ANY(”Greek_ alphabet”)

The SET_CHAR_SET() function sets the character set for all further processing (that is, for all
subsequent functions) in the expression unless it is overridden later in the expression by another
SET_CHAR_SET() function that changes the character set. Therefore, if all the functions in a given
simple expression are intended for UTF-8, you can include the SET_CHAR_SET(UTF_8) function
immediately after functions that identify text (for example, the HEADER(“<name>”) or BODY(<int>)
functions). In the second example that follows the first paragraph above, if the ASCII arguments
passed to the AFTER_REGEX() and BEFORE_REGEX() functions are changed to UTF-8 strings, you can
include the SET_CHAR_SET(UTF_8) function immediately after the BODY(1000) function, as follows:
HTTP.REQ.BODY(1000).SET_CHAR_SET(UTF_8).AFTER_REGEX(re/Bücher/).BEFORE_REGEX
(re/Wörterbuch/).CONTAINS_ANY(”Greek_alphabet”)

The UTF-8 character set is a superset of the ASCII character set, so expressions configured for the ASCII
character set continue to work as expected if you change the character set to UTF-8.

Compound expressions with different character sets

In a compound expression, if one subset of expressions is configured to work with data in the ASCII
character set and the rest of the expressions are configured to work with data in the UTF-8 character

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1197

NetScaler 12.0

set, the character set specified for each individual expression is considered when the expressions are
evaluated individually. However, when processing the compound expression, just before processing
the operators, the appliance promotes the character set of the returned ASCII values to UTF-8. For
example, in the following compound expression, the first simple expression evaluates data in the ASCII
character set while the second simple expression evaluates data in the UTF-8 character set:

HTTP.REQ.HEADER(”MyHeader”)== HTTP.REQ.BODY(10).SET_CHAR_SET(UTF_8)

However, when processing the compound expression, just before evaluating the “is equal to”
Boolean operator, the NetScaler appliance promotes the character set of the value returned by
HTTP.REQ.HEADER(“MyHeader”) to UTF-8.

The first simple expression in the following example evaluates data in the ASCII character set. How-
ever, when the NetScaler appliance processes the compound expression, just before concatenating
the results of the two simple expressions, the appliance promotes the character set of the value re-
turned by HTTP.REQ.BODY(10) to UTF-8.

HTTP.REQ.BODY(10)+ HTTP.REQ.HEADER(”MyHeader”).SET_CHAR_SET(UTF_8)

Consequently, the compound expression returns data in the UTF-8 character set.

Specify the character set based on the character set of traffic

You can set the character set to UTF-8 on the basis of traffic characteristics. If you are not sure whether
the character set of the traffic being evaluated is UTF-8, you can configure a compound expression in
which the first expression checks for UTF-8 traffic and subsequent expressions set the character set
to UTF-8. Following is an example of a compound expression that first checks the value of “charset”
in the request’s Content-Type header for “UTF-8” before checking whether the first 1000 bytes in the
request contain the UTF-8 string Bücher:

HTTP.REQ.HEADER(”Content-Type”).SET_TEXT_MODE(IGNORECASE).TYPECAST_NVLIST_T
(’=’, ’; ’, ’”’).VALUE(”charset”).EQ(”UTF-8”)&& HTTP.REQ.BODY(1000).SET_CHAR_SET
(UTF_8).CONTAINS(”Bücher”)

If you are sure that the character set of the traffic being evaluated is UTF-8, the second expression in
the example is sufficient.

Character and string literals in expressions

During expression evaluation, even if the current character set is ASCII, character literals and string
literals, which are enclosed in single quotation marks (‘’) and quotation marks (“”), respectively, are
considered to be literals in the UTF-8 character set. In a given expression, if a function is operating
on character or string literals in the ASCII character set and you include a non-ASCII character in the
literal, an error is returned.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1198

NetScaler 12.0

Values in hexadecimal and octal formats

When configuring an expression, you can enter values in octal and hexadecimal formats. However,
each hexadecimal or octal byte is considered a UTF-8 byte. Invalid UTF-8 bytes result in errors regard-
less of whether the value is entered manually or pasted from the clipboard. For example, “\xce\x20” is
an invalid UTF-8 character because “c8” cannot be followed by “20” (each byte in a multi-byte UTF-8
string must have the high bit set). Another example of an invalid UTF-8 character is “\xce \xa9,” since
the hexadecimal characters are separated by a white-space character.

Functions that return UTF-8 strings

Only the
<text>.XPATH and
<text>.XPATH_JSON functions always return UTF-8 strings. The following MYSQL routines determine
at runtime which character set to return, depending on the data in the protocol:
• MYSQL_CLIENT_T.USER
• MYSQL_CLIENT_T.DATABASE
• MYSQL_REQ_QUERY_T.COMMAND
• MYSQL_REQ_QUERY_T.TEXT
• MYSQL_REQ_QUERY_T.TEXT(<unsigned int>)
• MYSQL_RES_ERROR_T.SQLSTATE
• MYSQL_RES_ERROR_T.MESSAGE
• MYSQL_RES_FIELD_T.CATALOG
• MYSQL_RES_FIELD_T.DB
• MYSQL_RES_FIELD_T.TABLE
• MYSQL_RES_FIELD_T.ORIGINAL_TABLE
• MYSQL_RES_FIELD_T.NAME
• MYSQL_RES_FIELD_T.ORIGINAL_NAME
• MYSQL_RES_OK_T.MESSAGE
• MYSQL_RES_ROW_T.TEXT_ELEM(<unsigned int>)

Terminal connection settings for UTF-8

When you set up a connection to the NetScaler appliance by using a terminal connection (by using
PuTTY, for example), you must set the character set for transmission of data to UTF-8.
1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1199

NetScaler 12.0

Classic expressions in advanced policy expressions

September 24, 2018

Contributed by:
C
Warning

Classic policy expressions are no longer supported from NetScaler 12.0 build 56.20 onwards and
as an alternative, Citrix recommends you to use Advanced policies. For more information, see
Configure advanced policy expressions: Get started.

Classic expressions describe basic characteristics of traffic. In some cases, you may want to use a clas-
sic expression in an Advanced policy expression are no longer supported from NetScaler 12.0 build
56.20 onwards and as an alternative, Citrix recommends you to use Advanced policies. For more in-
formation, see Advanced Policies topic. You can do so with the Advanced policy expression configura-
tion tool. This can be helpful when manually migrating the older classic expressions to the Advanced
policy.

Note that when you upgrade the NetScaler to version 9.0 or higher, Integrated Caching policies are
automatically upgraded to Advanced policies, and the expressions in these policies are upgraded to
the Advanced policies.

The following is the syntax for all Advanced policy expressions that use a classic expression:

SYS.EVAL_CLASSIC_EXPR(“expression”)

Note

The syntax and the metadata for the SYS.EVAL_CLASSIC_EXPR expression is getting deprecated.
You can manually convert or use nspepi tool to convert the Classic expression to advanced ex-
pression.

Following are examples of the SYS.EVAL_CLASSIC_EXPR(“expression”) expression:

1 sys.eval_classic_expr(”req.ssl.client.cipher.bits > 1000”)

2 sys.eval_classic_expr(”url contains abc”)
3 sys.eval_classic_expr(”req.ip.sourceip == 10.102.1.61 -netmask
255.255.255.255”)
4 sys.eval_classic_expr(”time >= *:30:00GMT”)
5 sys.eval_classic_expr(”e1 || e2”)
6 sys.eval_classic_expr(”req.http.urllen > 50”)
7 sys.eval_classic_expr(”dayofweek == wedGMT”)

1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1200

NetScaler 12.0

2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configure advanced policy expressions in a policy

September 24, 2018

Contributed by:
C

You can configure an Advanced policy expression of up to 1,499 characters in a policy. The user inter-
face for Advanced policy expressions depends to some extent on the feature for which you are con-
figuring the expression, and on whether you are configuring an expression for a policy or for another
use.

When configuring expressions on the command line, you delimit the expression by using quotation
marks (“. . .” or ‘. . .’). Within an expression, you escape additional quotation marks by using a
back-slash (). For example, the following are standard methods for escaping quotation marks in an
expression:

”\”abc\””

‘ \”abc\”’

You must also use a backslash to escape question marks and other backslashes on the command
line. For example, the expression http.req.url.contains(“\?”) requires a backslash so that the question
mark is parsed. Note that the backslash character will not appear on the command line after you
type the question mark. On the other hand, if you escape a backslash (for example, in the expression
‘http.req.url.contains(“\\http”)’), the escape characters are echoed on the command line.

To make an entry more readable, you can ~$ˆ+=&%@‘?.

escape the quotation marks for an entire
expression. At the start of the expression you
enter the escape sequence “q” plus one of the
following special characters: /{<

You enter only the special character at the end of the expression, as follows:

1 [email protected](”sometext”) && http.req.cookie.exists@

2
3 q~http.req.url.contains(”sometext”) && http.req.cookie.exists~

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1201

NetScaler 12.0

Note that an expression that uses the { delimiter is closed with }.

For some features (for example, Integrated Caching and Responder), the policy configuration dialog
box provides a secondary dialog box for configuring expressions. This dialog enables you to choose
from drop-down lists that show the available choices at each point during expression configuration.
You cannot use arithmetic operators when using these configuration dialogs, but most other advanced
policy expression features are available. To use arithmetic operators , write your expressions in free-
form format.

Configure an Advanced policy syntax rule by using the CLI

Note:

Default syntax policy is now renamed as Advanced policy.

At the command prompt, type the following commands to configure a default syntax rule and verify
the configuration:

1. add cache|dns|rewrite|cs policy policyName **-rule** expression featureSpecificPa

**-action**

2. show cache|dns|rewrite|cs policy policyName

Following is an example of configuring a caching policy:

Example:

1 > add cache policy pol-cache -rule http.req.content_length.le(5) -

action INVAL
2 Done
3
4 > show cache policy pol-cache
5 Name: pol-cache
6 Rule: http.req.content_length.le(5)
7 CacheAction: INVAL
8 Invalidate groups: DEFAULT
9 UndefAction: Use Global
10 Hits: 0
11 Undef Hits: 0
12
13 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1202

NetScaler 12.0

Configure a default syntax policy expression by using the GUI

1. In the navigation pane, click the name of the feature where you want to configure a policy, for
example, you can select Integrated Caching, Responder, DNS, Rewrite, or Content Switching,
and then click Policies.

2. Click Add.

3. For most features, click in the Expression field. For content switching, click Configure.

4. Click the Prefix icon (the house) and select the first expression prefix from the drop-down list.
For example, in Responder, the options are HTTP, SYS, and CLIENT. The next set of applicable
options appear in a drop-down list.

5. Double-click the next option to select it, and then type a period (.). Again, a set of applicable
options appears in another drop-down list.

6. Continue selecting options until an entry field (signalled by parentheses) appears. When you
see an entry field, enter an appropriate value in the parentheses. For example, if you select
GT(int) (greater-than, integer format), you specify an integer in the parentheses. Text strings
are delimited by quotation marks. Following is an example:

HTTP.REQ.BODY(1000).BETWEEN(”this”,”that”)

To insert an operator between ):

two parts of a compound
expression, click the
Operators icon (the sigma),
and select the operator type.
Following is an example of a
configured expression with a
Boolean OR (signalled by
double vertical bars,

7. HTTP.REQ.URL.EQ(”www.mycompany.com”)||HTTP.REQ.BODY(1000).BETWEEN(”this
”,”that”)

8. To insert a named expression, click the down arrow next to the Add icon (the plus sign) and
select a named expression.

9. To configure an expression using drop-down menus, and to insert built-in expressions, click the
Add icon (the plus sign). The Add Expression dialog box works in a similar way to the main dia-
log box, but it provides drop-down lists for selecting options, and it provides text fields for data
entry instead of parentheses. This dialog box also provides a Frequently Used Expressions drop-

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1203

NetScaler 12.0

down list that inserts commonly used expressions. When you are done adding the expression,
click OK.

10. When finished, click Create. A message in the status bar indicates that the policy expression is
configured successfully.

Test a default syntax expression by using the GUI

1. In the navigation pane, click the name of the feature for which you want to configure a policy (for
example, you can select Integrated Caching, Responder, DNS, Rewrite, or Content Switching),
and then click Policies.
2. Select a policy and click Open.
3. To test the expression, click the Evaluate icon (the check mark).
4. In the expression evaluator dialog box, select the Flow Type that matches the expression.
5. In the HTTP Request Data or HTTP Response Data field, paste the HTTP request or response
that you want to parse with the expression, and click Evaluate. Note that you must supply a
complete HTTP request or response, and the header and body should be separated by blank
line. Some programs that trap HTTP headers do not also trap the response. If you are copying
and pasting only the header, insert a blank line at the end of the header to form a complete
HTTP request or response.
6. Click Close to close this dialog box.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configure named advanced policy expressions

September 24, 2018

Contributed by:
C

Instead of retyping the same expression multiple times in multiple policies, you can configure a named
expression and refer to the name any time you want to use the expression in a policy. For example,
you could create the following named expressions:

• ThisExpression:

http.req.body(100).contains(”this”)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1204

NetScaler 12.0

• ThatExpression:

http.req.body(100).contains(”that”)

You can then use these named expressions in a policy expression. For example, the following is a legal
expression based on the preceding examples:

ThisExpression ThatExpression

You can use the name of an advanced policy expression as the prefix to a function. The named expres-
sion can be either a simple expression or a compound expression. The function must be one that can
operate on the type of data that is returned by the named expression.

Example 1: Simple Named Expression as a Prefix

The following simple named expression, which identifies a text string, can be used as a prefix to the
AFTER_STR(“<string>“)function, which works with text data:

HTTP.REQ.BODY(1000)

If the name of the expression is top1KB, you can use top1KB.AFTER_STR(“username”) instead of
HTTP.REQ.BODY(1000).AFTER_STR(“username”).

Example 2: Compound named expression as a prefix

You can create a compound named expression called basic_header_value to concatenate the user
name in a request, a colon (:), and the user’s password, as follows:

add policy expression basic_header_value ”HTTP.REQ.USER.NAME + \”:\” + HTTP

.REQ.USER.PASSWD”

You can then use the name of the expression in a rewrite action, as shown in the following example:

add rewrite action insert_b64encoded_authorization insert_http_header

authorization ’”Basic ” + basic_header_value.b64encode’-bypassSafetyCheck
YES

In the example, in the expression that is used to construct the value of the custom header, the B64
encoding algorithm is applied to the string returned by the compound named expression.

You can also use a named expression (either by itself or as a prefix to a function) to create the text
expression for the replacement target in a rewrite.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1205

NetScaler 12.0

Configure a named default syntax expression by using the CLI

At the command prompt, type the following commands to configure a named expression and verify
the configuration:

1 - add policy expression \<name\>\<value\>

2
3 - show policy expression \<name\>

Example:

1 > add policy expression myExp ”http.req.body(100).contains(\”the other

\”)”
2 Done
3
4 > show policy expression myExp
5 1) Name: myExp Expr: ”http.req.body(100).contains(”the other”
)” Hits: 0 Type : ADVANCED
6 Done

The expression can be up to 1,499 characters.

Configure a named expression by using the GUI

1. In the navigation pane, expand AppExpert, and then click Expressions.

2. Click Advanced Expressions.
3. Click Add.
4. Enter a name and a description for the expression.
5. Configure the expression by using the process described in Configure advanced policy expres-
sion. A message in the status bar indicates that the policy expression is configured successfully.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configure advanced policy expressions outside the context of a policy

September 24, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1206

NetScaler 12.0

Contributed by:
C

A number of functions, including the following, can require an advanced policy expression that is not
part of a policy:

• Integrated Caching selectors:

You define multiple non-compound expressions (selectlets) in the definition of the selector.
Each selectlet is in an implicit logical AND relationship with the others.

• Load Balancing:

You configure an expression for the TOKEN method of load balancing for a load balancing virtual
server.

• Rewrite actions:

Expressions define the location of the rewrite action and the type of rewriting to be performed,
depending on the type of rewrite action that you are configuring. For example, a DELETE action
only uses a target expression. A REPLACE action uses a target expression and an expression to
configure the replacement text.

• Rate-based policies:

You use advanced policy xpressions to configure Limit Selectors. You can use these selectors
when configuring policies to throttle the rate of traffic to various servers. You define up to five
non-compound expressions (selectlets) in the definition of the selector. Each selectlet is in an
implicit logical AND with the others.

Configure an advanced policy expression outside a policy by using the CLI (cache
selector example)

At the command prompt, type the following commands to configure an advanced policy expression
outside a policy and verify the configuration:

1 - add cache selector \<selectorName\> \<rule\>

2 - show cache selector \<selectorName\>

Example:

1 > add cache selector mainpageSelector ”http.req.cookie.value(\”ABC_def

\”)”
2 ”http.req.url.query.value(\”_ghi\”)”selector ”mainpageSelector”
added
3 Done
4 > show cache selector mainpageSelector

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1207

NetScaler 12.0

5 Name: mainpageSelector
6 Expressions:
7 1) http.req.cookie.value(”ABC_def”)
8 2) http.req.url.query.value(”_ghi”)
9 Done

Following is an equivalent command that uses the more readable q delimiter, as described in Config-
ure advanced policy expressions in a policy:

1 > add cache selector mainpageSelector2 q~http.req.cookie.value(”ABC_def

”)~
2 q~http.req.url.query.value(”_ghi”)~selector ”mainpageSelector2”
added
3 Done
4 > show cache selector mainpageSelector2
5 Name: mainpageSelector2
6 Expressions:
7 1) http.req.cookie.value(”ABC_def”)
8 2) http.req.url.query.value(”_ghi”)
9 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Advanced policy expressions: evaluating text

September 24, 2018

Contributed by:
C

You can configure a policy with an advanced policy expression that evaluates text in a request or
response. Advanced policy text expressions can range from simple expressions that perform string
matching in HTTP headers to complex expressions that encode and decode text. You can configure
text expressions to be case sensitive or case insensitive and to use or ignore spaces. You can also
configure complex text expressions by combining text expressions with Boolean operators

You can use expression prefixes and operators for evaluating HTTP requests, HTTP responses, and
VPN and Clientless VPN data. However, text expression prefixes are not restricted to evaluating these
elements of your traffic.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1208

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

About text expressions

December 7, 2018

Contributed by:
C

You can configure various expressions for working with text that flows through the NetScaler appli-
ance. Following are some examples of how you can parse text by using a default syntax expression:

• Determine that a particular HTTP header exists.

For example, you may want to identify HTTP requests that contains a particular Accept-
Language header for the purpose of directing the request to a particular server.

• Determine that a particular HTTP URL contains a particular string.

For example, you may want to block requests for particular URLs. Note that the string can occur
at the beginning, middle, or end of another string.

• Identify a POST request that is directed to a particular application.

For example, you may want to identify all POST requests that are directed to a database appli-
cation for the purpose of refreshing cached application data.

Note that there are specialized tools for viewing the data stream for HTTP requests and responses.

About operations on text

A text-based expression consists of at least one prefix to identify an element of data and usually (al-
though not always) an operation on that prefix. Text-based operations can apply to any part of a
request or a response. Basic operations on text include various types of string matches.

For example, the following expression compares a header value with a string:

http.req.header(”myHeader”).contains(”some-text”)

Following expressions are examples of matching a file type in a request:

http.req.url.suffix.contains(”jpeg”)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1209

NetScaler 12.0

http.req.url.suffix.eq(”jpeg”)

In the preceding examples, the contains operator permits a partial match and the eq operator looks
for an exact match.

Other operations are available to format the string before evaluating it. For example, you can use text
operations to strip out quotes and white spaces, to convert the string to all lowercase, or to concate-
nate strings.

Note: Complex operations are available to perform matching based on patterns or to convert
one type of text format to another type.

For more information, see the following topics:

• Pattern sets and data sets.

• Regular expressions.
• Typecasting data.

Compounding and precedence in text expressions

You can apply various operators to combine text prefixes or expressions. For example, the following
expression concatenates the returned values of each prefix:

http.req.hostname + http.req.url

Following is an example of a compound text expression that uses a logical AND. Both components of
this expression must be TRUE for a request to match the expression:

http.req.method.eq(post)&& http.req.body(1024).startswith(”destination=”)

Note: For more information on operators for compounding, see

Compound default syntax expressions.

Categories of text expressions

The primary categories of text expressions that you can configure are:

• Information in HTTP headers, HTTP URLs, and the POST body in HTTP requests.

For more information, see Expression prefixes for text in HTTP requests and responses.

• Information regarding a VPN or a clientless VPN.

For more information, see Expression prefixes for VPNs and clientless VPNs.

• TCP payload information.

For more information about TCP payload expressions, see Default syntax expressions: Parsing
HTTP, TCP, and UDP data.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1210

NetScaler 12.0

• Text in a Secure Sockets Layer (SSL) certificate.

For information about text expressions for SSL and SSL certificate data, see Default syntax ex-
pressions: Parsing SSL certificates and Expressions for SSL certificate dates.

Note: Parsing a document body, such as the body of a POST request, can affect performance.
You may want to test the performance impact of policies that evaluate a document body.

Guidelines for text expressions

From a performance standpoint, it typically is best to use protocol-aware functions in an expression.

For example, the following expression makes use of a protocol-aware function:

HTTP.REQ.URL.QUERY

The previous expression performs better than the following equivalent expression, which is based on
string parsing:

HTTP.REQ.URL.AFTER_STR(”?”)

In the first case, the expression looks specifically at the URL query. In the second case, the expression
scans the data for the first occurrence of a question mark.

There is also a performance benefit from structured parsing of text, as in the following expression:

HTTP.REQ.HEADER(”Example”).TYPECAST_LIST_T(’,’).GET(1)

(For more information on typecasting, seeTypecasting data. The typecasting expression, which col-
lects comma-delimited data and structures it into a list, typically would perform better than the fol-
lowing unstructured equivalent:

HTTP.REQ.HEADER(”Example”).AFTER_STR(”,”).BEFORE_STR(”,”)

Finally, unstructured text expressions typically have better performance than regular expressions. For
example, the following is an unstructured text expression:

HTTP.REQ.HEADER(”Example”).AFTER_STR(”more”)

The previous expression would generally provide better performance than the following equivalent,
which uses a regular expression:

HTTP.REQ.HEADER(”Example”).AFTER_REGEX(re/more/)

For more information on regular expressions, see Regular expressions.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1211

NetScaler 12.0

Expression prefixes for text in HTTP requests and responses

January 6, 2019

Contributed by:
C

An HTTP request or response typically contains text, such as in the form of headers, header values,
URLs, and POST body text. You can configure expressions to operate on one or more of these text-
based items in an HTTP request or response.

Refer to the Expression Prefix table for information on how to configure and extract text from different
parts of an HTTP request or response.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Expression prefixes for VPNs and clientless VPNs

May 13, 2019

Contributed by:
C

The Advanced policy engine provides prefixes that are specific to parsing VPN or Clientless VPN data.
This data includes the following:

• Host names, domains, and URLs in VPN traffic.

• Protocols in the VPN traffic.
• Queries in the VPN traffic.

These text elements are often URLs and components of URLs. In addition to applying the text-based
operations on these elements, you can parse these elements by using operations that are specific to
parsing URLs. For more information, see Expressions for extracting segments of URLs

For information about VPN expression prefixes, see VPN expression table.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1212

NetScaler 12.0

Basic operations on text

September 24, 2018

Contributed by:
C

Basic operations on text include operations for string matching, calculating the length of a string, and
controlling case sensitivity. You can include white space in a string that is passed as an argument to
an expression, but the string cannot exceed 255 characters.

String comparison functions

The following table lists basic string matching operations in which the functions return a Boolean
TRUE or FALSE.

Function Description

<text>.CONTAINS(<string>) Returns a Boolean TRUE value if the target

contains <string>. Example:
http.req.url.contains(”.jpeg”)
<text>.EQ(<string>) Returns a Boolean TRUE value if the target is an
exact match with <string>. For example, the
following expression returns a Boolean TRUE
for a URL with a host name of “myhostabc”:
http.req.url.hostname.eq(”myhostabc
”)
<text>.STARTSWITH(<string>) Returns a Boolean TRUE value if the target
begins with <string>. For example, the
following expression returns a Boolean TRUE
for a URL with a host name of “myhostabc”:
http.req.url.hostname.startswith(”
myhost”)
<text>.ENDSWITH(<string>) Returns a Boolean TRUE value if the target
ends with <string>. For example, the following
expression returns a Boolean TRUE for a URL
with a host name of “myhostabc”: http.req.
url.hostname.endswith(”abc”)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1213

NetScaler 12.0

Function Description

<text>.NE(<string>) Returns a Boolean TRUE value if the prefix is

not equal to the string argument. If the prefix
returns a non-string value, the function
argument is compared to the string
representation of the value returned by the
prefix. You can use the functions with
SET_TEXT_MODE(IGNORECASE) or
SET_TEXT_MODE(NOIGNORECASE), and with
both ASCII and UTF-8 character sets.
<text>.GT(<string>) Returns a Boolean TRUE value if the prefix is
alphabetically greater than the string
argument. If the prefix returns a non-string
value, the function argument is compared to
the string representation of the value returned
by the prefix. You can use the functions with
SET_TEXT_MODE(IGNORECASE) or
SET_TEXT_MODE(NOIGNORECASE), and with
both ASCII and UTF-8 character sets.
<text>.GE(<string>) Returns a Boolean TRUE value if the prefix is
alphabetically greater than or equal to the
string argument. If the prefix returns a
non-string value, the function argument is
compared to the string representation of the
value returned by the prefix. You can use the
functions with SET_TEXT_MODE(IGNORECASE)
or SET_TEXT_MODE(NOIGNORECASE), and
with both ASCII and UTF-8 character sets.
<text>.LT(<string>) Returns a Boolean TRUE value if the prefix is
alphabetically lesser than the string argument.
If the prefix returns a non-string value, the
function argument is compared to the string
representation of the value returned by the
prefix. You can use the functions with
SET_TEXT_MODE(IGNORECASE) or
SET_TEXT_MODE(NOIGNORECASE), and with
both ASCII and UTF-8 character sets.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1214

NetScaler 12.0

Function Description

<text>.LE(<string>) Returns a Boolean TRUE value if the prefix is

alphabetically lesser than or equal to the string
argument. If the prefix returns a non-string
value, the function argument is compared to
the string representation of the value returned
by the prefix. You can use the functions with
SET_TEXT_MODE(IGNORECASE) or
SET_TEXT_MODE(NOIGNORECASE), and with
both ASCII and UTF-8 character sets.

Calculate the length of a string

The <text>.LENGTH operation returns a numeric value that is equal to the number of characters (not
bytes) in a string:

<text>.LENGTH

For example, you may want to identify request URLs that exceed a particular length. Following is an
expression that implements this example:

HTTP.REQ.URL.LENGTH < 500

After taking a count of the characters or elements in a string, you can apply numeric operations to
them. For more information, see Default Syntax Expressions: Working with Dates, Times, and Num-
bers.

Consider, ignore, and change text case

The following functions operate on the case (upper-case or lower-case) of the characters in the string.

Function Description

<text>.SET_TEXT_MODE(IGNORECASE
NOIGNORECASE) This function turns case
sensitivity on or off for all text
operations.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1215

NetScaler 12.0

Function Description

<text>.TO_LOWER Converts the target to

lowercase for a text block of
up to 2 kilobyte (KB). Returns
UNDEF if the target exceeds 2
KB. For example, the string
“ABCd:” is converted to
“abcd:”.
<text>.TO_UPPER Converts the target to
uppercase. Returns UNDEF if
the target exceeds 2 KB. For
example, the string “abcD:” is
converted to “ABCD:”.

Strip specific characters from a string

You can use the STRIP_CHARS(<string>) function to remove specific characters from the text that is
returned by a default syntax expression prefix (the input string). All instances of the characters that
you specify in the argument are stripped from the input string. You can use any text method on the
resulting string, including the methods used for matching the string with a pattern set.

For example, in the expression CLIENT.UDP.DNS.DOMAIN.STRIP_CHARS(“.-_”), the STRIP_CHARS(<string>)

function strips all periods (.), hyphens (-), and underscores (_) from the domain name returned by
the prefix CLIENT.UDP.DNS.DOMAIN. If the domain name that is returned is “a.dom_ai_n-name”, the
function returns the string “adomainname”.

In the following example, the resulting string is compared with a pattern set called “listofdomains”:

CLIENT.UDP.DNS.DOMAIN.STRIP_CHARS(”.-_”).CONTAINS_ANY(”listofdomains”)

Note: You cannot perform a rewrite on the string that is returned by the
STRIP_CHARS(<string>) function.

The following functions strip matching characters from the beginning and end of a given string input.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1216

NetScaler 12.0

Function Description

<text>.STRIP_START_CHARS(s) Strips matching characters from the beginning

of the input string until the first non-matching
character is found and returns the remainder
of the string. You must specify the characters
that you want to strip as a single string within
quotation marks. For example, if the name of a
header is TestLang and ://en_us:is its
value,HTTP.RES.HEADER(“TestLang”).STRIP_START_CHARS(“:/“)
the specified characters from the beginning of
the value of the header until the first
non-matching character e is found and
returnsen_us: as a string.
<text>.STRIP_END_CHARS(s) Strips matching characters from the end of the
input string to the first non-matching character
is found and returns the remainder of the
string. You must specify the characters that
you want to strip as a single string within
quotation marks. For example, if the name of a
header is TestLang and ://en_us:is its
value,HTTP.RES.HEADER(“TestLang”).STRIP_START_CHARS(“:/“)
the specified characters from the end of the
value of the header until the first non-matching
character s is found and returns://_en_us as a
string.

Append a string to another string

You can use the APPEND() function to append the string representation of the argument to the string
representation of the value returned by the preceding function. The preceding function can be one
that returns a number, unsigned long, double, time value, IPv4 address, or IPv6 address. The argu-
ment can be a text string, number, unsigned long, double, time value, IPv4 address, or IPv6 address.
The resulting string value is the same string value that is obtained by using the + operator.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1217

NetScaler 12.0

Complex operations on text

January 6, 2019

Contributed by:
C

In addition to performing simple string matching, you can configure expressions that examine more
complex aspects of text, including examining the length of a string and looking within a text block for
patterns rather than specific strings.

Be aware of the following for any text-based operation:

• For any operation that takes a string argument, the string cannot exceed 255 characters.
• You can include white space when you specify a string in an expression.

Operations on the length of a string

The following operations extract strings on the basis of a character count.

Character Count Operation Description

<text>.TRUNCATE(<count>) Returns a string after truncating the end of the

target by the number of characters in
<count>. If the entire string is shorter than
<count>, nothing is returned.
<text>.TRUNCATE(<character>, <count>) Returns a string after truncating the text after
<character> by the number of characters
specified in <count>.
<text>.PREFIX(<character>, <count>) Selects the longest prefix in the target that has
at most <count> occurrences of
<character>.
<text>.SUFFIX(<character>, <count>) Selects the longest suffix in the target that has
at most <count> occurrences of
<character>. For example, consider the
following response body: JLEwx. The following
expression returns a value of
“JLEwx”: http.res.body(100).suffix(‘L’,1) The
following expression returns
“LLEwx”: http.res.body(100).suffix(‘L’,2)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1218

NetScaler 12.0

Character Count Operation Description

<text>.SUBSTR(<starting_offset>, < Select a string with <length>number of

length>) characters from the target object. Begin
extracting the string after the
<starting_offset>. If the number of
characters after the offset are fewer than the
value of the <length> argument, select all the
remaining characters.
<text>.SKIP(<character>, <count>) Select a string from the target after skipping
over the longest prefix that has at most
<count> occurrences of <character>.

Operations on a portion of a string

Refer to the String operations table to know how to extract a subset of a larger string by using one of
the operations.

Operations for comparing the alphanumeric order of two strings

The COMPARE operation examines the first nonmatching character of two different strings. This oper-
ation is based on lexicographic order, which is the method used when ordering terms in dictionaries.

This operation returns the arithmetic difference between the ASCII values of the first nonmatching
characters in the compared strings. The following differences are examples:

• The difference between “abc” and “abd” is -1 (based on the third pair-wise character compari-
son).
• The difference between “@” and “abc” is -33.
• The difference between “1” and “abc” is -47.

Following is the syntax for the COMPARE operation.

<text>.COMPARE(<string>)

Extract an integer from a string of bytes that represent text

Refer to the Integer extraction table to know how to treat a string of bytes that represent text as a
sequence of bytes, extract 8, 16, or 32 bits from the sequence, and then convert the extracted bits to
an integer.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1219

NetScaler 12.0

Convert text to a hash value

You can convert a text string to a hash value by using the HASH function. This function returns a 31-bit
positive integer as a result of the operation. Following is the format of the expression:

<text>.HASH

This function ignores case and white spaces. For example, after the operation, the two strings Ab c
and a bc would produce the same hash value.

Encode and decode text by applying the Base64 encoding algorithm

The following two functions encode and decode a text string by applying the Base64 encoding algo-
rithm

Function Description

text.B64ENCODE Encodes the text string (designated by text) by

applying the Base64 encoding algorithm.
text.B64DECODE Decodes the Base64-encoded string
(designated by text) by applying the Base64
decoding algorithm. The operation raises an
UNDEF if text is not in B64-encoded format.

Refine the search in a rewrite action by using the EXTEND function

The EXTEND function is used in rewrite actions that specify patterns or pattern sets and target the
bodies of HTTP packets. When a pattern match is found, the EXTEND function extends the scope of
the search by a predefined number of bytes on both sides of the matching string. A regular expression
can then be used to perform a rewrite on matches in this extended region. Rewrite actions that are
configured with the EXTEND function perform rewrites faster than rewrite actions that evaluate entire
HTTP bodies using only regular expressions.

The format of the EXTEND function is EXTEND(m,n ), where m and n are the number of bytes by which
the scope of the search is extended before and after the matching pattern, respectively. When a match
is found, the new search scope comprises m bytes that immediately precede the matching string, the
string itself, and the n bytes that follow the string. A regular expression can then be used to perform a
rewrite on a portion of this new string.

The EXTEND function can be used only if the rewrite action in which it is used fulfills the following
requirements:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1220

NetScaler 12.0

• The search is performed by using patterns or patterns sets (not regular expressions)
• The rewrite action evaluates only the bodies of HTTP packets.
Additionally, the EXTEND function can be used only with the following types of rewrite actions:
• replace_all
• insert_after_all
• delete_all
• insert_before_all
For example, you might want to delete all instances of ”<http://exampleurl.com/>” and ”<http
://exampleurl.au/>” in the first 1000 bytes of the body. To do this, you can configure a rewrite
action to search for all instances of the string exampleurl, extend the scope of the search on both
sides of the string when a match is found, and then use a regular expression to perform the rewrite
in the extended region. The following example extends the scope of the search by 20 bytes to the left
and 50 bytes to the right of the matching string:
add rewrite action delurl_example delete_all ’HTTP.REQ.BODY(1000)’-pattern
exampleurl -refineSearch ’extend(20,50).regex_select(re##http://exampleurl
.(com|au)##)’

Convert text to hexadecimal format

The following function converts text to hexadecimal format and extracts the resulting string:
<text>.BLOB_TO_HEX(<string>)

For example, this function converts the byte string “abc” to “61:62:63”.

Encrypt and decrypt text

In default syntax expressions, you can use the ENCRYPT and DECRYPT functions to encrypt and de-
crypt text. Data encrypted by the ENCRYPT function on a given NetScaler appliance or high availabil-
ity (HA) pair is intended for decryption by the DECRYPT function on the same NetScaler appliance or
HA pair. The appliance supports the RC4, DES3, AES128, AES192, and AES256 encryption methods.
The key value that is required for encryption is not user-specifiable. When an encryption method is
set, the appliance automatically generates a random key value that is appropriate for the specified
method. The default method is AES256 encryption, which is the most secure encryption method and
the one that Citrix recommends.
You do not need to configure encryption unless you want to change the encryption method or you
want the appliance to generate a new key value for the current encryption method.
Note: You can also encrypt and decrypt XML payloads. For information about the functions for en-
crypting and decrypting XML payloads, see Encrypt and decrypt XML payloads.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1221

NetScaler 12.0

Configure encryption

During startup, the appliance runs the set ns encryptionParams command with, by default, the
AES256 encryption method, and uses a randomly generated key value that is appropriate for AES256
encryption. The appliance also encrypts the key value and saves the command, with the encrypted
key value, to the NetScaler configuration file. Consequently, the AES256 encryption method is
enabled for the ENCRYPT and DECRYPT functions by default. The key value that is saved in the
configuration file persists across reboots even though the appliance runs the command each time
you restart it.

You can run the set ns encryptionParams command manually, or use the GUI, if you want to change the
encryption method or if you want the appliance to generate a new key value for the current encryption
method. To use the CLI to change the encryption method, set only the method parameter, as shown
in “Example 1: Changing the Encryption Method.” If you want the appliance to generate a new key
value for the current encryption method, set the method parameter to the current encryption method
and the keyValue parameter to an empty string (“”), as shown in “Example 2: Generating a New Key
Value for the Current Encryption Method.” After you generate a new key value, you must save the
configuration. If you do not save the configuration, the appliance uses the newly generated key value
only until the next restart, after which it reverts to the key value in the saved configuration.

Configure encryption by using the GUI

1. Navigate to System > Settings.

2. In the Settings area, click Change Encryption parameters.
3. In the Change Encryption Parameters dialog box, do one of the following:
• To change the encryption method, in the Method list, select the encryption method that
you want.
• To generate a new key value for the current encryption method, click Generate a new key
for the selected method.
4. Click OK.

Use the ENCRYPT and DECRYPT functions

You can use the ENCRYPT and DECRYPT functions with any expression prefix that returns text. For
example, you can use the ENCRYPT and DECRYPT functions in rewrite policies for cookie encryption.
In the following example, the rewrite actions encrypt a cookie named MyCookie, which is set by a
back-end service, and decrypt the same cookie when it is returned by a client:

1 add rewrite action my-cookie-encrypt-action replace ”HTTP.RES.

SET_COOKIE.COOKIE(”MyCookie”).VALUE(0)” ”HTTP.RES.SET_COOKIE.COOKIE(
”MyCookie”).VALUE(0).ENCRYPT” -bypassSafetyCheck YES

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1222

NetScaler 12.0

2
3 add rewrite action my-cookie-decrypt-action replace ”HTTP.REQ.COOKIE.
VALUE(”MyCookie”)” ”HTTP.REQ.COOKIE.VALUE(”MyCookie”).DECRYPT” -
bypassSafetyCheck YES

After you configure policies for encryption and decryption, save the configuration to bring the policies
into effect.

Configure encryption key for third-party encryption

In default syntax expressions, you can use ENCRYPT and DECRYPT functions for encrypting and de-
crypting text in a request or response. The data encrypted by the ENCRYPT function on an appliance
(standalone, high availability or cluster) is intended to be decrypted by the DECRYPT function by the
same appliance. The appliance supports RC4, DES, Triple-DES, AES92, and AES256 encryption meth-
ods and each of these methods use a secret key for both encryption and decryption of data. You can
use the any of these methods to encrypt and decrypt data in two ways - self-encryption and third-party
encryption.

The self-encryption feature in an appliance (standalone, high availability or cluster) encrypts and then
decrypts data by evaluating the header value. One example to understand this is the HTTP Cookie
encryption. The expression evaluates the header, encrypts the HTTP cookie value in the Set-Cookie
header in the outgoing response and then decrypts the cookie value when it is returned in the cookie
header of a subsequent incoming request from the client. The key value is not user configurable,
instead when an encryption method is configured in the set ns encryptionParams command, the
appliance automatically generates a random key value for the configured method. By default, the
command uses the AES256 encryption method, which is the highly secured method and Citrix recom-
mends this method.

The third-party encryption feature encrypts or decrypts data with a third-party application. For ex-
ample, a client may encrypt data in a request and the appliance decrypts the data before sending it
the back-end server or vice versa. To perform this, the appliance and the third party application must
share a secret key. On the appliance, you can directly configure the secret key using an encryption
key object and key value is automatically generated by the appliance for a stronger encryption. The
same key is manually configured on the third-party appliance so that both appliance and third-party
application can use the same key for encrypting and decryption data.

Note:

Using third-party encryption, you can also encrypt and decrypt XML payloads. For information
about the functions for encrypting and decrypting XML payloads, see “Encrypting and Decrypt-
ing XML Payloads.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1223

NetScaler 12.0

Cipher methods

A cipher method provides two functions: an encryption function that transforms a plaintext byte se-
quence into a ciphertext byte sequence, and a decryption function that transforms the ciphertext
back to the plaintext. Cipher methods use byte sequences called keys to perform encryption and
decryption. Cipher methods that use the same key for encryption and decryption are called symmet-
ric. Cipher methods that use different keys for encryption and decryption are asymmetric. The most
notable examples of asymmetric ciphers are in public key cryptography, which uses a public key avail-
able to anyone for encryption and a private key known only to the decryptor.

A good cipher method makes it infeasible to decrypt (“crack”) ciphertext if you don’t possess the key.
“Infeasible” really means that cracking the cyphertext would take more time and computing resources
than it is worth. As computers become more powerful and cheaper, ciphers that were formerly in-
feasible to crack become more feasible. Also, over time, flaws are found in cipher methods (or their
implementations), making cracking easier. Newer cipher methods are therefore preferred over older
ones. In general, longer length keys provide better security than shorter keys, at the cost of longer
encryption and decryption times.

A cipher method can use stream ciphers or block ciphers. RC4 is the mostly secured stream ciphers
and it is used only for legacy application. Block ciphers can include padding.

Stream ciphers

A stream cipher method operates on individual bytes. Only one stream cipher is available on
NetScaler- appliances: RC4, which uses a 128 bit (16 byte) key length. For a given key, RC4 generates
a pseudo-random sequence of bytes, call a keystream, which is X-ORed with the plaintext to produce
the ciphertext. RC4 is no longer considered secure and should be used only if required by legacy
applications.

Block ciphers

A block cipher method operates on a fixed block of bytes. A NetScaler appliance provides two block
ciphers: Data Encryption Standard (DES) and the Advanced Encryption Standard (AES). DES uses a
block size of 8 bytes and (on a NetScaler appliance) two choices for key length: 64 bits (8 bytes), of
which 56 bits are data and 8 bits are parity, and Triple-DES, a 192 bit (24 byte) key length. AES has a
block size of 16 bytes and (on NetScaler) three choices for key length: 128 bits (16 bytes), 192 bits (24
bytes) and 256 bits (32 bytes).

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1224

NetScaler 12.0

Padding

If the plaintext for a block cipher is not an integral number of blocks, padding with additional bytes
might be required. For example, suppose the plaintext is “xyzzy” (hex 78797a7a79). For an 8-byte
Triple-DES block, this value would have to be padded to create 8 bytes. The padding scheme must
allow the decryption function to determine the length of the original plaintext after decryption. Fol-
lowing are some padding schemes currently in use (n is the number of bytes added):
• PKCS7: Adds n bytes of value n each. For example, 78797a7a79030303. This is the padding
scheme used by OpenSSL and ENCRYPT() policy function. The PKCS5 padding scheme is the
same as PKCS7.
• ANSI X.923: Adds n-1 zero bytes and a final byte of value n. For example, 78797a7a79000003.
• ISO 10126: Adds n-1 random bytes and a final byte of value n. For example, 78797a7a79xxxx03,
where xx can be any byte value. The DECRYPT() policy function accepts this padding scheme,
which also allows it to accept the PKCS7 and ANSI X.923 schemes.
• ISO/IEC 7816-4: Adds a 0x80 byte and n-1 zero bytes. For example, 78797a7a79800000. This is
also call OneAndZeros padding.
• Zero: Adds n zero bytes. Example: 78797a7a79000000. This can only be used with plaintext
that does not include NUL bytes.
If padding is used and the plaintext is an integral number of blocks, an additional block is typically
added so that the decryption function can unambiguously determine the original plaintext length.
For PCKS7 and 8 byte block, this would be 0808080808080808.

Modes of operation

There are a number of different modes of operation for block ciphers, which specify how multiple
blocks of plaintext are encrypted. Some modes use an initialization vector (IV), a block of data apart
from the plaintext that is used to start the encryption process. It is a good practice to use a different
IV for each encryption, so that the same plaintext produces different ciphertext. The IV does not need
to be secret, and so is usually prepended to the ciphertext. Modes include:
• Electronic Codebook (ECB): Each block of plaintext is encrypted independently. An IV is not
used. Padding is required if the plaintext is not a multiple of the cipher block size. The same
plaintext and key always produces the same ciphertext. Because of this, ECB is considered less
secure than other modes and should only be used for legacy applications.
• Cipher Block Chaining (CBC): Each block of plaintext is XORed with the previous ciphertext
block, or the IV for the first block, before being encrypted. Padding is required if the plain-
text is not a multiple of the cipher block size. This is the mode used with the NetScaler
encryptionParams method.
• Cipher Feedback (CFB): The previous ciphertext block, or the IV for the first block, is encrypted
and the output is XORed with the current plaintext block to create the current ciphertext block.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1225

NetScaler 12.0

The feedback can be 1 bit, 8 bits, or 128 bits. Since the plaintext is XORed with the cipher text,
padding is not required.
• Output Feedback (OFB): A keystream is generated by applying the cipher successively to the IV
and XORing the keystream blocks with the plaintext. Padding is not required.

Configure encryption keys for third-party encryption

Following are the configuration tasks performed in configuring encryption key.

1. Adding an encryption key. Configures an encryption key for a specified cipher method with a
specified key value.
2. Modifying an encryption key. You can edit parameters for a configured encryption key.
3. Unsetting an encryption key. Sets parameters for a configured encryption key to their default
values. An encryptionKey value with the name must exist. Sets padding to DEFAULT (deter-
mined by the method), Deletes an existing IV, which causes ENCRYPT() to generate a random IV.
Deletes an existing comment. The method and key value cannot be reset.
4. Removing an encryption key. Deletes a configured encryption key. The key cannot have any
references.
5. Show an encryption key. Displays parameters for the configured encryption key or all config-
ured keys. If the name is omitted, the key value is not displayed.

Add an encryption key by using the CLI

At the command prompt, type:

add ns encryptionKey <name> -method <method> [-keyValue <hexstring>][-

padding (OFF | ON)] [-iv <hexstring>] [-comment <string>]

Where,

1 <method> = ( NONE | RC4 | DES3 | AES128 | AES192 | AES256 | DES | DES-

CBC | DES-CFB | DES-OFB | DES-ECB | DES3-CBC | DES3-CFB | DES3-OFB |
DES3-ECB | AES128-CBC | AES128-CFB | AES128-OFB | AES128-ECB |
AES192-CBC | AES192-CFB | AES192-OFB | AES192-ECB | AES256-CBC |
AES256-CFB | AES256-OFB | AES256-ECB ) <hexstring> = hex-encoded
byte sequence

The above encryption methods specify the operation mode with CBC as the default mode of opera-
tion. Therefore, DES, DES2, AES128, AES192, and AES256 methods are equivalent to DES-CBC, DES3-
CBC, AES128-CBC, AES192-CBC, and AES256-CBC methods.

Modify an encryption key by using the CLI

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1226

NetScaler 12.0

At the command prompt, type:

set ns encryptionKey <name> [-method <method>] [-keyValue <hexstring>] [-
padding ( OFF | ON )] [-iv <string>] [-comment <string>]

Unset an encryption key by using the CLI

At the command prompt, type:
unset ns encryptionKey <name> [-padding] [-iv] [-comment]

Remove an encryption key by using the CLI

At the command prompt, type:
rm ns encryptionKey <name>

Show an encryption key by using the CLI

At the command prompt, type:
Example:

1 show ns encryptionKey [<name>]

2
3 add ns encryptionKey my_key -method aes256 -keyValue 26
ea5537b7e0746089476e5658f9327c0b10c3b4778c673a5b38cee182874711 ‒ iv
c2bf0b2e15c15004d6b14bcdc7e5e365
4 set ns encryptionKey my_key -keyValue
b8742b163abcf62d639837bbee3cef9fb5842d82d00dfe6548831d2bd1d93476
5 unset ns encryptionKey my_key -iv
6 rm ns encryptionKey my_key
7 show ns encryptionKey my_key
8 Name: my_key
9 Method: AES256
10 Padding: DEFAULT
11 Key Value: (not disclosed)

Add an encryption key by using the GUI

Navigate to System > Encryption Keys and click Add to create an encryption key.

Modify an encryption key by using the GUI

Navigate to System > Encryption Keys and click Edit to modify parameters for a configured encryp-
tion key.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1227

NetScaler 12.0

Remove an encryption key by using the GUI

Navigate to System > Encryption keys and click Delete.

ENCRYPT and DECRYPT functions for third-party encryption

Following is the ENCRYPT function used for third-part encryption.

ENCRYPT (encryptionKey, out_encoding)

Where,

Input data for the appliance is the text to be encrypted

encryptionKey: An optional string parameter that specifies the configured encryption key object to
provide the encryption method, secret key value and other encryption parameters. If omitted, the
method uses the automatically generated key value associated with the set ns encryptionParamS
command.

out_encoding: This value specifies how the output is encoded. If omitted, BASE64 encoding is used.

Input:

1 BASE64:     original PEM base64-encoding: 6 bits (0..63) encoded as one

ASCII character:
2               0..23 = ’A’..’Z’, 24..51 = ’a’..’z’, 52..61 = ’0’..’9
’, 62 = ’+’, 63 = ’/’, ’=’ = pad byte.
3   BASE64URL:  URL and Filename safe base64-encoding: same as BASE64
except 62 = ’-’, 63 = ’_’
4   HEX_UPPER:  Hexadecimal with 0..9 = ’0’..’9’ and 10..15 = ’A’..’F
’.
5   HEX_LOWER:  Hexadecimal with 0..9 = ’0’..’9’ and 10..15 = ’a’..’f
’.
6   HEX_COLONS: Hexadecimal with 0..9 = ’0’..’9’ and 10..15 = ’A’..’F
’; ’:’ between each hex byte. Matches BLOB_TO_HEX() output
format
7   HEX:        For input, accepts HEX_UPPER, HEX_LOWER, and
HEX_COLONS format. For output, produces HEX_LOWER format

Output: The output is a text encrypted using the specified method and key and encoded using a speci-
fied output encoding. It inserts a generated IV before the encrypted text for block methods and modes
that require an IV, and either no IV is specified for the encryptionKey or the encryptionKey is omitted.

Following is the DECRYPT function used for third-part decryption.

DECRYPT(encryptionKey, in_encoding)

Where,

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1228

NetScaler 12.0

Input data is an encrypted text using the specified method and key encoded using the specified input
encoding. This text is expected to include a generated IV before the encrypted text for block methods
and modes that require an IV, and either no IV is specified for the encryptionKey or the encryptionKey
is omitted.

encryptionKey—An optional string parameter that specifies the configured encryptionKey object to
provide the encryption method, secret key and other encryption parameters. If omitted, the method
and automatically generated key associated with the encryptionParams setting will be used

in_encoding—An optional enumeration parameter that specifies how the input is expected to be en-
coded. The values are the same as the out_encoding of ENCRYPT. If omitted, BASE64 encoding will
be expected.

The output data is an unencoded decrypted text.

Variants and optional parameters

Following are the variants of these functions with the optional parameters:

Variant Description

ENCRYPT Use encryptionParams command and BASE64

output encoding parameter.
ENCRYPT(out_encoding) Use encryptionParams and specified output
encoding parameter.
ENCRYPT(encryptionKey) Use the specified encryptionKey and BASE64
output encoding parameter.
ENCRYPT(encryptionKey, out_encoding) Use the specified encryptionKey and output
encoding parameter.
DECRYPT Use encryptionParams command and BASE64
input encoding parameter.
DECRYPT(out_encoding) Use encryptionParams command and the
specified input encoding parameter.
DECRYPT(encryptionKey) Use the specified encryptionKey and BASE64
input encoding parameter.
DECRYPT(encryptionKey, out_encoding) Use the specified encryptionKey and input
encoding parameter.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1229

NetScaler 12.0

Configure HMAC keys

NetScaler appliances support a Hashed Message Authentication Code (HMAC) function that calculates
a digest method or hash of input text by using a secret key shared between a message sender and mes-
sage receiver. The digest method (derived from an RFC 2104 technique) authenticates the sender and
verifies that the message content has not been altered. For example, when a client sends a message
with the shared HMAC key to a NetScaler appliance, advanced (PI) policy expressions use the HMAC
function to compute the hash-based code on the selected text. Then, when the receiver receives the
message with the secret key, it recomputes the HMAC by comparing it with the original HMAC to de-
termine whether the message has been altered. The HMAC function is supported by standalone ap-
pliances and by appliances in a high availability configuration or in a cluster. Using it is similar to
configuring an encryption key.

The add ns hmackey and set ns hmackey commands include a parameter that specifies the digest
method and the shared secret key to use for the HMAC computation.

To configure a HMAC key, you must perform the following:

1. Adding an HMAC key. Configures an HMAC key with a specified key value.
2. Modifying an HMAC key. Modifies parameters for a configured HMAC key. The digest method
can be changed without changing the key value, since the key value length is not determined
by the digest. However, it is advisable to specify a new key when changing the digest.
3. Unsetting an HMAC key. Sets parameters for a configured HMAC key to their default values. An
hmacKey object with the name must exist. The only parameter that can be unset is the com-
ment, which is deleted.
4. Removing an HMAC key. Deletes a configured key. The key cannot have any references.
5. Show an HMAC key. Displays parameters for the configured HMAC ac key or all configured keys.
If the name is omitted, the key value is not displayed.

Add an HMAC key by using the CLI

At the command prompt, type:

add ns hmacKey <name> -digest <digest> -keyValue <hexstring> [-comment <

string>]

Where,

<digest> = (MD2 | MD4 | MD5 | SHA1 | SHA224 | SHA256 | SHA384 | SHA512)

This command configures a key for the HMAC () function with the specified digest and key value and
also validates the following:

• Name syntax is correct and does not duplicate the name of an existing key.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1230

NetScaler 12.0

• Key value is valid hex. As specified by RFC 2104, the key can any length. On a NetScaler appli-
ance, the key value can range from 0 to 255 bytes (0 to 510 hex characters). If the key is shorter
than the digest block size, a warning is issued and the key is padded with zeroes. If the key is
longer than the block size, it is run through the digest to produce an effective key that is the
same length as the block.

Example:

add ns hmacKey my_hmac_key -digest sha1 -keyValue 0c753c6c5ef859189cacdf95b506d02c1797

The above encryption methods specify the operation mode with CBC as the default mode of opera-
tion. Therefore, DES, DES2, AES128, AES192, and AES256 methods are equivalent to DES-CBC, DES3-
CBC, AES128-CBC, AES192-CBC, and AES256-CBC methods.

Modify an HMAC key by using the CLI

This command modifies the parameters configured for a HMAC key. You can change the digest without
changing the key value, since the key value length is not determined by the digest. However, it is
advisable to specify a new key when changing the digest. At the command prompt, type:

set ns hmacKey <name> [-digest <digest>] [-keyValue <hexvalue>] [-comment <

string>]

Unset an HMAC key by using the CLI

This command sets parameters configured for a HMAC key with their default values. An hmacKey
object with the name must exist. The only parameter that you can unset is the comment option, which
is deleted. At the command prompt, type:

unset ns hmacKey <name> -comment

Remove an HMAC key by using the CLI

This command deletes the configured hmac key. The key cannot have references. At the command
prompt, type:

rm ns hmacKey <name>

Show an HMAC key by using the CLI

At the command prompt, type:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1231

NetScaler 12.0

1 show ns encryptionKey [<name>]

2
3 add ns hmacKey my_hmac_key -digest sha1 -keyValue 0
c753c6c5ef859189cacdf95b506d02c1797407d
4 set ns hmacKey my_hmac_key -keyValue
f348c594341a840a1f641a1cf24aa24c15eb1317
5 rm ns hmacKey my_hmac_key
6 show ns hmacKey my_hmac_key
7       Name: my_hmac_key
8 Digest: SHA1
9 Key Value: (not disclosed)

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Advanced policy expressions: working with dates, times, and numbers

September 24, 2018

Contributed by:
C

Most numeric data that the NetScaler appliance processes consists of dates and times. In addition
to working with dates and times, the appliance processes other numeric data, such as the lengths of
HTTP requests and responses. To process this data, you can configure advanced policy expressions
that process numbers.

A numeric expression consists of an expression prefix that returns a number and sometimes,
but not always, an operator that can perform an operation on the number. Examples of ex-
pression prefixes that return numbers are SYS.TIME.DAY, HTTP.REQ.CONTENT_LENGTH, and
HTTP.RES.BODY.LENGTH. Numeric operators can work with any prefix expression that returns data in
numeric format. The GT(<int>) operator, for example, can be used with any prefix expression, such as
HTTP.REQ.CONTENT_LENGTH, that returns an integer. Numeric expression prefixes and operators
are also covered in Compound Operations for Numbers and Advanced Policy Expressions: Parsing
HTTP, TCP, and UDP Data.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1232

NetScaler 12.0

4. AppExpert

Format of dates and times in an expression

September 24, 2018

Contributed by:
C

When configuring an advanced policy expression in a policy that works with dates and times (for ex-
ample, the NetScaler system time or a date in an SSL certificate), you specify a time format as follows:

GMT|LOCAL [<yyyy>] [<month>] [<d>] [<h>] [<m>] [<s>]

Where:

• <yyyy> is a four-digit year after GMT or LOCAL.

• <month> is a three-character abbreviation for the month, for example, Jan, Dec.

• <d> is a day of the week or an integer for the date.

You cannot specify the day as Monday, Tuesday, and so on. You specify either an integer for a
specific day of the month, or you specify a date as the first, second, third weekday of the month,
and so on. Following are examples of specifying a day of the week:

– Sun_1 is the first Sunday of the month.

– Sun_3 is the third Sunday of the month.
– Wed_3 is the third Wednesday of the month.
– 30 is an example of an exact date in a month.

• <h> is the hour, for example, 10h.

• <s> is the number of seconds, for example, 30s.

The following example expression is true if the date is between 2008 Jan and 2009 Jan, based on GMT.

http.req.date.between(GMT 2008 Jan, GMT 2009 Jan)

The following example expression is true for March and all months that follow March in the calendar
year, based on GMT:

sys.time.ge(GMT 2008 Mar)

When you specify a date and time, note that the format is case sensitive and must preserve the exact
number of blank spaces between entries.

1 **Note:**
2

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1233

NetScaler 12.0

3 In an expression that requires two time values, both must use GMT or
both must use LOCAL. You cannot mix the two in an expression.
4
5 Unlike when you use the SYS.TIME prefix in an advanced policy
expression, if you specify SYS.TIME in a rewrite action, the
NetScaler returns a string in conventional date format (for example,
Sun, 06 Nov 1994 08:49:37 GMT). For example, the following rewrite
action replaces the http.res.date header with the NetScaler system
time in a conventional date format:
6
7 add rewrite action sync_date replace http.res.date sys.time

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Expressions for the NetScaler system time

September 24, 2018

Contributed by:
C

The SYS.TIME expression prefix extracts the NetScaler system time. You can configure expressions that
establish whether a particular event occurred at a particular time or within a particular time range
according to the NetScaler system time.

The following table describes the expressions that you can create by using the SYS.TIME prefix.

• SYS.TIME.BETWEEN(<time1>, <time2>):

Returns a Boolean TRUE if the returned value is later than <time1> and earlier than <time2>.

You format the <time1>, <time2> arguments as follows:

– They must both be GMT or both LOCAL.

– <time2> must be later than <time1>.

For example, if the current time is GMT 2005 May 1 10h 15m 30s, and it is the first Sunday of the
month, you can specify the following:

– sys.time.between(GMT 2004, GMT 2006)

– sys.time.between(GMT 2004 Jan, GMT 2006 Nov)
– sys.time.between(GMT 2004 Jan, GMT 2006)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1234

NetScaler 12.0

– sys.time.between(GMT 2005 May Sun_1, GMT 2005 May Sun_3)

– sys.time.between(GMT 2005 May 1, GMT May 2005 1)
– sys.time.between(LOCAL 2005 May 1, LOCAL May 2005 1)

• SYS.TIME.DAY:

Returns the current day of the month as a number from 1 through 31.

• SYS.TIME.EQ(<time>):

Returns a Boolean TRUE if the current time is equal to the <time> argument.

For example, if the current time is GMT 2005 May 1 10h 15m 30s, and it is the first Sunday of the
month, you can specify the following (evaluation results are shown in parentheses):

– sys.time.eq(GMT 2005) (TRUE in this example.)

– sys.time.eq(GMT 2005 Dec) (FALSE in this example.)
– sys.time.eq(LOCAL 2005 May) (Evaluates to TRUE or FALSE in this example, depending on
the current time zone.)
– sys.time.eq(GMT 10h) (TRUE in this example.)
– sys.time.eq(GMT 10h 30s) (TRUE in this example.)
– sys.time.eq(GMT May 10h) (TRUE in this example.)
– sys.time.eq(GMT Sun) (TRUE in this example.)
– sys.time.eq(GMT May Sun_1) (TRUE in this example.)

• SYS.TIME.NE(<time>):

Returns a Boolean TRUE if the current time is not equal to the <time> argument.

• SYS.TIME.GE(<time>):

Returns a Boolean TRUE if the current time is later than or equal to <time>.

For example, if the current time is GMT 2005 May 1 10h 15m 30s, and it is the first Sunday of the
month, you can specify the following (evaluation results are shown in parentheses):

– sys.time.ge(GMT 2004) (TRUE in this example.)

– sys.time.ge(GMT 2005 Jan) (TRUE in this example.)
– sys.time.ge(LOCAL 2005 May) (TRUE or FALSE in this example, depending on the current
time zone.)
– sys.time.ge(GMT 8h) (TRUE in this example.)
– sys.time.ge(GMT 30m) (FALSE in this example.)
– sys.time.ge(GMT May 10h) (TRUE in this example.)
– sys.time.ge(GMT May 10h 0m) (TRUE in this example.)
– sys.time.ge(GMT Sun) (TRUE in this example.)
– sys.time.ge(GMT May Sun_1) (TRUE in this example.)

• SYS.TIME.GT(<time>):

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1235

NetScaler 12.0

Returns a Boolean TRUE if the time value is later than the <time> argument.

For example, if the current time is GMT 2005 May 1 10h 15m 30s, and it is the first Sunday of the
month, you can specify the following (evaluation results are shown in parentheses):

– sys.time.gt(GMT 2004) (TRUE in this example.)

– sys.time.gt(GMT 2005 Jan) (TRUE in this example.)
– sys.time.gt(LOCAL 2005 May) (TRUE or FALSE, depending on the current time zone. )
– sys.time.gt(GMT 8h) (TRUE in this example.)
– sys.time.gt(GMT 30m) (FALSE in this example.)
– sys.time.gt(GMT May 10h) (FALSE in this example.)
– sys.time.gt(GMT May 10h 0m) (TRUE in this example.)
– sys.time.gt(GMT Sun) (FALSE in this example.)
– sys.time.gt(GMT May Sun_1) (FALSE in this example.)

• SYS.TIME.HOURS:

Returns the current hour as an integer from 0 to 23.

• SYS.TIME.LE(<time>):

Returns a Boolean TRUE if the current time value precedes or is equal to the <time> argument.

For example, if the current time is GMT 2005 May 1 10h 15m 30s, and it is the first Sunday of the
month, you can specify the following (evaluation results are shown in parentheses):

– sys.time.le(GMT 2006) (TRUE in this example.)

– sys.time.le(GMT 2005 Dec) (TRUE in this example.)
– sys.time.le(LOCAL 2005 May) (TRUE or FALSE depending on the current timezone. )
– sys.time.le(GMT 8h) (FALSE in this example.)
– sys.time.le(GMT 30m) (TRUE in this example.)
– sys.time.le(GMT May 10h) (TRUE in this example.)
– sys.time.le(GMT Jun 11h) (TRUE in this example.)
– sys.time.le(GMT Wed) (TRUE in this example.)
– sys.time.le(GMT May Sun_1) (TRUE in this example.)

• SYS.TIME.LT(<time>):

Returns a Boolean TRUE if the current time value precedes the <time> argument.

For example, if the current time is GMT 2005 May 1 10h 15m 30s, and it is the first Sunday of the
month, you can specify the following (evaluation results are shown in parentheses):

– sys.time.lt(GMT 2006) (TRUE in this example.)

– sys.time.lt.time.lt(GMT 2005 Dec) (TRUE in this example.)
– sys.time.lt(LOCAL 2005 May) (TRUE or FALSE depending on the current time zone.)
– sys.time.lt(GMT 8h) (FALSE in this example.)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1236

NetScaler 12.0

– sys.time.lt(GMT 30m) (TRUE in this example.)

– sys.time.lt(GMT May 10h) (FALSE in this example.)
– sys.time.lt(GMT Jun 11h) (TRUE in this example.)
– sys.time.lt(GMT Wed) (TRUE in this example.)
– sys.time.lt(GMT May Sun_1) (FALSE in this example.)

• SYS.TIME.MINUTES:

Returns the current minute as an integer from 0 to 59.

• SYS.TIME.MONTH:

Extracts the current month and returns an integer from 1 (January) to 12 (December).

• SYS.TIME.RELATIVE_BOOT:

Calculates the number of seconds to the closest previous or scheduled reboot, and returns an
integer.

If the closest boot time is in the past, the integer is negative. If it is in the future, the integer is
positive.

• SYS.TIME.RELATIVE_NOW:

Calculates the number of seconds between the current NetScaler system time and the specified
time, and returns an integer showing the difference.

If the designated time is in the past, the integer is negative; if it is in the future, the integer is
positive.

• SYS.TIME.SECONDS:

Extracts the seconds from the current NetScaler system time, and returns that value as an inte-
ger from 0 to 59.

• SYS.TIME.WEEKDAY:

Returns the current weekday as a value from 0 (Sunday) to 6 (Saturday).

• SYS.TIME.WITHIN (<time1>, <time2>):

If you omit an element of time in <time1>, for example, the day or hour, it is assumed to have the
lowest value in its range. If you omit an element in <time2>, it is assumed to have the highest
value of its range.

The ranges for the elements of time are as follows: month 1-12, day 1-31, weekday 0-6, hour 0-
23, minutes 0-59 and seconds 0-59. If you specify the year, you must do so in both <time1> and
<time2>.

For example, if the time is GMT 2005 May 10 10h 15m 30s, and it is the second Tuesday of the
month, you can specify the following (evaluation results are shown in parentheses):

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1237

NetScaler 12.0

– sys.time.within(GMT 2004, GMT 2006) (TRUE in this example.)

– sys.time.within(GMT 2004 Jan, GMT 2006 Mar) (FALSE, May is not in the range of January
to March.)
– sys.time.within(GMT Feb, GMT) (TRUE, May is in the range of February to December.)
– sys.time.within(GMT Sun_1, GMT Sun_3) (TRUE, the second Tuesday is between the first
Sunday and the third Sunday.)
– sys.time.within(GMT 2005 May 1 10h, GMT May 2005 1 17h) (TRUE in this example.)
– sys.time.within(LOCAL 2005 May 1, LOCAL May 2005 1) (TRUE or FALSE, depending on the
NetScaler system time zone.)

• SYS.TIME.YEAR:

Extracts the year from the current system time and returns that value as a four-digit integer.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Expressions for SSL certificate dates

September 24, 2018

Contributed by:
C

You can determine the validity period for SSL certificates by configuring an expression that contains
the following prefix:

CLIENT.SSL.CLIENT_CERT

The following example expression matches a particular time for expiration with the information in the
certificate:

client.ssl.client_cert.valid_not_after.eq(GMT 2009)

The following table describes time-based operations on SSL certificates. To obtain the expres-
sion you want, replace certificate in the expression in the first column with the prefix expression,
“CLIENT.SSL.CLIENT_CERT”.

• <certificate>.VALID_NOT_AFTER:

Returns the last day before certificate expiration. The return format is the number of seconds
since GMT January 1, 1970 (0 hours, 0 minutes, 0 seconds).

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1238

NetScaler 12.0

• <certificate>.VALID_NOT_AFTER.BETWEEN(<time1>, <time2>):

Returns a Boolean TRUE value if the certificate validity is between the <time1> and <time2> ar-
guments. Both <time1> and <time2> must be fully specified. Following are examples:

GMT 1995 Jan is fully specified.

GMT Jan is not fully specified

GMT 1995 20 is not fully specified.

GMT Jan Mon_2 is not fully specified.

The <time1> and <time2> arguments must be both GMT or both LOCAL, and <time2> must be
greater than <time1>.

For example, if it is GMT 2005 May 1 10h 15m 30s, and the first Sunday of the month, you can
specify the following (evaluation results are in parentheses).

– . . .between(GMT 2004, GMT 2006) (TRUE)

– . . .between(GMT 2004 Jan, GMT 2006 Nov) (TRUE)
– . . .between(GMT 2004 Jan, GMT 2006) (TRUE)
– . . .between(GMT 2005 May Sun_1, GMT 2005 May Sun_3) (TRUE)
– . . .between(GMT 2005 May 1, GMT May 2005 1) (TRUE)
– . . .between(LOCAL 2005 May 1, LOCAL May 2005 1) (TRUE or FALSE, depending on the
NetScaler system time zone.)

• <certificate>.VALID_NOT_AFTER.DAY:

Extracts the last day of the month that the certificate is valid, and returns a number from 1
through 31, as appropriate for the date.

• <certificate>.VALID_NOT_AFTER.EQ(<time>):

Returns a Boolean TRUE if the time is equal to the <time> argument.

For example, if the current time is GMT 2005 May 1 10h 15m 30s, and it is the first Sunday of the
month, you can specify the following (evaluation results for this example are in parentheses):

– . . .eq(GMT 2005) (TRUE)

– . . .eq(GMT 2005 Dec) (FALSE)
– . . .eq(LOCAL 2005 May) (TRUE or FALSE, depending on the current time zone)
– . . .eq(GMT 10h) (TRUE)
– . . .eq(GMT 10h 30s) (TRUE)
– . . .eq(GMT May 10h) (TRUE)
– . . .eq(GMT Sun) (TRUE)
– . . .eq(GMT May Sun_1) (TRUE)

• <certificate>.VALID_NOT_AFTER.GE(<time>):

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1239

NetScaler 12.0

Returns a Boolean TRUE if the time value is greater than or equal to the argument <time>.

For example, if the time value is GMT 2005 May 1 10h 15m 30s, and it is the first Sunday of the
month of May in 2005, you can specify the following (evaluation results for this example are in
parentheses):

– . . .ge(GMT 2004) (TRUE)

– . . .ge(GMT 2005 Jan) (TRUE)
– . . .ge(LOCAL 2005 May) (TRUE or FALSE, depending on the current time zone.)
– . . .ge(GMT 8h) (TRUE)
– . . .ge(GMT 30m) (FALSE)
– . . .ge(GMT May 10h) (TRUE)
– . . .ge(GMT May 10h 0m) (TRUE)
– . . .ge(GMT Sun) (TRUE)
– . . .ge(GMT May Sun_1) (TRUE)

• <certificate>.VALID_NOT_AFTER.GT(<time>):

Returns a Boolean TRUE if the time value is greater than the argument <time>.

For example, if the time value is GMT 2005 May 1 10h 15m 30s, and it is the first Sunday of the
month of May in 2005, you can specify the following (evaluation results for this example are in
parentheses):

– . . .gt(GMT 2004) (TRUE)

– . . .gt(GMT 2005 Jan) (TRUE)
– . . .gt(LOCAL 2005 May) (TRUE or FALSE, depending on the current time zone.)
– . . .gt(GMT 8h) (TRUE)
– . . .gt(GMT 30m) (FALSE)
– . . .gt(GMT May 10h) (FALSE)
– . . .gt(GMT Sun) (FALSE)
– . . .gt(GMT May Sun_1) (FALSE)

• <certificate>.VALID_NOT_AFTER.HOURS:

Extracts the last hour that the certificate is valid and returns that value as an integer from 0 to
23.

• <certificate>.VALID_NOT_AFTER.LE(<time>):

Returns a Boolean TRUE if the time precedes or is equal to the <time> argument.

For example, if the time value is GMT 2005 May 1 10h 15m 30s, and it is the first Sunday of the
month of May in 2005, you can specify the following (evaluation results for this example are in
parentheses):

– . . .le(GMT 2006) (TRUE)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1240

NetScaler 12.0

– . . .le(GMT 2005 Dec) (TRUE)

– . . .le(LOCAL 2005 May) (TRUE or FALSE, depending on the current time zone.)
– . . .le(GMT 8h) (FALSE)
– . . .le(GMT 30m) (TRUE)
– . . .le(GMT May 10h) (TRUE)
– . . .le(GMT Jun 11h) (TRUE)
– . . .le(GMT Wed) (TRUE)
– . . .le(GMT May Sun_1) (TRUE)

• <certificate>.VALID_NOT_AFTER.LT(<time>):

Returns a Boolean TRUE if the time precedes the <time> argument.

For example, if the current time is GMT 2005 May 1 10h 15m 30s, and it is the first Sunday of the
month, you can specify the following:

– . . .lt(GMT 2006) (TRUE)

– . . .lt(GMT 2005 Dec) (TRUE)
– . . .lt(LOCAL 2005 May) (TRUE or FALSE, depending on the current time zone.)
– . . .lt(GMT 8h) (FALSE)
– . . .lt(GMT 30m) (TRUE)
– . . .lt(GMT May 10h) (FALSE)
– . . .lt(GMT Jun 11h) (TRUE)
– . . .lt(GMT Wed) (TRUE)
– . . .lt(GMT May Sun_1) (FALSE)

• <certificate>.VALID_NOT_AFTER.MINUTES:

Extracts the last minute that the certificate is valid and returns that value as an integer from 0
to 59.

• <certificate>.VALID_NOT_AFTER.MONTH:

Extracts the last month that the certificate is valid and returns that value as an integer from 1
(January) to 12 (December).

• <certificate>.VALID_NOT_AFTER.RELATIVE_BOOT:

Calculates the number of seconds to the closest previous or scheduled reboot and returns an
integer. If the closest boot time is in the past, the integer is negative. If it is in the future, the
integer is positive.

• <certificate>.VALID_NOT_AFTER.RELATIVE_NOW;

Calculates the number of seconds between the current system time and the specified time and
returns an integer. If the time is in the past, the integer is negative; if it is in the future, the integer
is positive.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1241

NetScaler 12.0

• <certificate>.VALID_NOT_AFTER.SECONDS:

Extracts the last second that the certificate is valid and returns that value as an integer from 0
to 59.

• <certificate>.VALID_NOT_AFTER.WEEKDAY:

Extracts the last weekday that the certificate is valid. Returns a number between 0 (Sunday) and
6 (Saturday) to give the weekday in the time value.

• <certificate>.VALID_NOT_AFTER.WITHIN(<time1>, <time2>):

Returns a Boolean TRUE if the time lies within all the ranges defined by the elements in <time1>
and <time2>.

If you omit an element of time from <time1>, it is assumed to have the lowest value in its range.
If you omit an element from <time2>, it is assumed to have the highest value of its range. If you
specify a year in <time1>, you must specify it in <time2>.

The ranges for elements of time are as follows: month 1-12, day 1-31, weekday 0-6, hour 0-23,
minutes 0-59 and seconds 0-59. For the result to be TRUE, each element in the time must exist
in the corresponding range that you specify in <time1>, <time2>.

For example, if time is GMT 2005 May 10 10h 15m 30s, and it is the second Tuesday of the month,
you can specify the following (evaluation results are in parentheses):

– . . .within(GMT 2004, GMT 2006) (TRUE)

– . . .within(GMT 2004 Jan, GMT 2006 Mar) (FALSE, May is not in the range of January to
March.)
– . . .within(GMT Feb, GMT) (TRUE, May is in the range for February to December)
– . . .within(GMT Sun_1, GMT Sun_3) (TRUE, the second Tuesday lies within the range of the
first Sunday through the third Sunday)
– . . .within(GMT 2005 May 1 10h, GMT May 2005 1 17h) (TRUE)
– . . .within(LOCAL 2005 May 1, LOCAL May 2005 1) (TRUE or FALSE, depending on the
NetScaler system time zone)

• <certificate>.VALID_NOT_AFTER.YEAR:

Extracts the last year that the certificate is valid and returns a four-digit integer.

• <certificate>.VALID_NOT_BEFORE:

Returns the date that the client certificate becomes valid.

The return format is the number of seconds since GMT January 1, 1970 (0 hours, 0 minutes, 0
seconds).

• <certificate>.VALID_NOT_BEFORE.BETWEEN(<time1>, <time2>):

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1242

NetScaler 12.0

Returns a Boolean TRUE if the time value is between the two time arguments. Both <time1> and
<time2> arguments must be fully specified.

Following are examples:

GMT 1995 Jan is fully specified.

GMT Jan is not fully specified.
GMT 1995 20 is not fully specified.
GMT Jan Mon_2 is not fully specified.
The time arguments must be both GMT or both LOCAL, and <time2> must be greater than
<time1>.

For example, if the time value is GMT 2005 May 1 10h 15m 30s, and it is the first Sunday of the
month of May in 2005, you can specify the following (evaluation results for this example are in
parentheses):

– . . .between(GMT 2004, GMT 2006) (TRUE)

– . . .between(GMT 2004 Jan, GMT 2006 Nov) (TRUE)
– . . .between(GMT 2004 Jan, GMT 2006) (TRUE)
– . . .between(GMT 2005 May Sun_1, GMT 2005 May Sun_3) (TRUE)
– . . .between(GMT 2005 May 1, GMT May 2005 1) (TRUE)
– . . .between(LOCAL 2005 May 1, LOCAL May 2005 1) (TRUE or FALSE, depending on the
NetScaler system time zone.)

• <certificate>.VALID_NOT_BEFORE.DAY:

Extracts the last day of the month that the certificate is valid and returns that value as a number
from 1 through 31 representing that day.

• <certificate>.VALID_NOT_BEFORE.EQ(<time>):

Returns a Boolean TRUE if the time is equal to the <time> argument.

For example, if the time value is GMT 2005 May 1 10h 15m 30s, and it is the first Sunday of the
month of May in 2005, you can specify the following (evaluation results for this example are in
parentheses):

– . . .eq(GMT 2005) (TRUE)

– . . .eq(GMT 2005 Dec) (FALSE)
– . . .eq(LOCAL 2005 May) (TRUE or FALSE, depending on the current time zone.)
– . . .eq(GMT 10h) (TRUE)
– . . .eq(GMT 10h 30s) (TRUE)
– . . .eq(GMT May 10h) (TRUE)
– . . .eq(GMT Sun) (TRUE)
– . . .eq(GMT May Sun_1) (TRUE)

• <certificate>.VALID_NOT_BEFORE.GE(<time>):

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1243

NetScaler 12.0

Returns a Boolean TRUE if the time is greater than (after) or equal to the <time> argument.

For example, if the time value is GMT 2005 May 1 10h 15m 30s, and it is the first Sunday of the
month of May in 2005, you can specify the following (evaluation results are in parentheses):

– . . .ge(GMT 2004) (TRUE)

– . . .ge(GMT 2005 Jan) (TRUE)
– . . .ge(LOCAL 2005 May) (TRUE or FALSE, depending on the current time zone.)
– . . .ge(GMT 8h) (TRUE)
– . . .ge(GMT 30m) (FALSE)
– . . .ge(GMT May 10h) (TRUE)
– . . .ge(GMT May 10h 0m) (TRUE)
– . . .ge(GMT Sun) (TRUE)
– . . .ge(GMT May Sun_1) (TRUE)

• <certificate>.VALID_NOT_BEFORE.GT(<time>):

Returns a Boolean TRUE if the time occurs after the <time> argument.

For example, if the time value is GMT 2005 May 1 10h 15m 30s, and it is the first Sunday of the
month of May in 2005, you can specify the following (evaluation results are in parentheses):

– . . .gt(GMT 2004) (TRUE)

– . . .gt(GMT 2005 Jan) (TRUE)
– . . .gt(LOCAL 2005 May) (TRUE or FALSE, depending on the current time zone.)
– . . .gt(GMT 8h) (TRUE)
– . . .gt(GMT 30m) (FALSE)
– . . .gt(GMT May 10h) (FALSE)
– . . .gt(GMT May 10h 0m) (TRUE)
– . . .gt(GMT Sun) (FALSE)
– . . .gt(GMT May Sun_1) (FALSE)

• <certificate>.VALID_NOT_BEFORE.HOURS:

Extracts the last hour that the certificate is valid and returns that value as an integer from 0 to
23.

• **<certificate>.VALID_NOT_BEFORE.LE(<time>)

Returns a Boolean TRUE if the time precedes or is equal to the <time> argument.

For example, if the time value is GMT 2005 May 1 10h 15m 30s, and it is the first Sunday of the
month of May in 2005, you can specify the following (evaluation results for this example are in
parentheses):

– . . .le(GMT 2006) (TRUE)

– . . .le(GMT 2005 Dec) (TRUE)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1244

NetScaler 12.0

– . . .le(LOCAL 2005 May) (TRUE or FALSE,depending on the current time zone.)

– . . .le(GMT 8h) (FALSE)
. - . .le(GMT 30m) (TRUE)
– . . .le(GMT May 10h) (TRUE)
– . . .le(GMT Jun 11h) (TRUE)
– . . .le(GMT Wed) (TRUE)
– . . .le(GMT May Sun_1) (TRUE)

• <certificate>.VALID_NOT_BEFORE.LT(<time>):

Returns a Boolean TRUE if the time precedes the <time> argument.

For example, if the time value is GMT 2005 May 1 10h 15m 30s, and it is the first Sunday of the
month of May in 2005, you can specify the following (evaluation results for this example are in
parentheses):

– . . .lt(GMT 2006) (TRUE)

– . . .lt(GMT 2005 Dec) (TRUE)
– . . .lt(LOCAL 2005 May) (TRUE or FALSE, depending on the current time zone.)
– . . .lt(GMT 8h) (FALSE)
– . . .lt(GMT 30m) (TRUE)
– . . .lt(GMT May 10h) (FALSE)
– . . .lt(GMT Jun 11h) (TRUE)
– . . .lt(GMT Wed) (TRUE)
– . . .lt(GMT May Sun_1) (FALSE)

• <certificate>.VALID_NOT_BEFORE.MINUTES:

Extracts the last minute that the certificate is valid. Returns the current minute as an integer
from 0 to 59.

• <certificate>.VALID_NOT_BEFORE.MONTH:

Extracts the last month that the certificate is valid. Returns the current month as an integer from
1 (January) to 12 (December).

• <certificate>.VALID_NOT_BEFORE.RELATIVE_BOOT:

Calculates the number of seconds to the closest previous or scheduled NetScaler reboot and
returns an integer. If the closest boot time is in the past, the integer is negative; if it is in the
future, the integer is positive.

• <certificate>.VALID_NOT_BEFORE.RELATIVE_NOW:

Returns the number of seconds between the current NetScaler system time and the specified
time as an integer. If the designated time is in the past, the integer is negative. If it is in the
future, the integer is positive.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1245

NetScaler 12.0

• <certificate>.VALID_NOT_BEFORE.SECONDS:

Extracts the last second that the certificate is valid. Returns the current second as an integer
from 0 to 59.

• <certificate>.VALID_NOT_BEFORE.WEEKDAY:

Extracts the last weekday that the certificate is valid. Returns the weekday as a number between
0 (Sunday) and 6 (Saturday).

• <certificate>.VALID_NOT_BEFORE.WITHIN(<time1>, <time2>):

Returns a Boolean TRUE if each element of time exists within the range defined in the <time1>,
<time2> arguments.

If you omit an element of time from <time1>, it is assumed to have the lowest value in its range.
If you omit an element of time from <time2>, it is assumed to have the highest value in its range.
If you specify a year in <time1>, it must be specified in <time2>. The ranges for elements of time
are as follows: month 1-12, day 1-31, weekday 0-6, hour 0-23, minutes 0-59 and seconds 0-59.

For example, if the time is GMT 2005 May 10 10h 15m 30s, and it is the second Tuesday of the
month, you can specify the following (evaluation results are in parentheses):

– . . .within(GMT 2004, GMT 2006) (TRUE)

– . . .within(GMT 2004 Jan, GMT 2006 Mar) (FALSE, May is not in the range of January to
March.)
– . . .within(GMT Feb, GMT) (TRUE, May is in the range of February to December.)
– . . .within(GMT Sun_1, GMT Sun_3) (TRUE, the second Tuesday is between the first Sunday
and the third Sunday.)
– . . .within(GMT 2005 May 1 10h, GMT May 2005 1 17h) (TRUE)
– . . .within(LOCAL 2005 May 1, LOCAL May 2005 1) (TRUE or FALSE, depending on the
NetScaler system time zone)

• <certificate>.VALID_NOT_BEFORE.YEAR:

Extracts the last year that the certificate is valid. Returns the current year as a four-digit integer.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Expressions for HTTP request and response dates

September 24, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1246

NetScaler 12.0

Contributed by:
C

The following expression prefixes return the contents of the HTTP Date header as text or as a date
object. These values can be evaluated as follows:

• As a number. The numeric value of an HTTP Date header is returned in the form of the number
of seconds since Jan 1, 1970.

For example, the expression http.req.date.mod(86400) returns the number of seconds since
the beginning of the day. These values can be evaluated using the same operations as other
non-date-related numeric data. For more information, see Expression prefixes for numeric data
other than date and time.

• As an HTTP header. Date headers can be evaluated using the same operations as other HTTP
headers.

For more information, see Default syntax expressions: Parsing HTTP, TCP, and UDP data.

• As text. Date headers can be evaluated using the same operations as other strings.

For more information, see Advanced Policy Expressions: Evaluating Text.

Prefix Description

HTTP.REQ.DATE Returns the contents of the HTTP Date header

as text or as a date object. The date formats
recognized are: RFC822. Sun, 06 Jan 1980
08:49:37 GMT, RFC850. Sunday, 06-Jan-80
09:49:37 GMT, and ASCTIME. Sun Jan 6
08:49:37 1980.
HTTP.RES.DATE Returns the contents of the HTTP Date header
as text or as a date object. The date formats
recognized are: RFC822. Sun, 06 Jan 1980
8:49:37 GMT, RFC850. Sunday, 06-Jan-80
9:49:37 GMT, and ASCTIME. Sun Jan 6 08:49:37
1980.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1247

NetScaler 12.0

Generate the day of the week, as a string, in short and long formats

September 24, 2018

Contributed by:
C

The functions, WEEKDAY_STRING_SHORT and WEEKDAY_STRING, generate the day of the week, as a
string, in short and long formats, respectively. The strings that are returned are always in English. The
prefix used with these functions must return the day of the week in integer format and the acceptable
range for the value returned by the prefix is 0-6. Therefore, you can use any prefix that returns an
integer in the acceptable range. An UNDEF condition is raised if the returned value is not in this range
or if memory allocation fails.

Following are the descriptions of the functions:

Function Description

<prefix>.WEEKDAY_STRING_SHORT Returns the day of the week in short format.

The short form is always 3 characters long with
an initial capital and the remaining characters
in lower case. For example,
SYS.TIME.WEEKDAY.WEEKDAY_STRING_SHORT
returns Sun if the value returned by the
WEEKDAY function is 0 and Sat if the value
returned by the prefix is 6.
<prefix>.WEEKDAY_STRING Returns the day of the week in long format.
The long form always has an initial capital,
with the remaining characters in lower case.
For example,
SYS.TIME.WEEKDAY.WEEKDAY_STRING returns
Sunday if the value returned by the WEEKDAY
function is 0 and Saturday if the value returned
by the prefix is 6.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1248

NetScaler 12.0

Expression prefixes for numeric data other than date and time

September 24, 2018

Contributed by:
C

In addition to configuring expressions that operate on time, you can configure expressions for the
following types of numeric data:

• The length of HTTP requests, the number of HTTP headers in a request, and so on.

For more information, see Expressions for numeric HTTP payload data other than dates.

• IP and MAC addresses.

For more information, see Expressions for IP addresses and IP subnets.

• Client and server data in regard to interface IDs and transaction throughput rate.

For more information, see Expressions for numeric client and server data.

• Numeric data in client certificates other than dates.

For information on these prefixes, including the number of days until certificate expiration and
the encryption key size, see Prefixes for numeric data in SSL certificates.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Converting numbers to text

September 24, 2018

Contributed by:
C

The following functions produce binary strings from a number returned by an expression prefix. These
functions are particularly useful in the TCP rewrite feature as replacement strings for binary data. For
more information about the TCP rewrite feature, see Rewrite.

All the functions return a value of type text. The endianness that some of the functions accept as a
parameter is either LITTLE_ENDIAN or BIG_ENDIAN.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1249

NetScaler 12.0

Function Description

<number>.SIGNED8_STRING Produces an 8-bit signed binary string

representing the number. If the value is
out of range, an undef condition is raised. Exam-
ple: HTTP.REQ.BODY(100).GET_SIGNED8(16).SUB(3).SIGNED8_
<number>.UNSIGNED8_STRING Produces an 8-bit unsigned binary string
representing the number. If the value is
out of range, an undef condition is raised. Exam-
ple: HTTP.REQ.BODY(100).GET_UNSIGNED8(31).ADD(3).UNSIG
<number>.SIGNED16_STRING(<endianness>) Produces a 16-bit signed binary string
representing the number. If the value is
out of range, an undef condition is raised. Exam-
ple: HTTP.REQ.BODY(100).SKIP(12).GET_SIGNED16(0,
BIG_ENDIAN).SUB(4).SIGNED16_STRING(BIG_ENDIAN)
<number>.UNSIGNED16_STRING(<endianness>) Produces a 16-bit unsigned binary string
representing the number. If the value is
out of range, an undef condition is raised. Exam-
ple: HTTP.REQ.BODY(100).GET_UNSIGNED16(47,
LIT-
TLE_ENDIAN).ADD(7).UNSIGNED16_STRING(LITTLE_ENDIAN)
<number>.SIGNED32_STRING(<endianness>) Produces a 32-bit signed binary string
representing the number. Exam-
ple: HTTP.REQ.BODY(100).AFTER_STR(“delim”).GET_SIGNED3
BIG_ENDIAN).SUB(1).SIGNED32_STRING(BIG_ENDIAN)
<unsigned_long_number>.UNSIGNED8_STRING Produces an 8-bit unsigned binary string
representing the number. If the value is
out of range, an undef condition is raised. Exam-
ple: HTTP.REQ.BODY(100).GET_UNSIGNED8(24).TYPECAST_UN
<unsigned_long_number>.UNSIGNED16_STRING(<endianness>)
Produces a 16-bit unsigned binary string
representing the number. If the value is
out of range, an undef condition is raised. Exam-
ple: HTTP.REQ.BODY(100).GET_UNSIGNED16(23,
LIT-
TLE_ENDIAN).TYPECAST_UNSIGNED_LONG_AT.ADD(10).UNSIG

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1250

NetScaler 12.0

Function Description

<unsigned_long_number>.UNSIGNED32_STRING(<endianness>)
Produces a 32-bit unsigned binary string
representing the number. If the value is
out of range, an undef condition is raised. Exam-
ple: HTTP.REQ.BODY(100).AFTER_STR(“delim2”).GET_UNSIGN
BIG_ENDIAN).ADD(2).UNSIGNED32_STRING(BIG_ENDIAN)

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Virtual server based expressions

September 24, 2018

Contributed by:
C

The
SYS.VSERVER(“<vserver-name>”) expression prefix enables you to identify a virtual server. You can use
the following functions with this prefix to retrieve information related to the specified virtual server:

• THROUGHPUT. Returns the throughput of the virtual server in Mbps (Megabits per second). The
value returned is an unsigned long number.

Usage: SYS.VSERVER(“vserver”).THROUGHPUT

• CONNECTIONS. Returns the number of connections being managed by the virtual server. The
value returned is an unsigned long number.

Usage: SYS.VSERVER(“vserver”).CONNECTIONS

• STATE. Returns the state of the virtual server. The value returned is UP, DOWN, or
OUT_OF_SERVICE. One of these values can therefore be passed as an argument to the
EQ() operator to perform a comparison that results in a Boolean TRUE or FALSE.

Usage: SYS.VSERVER(“vserver”).STATE

• HEALTH. Returns the percentage of services in an UP state for the specified virtual server. The
value returned is an integer.

Usage: SYS.VSERVER(“vserver”).HEALTH

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1251

NetScaler 12.0

• RESPTIME. Returns the response time as an integer representing the number of microseconds.
Response time is the average TTFB (Time To First Byte) from all the services bound to the virtual
server.

Usage: SYS.VSERVER(“vserver”).RESPTIME

• SURGECOUNT. Returns the number of requests in the surge queue of the virtual server. The
value returned is an integer.

Usage: SYS.VSERVER(“vserver”).SURGECOUNT

Example 1:

The following rewrite policy aborts rewrite processing if the number of connections at the load bal-
ancing virtual server LBvserver exceeds 10000:

add rewrite policy norewrite_pol sys.vserver(”LBvserver”).connections.gt

(10000)norewrite

Example 2:

The following rewrite action inserts a custom header, TP, whose value is the throughout at the virtual
server LBvserver:

add rewrite action tp_header insert_http_header TP SYS.VSERVER(”LBvserver”)

.THROUGHPUT

Example 3:

The following audit log message action writes the average TTFB of the services bound to a virtual
server, to the newnslog log file:

add audit messageaction log_vserver_resptime_act INFORMATIONAL ”\”NS

Response Time to Servers:\” + sys.vserver(\”ssllb\”).resptime + \” millisec
\””-logtoNewnslog YES -bypassSafetyCheck YES

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Advanced policy expressions: Parsing HTTP, TCP, and UDP data

September 24, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1252

NetScaler 12.0

You can configure Advanced policy expressions to evaluate and process the payload in HTTP requests
and responses. The payload associated with an HTTP connection includes the various HTTP headers
(both standard and custom headers), the body, and other connection information such as the URL.
Additionally, you can evaluate and process the payload in a TCP or UDP packet. For HTTP connec-
tions, for example, you can check whether a particular HTTP header is present or if the URL includes
a particular query parameter.

You can configure expressions to transform the URL encoding and apply HTML or XML “safe” coding
for subsequent evaluation. You can also use XPATH and JSON prefixes to evaluate date in XML and
JSON files, respectively.

You can also use text-based and numeric Advanced policy expressions to evaluate HTTP request and
response data. For more information, see Advanced policy expressions: Evaluating text. and Default
Syntax Expressions: Working with Dates, Times, and Numbers.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

About evaluating HTTP and TCP payload

September 24, 2018

Contributed by:
C

The payload of an HTTP request or response consists of HTTP protocol information such as headers,
a URL, body content, and version and status information. When you configure a default syntax ex-
pression to evaluate HTTP payload, you use a default syntax expression prefix and, if necessary, an
operator.

For example, you use the following expression, which includes the http.req.header(“<header_name>“)
prefix and the exists operator, if you want to determine whether an HTTP connection includes a
custom header named “myHeader”:

http.req.header(”myHeader”).exists

You can also combine multiple Advanced policy expressions with Boolean and arithmetic operators.
For example, the following compound expression could be useful with various NetScaler features,
such as Integrated Caching, Rewrite, and Responder. This expression first uses the && Boolean op-
erator to determine whether an HTTP connection includes the Content-Type header with a value of

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1253

NetScaler 12.0

“text/html.” If that operation returns a value of FALSE, the expression determines whether the HTTP
connection includes a “Transfer-Encoding” or “Content-Length” header.
(http.req.header(”Content-Type”).exists && http.req.header(”Content-Type”)
.eq(”text/html”))|| (http.req.header(”Transfer-Encoding”).exists)|| (http.
req.header(”Content-Length”).exists)

The payload of a TCP or UDP packet is the data portion of the packet. You can configure Advanced
policy expressions to examine features of a TCP or UDP packet, including the following:
• Source and destination domains
• Source and destination ports
• The text in the payload
• Record types
The following expression prefixes extract text from the body of the payload:
• HTTP.REQ.BODY(integer). Returns the body of an HTTP request as a multiline text object, up to
the character position designated in the integer argument. If there are fewer characters in the
body than is specified in the argument, the entire body is returned.
• HTTP.RES.BODY(integer). Returns a portion of the HTTP response body. The length of the re-
turned text is equal to the number in the integer argument. If there are fewer characters in the
body than is specified in integer, the entire body is returned.
• CLIENT.TCP.PAYLOAD(integer). Returns TCP payload data as a string, starting with the first char-
acter in the payload and continuing for the number of characters in the integer argument.
Following is an example that evaluates to TRUE if a response body of 1024 bytes contains the string
“https”, and this string occurs after the string “start string” and before the string “end string”:
http.res.body(1024).after_str(”start_string”).before_str(”end_string”).
contains(”https”)

Note: You can apply any text operation to the payload body. For information on operations that you
can apply to text, see
Advanced policy expressions: Evaluating text.
1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Expressions for identifying the protocol in an incoming IP packet

September 24, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1254

NetScaler 12.0

Contributed by:
C

The following table lists the expressions that you can use to identify the protocol in an incoming
packet.

Expression Description

CLIENT.IP.PROTOCOL Identifies the protocol in IPv4 packets sent by

clients.
CLIENT.IPV6.PROTOCOL Identifies the protocol in IPv6 packets sent by
clients.
SERVER.IP.PROTOCOL Identifies the protocol in IPv4 packets sent by
servers.
SERVER.IPV6.PROTOCOL Identifies the protocol in IPv6 packets sent by
servers.

Arguments to the PROTOCOL function

You can pass the Internet Assigned Numbers Authority (IANA) protocol number to the PROTOCOL func-
tion. For example, if you want to determine whether the protocol in an incoming packet is TCP, you
can use CLIENT.IP.PROTOCOL.EQ(6), where 6 is the IANA-assigned protocol number for TCP. For some
protocols, you can pass an enumeration value instead of the protocol number. For example, instead
of CLIENT.IP.PROTOCOL.EQ(6), you can use CLIENT.IP.PROTOCOL.EQ(TCP). The following table lists
the protocols for which you can use enumeration values, and the corresponding enumeration values
for use with the PROTOCOL function.

Protocol Enumeration value

Transmission Control Protocol (TCP) TCP

User Datagram Protocol (UDP) UDP
Internet Control Message Protocol (ICMP) ICMP
IP Authentication Header (AH), for providing AH
authentication services in IPv4 and IPv6
Encapsulating Security Payload (ESP) protocol ESP
General Routing Encapsulation (GRE) GRE
IP-within-IP Encapsulation Protocol IPIP

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1255

NetScaler 12.0

Protocol Enumeration value

Internet Control Message Protocol for IPv6 ICMPv6

(ICMPv6)
Fragment Header for IPv6 FRAGMENT

Use case scenarios

The protocol expressions can be used in both request-based and response-based policies. You can
use the expressions in various NetScaler features, such as load balancing, WAN optimization, content
switching, rewrite, and listen policies. You can use the expressions with functions such as EQ() and
NE(), to identify the protocol in a policy and perform an action.

Following are some use cases for the expressions:

• In Branch Repeater load balancing configurations, you can use the expressions in a listen policy
for the wildcard virtual server. For example, you can configure the wildcard virtual server with
the listen policy CLIENT.IP.PROTOCOL.EQ(TCP) so that the virtual server processes only TCP traf-
fic and simply bridges all non-TCP traffic. Even though you can use an Access Control List instead
of the listen policy, the listen policy provides better control over what traffic is processed.
• For content switching virtual servers of type ANY, you can configure content switching policies
that switch requests on the basis of the protocol in incoming packets. For example, you can
configure content switching policies to direct all TCP traffic to one load balancing virtual server
and all non-TCP traffic to another load balancing virtual server.
• You can use the client-based expressions to configure persistence based on the protocol. For ex-
ample, you can use CLIENT.IP.PROTOCOL to configure persistence on the basis of the protocols
in incoming IPv4 packets.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Expressions for HTTP and cache-control headers

September 24, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1256

NetScaler 12.0

One common method of evaluating HTTP traffic is to examine the headers in a request or a response.
A header can perform a number of functions, including the following:

• Provide cookies that contain data about the sender.

• Identify the type of data that is being transmitted.
• Identify the route that the data has traveled (the Via header).

Note

If an operation is used to evaluate both header and text data, the header-based operation always
overrides the text-based operation. For example, the AFTER_STR operation, when applied to a
header, overrides text-based AFTER_STR operations for all instances of the current header type.

Prefixes for HTTP headers

The following table describes expression prefixes that extract HTTP headers.

HTTP Header Prefix Description

HTTP.REQ.HEADER(“”) Returns the contents

of the HTTP header
specified by the
argument. The
header name cannot
exceed 32 characters.
Note that this prefix
returns the value
from the Host header
by default. To use this
value as a hostname
you need to typecast
it as fol-
lows: http.req.header(”host”).typecast_http_hostname_t. For
more information on
typecasting, see
[Typecasting
data](/en-
us/netscaler/12/appexpert/policies-
and-expressions/ns-
typecasting-data-
wrapper-con.html).

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1257

NetScaler 12.0

HTTP Header Prefix Description

HTTP.REQ.FULL_HEADERReturns the contents

of the complete set of
HTTP header fields
including the request
line (for example,
“GET /brochures/in-
dex.html HTTP/1.1”)
and the terminat-
ing \r\n\r\n sequence.
HTTP.REQ.DATE Returns the contents
of the HTTP Date
header. The following
date formats are
recognized: RFC822.
Sun, 06 Jan 1980
8:49:37 GMT, RFC850.
Sunday, 06-Jan-80
9:49:37 GMT, ASCII
TIME. Sun Jan 6
08:49:37 1980. To
evaluate a Date
header as a date
object, see Default
Syntax Expressions:
Working with Dates,
Times, and Numbers.
HTTP.REQ.COOKIE (Name/Value List)
Returns the contents
of the HTTP Cookie
header.
HTTP.REQ.TXID Returns the HTTP
transaction ID. The
value is a function of
an internal
transaction number,
system boot time and
system MAC address.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1258

NetScaler 12.0

HTTP Header Prefix Description

HTTP.RES.HEADER(“”) Returns the contents

of the HTTP header
specified by the
argument. The
header name cannot
exceed 32 characters.
HTTP.RES.FULL_HEADERReturns the contents
of the complete set of
HTTP header fields
including the status
line (for example,
“HTTP/1.1 200 OK”)
and the terminat-
ing \r\n\r\n sequence.
HTTP.RES.SET_COOKIE orReturns
HTTP.RES.SET_COOKIE2
the HTTP
Set-Cookie header
object in a response.
HTTP.RES.SET_COOKIE(<name>)
Returns the
or HTTP.RES.SET_COOKIE2(<name>)
cookie of
the specified name if
it is present. If it is not
present, returns a text
object of length 0.
Returns UNDEF if
more than 15
Set-Cookie headers
are present and the
specified cookie was
not found in these
headers.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1259

NetScaler 12.0

HTTP Header Prefix Description

HTTP.RES.SET_COOKIE(<name>).DOMAIN
Returns the valueorofHTTP.RES.SET_COOKIE2(<name>).DOMAIN
the first Domain field
in the cookie. For
example, if the cookie
is Set-Cookie :
Customer = “ABC”;
DOMAIN=”.abc.com”;
DOMAIN=.xyz.com,
the follow-
ing expression returns
.abc.com: http.res.set_cookie.cookie(“customer”).domain. A
string of zero length is
returned if the
Domain field or its
value is absent.
HTTP.RES.SET_COOKIE.EXISTS(<name>)
Returns a Boolean or HTTP.RES.SET_COOKIE2.EXISTS(<name>)
TRUE if a Cookie with
the name specified in
the <name>
argument exists in the
Set-Cookie header.
This prefix returns
UNDEF if more than
15 Set-Cookie headers
are present and the
named cookie is not
in the first 15 headers.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1260

NetScaler 12.0

HTTP Header Prefix Description

HTTP.RES.SET_COOKIE.COOKIE(<name>).EXPIRES
Returns the Expires or HTTP.RES.SET_COOKIE2.COOKIE(<name>).EXPIRES
field of the cookie.
This is a date string
that can be evaluated
as a number, as a
time object, or as text.
If multiple Expires
fields are present, the
first one is returned.
If the Expires field is
absent, a text object
of length zero is
returned. To evaluate
the returned value as
a time object, see
Default Syntax
Expressions: Working
with Dates, Times,
and Numbers.
HTTP.RES.SET_COOKIE.COOKIE(<name>).PATH
PATH.GET(n)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1261

NetScaler 12.0

HTTP Header Prefix Description

o PATH.GET(n) Returns the value of

HTTP.RES.SET_COOKIE2.COOKIE(<name>).PATH Path field of the
cookie as a slash-
(“/”) separated list.
Multiple instances of
a slash are treated as
single slash. If
multiple Path fields
are present, the value
of the first instance is
returned. For
example, the
following is a cookie
with two path
fields:Set-Cookie :
Customer = “ABC”;
PATH=”/a//b/c”;
PATH= “/x/y/z”. The
following expression
returns /a//b/c from
this
cookie: http.res.set_cookie.cookie(“Customer”).path. The
follow-
ing expression returns
b: http.res.set_cookie.cookie(“Customer”).path.get(2). Quotes
are stripped from the
returned value. A
string of zero length is
returned if the Path
field or its value is
absent.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1262

NetScaler 12.0

HTTP Header Prefix Description

HTTP.RES.SET_COOKIE.COOKIE(<name>).PATH.IGNORE_EMPTY_ELEMENTS
Ignores the empty or HTTP.RES.SET_COOKIE2.COOKIE
elements in the list.
For example, in the
list a=10,b=11, ,c=89,
the element delimiter
in the list is , and the
list has an empty
element following
a=10. The element
following b=11 is not
considered an empty
element. As another
example, in the
following expression,
if a request contains
Cust_Header : 123„24,
,15 the following
expression returns a
value of
4: http.req.header(“Cust_Header”).typecast_list_t(‘,’).ignore_empty_elements.count. T
following expression
returns a value of
5: http.req.header(“Cust_Header”).typecast_list_t(‘,’).count

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1263

NetScaler 12.0

HTTP Header Prefix Description

HTTP.RES.SET_COOKIE.COOKIE(<name>).PORT
Returns the value of or HTTP.RES.SET_COOKIE2.COOKIE(<name>).PORT
Port field of the
cookie. Operate as a
comma-separated
list. For example, the
following expression
returns 80. 2580 from
Set-Cookie :
Customer = “ABC”;
PATH=”/a/b/c”;
PORT= “80,
2580”: http.res.set_cookie.cookie(“ABC”).port. A
string of zero length is
returned if the Port
field or value is
absent.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1264

NetScaler 12.0

HTTP Header Prefix Description

HTTP.RES.SET_COOKIE.COOKIE(<name>).PORT.IGNORE_EMPTY_ELEMENTS
Ignores the empty or HTTP.RES.SET_COOKIE2.COOKIE
elements in the list.
For example, in the
list a=10,b=11, ,c=89,
the element delimiter
in the list is , and the
list has an empty
element following
a=10. The element
following b=11 is not
considered an empty
element.As another
example, in the
following expression,
if a request contains
Cust_Header : 123„24,
,15 the following
expression returns a
value of
4: http.req.header(“Cust_Header”).typecast_list_t(‘,’).ignore_empty_elements.count. T
following expression
returns a value of
5: http.req.header(“Cust_Header”).typecast_list_t(‘,’).count

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1265

NetScaler 12.0

HTTP Header Prefix Description

HTTP.RES.SET_COOKIE.COOKIE(<name>).VERSION
Returns the value of or HTTP.RES.SET_COOKIE2.COOKIE(<name>).VERSION
the first Version field
in the cookie as a
decimal integer. For
example, the
following expression
returns 1 from the
cookie Set-Cookie :
Customer = “ABC”;
VERSION = “1”;
VERSION =
“0”: http.res.set_cookie.cookie(“CUSTOMER”).version. A
zero is returned if the
Version field or its
value is absent or if
the value is not a
decimal number.
HTTP.RES.SET_COOKIE.COOKIE(<name>,
Returns the nth
<integer>) or HTTP.RES.SET_COOKIE2.COOKIE(<name>,
instance (0-based) of
<integer>) the cookie with the
specified name. If the
cookie is absent,
returns a text object
of length 0. Returns
UNDEF if more than
15 Set-Cookie headers
are present and the
cookie is not found.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1266

NetScaler 12.0

HTTP Header Prefix Description

HTTP.RES.SET_COOKIE.COOKIE(<name>,
Returns the value of
<integer>).DOMAIN or HTTP.RES.SET_COOKIE2.COOKIE(<name>,
the Domain field of
<integer>).DOMAIN the first cookie with
the specified name.
For example, the
following expression
returns a value of
abc.com from the
cookie Set-Cookie :
Customer = “ABC”;
DOMAIN=”.abc.com”;
DO-
MAIN=.xyz.com: http.res.set_cookie.cookie(“CUSTOMER”).domain. A
string of zero length is
returned if the
Domain field or its
value is absent.
HTTP.RES.SET_COOKIE.COOKIE(<name>,
Returns the nth
<integer>).EXPIRES or HTTP.RES.SET_COOKIE2.COOKIE(<name>,
instance (0-based) of
<integer>).EXPIRES the Expires field of
the cookie with the
specified name as a
date string. The value
can be operated upon
as a time object that
supports a number of
date formats. If the
Expires attribute is
absent a string of
length zero is
returned.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1267

NetScaler 12.0

HTTP Header Prefix Description

HTTP.RES.SET_COOKIE.COOKIE(<name>,
PATH.GET(i) or HTTP.RES.SET_COOKIE2.COOKIE(<name>,
PATH.GET(i) Returns the value of
<integer>).PATH <integer>).PATH the Path field of the
nth cookie, as a ‘/’
separated list.
Multiple /s are treated
as a single /. For
example, the
following expression
returns /a//b/c from
the cookie Set-Cookie
: Customer = “ABC”;
PATH=”/a//b/c”;
PATH= ”/x/y/z”: http.res.set_cookie.co
following returns
b: http.res.set_cookie.cookie(“CUSTO
string of zero length is
returned if the Path
field or its value is
absent.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1268

NetScaler 12.0

HTTP Header Prefix Description

HTTP.RES.SET_COOKIE.COOKIE(<name>,
Ignores the empty
<integer>).PATH.IGNORE_EMPTY_ELEMENTS
elements in the list. or HTTP.RES.SET_COOKIE2.COOKIE(<name>,
<integer>).PATH.IGNORE_EMPTY_ELEMENTS
For example, in the
list a=10,b=11, ,c=89,
the element delimiter
in the list is , and the
list has an empty
element following
a=10. The element
following b=11 is not
considered an empty
element. As another
example, in the
following expression,
if a request contains
Cust_Header : 123„24,
,15 the following
expression returns a
value of
4: http.req.header(“Cust_Header”).typecast_list_t(‘,’).ignore_empty_elements.count. T
following expression
returns a value of
5: http.req.header(“Cust_Header”).typecast_list_t(‘,’).count

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1269

NetScaler 12.0

HTTP Header Prefix Description

HTTP.RES.SET_COOKIE.COOKIE(<name>,
Returns the value or
<integer>).PORT or HTTP.RES.SET_COOKIE2.COOKIE(<name>,
values of the Port
<integer>).PORT field of the named
cookie as a ‘,’
separated list. For
example, the
following expression
returns 80, 2580 from
the cookie Set-Cookie
: Customer = “ABC”;
PATH=”/a/b/c”;
PORT= “80,
2580”: http.res.set_cookie.cookie(“ABC”).port. A
string of zero length is
returned if the Port
field or its value is
absent.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1270

NetScaler 12.0

HTTP Header Prefix Description

HTTP.RES.SET_COOKIE.COOKIE(<name>,
Ignores the empty
<integer>).PORT.IGNORE_EMPTY_ELEMENTS
elements in the list. or HTTP.RES.SET_COOKIE2.COOKIE(<name>,
<integer>).PORT.IGNORE_EMPTY_ELEMENTS
For example, in the
list a=10,b=11, ,c=89,
the element delimiter
in the list is , and the
list has an empty
element following
a=10. The element
following b=11 is not
considered an empty
element. As another
example, in the
following expression,
if a request contains
Cust_Header : 123„24,
,15 the following
expression returns a
value of
4: http.req.header(“Cust_Header”).typecast_list_t(‘,’).ignore_empty_elements.count. T
following expression
returns a value of
5: http.req.header(“Cust_Header”).typecast_list_t(‘,’).count
HTTP.RES.SET_COOKIE.COOKIE(<name>,
Returns the value of
<integer>).VERSION or HTTP.RES.SET_COOKIE2.COOKIE(<name>,
Version field of
<integer>).VERSION the nth cookie as a
decimal integer. A
string of zero length is
returned if the Port
field or its value is
absent.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1271

NetScaler 12.0

HTTP Header Prefix Description

HTTP.RES.TXID Returns the HTTP

transaction ID. The
value is a function of
an internal
transaction number,
system boot time and
system MAC address.

Operations for HTTP headers

The following table describes operations that you can specify with the prefixes for HTTP headers.

HTTP Header Operation Description

http header .EXISTS Returns a Boolean TRUE if an instance of the

specified header type exists. Following is an
example: http.req.header(“Cache-
Control”).exists
http header.CONTAINS” http Returns a Boolean TRUE if the <string>
header.CONTAINS(<string>) argument appears in any instance of the
header value. Note: This operation overrides
any text-based Contains operations on all
instances of the current header type.
http header .COUNT Returns the number of headers in a request or
response, to a maximum of 15 headers of the
same type. The result is undefined if there are
more than 15 instances of the header.
http header.AFTER_STR(<string>) Extracts the text that follows the first
occurrence of the <string> argument. The
headers are evaluated from the last instance to
the first.
http header.BEFORE_STR(<string>) Extracts the text that appears prior to the first
occurrence of the input <string> argument.
The headers are evaluated from the last
instance to the first.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1272

NetScaler 12.0

HTTP Header Operation Description

http header.INSTANCE(<instance number>) An HTTP header can occur multiple times in a

request or a response. This operation returns
the header that occurs <instance number> of
places before the final instance. For example,
instance(0) selects the last instance of the
current type, instance(1) selects the
next-to-last instance, and so on. This prefix
cannot be used in bidirectional policies.
http header.SUBSTR(<string>) Extracts the text that matches the <string>
argument. The headers are evaluated from the
last instance to the first.
http header.VALUE(<instance number>) An HTTP header can occur multiple times in a
request or a response. VALUE(0) selects the
value in the last instance, VALUE(1) selects the
value in the next-to-last instance, and so on.
The <instance number> argument cannot
exceed 14.

Prefixes for cache-control headers

The following prefixes apply specifically to Cache-Control headers.

HTTP Header Prefix Description

HTTP.REQ.CACHE_CONTROL Returns a Cache-Control header in an HTTP

request.
HTTP.RES.CACHE_CONTROL Returns a Cache-Control header in an HTTP
response.

Operations for cache-control headers

You can apply any of the operations for HTTP headers to Cache-Control headers. For more informa-
tion, see Operations for HTTP headers.
In addition, the following operations identify specific types of Cache-Control headers. See RFC 2616
for information about these header types.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1273

NetScaler 12.0

HTTP Header Operation Description

Cache-Control header.NAME(<integer>) Returns as a text value the name of the

Cache-Control header that corresponds to the
nth component in a name-value list, as
specified by <integer>. The index of the
name-value component is 0-based. If the
<integer> that is specified by the integer
argument is greater than the number of
components in the list, a zero-length text
object is returned. Following is an exam-
ple: http.req.cache_control.name(3).contains(“some_text”)
Cache-Control header.IS_INVALID Returns a Boolean TRUE if the Cache-Control
header is not present in the request or
response. Following is an
example: http.req.cache_control.is_invalid
Cache-Control header.IS_PRIVATE Returns a Boolean TRUE if the Cache-Control
header has the value Private. Following is an
example: http.req.cache_control.is_private
Cache-Control header.IS_PUBLIC Returns a Boolean TRUE if the Cache-Control
header has the value Private. Following is an
example: http.req.cache_control.is_public
Cache-Control header.IS_NO_STORE Returns a Boolean TRUE if the Cache-Control
header has the value No-Store. Following is an
example: http.req.cache_control.is_no_store
Cache-Control header.IS_NO_CACHE Returns a Boolean TRUE if the Cache-Control
header has the value No-Cache. Following is an
example: http.req.cache_control.is_no_cache
Cache-Control header.IS_MAX_AGE Returns a Boolean TRUE if the Cache-Control
header has the value Max-Age. Following is an
example: http.req.cache_control.is_max_age
Cache-Control header.IS_MIN_FRESH Returns a Boolean TRUE if the Cache-Control
header has the value Min-Fresh. Following is an
example: http.req.cache_control.is_min_fresh
Cache-Control header.IS_MAX_STALE Returns a Boolean TRUE if the Cache-Control
header has the value Max-Stale. Following is an
example: http.req.cache_control.is_max_stale

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1274

NetScaler 12.0

HTTP Header Operation Description

Cache-Control header.IS_MUST_REVALIDATE Returns a Boolean TRUE if the Cache-Control

header has the value Must-Revalidate.
Following is an exam-
ple: http.req.cache_control.is_must_revalidate
Cache-Control header.IS_NO_TRANSFORM Returns a Boolean TRUE if the Cache-Control
header has the value No-Transform. Following
is an exam-
ple: http.req.cache_control.is_no_transform
Cache-Control header.IS_ONLY_IF_CACHED Returns a Boolean TRUE if the Cache-Control
header has the value Only-If-Cached.
Following is an exam-
ple: http.req.cache_control.is_only_if_cached
Cache-Control header.IS_PROXY_REVALIDATE Returns a Boolean TRUE if the Cache-Control
header has the value Proxy-Revalidate.
Following is an exam-
ple: http.req.cache_control.is_proxy_revalidate
Cache-Control header.IS_S_MAXAGE Returns a Boolean TRUE if the Cache-Control
header has the value S-Maxage. Following is an
example: http.req.cache_control.is_s_maxage
Cache-Control header.IS_UNKNOWN Returns a Boolean TRUE if the Cache-Control
header is of an unknown type. Following is an
example: http.req.cache_control.is_unknown
Cache-Control header.MAX_AGE Returns the value of the Cache-Control header
Max-Age. If this header is absent or invalid, 0 is
returned. Following is an exam-
ple: http.req.cache_control.max_age.le(3)
Cache-Control header.MAX_STALE Returns the value of the Cache-Control header
Max-Stale. If this header is absent or invalid, 0
is returned. Following is an exam-
ple: http.req.cache_control.max_stale.le(3)
Cache-Control header.MIN_FRESH Returns the value of the Cache-Control header
Min-Fresh. If this header is absent or invalid, 0
is returned. Following is an exam-
ple: http.req.cache_control.min_fresh.le(3)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1275

NetScaler 12.0

HTTP Header Operation Description

Cache-Control header.S_MAXAGE Returns the value of the Cache-Control header

S-Maxage. If this header is absent or invalid, 0
is returned.Following is an exam-
ple: http.req.cache_control.s_maxage.eq(2)

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Expressions for extracting segments of URLs

November 5, 2018

Contributed by:
C

You can extract URLs and portions of URLs, such as the host name, or a segment of the URL path.
For example, the following expression identifies HTTP requests for image files by extracting image file
suffixes from the URL:

http.req.url.suffix.eq(”jpeg”)|| http.req.url.suffix.eq(”gif”)

Most expressions for URLs operate on text and are described in Expression Prefixes for Text in HTTP
Requests and Responses. This section discusses the GET operation. The GET operation extracts text
when used with the following prefixes:

• HTTP.REQ.URL.PATH
• VPN.BASEURL.PATH
• VPN.CLIENTLESS_BASEURL.PATH

The following table describes prefixes for HTTP URLs.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1276

NetScaler 12.0

URL Prefix Description

HTTP.REQ.URL.PATH.GET(<n>) Returns a slash- (“/”) separated list from the

URL path. For example, consider the following
URL: http://www.mycompany.com/dir1/
dir2/dir3/index.html?a=1. The following
expression returns dir1 from this
URL: <http.req.url.path.get(1)>. The following
expression returns
dir2: http.req.url.path.get(2)
HTTP.REQ.URL.PATH.GET_REVERSE(<n>) Returns a slash- (“/”) separated list from the
URL path, starting from the end of the path.
For example, consider the following
URL: http://www.mycompany.com/dir1/
dir2/dir3/index.html?a=1. The following
expression returns index.html from this
URL: <http.req.url.path.get_reverse(0)>. The
following expression returns
dir3: http.req.url.path.get_reverse(1)

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Expressions for HTTP status codes and numeric HTTP payload data
other than dates

September 24, 2018

Contributed by:
C

The following table describes prefixes for numeric values in HTTP data other than dates.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1277

NetScaler 12.0

Prefix Description

HTTP.REQ.CONTENT_LENGTH Returns the length of an HTTP request as a

number. Following is an
example: http.req.content_length < 500
HTTP.RES.CONTENT_LENGTH Returns the length of the HTTP response as a
number. Following is an
example: http.res.content_length <= 1000
HTTP.RES.STATUS Returns the response status code
HTTP.RES.IS_REDIRECT Returns a Boolean TRUE if the response code is
associated with a redirect. Following are the
redirect response codes: 300 (Multiple
Choices), 301 (Moved
Permanently), 302 (Found), 303 (See
Other), 305 (Use Proxy), and 307 (Temporary
Redirect). Note: Status code 304 is not
considered a redirect HTTP response status
code. Status code 306 is unused.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

SIP expressions

September 24, 2018

Contributed by:
C

The NetScaler Advanced policy expressions language contains a number of expressions that operate
on Session Initiation Protocol (SIP) connections. These expressions are intended to be used in policies
for any supported protocol that operates on a request/response basis. These expressions can be used
in content switching, rate limiting, responder, and rewrite policies.

Certain limitations apply to SIP expressions used with responder policies. Only the DROP, NOOP or
RESPONDWITH actions are allowed on a SIP load balancing virtual server. Responder policies can be

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1278

NetScaler 12.0

bound to a load balancing virtual server, an override global bind point, a default global bind point, or
a sip_udp policy label.

The header format used by the SIP protocol is similar to that used by the HTTP protocol, so many of
the new expressions look and function much like their HTTP analogs. Each SIP header consists of a
line that includes the SIP method, the URL, and the version, followed by a series of name-value pairs
that look like HTTP headers.

Following is a sample SIP header that is referred to in the expressions tables beneath it:

1 INVITE sip:[email protected]:5060;transport=udp SIP/2.0

2 Record-Route: <sip:200.200.100.22;lr=on>
3 Via: SIP/2.0/UDP 200.200.100.22;branch=z9hG4bK444b.c8e103d1.0;rport
=5060;
4 received=10.102.84.18
5 Via: SIP/2.0/UDP 10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060;
6 received=10.102.84.160
7 From: ”12” <sip:12@sip_example.com>;tag=00127f54ec85a6d90cc14f45-53
cc0185
8 To: ”16” <sip:16@sip_example.com>;tag=00127f54ec85a6d90cc14f45-53cc0185
9 Call-ID: [email protected]
10 Max-Forwards: 69CSeq: 101 INVITE
11 User-Agent: Cisco-CP7940G/8.0
12 Contact: <sip:[email protected]:5060;transport=udp>
13 Expires: 180
14 Accept: application/sdp
15 Allow: ACK,BYE,CANCEL,INVITE,NOTIFY,OPTIONS,REFER,REGISTER,UPDATE
16 Supported: replaces,join,norefersub
17 Content-Length: 277
18 Content-Type: application/sdp
19 Content-Disposition: session;handling=optiona

SIP reference tables

The following tables contain lists of expressions that operate on SIP headers. The first table contains
expressions that apply to request headers. Most response-based expressions are nearly the same as
the corresponding request-based expressions. To create a response expression from the correspond-
ing request expression, you change the first two sections of the expression from SIP.REQ to SIP.RES,
and make other obvious adjustments. The second table contains those response expressions that are
unique to responses and have no request equivalents. You can use any element in the following tables
as a complete expression on its own, or you can use various operators to combine these expression
elements with others to form more complex expressions.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1279

NetScaler 12.0

SIP request expressions

Expression Description

SIP.REQ.METHOD Operates on the method of the SIP request.

The supported SIP request methods are ACK,
BYE, CANCEL, INFO, INVITE, MESSAGE, NOTIFY,
OPTIONS, PRACK, PUBLISH, REFER, REGISTER,
SUBSCRIBE, and UPDATE. This expression is a
derivative of the text class, so all operations
that are applicable to text are applicable to this
method. For example, for a SIP request
of INVITE
sip:[email protected]:5060;transport=udp
SIP/2.0, this expression returns INVITE.
SIP.REQ.URL Operates on the SIP request URL. This
expression is a derivative of the text class, so
all operations that are applicable to text are
applicable to this method. For example, for a
SIP request of INVITE
sip:[email protected]:5060;transport=udp
SIP/2.0, this expression re-
turnssip:[email protected]:5060;transport=udp.
SIP.REQ.URL.PROTOCOL Returns the URL protocol. For example, for a
SIP URL
ofsip:[email protected]:5060;transport=udp,
this expression returns sip.
SIP.REQ.URL.HOSTNAME Returns the hostname portion of the SIP URL.
For example, for a SIP URL
ofsip:[email protected]:5060;transport=udp,
this expression returns www.sip.com:5060.
SIP.REQ.URL.HOSTNAME.PORT Returns the port portion of the SIP URL
hostname. If no port is specified, this
expression returns the default SIP port, 5060.
For example, for a SIP hostname
of www.sip.com:5060, this expression
returns 5060.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1280

NetScaler 12.0

Expression Description

SIP.REQ.URL.HOSTNAME.DOMAIN Returns the domain name portion of the SIP

URL hostname. If the host is an IP address,
then this expression returns an incorrect
result. For example, for a SIP hostname
of www.sip.com:5060, this expression
returns sip.com. For a SIP hostname
of 192.168.43.15:5060, this expression returns
an error.
SIP.REQ.URL.HOSTNAME.SERVER Returns the server portion of the host. For
example, for a SIP hostname
of www.sip.com:5060, this expression
returns www.
SIP.REQ.URL.USERNAME Returns the username that precedes the @
character. For example, for a SIP URL of
sip:[email protected]:5060;transport=udp, this
expression returns 16.
SIP.REQ.VERSION Returns the SIP version number in the request.
For example, for a SIP request of INVITE
sip:[email protected]:5060;transport=udp
SIP/2.0, this expression returns SIP/2.0.
SIP.REQ.VERSION.MAJOR Returns the major version number (the
number to the left of the period). For example,
for a SIP version number of SIP/2.0, this
expression returns 2.
SIP.REQ.VERSION.MINOR Returns the minor version number (the
number to the right of the period). For
example, for a SIP version number of SIP/2.0,
this expression returns 0.
SIP.REQ.CONTENT_LENGTH Returns the contents of the Content-Length
header. This expression is a derivative of
thesip_header_t class, so all operations that
are available for SIP headers can be used. For
example, for a SIP Content-Length header
of Content-Length: 277, this expression
returns 277.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1281

NetScaler 12.0

Expression Description

SIP.REQ.TO Returns the contents of the To header. For

example, for a SIP To header of To: “16”
<sip:16@sip_example.com>;tag=00127f54ec85a6d90cc14f45-
53cc0185, this expression returns ”16”
<sip:16@sip_example.com>;tag=00127f54ec85a6d90cc14f45-
53cc0185.
SIP.REQ.TO.ADDRESS Returns the SIP URI, which is found in the
sip_url object. All operations that are available
for SIP URIs can be used. For example, for a SIP
To header of To: “16”
<sip:16@sip_example.com>;tag=00127f54ec85a6d90cc14f45-
53cc0185, this expression
returns sip:16@sip_example.com.
SIP.REQ.TO.DISPLAY_NAME Returns the display name portion of the To
header. For example, for a SIP To header of To:
“16”
<sip:16@sip_example.com>;tag=00127f54ec85a6d90cc14f45-
53cc0185, this expression
returns 16.
SIP.REQ.TO.TAG Returns the “tag” vale from the “tag” name
value pair in the TO header. For example, for a
SIP To header of To: “16”
<sip:16@sip_example.com>;tag=00127f54ec85a6d90cc14f45-
53cc0185, this expression
returns 00127f54ec85a6d90cc14f45-53cc0185.
SIP.REQ.FROM Returns the contents of the From header. For
example, for a SIP From header of From: “12”
<sip:12@sip_example.com>;tag=00127f54ec85a6d90cc14f45-
53cc0185, this expression
returns sip:12@sip_example.com.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1282

NetScaler 12.0

Expression Description

SIP.REQ.FROM.ADDRESS Returns the SIP URI, which is found in the

sip_url object. All operations that are available
for SIP URIs can be used. For example, for a SIP
From header of From: “12”
<sip:12@sip_example.com>;tag=00127f54ec85a6d90cc14f45-
53cc0185, this expression
returns sip:12@sip_example.com.
SIP.REQ.FROM.DISPLAY_NAME Returns the display name portion of the To
header. For example, for a SIP From header
of From: “12”
<sip:12@sip_example.com>;tag=00127f54ec85a6d90cc14f45-
53cc0185, this expression
returns 12.
SIP.REQ.FROM.TAG Returns the “tag” value from the “tag”
name/value pair in the TO header. For
example, for a SIP From header of From: “12”
<sip:12@sip_example.com>;tag=00127f54ec85a6d90cc14f45-
53cc0185, this expression
returns 00127f54ec85a6d90cc14f45-53cc0185.
SIP.REQ.VIA Returns the complete Via header. If there are
multiple Via headers in the request, returns the
last Via header. For example, for the two Via
headers in the sample SIP header, this
expression returns Via: SIP/2.0/UDP
10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060;re
SIP.REQ.VIA.SENTBY_ADDRESS Returns the address that sent the request. For
example, for the Via header Via: SIP/2.0/UDP
10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060;re
this expression returns 10.102.84.180.
SIP.REQ.VIA.SENTBY_PORT Returns the port that sent the request. For
example, for the Via header Via: SIP/2.0/UDP
10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060;re
this expression returns 5060.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1283

NetScaler 12.0

Expression Description

SIP.REQ.VIA.RPORT Returns the value from the rport name/value

pair. For example, for the Via header Via:
SIP/2.0/UDP
10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060;re
this expression returns 5060.
SIP.REQ.VIA.BRANCH Returns the value from the branch name/value
pair. For example, for the Via header Via:
SIP/2.0/UDP
10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060;re
this expression returns z9hG4bK03e76d0b.
SIP.REQ.VIA.RECEIVED Returns the value from the received
name/value pair. For example, for the Via
header Via: SIP/2.0/UDP
10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060;re
this expression returns 10.102.84.160.
SIP.REQ.CALLID Returns the contents of the Callid header. This
expression is a derivative of
the sip_header_t class, so all operations that
are available for SIP headers can be used. For
example, for a SIP Callid header ofCall-ID:
00127f54-ec850017-0e46f5b9-
[email protected], this expression
returns00127f54-ec850017-0e46f5b9-
[email protected].
SIP.REQ.CSEQ Returns the CSEQ number from the CSEQ, as
an integer. For example, for a SIP CSEQ header
of CSeq: 101 INVITE, this expression returns 101.
SIP.REQ.HEADER(<header_name>) Returns the specified SIP header. For ,
substitute the name of the header that you
want. For example, to return the SIP From
header, you would
type SIP.REQ.HEADER(”From”).

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1284

NetScaler 12.0

Expression Description

SIP.REQ.HEADER(<header_name>).INSTANCE() Returns the specified instance of the specified

SIP header. Multiple instances of the same SIP
header can occur. Where you want a specific
instance of such a SIP header (for example, a
specific Via header), you can specify that
header by typing a number as the . Header
instances are matched from last (0) to first. In
other
words, SIP.REQ.HEADER(”Via”).INSTANCE(0) re-
turns the last instance of the Via header,
while SIP.REQ.HEADER(”Via”).INSTANCE(1) re-
turns the last instance but one of the Via
header, and so on. For example, if used on the
example SIP
header, SIP.REQ.HEADER(”Via”).INSTANCE(1) re-
turnsVia: SIP/2.0/UDP
10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060.
SIP.REQ.HEADER(<header_name>).VALUE() Returns the contents of the specified instance
of the specified SIP header. The usage is nearly
the same as the previous expression. For
example, if used on the SIP header example in
the preceding table
entry, SIP.REQ.HEADER(“Via”).VALUE(1) re-
turns SIP/2.0/UDP
10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060.
SIP.REQ.HEADER(<header_name>).COUNT Returns the number of instances of a particular
header as an integer. For example, if used on
the SIP header example
above, SIP.REQ.HEADER(“Via”).COUNT re-
turns 2.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1285

NetScaler 12.0

Expression Description

SIP.REQ.HEADER(<header_name>).EXISTS Returns a boolean value of true or false,

depending upon whether the specified header
exists or not. For example, if used on the SIP
header example
above, SIP.REQ.HEADER(“Expires”).EXISTSreturns
true, while SIP.REQ.HEADER(“Caller-
ID”).EXISTS returns
false.
SIP.REQ.HEADER(<header_name>).LIST Returns the comma-separated parameter list
in the specified header. For example, if used on
the SIP header example above,
SIP.REQ.HEADER(“Allow”).LIST returns
ACK,BYE,CANCEL,INVITE,NOTIFY,OPTIONS,REFER,REGISTER,U
You can append the string .GET() to select a
specific list item. For example, to get the first
item (ACK) from the above list, you would type
SIP.REQ.HEADER(“Allow”).LIST.GET(0). To
extract the second item (BYE), you would type
SIP.REQ.HEADER(“Allow”).LIST.GET(1). Note: If
the specified header contains a list of
name/value pairs, the entire name/value pair is
returned.
SIP.REQ.HEADER(<header_name>).TYPECAST_SIP_HEADER_T(“”)
Typecasts to . Any text can be typecasted to
thesip_header_t class, after which all
header-based operations can be used. After
you perform this operation, you can apply all
operations that can be used with . For
example, the expres-
sion SIP.REQ.CONTENT_LENGTH.TYPECAST_SIP_HEADER_T ty
casts all instances of the Content-Length
header. After you perform this operation, you
can apply all header operations to all instances
of the specified header.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1286

NetScaler 12.0

Expression Description

SIP.REQ.HEADER(<header_name>).CONTAINS(<string>).
Returns boolean true if the specified text string
is present in any instance of the specified
header. Operates on all the instances of the
specified header. Header instances are
matched from last (0) to first.
SIP.REQ.HEADER(<header_name>).EQUALS_ANY(<patset>)
Returns boolean true if any pattern associated
with <patset> matches any content in any
instance of the specified header. Operates on
all the instances of the specified header.
Header instances are matched from last (0) to
first.
SIP.REQ.HEADER(<header_name>).CONTAINS_ANY(<patset>)
Returns Boolean true if any pattern associated
with <patset> matches any content in any
instance of the specified header. Operates on
all the instances of the specified header.
Header instances are matched from last (0) to
first.
SIP.REQ.HEADER(<header_name>).CONTAINS_INDEX(<patset>)
Returns the index of the matching pattern
associated with <patset> if that pattern
matches any content in any instance of the
specified header. Operates on all the instances
of the specified header. Header instances are
matched from last (0) to first.
SIP.REQ.HEADER(<header_name>).EQUALS_INDEX(<patset>)
Returns the index of the matching pattern
associated with <patset> if that pattern
matches any instance of the specified header.
Operates on all the instances of the specified
header. Header instances are matched from
last (0) to first.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1287

NetScaler 12.0

Expression Description

SIP.REQ.HEADER(<header_name>).SUBSTR(<string>)
If the specified string is present in any instance
of the specified header, this expression returns
that string. For example, for the SIP header Via:
SIP/2.0/UDP
10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060;re
turns “rport=5060”.SIP.REQ.HEADER(“Via”).SUBSTR(“rport=50
turns an empty
string.
SIP.REQ.HEADER(<header_name>).AFTER_STR(<string>)
If the specified string is present in any instance
of the specified header, this expression returns
the string immediately after that string. For
example, for the SIP header Via: SIP/2.0/UDP
10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060;re
the expres-
sion SIP.REQ.HEADER(“Via”).AFTER_STR(“rport=”) re-
turns 5060.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1288

NetScaler 12.0

Expression Description

SIP.REQ.HEADER(<header_name>).REGEX_MATCH(<regex>)
Returns boolean true if the specified regular
expression (regex) matches any instance of the
specified header. You must specify the regular
expression in the following format:
re<delimiter>regular expression<same
delimiter>. The regular expression cannot be
larger than 1499 characters in length. It must
conform to the PCRE regular expression
library. See http://www.pcre.org/pcre.txt for
documentation on PCRE regular expression
syntax. The pcrepattern man page also has
useful information on specifying patterns by
using PCRE regular expressions. The regular
expression syntax supported in this expression
has some differences from PCRE. Back
references are not allowed. You should avoid
recursive regular expressions; although some
work, many do not. The dot (.) metacharacter
matches newlines. Unicode is not sup-
ported.SET_TEXT_MODE(IGNORECASE) over-
rides the (?i) internal option specified in the
regular expression.
SIP.REQ.HEADER(<header_name>).REGEX_SELECT(<regex>)
If the specified regex matches any text in any
instance of the specified header, this
expression returns the text. For example, for
the SIP header Via: SIP/2.0/UDP
10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060;re
the expres-
sion SIP.REQ.HEADER(“Via”).REGEX_SELECT(“received=[0-
9]{1,3}.[0-9]{1,3}.[0-9]{1,3}.[0-9]{1,3}”) returns re-
ceived=10.102.84.160.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1289

NetScaler 12.0

Expression Description

SIP.REQ.HEADER(<header_name>).AFTER_REGEX(<regex>)
If the specified regex matches any text in any
instance of the specified header, this
expression returns the string immediately after
that text. For example, for the SIP header Via:
SIP/2.0/UDP
10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060;re
the expres-
sion SIP.REQ.HEADER(“Via”).AFTER_REGEX(“received=”) re-
turns10.102.84.160.
SIP.REQ.HEADER(<header_name>).BEFORE_REGEX(<regex>)
If the specified regex matches any text in any
instance of the specified header, this
expression returns the string immediately
before that text. For example, for the SIP
header Via: SIP/2.0/UDP
10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060;re
the expres-
sion SIP.REQ.HEADER(“Via”).BEFORE_REGEX(“[0-
9]{1,3}.[0-9]{1,3}.[0-9]{1,3}.[0-9]{1,3}”) returns re-
ceived=.
SIP.REQ.FULL_HEADER Returns the entire SIP header, including the
terminating CR/LF.
SIP.REQ.IS_VALID Returns boolean true if the request format is
valid.
SIP.REQ.BODY(<length>) Returns the request body, up to the specified
length. If the specified length is greater than
the length of the request body, this expression
returns the entire request body.
SIP.REQ.LB_VSERVER Returns the name of the load balancing virtual
server (LB vserver) that is serving the current
request.
SIP.REQ.CS_VSERVER Returns the name of the content switching
virtual server (CS vserver) that is serving the
current request.

SIP response expressions

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1290

NetScaler 12.0

Expression Description

SIP.RES.STATUS Returns the SIP response status code. For

example, if the first line of the response is
SIP/2.0 100 Trying, this expression returns 100.
SIP.RES.STATUS_MSG Returns the SIP response status message. For
example, if the first line of the response is
SIP/2.0 100 Trying, this expression returns
Trying.
SIP.RES.IS_REDIRECT Returns boolean true if the response code is a
redirect.
SIP.RES.METHOD Returns the response method extracted from
the request method string in the CSeq header.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Operations for HTTP, HTML, and XML encoding and “safe” characters

September 24, 2018

Contributed by:
C

The following operations work with the encoding of HTML data in a request or response and XML data
in a POST body.

• <text>.HTML_XML_SAFE:
Transforms special characters into XML safe format, as in the following examples:

A left-pointing angle bracket (<) is converted to <

A right-pointing angle bracket (>) is converted to >
An ampersand (&) is converted to &
This operation safeguards against cross-site scripting attacks. Maximum length of the trans-
formed text is 2048 bytes. This is a read-only operation.

After applying the transformation, additional operators that you specify in the expression are
applied to the selected text. Following is an example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1291

NetScaler 12.0

http.req.url.query.html_xml_safe. contains(“myQueryString”)

• <text>.HTTP_HEADER_SAFE:
Converts all new line (‘\n’) characters in the input text to ‘%0A’ to enable the input to be used
safely in HTTP headers.

This operation safeguards against response-splitting attacks.

The maximum length of the transformed text is 2048 bytes. This is a read-only operation.

• <text>.HTTP_URL_SAFE:
Converts unsafe URL characters to ‘%xx’ values, where “xx” is a hex-based representation of the
input character. For example, the ampersand (&) is represented as %26 in URL-safe encoding.
The maximum length of the transformed text is 2048 bytes. This is a read-only operation.

Following are URL safe characters. All others are unsafe:

– Alpha-numeric characters: a-z, A-Z, 0-9

– Asterix: “*”
– Ampersand: “&”
– At-sign: “@”
– Colon: “:”
– Comma: “,”
– Dollar: “$”
– Dot: “.”
– Equals: “=”
– Exclamation mark: “!”
– Hyphen: “-“
– Open and close parentheses: “(“, “)”
– Percent: “%”
– Plus: “+”
– Semicolon: “;”
– Single quote: “”’
– Slash: “/”
– Question mark: “?”
– Tilde: “~”
– Underscore: “_”

• <text>.MARK_SAFE:
Marks the text as safe without applying any type of data transformation.

• **<text>.SET_TEXT_MODE(URLENCODED|NOURLENCODED)
Transforms all %HH encoding in the byte stream. This operation works with characters (not
bytes). By default, a single byte represents a character in ASCII encoding. However, if you specify
URLENCODED mode, three bytes can represent a character.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1292

NetScaler 12.0

In the following example, a PREFIX(3) operation selects the first 3 characters in a target.

http.req.url.hostname.prefix(3)

In the following example, the NetScaler can select up to 9 bytes from the target:

http.req.url.hostname.set_text_mode(urlencoded).prefix(3)

• <text>.SET_TEXT_MODE(PLUS_AS_SPACE|NO_PLUS_AS_SPACE):
Specifies how to treat the plus character (+). The PLUS_AS_SPACE option replaces a plus
character with white space. For example, the text “hello+world” becomes “hello world.” The
NO_PLUS_AS_SPACE option leaves plus characters as they are.

• <text>.SET_TEXT_MODE(BACKSLASH_ENCODED|NO_BACKSLASH_ENCODED):
Specifies whether or not backslash decoding is performed on the text object represented by
<text>.

If BACKSLASH_ENCODED is specified, the SET_TEXT_MODE operator performs the following op-

erations on the text object:

– All occurrences of “\XXX” will be replaced with the character “Y” (where XXX represents a
number in the octal system and Y represents the ASCII equivalent of XXX). The valid range of
octal values for this type of encoding is 0 to 377. For example, the encoded text “http\72//”
and http\072//” will both be decoded to http://, where the colon (:) is the ASCII equivalent
of the octal value “72”.
– All occurrences of “\xHH” will be replaced with the character “Y” (HH represents a num-
ber in the hexadecimal system and Y denotes the ASCII equivalent of HH. For example,
the encoded text “http\x3a//” will be decoded to http://, where the colon (:) is the ASCII
equivalent of the hexadecimal value “3a“.
– All occurrences of “\uWWXX” will be replaced with the character sequence “YZ” (Where
WW and XX represent two distinct hexadecimal values and Y and Z represent their ASCII
equivalents of WW and XX respectively. For example, the encoded text “http%u3a2f/” and
“http%u003a//” will both be decoded to http://, where “3a” and “2f” are two hexadecimal
values and the colon (:) and forward slash (“/”) represent their ASCII equivalents respec-
tively.
– All occurrences of “\b”, “\n”, “\t”, “\f”, and “\r” are replaced with the corresponding ASCII
characters.
If NO_BACKSLASH_ENCODED is specified, backslash decoding is not performed on the text
object.

• <text>.SET_TEXT_MODE(BAD_ENCODE_RAISE_UNDEF|NO_BAD_ENCODE_RAISE_UNDEF):
Performs the associated undefined action if either the URLENCODED or the BACKSLASH_ENCODED
mode is set and bad encoding corresponding to the specified encoding mode is encountered
in the text object represented by <text>.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1293

NetScaler 12.0

If NO_BAD_ENCODE_RAISE_UNDEF is specified, the associated undefined action will not be per-

formed when bad encoding is encountered in the text object represented by<text>.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Expressions for TCP, UDP, and VLAN data

September 24, 2018

Contributed by:
C

TCP and UDP data take the form of a string or a number. For expression prefixes that return string
values for TCP and UDP data, you can apply any text-based operations. For more information, see
Advanced policy expressions: Evaluating text.

For expression prefixes that return numeric value, such as a source port, you can apply an arithmetic
operation. For more information, see Basic operations on expression prefixes and Compound opera-
tions for numbers.

The following table describes prefixes that extract TCP and UDP data.

GET Operation Description

CLIENT.TCP.PAYLOAD(<integer>) Returns TCP payload data as a string, starting

with the first character in the payload and
continuing for the number of characters in the
<integer> argument. You can apply any
text-based operation to this prefix.
CLIENT.TCP.SRCPORT Returns the ID of the current packet’s source
port as a number.
CLIENT.TCP.DSTPORT Returns the ID of the current packet’s
destination port as a number.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1294

NetScaler 12.0

GET Operation Description

CLIENT.TCP.OPTIONS Returns the TCP options set by the client.

Examples of TCP options are Maximum
Segment Size (MSS), Window Scale, Selective
Acknowledgements (SACK), and Time Stamp
Option. The COUNT, TYPE(<type>),
and TYPE_NAME(<m>) operators can be used
with this prefix. For the TCP options set by the
server, see the SERVER.TCP.OPTIONS prefix.
CLIENT.TCP.OPTIONS.COUNT Returns the number of TCP options that the
client has set.
CLIENT.TCP.OPTIONS.TYPE(<type>) Returns the value of the TCP option whose
type (or option kind) is specified as the
argument. The value is returned as a string of
bytes in big endian format (or network byte
order). Parameters: type - Type value
CLIENT.TCP.OPTIONS.TYPE_NAME(<m>) Returns the value of the TCP option whose
enumeration constant is specified as the
argument. The enumeration constants that
you can pass as the argument are REPEATER,
TIMESTAMP, SACK_PERMITTED, WINDOW, and
MAXSEG. To specify the TCP option kind
instead of these enumeration constants,
use CLIENT.TCP.OPTIONS.TYPE(<type>). For
other TCP options, you must
use CLIENT.TCP.OPTIONS.TYPE(<type>). Param-
eters: m - TCP option enumeration
constant
CLIENT.TCP.REPEATER_OPTION.EXISTS Returns a Boolean TRUE if Repeater TCP
options exist.
CLIENT.TCP.REPEATER_OPTION.IP Returns the branch repeater’s IPv4 address
from the Repeater TCP options.
CLIENT.TCP.REPEATER_OPTION.MAC Returns the branch repeater’s MAC address
from the Repeater TCP options.
CLIENT.UDP.DNS.DOMAIN Returns the DNS domain name.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1295

NetScaler 12.0

GET Operation Description

CLIENT.UDP.DNS.DOMAIN.EQ(“<hostname>”) Returns a Boolean TRUE if the domain name

matches the <hostname> argument. The
comparison is case insensitive. Following is an
exam-
ple: client.udp.dns.domain.eq(“www.mycompany.com”)
CLIENT.UDP.DNS.IS_AAAAREC Returns a Boolean TRUE if the record type is
AAAA. These types of records indicate an IPv6
address in forward lookups.
CLIENT.UDP.DNS.IS_ANYREC Returns a Boolean TRUE if it is of any record
type.
CLIENT.UDP.DNS.IS_AREC Returns a Boolean TRUE if the record is type A.
Type A records provide the host address.
CLIENT.UDP.DNS.IS_CNAMEREC Returns a Boolean TRUE if the record is of type
CNAME. In systems that use multiple names to
identify a resource, there is one canonical
name and a number of aliases. The CNAME
provides the canonical name.
CLIENT.UDP.DNS.IS_MXREC Returns a Boolean TRUE if the record is of type
MX (mail exchanger). This DNS record
describes a priority and a host name. The MX
records for the same domain name specify the
email servers in the domain and the priority for
each server.
CLIENT.UDP.DNS.IS_NSREC Returns a Boolean TRUE if the record is of type
NS. This is a name server record that includes a
host name with an associated A record. This
enables locating the domain name that is
associated with the NS record.
CLIENT.UDP.DNS.IS_PTRREC Returns a Boolean TRUE if the record is of type
PTR. This is a domain name pointer and is
often used to associate a domain name with an
IPv4 address.
CLIENT.UDP.DNS.IS_SOAREC Returns a Boolean TRUE if the record is of type
SOA. This is a start of authority record.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1296

NetScaler 12.0

GET Operation Description

CLIENT.UDP.DNS.IS_SRVREC Returns a Boolean TRUE if the record is of type

SRV. This is a more general version of the MX
record.
CLIENT.UDP.DSTPORT Returns the numeric ID of the current packet’s
UDP destination port.
CLIENT.UDP.SRCPORT Returns the numeric ID of the current packet’s
UDP source port.
CLIENT.UDP.RADIUS Returns RADIUS data for the current packet.
CLIENT.UDP.RADIUS.ATTR_TYPE(<type>) Returns the value for the attribute type
specified as the argument.
CLIENT.UDP.RADIUS.USERNAME Returns the RADIUS user name.
CLIENT.TCP.MSS Returns the maximum segment size (MSS) for
the current connection as a number.
CLIENT.VLAN.ID Returns the numeric ID of the VLAN through
which the current packet entered the
NetScaler.
SERVER.TCP.DSTPORT Returns the numeric ID of the current packet’s
destination port.
SERVER.TCP.SRCPORT Returns the numeric ID of the current packet’s
source port.
SERVER.TCP.OPTIONS Returns the TCP options set by the server.
Examples of TCP options are Maximum
Segment Size (MSS), Window Scale, Selective
Acknowledgements (SACK), and Time Stamp
Option. The COUNT, TYPE(<type>),
and TYPE_NAME(<m>) operators can be used
with this prefix. For the TCP options set by the
client, see the CLIENT.TCP.OPTIONS prefix.
SERVER.TCP.OPTIONS.COUNT Returns the number of TCP options that the
server has set.
SERVER.TCP.OPTIONS.TYPE(<type>) Returns the value of the TCP option whose
type (or option kind) is specified as the
argument. The value is returned as a string of
bytes in big endian format (or network byte
order). Parameters: type - Type value

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1297

NetScaler 12.0

GET Operation Description

SERVER.TCP.OPTIONS.TYPE_NAME(<m>) Returns the value of the TCP option whose

enumeration constant is specified as the
argument. The enumeration constants that
you can pass as the argument are REPEATER,
TIMESTAMP, SACK_PERMITTED, WINDOW, and
MAXSEG. To specify the TCP option kind
instead of these enumeration constants,
use CLIENT.TCP.OPTIONS.TYPE(<type>). For
other TCP options, you must
use CLIENT.TCP.OPTIONS.TYPE(<type>). Param-
eters: m - TCP option enumeration
constant
SERVER.VLAN Operates on the VLAN through which the
current packet entered the NetScaler.
SERVER.VLAN.ID Returns the numeric ID of the VLAN through
which the current packet entered the
NetScaler.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Expressions for evaluating a DNS message and identifying its carrier

protocol

September 24, 2018

Contributed by:
C

You can evaluate DNS requests and responses by using expressions that begin with DNS.REQ and
DNS.RES, respectively. You can also identify the transport layer protocol that is being used to send
the DNS messages.

The following functions return the contents of a DNS query.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1298

NetScaler 12.0

Function Description

DNS.REQ.QUESTION.DOMAIN Return the domain name (the value of

the QNAME field) in the question section of the
DNS query. The domain name is returned as a
text string, which can be passed to EQ(), NE(),
and any other functions that work with text.
DNS.REQ.QUESTION.TYPE Return the query type (the value of
the QTYPE field) in the DNS query. The field
indicates the type of resource record (for
example, A, NS, or CNAME) for which the name
server is being queried. The returned value can
be compared to one of the following values by
using the EQ() and NE()functions: A,
AAAA, NS, SRV, PTR, CNAME, SOA, MX, and ANY.
Note: You can use only
the EQ() and NE() functions with
the TYPE function. Exam-
ple: DNS.REQ.QUESTION.TYPE.EQ(MX)

The following functions return the contents of a DNS response.

Function Description

DNS.RES.HEADER.RCODE Return the response code (the value of

the RCODE field) in the header section of the
DNS response. You can use only
the EQ() and NE() functions with
the RCODE function. Following are the possible
values: NOERROR, FORMERR, SERVFAIL,
NXDOMAIN, NOTIMP, and REFUSED.
DNS.RES.QUESTION.DOMAIN Return the domain name (the value of
the QNAME field) in the question section of the
DNS response. The domain name is returned
as a text string, which can be passed
to EQ(), NE(), and any other functions that
work with text.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1299

NetScaler 12.0

Function Description

DNS.RES.QUESTION.TYPE Return the query type (the value of

the QTYPE field) in the question section of the
DNS response. The field indicates the type of
resource record (for example, A, NS, or CNAME)
that is contained in the response. The returned
value can be compared to one of the following
values by using the EQ()and NE() functions: A,
AAAA, NS, SRV, PTR, CNAME, SOA, MX, and ANY.
You can use only the EQ() and NE() functions
with the TYPE function. Exam-
ple: DNS.RES.QUESTION.TYPE.EQ(SOA)

The following functions return the transport layer protocol name.

Function Description

DNS.REQ.TRANSPORT Return the name of the transport layer

protocol that was used to send the DNS query.
Possible values returned are TCP and UDP. You
can use only the EQ() and NE() functions with
the TRANSPORT function. Exam-
ple: DNS.REQ.TRANSPORT.EQ(TCP)
DNS.RES.TRANSPORT Return the name of the transport layer
protocol that was used for the DNS response.
Possible values returned are TCP and UDP. You
can use only the EQ() and NE() functions with
the TRANSPORT function. Exam-
ple: DNS.RES.TRANSPORT.EQ(TCP)

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1300

NetScaler 12.0

XPath and HTML, XML, or JSON expressions

September 24, 2018

Contributed by:
C
The Advanced policy infrastructure supports expressions for evaluating and retrieving data from
HTML, XML, and JavaScript Object Notation (JSON) files. This enables you to find specific nodes in
an HTML, XML, or JSON document, determine if a node exists in the file, locate nodes in XML contexts
(for example, nodes that have specific parents or a specific attribute with a given value), and return
the contents of such nodes. Additionally, you can use XPath expressions in rewrite expressions.
The Advanced policy expression implementation for XPath comprises an Advanced policy expression
prefix (such as “HTTP.REQ.BODY”) that designates HTML or XML text, and the XPATH operator that
takes the XPath expression as its argument.
HTML files are a largely free-form collection of tags and text elements. You can use the XPATH_HTML
operator, which takes an XPath expression as its argument, to process HTML files. JSON files are either
a collection of name/value pairs or an ordered list of values. You can use the XPATH_JSON operator,
which takes an XPath expression as its argument, to process JSON files.
• <text>.XPATH(xpathex):
Operate on an XML file and return a Boolean value.
For example, the following expression returns a Boolean TRUE if a node called “creator” exists
under the node “Book” within the first 1000 bytes of the XML file.
HTTP.REQ.BODY(1000).XPATH(xp%boolean(//Book/creator)%)

Parameters:
xpathex - XPath Boolean expression
• <text>.XPATH(xpathex):
Operate on an XML file and return a value of data type “double.”
For example, the following expression converts the string “36” (a price value) to a value of data
type “double” if the string is in the first 1000 bytes of the XML file:
HTTP.REQ.BODY(1000).XPATH(xp%number(/Book/price)%)

Parameters:
xpathex - XPath numeric expression
• <text>.XPATH(xpathex):
Operate on an XML file and return a node-set or a string. Node-sets are converted to correspond-
ing strings by using the standard XPath string conversion routine.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1301

NetScaler 12.0

For example, the following expression selects all the nodes that are enclosed by “/Book/creator”
(a node-set) in the first 1000 bytes of the body:

HTTP.REQ.BODY(1000).XPATH(xp%/Book/creator%)

Parameters:

xpathex - XPath expression

• <text>.XPATH_HTML(xpathex)

Operate on an HTML file and return a text value.

For example, the following expression operates on an HTML file and returns the text enclosed
in <title></title> tags if the title HTML element is found in the first 1000 bytes:

HTTP.REQ.BODY(1000).XPATH_HTML(xp%/html/head/title%)

Parameters:

xpathex - XPath text expression

• <text>.XPATH_HTML_WITH_MARKUP(xpathex)

Operate on an HTML file and return a string that contains the entire selected portion of the doc-
ument, including markup such as including the enclosing element tags.

The following expression operates on the HTML file and selects all content within the <title> tag,
including markup.

HTTP.REQ.BODY(1000).XPATH_HTML_WITH_MARKUP( xp%/html/head/title%)

The portion of the HTML body that is selected by the expression is marked for further processing.

Parameters:

xpathex - XPath expression

• <text>.XPATH_JSON(xpathex)

Operate on a JSON file and return a Boolean value.

For example, consider the following JSON file:

{ “Book”:{ “creator”:{ “person”:{ “name”:’<name>’ } }, “title”:’<title>’ } }

The following expression operates on the JSON file and returns a Boolean TRUE if the JSON file
contains a node named “creator,” whose parent node is “Book,” in the first 1000 bytes:

HTTP.REQ.BODY(1000).XPATH_JSON(xp%boolean(/Book/creator)%)

Parameters:

xpathex - XPath Boolean expression

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1302

NetScaler 12.0

• <text>.XPATH_JSON(xpathex)
Operate on a JSON file and return a value of data type “double.”

For example, consider the following JSON file:

{ “Book”:{ “creator”:{ “person”:{ “name”:’<name>’ } }, “title”:’<title>’, “price”:”36” } }

The following expression operates on the JSON file and converts the string “36” to a value of
data type “double” if the string is present in the first 1000 bytes of the JSON file.

HTTP.REQ.BODY(1000).XPATH_JSON(xp%number(/Book/price)%)

Parameters:

xpathex - XPath numeric expression

• <text>.XPATH_JSON(xpathex)
Operate on a JSON file and return a node-set or a string. Node-sets are converted to correspond-
ing strings by using the standard XPath string conversion routine.

For example, consider the following JSON file:

{ “Book”:{ “creator”:{ “person”:{ “name”:’<name>’ } }, “title”:’<title>’ } }

The following expression selects all the nodes that are enclosed by “/Book” (a node-set) in the
first 1000 bytes of the body of the JSON file and returns the corresponding string value, which
is “<name><title>”:

HTTP.REQ.BODY(1000).XPATH_JSON(xp%/Book%)

Parameters:

xpathex - XPath expression

• <text>.XPATH_JSON_WITH_MARKUP(xpathex)
Operate on an XML file and return a string that contains the entire portion of the document for
the result node, including markup such as including the enclosing element tags.

For example, consider the following JSON file:

{“Book”:{ “creator”:{ “person”:{ “name”:’<name>’ } }, “title”:’<title>’ } }

The following expression operates on the JSON file and selects all the nodes that are enclosed by
“/Book/creator” in the first 1000 bytes of the body, which is “creator:{ person:{ name:’<name>’
} }.”

HTTP.REQ.BODY(1000).XPATH_JSON_WITH_MARKUP(xp%/Book/creator%)

The portion of the JSON body that is selected by the expression is marked for further processing.

Parameters:

xpathex - XPath expression

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1303

NetScaler 12.0

• <text>.XPATH_WITH_MARKUP(xpathex):
Operate on an XML file and return a string that contains the entire portion of the document for
the result node, including markup such as including the enclosing element tags.

For example, the following expression operates on an XML file and selects all the nodes enclosed
by “/Book/creator” in the first 1000 bytes of the body.

HTTP.REQ.BODY(1000).XPATH_WITH_MARKUP(xp%/Book/creator%)

The portion of the JSON body that is selected by the expression is marked for further processing.

Parameters:

xpathex - XPath expression

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Encrypt and decrypt XML payloads

September 24, 2018

Contributed by:
C

You can use the XML_ENCRYPT() and XML_DECRYPT() functions in Advanced policy expressions to
encrypt and decrypt, respectively, XML data. These functions conform to the W3C XML Encryption
standard defined at “http://www.w3.org/TR/2001/PR-xmldsig-core-20010820/.” XML_ENCRYPT()
and XML_DECRYPT() support a subset of the XML Encryption specification. In the subset, data
encryption uses a bulk cipher method (RC4, DES3, AES128, AES192, or AES256), and an RSA public
key is used to encrypt the bulk cipher key.

Note: If you want to encrypt and decrypt text in a payload, you must use the
ENCRYPT and
DECRYPT functions. For more information about these functions, see
Encrypt and decrypt text.

The
XML_ENCRYPT() and
XML_DECRYPT() functions are not dependent on the encryption/decryption service that is used by the
ENCRYPT and
DECRYPT commands for text. The cipher method is specified explicitly as an argument to the

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1304

NetScaler 12.0

XML_ENCRYPT() function. The

XML_DECRYPT() function obtains the information about the specified cipher method from the
<xenc:EncryptedData> element. Following are synopses of the XML encryption and decryption func-
tions:

• XML_ENCRYPT(<certKeyName>, <method> [, <flags>]). Returns an <xenc:EncryptedData>

element that contains the encrypted input text and the encryption key, which is itself encrypted
by using RSA.
• XML_DECRYPT(<certKeyName>). Returns the decrypted text from the input <xenc:EncryptedData>
element, which includes the cipher method and the RSA-encrypted key.

Note: The
<xenc:EncryptedData> element is defined in the W3C XML Encryption specification.

Following are descriptions of the arguments:

• certKeyName: Selects an X.509 certificate with an RSA public key for XML_ENCRYPT() or an RSA
private key for XML_DECRYPT(). The certificate key must have been previously created by an add
ssl certKey command.

• method: Specifies which cipher method to use for encrypting the XML data. Possible values:
RC4, DES3, AES128, AES192, AES256.

• flags: A bitmask specifying the following optional key information (

<ds:KeyInfo>) to be included in the
<xenc:EncryptedData> element that is generated by
XML_ENCRYPT():

– 1 - Include a KeyName element with the certKeyName. The element is <ds:KeyName>.

– 2 - Include a KeyValue element with the RSA public key from the certificate. The element
is <ds:KeyValue>.
– 4 - Include an X509IssuerSerial element with the certificate serial number and issuer DN.
The element is <ds:X509IssuserSerial>.
– 8 - Include an X509SubjectName element with the certificate subject DN. The element is
<ds:X509SubjectName>.
– 16 - Include an X509Certificate element with the entire certificate. The element is
<ds:X509Certificate>.

Use the XML_ENCRYPT() and XML_DECRYPT() functions in expressions

The XML encryption feature uses SSL certificate-key pairs to provide X.509 certificates (with RSA pub-
lic keys) for key encryption and RSA private keys for key decryption. Therefore, before you use the
XML_ENCRYPT() function in an expression, you must create an SSL certificate-key pair. The following

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1305

NetScaler 12.0

command creates an SSL certificate-key pair, my-certkey, with the X.509 certificate, my-cert.pem, and
the private key file, my-key.pem.

add ssl certKey my-certkey -cert my-cert.pem -key my-key.pem -passcrypt

kxPeMRYnitY=

The following CLI commands create rewrite actions and policies for encrypting and decrypting XML
content.

1 add rewrite action my-xml-encrypt-action replace ”HTTP.RES.BODY(10000).

XPATH_WITH_MARKUP(xp%/%)” ”HTTP.RES.BODY(10000).XPATH_WITH_MARKUP(xp
%/%).XML_ENCRYPT(”my-certkey”, AES256, 31)” -bypassSafetyCheck YES
2
3 add rewrite action my-xml-decrypt-action replace ”HTTP.REQ.BODY(10000).
XPATH_WITH_MARKUP(xp%//xenc:EncryptedData%)” ”HTTP.REQ.BODY(10000).
XPATH_WITH_MARKUP(xp%//xenc:EncryptedData%).XML_DECRYPT(”my-certkey”
)” -bypassSafetyCheck YES
4
5 add rewrite policy my-xml-encrypt-policy ”HTTP.REQ.URL.CONTAINS(”xml-
encrypt”)” my-xml-encrypt-action
6
7 add rewrite policy my-xml-decrypt-policy ”HTTP.REQ.BODY(10000).XPATH(xp
%boolean(//xenc:EncryptedData)%)” my-xml-decrypt-action
8
9 bind rewrite global my-xml-encrypt-policy 30
10
11 bind rewrite global my-xml-decrypt-policy 30

In the above example, the rewrite action my-xml-encrypt-action encrypts the entire XML document (
XPATH_WITH_MARKUP(xp%/%)) in the request by using the AES-256 bulk encryption method and the
RSA public key from my-certkey to encrypt the bulk encryption key. The action replaces the document
with an <xenc:EncryptedData> element containing the encrypted data and an encrypted key. The
flags represented by 31 include all of the optional <ds:KeyInfo> elements.

The action my-xml-decrypt-action decrypts the first <xenc:EncryptedData> element in the response
(XPATH_WITH_MARKUP(xp%//xenc:EncryptedData%)). This requires the prior addition of the xenc
XML namespace by use of the following CLI command:

add ns xmlnamespace xenc http://www.w3.org/2001/04/xmlenc##

The my-xml-decrypt-action action uses the RSA private key in my-certkey to decrypt the encrypted key
and then uses the bulk encryption method specified in the element to decrypt the encrypted contents.
Finally, the action replaces the encrypted data element with the decrypted content.

The rewrite policy my-xml-encrypt-policy applies my-xml-encrypt-action to requests for URLs contain-
ing xml-encrypt. The action encrypts the entire response from a service configured on the NetScaler

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1306

NetScaler 12.0

appliance.

The rewrite policy my-xml-decrypt-policy applies my-xml-decrypt-action to requests that contain an

<xenc:EncryptedData> element ((XPATH(xp%//xenc:EncryptedData%) returns a non-empty string).
The action decrypts the encrypted data in requests that are bound for a service configured on the
NetScaler appliance.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Advanced policy expressions: parsing SSL

November 5, 2018

Contributed by:
C

There are advanced policy expressions to parse SSL certificates and SSL client hello messages.

Parse SSL certificates

You can use advanced policy expressions to evaluate X.509 Secure Sockets Layer (SSL) client certifi-
cates. A client certificate is an electronic document that can be used to authenticate a user’s identity. A
client certificate contains (at a minimum) version information, a serial number, a signature algorithm
ID, an issuer name, a validity period, a subject (user) name, a public key, and signatures.

You can examine both SSL connections and data in client certificates. For example, you may want to
send SSL requests that use low-strength ciphers to a particular load balancing virtual server farm. The
following command is an example of a Content Switching policy that parses the cipher strength in a
request and matches cipher strengths that are less than or equal to 40:

1 add cs policy p1 -rule ”client.ssl.cipher\_bits.le(40)”

As another example, you can configure a policy that determines whether a request contains a client
certificate:

1 add cs policy p2 -rule ”client.ssl.client\_cert EXISTS”

Or, you might want to configure a policy that examines particular information in a client certificate.
For example, the following policy verifies that the certificate has one or more days before expiration:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1307

NetScaler 12.0

1 add cs policy p2 -rule ”client.ssl.client\_cert exists && client.ssl.

client\_cert.days\_to\_expire.ge(1)”

Note

For information on parsing dates and times in a certificate, see Format of Dates and Times in an
Expression” and
Expressions for SSL Certificate Dates.

Prefixes for text-based SSL and certificate data

The following table describes expression prefixes that identify text-based items in SSL transactions
and client certificates.

Table 1. Prefixes That Return Text or Boolean Values for SSL and Client Certificate Data

Prefix Description

CLIENT.SSL.CLIENT_CERT Returns the SSL client certificate in the current

SSL transaction.
CLIENT.SSL.CLIENT_CERT.TO_PEM Returns the SSL client certificate in binary
format.
CLIENT.SSL.CIPHER_EXPORTABLE Returns a Boolean TRUE if the SSL
cryptographic SSL cryptographic cipher is
exportable.
CLIENT.SSL.CIPHER_NAME Returns the name of the SSL Cipher if invoked
from an SSL connection, and a NULL string if
invoked from a non-SSL connection.
CLIENT.SSL.IS_SSL Returns a Boolean TRUE if the current
connection is SSL-based.

Prefixes for numeric data in SSL certificates

The following table describes prefixes that evaluate numeric data other than dates in SSL certificates.
These prefixes can be used with the operations that are described in Basic Operations on Expression
Prefixes” and Compound Operations for Numbers.

Table 2. Prefixes That Evaluate Numeric Data Other Than Dates in SSL Certificates

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1308

NetScaler 12.0

Prefix Description

CLIENT.SSL.CLIENT_CERT.DAYS_TO_EXPIRE Returns the number of days that the certificate

is valid, or returns -1 for expired certificates.
CLIENT.SSL.CLIENT_CERT.PK_SIZE Returns the size of the public key used in the
certificate.
CLIENT.SSL.CLIENT_CERT.VERSION Returns the version number of the certificate.
If the connection is not SSL-based, returns zero
(0).
CLIENT.SSL.CIPHER_BITS Returns the number of bits in the cryptograhic
key. Returns 0 if the connection is not
SSL-based.
CLIENT.SSL.VERSION Returns a number that represents the SSL
protocol version, as follows: 0. The transaction
is not SSL-based.; 0x002. The transaction is
SSLv2.; 0x300. The transaction is SSLv3.;
0x301. The transaction is TLSv1.; 0x302. The
transaction is TLSv1.1.; 0x303. The transaction
is TLSv1.2.

Note

For expressions related to expiration dates in a certificate, see

Expressions for SSL Certificate Dates.

Expressions for SSL certificates

You can parse SSL certificates by configuring expressions that use the following prefix:

CLIENT.SSL.CLIENT_CERT

This section discusses the expressions that you can configure for certificates, with the exception of
expressions that examine certificate expiration. Time-based operations are described in Advanced
Policy Expressions: Working with Dates, Times, and Numbers.

The following table describes operations that you can specify for the CLIENT.SSL.CLIENT_CERT prefix.

Table 3. Operations That Can Be Specified with the CLIENT.SSL.CLIENT_CERT Prefix

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1309

NetScaler 12.0

SSL Certificate Operation Description

<certificate>.EXISTS Returns a Boolean TRUE if the client has an SSL

certificate.
<certificate>.ISSUER Returns the Distinguished Name (DN) of the
Issuer in the certificate as a name-value list. An
equals sign (“=”) is the delimiter for the name
and the value, and the slash (“/”) is the
delimiter that separates the name-value pairs.
Following is an example of the returned DN:
/C=US/O=myCompany/OU=www.mycompany.
com/CN=www.mycompany.com/
[email protected]
<certificate>.ISSUER. Returns the Issuer and ignores the empty
IGNORE_EMPTY_ELEMENTS elements in a name-value list. For example,
consider the following: Cert-Issuer:
/c=in/st=kar//l=bangelore
//o=mycompany/ou=sales/
/[email protected].
The following Rewrite action returns a count of
6 based on the preceding Issuer definition:
sh rewrite action insert_ssl_header
Name: insert_sslOperation:
insert_http_header Target:Cert-
Issuer
Value:CLIENT.SSL.CLIENT_CERT.ISSUER
.COUNT. However, if you change the value to
the following, the returned count is 9:
CLIENT.SSL.CLIENT_CERT.ISSUER.
IGNORE_EMPTY_ELEMENTS.COUNT

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1310

NetScaler 12.0

Advanced policy expressions: IP and MAC addresses, throughput, VLAN

IDs

November 5, 2018

Contributed by:
C

You can use Advanced policy expression prefixes that return IPv4 and IPv6 addresses, MAC addresses,
IP subnets, useful client and server data such as the throughput rates at the interface ports (Rx, Tx,
and RxTx), and the IDs of the VLANs through which packets are received. You can then use various
operators to evaluate the data that is returned by these expression prefixes.

Expressions for IP Addresses and IP Subnets

You can use Advanced policy expressions to evaluate addresses and subnets that are in Internet Proto-
col version 4 (IPv4) or Internet Protocol version 6 (IPv6) format. Expression prefixes for IPv6 addresses
and subnets include IPv6 in the prefix. Expression prefixes for IPv4 addresses and subnets include IP
in the prefix. Following is an example of an expression that identifies whether a request has originated
from a particular IPv4 subnet.

1 client.ip.src.in_subnet(147.1.0.0/16)

Following are two examples of Rewrite policies that examine the subnet from which the packet is
received and perform a rewrite action on the Host header. With these two policies configured, the
rewrite action that is performed depends on the subnet in the request. These two policies evaluate IP
addresses that are in the IPv4 address format.

1 - add rewrite action URL1-rewrite-action replace ”http.req.header(\”

Host\”)” ”\”www.mycompany1.com\””
2 - add rewrite policy URL1-rewrite-policy ”http.req.header(\”Host\”).
contains(\”www.test1.com\”) && client.ip.src.in_subnet(147.1.0.0/16)
” URL1-rewrite-action
3 - add rewrite action URL2-rewrite-action replace ”http.req.header(\”
Host\”)” ”\”www.mycompany2.com\””
4 - add rewrite policy URL2-rewrite-policy ”http.req.header(\”Host\”).
contains(\”www.test2.com\”) && client.ip.src.in_subnet
(10.202.0.0/16)” URL2-rewrite-action

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1311

NetScaler 12.0

Note

The preceding examples are commands that you type at the NetScaler command-line interface
(CLI) and, therefore, each quotation mark must be preceded by a backslash (\). For more infor-
mation, see Configuring advanced policy expressions in a policy.

Prefixes for IPV4 Addresses and IP Subnets

The following table describes prefixes that return IPv4 addresses and subnets, and segments of IPv4
addresses. You can use numeric operators and operators that are specific to IPv4 addresses with these
prefixes. For more information about numeric operations, see Basic Operations on Expression Pre-
fixes and Compound Operations for Numbers.

Table 1. Prefixes That Evaluate IP and MAC Addresses

Prefix Description

CLIENT.IP.SRC Returns the source IP of the current packet as

an IP address or as a number.
CLIENT.IP.DST Returns the destination IP of the current
packet as an IP address or as a number.
SERVER.IP.SRC Returns the source IP of the current packet as
an IP address or as a number.
SERVER.IP.DST Returns the destination IP of the current
packet as an IP address or as a number.

Operations for IPV4 Addresses

The following table describes the operators that can be used with prefixes that return an IPv4 address.

Prefix Description

<ip address>.EQ(<address>) Returns a Boolean TRUE if the IP address value

is same as the <address> argument. The
following example checks whether the client’s
destination IP address is equal to 10.100.10.100:
client.ip.dst.eq(10.100.10.100)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1312

NetScaler 12.0

Prefix Description

<ip address>.GET1. . .GET4 Returns a portion of an IP address as a numeric

value. For example, if the IP address value is
10.100.200.1, the following is returned:
client.ip.src.get1 Returns 10;
client.ip.src.get2 returns 100;
client.ip.src.get3 returns 200
<ip address>.IN_SUBNET(<subnet>) Returns a Boolean TRUE if the <subnet>
argument matches the subnet of the IP
address value. For example, the following
determines whether the client’s destination IP
address subnet is 10.100.10.100/18:
client.ip.dst.eq(10.100.10.100/18)
<ip address>.SUBNET(<n>) Returns the IP address after applying the
subnet mask specified as the argument. The
subnet mask can take values between 0 and
32. For example: CLIENT.IP.SRC.SUBNET
(24)returns 192.168.1.0 if the IP
address represented by the prefix
is 192.168.1.[0-255].
<ip address>.IS_IPV6 Returns a Boolean TRUE if this is an Internet
Protocol version 6 (IPv6) host for the client or
server. Following is an example:
client.ip.src.is_ipv6
<ip address>.MATCHES(<hostname>) Returns a Boolean TRUE if the IP address for
the host specified in <hostname> matches the
current IP address. The <hostname> cannot
exceed 255 characters.
<ip address>.MATCHES_LOCATION(< Returns a Boolean TRUE if the location of the IP
location>) address matches the <location> argument.
The Location string can take the following
form: qual1.qual2.qual3.qual4.qual5.qual6,
for example: NorthAmeria.CA.*
Following is an example: client.ip.
src.matches_location \”Europe.GB
.17.London.*.*\”)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1313

NetScaler 12.0

About IPv6 expressions

The IPv6 address format allows more flexibility than the older IPv4 format. IPv6 addresses are in the
hexadecimal format (RFC 2373). In the following examples, Example 1 is an IPv6 address, Example 2 is
a URL that includes the IPv6 address, and Example 3 includes the IPv6 address and a port number.

Example 1:

1 9901:0ab1:22a2:88a3:3333:4a4b:5555:6666

Example 2:

1 http://[9901:0ab1:22a2:88a3:3333:4a4b:5555:6666]/

Example 3:

1 https://[9901:0ab1:22a2:88a3:3333:4a4b:5555:6666]:8080/

In Example 3, the brackets separate the IP address from the port number (8080).

Note that you can only use the ‘+’ operator to combine IPv6 expressions with other expressions. The
output is a concatenation of the string values that are returned from the individual expressions. You
cannot use any other arithmetic operator with an IPv6 expression. The following syntax is an example:

1 client.ipv6.src + server.ip.dst

For example, if the client source IPv6 address is ABCD:1234::ABCD, and the server destination IPv4
address is 10.100.10.100, the preceding expression returns “ABCD:1234::ABCD10.100.10.100”.

Note that when the NetScaler appliance receives an IPv6 packet, it assigns a temporary IPv4 address
from an unused IPv4 address range and changes the source address of the packet to this temporary
address. At response time, the outgoing packet’s source address is replaced with the original IPv6
address.
Note

You can combine an IPv6 expression with any other expression except an expression that pro-
duces a Boolean result.

Expression prefixes for IPv6 addresses

The IPv6 addresses that are returned by the expression prefixes in the following table can be treated
as text data. For example, the prefix client.ipv6.dst returns the destination IPv6 address as a string
that can be evaluated as text.

The following table describes expression prefixes that return an IPv6 address.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1314

NetScaler 12.0

Table 3. IPv6 Expression Prefixes That Return Text

Prefix Description

CLIENT.IPV6 Operates on the IPv6 address in with the

current packet.
CLIENT.IPV6.DST Returns the IPv6 address in the destination
field of the IP header.
CLIENT.IPV6.SRC Returns the IPv6 address in the source field of
the IP header. Following are examples: client
.ipv6.src.in_subnet(2007::2008/64)
client.ipv6.src.get1.le(2008)
SERVER.IPV6 Operates on the IPv6 address in with the
current packet.
SERVER.IPV6.DST Returns the IPv6 address in the destination
field of the IP header.
SERVER.IPV6.SRC Returns the IPv6 address in the source field of
the IP header. Following are examples: server
.ipv6.src.in_subnet(2007::2008/64)
server.ipv6.src.get1.le(2008)

Operations for IPv6 prefixes

The following table describes the operators that can be used with prefixes that return an IPv6 address:

Table 4. Operations That Evaluate IPv6 Addresses

IPv6 Operation Description

<ipv6>.EQ(<IPv6_address> Returns a Boolean TRUE if the IP address value

is same as the argument. Following is an
example:
‘client.ipv6.dst.eq(ABCD:1234::ABCD)‘

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1315

NetScaler 12.0

IPv6 Operation Description

<ipv6>.GET1. . .GET8 Returns a segment of an IPv6 address as a

number. The following example expressions
retrieve segments from the ipv6 address
1000:1001:CD10:0000:0000:89AB:4567:CDEF:
client.ipv6.dst.get5 extracts 0000,
which is the fifth set of bits in the address.
client.ipv6.dst.get6 extracts 89AB.
client.ipv6.dst.get7 extracts 4567.
You can perform numeric operations on these
segments. Note that you cannot perform
numeric operations when you retrieve an
entire IPv6 address. This is because
expressions that return an entire IPv6 address,
such as CLIENT.IPV6.SRC, return the address in
text format.
<ipv6>.IN_SUBNET(<subnet>) Returns a Boolean TRUE if the IPv6 address
value is in the subnet specified by the
<subnet> argument. Following is an example:
client.ipv6.dst.eq(1000:1001:CD10
:0000:0000:89AB:4567:CDEF/60)
<ipv6>.IS_IPV4 Returns a Boolean TRUE if this is an IPv4 client,
and returns a Boolean FALSE if it is not.
<ipv6>.SUBNET(<n>) Returns the IPv6 address after applying the
subnet mask specified as the argument. The
subnet mask can take values between 0 and
128. For example:
CLIENT.IPV6.SRC.SUBNET(24)

Expressions for MAC addresses

A MAC address consists of colon-delimited hexadecimal values in the format ##:##:##:##:##:##, where
each “#” represents either a number from 0 through 9 or a letter from A through F. Default syntax
expression prefixes and operators are available for evaluating source and destination MAC addresses.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1316

NetScaler 12.0

Prefixes for MAC addresses

The following table describes prefixes that return MAC addresses.

Table 5. Prefixes That Evaluate MAC Addresses

Prefix Description

client.ether.dstmac Returns the MAC address in the destination

field of the Ethernet header.
client.ether.srcmac Returns the MAC address in the source field of
the Ethernet header.

Operations for MAC addresses

The following table describes the operators that can be used with prefixes that return a MAC address.

Table 6. Operations on MAC Addresses

Prefix Description

<mac address>.EQ(<address>) Returns a Boolean TRUE if the MAC address

value is same as the <address> argument.
<mac address>.GET1. . .GET4 Returns a numeric value extracted from the
segment of the MAC address that is specified in
the GET operation. For example, if the MAC
address is 12:34:56:78:9a:bc, the following
returns 34: client.ether.dstmac.get2

Expressions for Numeric Client and Server Data

The following table describes prefixes for working with numeric client and server data, including
throughput, port numbers, and VLAN IDs.

Table 7. Prefixes That Evaluate Numeric Client and Server Data

Prefix Description

client.interface.rxthroughput Returns an integer representing the raw

received traffic throughput in kilobytes per
second (KBps) for the previous seven seconds.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1317

NetScaler 12.0

Prefix Description

client.interface.txthroughput Returns an integer representing the raw

transmitted traffic throughput in KBps for the
previous seven seconds.
client.interface.rxtxthroughput Returns an integer representing the raw
received and transmitted traffic throughput in
KBps for the previous seven seconds.
server.interface.rxthroughput Returns an integer representing the raw
received traffic throughput in KBps for the
previous seven seconds.
server.interface.txthroughput Returns an integer representing the raw
transmitted traffic throughput in KBps for the
previous seven seconds.
server.interface.rxtxthroughput Returns an integer representing the raw
received and transmitted traffic throughput in
KBps for the previous seven seconds.
server.vlan.id Returns a numeric ID of the VLAN through
which the current packet entered the
NetScaler.
client.vlan.id Returns a numeric ID for the VLAN through
which the current packet entered the
NetScaler.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Advanced policy expressions: stream analytics functions

September 24, 2018

Contributed by:
C
Stream Analytics expressions begin with the ANALYTICS.STREAM(<identifier_name>) prefix. The fol-
lowing list describes the functions that can be used with this prefix.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1318

NetScaler 12.0

• COLLECT_STATS

Collect statistical data from the requests that are evaluated against the policy and create a
record for each request.

• REQUESTS

Return the number of requests that exist for the specified record grouping. The value returned
is of type unsigned long.

• BANDWIDTH

Return the bandwidth statistic for the specified record grouping. The value returned is of type
unsigned long.

• RESPTIME

Return the response time statistic for the specified record grouping. The value returned is of
type unsigned long.

• CONNECTIONS

Return the number of concurrent connections that exist for the specified record grouping. The
value returned is of type unsigned long.

• IS_TOP(n)

Return a Boolean
TRUE if the statistical value for the specified record grouping is one among the top
n groups. Otherwise, return a Boolean
FALSE.

• CHECK_LIMIT

Return a Boolean
TRUE if the statistic for the specified record grouping has hit the preconfigured limit. Otherwise,
return a Boolean
FALSE.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Advanced policy expressions: DataStream

September 24, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1319

NetScaler 12.0

Contributed by:
C

The policy infrastructure on the NetScaler appliance includes expressions that you can use to evaluate
and process database server traffic when the appliance is deployed between a farm of application
servers and their associated database servers.

This topic includes the following sections:

• Expressions for the MySQL Protocol

• Expressions for Evaluating Microsoft SQL Server Connections

Expressions for the MySQL protocol

The following expressions evaluate traffic associated with MySQL database servers. You can use the
request-based expressions (expressions that begin with MYSQL.CLIENT and MYSQL.REQ) in policies
to make request switching decisions at the content switching virtual server bind point and the
response-based expressions (expressions that begin with MYSQL.RES) to evaluate server responses
to user-configured health monitors.

• MYSQL.CLIENT. Operates on the client properties of a MySQL connection.

• MYSQL.CLIENT.CAPABILITIES. Returns the set of flags that the client has set in the capabilities
field of the handshake initialization packet during authentication. Examples of the flags that
are set are CLIENT_FOUND_ROWS, CLIENT_COMPRESS, and CLIENT_SSL.

• MYSQL.CLIENT.CHAR_SET. Returns the enumeration constant assigned to the character set

that the client uses. The EQ(<m>) and NE(<m>) operators, which return Boolean values to in-
dicate the result of a comparison, are used with this prefix. Following are the character set enu-
meration constants:

– LATIN2_CZECH_CS
– DEC8_SWEDISH_CI
– CP850_GENERAL_CI
– GREEK_GENERAL_CI
– LATIN1_GERMAN1_CI
– HP8_ENGLISH_CI
– KOI8R_GENERAL_CI
– LATIN1_SWEDISH_CI
– LATIN2_GENERAL_CI
– SWE7_SWEDISH_CI
– ASCII_GENERAL_CI
– CP1251_BULGARIAN_CI
– LATIN1_DANISH_CI

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1320

NetScaler 12.0

– HEBREW_GENERAL_CI
– LATIN7_ESTONIAN_CS
– LATIN2_HUNGARIAN_CI
– KOI8U_GENERAL_CI
– CP1251_UKRAINIAN_CI
– CP1250_GENERAL_CI
– LATIN2_CROATIAN_CI
– CP1257_LITHUANIAN_CI
– LATIN5_TURKISH_CI
– LATIN1_GERMAN2_CI
– ARMSCII8_GENERAL_CI
– UTF8_GENERAL_CI
– CP1250_CZECH_CS
– CP866_GENERAL_CI
– KEYBCS2_GENERAL_CI
– MACCE_GENERAL_CI
– MACROMAN_GENERAL_CI
– CP852_GENERAL_CI
– LATIN7_GENERAL_CI
– LATIN7_GENERAL_CS
– MACCE_BIN
– CP1250_CROATIAN_CI
– LATIN1_BIN
– LATIN1_GENERAL_CI
– LATIN1_GENERAL_CS
– CP1251_BIN
– CP1251_GENERAL_CI
– CP1251_GENERAL_CS
– MACROMAN_BIN
– CP1256_GENERAL_CI
– CP1257_BIN
– CP1257_GENERAL_CI
– ARMSCII8_BIN
– ASCII_BIN
– CP1250_BIN
– CP1256_BIN
– CP866_BIN
– DEC8_BIN
– GREEK_BIN

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1321

NetScaler 12.0

– HEBREW_BIN
– HP8_BIN
– KEYBCS2_BIN
– KOI8R_BIN
– KOI8U_BIN
– LATIN2_BIN
– LATIN5_BIN
– LATIN7_BIN
– CP850_BIN
– CP852_BIN
– SWE7_BIN
– UTF8_BIN
– GEOSTD8_GENERAL_CI
– GEOSTD8_BIN
– LATIN1_SPANISH_CI
– UTF8_UNICODE_CI
– UTF8_ICELANDIC_CI
– UTF8_LATVIAN_CI
– UTF8_ROMANIAN_CI
– UTF8_SLOVENIAN_CI
– UTF8_POLISH_CI
– UTF8_ESTONIAN_CI
– UTF8_SPANISH_CI
– UTF8_SWEDISH_CI
– UTF8_TURKISH_CI
– UTF8_CZECH_CI
– UTF8_DANISH_CI
– UTF8_LITHUANIAN_CI
– UTF8_SLOVAK_CI
– UTF8_SPANISH2_CI
– UTF8_ROMAN_CI
– UTF8_PERSIAN_CI
– UTF8_ESPERANTO_CI
– UTF8_HUNGARIAN_CI
– INVAL_CHARSET

• MYSQL.CLIENT.DATABASE. Returns the name of the database specified in the authentication

packet that the client sends to the database server. This is the databasename attribute.

• MYSQL.CLIENT.USER. Returns the user name (in the authentication packet) with which the client
is attempting to connect to the database. This is the user attribute.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1322

NetScaler 12.0

• MYSQL.REQ. Operates on a MySQL request.

• MYSQL.REQ.COMMAND. Identifies the enumeration constant assigned to the type of command

in the request. The EQ(<m>) and NE(<m>) operators, which return Boolean values to indicate
the result of a comparison, are used with this prefix. Following are the enumeration constant
values:

– SLEEP
– QUIT
– INIT_DB
– QUERY
– FIELD_LIST
– CREATE_DB
– DROP_DB
– REFRESH
– SHUTDOWN
– STATISTICS
– PROCESS_INFO
– CONNECT
– PROCESS_KILL
– DEBUG
– PING
– TIME
– DELAYED_INSERT
– CHANGE_USER
– BINLOG_DUMP
– TABLE_DUMP
– CONNECT_OUT
– REGISTER_SLAVE
– STMT_PREPARE
– STMT_EXECUTE
– STMT_SEND_LONG_DATA
– STMT_CLOSE
– STMT_RESET
– SET_OPTION
– STMT_FETCH

• MYSQL.REQ.QUERY. Identifies the query in the MySQL request.

• MYSQL.REQ.QUERY.COMMAND. Returns the first keyword in the MySQL query.

• MYSQL.REQ.QUERY.SIZE. Returns the size of the request query in integer format. The SIZE
method is similar to the CONTENT_LENGTH method that returns the length of an HTTP request

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1323

NetScaler 12.0

or response.

• MYSQL.REQ.QUERY.TEXT. Returns a string covering the entire query.

• MYSQL.REQ.QUERY.TEXT(<n>). Returns the first n bytes of the MySQL query as a string. This is
similar to HTTP.BODY(<n>).

Parameters:

n - Number of bytes to be returned

• MYSQL.RES. Operates on a MySQL response.

• MYSQL.RES.ATLEAST_ROWS_COUNT(<i>). Checks whether the response has at least i number

of rows and returns a Boolean TRUE or FALSE to indicate the result.

Parameters:

i - Number of rows

• MYSQL.RES.ERROR. Identifies the MySQL error object. The error object includes the error num-
ber and the error message.

• MYSQL.RES.ERROR.MESSAGE. Returns the error message that is retrieved from the server’s
error response.

• MYSQL.RES.ERROR.NUM. Returns the error number that is retrieved from the server’s error
response.

• MYSQL.RES.ERROR.SQLSTATE. Returns the value of the SQLSTATE field in the server’s error
response. The MySQL server translates error number values to SQLSTATE values.

• MYSQL.RES.FIELD(<i>). Identifies the packet that corresponds to the i^th individ-

ual field in the server’s response. Each field packet describes the properties of the associated
column. The packet count (i) begins at 0.

Parameters:

i - Packet number

• MYSQL.RES.FIELD(<i>).CATALOG. Returns the catalog property of the field packet.

• MYSQL.RES.FIELD(<i>).CHAR_SET. Returns the character set of the column. The EQ(<m>) and
NE(<m>) operators, which return Boolean values to indicate the result of a comparison, are used
with this prefix.

• MYSQL.RES.FIELD(<i>).DATATYPE. Returns an enumeration constant that represents the data

type of the column. This is the type (also called enum_field_type) attribute of the column. The
EQ(<m>) and NE(<m>) operators, which return Boolean values to indicate the result of a com-
parison, are used with this prefix. The possible values for the various data types are:

– DECIMAL

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1324

NetScaler 12.0

– TINY
– SHORT
– LONG
– FLOAT
– DOUBLE
– NULL
– TIMESTAMP
– LONGLONG
– INT24
– DATE
– TIME
– DATETIME
– YEAR
– NEWDATE
– VARCHAR (new in MySQL 5.0)
– BIT (new in MySQL 5.0)
– NEWDECIMAL (new in MySQL 5.0)
– ENUM
– SET
– TINY_BLOB
– MEDIUM_BLOB
– LONG_BLOB
– BLOB
– VAR_STRING
– STRING
– GEOMETRY

• MYSQL.RES.FIELD(<i>).DB. Returns the database identifier (db) attribute of the field packet.

• MYSQL.RES.FIELD(<i>).DECIMALS. Returns the number of positions after the decimal point if

the type is DECIMAL or NUMERIC. This is the decimals attribute of the field packet.

• MYSQL.RES.FIELD(<i>).FLAGS. Returns the flags property of the field packet. Following are
the possible hexadecimal flag values:

– 0001: NOT_NULL_FLAG
– 0002: PRI_KEY_FLAG
– 0004: UNIQUE_KEY_FLAG
– 0008: MULTIPLE_KEY_FLAG
– 0010: BLOB_FLAG
– 0020: UNSIGNED_FLAG
– 0040: ZEROFILL_FLAG

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1325

NetScaler 12.0

– 0080: BINARY_FLAG
– 0100: ENUM_FLAG
– 0200: AUTO_INCREMENT_FLAG
– 0400: TIMESTAMP_FLAG
– 0800: SET_FLAG

• MYSQL.RES.FIELD(<i>).LENGTH. Returns the length of the column. This is the value of the
length attribute of the field packet. The value that is returned might be larger than the actual
value. For example, an instance of a VARCHAR(2) column might return a value of 2 even when it
contains only one character.

• MYSQL.RES.FIELD(<i>).NAME. Returns the column identifier (the name after the AS clause, if
any). This is the name attribute of the field packet.

• MYSQL.RES.FIELD(<i>).ORIGINAL_NAME. Returns the original column identifier (before the

AS clause, if any). This is the org_name attribute of the field packet.

• MYSQL.RES.FIELD(<i>).ORIGINAL_TABLE. Returns the original table identifier of the column

(before the AS clause, if any). This is the org_table attribute of the field packet.

• MYSQL.RES.FIELD(<i>).TABLE. Returns the table identifier of the column (after the AS clause,
if any). This is the table attribute of the field packet.

• MYSQL.RES.FIELDS_COUNT. Returns the number of field packets in the response (the

field_count attribute of the OK packet).

• MYSQL.RES.OK. Identifies the OK packet sent by the database server.

• MYSQL.RES.OK.AFFECTED_ROWS. Returns the number of rows affected by an INSERT, UP-

DATE, or DELETE query. This is the value of the affected_rows attribute of the OK packet.

• MYSQL.RES.OK.INSERT_ID. Identifies the unique_id attribute of the OK packet. If an auto-

increment identity is not generated by the current MySQL statement or query, the value of
unique_id, and hence the value returned by the expression, is 0.

• MYSQL.RES.OK.MESSAGE. Returns the message property of the OK packet.

• MYSQL.RES.OK.STATUS. Identifies the bit string in the server_status attribute of the OK packet.
Clients can use the server status to check whether the current command is a part of a running
transaction. The bits in the server_status bit string correspond to the following fields (in the
given order):

– IN TRANSACTION
– AUTO_COMMIT
– MORE RESULTS
– MULTI QUERY
– BAD INDEX USED

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1326

NetScaler 12.0

– NO INDEX USED
– CURSOR EXISTS
– LAST ROW SEEN
– DATABASE DROPPED
– NO BACKSLASH ESCAPES

• MYSQL.RES.OK.WARNING_COUNT. Returns the warning_count attribute of the OK packet.

• MYSQL.RES.ROW(<i>). Identifies the packet that corresponds to the i^th individual

row in the database server’s response.

Parameters:

i - Row number

• MYSQL.RES.ROW(<i>).DOUBLE_ELEM(<j>). Checks whether the j^th column of

the i^th row of the table is NULL. Following C conventions, both indexes i and j
start from 0. Therefore, row i and column j are actually the (i+1)^th row and the
(j+1)^th column, respectively.

Parameters:

i - Row number

j - Column number

• MYSQL.RES.ROW(<i>).IS_NULL_ELEM(j). Checks whether the j^th column of

the i^th row of the table is NULL. Following C conventions, both indexes i and j
start from 0. Therefore, row i and column j are actually the (i+1)^th row and the
(j+1)^th column, respectively.

Parameters:

i - Row number

j - Column number

• MYSQL.RES.ROW(<i>).NUM_ELEM(<j>). Returns an integer value from the j^th col-

umn of the i^th row of the table. Following C conventions, both indexes i and j
start from 0. Therefore, row i and column j are actually the (i+1)^th row and the
(j+1)^th column, respectively.

Parameters:

i - Row number

j - Column number

• MYSQL.RES.ROW(<i>).TEXT_ELEM(j). Returns a string from the j^th column

of the i^th row of the table. Following C conventions, both indexes i and j start

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1327

NetScaler 12.0

from 0. Therefore, row i and column j are actually the (i+1)^th row and the
(j+1)^th column, respectively.

Parameters:

i - Row number

j - Column number

• MYSQL.RES.TYPE. Returns an enumeration constant for the response type. Its values can be ER-
ROR, OK, and RESULT_SET. The EQ(<m>) and NE(<m>) operators, which return Boolean values
to indicate the result of a comparison, are used with this prefix.

Expressions for evaluating Microsoft SQL server connections

The following expressions evaluate traffic associated with Microsoft SQL Server database servers. You
can use the request-based expressions (expressions that begin with MSSQL.CLIENT and MSSQL.REQ)
in policies to make request switching decisions at the content switching virtual server bind point
and the response-based expressions (expressions that begin with MSSQL.RES) to evaluate server re-
sponses to user-configured health monitors.

Expression Description

MSSQL.CLIENT.CAPABILITIES Returns
the OptionFlags1, OptionFlags2, OptionFlags3,
and TypeFlags fields of
the LOGIN7authentication packet, in that
order, as a 4-byte integer. Each field is 1 byte
long and specifies a set of client capabilities.
MSSQL.CLIENT.DATABASE Returns the name of the client database. The
value returned is of type text.
MSSQL.CLIENT.USER Returns the user name with which the client
authenticated. The value returned is of
type text.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1328

NetScaler 12.0

Expression Description

MSSQL.REQ.COMMAND Returns an enumeration constant that

identifies the type of command in the request
sent to a Microsoft SQL Server database server.
The value returned is of type text. Examples of
the values of the enumeration constant
are QUERY, RESPONSE, RPC, and ATTENTION.
The EQ(<m>) and NE(<m>) operators, which
return Boolean values to indicate the result of
a comparison, are used with this expression.
MSSQL.REQ.QUERY.COMMAND Returns the first keyword in the SQL query. The
value returned is of type text.
MSSQL.REQ.QUERY.SIZE Returns the size of the SQL query in the
request. The value returned is a number.
MSSQL.REQ.QUERY.TEXT Returns the entire SQL query as a string. The
value returned is of type text.
MSSQL.REQ.QUERY.TEXT(<n>) Returns the first n bytes of the SQL query. The
value returned is of type text. Parameters: n -
Number of bytes
MSSQL.REQ.RPC.NAME Returns the name of the procedure that is
being called in a remote procedure call (RPC)
request. The name is returned as a string.
MSSQL.REQ.RPC.IS_PROCID Returns a Boolean value that indicates whether
the remote procedure call (RPC) request
contains a procedure ID or an RPC name. A
return value of TRUEindicates that the request
contains a procedure ID and a return value
of FALSE indicates that the request contains an
RPC name.
MSSQL.REQ.RPC.PROCID Returns the procedure ID of the remote
procedure call (RPC) request as an integer.
MSSQL.REQ.RPC.BODY
Note: Not available for releases before 10.1. Returns the body of the SQL request as a string
in the form of parameters represented as “a=b”
clauses separated by commas, where “a” is the
RPC parameter name and “b” is its value.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1329

NetScaler 12.0

Expression Description

MSSQL.REQ.RPC.BODY(n)
Note: Not available for releases before 10.1. Returns part of the body of the SQL request as
a string in the form of parameters represented
as “a=b” clauses separated by commas, where
“a” is the RPC parameter name and “b” is its
value. Parameters are returned from only the
first “n” bytes of the request, skipping the SQL
header. Only complete name-value pairs are
returned.
MSSQL.RES.ATLEAST_ROWS_COUNT(i) Checks whether the response has at
least i number of rows. The value returned is a
Boolean TRUE or FALSEvalue. Parameters: i -
Number of rows
MSSQL.RES.DONE.ROWCOUNT Returns a count of the number of rows affected
by an INSERT, UPDATE, or DELETE query. The
value returned is of type unsigned long.
MSSQL.RES.DONE.STATUS Returns the status field from the DONE token
sent by a Microsoft SQL Server database server.
The value returned is a number.
MSSQL.RES.ERROR.MESSAGE Returns the error message from
the ERROR token sent by a Microsoft SQL
Server database server. This is the value of
the MsgText field in the ERROR token. The
value returned is of type text.
MSSQL.RES.ERROR.NUM Returns the error number from
the ERROR token sent by a Microsoft SQL
Server database server. This is the value of
the Number field in the ERROR token. The
value returned is a number.
MSSQL.RES.ERROR.STATE Returns the error state from the ERROR token
sent by a Microsoft SQL Server database server.
This is the value of the State field in
the ERROR token. The value returned is a
number.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1330

NetScaler 12.0

Expression Description

MSSQL.RES.FIELD(<i>).DATATYPE Returns the data type of the ith field in the

server response.
The EQ(<m>) and NE(<m>) functions, which
return Boolean values to indicate the result of
a comparison, are used with this prefix. For
example, the following expression returns a
Boolean TRUE if the DATATYPE function returns
a value of datetime for the third field in the re-
sponse: MSSQL.RES.FIELD(<2>).DATATYPE.EQ(datetime) Pa-
rameters: i - Row
number
MSSQL.RES.FIELD(<i>).LENGTH Returns the maximum possible length of
the ith field in the server response. The value
returned is a number. Parameters: i - Row
number
MSSQL.RES.FIELD(<i>).NAME Returns the name of the ith field in the server
response. The value returned is of
type text. Parameters: i - Row number
MSSQL.RES.ROW(<i>).DOUBLE_ELEM(<j>) Returns a value of type double from
the jth column of the ith row of the table. If the
value is not a double value,
an UNDEF condition is raised. Following C
conventions, both indexes i and j start from 0
(zero). Therefore, row i and column j are
actually the (i + 1)th row and the (j +
1)th column, respectively. Parameters: i - Row
number j - Column number
MSSQL.RES.ROW(<i>).NUM_ELEM(j) Returns an integer value from the jth column
of ith row of the table. If the value is not an
integer value, an UNDEF condition is raised.
Following C conventions, both
indexes i and j start from 0 (zero). Therefore,
row i and column j are actually the (i + 1)th row
and the (j + 1)th column,
respectively. Parameters: i - Row number j -
Column number

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1331

NetScaler 12.0

Expression Description

MSSQL.RES.ROW(<i>).IS_NULL_ELEM(j) Checks whether the jth column of the ith row

of the table is NULL and returns a
Boolean TRUE or FALSE to indicate the result.
Following C conventions, both
indexes i and j start from 0 (zero). Therefore,
row iand column j are actually the (i + 1)th row
and the (j + 1)th column,
respectively. Parameters: i - Row number j -
Column number
MSSQL.RES.ROW(<i>).TEXT_ELEM(j) Returns a text string from the jth column
of ith row of the table. Following C
conventions, both indexes i and j start from 0
(zero). Therefore, row i and column j are
actually the (i + 1)th row and the (j +
1)th column, respectively. Parameters: i - Row
number j - Column number
MSSQL.RES.TYPE Returns an enumeration constant that
identifies the response type. Following are the
possible return values: ERROR, OK, and
RESULT_SET.
The EQ(<m>) and NE(<m>) operators, which
return Boolean values to indicate the result of
a comparison, are used with this expression.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Typecasting data

January 6, 2019

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1332

NetScaler 12.0

You can extract data of one type (for example, text or an integer) from requests and responses and
transform it to data of another type. For example, you can extract a string and transform the string to
time format. You can also extract a string from an HTTP request body and treat it like an HTTP header
or extract a value from one type of request header and insert it in a response header of a different type.

After typecasting the data, you can apply any operation that is appropriate for the new data type. For
example, if you typecast text to an HTTP header, you can apply any operation that is applicable to
HTTP headers to the returned value.

For more information about typecasting data, see the Typecasting Operations pdf.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Regular Expressions

March 14, 2019

Contributed by:
C

When you want to perform string matching operations that are more complex than the operations that
you perform with the CONTAINS(“<string>”) or EQ(“<string>“) operators, you use regular expressions.
The policy infrastructure on the Citrix® NetScaler® appliance includes operators to which you can pass
regular expressions as arguments for text matching. The names of the operators that work with reg-
ular expressions include the string REGEX. The regular expressions that you pass as arguments must
conform to the regular expression syntax that is described in “http://www.pcre.org/pcre.txt.” You can
learn more about regular expressions at “http://www.regular-expressions.info/quickstart.html” and
at “http://www.silverstones.com/thebat/Regex.html.”

The target text for an operator that works with regular expressions can be either text or the value of
an HTTP header. Following is the format of a default syntax expression that uses a regular expression
operator to operate on text:

<text>.<regex_operator>(re<delimiter><regex_pattern><delimiter>)

The string <text> represents the default syntax expression prefix that identifies a text string in a
packet (for example, HTTP.REQ.URL). The string <regex_operator> represents the regular expres-
sion operator. The regular expression always
begins with the string re. A pair of matching delimiters, represented by <delimiter>, enclose the
string <regex_pattern>, which represents the regular expression.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1333

NetScaler 12.0

The following example expression checks whether the URL in an HTTP packet contains the string *.
jpeg (where * is a wildcard) and returns a Boolean TRUE or FALSE to indicate the result. T he regular
expression is enclosed within a pair of
slash marks (/), which act as delimiters..

http.req.url.regex_match(re/.<asterisk>\.jpeg/)

Regular expression operators can be combined to define or refine the scope of a search. For exam-
ple, <text>.AFTER_REGEX(re/regex_pattern1/).BEFORE_REGEX(re/regex_pattern2/) specifies that the
target for string matching is the text between the patterns regex_pattern1 and regex_pattern2. You
can use a text operator on the scope that is defined by the regular expression operators. For exam-
ple, you can use the CONTAINS(“<string>”) operator to check whether the defined scope contains the
string abc:

<text>.AFTER_REGEX(re/regex_pattern1/).BEFORE_REGEX(re/regex_pattern2/).CONTAINS(“abc”)

Note

The process of evaluating a regular expression inherently takes more time than that for an oper-
ator such as CONTAINS(“<string>”) or EQ(“<string>”), which work with simple string arguments.
You should use regular expressions only if your requirement is beyond the scope of other opera-
tors.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Basic characteristics of regular expressions

September 24, 2018

Contributed by:
C

Following are notable characteristics of regular expressions as defined on the NetScaler appliance:

• A regular expression always begins with the string “re” followed by a pair of delimiting charac-
ters (called delimiters) that enclose the regular expression that you want to use.

For example, re#<regex_pattern># uses the number sign (#) as a delimiter.

• A regular expression cannot exceed 1499 characters.

• Digit matching can be done by using the string \d (a backslash followed by d).

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1334

NetScaler 12.0

• White space can be represented by using \s (a backslash followed by s).

• A regular expression can contain white spaces.

Following are the differences between the NetScaler syntax and the PCRE syntax:

• The NetScaler does not allow back references in regular expressions.

• You should not use recursive regular expressions.
• The dot meta-character also matches the newline character.
• Unicode is not supported.
• The operation SET_TEXT_MODE(IGNORECASE) overrides the (?i) internal option in the regular
expression.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Operations for regular expressions

September 24, 2018

Contributed by:
C

The following table describes the operators that work with regular expressions. The operation per-
formed by a regular expression operator in a given default syntax expression depends on whether the
expression prefix identifies text or HTTP headers. Operations that evaluate headers override any text-
based operations for all instances of the specified header type. When you use an operator, replace
<text> with the default syntax expression prefix that you want to configure for identifying text.

Regular Expression Operation Description

<text>.BEFORE_REGEX(<regular expression>) Selects the text that precedes the string that
matches the <regular expression> argument. If
the regular expression does not match any
data in the target, the expression returns a text
object of length 0. The following expression
selects the string “text” from
“text/plain”. http.res.header(“content-
type”).before_regex(re#/#)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1335

NetScaler 12.0

Regular Expression Operation Description

<text>.AFTER_REGEX(<regular expression>) Selects the text that follows the string that
matches the <regular expression> argument. If
the regular expression does not match any text
in the target, the expression returns a text
object of length 0. The following expression
extracts “Example” from “myExam-
ple”: http.req.header(“etag”).after_regex(re/my/)
<text>.REGEX_SELECT(<regular expression>) Selects a string that matches the <regular
expression> argument. If the regular
expression does not match the target, a text
object of length 0 is returned. The following
example extracts the string “NS-CACHE-9.0:
90” from a Via
header: http.req.header(“via”).regex_select(re!NS-
CACHE-\d.\d:\s*\d{1,3}!)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1336

NetScaler 12.0

Regular Expression Operation Description

<text>.REGEX_MATCH(<regular expression>) Returns TRUE if the target matches a <regular

expression> argument of up to 1499
characters. The regular expression must be of
the following format: re<delimiter>regular
expression< delimiter> Both delimiters must
be the same. Additionally, the regular
expression must conform to the
Perl-compatible (PCRE) regular expression
library syntax. For more information, go
to http://www.pcre.org/pcre.txt. In particular,
see the pcrepattern man page. However, note
the following: Back-references are not allowed.
Recursive regular expressions are not
recommended. The dot metacharacter also
matches the newline character. The Unicode
character set is not supported.
SET_TEXT_MODE(IGNORECASE) overrides
the (?i) internal option specified in the regular
expression. The following are examples:
http.req.hostname.regex_match(re/[[:alpha:]]+(abc){2,3}/)
and
http.req.url.set_text_mode(urlencoded).regex_match(re#(ab+
The following example matches ab and
aB: http.req.url.regex_match(re/a(?i)b/) The
following example matches ab, aB, Ab and
AB: http.req.url.set_text_mode(ignorecase).regex_match(re/a
following example performs a case-insensitive,
multiline match in which the dot
meta-character also matches a newline charac-
ter: http.req.body.regex_match(re/(?ixm) (ˆab
(.*) cd$) /)

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1337

NetScaler 12.0

Configuring classic policies and expressions

January 6, 2019
Contributed by:
C
Some NetScaler features use classic policies and classic expressions. As with default syntax policies,
classic policies can be either global or specific to a virtual server. However, to a certain extent, the
configuration method and bind points for classic policies are different from those of default syntax
policies. As with default syntax expressions, you can configure named expressions and use a named
expression in multiple classic policies.
The following table summarizes NetScaler features that can be configured by using classic policies.
Click here to view the table.
1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configure a classic policy

September 24, 2018

Contributed by:
C
You can configure classic policies and classic expressions by using either the GUI or the command-
line interface. A policy rule cannot exceed 1,499 characters. When configuring the policy rule, you can
use named classic expressions. For more information about named expressions, see Create named
classic expressions. After configuring the policy, you bind it either globally or to a virtual server.
Note that there are small variations in the policy configuration methods for various NetScaler features.
Note: You can embed a classic expression in a default syntax expression by using the syntax
SYS.EVAL_CLASSIC_EXPR(classic_expression), specifying the classic_expression as the argument.

Create a classic policy by using the CLI

At the command prompt, type the following commands to set the parameters and verify the configu-
ration:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1338

NetScaler 12.0

1 - add cmp policy <name> -rule <expression> -action <action>

2
3 - show cmp policy [<policyName>]

Example

The following commands first create a compression action and then create a compression policy that
applies the action:

1 > add cmp action cmp-act-compress compress

2 Done
3 > show cmp action cmp-act-compress
4 1) Name: cmp-act-compress Compression Type: compress
5 Done
6 > add cmp pol cmp-pol-compress -rule ExpCheckIp -resAction cmp-act-
compress
7 Done
8 > show cmp pol cmp-pol-compress
9 1) Name: cmp-pol-compress Rule: ExpCheckIp
10 Response action: cmp-act-compress Hits: 0
11 Done
12 >

Create a policy with classic expressions by using the GUI

1. In the navigation pane, expand the feature for which you want to configure a policy and, de-
pending on the feature, do the following:

• For Content Switching, Cache Redirection, and the application firewall, click Policies.
• For SSL, click Policies, and then in the details pane, click the Policies tab.
• For System Authentication, click Authentication, and then in the details pane, click the
Policies tab.
• For Filter, SureConnect, and Priority Queuing, expand Protection Features, select the de-
sired function, and then in the details pane, click the Policies tab.
• For the NetScaler Gateway, expand NetScaler Gateway, expand Policies, select the desired
function, and then in the details pane, click the Policies tab.

2. For most features, click the Add button.

3. In the Create <feature name> Policy dialog box, in the Name* text box, enter a name for the
policy.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1339

NetScaler 12.0

Note: You must begin a policy name with a letter or underscore. A policy name can consist of 1
to 31 characters, including letters, numbers, hyphen (-), period (.), pound sign (#), space ( ), and
underscore (_).

4. For most features, you associate an action or a profile. For example, you may be required to
select an action, or, in the case of an NetScaler Gateway or application firewall policy, you select
a profile to associate with the policy. A profile is a set of configuration options that operate as a
set of actions that are applied when the data being analyzed matches the policy rule.

5. Create an expression that describes the type of data that you want this policy to match.

Depending on the type of policy you want to create, you can choose a predefined expression,
or you can create a new expression.

Named expressions are predefined expressions that you can reference by name in a policy rule.

6. Click Create to create your new policy.

7. Click Close to return to the Policies screen for the type of policy you were creating.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configure a classic expression

September 24, 2018

Contributed by:
C

Classic expressions consist of the following expression elements, listed in hierarchical order:

• Flow Type. Specifies whether the connection is incoming or outgoing. The flow type is REQ for
incoming connections and RES for outgoing connections.
• Protocol. Specifies the protocol, the choices for which are HTTP, SSL, TCP, and IP.
• Qualifier. The protocol attribute, which depends on the selected protocol.
• Operator. The type of test you want to perform on the connection data. Your choice of operator
depends upon the connection information you are testing. If the connection information you
are testing is text, you use text operators. If it is a number, you use standard numeric operators.
• Value. The string or number against which the connection data element—defined by the flow
type, protocol, and qualifier—is tested. The value can be either a literal or an expression. The
literal or expression must match the data type of the connection data element.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1340

NetScaler 12.0

In a policy, classic expressions can be combined to create more complex expressions using Boolean
and comparative operators.

Expression elements are parsed from left to right. The leftmost element is either REQ or RES and des-
ignates a request or a response, respectively. Successive terms define a specific connection type and
a specific attribute for that connection type. Each term is separated from any preceding or following
term by a period. Arguments appear in parentheses and follow the expression element to which they
are passed.

The following classic expression fragment returns the client source IP for an incoming connection.

REQ.IP.SOURCEIP

The example identifies an IP address in a request. The expression element SOURCEIP designates the
source IP address. This expression fragment may not be useful by itself. You can use an additional
expression element, an operator, to determine whether the returned value meets specific criteria.
The following expression tests whether the client IP is in the subnet 200.0.0.0/8 and returns a Boolean
TRUE or FALSE:

REQ.IP.SOURCEIP == 200.0.0.0 -netmask 255.0.0.0

Create a classic policy expression by using the CLI

At the command prompt, type the following commands to set the parameters and verify the configu-
ration:

1 - set appfw policy \<name\> -rule \<expression\> -action \<action\>

2
3 - show appfw policy \<name\>

Example

1 > set appfw policy GenericApplicationSSL_ ’HTTP.REQ.METHOD.EQ(”get”)’

APPFW_DROP
2 Done
3 > show appfw policy GenericApplicationSSL_
4 Name: GenericApplicationSSL_ Rule: HTTP.REQ.METHOD.EQ(”get”)
5 Profile: APPFW_DROP Hits: 0
6 Undef Hits: 0
7 Policy is bound to following entities
8 1) REQ VSERVER app_u_GenericApplicationSSLPortalPages
PRIORITY : 100
9 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1341

NetScaler 12.0

Add an expression for a classic policy by using the GUI

This procedure documents the Add Expression dialog box. Depending on the feature for which you
are configuring a policy, the route by which you arrive at this dialog box may be different.

1. Perform steps 1-4 in “To create a policy with classic expressions by using the GUI.”

2. In the Add Expression dialog box, in Expression Type, click the type of expression you want to
create.

3. Under Flow Type, click the down arrow and choose a flow type.

The flow type is typically REQ or RES. The REQ option specifies that the policy applies to all in-
coming connections or requests. The RES option applies the policy to all outgoing connections
or responses.

For Application Firewall policies, you should leave the expression type set to General Expres-
sion, and the flow type set to REQ. The Application Firewall treats each request and response as
a single paired entity, so all Application Firewall policies begin with REQ.

4. Under Protocol, click the down arrow and choose the protocol you want for your policy expres-
sion. Your choices are:

• HTTP. Evaluates HTTP requests that are sent to a Web server. For classic expressions, HTTP
includes HTTPS requests.
• SSL. Evaluates SSL data associated with the current connection.
• TCP. Evaluates the TCP data associated with the current connection.
• IP. Evaluates the IP addresses associated with the current connection.

5. Under Qualifier, click the down arrow and choose a qualifier for your policy.

The qualifier defines the type of data to be evaluated. The list of qualifiers that appears depends
on which protocol you selected in step 4.

The following choices appear for the HTTP protocol:

• METHOD. Filters HTTP requests that use a particular HTTP method.

• URL. Filters HTTP requests for a specific Web page.
• URLQUERY. Filters HTTP requests that contain a particular query string.
• VERSION. Filters HTTP requests on the basis of the specified HTTP protocol version.
• HEADER. Filters on the basis of a particular HTTP header.
• URLLEN. Filters on the basis of the length of the URL.
• URLQUERY. Filters on the basis of the query portion of the URL.
• URLQUERYLEN. Filters on the basis of the length of the query portion of the URL only.

6. Under Operator, click the down arrow and choose the operator for your policy expression. Some
common operators are:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1342

NetScaler 12.0

Operator Description

== Matches the specified value exactly or is

exactly equal to the specified value.
!= Does not match the specified value.
> Is greater than the specified value.
< Is less than the specified value.
>= Is greater than or equal to the specified value.
<= Is less than or equal to the specified value.
CONTAINS Contains the specified value.
CONTENTS Returns the contents of the designated header,
URL, or URL query.
EXISTS The specified header or query exists.
NOTCONTAINS Does not contain the specified value.
NOTEXISTS The specified header or query does not exist.

7. If a Value text box appears, type a string or numeric value, as appropriate. For example, chose
REQ as the Flow Type, HTTP as the Protocol, and HEADER as the qualifier, and then type the
value of the header string in the Value field and the header type for which you want to match
the string in the Header Name text box.

8. Click OK.

9. To create a compound expression, click Add. Note that the type of compounding that is done
depends on the following choices in the Create Policy dialog box:

• Match Any Expression. The expressions are in a logical OR relationship.

• Match All Expressions. The expressions are in a logical AND relationship.
• Tabular Expressions. Click the AND, OR, and parentheses buttons to control evaluation.
• Advanced Free-Form. Enter the expressions components directly into the Expression
field, and click the AND, OR, and parentheses buttons to control evaluation.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1343

NetScaler 12.0

Bind a classic policy

September 24, 2018

Contributed by:
C

Depending on the policy type, you can bind a classic policy either globally or to a virtual server. Policy
bind points are described in the table, “Policy Type and Bind Points for Policies in Features That Use
Classic Policies.”

Note: You can bind a classic policy to multiple bind points.

Bind a classic policy globally by using the CLI

At the command prompt, type the following commands to set the parameters and verify the configu-
ration:

1 - bind cmp global <policyName> [-priority <positive_integer>]

2
3 - show cmp global

Example

1 > bind cmp global cmp-pol-compress -priority 2

2 Done
3 > show cmp global
4 1) Policy Name: cmp-pol-compress Priority: 2
5 2) Policy Name: ns_nocmp_xml_ie Priority: 8700
6 3) Policy Name: ns_nocmp_mozilla_47 Priority: 8800
7 4) Policy Name: ns_cmp_mscss Priority: 8900
8 5) Policy Name: ns_cmp_msapp Priority: 9000
9 6) Policy Name: ns_cmp_content_type Priority: 10000
10 Done
11 >

Bind a classic policy to a virtual server by using the CLI

At the command prompt, type the following commands to set the parameters and verify the configu-
ration:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1344

NetScaler 12.0

1 - bind lb vserver <name> [<targetVserver>] [-policyName <string> [-

priority <positive_integer>]
2
3 - show lb vserver<name>

Example

1 > bind lb vserver lbtemp -policyName cmp-pol-compress -priority 1

2 Done
3 > show lb vserver lbtemp
4 lbtemp (10.102.29.101:80) - HTTP Type: ADDRESS
5 State: UP
6 Last state change was at Tue Oct 27 06:40:38 2009 (+557 ms)
7 Time since last state change: 0 days, 02:00:40.330
8 Effective State: UP
9 Client Idle Timeout: 180 sec
10 Down state flush: ENABLED
11 Disable Primary Vserver On Down : DISABLED
12 Port Rewrite : DISABLED
13 No. of Bound Services : 1 (Total) 1 (Active)
14 Configured Method: LEASTCONNECTION
15 Current Method: Round Robin, Reason: Bound service’s state
changed to UP
16 Group: vserver-grp
17 Mode: IP
18 Persistence: COOKIEINSERT (version 0) Persistence Backup:
SOURCEIP Persistence Mask: 255.255.255.255
19 Persistence Timeout: 2 min Backup Persistence Timeout: 2
min
20 Vserver IP and Port insertion: OFF
21 Push: DISABLED Push VServer:
22 Push Multi Clients: NO
23 Push Label Rule: none
24 1) http-one (10.102.29.252: 80) - HTTP State: UP Weight: 1
25 Persistence Cookie Value : NSC_wtfswfs-hsq=
ffffffff096e03ed45525d5f4f58455e445a4a423660
26 1) Policy : cmp-pol-compress Priority:1
27 Done
28 >

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1345

NetScaler 12.0

Bind a classic policy globally by using the GUI

Note: This procedure documents the Global Bindings dialog box. Depending on the feature for which
you want to globally bind a policy, the route by which you arrive at this dialog box may be different.

1. In the navigation pane, expand the feature for which you want to globally bind a classic policy,
and then locate the policy that you want to bind globally.

Note: You cannot globally bind policies for Content Switching, Cache Redirection, SureConnect,
Priority Queuing, or
NetScaler Gateway Authorization.

2. In the details pane, click Global Bindings.

3. In the Bind/Unbind <feature name> Policy(s) to Global dialog box, click Insert Policy.

4. In the Policy Name column, click the name of an existing policy that you want to globally bind,
or click New Policy to open the Create <feature name> Policy dialog box.

5. After you have selected the policy or created a new policy, in the Priority column, type the pri-
ority value.

The lower the number, the sooner this policy is applied relative to other policies. For example,
a policy assigned a priority of 10 is applied before a policy with a priority of 100. You can use
the same priority for different policies. All features that use classic policies implement only the
first policy that a connection matches, so policy priority is important for getting the results you
intend.

As a best practice, leave room to add policies by setting priorities with intervals of 50 (or 100)
between each policy.

6. Click OK.

Bind a classic policy to a virtual server by using the GUI

1. In the navigation pane, expand the feature that contains the virtual server to which you want
to bind a classic policy (for example, if you want to bind a classic policy to a content switching
virtual server, expand Traffic Management > Content Switching), and then click Virtual Servers.

2. In the details pane, select the virtual server, and then click Open.

3. In the Configure <Feature> Virtual Server dialog box, on the Policies tab, click the feature icon
for the type policy that you want, and then click Insert Policy.

4. In the Policy Name column, click the name of an existing policy that you want to bind to a virtual
server, or click A to open the Create <feature name> Policy dialog box.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1346

NetScaler 12.0

5. After you have selected the policy or created a new policy, in the Priority column, set the priority.

If you are binding a policy to a content switching virtual server, in the Target column, select a
load balancing virtual server to which traffic that matches the policy should be sent.

6. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

View classic policies

September 24, 2018

Contributed by:
C

You can view classic policies by using either the GUI or the command line. You can view details such
as the policy’s name, expression, and bindings.

View a classic policy and its binding information by using the CLI

At the command prompt, type the following commands to view a classic policy and its binding infor-
mation:

show <featureName> policy [policyName]

Example

1 > show appfw policy GenericApplicationSSL_

2 Name: GenericApplicationSSL_ Rule: ns_only_get_adv
3 Profile: GenericApplicationSSL_Prof1 Hits: 0
4 Undef Hits: 0
5 Policy is bound to following entities
6 1) REQ VSERVER app_u_GenericApplicationSSLPortalPages
PRIORITY : 100
7 Done

Note: If you omit the policy name, all policies are listed without the binding details.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1347

NetScaler 12.0

View classic policies and policy bindings by using the GUI

1. In the navigation pane, expand the feature whose policies you want to view, (for example, if you
want to view application firewall policies, expand Application Firewall), and then click Policies.
2. In the details pane, do one or more of the following:
• To view details for a specific policy, click the policy. Details appear in the Details area of
the configuration pane.
• To view bindings for a specific policy, click the policy, and then click Show Bindings.
• To view global bindings, click the policy, and then click Global Bindings. Note that you
cannot bind a Content Switching, Cache Redirection, SureConnect, Priority Queuing, or
NetScaler Gateway Authorization policy globally.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Create named classic expressions

September 24, 2018

Contributed by:
C

A named classic expression is a classic expression that can be referenced through an assigned name.
Often, you need to configure classic expressions that are large or complex and form a part of a larger
compound expression. You might also configure classic expressions that you need to use frequently
and in multiple compound expressions or classic policies. In these scenarios, you can create the clas-
sic expression you want, save it with a name of your choice, and then reference the expression from
compound expressions or policies through its name. This saves configuration time and improves the
readability of complex compound expressions. Additionally, any modifications to a named classic
expression need to be made only once.

Some named expressions are built-in, and a subset of these are read-only. Built-in named expressions
are divided into four categories: General, Anti-Virus, Personal Firewall, and Internet Security. General
named expressions have a wide variety of uses. For example, from the General category, you can use
the expressions ns_true and ns_false to specify a value of TRUE or FALSE, respectively, to be returned
for all traffic. You can also identify data of a particular type (for example, HTM, DOC, or GIF files),
determine whether caching headers are present, or determine whether the round trip time for packets
between a client and the NetScaler is high (over 80 milliseconds).

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1348

NetScaler 12.0

Anti-Virus, Personal Firewall, and Internet Security named expressions test clients for the presence of
a particular program and version and are used primarily in NetScaler Gateway policies.

Note: You cannot modify or delete built-in named expressions.

Create a named classic expression by using the CLI

At the command prompt, type the following commands to set the parameters and verify the configu-
ration:

1 - add expression <name> <value> [-comment <string>] [-

clientSecurityMessage <string>]
2 - show expression [<name> | -type CLASSIC

Example

1 > add expression classic_ne ”REQ.HTTP.URL CONTAINS www.example1.com” -

comment ”Checking the URL for www.example1.com”
2 Done
3 > show expression classic_ne
4 1) Name: classic_ne Expr: REQ.HTTP.URL CONTAINS www.example1.com
Hits: 0 Type : CLASSIC
5 Comment: ”Checking the URL for www.example1.com”
6 Done
7 >

Create a named classic expression by using the GUI

1. In the navigation pane, expand AppExpert, expand Expressions, and then click Classic Expres-
sions.

2. In the details pane, click Add.

Note: Some of the built-in expressions in the Expressions list are read-only.

3. In the Create Policy Expression dialog box, specify values for the following parameters:

• Expression Name*—name
• Client Security Message—clientSecurityMessage
• Comments—comment

*A required parameter

4. To create the expression, do one of the following:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1349

NetScaler 12.0

• You can choose inputs to this expression from the Named Expressions drop-down list.
• You can create a new expression, as described in Add an expression for a classic policy by
using the GUI.

5. When you are done, click Close. Verify that your new expression was created by scrolling to the
bottom of the Classic Expressions list to view it.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Expressions reference-advanced policy expressions

January 6, 2019

Contributed by:
C
Warning

Q and S prefixes are deprecated from NetScaler 12.0 build 56.20 onwards and are no longer sup-
ported in Advanced policy expressions.

The following table is a listing of default syntax expression prefixes, with cross-references to descrip-
tions of these prefixes and the operators that you can specify for them. Note that some prefixes can
work with multiple types of operators. For example, a cookie can be parsed by using operators for
text or operators for HTTP headers.

You can use any element in the following tables as a complete expression on its own, or you can use
various operators to combine these expression elements with others to form more complex expres-
sions.

Note: The Description column in the following table contains cross-references to additional informa-
tion about prefix usage and applicable operators for the prefix.

Click here to view the table.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1350

NetScaler 12.0

Expressions reference-classic expressions

January 6, 2019

Contributed by:
C
Warning

Classic policy expressions are no longer supported from NetScaler 12.0 build 56.20 onwards and
as an alternative, Citrix recommends you to use Advanced policies. For more information, see
Advanced Policies

The subtopics listed in the table of contents on the left side of your screen contain tables listing the
NetScaler classic expressions.

In the table of operators, the result type of each operator is shown at the beginning of the description.
In the other tables, the level of each expression is shown at the beginning of the description. For
named expressions, each expression is shown as a whole.

Operators

Expression Element Definition

== Boolean. Returns TRUE if the current

expression equals the argument. For text
operations, the items being compared must
exactly match one another. For numeric
operations, the items must evaluate to the
same number.
!= Boolean. Returns TRUE if the current
expression does not equal the argument. For
text operations, the items being compared
must not exactly match one another. For
numeric operations, the items must not
evaluate to the same number.
CONTAINS Boolean. Returns TRUE if the current
expression contains the string that is
designated in the argument.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1351

NetScaler 12.0

Expression Element Definition

NOTCONTAINS Boolean. Returns TRUE if the current

expression does not contain the string that is
designated in the argument.
CONTENTS Text. Returns the contents of the current
expression.
EXISTS Boolean. Returns TRUE if the item designated
by the current expression exists.
NOTEXISTS Boolean.
Returns TRUE if the item designated by the
current expression does not exist.
> Boolean. Returns TRUE if the current
expression evaluates to a number that is
greater than the argument.
< Boolean. Returns TRUE if the current
expression evaluates to a number that is less
than the argument.
>= Boolean. Returns TRUE if the current
expression evaluates to a number that is
greater than or equal to the argument.
<= Boolean. Returns TRUE if the current
expression evaluates to a number that is less
than or equal to the argument.

General expressions

Expression Element Definition

REQ Flow Type. Operates on incoming (or request)

packets.
REQ.HTTP Protocol. Operates on HTTP requests.
REQ.HTTP.METHOD Qualifier. Designates the HTTP method.
REQ.HTTP.URL Qualifier. Designates the URL.
REQ.HTTP.URLTOKENS Qualifier. Designates the URL token.
REQ.HTTP.VERSION Qualifier. Designates the HTTP version.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1352

NetScaler 12.0

Expression Element Definition

REQ.HTTP.HEADER Qualifier. Designates the HTTP header.

REQ.HTTP.URLLEN Qualifier. Designates the number of characters
in the URL.
REQ.HTTP.URLQUERY Qualifier. Designates the query portion of the
URL.
REQ.HTTP.URLQUERYLEN Qualifier. Designates the length of the query
portion of the URL.
REQ.SSL Protocol. Operates on SSL requests.
REQ.SSL.CLIENT.CERT Qualifier. Designates the entire client
certificate.
REQ.SSL.CLIENT.CERT.SUBJECT Qualifier. Designates the client certificate
subject.
REQ.SSL.CLIENT.CERT.ISSUER Qualifier. Designates the issuer of the client
certificate.
REQ.SSL.CLIENT.CERT.SIGALGO Qualifier. Designates the validation algorithm
used by the client certificate.
REQ.SSL.CLIENT.CERT.VERSION Qualifier. Designates the client certificate
version.
REQ.SSL.CLIENT.CERT.VALIDFROM Qualifier. Designates the date before which the
client certificate is not valid.
REQ.SSL.CLIENT.CERT.VALIDTO Qualifier. Designates the date after which the
client certificate is not valid.
REQ.SSL.CLIENT.CERT.SERIALNUMBER Qualifier. Designates the serial number of the
client certificate.
REQ.SSL.CLIENT.CIPHER.TYPE Qualifier. Designates the encryption protocol
used by the client.
REQ.SSL.CLIENT.CIPHER.BITS Qualifier. Designates the number of bits used
by the client’s SSL key.
REQ.SSL.CLIENT.SSL.VERSION Qualifier. Designates the SSL version that the
client is using.
REQ.TCP Protocol. Operates on incoming TCP packets.
REQ.TCP.SOURCEPORT Qualifier. Designates the source port of the
incoming packet.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1353

NetScaler 12.0

Expression Element Definition

REQ.TCP.DESTPORT Qualifier. Designates the destination port of

the incoming packet.
REQ.IP Protocol. Operates on incoming IP packets.
REQ.IP.SOURCEIP Qualifier. Designates the source IP of the
incoming packet.
REQ.IP.DESTIP Qualifier.Designates the destination IP of the
incoming packet.
RES Flow Type. Operates on outgoing (or response)
packets.
RES.HTTP Protocol. Operates on HTTP responses.
RES.HTTP.VERSION Qualifier. Designates the HTTP version.
RES.HTTP.HEADER Qualifier. Designates the HTTP header.
RES.HTTP.STATUSCODE Qualifier. Designates the status code of the
HTTP response.
RES.TCP Protocol. Operates on incoming TCP packets.
RES.TCP.SOURCEPORT Qualifier. Designates the source port of the
outgoing packet.
RES.TCP.DESTPORT Qualifier. Designates the destination port of
the outgoing packet.
RES.IP Protocol. Operates on outgoing IP packets.
RES.IP.SOURCEIP Qualifier. Designates the source IP of the
outgoing packet. This can be in IPv4 or IPv6
format. For example: add expr exp3 “sourceip
== 10.102.32.123 –netmask 255.255.255.0 &&
destip == 2001::23/120”.
RES.IP.DESTIP Qualifier. Designates the destination IP of the
outgoing packet.

Client security expressions

The expressions to configure client settings on the Access Gateway with the following software:

• Antivirus
• Personal firewall

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1354

NetScaler 12.0

• Antispam
• Internet Security

For example usage, see http://support.citrix.com/article/CTX112599.

Actual Expression Definition

CLIENT.APPLICATION.AV(<NAME>.VERSION == Checks whether the client is running the

<VERSION>) designated anti-virus program and version.
CLIENT.APPLICATION.AV(<NAME>.VERSION != Checks whether the client is not running the
<VERSION>) designated anti-virus program and version.
CLIENT.APPLICATION.PF(<NAME>.VERSION == Checks whether the client is running the
<VERSION>) designated personal firewall program and
version.
CLIENT.APPLICATION.PF(<NAME>.VERSION != Checks whether the client is not running the
<VERSION>) designated personal firewall program and
version.
CLIENT.APPLICATION.IS(<NAME>.VERSION == Checks whether the client is running the
<VERSION>) designated internet security program and
version.
CLIENT.APPLICATION.IS(<NAME>.VERSION != Checks whether the client is not running the
<VERSION>) designated internet security program and
version.
CLIENT.APPLICATION.AS(<NAME>.VERSION == Checks whether the client is running the
<VERSION>) designated anti-spam program and version.
CLIENT.APPLICATION.AS(<NAME>.VERSION != Checks whether the client is not running the
<VERSION>) designated anti-spam program and version.

Network-based expressions

Expression Definition

REQ Flow Type. Operates on incoming, or request,

packets.
REQ.VLANID Qualifier. Operates on the virtual LAN (VLAN)
ID.
REQ.INTERFACE.ID Qualifier. Operates on the ID of the designated
NetScaler interface.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1355

NetScaler 12.0

Expression Definition

REQ.INTERFACE.RXTHROUGHPUT Qualifier. Operates on the raw received packet

throughput of the designated NetScaler
interface.
REQ.INTERFACE.TXTHROUGHPUT Qualifier. Operates on the raw transmitted
packet throughput of the designated NetScaler
interface.
REQ.INTERFACE.RXTXTHROUGHPUT Qualifier. Operates on the raw received and
transmitted packet throughput of the
designated NetScaler interface.
REQ.ETHER.SOURCEMAC Qualifier. Operates on the source MAC address.
REQ.ETHER.DESTMAC Qualifier. Operates on the destination MAC
address.
RES Flow Type. Operates on outgoing (or response)
packets.
RES.VLANID Qualifier. Operates on the virtual LAN (VLAN)
ID.
RES.INTERFACE.ID Qualifier. Operates on the ID of the designated
NetScaler interface.
RES.INTERFACE.RXTHROUGHPUT Qualifier. Operates on the raw received packet
throughput of the designated NetScaler
interface.
RES.INTERFACE.TXTHROUGHPUT Qualifier. Operates on the raw transmitted
packet throughput of the designated NetScaler
interface.
RES.INTERFACE.RXTXTHROUGHPUT Qualifier. Operates on the raw received and
transmitted packet throughput of the
designated NetScaler interface.
RES.ETHER.SOURCEMAC Qualifier. Operates on the source MAC address.
RES.ETHER.DESTMAC Qualifier. Operates on the destination MAC
address.

Date/time expressions

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1356

NetScaler 12.0

Expression Definition

TIME Qualifier. Operates on the date and time of

day, GMT.
DATE Qualifier. Operates on the date, GMT.
DAYOFWEEK Operates on the specified day in the week,
GMT.

File system expressions

You can specify file system expressions in authorization policies for users and groups who access file
sharing through the NetScaler Gateway file transfer utility (the VPN portal). These expressions work
with the NetScaler Gateway file transfer authorization feature to control user access to file servers,
folders, and files. For example, you can use these expressions in authorization policies to control
access based on file type and size.

For more information, refer to the File Name Expression pdf.

Note: File system expressions do not support regular expressions.

Built-in named expressions (General)

Expression Definition

ns_all_apps_ncomp Tests for connections with destination ports

between 0 and 65535. In other words, tests for
all applications.
ns_cachecontrol_nocache Tests for connections with an HTTP
Cache-Control header that contains the value
“no-cache”.
ns_cachecontrol_nostore Tests for connections with an HTTP
Cache-Control header that contains the value
“no-store”.
ns_cmpclient Tests the client to determine if it accepts
compressed content.
ns_content_type Tests for connections with an HTTP
Content-Type header that contains “text”.
ns_css Tests for connections with an HTTP
Content-Type header that contains “text/css”.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1357

NetScaler 12.0

Expression Definition

ns_ext_asp Tests for HTTP connections to any URL that

contains the string .asp—in other words, any
connection to an active server page (ASP).
ns_ext_cfm Tests for HTTP connections to any URL that
contains the string .cfm
ns_ext_cgi Tests for HTTP connections to any URL that
contains the string .cgi—in other words, any
connection to a common gateway interface
(CGI) script.
ns_ext_ex Tests for HTTP connections to any URL that
contains the string .ex
ns_ext_exe Tests for HTTP connections to any URL that
contains the string .exe—in other words, any
connection to a executable file.
ns_ext_htx Tests for HTTP connections to any URL that
contains the string .htx
ns_ext_not_gif Tests for HTTP connections to any URL that
does not contain the string .gif—in other words,
any connection to a URL that is not a GIF image.
ns_ext_not_jpeg Tests for HTTP connections to any URL that
does not contain the string .jpeg—in other
words, any connection to a URL that is not a
JPEG image.
ns_ext_shtml Tests for HTTP connections to any URL that
contains the string .shtml—in other words, any
connection to a server-parsed HTML page.
ns_false Always returns a value of FALSE.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1358

NetScaler 12.0

Expression Definition

ns_farclient Client is in a different geographical region from

the NetScaler, as determined by the
geographical region in the client’s IP address.
The following regions are predefined: 192.0.0.0
– 193.255.255.255: Multi-regional, 194.0.0.0 –
195.255.255.255: European Union, 196.0.0.0 –
197.255.255.255: Other1, 198.0.0.0 – ,
199.255.255.255: North America, 200.0.0.0 –
201.255.255.255: Central and South America,
202.0.0.0 – 203.255.255.255: Pacific Rim,
204.0.0.0 – 205.255.255.255: Other2, and
206.0.0.0 – 207.255.255.255: Other3
ns_header_cookie Tests for HTTP connections that contain a
Cookie header.
ns_header_pragma Tests for HTTP connections that contain a
Pragma: no-cache header.
ns_mozilla_47 Tests for HTTP connections whose User-Agent
header contains the string Mozilla/4.7—in
other words, any connection from a client
using the Mozilla 4.7 Web browser.
ns_msexcel Tests for HTTP connections whose
Content-Type header contains the string
application/vnd.msexcel—in other words, any
connection transmitting a Microsoft Excel
spreadsheet.
ns_msie Tests for HTTP connections whose User-Agent
header contains the string MSIE—in other
words, any connection from a client using any
version of the Internet Explorer Web browser.
ns_msppt Tests for HTTP connections whose
Content-Type header contains the string
application/vnd.ms-powerpoint—in other
words, any connection transmitting a Microsoft
PowerPoint file.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1359

NetScaler 12.0

Expression Definition

ns_msword Tests for HTTP connections whose

Content-Type header contains the string
application/vnd.msword—in other words, any
connection transmitting a Microsoft Word file.
ns_non_get Tests for HTTP connections that use any HTTP
method except for GET.
ns_slowclient Returns TRUE if the average round trip time
between the client and the NetScaler is more
than 80 milliseconds.
ns_true Returns TRUE for all traffic.
ns_url_path_bin Tests the URL path to see if it points to the /bin/
directory.
ns_url_path_cgibin Tests the URL path to see if it points to the
CGI-BIN directory.
ns_url_path_exec Tests the URL path to see if it points to the
/exec/directory.
ns_url_tokens Tests for the presence of URL tokens.
ns_xmldata Tests for the presence of XML data.

Built-in named expressions (Anti-Virus)

Expression Definition

McAfee Virus Scan 11 Tests to determine whether the client is

running the latest version of McAfee VirusScan.
McAfee Antivirus Tests to determine whether the client is
running any version of McAfee Antivirus.
Symantec AntiVirus 10 (with Updated Tests to determine whether the client is
Definition File) running the most current version of Symantec
AntiVirus.
Symantec AntiVirus 6.0 Tests to determine whether the client is
running Symantec AntiVirus 6.0.
Symantec AntiVirus 7.5 Tests to determine whether the client is
running Symantec AntiVirus 7.5.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1360

NetScaler 12.0

Expression Definition

TrendMicro OfficeScan 7.3 Tests to determine whether the client is

running Trend Microsystems’ OfficeScan,
version 7.3.
TrendMicro AntiVirus 11.25 Tests to determine whether the client is
running Trend Microsystems’ AntiVirus, version
11.25.
Sophos Antivirus 4 Tests to determine whether the client is
running Sophos Antivirus, version 4.
Sophos Antivirus 5 Tests to determine whether the client is
running Sophos Antivirus, version 5.
Sophos Antivirus 6 Tests to determine whether the client is
running Sophos Antivirus, version 6.

Built-in named expressions (Personal Firewall)

Expression Definition

TrendMicro OfficeScan 7.3 Tests to determine whether the client is

running Trend Microsystems’ OfficeScan,
version 7.3.
Sygate Personal Firewall 5.6 Tests to determine whether the client is
running the Sygate Personal Firewall, version
5.6.
ZoneAlarm Personal Firewall 6.5 Tests to determine whether the client is
running the ZoneAlarm Personal Firewall,
version 6.5.

Built-in named expressions (Client Security)

Expression Definition

Norton Internet Security Tests to determine whether the client is

running any version of Norton Internet
Security.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1361

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Summary examples of default syntax expressions and policies

September 24, 2018

Contributed by:
C

The following table provides examples of default syntax expressions that you can use as the basis for
your own default syntax expressions.

Table 1. Examples of Default Syntax Expressions

Expression Type Sample Expressions

Look at the method used in the HTTP request. http.req.method.eq(post)http.req.

method.eq(get)
Check the Cache-Control or Pragma header http.req.header(”Cache-Control”).
value in an HTTP request (req) or response contains(”no-store”)
(res). http.req.header(”Cache-Control”).
contains(”no-cache”)
http.req.header(”Pragma”).contains(
”no-cache”)
http.res.header(”Cache-Control”).
contains(”private”)
http.res.header(”Cache-Control”).
contains(”public”)
http.res.header(”Cache-Control”).
contains(”must-revalidate”)http.res
.header(”Cache-Control”).contains (
”proxy-revalidate”)
http.res.header(”Cache-Control”).
contains(”max-age”)
Check for the presence of a header in a request http.req.header(”myHeader”).exists
(req) or response (res). http.res.header(”myHeader”).exists

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1362

NetScaler 12.0

Expression Type Sample Expressions

Look for a particular file type in an HTTP http.req.url.contains(”.html”)http.

request based on the file extension. req.url.contains(”.cgi”)http.req.
url.contains(”.asp”)http.req.url.
contains(”.exe”)http.req.url.
contains(”.cfm”)http.req.url.
contains(”.ex”)http.req.url.
contains(”.shtml”)http.req.url.
contains(”.htx”)http.req.url.
contains(”/cgi-bin/”)http.req.url.
contains(”/exec/”)http.req.url.
contains(”/bin/”)
Look for anything that is other than a http.req.url.contains(”.gif”).not;
particular file type in an HTTP request. http.req.url.contains(”.jpeg”).not
Check the type of file that is being sent in an http.res.header(”Content-Type”).
HTTP response based on the Content-Type contains(”text”)http.res.header(”
header. Content-Type”).contains ”
application/msword”)http.res.header
(”Content-Type”).contains(”vnd.ms-
excel”)http.res.header(”Content-
Type”).contains(”application/vnd.ms
-powerpoint”); http.res.header(”
Content-Type”).contains(”text/css”)
; http.res.header(”Content-Type”).
contains(”text/xml”); http.res.
header(”Content-Type”).contains(”
image/”)
Check whether this response contains an ‘http.res.header(“Expires”).exists
expiration header.
Check for a Set-Cookie header in a response. http.res.header(“Set-Cookie”).exists
Check the agent that sent the response. http.res.header(“User-
Agent”).contains(“Mozilla/4.7”)
http.res.header(“User-
Agent”).contains(“MSIE”)‘
Check if the first 1024 bytes of the body of a http.req.body(1024).contains(”some
request starts with the string “some text”. text”)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1363

NetScaler 12.0

The following table shows examples of policy configurations and bindings for commonly used func-
tions.

Table 2. Examples of Default Syntax Expressions and Policies

Purpose Example

Use the rewrite feature to replace occurrences add rewrite action

of http://with https:// in the body of an httpRewriteAction replace_all http.
HTTP response. res.body(50000)”\”https://\””-
pattern http://add rewrite policy
demo_rep34312 ”http.res.body(50000)
.contains(\”http://\”)”
httpRewriteAction
Replace all occurrences of “abcd” with “1234” add rewrite action abcdTo1234Action
in the first 1000 bytes of the HTTP body. replace_all ”http.req.body(1000)””
\”1234\””-pattern abcd add rewrite
policy abcdTo1234Policy ”http.req.
body(1000).contains(\”abcd\”)”
abcdTo1234Action bind rewrite
global abcdTo1234Policy 100 END -
type REQ_OVERRIDE
Downgrade the HTTP version to 1.0 to prevent add rewrite action downgradeTo1.0
the server from chunking HTTP responses. Action replace http.req.version.
minor ”\”0\””add rewrite policy
downgradeTo1.0Policy ”http.req.
version.minor.eq(1)”downgradeTo1.0
Action bind lb vserver myLBVserver
-policyName downgradeTo1.0Policy -
priority 100 -
gotoPriorityExpression NEXT -type
REQUEST

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1364

NetScaler 12.0

Purpose Example

Remove references to the HTTP or HTTPS add rewrite action

protocol in all responses, so that if the user’s remove_http_https replace_all ”http
connection is HTTP, the link is opened by using .res.body(1000000).set_text_mode(
HTTP, and if the user’s connection is HTTPS, ignorecase)””\”//\””-pattern ”re~
the link is opened by using HTTPS. https?://|HTTPS?://~”add rewrite
policy remove_http_https true
remove_http_https bind lb vserver
test_vsvr -policyName
remove_http_https -priority 20 -
gotoPriorityExpression NEXT -type
RESPONSE
Rewrite instances of http: to https: in all URLs. add responder action
httpToHttpsAction redirect ”\”https
://\” + http.req.hostname + http.
req.url”-bypassSafetyCheck YES add
responder policy httpToHttpsPolicy
”!CLIENT.SSL.IS_SSL”
httpToHttpsAction bind responder
global httpToHttpsPolicy 1 END -
type OVERRIDE
Modify a URL to redirect from URL A to URL B. add responder action
In this example, “file5.html” is appended to the appendFile5Action redirect \”http
path. ://\” + http.req.hostname + http.
req.url + \”/file5.html\””-
bypassSafetyCheck YES add responder
policy appendFile5Policy ”http.req
.url.eq(\”/testsite\”)”
appendFile5Action bind responder
global appendFile5Policy 1 END -
type OVERRIDE

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1365

NetScaler 12.0

Purpose Example

Redirect an external URL to an internal URL. add rewrite action

act_external_to_internal REPLACE ’
http.req.hostname.server’’”www.my.
host.com”’add rewrite policy
pol_external_to_internal ’http.req.
hostname.server.eq(”www.external.
host.com”)’act_external_to_internal
bind rewrite global
pol_external_to_internal 100 END -
type REQ_OVERRIDE
Redirect requests to www.example.com that add rewrite action
have a query string to act_redirect_query REPLACE q##http.
www.Webn.example.com. The value n is req.header(”Host”).before_str(”.
derived from a server parameter in the query example.com”)’’”Web”+ http.req.url.
string, for example, server=5. query.value(”server”)## add rewrite
policy pol_redirect_query q##http.
req.header(”Host”).eq(”www.example.
com”)&& http.req.url.contains(”?”)’
act_redirect_query##
Limit the number of requests per second from add ns limitSelector
a URL. ip_limit_selector http.req.url ”
client.ip.src”add ns
limitIdentifier ip_limit_identifier
-threshold 4 -timeSlice 3600 -mode
request_rate -limitType smooth -
selectorName ip_limit_selector add
responder action
my_Web_site_redirect_action
redirect ”\”http://www.mycompany.
com/\””add responder policy
ip_limit_responder_policy ”http.req
.url.contains(\”myasp.asp\”)&& sys.
check_limit (\”ip_limit_identifier
\”)”my_Web_site_redirect_action
bind responder global
ip_limit_responder_policy 100 END -
type default

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1366

NetScaler 12.0

Purpose Example

Check the client IP address but pass the add rewrite policy
request without modifying the request. check_client_ip_policy ’HTTP.REQ.
HEADER (”x-forwarded-for”).EXISTS
HTTP.REQ.HEADER (”client-ip”).
EXISTS’NOREWRITE bind rewrite
global check_client_ip_policy 100
END
Remove old headers from a request and insert add rewrite action
an NS-Client header. del_x_forwarded_for
delete_http_header x-forwarded-for
add rewrite action del_client_ip
delete_http_header client-ip add
rewrite policy
check_x_forwarded_for_policy ’HTTP.
REQ.HEADER(”x-forwarded-for”).
EXISTS’del_x_forwarded_for add
rewrite policy
check_client_ip_policy ’HTTP.REQ.
HEADER(”client-ip”).EXISTS’
del_client_ip add rewrite action
insert_ns_client_header
insert_http_header NS-Client ’
CLIENT.IP.SRC’add rewrite policy
insert_ns_client_policy ’HTTP.REQ.
HEADER(”x-forwarded-for”).EXISTS
HTTP.REQ.HEADER(”client-ip”).EXISTS
’insert_ns_client_header bind
rewrite global
check_x_forwarded_for_policy 100
200 bind rewrite global
check_client_ip_policy 200 300 bind
rewrite global
insert_ns_client_policy 300 END

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1367

NetScaler 12.0

Purpose Example

Remove old headers from a request, insert an add rewrite action

NS-Client header, and then modify the “insert del_x_forwarded_for
header” action so that the value of the inserted delete_http_header x-forwarded-for
header contains the client IP values from the add rewrite action del_client_ip
old headers and the NetScaler appliance’s delete_http_header client-ip add
connection IP address. Note that this example rewrite policy
repeats the previous example, with the check_x_forwarded_for_policy ’HTTP.
exception of the final set rewrite action. REQ.HEADER(”x-forwarded-for”).
EXISTS’del_x_forwarded_for add
rewrite policy
check_client_ip_policy ’HTTP.REQ.
HEADER(”client-ip”).EXISTS’
del_client_ip add rewrite action
insert_ns_client_header
insert_http_header NS-Client ’
CLIENT.IP.SRC’add rewrite policy
insert_ns_client_policy ’HTTP.REQ.
HEADER(”x-forwarded-for”).EXISTS
HTTP.REQ.HEADER(”client-ip”).EXISTS
’insert_ns_client_header bind
rewrite global
check_x_forwarded_for_policy 100
200 bind rewrite global
check_client_ip_policy 200 300 bind
rewrite global
insert_ns_client_policy 300 END set
rewrite action
insert_ns_client_header -
stringBuilderExpr ’HTTP.REQ.HEADER
(”x-forwarded-for”).VALUE(0)+ ” ” +
HTTP.REQ.HEADER(”client-ip”).VALUE
(0)+ ” ” + CLIENT.IP.SRC’-
bypassSafetyCheck YES

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1368

NetScaler 12.0

4. AppExpert

Tutorial examples of default syntax policies for rewrite

March 14, 2019

Contributed by:
C

With the rewrite feature, you can modify any part of an HTTP header, and, for responses, you can mod-
ify the HTTP body. You can use this feature to accomplish a number of useful tasks, such as removing
unnecessary HTTP headers, masking internal URLs, redirecting Web pages, and redirecting queries or
keywords.

In the following examples, you first create a rewrite action and a rewrite policy. Then you bind the
policy globally.

This document includes the following details:

• Redirecting an External URL to an Internal URL

• Redirecting a Query
• Rewriting HTTP to HTTPS
• Removing Unwanted Headers
• Reducing Web Server Redirects
• Masking the Server Header
• Converting plain text to URL encoded string and vice-versa

For more information about the commands and syntax descriptions, see Rewrite Command Reference
page.

Redirecting an external URL to an internal URL

Updated: 2013-10-29

This example describes how to create a rewrite action and rewrite policy that redirects an external URL
to an internal URL. You create an action, called act_external_to_internal, that performs the rewrite.
Then you create a policy called pol _external _to _internal.

To redirect an external URL to an internal URL by using the command line interface

• To create the rewrite action, at the command prompt, type:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1369

NetScaler 12.0

add rewrite action act _external _to_internal REPLACE ’http.req.hostname

.server’’”host_name_of_internal_Web_server”

• To create the rewrite policy, at the NetScaler command prompt, type:

add rewrite policy pol_external_to_internal ’http.req.hostname.server.

eq(”host_name_of_external_Web_server”)’act_external_to_internal

• Bind the policy globally.

To redirect an external URL to an internal URL by using the GUI

1. Navigate to AppExpert > Rewrite > Actions.

2. In the details pane, click Add.

3. In the Create Rewrite Action dialog box, enter the name act_external_to_internal.

4. To replace the HTTP server host name with the internal server name, choose Replace from the
Type list box.

5. In the Header Name field, type Host.

6. In the String expression for replacement text field, type the internal host name of your Web
server.

7. Click Create and then click Close.

8. In the navigation pane, click Policies.

9. In the details pane, click Add.

10. In the Name field, type pol_external_to_internal. This policy will detect connections to the Web
server.

11. In the Action drop-down menu, choose the action act_external_to_internal.

12. In the Expression editor, construct the following expression:

1 HTTP.REQ.HOSTNAME.SERVER.EQ(”www.example.com”)

13. Bind your new policy globally.

Redirecting a query

This example describes how to create a rewrite action and rewrite policy that redirects a query to the
proper URL. The example assumes that the request contains a Host header set to www.example.com
and a GET method with the string /query.cgi?server=5. The redirect extracts the domain name from

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1370

NetScaler 12.0

the host header and the number from the query string, and redirects the user’s query to the server
Web5.example.com, where the rest of the user’s query is processed.

Note: Although the following commands appears on multiple lines, you should enter them on a single
line without line breaks.

To redirect a query to the appropriate URL using the command line

• To create a rewrite action named act_redirect_query that replaces the HTTP server host name
with the internal server name, type:

add rewrite action act_redirect_query REPLACE q##http.req.header(”Host”

).before_str(”.example.com”)’’”Web”+ http.req.url.query.value(”server”)
##

• To create a rewrite policy named pol_redirect_query, type the following commands at the
NetScaler command prompt.. This policy detects connections, to the Web server, that contain
a query string. Do not apply this policy to connections that do not contain a query string:

add rewrite policy pol_redirect_query q##http.req.header(”Host”).eq(”

www.example.com”)http.req.url.contains(”?”)’act_redirect_query##

• Bind your new policy globally.

Because this rewrite policy is highly specific and should be run before any other rewrite policies, it is
advisable to assign it a high priority. If you assign it a priority of 1, it will be evaluated first.

Rewriting HTTP to HTTPS

This example describes how to rewrite Web server responses to find all URLs that begin with the string
“http” and replace that string with “https.” You can use this to avoid having to update Web pages after
moving a server from HTTP to HTTPS.

To redirect HTTP URLs to HTTPS by using the command line interface

• To create a rewrite action named act_replace_http_with_https that replaces all instances of the
string “http” with the string “https,” enter the following command:

add rewrite action act_replace_http_with_https replace_all ‘http.res.body(100)’ “‘https”’

-pattern http

• To create a rewrite policy named pol_replace_http_with_https that detects connections to the

Web server, enter the following command:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1371

NetScaler 12.0

add rewrite policy pol_replace_http_with_https TRUE act_replace_http_with_https

NOREWRITE
• Bind your new policy globally.
To troubleshoot this rewrite operation, see “Case Study: Rewrite Policy for Converting HTTP Links to
HTTPS not Working.”

Removing Unwanted Headers

This example explains how to use a Rewrite policy to remove unwanted headers. Specifically, the
example shows how to remove the following headers:
• Accept Encoding header. Removing the Accept Encoding header from HTTP responses pre-
vents compression of the response.
• Content Location header. Removing the Content Location header from HTTP responses pre-
vents your server from providing a hacker with information that might allow a security breach.
To delete headers from HTTP responses, you create a rewrite action and a rewrite policy, and you bind
the policy globally.

To create the appropriate Rewrite action by using the command line interface

At the command prompt, type one of the following commands to either remove the Accept Encoding
header and prevent response compression or remove the Content Location header:
• add rewrite action ”act_remove-ae”delete_http_header ”Accept-Encoding”
• add rewrite action ”act_remove-cl”delete_http_header ”Content-Location”

To create the appropriate Rewrite policy by using the command line interface

At the command prompt, type one of the following commands to remove either the Accept Encoding
header or the Content Location header:
• add rewrite policy ”pol_remove-ae”true ”act_remove-ae”
• add rewrite policy ”pol_remove-cl”true ”act_remove-cl”

To bind the policy globally by using the command line interface

At the command prompt, type one of the following commands, as appropriate, to globally bind the
policy that you have created:
• bind rewrite global pol_remove_ae 100
• bind rewrite global pol_remove_cl 200

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1372

NetScaler 12.0

Reducing Web Server Redirects

This example explains how to use a Rewrite policy to modify connections to your home page and other
URLs that end with a forward slash (/) to the default index page for your server, preventing redirects
and reducing load on your server.

To modify directory-level HTTP requests to include the default home page by using the
command line

• To create a Rewrite action named action-default-homepage that modifies URLs that end in a
forward slash to include the default home page index.html, type:

add rewrite action “action-default-homepage” replace q#http.req.url.path “/” “/index.html”#

• To create a Rewrite policy named policy-default-homepage that detects connections to your

home page and applies your new action, type:

add rewrite policy “policy-default-homepage” q#http.req.url.path.EQ(“/”) “action-default-

homepage”#

• Globally bind your new policy to put it into effect.

Masking the Server Header

This example explains how to use a Rewrite policy to mask the information in the Server header in
HTTP responses from your Web server. That header contains information that hackers can use to
compromise your Web site. While masking the header will not prevent a skilled hacker from finding
out information about your server, it will make hacking your Web server more difficult and encourage
hackers to choose less well protected targets.

To mask the Server header in responses from the command line

1. To create a Rewrite action named act_mask-server that replaces the contents of the Server
header with an uninformative string, type:

add rewrite action ”act_mask-server” replace ”http.RES.HEADER(”Server”)”””Web

Server 1.0””

2. To create a Rewrite policy named pol_mask-server that detects all connections, type:

add rewrite policy ”pol_mask-server”true ”act_mask-server”

3. Globally bind your new policy to put it into effect.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1373

NetScaler 12.0

How to convert plain text to URL encoded string and vice-versa

The following expressions convert plain text to URL encoded string and vice-versa:

1. URL_RESERVED_CHARS_SAFE (string to URL ENCODED).

Example

1 (”abc def&123”).URL_RESERVED_CHARS_SAFE
2 Output will be
3 “ abc%20def%26123 ” which is url encoded.

2. SET_TEXT_MODE(URLENCODED).DECODE_USING_TEXT_MODE. (URL ENCODED to string)

Example:

1 (”abc%20def%26123”).SET_TEXT_MODE(URLENCODED).
DECODE_USING_TEXT_MODE
2 Output will be
3 “ abc def&123 ”

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Tutorial Examples of Classic Policies

September 24, 2018

Contributed by:
C

The following examples describe useful examples of classic policy configuration for certain NetScaler
features, such as NetScaler Gateway, application firewall, and SSL.

This document includes the following details:

• NetScaler Gateway Policy to Check for a Valid Client Certificate

• Application Firewall Policy to Protect a Shopping Cart Application
• Application Firewall Policy to Protect Scripted Web Pages
• DNS Policy to Drop Packets from Specific IPs
• SSL Policy to Require Valid Client Certificates

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1374

NetScaler 12.0

NetScaler Gateway Policy to Check for a Valid Client Certificate

Updated: 2014-09-25

The following policies enable the NetScaler to ensure that a client presents a valid certificate before
establishing a connection to a company’s SSL VPN.

To check for a valid client certificate by using the command line interface

• Add an action to perform client certificate authentication.

add ssl action act1 -clientAuth DOCLIENTAUTH

• Create an SSL policy to evaluate the client requests.

add ssl policy pol1 -rule ”REQ.HTTP.METHOD == GET”-action act1

• Add a rewrite action to insert the certificate issuer details into the HTTP header of the requests
being sent to web server.

add rewrite action act2 insert\\_http\\_header ”CertDN”CLIENT.SSL.

CLIENT\\_CERT.SUBJECT

• Create a rewrite policy to insert the certificate issuer details, if the client certificate exists.

add rewrite policy pol2 ”CLIENT.SSL.CLIENT\\_CERT.EXISTS”act2

Bind these new policies to the NetScaler VIP to put them into effect.

Application firewall policy to protect a shopping cart application

Shopping cart applications handle sensitive customer information, for example, credit card numbers
and expiration dates, and they access back-end database servers. Many shopping cart applications
also use legacy CGI scripts, which can contain security flaws that were unknown at the time they were
written, but are now known to hackers and identity thieves.

A shopping cart application is particularly vulnerable to the following attacks:

• Cookie tampering. If a shopping cart application uses cookies, and does not perform the ap-
propriate checks on the cookies that users return to the application, an attacker could modify a
cookie and gain access to the shopping cart application under another user’s credentials. Once
logged on as that user, the attacker could obtain sensitive private information about the legiti-
mate user or place orders using the legitimate user’s account.
• SQL injection. A shopping cart application normally accesses a back-end database server. Un-
less the application performs the appropriate safety checks on the data users return in the form
fields of its Web forms before it passes that information on to the SQL database, an attacker can

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1375

NetScaler 12.0

use a Web form to inject unauthorized SQL commands into the database server. Attackers nor-
mally use this type of attack to obtain sensitive private information from the database or modify
information in the database.
The following configuration will protect a shopping cart application against these and other attacks.

To protect a shopping cart application by using the GUI

1. Navigate to Security > Application Firewall > Profiles, and then click Add.
2. In the Create Application Firewall Profile dialog box, in the Profile Name field, enter shop-
ping_cart.
3. In the Profile Type drop-down list, select Web Application.
4. In the Configure Select Advanced defaults.
5. Click Create and then click Close.
6. In the details view, double-click the new profile.
7. In the Configure Web Application Profile dialog box, configure your new profile as described
below:
• Click the Checks tab, double-click the Start URL check, and in the Modify Start URL Check
dialog box, click the General tab and disable blocking, and enable learning, logging, statis-
tics, and URL closure. Click OK and then click Close.
Note that if you are using the command line, you configure these settings by typing the
following at the prompt, and pressing ENTER:
set appfw profile shopping\\_cart -startURLAction LEARN LOG STATS -
startURLClosure ON

• For the Cookie Consistency check and Form Field Consistency checks, disable blocking,
and enable learning, logging, statistics, using a similar method to the Modify Start URL
Check configuration.
If you are using the command line, you configure these settings by typing the following
commands:
set appfw profile shopping\\_cart -cookieConsistencyAction LEARN
LOG STATS

set appfw profile shopping\\_cart -fieldConsistencyAction LEARN LOG

STATS

• For the SQL Injection check, disable blocking, and enable learning, logging, statistics, and
transformation of special characters in the Modify SQL Injection Check dialog box, General
tab, Check Actions section.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1376

NetScaler 12.0

If you are using the command line, you configure these settings by typing the following at
the prompt, and pressing ENTER:

set appfw profile shopping\\_cart -SQLInjectionAction LEARN LOG

STATS -SQLInjectionTransformSpecialChars ON

• For the Credit Card check, disable blocking; enable logging, statistics, and masking of
credit card numbers; and enable protection for those credit cards you accept as forms of
payment.

– If you are using the GUI, you configure blocking, logging, statistics, and masking (or
x-out) in the Modify Credit Card Check dialog box, General tab, Check Actions section.
You configure protection for specific credit cards in the Settings tab of the same dialog
box.
– If you are using the command line, you configure these settings by typing the following
at the prompt, and pressing ENTER:

set appfw profile shopping_cart -creditCardAction LOG STATS -

creditCardXOut ON -creditCard <name> [<name>...]

For <name> you substitute the name of the credit card you want to protect. For Visa, you
substitute VISA. For Master Card, you substitute MasterCard. For American Express, you
substitute Amex. For Discover, you substitute Discover. For Diners Club, you substitute
DinersClub. For JCB, you substitute JCB.

8. Create a policy named shopping_cart that detects connections to your shopping cart applica-
tion and applies the shopping_cart profile to those connections.

To detect connections to the shopping cart, you examine the URL of incoming connections. If
you host your shopping cart application on a separate host (a wise measure for security and
other reasons), you can simply look for the presence of that host in the URL. If you host your
shopping cart in a directory on a host that handles other traffic, as well, you must determine
that the connection is going to the appropriate directory and/or HTML page.

The process for detecting either of these is the same; you create a policy based on the following
expression, and substitute the proper host or URL for .

1 REQ.HTTP.HEADER URL CONTAINS <string>

• If you are using the GUI, you navigate to the application firewall Policies page, click the
Add… button to add a new policy, and follow the policy creation process described in “To
create a policy with classic expressions using the GUI” beginning on page 201 and follow-
ing.

• If you are using the command line, you type the following command at the prompt and
press Enter:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1377

NetScaler 12.0

add appfw policy shopping_cart ”REQ.HTTP.HEADER URL CONTAINS <

string>”shopping_cart

2. Globally bind your new policy to put it into effect.

Because you want to ensure that this policy will match all connections to the shopping cart, and not
be preempted by another more general policy, you should assign a high priority to it. If you assign one
(1) as the priority, no other policy can preempt this one.

Application firewall policy to protect scripted web pages

Web pages with embedded scripts, especially legacy JavaScripts, often violate the “same origin rule,”
which does not allow scripts to access or modify content on any server but the server where they are
located. This security vulnerability is called cross-site scripting. The application firewall Cross-Site
Scripting rule normally filters out requests that contain cross-site scripting.

Unfortunately, this can cause Web pages with older JavaScripts to stop functioning, even when your
system administrator has checked those scripts and knows that they are safe. The example below ex-
plains how to configure the application firewall to allow cross-site scripting in Web pages from trusted
sources without disabling this important filter for the rest of your Web sites.

To protect Web pages with cross-site scripting by using the command line interface

• At the command line, to create an advanced profile, type:

add appfw profile pr_xssokay -defaults advanced

• To configure the profile, type:

set appfw profile pr_xssokay -startURLAction NONE -startURLClosure OFF

-cookieConsistencyAction LEARN LOG STATS -fieldConsistencyAction LEARN
LOG STATS -crossSiteScriptingAction LEARN LOG STATS$”

• Create a policy that detects connections to your scripted Web pages and applies the pr_xssokay
profile, type:

add appfw policy pol_xssokay ”REQ.HTTP.HEADER URL CONTAINS ^\\.pl\\?$

|| REQ.HTTP.HEADER URL CONTAINS ^\\.js$”pr\\_xssokay

• Globally bind the policy.

To protect Web pages with cross-site scripting by using the GUI

1. Navigate to Security > Application Firewall > Profiles.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1378

NetScaler 12.0

2. In the details view, click Add.

3. In the Create Application Firewall Profile dialog box, create a Web Application profile with
advanced defaults and name it pr_xssokay. Click Create and then click Close.

4. In the details view, click the profile, click Open, and in the Configure Web Application Profile
dialog box, configure the pr_xssokay profile as shown below.

Start URL Check: Clear all actions.

• Cookie Consistency Check: Disable blocking.

• Form Field Consistency Check: Disable blocking.
• Cross-Site Scripting Check: Disable blocking.

This should prevent blocking of legitimate requests involving Web pages with cross-site script-
ing that you know are nonetheless safe.

5. Click Policies, and then click Add.

6. In the Create Application Firewall Policy dialog box, create a policy that detects connections
to your scripted Web pages and applies the pr_xssokay profile:

• Policy name: pol_xssokay

• Associated profile: pr_xssokay

Policy expression: REQ.HTTP.HEADER URL

“REQ.HTTP.HEADER URL CONTAINS ˆ\.js$”
CONTAINS ˆ\.pl\?$

7. Globally bind your new policy to put it into effect.

DNS Policy to drop packets from specific IPs

The following example describes how to create a DNS action and DNS policy that detects connections
from unwanted IPs or networks, such as those used in a DDOS attack, and drops all packets from
those locations. The example shows networks within the IANA reserved IP block 192.168.0.0/16. A
hostile network will normally be on publicly routable IPs.

To drop packets from specific IPs by using the command line interface

• To create a DNS policy named pol_ddos_drop that detects connections from hostile networks
and drops those packets, type:
add dns policy pol_ddos_drop ’client.ip.src.in_subnet(192.168.253.128/25)
|| client.ip.src.in_subnet(192.168.254.32/27)’-drop YES’

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1379

NetScaler 12.0

For the example networks in the 192.168.0.0/16 range, you substitute the IP and netmask in
###.###.###.###/## format of each network you want to block. You can include as many net-
works as you want, separating each CLIENT.IP.SRC.IN_SUBNET(###.###.###.###./##) command
with the OR operator.

• Globally bind your new policy to put it into effect.

SSL policy to require valid client certificates

The following example shows an SSL policy that checks the user’s client certificate validity before
initiating an SSL connection with a client.

To block connections from users with expired client certificates

• Log on to the command line interface.

If you are using the GUI, navigate to the SSL Policies page, then in the Data area, click the Actions
tab.

• Create an SSL action named act_current_client_cert that requires that users have a current
client certificate to establish an SSL connection with the NetScaler.

add ssl action act_current_client_cert-clientAuth DOCLIENTAUTH -clientCert

ENABLED -certHeader ”clientCertificateHeader”-clientCertNotBefore
ENABLED -certNotBeforeHeader ”Mon, 01 Jan 2007 00:00:00 GMT”

• Create an SSL policy named pol_current_client_cert that detects connections to the Web server
that contain a query string.

add ssl policy pol_current_ client_cert ’REQ.SSL.CLIENT.CERT.VALIDFROM

\>= ”Mon, 01 Jan 2007 00:00:00 GMT”’act_block_ssl

• Bind your new policy globally.

Because this SSL policy should apply to any user’s SSL connection unless a more specific SSL
policy applies, you may want to assign it a low priority. If you assign it a priority of one thousand
(1000), that should ensure that other SSL policies are evaluated first, meaning that this policy
will apply only to connections that do not match more specific policy criteria.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1380

NetScaler 12.0

Migration of Apache mod_rewrite rules to the default syntax

November 5, 2018
Contributed by:
C
The Apache HTTP Server provides an engine known as mod_rewrite for rewriting HTTP request URLs.
If you migrate the mod_rewrite rules from Apache to the NetScaler, you boost back-end server per-
formance. In addition, because the NetScaler typically load balances multiple (sometimes thousands
of) Web servers, after migrating the rules to the NetScaler you will have a single point of control for
these rules.
Following are examples of mod_rewrite functions, and translations of these functions into Rewrite
and Responder policies on the NetScaler.

Converting URL variations into canonical URLs

On some Web servers you can have multiple URLs for a resource. Although the canonical URLs should
be used and distributed, other URLs can exist as shortcuts or internal URLs. You can make sure that
users see the canonical URL regardless of the URL used to make an initial request.
In the following examples, the URL /~user is converted to /u/user.

Apache mod_rewrite solution for converting a URL

1 RewriteRule ^/~([^/]+)/?(.*) /u/$1/$2[R]

NetScaler solution for converting a URL

1 add responder action act1 redirect ’”/u/”+HTTP.REQ.URL.AFTER_STR(”/~”)’

-bypassSafetyCheck yes
2 add responder policy pol1 ’HTTP.REQ.URL.STARTSWITH(”/~”) && HTTP.REQ.
URL.LENGTH.GT(2)’ act1
3 bind responder global pol1 100

Converting host name variations to canonical host names

You can enforce the use of a particular host name for reaching a site. For example, you can enforce
the use of www.example.com instead of example.com.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1381

NetScaler 12.0

Apache mod_rewrite solution for enforcing a particular host name for sites running on
a port other than 80

1 RewriteCond %{
2 HTTP_HOST }
3 !^www.example.com
4 RewriteCond %{
5 HTTP_HOST }
6 !^$
7 RewriteCond %{
8 SERVER_PORT }
9 !^80$
10 RewriteRule ^/(.*) http://www.example.com:%{
11 SERVER_PORT }
12 /$1 [L,R]

Apache mod_rewrite solution for enforcing a particular host name for sites running on
port 80

1 RewriteCond %{
2 HTTP_HOST }
3 !^www.example.com
4 RewriteCond %{
5 HTTP_HOST }
6 !^$
7 RewriteRule ^/(.*) http://www.example.com/$1 [L,R]

NetScaler solution for enforcing a particular host name for sites running on a port
other than 80

1 add responder action act1 redirect ’”http://www.example.com:”+CLIENT.

TCP.DSTPORT+HTTP.REQ.URL’ -bypassSafetyCheck yes
2 add responder policy pol1 ’!HTTP.REQ.HOSTNAME.CONTAINS(”www.example.com
”)&&!HTTP.REQ.HOSTNAME.EQ(””)&&!HTTP.REQ.HOSTNAME.PORT.EQ(80)&&HTTP.
REQ.HOSTNAME.CONTAINS(”example.com”)’ act1
3 bind responder global pol1 100 END

NetScaler solution for enforcing a particular host name for sites running on port 80

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1382

NetScaler 12.0

1 add responder action act1 redirect ’”http://www.example.com”+HTTP.REQ.

URL’ -bypassSafetyCheck yes
2 add responder policy pol1 ’!HTTP.REQ.HOSTNAME.CONTAINS(”www.example.
com”)&&!HTTP.REQ.HOSTNAME.EQ(””)&&HTTP.REQ.HOSTNAME.PORT.EQ(80)&&
HTTP.REQ.HOSTNAME.CONTAINS(”example.com”)’ act1
3 bind responder global pol1 100 END

Moving a document root

Usually the document root of a Web server is based on the URL “/”. However, the document root can
be any directory. You can redirect traffic to the document root if it changes from the top-level “/”
directory to another directory.

In the following examples, you change the document root from / to /e/www. The first two examples
simply replace one string with another. The third example is more universal because, along with re-
placing the root directory, it preserves the rest of the URL (the path and query string), for example,
redirecting /example/file.html to /e/www/example/file.html.

Apache mod_rewrite solution for moving the document root

1 RewriteEngine on
2 RewriteRule ^/$ /e/www/ [R]

NetScaler solution for moving the document root

1 add responder action act1 redirect ’”/e/www/”’ -bypassSafetyCheck yes

2 add responder policy pol1 ’HTTP.REQ.URL.EQ(”/”)’ act1
3 bind responder global pol1 100

NetScaler solution for moving the document root and appending path information to
the request

1 add responder action act1 redirect ’”/e/www”+HTTP.REQ.URL’ -

bypassSafetyCheck yes
2 add responder policy pol1 ’!HTTP.REQ.URL.STARTSWITH(”/e/www/”)’ act1
3 bind responder global pol1 100 END

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1383

NetScaler 12.0

Moving home directories to a new web server

You may want to redirect requests that are sent to home directories on a Web server to a different
Web server. For example, if a new Web server is replacing an old one over time, as you migrate home
directories to the new location you need to redirect requests for the migrated home directories to the
new Web server.

In the following examples, the host name for the new Web server is newserver.

Apache mod_rewrite solution for redirecting to another Web server

1 RewriteRule ^/(.+) http://newserver/$1 [R,L]

NetScaler solution for redirecting to another Web server (method 1)

1 add responder action act1 redirect ’”http://newserver”+HTTP.REQ.URL’ -

bypassSafetyCheck yes
2 add responder policy pol1 ’HTTP.REQ.URL.REGEX_MATCH(re#^/(.+)#)’ act1
3 bind responder global pol1 100 END

NetScaler solution for redirecting to another Web server (method 2)

1 add responder action act1 redirect ’”http://newserver”+HTTP.REQ.URL’ -

bypassSafetyCheck yes
2 add responder policy pol1 ’HTTP.REQ.URL.LENGTH.GT(1)’ act1
3 bind responder global pol1 100 END

Working with structured home directories

Typically, a site with thousands of users has a structured home directory layout. For example,
each home directory may reside under a subdirectory that is named using the first character
of the user name. For example, the home directory for jsmith (/~jsmith/anypath) might be
/home/j/smith/.www/anypath, and the home directory for rvalveti (/~rvalveti/anypath) might be
/home/r/rvalveti/.www/anypath.

The following examples redirect requests to the home directory.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1384

NetScaler 12.0

Apache mod_rewrite solution for structured home directories

1 RewriteRule ^/~(([a-z])[a-z0-9]+)(.*) /home/$2/$1/.www$3

NetScaler solution for structured home directories

1 NetScaler solution for structured home directories

2
3 add rewrite action act1 replace ’HTTP.REQ.URL’ ’”/home/”+ HTTP.REQ.URL
.AFTER_STR(”~”).PREFIX(1)+”/”+ HTTP.REQ.URL.AFTER_STR(”~”).
BEFORE_STR(”/”)+”/.www”+HTTP.REQ.URL.SKIP(\’/\’,1)’ -
bypassSafetyCheck yes
4 add rewrite policy pol1 ’HTTP.REQ.URL.PATH.STARTSWITH(”/~”)’ act1
5 bind rewrite global pol1 100

Redirecting invalid URLs to other web servers

If a URL is not valid, it should be redirected to another Web server. For example, you should redirect
to another Web server if a file that is named in a URL does not exist on the server that is named in the
URL.

On Apache, you can perform this check using mod_rewrite. On the NetScaler, an HTTP callout can
check for a file on a server by running a script on the server. In the following NetScaler examples, a
script named file_check.cgi processes the URL and uses this information to check for the presence of
the target file on the server. The script returns TRUE or FALSE, and the NetScaler uses the value that
the script returns to validate the policy.

In addition to performing the redirection, the NetScaler can add custom headers or, as in the second
NetScaler example, it can add text in the response body.

Apache mod_rewrite solution for redirection if a URL is wrong

1 RewriteCond /your/docroot/%{
2 REQUEST_FILENAME }
3 !-f
4 RewriteRule ^(.+) http://webserverB.com/$1 [R]

NetScaler solution for redirection if a URL is wrong (method 1)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1385

NetScaler 12.0

1 add HTTPCallout Call

2 set policy httpCallout Call -IPAddress 10.102.59.101 -port 80 -hostExpr
’”10.102.59.101”’ -returnType BOOL -ResultExpr ’HTTP.RES.BODY(100).
CONTAINS(”True”)’ -urlStemExpr ’”/cgi-bin/file_check.cgi”’ -
parameters query=http.req.url.path -headers Name(”ddd”)
3 add responder action act1 redirect ’”http://webserverB.com”+HTTP.REQ.
URL’ -bypassSafetyCheck yes
4 add responder policy pol1 ’!HTTP.REQ.HEADER(”Name”).EXISTS && !SYS.
HTTP_CALLOUT(call)’ act1
5 bind responder global pol1 100

NetScaler solution for redirection if a URL is wrong (method 2)

1 add HTTPCallout Call

2 set policy httpCallout Call -IPAddress 10.102.59.101 -port 80 -hostExpr
’”10.102.59.101”’ -returnType BOOL -ResultExpr ’HTTP.RES.BODY(100).
CONTAINS(”True”)’ -urlStemExpr ’”/cgi-bin/file_check.cgi”’ -
parameters query=http.req.url.path -headers Name(”ddd”)
3 add responder action act1 respondwith ’”HTTP/1.1 302 Moved
Temporarily\r\nLocation: http://webserverB.com”+HTTP.REQ.URL+”\r\n\r
\nHTTPCallout Used”’ -bypassSafetyCheck yes
4 add responder policy pol1 ’!HTTP.REQ.HEADER(”Name”).EXISTS && !SYS.
HTTP_CALLOUT(call)’ act1
5 bind responder global pol1 100

Rewriting a URL based on time

You can rewrite a URL based on the time. The following examples change a request for example.html
to example.day.html or example.night.html, depending on the time of day.

Apache mod_rewrite solution for rewriting a URL based on the time

1 RewriteCond %{
2 TIME_HOUR }
3 %{
4 TIME_MIN }
5 >0700
6 RewriteCond %{
7 TIME_HOUR }
8 %{

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1386

NetScaler 12.0

9 TIME_MIN }
10 <1900
11 RewriteRule ^example\.html$ example.day.html [L]
12 RewriteRule ^example\.html$ example.night.html

NetScaler solution for rewriting a URL based on the time

1 add rewrite action act1 insert_before ’HTTP.REQ.URL.PATH.SUFFIX

(\’.\’,0)’ ’”day.”’
2 add rewrite action act2 insert_before ’HTTP.REQ.URL.PATH.SUFFIX
(\’.\’,0)’ ’”night.”’
3 add rewrite policy pol1 ’SYS.TIME.WITHIN(LOCAL 07h 00m,LOCAL 18h 59m)’
act1
4 add rewrite policy pol2 ’true’ act2
5 bind rewrite global pol1 101
6 bind rewrite global pol2 102

Redirecting to a new file name (Invisible to the User)

If you rename a Web page, you can continue to support the old URL for backward compatibility while
preventing users from recognizing that the page was renamed.

In the first two of the following examples, the base directory is /~quux/. The third example accommo-
dates any base directory and the presence of query strings in the URL.

Apache mod_rewrite solution for managing a file name change in a fixed location

1 RewriteEngine on
2 RewriteBase /~quux/
3 RewriteRule ^foo\.html$ bar.html

NetScaler solution for managing a file name change in a fixed location

1 add rewrite action act1 replace ’HTTP.REQ.URL.AFTER_STR(”/~quux”).

SUBSTR(”foo.html”)’ ’”bar.html”’
2 add rewrite policy pol1 ’HTTP.REQ.URL.ENDSWITH(”/~quux/foo.html”)’ act1
3 bind rewrite global pol1 100

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1387

NetScaler 12.0

NetScaler solution for managing a file name change regardless of the base directory or
query strings in the URL

1 add rewrite action act1 replace ’HTTP.REQ.URL.PATH.SUFFIX(\’/\’,0)’ ’”

bar.html”’
2 Add rewrite policy pol1 ’HTTP.REQ.URL.PATH.CONTAINS(”foo.html”)’ act1
3 Bind rewrite global pol1 100

Redirecting to new file name (user-visible URL)

If you rename a Web page, you may want to continue to support the old URL for backward compati-
bility and allow users to see that the page was renamed by changing the URL that is displayed in the
browser.

In the first two of the following examples, redirection occurs when the base directory is /~quux/. The
third example accommodates any base directory and the presence of query strings in the URL.

Apache mod_rewrite solution for changing the file name and the URL displayed in the
browser

1 RewriteEngine on
2 RewriteBase /~quux/
3 RewriteRule ^old\.html$ new.html [R]

NetScaler solution for changing the file name and the URL displayed in the browser

1 add responder action act1 redirect ’HTTP.REQ.URL.BEFORE_STR(”foo.html”)

+”new.html”’ -bypassSafetyCheck yes
2 add responder policy pol1 ’HTTP.REQ.URL.ENDSWITH(”/~quux/old.html”)’
act1
3 bind responder global pol1 100

NetScaler solution for changing the file name and the URL displayed in the browser
regardless of the base directory or query strings in the URL

1 add responder action act1 redirect ’HTTP.REQ.URL.PATH.BEFORE_STR(”old.

html”)+”new.html”+HTTP.REQ.URL.AFTER_STR(”old.html”)’ -
bypassSafetyCheck yes

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1388

NetScaler 12.0

2 add responder policy pol1 ’HTTP.REQ.URL.PATH.CONTAINS(”old.html”)’ act1

3 bind responder global pol1 100

Accommodating browser dependent content

To accommodate browser-specific limitations—at least for important top-level pages—it is sometimes

necessary to set restrictions on the browser type and version. For example, you might want to set
a maximum version for the latest Netscape variants, a minimum version for Lynx browsers, and an
average feature version for all others.

The following examples act on the HTTP header “User-Agent”, such that if this header begins with
“Mozilla/3”, the page MyPage.html is rewritten to MyPage.NS.html. If the browser is “Lynx” or “Mozilla”
version 1 or 2, the URL becomes MyPage.20.html. All other browsers receive page MyPage.32.html.

Apache mod_rewrite solution for browser-specific settings

1 RewriteCond %{
2 HTTP_USER_AGENT }
3 ^Mozilla/3.*
4 RewriteRule ^MyPage\.html$ MyPage.NS.html [L]
5 RewriteCond %{
6 HTTP_USER_AGENT }
7 ^Lynx/.* [OR]
8 RewriteCond %{
9 HTTP_USER_AGENT }
10 ^Mozilla/[12].*
11 RewriteRule ^MyPage\.html$ MyPage.20.html [L]
12 RewriteRule ^fMyPage\.html$ MyPage.32.html [L]
13 NetScaler solution for browser-specific settings
14 add patset pat1
15 bind patset pat1 Mozilla/1
16 bind Patset pat1 Mozilla/2
17 bind patset pat1 Lynx
18 bind Patset pat1 Mozilla/3
19 add rewrite action act1 insert_before ’HTTP.REQ.URL.SUFFIX’ ’”NS.”’
20 add rewrite action act2 insert_before ’HTTP.REQ.URL.SUFFIX’ ’”20.”’
21 add rewrite action act3 insert_before ’HTTP.REQ.URL.SUFFIX’ ’”32.”’
22 add rewrite policy pol1 ’HTTP.REQ.HEADER(”User-Agent”).STARTSWITH_INDEX
(”pat1”).EQ(4)’ act1
23 add rewrite policy pol2 ’HTTP.REQ.HEADER(”User-Agent”).STARTSWITH_INDEX
(”pat1”).BETWEEN(1,3)’ act2

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1389

NetScaler 12.0

24 add rewrite policy pol3 ’!HTTP.REQ.HEADER(”User-Agent”).STARTSWITH_ANY

(”pat1”)’ act3
25 bind rewrite global pol1 101 END
26 bind rewrite global pol2 102 END
27 bind rewrite global pol3 103 END

Blocking access by robots

You can block a robot from retrieving pages from a specific directory or a set of directories to ease up
the traffic to and from these directories. You can restrict access based on the specific location or you
can block requests based on information in User-Agent HTTP headers.

In the following examples, the Web location to be blocked is /~quux/foo/arc/, the IP addresses to be
blocked are 123.45.67.8 and 123.45.67.9, and the robot’s name is NameOfBadRobot.

Apache mod_rewrite solution for blocking a path and a User-Agent header

1 RewriteCond %{
2 HTTP_USER_AGENT }
3 ^NameOfBadRobot.*
4 RewriteCond %{
5 REMOTE_ADDR }
6 ^123\.45\.67\.[8-9]$
7 RewriteRule ^/~quux/foo/arc/.+ - [F]

NetScaler solution for blocking a path and a User-Agent header

1 add responder action act1 respondwith ’”HTTP/1.1 403 Forbidden\r\n\r\n”

’
2 add responder policy pol1 ’HTTP.REQ.HEADER(”User_Agent”).STARTSWITH(”
NameOfBadRobot”)&&CLIENT.IP.SRC.EQ(123.45.67.8)&&CLIENT.IP.SRC.EQ
(123.45.67.9) && HTTP.REQ.URL.STARTSWITH(”/~quux/foo/arc”)’ act1
3 bind responder global pol1 100

Blocking access to inline images

If you find people frequently going to your server to copy inline graphics for their own use (and gen-
erating unnecessary traffic), you may want to restrict the browser’s ability to send an HTTP Referer
header.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1390

NetScaler 12.0

In the following example, the graphics are located in Example.

Apache mod_rewrite solution for blocking access to an inline image

1 RewriteCond %{
2 HTTP_REFERER }
3 !^$
4 RewriteCond %{
5 HTTP_REFERER }
6 !^http://www.quux-corp.de/~quux/.*$
7 RewriteRule .*\.gif$ - [F]

NetScaler solution for blocking access to an inline image

1 add patset pat1

2 bind patset pat1 .gif
3 bind patset pat1 .jpeg
4 add responder action act1 respondwith ’”HTTP/1.1 403 Forbidden\r\n\r\n”
’
5 add responder policy pol1 ’!HTTP.REQ.HEADER(”Referer”).EQ(””) && !HTTP.
REQ.HEADER(”Referer”).STARTSWITH(”http://www.quux-corp.de/~quux/”)&&
HTTP.REQ.URL.ENDSWITH_ANY(”pat1”)’ act1
6 bind responder global pol1 100

Creating extensionless links

To prevent users from knowing application or script details on the server side, you can hide file ex-
tensions from users. To do this, you may want to support extensionless links. You can achieve this
behavior by using rewrite rules to add an extension to all requests, or to selectively add extensions to
requests.

The first two of the following examples show adding an extension to all request URLs. In the last exam-
ple, one of two file extensions is added. Note that in the last example, the mod_rewrite module can
easily find the file extension because this module resides on the Web server. In contrast, the NetScaler
must invoke an HTTP callout to check the extension of the requested file on the Web server. Based on
the callout response, the NetScaler adds the .html or .php extension to the request URL.

Note

In the second NetScaler example, an HTTP callout is used to query a script named

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1391

NetScaler 12.0

file_check.cgi hosted on the server. This script checks whether the argument that is provided in
the callout is a valid file name.

Apache mod_rewrite solution for adding a .php extension to all requests

1 RewriteRule ^/?([a-z]+)$ $1.php [L]

NetScaler policy for adding a .php extension to all requests

1 add rewrite action act1 insert_after ’HTTP.REQ.URL’ ’”.php”’

2 add rewrite policy pol1 ’HTTP.REQ.URL.PATH.REGEX_MATCH(re#^/([a-z]+)$#)
’ act1
3 bind rewrite global pol1 100

Apache mod_rewrite solution for adding either .html or .php extensions to requests

1 RewriteCond %{
2 REQUEST_FILENAME }
3 .php -f
4 RewriteRule ^/?([a-zA-Z0-9]+)$ $1.php [L]
5 RewriteCond %{
6 REQUEST_FILENAME }
7 .html ‒ f
8 RewriteRule ^/?([a-zA-Z0-9]+)$ $1.html [L]

NetScaler policy for adding either .html or .php extensions to requests

1 add HTTPCallout Call_html

2 add HTTPCallout Call_php
3 set policy httpCallout Call_html -IPAddress 10.102.59.101 -port 80 -
hostExpr ’”10.102.59.101”’ -returnType BOOL -ResultExpr ’HTTP.RES.
BODY(100).CONTAINS(”True”)’ -urlStemExpr ’”/cgi-bin/file_check.cgi”
’ -parameters query=http.req.url+”.html”
4 set policy httpCallout Call_php -IPAddress 10.102.59.101 -port 80 -
hostExpr ’”10.102.59.101”’ -returnType BOOL -ResultExpr ’HTTP.RES.
BODY(100).CONTAINS(”True”)’ -urlStemExpr ’”/cgi-bin/file_check.cgi”
’ -parameters query=http.req.url+”.php”
5 add patset pat1
6 bind patset pat1 .html

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1392

NetScaler 12.0

7 bind patset pat1 .php

8 bind patset pat1 .asp
9 bind patset pat1 .cgi
10 add rewrite action act1 insert_after ’HTTP.REQ.URL.PATH’ ’”.html”’
11 add rewrite action act2 insert_after ”HTTP.REQ.URL.PATH” ’”.php”’
12 add rewrite policy pol1 ’!HTTP.REQ.URL.CONTAINS_ANY(”pat1”) && SYS.
HTTP_CALLOUT(Call_html)’ act1
13 add rewrite policy pol2 ’!HTTP.REQ.URL.CONTAINS_ANY(”pat1”) && SYS.
HTTP_CALLOUT(Call_php)’ act2
14 bind rewrite global pol1 100 END
15 bind rewrite global pol2 101 END

Redirecting a Working URI to a New Format

Suppose that you have a set of working URLs that resemble the following:

1 /index.php?id=nnnn

To change these URLs to /nnnn and make sure that search engines update their indexes to the new
URI format, you need to do the following:

• Redirect the old URIs to the new ones so that search engines update their indexes.
• Rewrite the new URI back to the old one so that the index.php script runs correctly.

To accomplish this, you can insert marker code into the query string (making sure that the marker
code is not seen by visitors), and then removing the marker code for the index.php script.

The following examples redirect from an old link to a new format only if a marker is not present in the
query string. The link that uses the new format is re-written back to the old format, and a marker is
added to the query string.

Apache mod_rewrite solution

1 RewriteCond %{
2 QUERY_STRING }
3 !marker
4 RewriteCond %{
5 QUERY_STRING }
6 id=([-a-zA-Z0-9_+]+)
7 RewriteRule ^/?index\.php$ %1? [R,L]
8 RewriteRule ^/?([-a-zA-Z0-9_+]+)$ index.php?marker&id=$1 [L]
9 NetScaler solution

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1393

NetScaler 12.0

10 add responder action act_redirect redirect ’HTTP.REQ.URL.PATH.

BEFORE_STR(”index.php”)+HTTP.REQ.URL.QUERY.VALUE(”id”)’ -
bypassSafetyCheck yes
11 add responder policy pol_redirect ’!HTTP.REQ.URL.QUERY.CONTAINS(”marker
”)&& HTTP.REQ.URL.QUERY.VALUE(”id”).REGEX_MATCH(re/[-a-zA-Z0-9_+]+/)
&& HTTP.REQ.URL.PATH.CONTAINS(”index.php”)’ act_redirect
12 bind responder global pol_redirect 100 END
13 add rewrite action act1 replace ’HTTP.REQ.URL.PATH.SUFFIX(\’/\’,0)’ ’”
index.phpmarker&id=”+HTTP.REQ.URL.PATH.SUFFIX(\’/\’,0)’ -
bypassSafetyCheck yes
14 add rewrite policy pol1 ’!HTTP.REQ.URL.QUERY.CONTAINS(”marker”)’ act1
15 bind rewrite global pol1 100 END

Ensuring That a Secure Server Is Used for Selected Pages

To make sure that only secure servers are used for selected Web pages, you can use the following
Apache mod_rewrite code or NetScaler Responder policies.

Apache mod_rewrite solution

1 RewriteCond %{
2 SERVER_PORT }
3 !^443$
4 RewriteRule ^/?(page1|page2|page3|page4|page5)$ https://www.example.
com/%1 [R,L]

NetScaler solution using regular expressions

1 add responder action res_redirect redirect ’”https://www.example.com”+

HTTP.REQ.URL’ -bypassSafetyCheck yes
2 add responder policy pol_redirect ’!CLIENT.TCP.DSTPORT.EQ(443)&&HTTP.
REQ.URL.REGEX_MATCH(re/page[1-5]/)’ res_redirect
3 bind responder global pol_redirect 100 END

NetScaler solution using pattern sets

1 add patset pat1

2 bind patset pat1 page1
3 bind patset pat1 page2

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1394

NetScaler 12.0

4 bind patset pat1 page3

5 bind patset pat1 page4
6 bind patset pat1 page5
7 add responder action res_redirect redirect ’”https://www.example.com”+
HTTP.REQ.URL’ -bypassSafetyCheck yes
8 add responder policy pol_redirect ’!CLIENT.TCP.DSTPORT.EQ(443)&&HTTP.
REQ.URL.CONTAINS_ANY(”pat1”)’ res_redirect
9 bind responder global pol_redirect 100 END

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Rate limiting

September 24, 2018

Contributed by:
C

The rate limiting feature enables you to define the maximum load for a given network entity or virtual
entity on the NetScaler appliance. The feature enables you to configure the appliance to monitor the
rate of traffic associated with the entity and take preventive action, in real time, based on the traffic
rate. This feature is particularly useful when the network is under attack from a hostile client that
is sending the appliance a flood of requests. You can mitigate the risks that affect the availability of
resources to clients, and you can improve the reliability of the network and the resources that the
appliance manages.

You can monitor and control the rate of traffic that is associated with virtual and user-defined entities,
including virtual servers, URLs, domains, and combinations of URLs and domains. You can throttle the
rate of traffic if it is too high, base information caching on the traffic rate, and redirect traffic to a given
load balancing virtual server if the traffic rate exceeds a predefined limit. You can apply rate-based
monitoring to HTTP, TCP, and DNS requests.

To monitor the rate of traffic for a given scenario, you configure a rate limit identifier. A rate limit iden-
tifier specifies numeric thresholds such as the maximum number of requests or connections (of a par-
ticular type) that are permitted in a specified time period called a time slice.

Optionally, you can configure filters, known as stream selectors, and associate them with rate limit
identifiers when you configure the identifiers. After you configure the optional stream selector and
the limit identifier, you must invoke the limit identifier from a default syntax policy. You can invoke

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1395

NetScaler 12.0

identifiers from any feature in which the identifier may be useful, including rewrite, responder, DNS,
and integrated caching.
You can globally enable and disable SNMP traps for rate limit identifiers. Each trap contains cumula-
tive data for the rate limit identifier’s configured data collection interval (time slice), unless you speci-
fied multiple traps to be generated per time slice. For more information about configuring SNMP traps
and managers, see “SNMP.”
1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring a Stream Selector

September 24, 2018

Contributed by:
C
A traffic stream selector is an optional filter for identifying an entity for which you want to throttle
access. The selector is applied to a request or a response and selects data points (keys ) that can
be analyzed by a rate stream identifier. These data points can be based on almost any characteristic
of the traffic, including IP addresses, subnets, domain names, TCP or UDP identifiers, and particular
strings or extensions in URLs.
A stream selector consists of individual default syntax expressions called selectlets. Each selectlet
is a non-compound default syntax expression. A traffic stream selector can contain up to five non-
compound expressions called selectlets. Each selectlet is considered to be in an AND relationship
with the other expressions. Following are some examples of selectlets:

1 http.req.url
2 http.res.body(1000>after_str(”car_model”).before_str(”made_in”)”
3 ”client.ip.src.subnet(24)”

The order in which you specify parameters is significant. For example, if you configure an IP address
and a domain (in that order) in one selector, and then specify the domain and the IP address (in the
reverse order) in another selector, the NetScaler considers these values to be unique. This can lead
to the same transaction being counted twice. Also, if multiple policies invoke the same selector, the
NetScaler, again, can count the same transaction more than once.
Note: If you modify an expression in a
stream selector, you may get an error if any policy that invokes it is bound to a new policy label or bind

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1396

NetScaler 12.0

point. For example, suppose that you create a

stream selector named
myStreamSelector1, invoke it from myLimitID1, and invoke the identifier from a DNS policy named
dnsRateLimit1. If you change the expression in
myStreamSelector1, you might receive an error when binding dnsRateLimit1 to a new bind point. The
workaround is to modify these expressions before creating the policies that invoke them.

To configure a traffic stream selector by using the command line interface

At the command prompt, type:

1 add stream selector <name> <rule> ...

Example:

1 add stream selector myStreamSel HTTP.REQ.URL CLIENT.IP.SRC

To configure a stream selector by using the GUI

Navigate to AppExpert > Rate Limiting > Selectors, click Add and specify the relevant details.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Viewing the Traffic Rate

September 24, 2018

Contributed by:
C

If traffic through one or more virtual servers matches a rate-based policy, you can view the rate of this
traffic. The rate statistics are maintained in the limit identifier that you named in the rule for the rate-
based policy. If more than one policy uses the same limit identifier, you can view the traffic rate as
defined by hits to all of the policies that use the particular limit identifier.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1397

NetScaler 12.0

To view the traffic rate by using the command line interface

At the command prompt, type the following command to view the traffic rate:

1 show ns limitSessions <limitIdentifier>

Example:

1 sh limitsession myLimitSession

To view the traffic rate by using the GUI

1. Navigate to AppExpert > Rate Limiting > Limit Identifiers.

2. Select a limit identifier whose traffic rate you want to view.
3. Click the Show Sessions button. If traffic through one or more virtual servers has matched a rate
limiting policy that uses this limit identifier (and the hits are within the configured time slice for
this identifier), the Session Details dialog box appears. Otherwise, you receive a “No session
exists” message.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Testing a Rate-Based Policy

September 24, 2018

Contributed by:
C

To test a rate-based policy, you can send traffic to any virtual server to which a rate-based policy is
bound.

Task overview: Testing a rate-based policy

1. Configure a stream selector (optional) and a rate limit identifier (required). For example:

1 add stream selector sel_subnet Q.URL ”CLIENT.IP.SRC.SUBNET(24)”

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1398

NetScaler 12.0

2 add ns limitIdentifier k_subnet -Threshold 4 -timeSlice 3600 -mode

REQUEST_RATE -limittype smooth -selectorName sel_subnet -
trapsInTimeSlice 8

2. Configure the action that you want to associate with the policy that uses the rate limit identifier.
For example:

1 add responder action resp_redirect redirect ”\”http://

response_site.com/\””

3. Configure a policy that uses the sys.check_limit expression prefix to call the rate limit identifier.
For example, the policy can apply a rate limit identifier to all requests arriving from a particular
subnet, as follows:

1 add responder policy resp_subnet ”SYS.CHECK_LIMIT(\”k_subnet\”)”

resp_redirect

4. Bind the policy globally or to a virtual server. For example:

1 bind responder global resp_subnet 6 END -type DEFAULT

5. In a browser address bar, send a test HTTP query to a virtual server. For example:

1 http://<IP of a vserver>/testsite/test.txt

6. At the NetScaler command prompt, type:

1 show ns limitSessions \<limitIdentifier\>

Example

1 > sh limitsession k_subnet

2 1) Time Remaining: 98 secs Hits: 2
Action Taken: 0
3 Total Hash: 1718618 Hash String: /test.txt
4 IPs gathered:
5 1) 10.217.253.0
6 Active Transactions: 0
7 Done
8 >

7. Repeat the query and check the limit identifier statistics again to verify that the statistics are
being updated correctly.</span>

1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1399

NetScaler 12.0

2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Viewing the Traffic Rate

September 24, 2018

Contributed by:
C

If traffic through one or more virtual servers matches a rate-based policy, you can view the rate of this
traffic. The rate statistics are maintained in the limit identifier that you named in the rule for the rate-
based policy. If more than one policy uses the same limit identifier, you can view the traffic rate as
defined by hits to all of the policies that use the particular limit identifier.

To view the traffic rate by using the command line interface

At the command prompt, type the following command to view the traffic rate:

1 show ns limitSessions <limitIdentifier>

Example:

1 sh limitsession myLimitSession

To view the traffic rate by using the GUI

1. Navigate to AppExpert > Rate Limiting > Limit Identifiers.

2. Select a limit identifier whose traffic rate you want to view.
3. Click the Show Sessions button. If traffic through one or more virtual servers has matched a rate
limiting policy that uses this limit identifier (and the hits are within the configured time slice for
this identifier), the Session Details dialog box appears. Otherwise, you receive a “No session
exists” message.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1400

NetScaler 12.0

Testing a Rate-Based Policy

September 24, 2018

Contributed by:
C

To test a rate-based policy, you can send traffic to any virtual server to which a rate-based policy is
bound.

Task overview: Testing a rate-based policy

1. Configure a stream selector (optional) and a rate limit identifier (required). For example:

1 add stream selector sel_subnet Q.URL ”CLIENT.IP.SRC.SUBNET(24)”

2 add ns limitIdentifier k_subnet -Threshold 4 -timeSlice 3600 -mode
REQUEST_RATE -limittype smooth -selectorName sel_subnet -
trapsInTimeSlice 8

2. Configure the action that you want to associate with the policy that uses the rate limit identifier.
For example:

1 add responder action resp_redirect redirect ”\”http://

response_site.com/\””

3. Configure a policy that uses the sys.check_limit expression prefix to call the rate limit identifier.
For example, the policy can apply a rate limit identifier to all requests arriving from a particular
subnet, as follows:

1 add responder policy resp_subnet ”SYS.CHECK_LIMIT(\”k_subnet\”)”

resp_redirect

4. Bind the policy globally or to a virtual server. For example:

1 bind responder global resp_subnet 6 END -type DEFAULT

5. In a browser address bar, send a test HTTP query to a virtual server. For example:

1 http://<IP of a vserver>/testsite/test.txt

6. At the NetScaler command prompt, type:

1 show ns limitSessions \<limitIdentifier\>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1401

NetScaler 12.0

Example

1 > sh limitsession k_subnet

2 1) Time Remaining: 98 secs Hits: 2
Action Taken: 0
3 Total Hash: 1718618 Hash String: /test.txt
4 IPs gathered:
5 1) 10.217.253.0
6 Active Transactions: 0
7 Done
8 >

7. Repeat the query and check the limit identifier statistics again to verify that the statistics are
being updated correctly.</span>

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Examples of Rate-Based Policies

January 6, 2019

Contributed by:
C

The following table shows examples of rate-based policies.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Sample Use Cases for Rate-Based Policies

September 24, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1402

NetScaler 12.0

The following scenarios describe two uses of rate-based policies in global server load balancing
(GSLB):

• The first scenario describes the use of a rate-based policy that sends traffic to a new data center
if the rate of DNS requests exceed 1000 per second.
• In the second scenario, if more than five DNS requests arrive for a local DNS (LDNS) client within
a particular period, the additional requests are dropped.

Redirecting Traffic on the Basis of Traffic Rate

In this scenario, you configure a proximity-based load balancing method, and a rate-limiting pol-
icy that identifies DNS requests for a particular region. In the rate-limiting policy, you specify a
threshold of 1000 DNS requests per second. A DNS policy applies the rate limiting policy to DNS
requests for the region “Europe.GB.17.London.UK-East.ISP-UK.” In the DNS policy, DNS requests
that exceed the rate limiting threshold, starting with request 1001 and continuing to the end of the
one-second interval, are to be forwarded to the IP addresses that are associated with the region
“North America.US.TX.Dallas.US-East.ISP-US.”

The following configuration demonstrates this scenario:

1 add stream selector DNSSelector1 client.udp.dns.domain

2
3 add ns limitIdentifier DNSLimitIdentifier1 -threshold 5 -timeSlice 1000
-selectorName DNSSelector1
4
5 add dns policy DNSLimitPolicy1 ”client.ip.src.matches_location(\”Europe
.GB.17.London.*.*\”) &&
6 sys.check_limit(\”DNSLimitIdentifier1\”)” -preferredLocation ”North
America.US.TX.Dallas.*.*”
7
8 bind dns global DNSLimitPolicy1 5

Dropping DNS Requests on the Basis of Traffic Rate

In the following example of global server load balancing, you configure a rate limiting policy that per-
mits a maximum of five DNS requests in a particular interval, per domain, to be directed to an LDNS
client for resolution. Any requests that exceed this rate are dropped. This type of policy can help pro-
tect the NetScaler from resource exploitation. For example, in this scenario, if the time to live (TTL)
for a connection is five seconds, this policy prevents the LDNS from requerying a domain. Instead, it
uses data that is cached on the NetScaler.

1 add stream selector LDNSSelector1 client.udp.dns.domain client.ip.src

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1403

NetScaler 12.0

2
3 add ns limitIdentifier LDNSLimitIdentifier1 -threshold 5 -timeSlice
1000 -selectorName LDNSSelector1
4
5 add dns policy LDNSPolicy1 ”client.udp.dns.domain.contains(\”.\”) &&
sys.check_limit(\”LDNSLimitIdentifier1\”)” -drop YES
6
7 bind dns global LDNSPolicy1 6
8
9 show gslb vserver gvip
10
11 gvip - HTTP State: UP
12 Last state change was at Mon Sep 8 11:50:48 2008 (+711 ms)
13 Time since last state change: 1 days, 02:55:08.830
14 Configured Method: STATICPROXIMITY
15 BackupMethod: ROUNDROBIN
16 No. of Bound Services : 3 (Total) 3 (Active)
17 Persistence: NONE Persistence ID: 100
18 Disable Primary Vserver on Down: DISABLED Site Persistence: NONE
19 Backup Session Timeout: 0
20 Empty Down Response: DISABLED
21 Multi IP Response: DISABLED Dynamic Weights: DISABLED
22 Cname Flag: DISABLED
23 Effective State Considered: NONE
24 1) site11_svc(10.100.00.00: 80)- HTTP State: UP Weight: 1
25 Dynamic Weight: 0 Cumulative Weight: 1
26 Effective State: UP
27 Threshold : BELOW
28 Location: Europe.GB.17.London.UK-East.ISP-UK
29 2) site12_svc(10.101.00.100: 80)- HTTP State: UP Weight: 1
30 Dynamic Weight: 0 Cumulative Weight: 1
31 Effective State: UP
32 Threshold : BELOW
33 Location: North America.US.TX.Dallas.US-East.ISP-US
34 3) site13_svc(10.102.00.200: 80)- HTTP State: UP Weight: 1
35 Dynamic Weight: 0 Cumulative Weight: 1
36 Effective State: UP
37 Threshold : BELOW
38 Location: North America.US.NJ.Salem.US-Mid.ISP-US
39 1) www.gslbindia.com TTL: 5 secn
40 Cookie Timeout: 0 min Site domain TTL: 3600 sec
41 Done

1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1404

NetScaler 12.0

2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Rate Limiting for Traffic Domains

September 24, 2018

Contributed by:
C

You can configure rate limiting for traffic domains. The following expression in the NetScaler expres-
sions language for identifies traffic associated with traffic domains.

• client.traffic_domain.id

You can configure rate limiting for traffic associated with a particular traffic domain, a set of traffic
domains, or all traffic domains.

For configuring rate limiting for traffic domains, you perform the following steps on a NetScaler appli-
ance by using the GUI or the NetScaler command line:

1. Configure a stream selector that uses the client.traffic_domain.id expression for identifying the
traffic, associated with traffic domains, to be rate limited.
2. Configure a rate limit identifier that specifies parameters such as maximum threshold for traffic
to be rate limited. You also associate a stream selector to the rate limiter in this step.
3. Configure an action that you want to associate with the policy that uses the rate limit identifier.
4. Configure a policy that uses the sys.check_limit expression prefix to call the rate limit identifier,
and associate the action with this policy.
5. Bind the policy globally.

Consider an example in which two traffic domains, with IDs 10 and 20, are configured on NetScaler NS1.
On traffic domain 10, LB1-TD-1 is configured to load balance servers S1 and S2; LB2-TD1 is configured
to load balance servers S3 and S4.

On traffic domain 20, LB1-TD-2 is configured to load balance servers S5 and S6; LB2-TD2 is configured
to load balance servers S7 and S8.

The following table lists some examples of rate limiting policies for traffic domains in the example
setup.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1405

NetScaler 12.0

Purpose CLI commands

Limit the number of requests to 10 per second add stream selector tdratelimit-1
for each of the traffic domains. CLIENT.TRAFFIC_DOMAIN.ID add ns
limitIdentifier limitidf-1 -threshold 10
-selectorName tdratelimit-1 -trapsInTimeSlice 0
add responder policy ratelimit-pol
“sys.check_limit(\“limitidf-1\”)” DROP bind
responder global ratelimit-pol 1
Limit the number of requests to 5 per client per add stream selector tdandclientip
second for each of the traffic domains. CLIENT.IP.SRC,CLIENT.TRAFFIC_DOMAIN.ID add
ns limitIdentifier td_limitidf -threshold 5
-selectorName tdandclientip -trapsInTimeSlice
5 add responder policy tdratelimit-pol
“sys.check_limit(\“td_limitidf\”)” DROP bind
responder global tdratelimit-pol 2
Limit the number of requests sent for a add stream selector tdratelimit
particular traffic domain (for example traffic CLIENT.TRAFFIC_DOMAIN.ID add ns
domain 10) to 30 requests every 3 seconds. limitIdentifier td10_limitidf -threshold 30
-timeSlice 3000 -selectorName tdratelimit
-trapsInTimeSlice 5 add responder policy
td10ratelimit “client.traffic_domain.id==10 &&
sys.check_limit(\“td10_limitidf\”)” DROP bind
responder global td10ratelimit 3
Limit the number of connections to 5 per client add stream selector tdandclientip
per second for a particular traffic domain (for CLIENT.IP.SRC CLIENT.TRAFFIC_DOMAIN.ID add
example traffic domain 20). ns limitIdentifier td20_limitidf -threshold 5
-mode CONNECTION -selectorName
tdandclientip -trapsInTimeSlice 5 add
responder policy td20_ratelimit
“client.traffic_domain.id==20 &&
sys.check_limit(\“td20_limitidf\”)” DROP bind
responder global td20_ratelimit 4

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1406

NetScaler 12.0

Configure rate limit at packet level

September 24, 2018

Contributed by:
C

Note: This feature was introduced in NetScaler release 11.1 build 51.21.

You can collect statistics at the packet level to determine bad/attack prone packets flowing through
all the connections identified by the selector. At any point, if the percentage of bad or attack-prone
packets exceed the configured threshold, a corrective action (RESET or DROP) is triggered as per the
configuration. This functionality can be used to address DDoS attacks involving small TCP packets in
which PUSH flag is enabled.

The following configuration demonstrates this functionality. This configuration tracks packet cred-
its for all the TCP connections flowing through the system. This creates a session and associates on
pcb/natpcb and the performs the per packet check.

Example:

1 add stream selector packetcreditrateselector client.ip.src client.tcp.

srcport client.ip.dst client.tcp.dstport
2
3 add stream identifier packetcreditrateidentifier
packetcreditrateselector ‒ interval 1
4
5 add responder policy packetcreditratesessionpolicy ”ANALYTICS.STREAM(\”
packetcreditrateidentifier\”).COLLECT_STATS(\”PACKET_CREDITS\”, <
max_threshold_percentage>, ACTION)” NOOP
6
7 <max_threshold_percentage> is any value between 0-100.

ACTION can be either DROP/RESET

After the configuration is complete, we must bind this responder policy globally.

Example:

1 bind responder global packetcreditratesessionpolicy 101 END -type

REQ_DEFAULT
2
3 bind responder global packetcreditratesessionpolicy 102 END -type
NAT_REQ_DEFAULT

1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1407

NetScaler 12.0

2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Responder

September 24, 2018

Contributed by:
C
Warning

Responder and Rewrite filters are deprecated and as an alternative, Citrix recommends you to
use filters using advanced policy infrastructure.

Today’s complex Web configurations often require different responses to HTTP requests that appear,
on the surface, to be similar. When users request a Web site’s home page, you may want to provide
a different home page depending on where each user is located, which browser the user is using, or
which language(s) the browser accepts and the order of preference. You might want to break the con-
nection immediately if the request is coming from an IP range that has been generating DDoS attacks
or initiating hacking attempts.

With the Responder feature, responses can be based on who sends the request, where it is sent from,
and other criteria with security and system management implications. The feature is simple and quick
to use. By avoiding the invocation of more complex features, it reduces CPU cycles and time spent in
handling requests that do not require complex processing.

For handling sensitive data such as financial information, if you want to ensure that the client uses a
secure connection to browse a site, you can redirect the request to secure connection by using https
:// instead of http://.

To use the Responder feature, do the following;

• Enable the Responder feature on the NetScaler.

• Configure responder actions. The action can be to generate a custom response, redirect a re-
quest to a different Web page, or reset a connection.
• Configure responder policies. The policy determines the requests (traffic) on which an action
has to be taken.
• Bind each policy to a bind point put it into effect. A bind point refers to an entity at which
NetScaler examines the traffic to see if it matches a policy. For example, a bind point can be
a load balancing virtual server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1408

NetScaler 12.0

You can specify a default action for requests that do not match any policy, and you can bypass the
safety check for actions that would otherwise generate error messages.

The Rewrite feature of NetScaler helps in rewriting some information in the requests or responses
handled by NetScaler. The following section shows some differences between the two features.

Comparison between Rewrite and Responder options

The main difference between the rewrite feature and the responder feature is as follows:

Responder cannot be used for response or server-based expressions. Responder can be used only for
the following scenarios depending on client parameters:

• Redirecting a http request to new Web sites or Web pages

• Responding with some custom response
• Dropping or resetting a connection at request level

In case of a responder policy, the NetScaler examines the request from the client, takes action accord-
ing to the applicable policies, sends the response to the client, and closes the connection with the
client.

In case of a rewrite policy, the NetScaler examines the request from the client or response from the
server, takes action according to the applicable policies, and forwards the traffic to the client or the
server.

In general, it is recommended to use responder if you want the NetScaler to reset or drop a connec-
tion based on a client or request-based parameter. Use responder to redirect traffic, or respond with
custom messages. Use rewrite for manipulating data on HTTP requests and responses.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Enabling the Responder Feature

September 24, 2018

Contributed by:
C

To use the Responder feature, you must first enable it.

To enable the responder feature by using the NetScaler command line:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1409

NetScaler 12.0

At the command prompt, type the following commands to enable the responder feature and verify
the configuration:

• enable ns feature <feature>

• show ns feature

Example:

1 enable ns feature Responder

2 Done
3 > show ns feature
4
5 Feature Acronym Status
6 ------- ------- ------
7 1) Web Logging WL ON
8 2) Surge Protection SP ON
9 .
10 .
11 .
12 1) Responder RESPONDER ON
13 2) HTML Injection HTMLInjection ON
14 3) NetScaler Push push OFF
15 Done
16 >

To enable the responder feature by using the GUI:

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

2. In the details pane, under Modes and Features, click Change advanced features.
3. In the Configure Advanced Features dialog box, select the Responder check box, and then click
OK.
4. In the Enable/Disable Feature(s)? dialog box, click YES. A message appears in the status bar,
stating that the feature has been enabled.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring a Responder Action

September 24, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1410

NetScaler 12.0

Contributed by:
C

After enabling the responder feature, you must configure one or more actions for handling requests.
The responder supports the following types of actions:

• Respond with. Sends the response defined by the Target expression without forwarding the
request to a web server. (The NetScaler appliance substitutes for and acts as a web server.) Use
this type of action to manually define a simple HTML-based response. Normally the text for a
Respond with action consists of a web server error code and brief HTML page.

• Respond with SQL OK. Sends the designated SQL OK response defined by the Target expres-
sion. Use this type of action to send an SQL OK response to an SQL query.

• Respond with SQL Error. Sends the designated SQL Error response defined by the Target ex-
pression. Use this type of action to send an SQL Error response to an SQL query.

• Respond with HTML page. Sends the designated HTML page as the response. You can choose
from a drop-down list of HTML pages that were previously uploaded, or upload a new HTML
page. Use this type of action to send an imported HTML page as the response.

• Redirect. Redirects the request to a different web page or web server. A Redirect action can
redirect requests originally sent to a “dummy” web site that exists in DNS, but for which there is
no actual web server, to an actual web site. It can also redirect search requests to an appropriate
URL. Normally, the redirection target for a Redirect action consists of a complete URL.

To configure a responder action by using the NetScaler command line:

Displays the current settings for the specified responder action. If no action name is provided, dis-
plays a list of all responder actions currently configured on the NetScaler appliance, with abbreviated
settings.

At the command prompt, type the following commands to configure a responder action and verify the
configuration:

• add responder action <name> <type> <target> [-bypassSafetyCheck (YES | NO) ]

• show responder action

Parameters:

• Name. Name of the responder action. Maximum Length: 127

• type. Type of responder action. It can be: (respondwith).

• target. An expression specifying what to respond with

• htmlpage. Option specifying to respondwith htmlpage

• bypassSafetyCheck. The safety check to allow unsafe expressions. Note: This attribute is dep-
recated.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1411

NetScaler 12.0

• hits. The number of times the action has been taken.

• referenceCount. The number of references to the action.
• undefHits. The number of times the action resulted in UNDEF.
• comment. Any type of information about this responder action.
• builtin. Flag to determine whether responder action is built-in or not
Example:

1 To create a responder action that displays a “ Not Found ” error page

for URLs that do not exist:
2
3 > add responder action act404Error respondWith ’”HTTP/1.1 404 Not Found
\r\n\r\n”+ ”HTTP.REQ.URL.HTTP_URL_SAFE” + ”does not exist on the web
server.”’
4 Done
5
6 > show responder action
7
8 1\) Name: act404Error
9 Operation: respondwith
10 Target: ”HTTP/1.1 404 Not Found
11
12 ”+ ”HTTP.REQ.URL.HTTP_URL_SAFE” + ”does not exist on the web server.”
13 BypassSafetyCheck : NO
14 Hits: 0
15 Undef Hits: 0
16 Action Reference Count: 0
17 Done
18
19 To create a responder action that displays a “ Not Found ” error page
for URLs that do not exist:
20
21 add responder action act404Error respondWith ’”HTTP/1.1 404 Not Found\r
\n\r\n”+ ”HTTP.REQ.URL.HTTP_URL_SAFE” + ”does not exist on the web
server.”’
22 Done
23 > show responder action
24
25 1\) Name: act404Error
26 Operation: respondwith
27 Target: ”HTTP/1.1 404 Not Found
28
29 ”+ ”HTTP.REQ.URL.HTTP_URL_SAFE” + ”does not exist on the web server.”
30 BypassSafetyCheck : NO

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1412

NetScaler 12.0

31 Hits: 0
32 Undef Hits: 0
33 Action Reference Count: 0
34 Done

To modify an existing responder action by using the NetScaler command line:

At the command prompt, type the following command to modify an existing responder action and
verify the configuration:

• set responder action -target [-bypassSafetyCheck ( YES | NO )]

• show responder action

Example:

1 set responder action act404Error -target ’”HTTP/1.1 404 Not Found\r\n\

r\n”+ ”HTTP.REQ.URL.HTTP_URL_SAFE” + ”does not exist on the web
server.”’
2 Done
3 > show responder action
4
5 1) Name: act404Error
6 Operation: respondwith
7 Target: ”HTTP/1.1 404 Not Found
8
9 ”+ ”HTTP.REQ.URL.HTTP_URL_SAFE” + ”does not exist on the web server.”
10 BypassSafetyCheck : NO
11 Hits: 0
12 Undef Hits: 0
13 Action Reference Count: 0
14 Done

To remove a responder action by using the NetScaler command line:

At the command prompt, type the following command to remove a responder action and verify the
configuration:

• rm responder action
• show responder action

Example:

1 rm responder action act404Error

2 Done
3
4 > show responder action
5 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1413

NetScaler 12.0

To configure a responder action by using the GUI:

1. Navigate to AppExpert > Responder > Actions.
2. In the details pane, do one of the following:
• To create a new action, click Add.
• To modify an existing action, select the action, and then click Open.
3. Click Create or OK, depending on whether you are creating a new action or modifying an existing
action.
4. Click Close. A message appears in the status bar, stating that the feature has been enabled.
5. To delete a responder action, select the action, and then click Remove. A message appears in
the status bar, stating that the feature has been disabled.
To add an expression by using the Add Expression dialog box
1. In the Create Responder Action or Configure Responder Action dialog box, click Add.
2. In the Add Expression dialog box, in the first list box choose the first term for your expression.
• HTTP. The HTTP protocol. Choose this if you want to examine some aspect of the request
that pertains to the HTTP protocol.
• SYS. The protected web site(s). Choose this if you want to examine some aspect of the
request that pertains to the recipient of the request.
• CLIENT. The computer that sent the request. Choose this if you want to examine some
aspect of the sender of the request.
• ANALYTICS. The analytics data associated with the request. Choose this if you want to
examine request metadata.
• SIP. A SIP request. Choose this if you want to examine some aspect of a SIP request.
When you make your choice, the rightmost list box lists appropriate terms for the next part of
your expression.
3. In the second list box, choose the second term for your expression. The choices depend upon
which choice you made in the previous step, and are appropriate to the context. After you
make your second choice, the Help window below the Construct Expression window (which
was blank) displays help describing the purpose and use of the term you just chose.
4. Continue choosing terms from the list boxes that appear to the right of the previous list box,
or typing strings or numbers in the text boxes that appear to prompt you to enter a value, until
your expression is finished.

Configuring the Global HTTP Action

You can configure the global HTTP action to invoke a responder action when an HTTP request times
out. To configure this feature, you must first create the responder action that you want to invoke.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1414

NetScaler 12.0

Then, you configure the global HTTP timeout action to respond to a timeout with that responder ac-
tion.

To configure the global HTTP action by using the NetScaler command line:

At the command prompt, type the following command:

• set ns httpProfile -reqTimeoutAction <responder action name>

• save ns config

For <responder action name>, substitute the name of the responder action.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring a Responder Policy

September 24, 2018

Contributed by:
C

After you configure a responder action, you must next configure a responder policy to select the re-
quests to which the NetScaler appliance should respond. A responder policy is based on a rule, which
consists of one or more expressions. The rule is associated with an action, which is performed if a
request matches the rule.

Note: For creating and managing responder policies, the GUI provides assistance that is not available
at the NetScaler command prompt.

To configure a responder policy by using the NetScaler command line:

At the command prompt, type:

• add responder policy []-appFlowaction

• show responder policy

Example:

1 > add responder policy policyThree ”CLIENT.IP.SRC.IN_SUBNET

(222.222.0.0/16)” RESET
2 Done
3 > show responder policy policyThree
4

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1415

NetScaler 12.0

5 Name: policyThree
6 Rule: CLIENT.IP.SRC.IN_SUBNET(222.222.0.0/16)
7 Responder Action: RESET
8 UndefAction: Use Global
9 Hits: 0
10 Undef Hits: 0
11 Done

To modify an existing responder policy by using the NetScaler command line:

At the command prompt, type:

• set responder policy [-rule ] [-action ] [-undefAction ]

• show responder policy

To remove a responder policy by using the NetScaler command line:

At the command prompt, type:

• rm responder policy

• show responder policy

Example:

1 >rm responder policy pol404Error

2 Done
3
4 > show responder policy
5 Done

To configure a responder policy by using the GUI:

1. Navigate to AppExpert > Responder > Policies.

2. In the details pane, do one of the following:
• To create a new policy, click Add.
• To modify an existing policy, select the policy, and then click Open.
3. Click Create or OK, depending on whether you are creating a new policy or modifying an existing
policy.
4. Click Close. A message appears in the status bar, stating that the feature has been configured.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1416

NetScaler 12.0

Binding a Responder Policy

September 26, 2018

Contributed by:
C

To put a policy into effect, you must bind it either globally, so that it applies to all traffic that flows
through the NetScaler, or to a specific virtual server, so that the policy applies only to requests whose
destination IP address is the VIP of that virtual server.

When you bind a policy, you assign a priority to it. The priority determines the order in which the
policies you define are evaluated. You can set the priority to any positive integer.

In the NetScaler operating system, policy priorities work in reverse order—the higher the number, the
lower the priority. For example, if you have three policies with priorities of 10, 100, and 1000, the
policy assigned a priority of 10 is performed first, then the policy assigned a priority of 100, and finally
the policy assigned an order of 1000. The responder feature implements only the first policy that a
request matches, not any additional policies that it might also match, so policy priority is important
for getting the results you intend.

You can leave yourself plenty of room to add other policies in any order, and still set them to evalu-
ate in the order you want, by setting priorities with intervals of 50 or 100 between each policy when
you globally bind it. You can then add additional policies at any time without having to reassign the
priority of an existing policy.

For additional information about binding policies on the NetScaler, see Policies and Expressions.

Note: Responder policies cannot be bound to TCP-based virtual servers.

To globally bind a responder policy by using the NetScaler command line:

At the command prompt, type the following command to globally bind a responder policy and verify
the configuration:

• bind responder global <policyName> <priority> [<gotoPriorityExpression

[-type <type>] [-invoke (<labelType> <labelName>)]
• show responder global

Example:

1 > bind responder global poliError 100

2 Done
3 > show responder global
4 1) Global bindpoint: REQ_DEFAULT
5 Number of bound policies: 1
6

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1417

NetScaler 12.0

7 Done

To bind responder policy to a specific virtual server by using the NetScaler command line:

At the command prompt, type:

• bind lb vserver <name> -policyname <policy_name> -priority <priority>

• sh lb vserver <name>

Example:

1 > bind lb vserver vs-loadbal -policyName policyTwo -priority 100

2 Done
3 > show lb vserver
4 1) vs-loadbal (10.102.29.20:80) - HTTP Type: ADDRESS
5 State: OUT OF SERVICE
6 Last state change was at Wed Aug 19 09:05:47 2009 (+211 ms)
7 Time since last state change: 2 days, 00:58:03.260
8 Effective State: DOWN
9 Client Idle Timeout: 180 sec
10 Down state flush: ENABLED
11 Disable Primary Vserver On Down : DISABLED
12 Port Rewrite : DISABLED
13 No. of Bound Services : 0 (Total) 0 (Active)
14 Configured Method: LEASTCONNECTION
15 Mode: IP
16 Persistence: NONE
17 Vserver IP and Port insertion: OFF
18 Push: DISABLED Push VServer:
19 Push Multi Clients: NO
20 Push Label Rule: none
21 2) vs-cont-sw (0.0.0.0:0) - TCP Type: ADDRESS
22 State: DOWN
23 Last state change was at Wed Aug 19 10:03:46 2009 (+213 ms)
24 Time since last state change: 2 days, 00:00:04.260
25 Effective State: DOWN
26 Client Idle Timeout: 9000 sec
27 Down state flush: ENABLED
28 Disable Primary Vserver On Down : DISABLED
29 No. of Bound Services : 0 (Total) 0 (Active)
30 Configured Method: LEASTCONNECTION
31 Mode: IP
32 Persistence: NONE
33 Connection Failover: DISABLED
34 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1418

NetScaler 12.0

To globally bind a responder policy by using the GUI:

1. Navigate to AppExpert > Responder > Policies.

2. On the Responder Policies page, select a responder policy, and then click Policy Manager.
3. In the Responder Policy Manager dialog box Bind Points menu, select Default Global.
4. Click Insert Policy to insert a new row and display a drop-down list of all unbound responder
policies.
5. Click one of the policies on the list. That policy is inserted into the list of globally bound respon-
der policies.
6. Click Apply Changes.
7. Click Close. A message appears in the status bar, stating that the configuration has been suc-
cessfully completed.

To bind a responder policy to a specific virtual server by using the GUI:

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.

2. On the Load Balancing Virtual Servers page, select the virtual server to which you want to bind
the responder policy, and then click Open.
3. In the Configure Virtual Server (Load Balancing) dialog box, select the Policies tab, which dis-
plays a list of all policies configured on your NetScaler appliance.
4. Select the check box next to the name of the policy you want to bind to this virtual server.
5. Click OK. A message appears in the status bar, stating that the configuration has been success-
fully completed.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Setting the default action for a responder policy

September 24, 2018

Contributed by:
C

The NetScaler appliance generates an undefined event (UNDEF event) when a request does not match
a responder policy, and then carries out the default action assigned to undefined events. By default,
that action is to forward the request to the next feature without changing it. This default behavior is
normally what you want; it ensures that requests that do not require special handling by a specific
responder action are sent to your Web servers and clients receive access to the content that they re-
quested.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1419

NetScaler 12.0

If the Web site(s) your NetScaler appliance protects receive a significant number of invalid or malicious
requests, however, you may want to change the default action to either reset the client connection or
drop the request. In this type of configuration, you would write one or more responder policies that
would match any legitimate requests, and simply redirect those requests to their original destinations.
Your NetScaler appliance would then block any other requests as specified by the default action you
configured.

You can assign any one of the following actions to an undefined event:

• NOOP

The NOOP action aborts responder processing but does not alter the packet flow. This means
that the appliance continues to process requests that do not match any responder policy, and
eventually forwards them to the requested URL unless another feature intervenes and blocks
or redirects the request. This action is appropriate for normal requests to your Web servers and
is the default setting.

• RESET

If the undefined action is set to RESET, the appliance resets the client connection, informing the
client that it must re-establish its session with the Web server. This action is appropriate for
repeat requests for Web pages that do not exist, or for connections that might be attempts to
hack or probe your protected Web site(s).

• DROP

If the undefined action is set to DROP, the appliance silently drops the request without respond-
ing to the client in any way. This action is appropriate for requests that appear to be part of a
DDoS attack or other sustained attack on your servers.

Note: UNDEF events are triggered only for client requests. No UNDEF events are triggered for re-
sponses.

To set the undefined action by using the NetScaler command line:

At the command prompt, type the following command to set the undefined action and verify the con-
figuration:

set responder param DROP NOOP)

-undefAction (RESET

• show responder param

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1420

NetScaler 12.0

1 >set responder param -undefAction RESET

2 Done
3 > show responder param
4 Action Name: RESET
5 Done
6 >

To set the undefined action by using the GUI:

1. Navigate to AppExpert > Responder, and then under Settings, click the **Change Responder
Settings **link.
2. In the Set Responder Params dialog box, under Global Undefined-Result Action, select
NOOP, RESET, or DROP.
3. Click OK. A message appears in the status bar, stating that the Responder Parameters have been
configured.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Responder action and policy examples

November 13, 2018

Contributed by:
C

Responder actions and policies are powerful and complex, but you can get started with relatively sim-
ple applications.

Example: Blocking access from specified IP addresses

The following procedures block access to your protected Web site(s) by clients originating from the
CIDR 222.222.0.0/16. The responder sends an error message stating that the client is not authorized
to access the URL requested.

To block access by using the NetScaler command line:

At the command prompt, type the following commands to block access:

• add responder action act_unauthorized respond with “HTTP/1.1 403 Forbidden\r\n\r\n” +

“Client: “ + CLIENT.IP.SRC + “ is not authorized to access URL:” + “HTTP.REQ.URL.HTTP_URL_SAFE”’

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1421

NetScaler 12.0

• add responder policy pol_un “CLIENT.IP.SRC.IN_SUBNET (222.222.0.0/16)” act_unauthorized

• bind responder global pol_un 10

To block access by using the GUI:

1. In the navigation pane, expand Responder, and then click Actions.

2. In the details pane, click Add.
3. In the Create Responder Action dialog box, do the following:
a) In the Name text box, type act_unauthorized.
b) Under Type, select Respond with.
c) In the Target text area, type the following string: “HTTP/1.1 200 OK\r\n\r\n” + “Client: “ +
CLIENT.IP.SRC + “ is not authorized to access URL:” + HTTP.REQ.URL.HTTP_URL_SAFE
d) Click Create, and then click Close.
The responder action you configured, named act_unauthorized, now appears in the Re-
sponder Actions page.
4. In the navigation pane, click Policies.
5. In the details pane, click Add.
6. In the Create Responder Policy dialog box, do the following:
a) In the Name text box, type pol_unauthorized.
b) Under Action, select act_unauthorized.
c) In the Expression window, type the following rule: CLIENT.IP.SRC.IN_SUBNET(222.222.0.0/16)
d) Click Create, then click Close.
The responder policy you configured, named pol_unauthorized, now appears in the Re-
sponder Policies page.
7. Globally bind your new policy, pol_unauthorized, as described in Binding a Responder Policy.

Example: Redirecting a client to a new URL

The following procedures redirect clients who access your protected Web site(s) from within the CIDR
222.222.0.0/16 to a specified URL.

To redirect clients by using the NetScaler command line:

At the command prompt, type the following commands to redirect clients and verify the configuration:

• add responder action act_redirect redirect ’”<http://www.example.com

/404.html>”’
• show responder action act_redirect
• add responder policy pol_redirect ”CLIENT.IP.SRC.IN_SUBNET(222.222.0.0/16)
”act_redirect
• show responder policy pol_redirect
• bind responder global pol_redirect 10

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1422

NetScaler 12.0

Example:

1 > add responder action act_redirect redirect ’” http ://www.example.com

/404.html ”’
2 Done
3
4 > add responder policy pol_redirect ”CLIENT.IP.SRC.IN_SUBNET
(222.222.0.0/16)” act_redirect
5 Done

To redirect clients by using the GUI:

1. Navigate to AppExpert > Responder > Actions.

2. In the details pane, click Add.
3. In the Create Responder Action dialog box, do the following:
a) In the Name text box, type act_redirect.
b) Under Type, select Redirect.
c) In the Target text area, type the following string: ”<http://www.example.com/404.
html>”
d) Click , then Create click Close.
The responder action you configured, named act_redirect, now appears in the Responder
Actions page.
4. In the navigation pane, click Policies.
5. In the details pane, click Add.
6. In the Create Responder Policy dialog box, do the following:
a) In the Name text box, type pol_redirect.
b) Under Action, select act_redirect.
c) In the Expression window, type the following rule: CLIENT.IP.SRC.IN_SUBNET(222.222.0.0/16)
d) Click Create, then click Close.
The responder policy you configured, named pol_redirect, now appears in the Responder
Policies page.
7. Globally bind your new policy, pol_redirect, as described in Binding a Responder Policy.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1423

NetScaler 12.0

Diameter Support for Responder

September 24, 2018

Contributed by:
C

The Responder feature now supports the Diameter protocol. You can configure Responder to respond
to Diameter requests as it does HTTP and TCP requests. For example, you could configure Responder
to respond to requests from a specific Diameter origin with a redirect to a web page enhanced for
mobile devices. A number of NetScaler expressions have been added that support examination of the
Diameter header and the attribute-value pairs (AVPs). These expressions support lookup of specific
AVPs by index, ID or name, examine the information in each AVP, and send an appropriate response.

To configure Responder to respond to a Diameter request:

At the command prompt, type the following commands:

• add responder action <actname> RESPONDWITH “DIAMETER.NEW_REDIRECT(”aaa://host.example.com”)”

For <actname>, substitute a name for your new action. The name can consist of from one to
127 characters in length, and can contain letters, numbers, and the hyphen (-) and underscore
(_) symbols. For aaa://host.example.com, substitute the URL of the diameter host to which you
want to redirect connections.

• add responder policy <polname> “diameter.req.avp(264).value.eq(”host1.example.net”)”

<actname>

For <polname>, substitute a name for your new policy. As with <actname>, the name can consist
of from one to 127 characters in length, and can contain letters, numbers, and the hyphen (-) and
underscore (_) symbols. For host1.example.net, substitute the name of the originating host of
the requests that you want to redirect. For <actname>, substitute the name of the action that
you just created.

• bind lb vserver <vservername> -policyName <polname> -priority <priority> -type REQUEST

For <vservername>, substitute the name of the load balancing virtual server to which you want
to bind the policy. For <polname>, substitute the name of the policy you just created. For
<priority>, substitute a priority for the policy.

Example:

To create a Responder action and policy to respond to Diameter requests that originate from
“host1.example.net” with a redirect to “host.example.com”, you could add the following action and
policy, and bind the policy as shown.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1424

NetScaler 12.0

1 > add responder action act_resp-dm-redirect RESPONDWITH ”DIAMETER.

NEW_REDIRECT(\”aaa://host.example.com\”)”
2 Done
3
4 > add responder pol_resp-dm-redirect ”diameter.req.avp(264).value.eq(\”
host1.example.net\”)” act_resp-dm-redirect
5 Done
6
7 > bind lb vserver vs1 -policyName pol_resp-dm-redirect -priority 10 -
type REQUEST
8 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

RADIUS Support for Responder

September 24, 2018

Contributed by:
C

The NetScaler expressions language contains expressions that can extract information from and ma-
nipulate RADIUS requests. These expressions enable you to use the Responder feature to respond
to RADIUS requests. Your responder policies and actions can use any expression that is appropriate
or relevant to a RADIUS request. The available expressions enable you to identify the RADIUS mes-
sage type, extract any attribute-value pair (AVP) from the connection, and send different responses
on the basis of that information. You can also create policy labels that invoke all responder policies
for RADIUS connections.

You can use RADIUS expressions to construct simple responses that do not require communication
with the RADIUS server to which the request was sent. When a responder policy matches a connection,
the NetScaler constructs and sends the appropriate RADIUS response without contacting the RADIUS
authentication server. For example, if the source IP address of a RADIUS request is from a subnet
that is specified in the responder policy, the NetScaler can reply to that request with an access-reject
message, or can simply drop the request.

You can also create policy labels to route specific types of RADIUS requests through a series of policies
that are appropriate to those requests.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1425

NetScaler 12.0

Note: The current RADIUS expressions do not work with RADIUS IPv6 attributes.

The NetScaler documentation for expressions that support RADIUS assumes familiarity with the basic
structure and purpose of RADIUS communications. If you need more information about RADIUS, see
your RADIUS server documentation or search online for an introduction to the RADIUS protocol.

Configuring Responder Policies for RADIUS

The following procedure uses the NetScaler command line to configure a responder action and policy,
and bind the policy to a RADIUS-specific global bind point.

To configure a Responder action and policy, and bind the policy:

At the command prompt, type the following commands:

• add responder action <actName> <actType>

• add responder policy <polName> <rule> <actName>
• bind responder policy <polName> <priority> <nextExpr> -type <bindPoint> where <bindPoint>
represents one of the RADIUS-specific global bind points.

RADIUS Expressions for Responder

In a responder configuration, you can use the following NetScaler expressions to refer to various por-
tions of a RADIUS request.

Identifying the Type of Connection:

• RADIUS.IS_CLIENT

Returns TRUE if the connection is a RADIUS client (request) message.

• RADIUS.IS_SERVER

Returns TRUE if the connection is a RADIUS server (response) message.

Request Expressions:

• RADIUS.REQ.CODE

Returns the number that corresponds to the RADIUS request type. A derivative of the num_at
class. For example, a RADIUS access request would return 1 (one). A RADIUS accounting request
would return 4.

• RADIUS.REQ.LENGTH

Returns the length of the RADIUS request, including the header. A derivative of the
num_at class.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1426

NetScaler 12.0

• RADIUS.REQ.IDENTIFIER

Returns the RADIUS request identifier, a number assigned to each request that allows the re-
quest to be matched to the corresponding response. A derivative of the
num_at class.

• RADIUS.REQ.AVP(<AVP Code No>).VALUE

Returns the value of first occurrence of this AVP as a string of type

text_t.

• RADIUS.REQ.AVP(<AVP code no>).INSTANCE(instance number)

Returns the specified instance of the AVP as a string of type RAVP_t. A specific RADIUS AVP can
occur multiple times in a RADIUS message. INSTANCE (0) returns the first instance, INSTANCE
(1) returns second instance, and so on, up to sixteen instances.

• RADIUS.REQ.AVP(<AVP code no>).VALUE(instance number)

Returns the value of specified instance of the AVP as a string of type

text_t.

• RADIUS.REQ.AVP(<AVP code no>).COUNT

Returns the number of instances of a specific AVP in a RADIUS connection, as an integer.

• RADIUS.REQ.AVP(<AVP code no>).EXISTS

Returns TRUE if the specified type of AVP exists in the message, or FALSE if it does not.

Response Expressions:

RADIUS response expressions are identical to RADIUS request expressions, except that RES replaces
REQ.

Typecasts of AVP Values:

The ADC supports expressions to typecast RADIUS AVP values to the text, integer, unsigned integer,
long, unsigned long, ipv4 address, ipv6 address, ipv6 prefix and time data types. The syntax is the
same as for other NetScaler typecast expressions.

Example:

The ADC supports expressions to typecast RADIUS AVP values to the text, integer, unsigned integer,
long, unsigned long, ipv4 address, ipv6 address, ipv6 prefix and time data types. The syntax is the
same as for other NetScaler typecast expressions.

1 RADIUS.REQ.AVP(8).VALUE(0).typecast_ip_address_at

AVP Type Expressions:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1427

NetScaler 12.0

The NetScaler supports expressions to extract RADIUS AVP values by using the assigned integer codes
described in RFC2865 and RFC2866. You can also use text aliases to accomplish the same task. Some
examples follow.

• RADIUS.REQ.AVP (1).VALUE or RADIUS.REQ.USERNAME.value

Extracts the RADIUS user-name value.

• RADIUS.REQ.AVP (4). VALUE or RADIUS.REQ. ACCT_SESSION_ID.value

Extracts the Acct-Session-ID AVP (code 44) from the message.

• RADIUS.REQ.AVP (26). VALUE or RADIUS.REQ.VENDOR_SPECIFIC.VALUE

Extracts the vendor-specific value.

The values of most commonly-used RADIUS AVPs can be extracted in the same manner.

RADIUS Bind Points:

Four global bind points are available for policies that contain RADIUS expressions.

• RADIUS_REQ_OVERRIDE

Priority/override request policy queue.

• RADIUS_REQ_DEFAULT

Standard request policy queue.

• RADIUS_RES_OVERRIDE

Priority/override response policy queue.

• RADIUS_RES_DEFAULT

Standard response policy queue.

RADIUS Responder-Specific Expressions:

• RADIUS_RESPONDWITH

Respond with the specified RADIUS response. The response is created with NetScaler expres-
sions, both RADIUS expressions and any others that are applicable.

• RADIUS.NEW_ANSWER

Sends a new RADIUS answer to the user.

• RADIUS.NEW_ACCESSREJECT

Rejects the RADIUS request.

• RADIUS.NEW_AVP

Adds the specified new AVP to the response.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1428

NetScaler 12.0

Use Cases

Following are use cases for RADIUS with responder.

Blocking RADIUS Requests from a Specific Network

To configure the responder feature to block authentication requests from a specific network, begin
by creating a responder action that rejects requests. Use the action in a policy that selects requests
from the networks that you want to block. Bind the responder policy to a RADIUS-specific global bind
point, specifying:

• The priority
• END as the nextExpr value, to ensure that policy evaluation stops when this policy is matched
• RADIUS_REQ_OVERRIDE as the queue to which you assign the policy, so that it is evaluated be-
fore policies assigned to the default queue

To configure Responder to block logons from a specific network**

• add responder action <actName> <actType>

• add responder policy <polName> <rule> <actName>
• bind responder global <polName> <priority> <nextExpr> -type <bindPoint>

Example:

1 > add responder action rspActRadiusReject respondwith radius.

new_accessreject
2 Done
3
4 > add responder policy rspPolRadiusReject client.ip.src.in_subnet
(10.224.85.0/24) rspActRadiusReject
5 Done
6
7 > bind responder global rspPolRadiusReject 1 END -type
RADIUS_REQ_OVERRIDE

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1429

NetScaler 12.0

DNS Support for the Responder Feature

September 24, 2018

Contributed by:
C

You can configure the responder feature to respond to DNS requests as it does to HTTP and TCP re-
quests. For example, you could configure it to send DNS responses over UDP and ensure that the DNS
requests from the client are sent over TCP. A number of NetScaler expressions support examination
of the DNS header in the request. These expressions examine specific header fields and send an ap-
propriate response.

• DNS Expressions. In a responder configuration, you can use the following NetScaler expres-
sions to refer to various portions of a DNS request:

Expressions Descriptions

DNS.NEW_RESPONSE Creates a new empty DNS response based on

the request.
DNS.NEW_RESPONSE <AA, TC, rcode> Creates a new DNS response based on the
specified parameters.

• DNS Bind Points. The following global bind points are available for policies that contain DNS
expressions.

Bind Points Descriptions

DNS_REQ_OVERRIDE Priority/override request policy queue.

DNS_REQ_DEFAULT Standard request policy queue.

In addition to the default bind points, you can create policy labels of type DNS and bind DNS
policies to them.

Configuring Responder Policies for DNS

The following procedure uses the NetScaler command line to configure a responder action and policy
and bind the policy to a responder-specific global bind point.

To configure Responder to respond to a DNS request:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1430

NetScaler 12.0

At the command prompt, type the following commands:

1. add responder action <actName> <actType>

For <actname>, substitute a name for your new action. The name can be 1 to 127 characters
in length, and can contain letters, numbers, hyphen (-), and underscore (_) symbols. For
<actType>, substitute a responder action type, respondWith.

2. add responder policy <polName> <rule> <actName>

For <polname>, substitute a name for your new policy. For <actname>, the name can be 1 to 127
characters in length, and can contain letters, numbers, hyphen (-), and underscore (_) symbols.
For <actname>, substitute the name of the action that you just created.

3. bind responder policy <polName> <priority> <nextExpr> -type <bindPoint>

For <bindPoint>, specify one of the responder-specific global bind points. For <polName>, sub-
stitute the name of the policy that you just created. For <priority>, specify the priority of the
policy.

Sample configuration - Enforce all DNS request over TCP:

To enforce all the DNS requests over TCP, create a responder action that will set the TC bit and rcode
as NOERROR.

1 > add responder action resp_act_set_tc_bit respondwith DNS.NEW_RESPONSE

(true, true, NOERROR)
2 Done
3
4 > add responder policy enforce_tcp dns.REQ.TRANSPORT.EQ(udp)
resp_act_set_tc_bit
5 Done
6
7 >bind lb vserver dns_udp ‒ policyName enforce_tcp -type request ‒
priority 100
8 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Troubleshooting

September 24, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1431

NetScaler 12.0

Contributed by:
C

If the responder feature does not work as expected after you have configured it, you can use some
common tools to access NetScaler resources and diagnose the problem.

Resources for Troubleshooting

For best results, use the following resources to troubleshoot an integrated cache issue on a NetScaler
appliance:

• The ns.conf file

• The relevant trace files from the client and the NetScaler appliance

In addition to the above resources, the following tools expedite troubleshooting:

• The iehttpheaders or a similar utility

• The Wireshark application customized for the NetScaler trace files

Troubleshooting Responder Issues

• Issue

The Responder feature is configured, but the responder action is not working.

Resolution

– Verify that the feature is enabled.

– Check the hit counters of any of the policies to see if the counters are getting incremented.
– Verify that the policies and actions are configured correctly.
– Verify that the actions and policies are bound appropriately.
– Record the packet traces on the client and the NetScaler appliance, and analyze the them
to get some pointer to the issue.
– Record the iehttpHeaters packet traces on the client and verify the HTTP requests and re-
sponses to get some pointer to the issue.

• Issue

You need to create a maintenance page.

Resolution

1. Configure the services and virtual Server.

2. Configure a backup virtual server with a service bound to it. This ensures that the status
of the Web site is always displayed as UP.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1432

NetScaler 12.0

3. Configure the primary virtual server to use the backup virtual server as a backup.

4. Create a responder action with an appropriate target. Following is an example for your
reference:

add responder action sorry_page respondwith q{“HTTP/1.0 200 OK” +”\r\n\r\n” +

“<html><body>Sorry, this page is not available</body></html>” + “\r\n”} .

5. Create a responder policy and bind the action to it.

6. Bind the responder policy to the backup virtual Server.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Rewrite

September 24, 2018

Contributed by:
C

May 24, 2018

Warning

Responder and Rewrite filters are deprecated and as an alternative, Citrix recommends you to
use filters using Advanced policy infrastructure.

Rewrite refers to the rewriting of some information in the requests or responses handled by the
NetScaler appliance. Rewriting can help in providing access to the requested content without
exposing unnecessary details about the Web site’s actual configuration. A few situations in which the
rewrite feature is useful are described below:

• <To improve security, the NetScaler can rewrite all the http://links to https:// in the re-
sponse body.
• <In the SSL offload deployment, the insecure links in the response have to be converted into
secure links. Using the rewrite option, you can rewrite all the http://links to https:// for
making sure that the outgoing responses from NetScaler to the client have the secured links.
• <If a Web site has to show an error page, you can show a custom error page instead of the default
404 Error page. For example, if you show the home page or site map of the Web site instead of
an error page, the visitor remains on the site instead of moving away from the Web site.
• <If you want to launch a new Web site, but use the old URL, you can use the Rewrite option.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1433

NetScaler 12.0

• <When a topic in a site has a complicated URL, you can rewrite it with a simple, easy-to-
remember URL (also referred to as ‘cool URL’).
• <You can append the default page name to the URL of a Web site. For example, if the default
page of a company’s Web site is http://www.abc.com/index.php, when the user types
‘abc.com’ in the address bar of the browser, you can rewrite the URL to ‘abc.com/index.php’.

When you enable the rewrite feature, NetScaler can modify the headers and body of HTTP requests
and responses.

To rewrite HTTP requests and responses, you can use protocol-aware NetScaler policy expressions in
the rewrite policies you configure. The virtual servers that manage the HTTP requests and responses
must be of type
HTTP or
SSL. In HTTP traffic, you can take the following actions:

• <Modify the URL of a request

• <Add, modify or delete headers
• <Add, replace, or delete any specific string within the body or headers.

To rewrite TCP payloads, consider the payload as a raw stream of bytes. Each of the virtual servers
that managing the TCP connections must be of type TCP or SSL_TCP. The term TCP rewrite is used to
refer to the rewrite of TCP payloads that are not HTTP data. In TCP traffic, you can add, modify, or
delete any part of the TCP payload.

For examples to use the rewrite feature, see Rewrite Action and Policy Examples.

Comparison between Rewrite and Responder options

The main difference between the rewrite feature and the responder feature is as follows:

Responder cannot be used for response or server-based expressions. Responder can be used only for
the following scenarios depending on client parameters:

• Redirecting a http request to new Web sites or Web pages

• Responding with some custom response
• Dropping or resetting a connection at request level

In case of a responder policy, the NetScaler examines the request from the client, takes action accord-
ing to the applicable policies, sends the response to the client, and closes the connection with the
client.

In case of a rewrite policy, the NetScaler examines the request from the client or response from the
server, takes action according to the applicable policies, and forwards the traffic to the client or the
server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1434

NetScaler 12.0

In general, it is recommended to use responder if you want the NetScaler to reset or drop a connec-
tion based on a client or request-based parameter. Use responder to redirect traffic, or respond with
custom messages. Use rewrite for manipulating data on HTTP requests and responses.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

How rewrite works

March 6, 2019

Contributed by:
C

A rewrite policy consists of a rule and action. The rule determines the traffic on which rewrite is applied
and the action determines the action to be taken by the NetScaler. You can define multiple rewrite
policies. For each policy, specify the bind point and priority.

A bind point refers to a point in the traffic flow at which the NetScaler examines the traffic to verify
whether any rewrite policy can be applied to it. You can bind a policy to a specific load balancing or
content switching virtual server, or make the policy global if you want the policy to be applied to the
entire traffic handled by the NetScaler. These policies are referred to as global policies.

In addition to the user-defined policies, the NetScaler has some default policies. You cannot modify
or delete a default policy.

For evaluating the policies, NetScaler follows the order mentioned below:

• Global policies
• Policies bound to specific virtual servers
• Default policies

Note: NetScaler can apply a rewrite policy only when it is bound to a point.

NetScaler implements the rewrite feature in the following steps:

• The NetScaler appliance checks for global policies and then checks for policies at individual
bind points.

• If multiple policies are bound to a bind point, the NetScaler evaluates the policies in the order of
their priority. The policy with the highest priority is evaluated first. After evaluating each policy,
if the policy is evaluated to TRUE (the traffic matches the rule), it adds the action associated with

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1435

NetScaler 12.0

the policy to a list of actions to be performed. A match occurs when the characteristics specified
in the policy rule match the characteristics of the request or response being evaluated.

• For any policy, in addition to the action, you can specify the policy that should be evaluated
after the current policy is evaluated. This policy is referred to as the ‘Go to Expression’. For any
policy, if a Go to Expression (gotoPriorityExpr) is specified, the NetScaler evaluates the Go to
Expression policy; it ignores policy with the next highest priority.

You can specify the priority of the policy to indicate the Go to Expression policy; you cannot
use the name of the policy. If you want the NetScaler to stop evaluating other policies after
evaluating a particular policy, you can set the Go to Expression to ‘END’.

• After all the policies are evaluated or when a policy has the Go to Expression set as END, the
NetScaler starts performing the actions according to the list of actions.

For more information about configuring rewrite policies, see “Configuring a Rewrite Policy” and about
binding rewrite policies, see “Binding a Rewrite Policy.”

The following figure illustrates how NetScaler processes a request or response when the rewrite fea-
ture is used.

Figure 1. The Rewrite Process

Policy Evaluation

The policy with the highest priority is evaluated first. NetScaler does not stop the evaluation of rewrite
policies when it finds a match; it evaluates all the rewrite policies configured on the NetScaler.

• If a policy evaluates to TRUE, the NetScaler follows the procedure below:

– If the policy has the Go to Expression set to END, the NetScaler stops evaluating all the
other policies and starts performing the rewrite.
– The gotoPriorityExpression can be set to ‘NEXT’, ‘END’, some integer or ‘INVOCATION_LIST’.
The value determines the policy with the next priority. The following table shows the ac-
tion taken by NetScaler for each value of the expression.
| Value of the expression | Action |
|—|–|
| NEXT | Policy with the next priority gets evaluated. | | END | Evaluation of policies stops.||
| <an integer>| Policy with specified priority gets evaluated.|
| INVOCATION_LIST | Goto NEXT or END is applied based on the result of the invocation list.
|
• If a policy evaluates to FALSE, the NetScaler continues the evaluation in the order of priority.
• If a policy evaluates to UNDEFINED (cannot be evaluated on the received traffic due to an error),
the NetScaler performs the action assigned to the UNDEFINED condition (referred to as unde-
fAction) and stops further evaluation of polices.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1436

NetScaler 12.0

The NetScaler starts the actual rewriting only after the evaluation is complete. It refers to the list of
actions identified by policies that are evaluated to TRUE, and starts the rewriting. After implementing
all the actions in the list, the NetScaler forwards the traffic as required.

Note:

Ensure that the policies do not specify conflicting or overlapping actions on the same part of the
HTTP header or body, or TCP payload. When such a conflict occurs, the NetScaler encounters an
undefined situation and aborts the rewrite.

Rewrite Actions

On the NetScaler appliance, specify the actions to be taken such as adding, replacing, or deleting
text within the body, or adding, modifying or deleting headers, or any changes in the TCP payload as
rewrite actions. For more information about rewrite actions, see Configuring a Rewrite Action.

The following table describes the steps the NetScaler can take when a policy evaluates to TRUE.

| Action | Result |
|—-|—|
| Insert | The rewrite action specified for the policy is carried out. |
| NOREWRITE | The request or response is not rewritten. NetScaler forwards the traffic without rewrit-
ing any part of the message. |
| RESET | The connection is aborted at the TCP level. |
| DROP | The message is dropped.|
Note: For any policy, you can configure the undefaction (action to be taken when the policy evaluates
to UNDEFINED) as NOREWRITE, RESET, or DROP.

To use the
Rewrite feature, take the following steps:

• Enable the feature on the NetScaler.

• Define rewrite actions.
• Define rewrite policies.
• Bind the policies to a bind point to bring a policy into effect.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1437

NetScaler 12.0

Enabling the rewrite feature

September 24, 2018

Contributed by:
C

Enable the rewrite feature on the NetScaler appliance if you want to rewrite the HTTP or TCP requests
or responses. If the feature is enabled, NetScaler takes rewrite action according to the specified poli-
cies. For more information, see
How rewrite works.

To enable the rewrite feature by using the command line interface

At the command prompt, type the following commands to enable the rewrite feature and verify the
configuration:

• enable ns feature REWRITE

• show ns feature

Example:

1 > enable ns feature REWRITE

2 Done
3 > show ns feature
4
5 Feature Acronym Status
6 ------- ------- ------
7 1) Web Logging WL OFF
8 2) Surge Protection SP ON
9 .
10 .
11 .
12 1) Rewrite REWRITE ON
13 .
14 .
15 1) NetScaler Push push OFF
16 Done

To enable the rewrite feature by using the GUI

1. <In the navigation pane, click System, and then click Settings.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1438

NetScaler 12.0

2. <In the details pane, under Modes and Features, click Configure basic features.
3. <In the Configure Basic Features dialog box, select the Rewrite check box, and then click OK.
4. <In the Enable/Disable Feature(s) dialog box, click Yes. A message appears in the status bar,
stating that the selected feature was enabled.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring a Rewrite Action

January 6, 2019

Contributed by:
C
Warning

The Pattern function in a rewrite action is deprecated from NetScaler 12.0 build 56.20 onwards
and as an alternative, Citrix recommends you to use the Search rewrite action parameter.

After enabling the rewrite feature, you need to configure one or more actions unless a built-in rewrite
action is sufficient. All of the built-in actions have names beginning with the string ns_cvpn, followed
by a string of letters and underscore characters. Built-in actions perform useful and complex tasks
such as decoding parts of a clientless VPN request or response or modifying JavaScript or XML data.
The built-in actions can be viewed, enabled, and disabled, but cannot be modified or deleted.

Target expressions in actions for TCP rewrite must begin with one of the following expression prefixes:

• <CLIENT.TCP.PAYLOAD. For rewriting TCP payloads in client requests. For example,

CLIENT.TCP.PAYLOAD(10000).AFTER_STR(“string1”).
• <SERVER.TCP.PAYLOAD. For rewriting TCP payloads in server responses. For example,
SERVER.TCP.PAYLOAD(1000).B64DECODE.BETWEEN(“string1”,”string2”).

You can use all types of existing string manipulation functions with these prefixes to identify the strings
that you want to rewrite. To configure a rewrite action, you assign it a name, specify an action type,
and add one or more arguments specifying additional data. The following table describes the action
types and the arguments you use with them.

Note: Action types that can be used only for HTTP rewrite are identified in the
Rewrite Action Type column.

See the Rewrite Action Types and their Arguments table.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1439

NetScaler 12.0

To create a new rewrite action by using the command line interface

At the command prompt, type the following commands to create a new rewrite action and verify the
configuration:

• add rewrite action <name> <type> <target> [<stringBuilderExpr>] [(-

pattern <expression> | -patset <string>)] [-bypassSafetyCheck (YES|NO)]
• show rewrite action <name>

Example 1. Inserting an HTTP Header With the Client IP:

1 > add rewrite action insertact INSERT_HTTP_HEADER ”client-IP” CLIENT.IP

.SRC
2 Done
3
4 > show rewrite action insertact
5
6 Name: insertact
7 Operation: insert_http_header Target:Client-IP
8 Value:CLIENT.IP.SRC
9 BypassSafetyCheck : NO
10 Hits: 0
11 Undef Hits: 0
12 Action Reference Count: 0
13 Done

Example 2. Replacing Strings in a TCP Payload (TCP Rewrite):

1 > add rewrite action client_tcp_payload_replace_all REPLACE_ALL

2 ’client.tcp.payload(1000)’ ’”new-string”’ -search text(”old-string”)
3 Done
4 > show rewrite action client_tcp_payload_replace_all
5
6 Name: client_tcp_payload_replace_all
7 Operation: replace_all
8 Target:client.tcp.payload(1000)
9 Value:”new-string”
10 Search: text(”old-string”)
11 BypassSafetyCheck : NO
12 Hits: 0
13 Undef Hits: 0
14 Action Reference Count: 0
15 Done
16 >

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1440

NetScaler 12.0

To modify an existing rewrite action by using the command line interface

At the command prompt, type the following commands to modify an existing rewrite action and verify
the configuration:

<set rewrite action <name> -patset <string>)] NO)]

[-target <string>] [-bypassSafetyCheck (YES
[-stringBuilderExpr <string>]
[(-pattern <expression>

•
• <show rewrite action <name>
Example:

1 > set rewrite action insertact -target ”Client-IP”

2 Done
3 > show rewrite action insertact
4
5 Name: insertact
6 Operation: insert_http_header Target:Client-IP
7 Value:CLIENT.IP.SRC
8 BypassSafetyCheck : NO
9 Hits: 0
10 Undef Hits: 0
11 Action Reference Count: 0
12 Done

To remove a rewrite action by using the command line interface

At the command prompt, type the following commands to remove a rewrite action :
rm rewrite action <name>
Example:

1 > rm rewrite action insertact

2 Done

To configure a rewrite action by using the GUI

1. Navigate to AppExpert > Rewrite > Actions.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1441

NetScaler 12.0

2. In the details pane, do one of the following:

• To create a new action, click Add.
• To modify an existing action, select the action, and then click Open.
3. Click Create or OK. A message appears in the status bar, stating that the Action has been config-
ured successfully.
4. Repeat steps 2 through 4 to create or modify as many rewrite actions as you wish.
5. Click Close.

To add an expression by using the Add Expression dialog box

1. In the Create Rewrite Action or Configure Rewrite Action dialog box, under the text area for the
type argument you want to enter, click Add.

2. In the Add Expression dialog box, in the first list box choose the first term for your expression.

• HTTP

The HTTP protocol. Choose this if you want to examine some aspect of the request that
pertains to the HTTP protocol.

• SYS

The protected Web site(s). Choose this if you want to examine some aspect of the request
that pertains to the recipient of the request.

• CLIENT

The computer that sent the request. Choose this if you want to examine some aspect of
the sender of the request.

When you make your choice, the rightmost list box lists appropriate terms for the next part of
your expression.

3. In the second list box, choose the second term for your expression. The choices depend upon
which choice you made in the previous step, and are appropriate to the context. After you
make your second choice, the Help window below the Construct Expression window (which
was blank) displays help describing the purpose and use of the term you just chose.

4. Continue choosing terms from the list boxes that appear to the right of the previous list box,
or typing strings or numbers in the text boxes that appear to prompt you to enter a value, until
your expression is finished.
For more information about the PI expressions language and creating expressions for responder
policies, see “Policies and Expressions.”

If you want to test the effect of a rewrite action when used on sample HTTP data, you can use
the Rewrite Expression Evaluator.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1442

NetScaler 12.0

Note: The Rewrite Expression Evaluator is only available in the GUI. There is no NetScaler com-
mand line version.

To evaluate a rewrite action by using the Rewrite Action Evaluator dialog box

1. In the Rewrite Actions details pane, select the rewrite action that you want to evaluate, and then
click Evaluate.
2. In the Rewrite Expression Evaluator dialog box, specify values for the following parameters. (An
asterisk indicates a required parameter.)
• Rewrite Action*—If the rewrite action you want to evaluate is not already selected, select
it from the drop-down list. After you select a Rewrite action, the Details section displays
the details of the selected Rewrite action.
• New*—Select New to open the Create Rewrite Action dialog box and create a new rewrite
action.
• Modify*—Select Modify to open the Configure Rewrite Action dialog box and modify the
selected rewrite action.
• Flow Type*—Specifies whether to test the selected rewrite action with HTTP Request data
or HTTP Response data. The default is Request. If you want to test with Response data,
select Response.
• HTTP Request/Response Data*—Provides a space for you to provide the HTTP data that
the Rewrite Action Evaluator will use for testing. You can paste the data directly into the
window, or click Sample to insert some sample HTTP headers.
• Show end-of-line—Specifies whether to show UNIX-style end-of-line characters (\n) at the
end of each line of sample HTTP data.
• Sample—Inserts sample HTTP data into the HTTP Request/Response Data window. You
can choose either GET or POST data.
• Browse—Opens a local browse window so that you can choose a file containing sample
HTTP data from a local or network location.
• Clear—Clears the current sample HTTP data from the HTTP Request/Response Data win-
dow.
3. Click Evaluate. The Rewrite Action Evaluator evaluates the effect of the Rewrite action on the
sample data that you chose, and displays the results as modified by the selected Rewrite action
in the Results window. Additions and deletions are highlighted as indicated in the legend in the
lower left-hand corner of the dialog box.
4. Continue evaluating Rewrite actions until you have determined that all of your actions have the
effect that you wanted.
• You can modify the selected rewrite action and test the modified version by clicking Modify
to open the Configure Rewrite Action dialog box, making and saving your changes, and

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1443

NetScaler 12.0

then clicking Evaluate again.

• You can evaluate a different rewrite action using the same request or response data by
selecting it from the Rewrite Action drop-down list, and then clicking Evaluate again.

5. Click Close to close the Rewrite Expression Evaluator and return to the Rewrite Actions pane.

To delete a rewrite action, select the rewrite action you want to delete, then click Remove and,
when prompted, confirm your choice by clicking OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring a Rewrite Policy

September 24, 2018

Contributed by:
C

After you create any needed rewrite action(s), you must create at least one rewrite policy to select the
requests that you want the NetScaler appliance to rewrite.

A rewrite policy consists of a rule, which itself consists of one or more expressions, and an associated
action that is performed if a request or response matches the rule. Policy rules for evaluating HTTP
requests and responses can be based on almost any part of a request or response.

Even though you cannot use TCP rewrite actions to rewrite data other than the TCP payload, you can
base the policy rules for TCP rewrite policies on the information in the transport layer and the layers
below the transport layer.

If a configured rule matches a request or response, the corresponding policy is triggered and the ac-
tion associated with it is carried out.

Note: You can use either the command line interface or the GUI to create and configure rewrite poli-
cies. Users who are not thoroughly familiar with the command line interface and the NetScaler Policy
expression language will usually find using the GUI much easier.

To add a new rewrite policy by using the command line interface

At the command prompt, type the following commands to add a new rewrite policy and verify the
configuration:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1444

NetScaler 12.0

• <add rewrite policy <name> <expression> <action> [<undefaction>]

• <show rewrite policy <name>

Example 1. Rewriting HTTP Content:

1 > add rewrite policy policyNew ”HTTP.RES.IS_VALID” insertact NOREWRITE

2 Done
3 > show rewrite policy policyNew
4 Name: policyNew
5 Rule: HTTP.RES.IS_VALID
6 RewriteAction: insertact
7 UndefAction: NOREWRITE
8 Hits: 0
9 Undef Hits: 0
10
11 Done

Example 2. Rewriting a TCP Payload (TCP Rewrite):

1 > add rewrite policy client_tcp_payload_policy CLIENT.IP.SRC.EQ

(172.168.12.232) client_tcp_payload_replace_all
2 Done
3 > show rewrite policy client_tcp_payload_policy
4 Name: client_tcp_payload_policy
5 Rule: CLIENT.IP.SRC.EQ(172.168.12.232)
6 RewriteAction: client_tcp_payload_replace_all
7 UndefAction: Use Global
8 LogAction: Use Global
9 Hits: 0
10 Undef Hits: 0
11
12 Done
13 >

To modify an existing rewrite policy by using the command line interface

At the command prompt, type the following commands to modify an existing rewrite policy and verify
the configuration:

• <set rewrite policy <name> -rule <expression> -action <action> [<undefaction>]

• <show rewrite policy <name>

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1445

NetScaler 12.0

1 > set rewrite policy policyNew -rule ”HTTP.RES.IS_VALID” -action

insertaction
2 Done
3
4 > show rewrite policy policyNew
5 Name: policyNew
6 Rule: HTTP.RES.IS_VALID
7 RewriteAction: insertaction
8 UndefAction: NOREWRITE
9 Hits: 0
10 Undef Hits: 0
11
12 Done

To remove a rewrite policy by using the command line interface

At the command prompt, type the following command to remove a rewrite policy:

rm rewrite policy <name>

Example:

1 > rm rewrite policy policyNew

2 Done

To configure a rewrite policy by using the GUI

1. <Navigate to AppExpert > Rewrite > Policies.

2. <In the details pane, do one of the following:
• <To create a new policy, click Add.
• <To modify an existing policy, select the policy, and then click Open.
3. <Click Create or OK. A message appears in the status bar, stating that the Policy has been con-
figured successfully.
4. <Repeat steps 2 through 4 to create or modify as many rewrite actions as you wish.
5. <Click Close. To delete a rewrite policy, select the rewrite policy you want to delete, then click
Remove and, when prompted, confirm your choice by clicking OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1446

NetScaler 12.0

Binding a Rewrite Policy

September 24, 2018

Contributed by:
C

After creating a rewrite policy, you must bind it to put it into effect. You can bind your policy to Global
if you want to apply it to all traffic that passes through your NetScaler, or you can bind your policy to
a specific virtual server or bind point to direct only that virtual server or bind point’s incoming traffic
to that policy. If an incoming request matches a rewrite policy, the action associated with that policy
is carried out.

Rewrite policies for evaluating HTTP requests and responses can be bound to virtual servers of type
HTTP or SSL, or they can be bound to the
REQ_OVERRIDE,
REQ_DEFAULT,
RES_OVERRIDE, and
RES_DEFAULT bind points. Rewrite policies for TCP rewrite can be bound only to virtual servers of
type
TCP or
SSL_TCP, or to the
OTHERTCP_REQ_OVERRIDE,
OTHERTCP_REQ_DEFAULT,
OTHERTCP_RES_OVERRIDE, and
OTHERTCP_RES_DEFAULT bind points.

Note: The term

OTHERTCP is used in the context of the NetScaler appliance to refer to all
TCP or
SSL_TCP requests and responses that you want to treat as a raw stream of bytes regardless of the
protocols that the TCP packets encapsulate.

When you bind a policy, you assign it a priority. The priority determines the order in which the policies
you define are evaluated. You can set the priority to any positive integer.

In the NetScaler operating system, policy priorities work in reverse order - the higher the number, the
lower the priority. For example, if you have three policies with priorities of 10, 100, and 1000, the policy
assigned a priority of 10 is applied first, then the policy assigned a priority of 100, and finally the policy
assigned an order of 1000.

Unlike most other features in the NetScaler operating system, the rewrite feature continues to evalu-
ate and implement policies after a request matches a policy. However, the effect of a particular action

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1447

NetScaler 12.0

policy on a request or response will often be different depending on whether it is performed before
or after another action. Priority is important to get the results you intended.

You can leave yourself plenty of room to add other policies in any order, and still set them to evaluate in
the order you want, by setting priorities with intervals of 50 or 100 between each policy when you bind
it. If you do this, you can add additional policies at any time without having to reassign the priority of
an existing policy.

When binding a rewrite policy, you also have the option of assigning a goto expression (gotoPriori-
tyExpression) to the policy. A goto expression can be any positive integer that matches the priority
assigned to a different policy that has a higher priority than the policy that contains the goto expres-
sion. If you assign a goto expression to a policy, and a request or response matches the policy, the
NetScaler will immediately go to the policy whose priority matches the goto expression. It will skip
over any policies with priority numbers that are lower than that of the current policy, but higher than
the priority number of the goto expression, and not evaluate those policies.

To globally bind a rewrite policy by using the command line interface

At the command prompt, type the following commands to globally bind a rewrite policy and verify the
configuration:

• bind rewrite global <policyName> <priority> [<gotoPriorityExpression>] [-type <type>] [-invoke

(<labelType> <labelName>) ]
• show rewrite global

Example:

1 >bind rewrite global policyNew 10

2 Done
3
4 > show rewrite global
5 1) Global bindpoint: RES_DEFAULT
6 Number of bound policies: 1
7
8 2) Global bindpoint: REQ_OVERRIDE
9 Number of bound policies: 1
10
11 Done

To bind rewrite policy to a specific virtual server by using the command line interface

At the command prompt, type the following commands to bind rewrite policy to a specific virtual
server and verify the configuration:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1448

NetScaler 12.0

bind lb vserver <serviceGroupName>@ (-policyName RESPONSE )] [-invoke

<name>@ <string>@ [-priority (<labelType>
(<serviceName>@ <positive_integer>] [- <labelName>) ] )
[-weight gotoPriorityExpression
<positive_integer>]) <expression>] [-type (
REQUEST

• show lb vserver <name>

Example:

1 > bind lb vserver lbvip -policyName ns_cmp_msapp -priority 50

2 Done
3 >
4 > show lb vserver lbvip
5 lbvip (8.7.6.6:80) - HTTP Type: ADDRESS
6 State: DOWN
7 Last state change was at Wed Jul 15 05:54:24 2009 (+226 ms)
8 Time since last state change: 28 days, 01:57:26.350
9 Effective State: DOWN
10 Client Idle Timeout: 180 sec
11 Down state flush: ENABLED
12 Disable Primary Vserver On Down : DISABLED
13 Port Rewrite : DISABLED
14 No. of Bound Services : 0 (Total) 0 (Active)
15 Configured Method: LEASTCONNECTION
16 Mode: IP
17 Persistence: NONE
18 Vserver IP and Port insertion: OFF
19 Push: DISABLED Push VServer:
20 Push Multi Clients: NO
21 Push Label Rule: none
22
23 1) Policy : ns_cmp_msapp Priority:50
24 2) Policy : cf-pol Priority:1 Inherited
25 Done

To bind a rewrite policy to a bind point by using the GUI

1. Navigate to AppExpert > Rewrite > Policies.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1449

NetScaler 12.0

2. In the details pane, select the rewrite policy you want to globally bind, and then click Policy
Manager.
3. In the Rewrite Policy Manager dialog box, in the Bind Points menu, do one of the following:
a) If you want to configure bindings for HTTP rewrite policies, click HTTP, and then click either
Request or Response, depending on whether you want to configure request-based rewrite
policies or response-based rewrite policies.
b) If you want to configure bindings for TCP rewrite policies, click TCP, and then click either
Client or Server, depending on whether you want to configure client-side TCP rewrite poli-
cies or server-side TCP rewrite policies.
4. Click the bind point to which you want to bind the rewrite policy. The Rewrite Policy Manager
dialog box displays all the rewrite policies that are bound to the selected bind point.
5. Click Insert Policy to insert a new row and display a drop-down list with all available, unbound
rewrite policies.
6. Click the policy you want to bind to the bind point. The policy is inserted into the list of rewrite
policies bound to the bind point.
7. In the Priority column, you can change the priority to any positive integer. For more information
about this parameter, see priority in “Parameters for binding a rewrite policy.”
8. If you want to skip over policies and go directly to a specific policy in the event that the current
policy is matched, change the value in the Goto Expression column to equal the priority of the
next policy to be applied.. For more information about this parameter, see gotoPriorityExpres-
sion in “Parameters for binding a rewrite policy.”
9. To modify a policy, click the policy, and then click Modify Policy.
10. To unbind a policy, click the policy, and then click Unbind Policy.
11. To modify an action, in the Action column, click the action you want to modify, and then click
Modify Action.
12. To modify an invoke label, in the Invoke column, click the invoke label you want to modify, and
then click Modify Invoke Label.
13. To regenerate the priorities of all the policies that are bound to the bind point you are currently
configuring, click Regenerate Priorities. The policies retain their existing priorities relative to
the other policies, but the priorities are renumbered in multiples of ten.
14. Click Apply Changes.
15. Click Close. A message appears in the status bar, stating that the Policy has been configured
successfully.

To bind a rewrite policy to a specific virtual server by using the GUI

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.

2. In the details pane list of virtual servers, select the virtual server to which you want to bind the
rewrite policy, and then click Open.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1450

NetScaler 12.0

3. In the Configure Virtual Server (Load Balancing) dialog box, select the Policies tab. All policies
configured on your NetScaler appear on the list.
4. Select the check box next to the name of the policy you want to bind to this virtual server.
5. Click OK. A message appears in the status bar, stating that the Policy has been configured suc-
cessfully.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring Rewrite Policy Labels

September 24, 2018

Contributed by:
C

If you want to build a more complex policy structure than is supported by single policies, you can
create policy labels and then bind them as you would policies. A policy label is a user-defined point
to which policies are bound. When a policy label is invoked, all the policies bound to it are evaluated
in the order of the priority you configured. A policy label can include one or multiple policies, each of
which can be assigned its own result. A match on one policy in the policy label can result in proceeding
to the next policy, invoking a different policy label or appropriate resource, or an immediate end to
policy evaluation and the return of control to the policy that invoked the policy label.

A rewrite policy label consists of a name, a transform name that describes the type of policy included
in the policy label, and a list of policies bound to the policy label. Each policy that is bound to the
policy label contains all of the elements described in Configuring a Rewrite Policy.

Note: You can use either the command line interface or the GUI to create and configure rewrite policy
labels. Users who are not thoroughly familiar with the command line interface and the NetScaler
Policy Infrastructure (PI) language will usually find using the GUI much easier.

To configure a rewrite policy label by using the command line interface

To add a new rewrite policy label, at the command prompt, type the following command:

add rewrite policylabel <labelName> <transform>

For example, to add a rewrite policy label named polLabelHTTPResponses to group all policies that
work on HTTP responses, you would type the following:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1451

NetScaler 12.0

add rewrite policylabel polLabelHTTPResponses http_res

To modify an existing rewrite policy label, at the NetScaler command prompt, type the following com-
mand:

set rewrite policy <name> <transform>

Note: The set rewrite policy command takes the same options as the add rewrite policy command.

To remove a rewrite policy label, at the NetScaler command prompt, type the following command:

rm rewrite policy<name>

For example, to remove a rewrite policy label named polLabelHTTPResponses, you would type the
following:

rm rewrite policy polLabelHTTPResponses

To configure a rewrite policy label by using the GUI

1. Navigate to AppExpert > Rewrite > Policy Labels.

2. In the details pane, do one of the following:

• To create a new policy label, click Add.

• To modify an existing policy label, select the policy, and then click Open.

3. Add or remove policies from the list that is bound to the policy label.

• To add a policy to the list, click Insert Policy, and choose a policy from the drop-down list.
You can create a new policy and add it to the list by choosing New Policy in the list, and
following the instructions in “Configuring a Rewrite Policy.”
• To remove a policy from the list, select that policy, and then click Unbind Policy.

4. Modify the priority of each policy by editing the number in the Priority column.

You can also automatically renumber policies by clicking Regenerate Priorities.

5. Click Create or OK, and then click Close.

To remove a policy label, select it, and then click Remove. To rename a policy label, select it and
then click Rename. Edit the name of the policy, and then click OK to save your changes.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1452

NetScaler 12.0

Configuring the Default Rewrite Action

September 24, 2018

Contributed by:
C

An undefined event is triggered when the NetScaler cannot evaluate a policy, usually because it de-
tects a logical or other error in the policy or an error condition on the NetScaler. When the rewrite
policy evaluation results in an error, the specified undefined action is carried out. Undefined actions
configured at the rewrite policy level are carried out before a globally configured undefined action.

The NetScaler supports following three types of undefined actions:

• undefAction NOREWRITE

Aborts rewrite processing, but does not alter the packet flow. This means that the NetScaler con-
tinues to process requests and responses that do not match any rewrite policy, and eventually
forwards them to the requested URL unless another feature intervenes and blocks or redirects
the request. This action is appropriate for normal requests to your Web servers, and is the de-
fault setting.

• undefAction RESET

Resets the client connection. This means that the NetScaler tells the client that it must re-
establish its session with the Web server. This action is appropriate for repeat requests for Web
pages that do not exist, or for connections that might be attempts to hack or probe your pro-
tected Web site(s).

• undefAction DROP

Silently drops the request without responding to the client in any way. This means that the
NetScaler simply discards the connection without responding to the client. This action is ap-
propriate for requests that appear to be part of a DDoS attack or another sustained attack on
your servers.

Note: Undefined events can be triggered for both request and response flow specific policies.

To configure the default action by using the command line interface

At the command prompt, type the following commands to configure the default action and verify the
configuration:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1453

NetScaler 12.0

<set rewrite param RESET DROP )

-undefAction ( NOREWRITE

• <show rewrite param

Example:

1 > set rewrite param -undefAction NOREWRITE

2 Done
3 > show rewrite param
4 Action Name: NOREWRITE
5 Done

To configure the default action by using the GUI

1. Navigate to AppExpert > Rewrite.

2. In the details pane, under Rewrite Overview, click the Change Rewrite Settings link. The Set
Rewrite Params dialog box appears.
3. Under Global Undefined-Result Action, select an option as follows:
• NoRewrite—NOREWRITE
• Reset—RESET
• Drop—DROP
4. Click OK. The global undefined action is set to the value you chose.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Bypassing the Safety Check

September 24, 2018

Contributed by:
C

When you create a rewrite action, the NetScaler verifies that the expression you used to create the ac-
tion is safe. Expressions created by the NetScaler from run-time data, such as URLs contained in HTTP

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1454

NetScaler 12.0

requests, can cause unexpected errors. The NetScaler reports expressions that cause such errors as
unsafe expressions.

In some cases, the expressions may be safe. For example, the NetScaler cannot validate an expression
that contains a URL that does not resolve, even if the URL does not resolve because the Web server is
temporarily unavailable. You can manually bypass the Safety Check to allow these expressions.

To bypass the safety check by using the command line interface

At the command prompt, type the following commands to bypass the safety check and verify the con-
figuration:

• <set rewrite action <name> -bypassSafetyCheck YES

• <show rewrite action <name>

Example:

1 > set rewrite action insertact -bypassSafetyCheck YES

2 Done
3 > show rewrite action insertact
4
5 Name: insertact
6 Operation: insert_http_header Target:Client-IP
7 Value:CLIENT.IP.SRC
8 BypassSafetyCheck : YES
9 Hits: 0
10 Undef Hits: 0
11 Action Reference Count: 2
12 Done

To bypass safety check by using the GUI

1. Navigate to AppExpert > Rewrite > Actions.

2. In the details pane, select the rewrite action to be exempted from the safety check, and then
click Open.
3. In the Configure Rewrite Action dialog box, select the Bypass Safety Check check box.
4. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1455

NetScaler 12.0

Rewrite Action and Policy Examples

September 24, 2018

Contributed by:
C

The examples in this section demonstrate how to configure rewrite to perform various useful tasks.
The examples occur in the server room of Example Manufacturing Inc., a mid-sized manufacturing
company that uses its Web site to manage a considerable portion of its sales, deliveries, and customer
support.

Example Manufacturing has two domains: example.com for its Web site and email to customers, and
example.net for its intranet. Customers use the Example Web site to place orders, request quotes,
research products, and contact customer service and technical support.

As an important part of Example’s revenue stream, the Web site must respond quickly and keep cus-
tomer data confidential. Example therefore has several Web servers and uses NetScaler appliances to
balance the Web site load and manage traffic to and from its Web servers.

The Example system administrators use the rewrite features to perform the following tasks:

Example 1: Delete old X-Forwarded-For and Client-IP Headers

Example Inc. removes old X-Forwarded-For and Client-IP HTTP headers from incoming requests.

Example 2: Adding a Local Client-IP Header

Example Inc. adds a new, local Client-IP header to incoming requests.

Example 3: Tagging Secure and Insecure Connections

Example Inc. tags incoming requests with a header that indicates whether the connection is a secure
connection.

Example 4: Mask the HTTP Server Type

Example Inc. modifies the HTTP Server: header so that unauthorized users and malicious code cannot
use that header to determine the HTTP server software it uses.

Example 5: Redirect an External URL to an Internal URL

Example Inc. hides information about the actual names of its Web servers and the configuration of its
server room from users, to make URLs on its Web site shorter and easier to remember and to improve
security on its site.

Example 6: Migrating Apache Rewrite Module Rules

Example Inc. moved its Apache rewrite rules to a NetScaler appliance, translating the Apache PERL-
based script syntax to the NetScaler rewrite rule syntax.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1456

NetScaler 12.0

Example 7: Marketing Keyword Redirection

The marketing department at Example Inc. sets up simplified URLs for certain predefined keyword
searches on the company’s Web site.

Example 8: Redirect Queries to the Queried Server.

Example Inc. redirects certain query requests to the appropriate server.

Example 9: Home Page Redirection

Example Inc. recently acquired a smaller competitor, and it now redirects requests to the acquired
company’s home page to a page on its own Web site.

Example 10: Policy-based RSA Encryption

Example Inc. encrypt HTTP predefined and user-defined header or body content by using PEM RSA
public key.

Each of these tasks requires that the system administrators create rewrite actions and policies and
bind them to a valid bind point on the NetScaler.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Example 1: Delete Old X-Forwarded-For and Client-IP Headers

September 24, 2018

Contributed by:
C

Example Inc. wants to remove old X-Forwarded-For and Client-IP HTTP headers from incoming re-
quests, so that the only X-Forwarded-For headers that appear are the ones added by the local server.
This configuration can be done through the NetScaler command line or the GUI. The Example Inc. sys-
tem administrator is an old-school networking engineer and prefers to use a CLI where possible, but
wants to be sure he understands the GUI interface so that he can show new system administrators on
the team how to use it.

The examples below demonstrate how to perform each configuration with both the CLI and the GUI.
The procedures are abbreviated on the assumption that users will already know the basics of creating
rewrite actions, creating rewrite policies, and binding policies.

• For more detailed information about creating rewrite actions, see Configuring a Rewrite Action.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1457

NetScaler 12.0

• For more detailed information about creating rewrite policies, see Configuring a Rewrite Policy.
• For more detailed information about binding rewrite policies, see Binding a Rewrite Policy.

To delete old X-Forwarded and Client-IP headers from a request by using the command
line interface

At the command prompt, type the following commands in the order shown:

1 add rewrite action act_del_xfor delete_http_header x-forwarded-for

2 add rewrite action act_del_cip delete_http_header client-ip
3 add rewrite policy pol_check_xfor ’HTTP.REQ.HEADER(”x-forwarded-for”).
EXISTS’ act_del_xfor
4 add rewrite policy pol_check_cip ’HTTP.REQ.HEADER(”client-ip”).EXISTS’
act_del_cip
5 bind rewrite global pol_check_xfor 100 200
6 bind rewrite global pol_check_cip 200 300

To delete old X-Forwarded and Client-IP headers from a request by using the GUI

In the Create Rewrite Action dialog box, create two rewrite actions with the following descriptions.

Name Type Argument(s)

act_del_xfor delete_http_header x-forwarded-for

act_del_cip delete_http_header client-ip

In the Create Rewrite Policy dialog box, create two rewrite policies with the following descriptions.

Name Expression Action

pol_check_xfor ‘HTTP.REQ.HEADER(“x- act_del_xfor

forwarded-for”).EXISTS’
pol_check_cip ‘HTTP.REQ.HEADER(“client- act_del_cip
ip”).EXISTS’

Bind both policies to global, assigning the priorities and goto expression values shown below.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1458

NetScaler 12.0

Name Priority Goto Expression

pol_check_xfor 100 200

pol_check_cip 200 300

All old X-Forwarded-For and Client-IP HTTP headers are now deleted from incoming requests.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Example 2: Adding a Local Client-IP Header

September 24, 2018

Contributed by:
C

Example Inc. wants to add a local Client-IP HTTP header to incoming requests. This example contains
two slightly different versions of the same basic task.

To add a local Client-IP header by using the command line interface

At the command prompt, type the following commands in the order shown:

1 add rewrite action act_ins_client insert_http_header NS-Client ’CLIENT.

IP.SRC’
2 add rewrite policy pol_ins_client ’HTTP.REQ.HEADER(”x-forwarded-for”).
EXISTS || HTTP.REQ.HEADER(”client-ip”).EXISTS’ act_ins_client
3 bind rewrite global pol_ins_client 300 END

To add a local Client-IP header by using the GUI

In the Create Rewrite Action dialog box, create a rewrite action with the following description.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1459

NetScaler 12.0

Name Type Argument(s)

act_ins_client insert_http_header NS-Client ‘CLIENT.IP.SRC’

In the Create Rewrite Policy dialog box, create a rewrite policy with the following description.

Name Expression Action

pol_ins_client ‘HTTP.REQ.HEADER(“x- HTTP.REQ.HEADER(“client-

act_ins_client
forwarded- ip”).EXISTS’
for”).EXISTS

Bind policy to global, assigning the priorities and goto expression values shown below.
|Name|Priority|Goto Expression|
|–|–|–|
|pol_ins_client|100|Next
A local Client-IP HTTP header is now added to incoming requests. You can also modify the configu-
ration above to append all IPs from X-Forwarded-For headers to the new Client-IP header, as shown
below.
1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Example 3: Tagging Secure and Insecure Connections

September 24, 2018

Contributed by:
C
Example Inc. wants to tag incoming requests with a header that indicates whether or not the connec-
tion is a secure connection. This helps the server keep track of secure connections after the NetScaler
has decrypted the connections.
To implement this configuration, you would begin by creating rewrite actions with the values shown
in the following tables. These actions label connections to port 80 as insecure connections, and con-
nections to port 443 as secure connections.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1460

NetScaler 12.0

Type of Rewrite
Action Name Action Header Name Value

Action-Rewrite- INSERT_HTTP_HEADER SSL YES

SSL_YES

Type of Rewrite
Action Name Action Header Name Value

Action-Rewrite- INSERT_HTTP_HEADER SSL NO

SSL_NO

You would then create a rewrite policy with the values shown in the following tables. These policies
check incoming requests to determine which requests are directed to port 80 and which are directed
to port 443. The policies then add the correct SSL header.

Policy Name Action Name Undefined Action Expression

Policy-Rewrite- Action-Rewrite- NOREWRITE CLIENT.TCP.DSTPORT.EQ(443)

SSL_YES SSL_YES
Policy-Rewrite- Action-Rewrite- NOREWRITE CLIENT.TCP.DSTPORT.EQ(80)
SSL_NO SSL_NO

Finally, you would bind the rewrite policies to NetScaler, assigning the first policy a priority of 200,
and the second a priority of 300, and setting the goto expression of both policies to END.

Each incoming connection to port 80 now has an SSL:NO HTTP header added to it and each incoming
connection to port 443 has an SSL:YES HTTP header added to it.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Example 4: Mask the HTTP Server Type

December 14, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1461

NetScaler 12.0

Contributed by:
C

Example Inc. wants to modify the HTTP Server: header so that unauthorized users and malicious code
cannot use the header to identify the software that the HTTP server uses.

To modify the HTTP Server: header, you would create a rewrite action and a rewrite policy with the
values in the following tables.

Type of Rewrite Expression to choose String expression for

Action Name Action target reference replacement text

Action-Rewrite- REPLACE HTTP.RES.HEADER(“Server”)

“Web Server 1.0”
Server_Mask

Policy Name Action Name Undefined Action Expression

Policy-Rewrite- Action-Rewrite- NOREWRITE HTTP.RES.IS_VALID

Server_Mask Server_Mask

Example commands:

> add rewrite action Action-Rewrite-Server_Mask REPLACE HTTP.RES.HEADER(”

Server”)”\”Web Server 1.0\””

> add rewrite policy Policy-Rewrite-Server_Mask HTTP.RES.IS_VALID Action-

Rewrite-Server_Mask NOREWRITE

You would then globally bind the rewrite policy, assigning a priority of 100 and setting the Goto Priority
Expression of the policy to END.

The HTTP Server: header is now modified to read “Web Server 1.0,” masking the actual HTTP server
software used by the Example Inc. Web site.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Example 5: Redirect an external URL to an internal URL

December 12, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1462

NetScaler 12.0

Contributed by:
C

Example Inc. wants to hide its actual server room configuration from users to improve security on its
Web servers.

To do this, you would create a rewrite action with the values as shown in the following tables. For
request headers, the action in the table modifies www.example.com to web.hq.example.net. For
response headers, the action does the opposite, translating web.hq.example.net to www.example
.com.

Type of Rewrite Expression to choose String expression for

Action Name Action target reference replacement text

Action-Rewrite- REPLACE HTTP.REQ.HOSTNAME.SERVER

“Web.hq.example.net”
Request_Server_Replace
Action-Rewrite- REPLACE HTTP.RES.HEADER(“Server”)
“www.example.com”
Response_Server_Replace

Next, you would create rewrite policies using the values shown in the following tables. The first pol-
icy checks incoming requests to see if they are valid, and if they are, it performs the Action-Rewrite-
Request_Server_Replace action. The second policy checks responses to see if they originate at the
server web.hq.example.net. If they do, it performs the Action-Rewrite-Response_Server_Replace ac-
tion.
Examples of rewrite action and policy for redirect
add rewrite action Action-Rewrite-Request_Server_Replace REPLACE HTTP.REQ.
HOSTNAME.SERVER ’”Web.hq.example.net”

add rewrite action Action-Rewrite-Response_Server_Replace REPLACE HTTP.RES.

HEADER(”Server”)’”www.example.com”

add rewrite policy Policy-Rewrite-Request_Server_Replace HTTP.REQ.HOSTNAME.

SERVER.EQ(”www.example.com”)Action-Rewrite-Request_Server_Replace NOREWRITE

add rewrite policy Policy-Rewrite-Response_Server_Replace HTTP.RES.HEADER

(”Server”).EQ(”web.hq.example.net”)Action-Rewrite-Response_Server_Replace
NOREWRITE

Finally, you would bind the rewrite policies, assigning each a priority of 500 because they are in differ-
ent policy banks and therefore will not conflict. You should set the goto expression to NEXT for both
bindings.
All instances of www.example.com in the request headers are now changed to web.hq.example.net,
and all instances of web.hq.example.net in response headers are now changed to www.example.com.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1463

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Example 6: Migrating Apache Rewrite Module Rules

September 24, 2018

Contributed by:
C

Example Inc., is currently using the Apache rewrite module to process search requests sent to its Web
servers and redirect those requests to the appropriate server on the basis of information in the request
URL. Example Inc. wants to simplify its setup by migrating these rules onto the NetScaler platform.

Several Apache rewrite rules that Example currently uses are shown below. These rules redirect search
requests to a special results page if they do not have a SiteID string or if they have a SiteID string equal
to zero (0), or to the standard results page if these conditions do not apply.

The following are the current Apache rewrite rules:

• RewriteCond %{REQUEST_FILENAME} ˆ/search$ [NC]

• RewriteCond %{QUERY_STRING} !SiteId= [OR]
• RewriteCond %{QUERY_STRING} SiteId=0
• RewriteCond %{QUERY_STRING} CallName=DisplayResults [NC]
• RewriteRule ˆ.*$ /results2.html [P,L]
• RewriteCond %{REQUEST_FILENAME} ˆ/search$ [NC]
• RewriteCond %{QUERY_STRING} CallName=DisplayResults [NC]
• <RewriteRule ˆ.*$ /results.html [P,L]

To implement these Apache rewrite rules on the NetScaler, you would create rewrite actions with the
values in the following tables.

Type of Rewrite Expression to choose String expression for

Action Name Action target reference replacement text

Action-Rewrite- REPLACE HTTP.REQ.URL “/results2.html”

Display_Results_NulSiteID
Action-Rewrite- REPLACE HTTP.REQ.URL “/results2.html”
Display_Results

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1464

NetScaler 12.0

You would then create rewrite policies with the values as shown in the tables below.

Policy Action Undefined

Name Name Action Expression

Policy- Action- NOREWRITE HTTP.REQ.URL.PATH.SET_TEXT_MODE(IGNORECASE).EQ(“/search”)

HTTP.REQ.URL.QUERY.CONTAINS(“SiteId=0”)
HTTP.REQ.URL.QUERY.S
Rewrite- Rewrite- &&
Display_Results_NulSiteID
Display_Results_NulSiteID
(!HTTP.REQ.URL.QUERY.CONTAINS(“SiteId=”)
Policy- Action- NOREWRITE HTTP.REQ.URL.PATH.SET_TEXT_MODE(IGNORECASE).EQ(“/search”)
HTTP.REQ.URL.QUERY.SET_TEXT_MODE(IGNORE
Rewrite- Rewrite-
Display_Results
Display_Results

Finally, you would bind the rewrite policies, assigning the first a priority of 600 and the second a pri-
ority of 700, and then set the goto expression to NEXT for both bindings.
The NetScaler now handles these search requests exactly as the Web server did before the Apache
rewrite module rules were migrated.
1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Example 7: Marketing Keyword Redirection

September 24, 2018

Contributed by:
C
The marketing department at Example Inc. wants to set up simplified URLs for certain predefined
keyword searches on the company’s Web site. For these keywords, it wants to redefine the URL as
shown below.
• External URL:
http://www.example.com/\<marketingkeyword\>

• Internal URL:
http://www.example.com/go/kwsearch.asp?keyword=\<marketingkeyword\>

To set up redirection for marketing keywords, you would create a rewrite action with the values in the
following table.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1465

NetScaler 12.0

Type of Rewrite Expression to choose String expression for

Action Name Action target location replacement text

Action-Rewrite- INSERT_BEFORE HTTP.REQ.URL.PATH.GET(1)

””go/kwsearch.aspkeyword=”l”
Modify_URL

You would then create a rewrite policy with the values in the following table.

Policy Name Action Name Undefined Action Expression

Policy-Rewrite- Action-Rewrite- NOREWRITE HTTP.REQ.HOSTNAME.SERVER.EQ(“w

Modify_URL Modify_URL

Finally, you would bind the rewrite policy, assigning it a priority of 800. Unlike the previous rewrite
policies, this policy should be the last to be applied to a request that matches its criteria. For this
reason, NetScaler administrator sets its Goto Priority Expression to END.

Any request using a marketing keyword is redirected to the keyword search CGI page, whereupon a
search is performed and all remaining policies are skipped.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Example 8: Redirect Queries to the Queried Server

December 13, 2018

Contributed by:
C

Example Inc. wants to redirect query requests to the appropriate server, as shown here.

• <Request: GET /query.cgi?server=5HOST: www.example.com

• <Redirect URL: <http://web-5.example.com/>

To implement this redirection, you would first create a rewrite action with the values in the following
table.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1466

NetScaler 12.0

Type of Rewrite Expression to choose String expression for

Action Name Action target reference replacement text

Action-Rewrite- REPLACE HTTP.REQ.HEADER( “server-“ +

Replace_Hostheader ”Host”).BEFORE\\ HTTP.REQ.URL.QUERY.VALUE(“web”)
_STR(”.example.
com”)

You would then create a rewrite policy with the values in the following table.

Policy Name Action Name Undefined Action Expression

Policy-Rewrite- Action-Rewrite- NOREWRITE HTTP.REQ.HEADER(

Replace_Hostheader Replace_Hostheader ”Host”).EQ(”www.
example.com”)

Example CLI commands:

> add rewrite action Action-Rewrite-Server_Mask REPLACE HTTP.RES.HEADER(”

Server”)”\”Web Server 1.0\””
Done

> add rewrite policy Policy-Rewrite-Server_Mask HTTP.RES.IS_VALID Action-

Rewrite-Server_Mask NOREWRITE
Done

Finally, you would bind the rewrite policy, assigning it a priority of 900. Because this policy should be
the last policy applied to a request that matches its criteria, you set the goto expression to END.

Incoming requests to any URL that begins with <http://www.example.com/query.cgi?server

>= are redirected to the server number in the query.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Example 9: Home Page Redirection

September 24, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1467

NetScaler 12.0

Contributed by:
C

New Company, Inc. recently acquired a smaller competitor, Purchased Company, and wants to redi-
rect the home page for Purchased Company to a new page on its own Web site, as shown here.

• Old URL: http://www.purchasedcompany.com/\*

• New URL: http://www.newcompany.com/products/page.htm

To redirect requests to the Purchased Company home page, you would create rewrite actions with the
values in the following table.

Type of Rewrite Expression to choose String expression for

Action Name Action target reference replacement text

Action-Rewrite- REPLACE HTTP.REQ.URL.PATH_AND_QUERY

“/products/page.htm”
Replace_URLr
Action-Rewrite- REPLACE HTTP.REQ.HOSTNAME “www.newcompany.com”
Replace_Host

You would then create rewrite policies with the values in the following table.

Policy Name Action Name Undefined Action Expression

Policy-Rewrite- Action-Rewrite- NOREWRITE !HTTP.REQ.HOSTNAME.SERVER.EQ(“

Replace-None Replace-None
Policy-Rewrite- Action-Rewrite- NOREWRITE HTTP.REQ.HOSTNAME.SERVER.EQ(“w
Replace-Host Replace_Host
Policy-Rewrite- Action-Rewrite- NOREWRITE HTTP.REQ.IS_VALID
Replace-URL Replace_URL

Finally, you would bind the rewrite policies globally, assigning the first a priority of 100, the second
a priority of 200, and the third a priority of 300. These policies should be the last policies applied to
a request that matches the criteria. For this reason, set the goto expression to END for the first and
third policies, and to 300 for the second policy. This ensures that all remaining requests are processed
correctly.

Requests to the acquired company’s old Web site are now redirected to the correct page on the New
Company home page.

1.
2. Citrix ADC

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1468

NetScaler 12.0

3. NetScaler 12.0
4. AppExpert

Example 10: Policy-based RSA Encryption

September 24, 2018

Contributed by:
C
The RSA algorithm uses the PKEY_ENCRYPT_PEM() function to encrypt HTTP predefined and user-
defined header or body content. The function accepts only RSA public keys (not private keys) and the
encrypted data cannot be longer than the length of the public key. When the data being encrypted is
shorter than the key length, the algorithm uses RSA_PKCS1 padding method.
In a sample scenario, the function can be used with B64ENCODE() function in a rewrite action to re-
place an HTTP header value with a value encrypted by an RSA public key. The data being encrypted
is then decrypted by the recipient using the RSA private key.
You can implement the feature by using a rewrite policy. To do this, you must complete the following
tasks:
1. Add RSA public key as a policy expression.
2. Create rewrite action.
3. Create rewrite policy.
4. Bind rewrite policy as global.
5. Verify RSA encryption

Policy-based RSA encryption by using NetScaler command interface

Complete the following tasks to configure policy-based RSA encryption by using the NetScaler com-
mand interface.
To add RSA public key as a policy expression by using the NetScaler command interface:

1 add policy expression pubkey ’”-----BEGIN RSA PUBLIC KEY-----

MIGJAoGBAKl5vgQEj73Kxp+9
yn1v5gPR1pnc4oLM2a0kaWwBOsB6rzCIy6znwnvwCY1xRvQhRlJSAyJbloL7wZFIJ2FOR8Cz
+8ZQWXU2syG+udi4EnWqLgFYowF9zK+o79az597eNPAjsHZ/C2oL/+6qY5a/
f1z8bQPrHC4GpFfAEJhh/+NnAgMBAAE=-----END RSA PUBLIC KEY-----”’

To add rewrite an action to encrypt an HTTP header request by using the NetScaler command
interface:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1469

NetScaler 12.0

1 add rewrite action encrypt_act insert_http_header encrypted_data

2
3 ’HTTP.REQ.HEADER(”data_to_encrypt”).PKEY_ENCRYPT_PEM(pubkey).B64ENCODE’

To add rewrite policy by using the NetScaler command interface:

1 add rewrite policy encrypt_pol ’HTTP.REQ.HEADER(”data_to_encrypt”).

EXISTS’ encrypt_act

To bind rewrite policy global by using the NetScaler command interface:

1 bind rewrite global encrypt_pol 10 -type RES_DEFAULT

To verify RSA encryption by using the NetScaler command interface:

1 >curl -v -H ”data_to_encrypt: Now is the time that tries men’s souls”

http://10.217.24.7/
2
3 * About to connect() to 10.217.24.7 port 80 (#0)
4
5 *   Trying 10.217.24.7...
6
7 * connected
8
9 * Connected to 10.217.24.7 (10.217.24.7) port 80 (#0)
10
11 > GET / HTTP/1.1
12
13 > User-Agent: curl/7.24.0 (amd64-portbld-freebsd8.4) libcurl/7.24.0
OpenSSL/0.9.8y zlib/1.2.3
14
15 > Host: 10.217.24.7
16
17 > Accept: */*
18
19 > data_to_encrypt: Now is the time that tries men’s souls
20
21 >
22
23 < HTTP/1.1 200 OK
24
25 < Date: Mon, 09 Oct 2017 05:22:37 GMT
26
27 < Server: Apache/2.2.24 (FreeBSD) mod_ssl/2.2.24 OpenSSL/0.9.8y DAV/2
28

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1470

NetScaler 12.0

29 < Last-Modified: Thu, 20 Feb 2014 20:29:06 GMT

30
31 < ETag: ”6bd9f2-2c-4f2dc5b570880”
32
33 < Accept-Ranges: bytes
34
35 < Content-Length: 44
36
37 < Content-Type: text/html
38
39 < encrypted_data: UliegKBJqZd7JdaC49XMLEK1+eQN2rEfevypW91gKvBVlaKM9N9/
C2BKuztS99SE0xQaisidzN5IgeIcpQMn+
CiKYVlLzPG1RuhGaqHYzIt6C8A842da7xE4OlV5SHwScqkqZ5aVrXc3EwtUksna7jOLr40aLeXnnB
/DB11pUAE=
40
41
42 <
43
44 * Connection #0 to host 10.217.24.7 left intact
45
46 <html><body><h1>It works!</h1></body></html>* Closing connection #0

Subsequent execution of this curl command with the same data to encrypt shows that the encrypted
data is different each execution. This is because the padding inserts random bytes at the beginning
of the data to encrypt, causing the encrypted data to be different each time.

1 >curl -v -H ”data_to_encrypt: Now is the time that tries men’s souls”

http://10.217.24.7/
2
3 . . .
4
5 < encrypted_data:
DaOjtl1Pl4DlQKf58MMeL4cFwFvZwhjMqv5aUYM5Iyzk4UpwIYhpRvgTNu2lXEVc1H0tcR1EGC
/ViQncLc4EbTurCWLbzjce3+fknnMmzF0lRT6ZZXWbMvsNFOxDA1SnuAgwxWXy/
ooe9Wy6SYsL2oi1sr5wTG+RihDd9zP+P14=
6
7 >curl -v -H ”data_to_encrypt: Now is the time that tries men’s souls”
http://10.217.24.7/
8
9 . . .
10
11 < encrypted_data: eej6YbGP68yHn48qFUvi+fkG+OiO8j3yYLScrRBU+
TPQ8WeDVaWnDNAVLvL0ZYHHAU1W2YDRYb+8
cdKHLpW36QbI6Q5FfBuWKZSI2hSyUvypTpCoAYcHXFv0ns+tRtg0EPNNj+
lyGjKQWtFi6K8IXXISoDy42FblKIlaA7gEriY=

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1471

NetScaler 12.0

Policy-based RSA encryption by using the GUI

The GUI enables you to complete the following tasks:

To add RSA public key as a policy expression by using the GUI:

1. Sign into the NetScaler appliance and navigate to Configurations > AppExpert > Advanced Ex-
pressions.
2. In the details pane, click Add to define an RSA public key as an advanced policy expression.
3. In Create Expression page, set the following parameters:
a) Expression name. Name of the advanced expression.
b) Expression. Define RSA public key as an advanced expression using the Expression Editor.
c) Comments. A brief description of the expression.
4. Click Create.

To add rewrite an action to encrypt an HTTP header request by using the GUI:

1. Sign into the NetScaler appliance and navigate to Configurations > AppExpert > Rewrite > Ac-
tions.
2. In the details pane, click Add to add a rewrite action.
3. In the Create Rewrite Action screen, set the following parameters:
a) Name. Name of the rewrite action.
b) Type. Select action type as INSERT_HTTP_HEADER.
c) Use the action type to insert a header. Enter the name of the HTTP header that needs to
be rewritten.
d) Expression. Name of the advanced policy expression associated to the action.
e) Comments. A brief description of the rewrite action.
4. Click Create.

To add rewrite advanced policy by using the GUI:

1. Sign into the NetScaler appliance and navigate to Configurations > AppExpert > Rewrite > Poli-
cies.
2. In the Rewrite Policies page, click Add to add a rewrite policy.
3. In the Create Rewrite Policy page, set the following parameters:
a) Name. Name of the rewrite policy.
b) Action. Name of the rewrite action to perform if the request or response matches this
rewrite policy.
c) Log Action. Name of message log action to use when a request matches this policy.
d) Undefined-Result Action. Action to perform if the result of policy evaluation is undefined.
e) Expression. Name of the advanced policy expression that triggers the action.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1472

NetScaler 12.0

f) Comments. A brief description of the rewrite action.

4. Click Create.**

To bind rewrite policy global by using the GUI:

1. Sign into the NetScaler appliance and navigate to Configurations > AppExpert > Rewrite > Poli-
cies.
2. In the Rewrite Policies screen, select a rewrite policy that you want to bind and click Policy
Manager.
3. In the Rewrite Policy Manager page, in the Bind Points section, set the following parameters:
a) Bind Point. Select the binding point as Default Global.
b) Protocol. Select the protocol type as HTTP.
c) Connection Type. Select the connection type as Request.
d) Click Continue to view the Policy Binding section.
e) In the Policy Binding section, select the rewrite policy and set the bind parameters.
4. Click Bind.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Example 11: Policy-based RSA encryption with no padding operation

May 20, 2019

Contributed by:
C

The PKEY_ENCRYPT_PEM_NO_PADDING() policy function uses the RSA algorithm with no

padding operation before performing RSA encryption. The policy function works just like the
PKEY_ENCRYPT_PEM() function, except it uses RSA_NO_PADDING method instead of RSA_PKCS1_PADDING.
The pkey parameter is a text string with a PEM-encoded RSA public key. Similar to PKEY_ENCRYPT_PEM(),
you can use a policy expression for the key.

You can implement the feature by using a rewrite policy. To do this, you must complete the following
tasks:

1. Add RSA public key as a policy expression.

2. Create rewrite action.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1473

NetScaler 12.0

Policy-based RSA encryption by using Citrix ADC command interface

Complete the following tasks to configure policy-based RSA encryption by using the Citrix ADC com-
mand interface.
To add RSA public key with no padding policy expression by using the Citrix ADC command in-
terface:

1 add expression rsa_pub_key_4096 ’”-----BEGIN RSA PUBLIC KEY-----” + ”

MIICCgKCAgEArrwBldKd48xrpOSRPMrg+eNAO0ODU6t5b/WYQLdElqNv7WpefBrA” +
\”nwI2s619gEU1r4zoLqL7l5ALtt5Z+F0JBYfOzBzOky0GtEJ5iX5GP4QxT65J3nHH”
+ ”4MTF3acmjvXxclmaKXEFlaVIzW7FTr3Luw/CnOjflAB403Q6F9VBVvQmOVYWnqoI”
+ \”+0q1VIg6Q1pAcvdKBiOf85BBofE5EIbZ/1Jt0CdbsV568l+8
ve7BnSUncFHoRR3O” + ”/
VfSsDuNWZf7n3RNMzxEuIA72UGPzNYFQzvcPOdzd0aN7jAXw0mgC/NSvKzGKHlo” +
\”mUYYBzlVQdDMZWnd6jSzsBRXSXxsNEy/RuXwplrA5epo7JdCoMkfeI4vUXm6MNr8”
+ ”TQdFqIc1pdnOsbRf9ec62XbcfR7P8CDTsmLSaagx3rjenPdB+LTWKw2VUF+YONIg”
+ \”jM3fyFef9ovVhLhS5HvMqFGs8P75W+
d7BOIbIu3EngACiEJOpYSsETD4WgPK6Iyv” + ”
j6cxsLeYMtElTb0fBIIqysCHdmjF3M1lqdqp4dKs3+W798GJZYM5MxZKUzrBi0Xu” +
\”e7GtSh2aimsfQureUD+0z0RN2umeDsYcA1ghXMclDP+jLS1lnrv0Yvo+TKcm9b8G”
+ ”uR/drbCrCsGyWFW+bsAu3AWz9S6TePurP5unRmNNvXpH5DRgsYl3d50CAwEAAQ==”
+ \”-----END RSA PUBLIC KEY-----\”

To add rewrite action for no padding policy expression by using the Citrix ADC command inter-
face:
add rewrite action rsa_encrypt_act insertHttpHeader encrypted ’HTTP.REQ.
HEADER(”plaintext”).PKEY_ENCRYPT_PEM_NO_PADDING(rsa_pub_key_4096)

Policy-based RSA encryption with no padding option by using the GUI

The GUI enables you to complete the following tasks:

To add RSA public key for no padding operation as a policy expression by using the GUI:
1. Sign into the Citrix ADC appliance and navigate to Configurations > AppExpert > Advanced
Expressions.
2. In the details pane, click Add to define an RSA public key as an advanced policy expression.
3. In Create Expression page, set the following parameters:
a) Expression name. Name of the advanced expression.
b) Expression. Define RSA public key as an advanced expression using the Expression Editor.
Note: The maximum string length is of 255 characters in a policy expression. For any key
longer than 1024-bits, you have to break the key into smaller chunks and concatenate the
chunks together as “chunk1” + “chunk2” + …

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1474

NetScaler 12.0

c) Comments. A brief description of the expression.

4. Click Create.

To add rewrite an action by using the GUI:

1. Sign into the Citrix ADC appliance and navigate to Configurations > AppExpert > Rewrite >
Actions.
2. In the details pane, click Add to add a rewrite action.
3. In the Create Rewrite Action screen, set the following parameters:
a) Name. Name of the rewrite action.
b) Type. Select action type as INSERT_HTTP_HEADER.
c) Use the action type to insert a header. Enter the name of the HTTP header that needs to
be rewritten.
d) Expression. Name of the advanced policy expression associated to the action.
e) Comments. A brief description of the rewrite action.
4. Click Create.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

URL Transformation

September 24, 2018

Contributed by:
C

The URL transformation feature provides a method for modifying all URLs in designated requests from
an external version seen by outside users to an internal URL seen only by your Web servers and IT staff.
You can redirect user requests seamlessly, without exposing your network structure to users. You can
also modify complex internal URLs that users may find difficult to remember into simpler, more easily
remembered external URLs.
Note

Before you can use the URL transformation feature, you must enable the Rewrite feature. To
enable the Rewrite feature, see Enabling the Rewrite Feature.

URL transform feature rewrites URLs in HTML response body and is not applied to JavaScript and
other variables.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1475

NetScaler 12.0

To begin configuring URL transformation, you create profiles, each describing a specific transforma-
tion. Within each profile, you create one or more actions that describe the transformation in detail.
Next, you create policies, each of which identifies a type of HTTP request to transform, and you as-
sociate each policy with an appropriate profile. Finally, you globally bind each policy to put it into
effect.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring URL Transformation Profiles

September 24, 2018

Contributed by:
C

A profile describes a specific URL transformation as a series of actions. The profile functions primarily
as a container for the actions, determining the order in which the actions are performed. Most trans-
formations transform an external hostname and optional path into a different, internal hostname and
path. Most useful transformations are simple and require only a single action, but you can use multi-
ple actions to perform complex transformations.

You cannot create actions and then add them to a profile. You must create the profile first, and then
add actions to it. In the CLI, creating an action and configuring the action are separate steps. Creating
a profile and configuring the profile are separate steps in both the CLI and the GUI.

To create a URL transformation profile by using the NetScaler command line

At the NetScaler command prompt, type the following commands, in the order shown, to create a
URL transformation profile and verify the configuration. You can then repeat the second and third
commands to configure additional actions:

add transform profile <profileName> -type URL OFF)] [-comment <comment>]

[-onlyTransformAbsURLinBody (ON

• add transform action <name> <profileName> <priority>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1476

NetScaler 12.0

set transform action <name> [-priority DISABLED)] [-comment “<string>”]

<priority>] [-reqUrlFrom <expression>]
[-reqUrlInto <expression>] [-resUrlFrom
<expression>] [-resUrlInto <expression>]
[-cookieDomainFrom <expression>]
[-cookieDomainInto <expression>] [-state
(ENABLED

•
• show transform profile <name>
Example:

1 > add transform profile shoppingcart -type URL

2 Done
3 > add transform action actshopping shoppingcart 1000
4 Done
5 > set transform action actshopping -priority 1000 -reqUrlFrom ’shopping
.example.com’ -reqUrlInto ’www.example.net/shopping’ -resUrlFrom ’
www.example.net/shopping’ -resUrlInto ’shopping.example.com’ -
cookieDomainFrom ’example.com’ -cookieDomainInto ’example.net’ -
state ENABLED -comment ’URL transformation for shopping cart.’
6 Done
7 > show transform profile shoppingcart
8 Name: shoppingcart
9 Type: URL onlyTransformAbsURLinBody: OFF
10 Comment:
11 Actions:
12
13 1) Priority 1000 Name: actshopping ENABLED
14 Done

To modify an existing URL transformation profile or action by using the NetScaler

command line

At the NetScaler command prompt, type the following commands to modify an existing URL transfor-
mation profile or action and verify the configuration:
Note: Use a set transform profile or set transform action command, respectively. The set transform
profile command takes the same arguments as does the add transform profile command, and set
transform action is the same command that was used for initial configuration.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1477

NetScaler 12.0

set transform action <name> [-priority DISABLED)] [-comment “<string>”]

<priority>] [-reqUrlFrom <expression>]
[-reqUrlInto <expression>] [-resUrlFrom
<expression>] [-resUrlInto <expression>]
[-cookieDomainInto <expression>] [-state
(ENABLED

• show transform profile <name>

Example:

1 > set transform action actshopping -priority 1000 -reqUrlFrom ’

searching.example.net’ -reqUrlInto ’www.example.net/searching’ -
resUrlFrom ’www.example.net/searching’ -resUrlInto ’searching.
example.com’ -cookieDomainInto ’example.net’ -state ENABLED -comment
’URL transformation for searching cart.’
2 Done
3 > show transform profile shoppingcart
4 Name: shoppingcart
5 Type: URL onlyTransformAbsURLinBody: OFF
6 Comment:
7 Actions:
8
9 1) Priority 1000 Name: actshopping ENABLED
10 Done

To remove a URL transformation profile and actions by using the NetScaler command
line

First remove all actions associated with that profile by typing the following command once for each
action:

• rm transform action <name> After you have removed all actions associated with a profile, re-
move the profile as shown below.
• rm transform profile <name>

To create a URL transformation profile by using the GUI

1. In the navigation pane, expand Rewrite, expand URL Transformation, and then click Profiles.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1478

NetScaler 12.0

2. In the details pane, click Add.

3. In the Create URL Transformation Profile dialog box, type or select values for the parameters.
The contents of the dialog box correspond to the parameters described in “Parameters for con-
figuring URL transformation profiles” as follows (asterisk indicates a required parameter):
• Name*—name
• Comment—comment
• Only transform absolute URLs in response body—onlyTransformAbsURLinBody
4. Click Create, and then click Close. A message appears in the status bar, stating that the Profile
has been configured successfully.

To configure a URL transformation profile and actions by using the GUI

1. In the navigation pane, expand Rewrite, expand URL Transformation, and then click Profiles.
2. In the details pane, select the profile you want to configure, and then click Open.
3. In the Configure URL Transformation Profile dialog box, do one of the following.
• To create a new action, click Add.
• To modify an existing action, select the action, and then click Open.
4. Fill in the Create URL Transformation Action or Modify URL Transformation Action dialog box by
typing or selecting values for the parameters. The contents of the dialog box correspond to the
parameters described in “Parameters for configuring URL transformation profiles” as follows
(asterisk indicates a required parameter):
• Action Name*—name
• Comments—comment
• Priority*—priority
• Request URL from—reqUrlFrom
• Request URL into—reqUrlInto
• Response URL from—resUrlFrom
• Response URL into—resUrlInto
• Cookie Domain from—cookieDomainFrom
• Cookie Domain into—cookieDomainInto
• Enabled—state
5. Save your changes.
• If you are creating a new action, click Create, and then Close.
• If you are modifying an existing action, click OK.
A message appears in the status bar, stating that the Profile has been configured success-
fully.
6. Repeat step 3 through step 5 to create or modify any additional actions.
7. To delete an action, select the action, and then click Remove. When prompted, click OK to con-
firm the deletion.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1479

NetScaler 12.0

8. Click OK to save your changes and close the Modify URL Transformation Profile dialog box.
9. To delete a profile, in the details pane select the profile, and then click Remove. When
prompted, click OK to confirm the deletion.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring URL Transformation Policies

September 24, 2018

Contributed by:
C

After you create a URL transformation profile, you next create a URL transformation policy to select
the requests and responses that the NetScaler should transform by using the profile. URL transfor-
mation considers each request and the response to it as a single unit, so URL transformation policies
are evaluated only when a request is received. If a policy matches, the NetScaler transforms both the
request and the response.

Note: The URL transformation and rewrite features cannot both operate on the same HTTP header
during request processing. Because of this, if you want to apply a URL transformation to a request,
you must make sure that none of the HTTP headers it will modify are manipulated by any rewrite
action.

To configure a URL transformation policy by using the NetScaler command line

You must create a new policy. On the command line, an existing policy can only be removed. At the
NetScaler command prompt, type the following commands to configure a URL transformation policy
and verify the configuration:

• <add transform policy <name> <rule> <profileName>

• <show transform policy <name>

Example:

1 > add transform policy polsearch HTTP.REQ.URL.SUFFIX.EQ(”Searching”)

prosearching
2 Done
3 > show transform policy polsearch

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1480

NetScaler 12.0

4 1) Name: polsearch
5 Rule: HTTP.REQ.URL.SUFFIX.EQ(”Searching”)
6 Profile: prosearching
7 Priority: 0
8 Hits: 0
9 Done

To remove a URL transformation policy by using the NetScaler command line

At the NetScaler command prompt, type the following command to remove a URL transformation
policy:

rm transform policy <name>

Example:

1 > rm transform policy polsearch

2 Done

To configure a URL transformation policy by using the GUI

1. In the navigation pane, expand Rewrite, expand URL Transformation, and then click Policies.

2. In the details pane, do one of the following:

• To create a new policy, click Add.

• To modify an existing policy, select the policy, and then click Open.

3. In the Create URL Transformation Policy or Configure URL Transformation Policy dialog box,
type or select values for the parameters. The contents of the dialog box correspond to the pa-
rameters described in “Parameters for configuring URL transformation policies” as follows (as-
terisk indicates a required parameter):

• Name*—name (Cannot be changed for a previously configured policy.)

• Profile*—profileName
• Expression—rule

If you want help with creating an expression for a new policy, you can either hold down the
Control key and press the space bar while your cursor is in the Expression text box. To create
the expression, you can type it directly as described below, or you can use the Add Expression
dialog box.

a) Click Prefix, and choose the prefix for your expression.

Your choices are:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1481

NetScaler 12.0

• HTTP—The HTTP protocol. Choose this if you want to examine some aspect of the
request that pertains to the HTTP protocol.

• SYS—The protected Web site(s). Choose this if you want to examine some aspect of
the request that pertains to the recipient of the request.

• CLIENT—The computer that sent the request. Choose this if you want to examine
some aspect of the sender of the request.

• SERVER—The computer to which the request was sent. Choose this if you want to
examine some aspect of the recipient of the request.

• URL—The URL of the request. Choose this if you want to examine some aspect of the
URL to which the request was sent.

• TEXT—Any text string in the request. Choose this if you want to examine a text string
in the request.

• TARGET—The target of the request. Choose this if you want to examine some aspect
of the request target.

After you choose a prefix, the NetScaler displays a two-part prompt window that dis-
plays the possible next choices at the top, and a brief explanation of what the selected
choice means at the bottom. The choices depend on which prefix you chose.

b) Select your next term.

If you chose HTTP as your prefix, your choices are REQ, which specifies HTTP requests, and
RES, which specifies HTTP responses. If you chose another prefix, your choices are more
varied. For help on a specific choice, click that choice once to display information about it
in the lower prompt window.

When you are certain which choice you want, double-click it to insert it into the Expression
window.

c) Type a period, and then continue selecting terms from the list boxes that appear to the
right of the previous list box. You type the appropriate text strings or numbers in the text
boxes that appear to prompt you to enter a value, until your expression is finished.

4. Click Create or OK, depending on whether you are creating a new policy or modifying an existing
policy.

5. Click Close. A message appears in the status bar, stating that the Policy has been configured
successfully.

To add an expression by using the Add Expression dialog box

1. In the Create Responder Action or Configure Responder Action dialog box, click Add.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1482

NetScaler 12.0

2. In the Add Expression dialog box, in the first list box choose the first term for your expression.

• HTTP

The HTTP protocol. Choose this if you want to examine some aspect of the request that
pertains to the HTTP protocol.

• SYS

The protected Web site(s). Choose this if you want to examine some aspect of the request
that pertains to the recipient of the request.

• CLIENT

The computer that sent the request. Choose this if you want to examine some aspect of
the sender of the request.

• SERVER

The computer to which the request was sent. Choose this if you want to examine some
aspect of the recipient of the request.

• URL

The URL of the request. Choose this if you want to examine some aspect of the URL to
which the request was sent.

• TEXT

Any text string in the request. Choose this if you want to examine a text string in the re-
quest.

• TARGET

The target of the request. Choose this if you want to examine some aspect of the request
target.
When you make your choice, the rightmost list box lists appropriate terms for the next part
of your expression.

3. <In the second list box, choose the second term for your expression. The choices depend upon
which choice you made in the previous step, and are appropriate to the context. After you
make your second choice, the Help window below the Construct Expression window (which
was blank) displays help describing the purpose and use of the term you just chose.

4. <Continue choosing terms from the list boxes that appear to the right of the previous list box,
or typing strings or numbers in the text boxes that appear to prompt you to enter a value, until
your expression is finished.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1483

NetScaler 12.0

4. AppExpert

Globally Binding URL Transformation Policies

September 24, 2018

Contributed by:
C

After you have configured your URL transformation policies, you bind them to Global or a bind point
to put them into effect. After binding, any a request or response that matches a URL transformation
policy is transformed by the profile associated with that policy.

When you bind a policy, you assign a priority to it. The priority determines the order in which the
policies you define are evaluated. You can set the priority to any positive integer. In the NetScaler OS,
policy priorities work in reverse order - the higher the number, the lower the priority.

Because the URL transformation feature implements only the first policy that a request matches, not
any additional policies that it might also match, policy priority is important for achieving the results
that you intend. If you give your first policy a low priority (such as 1000), you tell the NetScaler to per-
form it only if other policies with a higher priority do not match a request. If you give your first policy a
high priority (such as 1), you tell the NetScaler to perform it first, and skip any other policies that might
also match. You can leave yourself plenty of room to add other policies in any order, without having
to reassign priorities, by setting priorities with intervals of 50 or 100 between each policy when you
globally bind your policies.

Note: URL transformation policies cannot be bound to TCP-based virtual servers.

To bind a URL transformation policy by using the NetScaler command line

At the NetScaler command prompt, type the following commands to globally bind a URL transforma-
tion policy and verify the configuration:

• bind transform global \<policyName\> \<priority\>

• show transform global

Example:

1 > bind transform global polisearching 100

2 Done
3 > show transform global
4 1) Policy Name: polisearching
5 Priority: 100

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1484

NetScaler 12.0

6
7 Done

To bind a URL transformation policy by using the GUI

1. In the navigation pane, expand Rewrite, then expand URL Transformation, and then click Poli-
cies.
2. In the details pane, click Policy Manager.
3. In the Transform Policy Manager dialog box, choose the bind point to which you want to bind
the policy. The choices are:
• Override Global. Policies that are bound to this bind point process all traffic from all in-
terfaces on the NetScaler appliance, and are applied before any other policies.
• LB Virtual Server. Policies that are bound to a load balancing virtual server are applied
only to traffic that is processed by that load balancing virtual server, and are applied be-
fore any Default Global policies. After selecting LB Virtual Server, you must also select the
specific load balancing virtual server to which you want to bind this policy.
• CS Virtual Server. Policies that are bound to a content switching virtual server are applied
only to traffic that is processed by that content switching virtual server, and are applied
before any Default Global policies. After selecting CS Virtual Server, you must also select
the specific content switching virtual server to which you want to bind this policy.
• Default Global. Policies that are bound to this bind point process all traffic from all inter-
faces on the NetScaler appliance.
• Policy Label. Policies that are bound to a policy label process traffic that the policy label
routes to them. The policy label controls the order in which policies are applied to this
traffic.
4. Select Insert Policy to insert a new row and display a drop-down list with all available, unbound
URL transformation policies.
5. Select the policy you want to bind, or select New Policy to create a new policy. The policy that
you selected or created is inserted into the list of globally bound URL transformation policies.
6. Make any additional adjustments to the binding.
• <To modify the policy priority, click the field to enable it, and then type a new priority. You
can also select Regenerate Priorities to renumber the priorities evenly.
• To modify the policy expression, double click that field to open the Configure Transform
Policy dialog box, where you can edit the policy expression.
• To set the Goto Expression, double click field in the Goto Expression column heading to
display the drop-down list, where you can choose an expression.
• To set the Invoke option, double click field in the Invoke column heading to display the
drop-down list, where you can choose an expression.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1485

NetScaler 12.0

7. Repeat steps 3 through 6 to add any additional URL transformation policies you want to globally
bind.
8. Click OK to save your changes. A message appears in the status bar, stating that the Policy has
been configured successfully.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Globally Binding URL Transformation Policies

September 24, 2018

Contributed by:
C

After you have configured your URL transformation policies, you bind them to Global or a bind point
to put them into effect. After binding, any a request or response that matches a URL transformation
policy is transformed by the profile associated with that policy.

When you bind a policy, you assign a priority to it. The priority determines the order in which the
policies you define are evaluated. You can set the priority to any positive integer. In the NetScaler OS,
policy priorities work in reverse order - the higher the number, the lower the priority.

Because the URL transformation feature implements only the first policy that a request matches, not
any additional policies that it might also match, policy priority is important for achieving the results
that you intend. If you give your first policy a low priority (such as 1000), you tell the NetScaler to per-
form it only if other policies with a higher priority do not match a request. If you give your first policy a
high priority (such as 1), you tell the NetScaler to perform it first, and skip any other policies that might
also match. You can leave yourself plenty of room to add other policies in any order, without having
to reassign priorities, by setting priorities with intervals of 50 or 100 between each policy when you
globally bind your policies.

Note: URL transformation policies cannot be bound to TCP-based virtual servers.

To bind a URL transformation policy by using the NetScaler command line

At the NetScaler command prompt, type the following commands to globally bind a URL transforma-
tion policy and verify the configuration:

• bind transform global \<policyName\> \<priority\>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1486

NetScaler 12.0

• show transform global

Example:

1 > bind transform global polisearching 100

2 Done
3 > show transform global
4 1) Policy Name: polisearching
5 Priority: 100
6
7 Done

To bind a URL transformation policy by using the GUI

1. In the navigation pane, expand Rewrite, then expand URL Transformation, and then click Poli-
cies.
2. In the details pane, click Policy Manager.
3. In the Transform Policy Manager dialog box, choose the bind point to which you want to bind
the policy. The choices are:
• Override Global. Policies that are bound to this bind point process all traffic from all in-
terfaces on the NetScaler appliance, and are applied before any other policies.
• LB Virtual Server. Policies that are bound to a load balancing virtual server are applied
only to traffic that is processed by that load balancing virtual server, and are applied be-
fore any Default Global policies. After selecting LB Virtual Server, you must also select the
specific load balancing virtual server to which you want to bind this policy.
• CS Virtual Server. Policies that are bound to a content switching virtual server are applied
only to traffic that is processed by that content switching virtual server, and are applied
before any Default Global policies. After selecting CS Virtual Server, you must also select
the specific content switching virtual server to which you want to bind this policy.
• Default Global. Policies that are bound to this bind point process all traffic from all inter-
faces on the NetScaler appliance.
• Policy Label. Policies that are bound to a policy label process traffic that the policy label
routes to them. The policy label controls the order in which policies are applied to this
traffic.
4. Select Insert Policy to insert a new row and display a drop-down list with all available, unbound
URL transformation policies.
5. Select the policy you want to bind, or select New Policy to create a new policy. The policy that
you selected or created is inserted into the list of globally bound URL transformation policies.
6. Make any additional adjustments to the binding.
• <To modify the policy priority, click the field to enable it, and then type a new priority. You
can also select Regenerate Priorities to renumber the priorities evenly.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1487

NetScaler 12.0

• To modify the policy expression, double click that field to open the Configure Transform
Policy dialog box, where you can edit the policy expression.
• To set the Goto Expression, double click field in the Goto Expression column heading to
display the drop-down list, where you can choose an expression.
• To set the Invoke option, double click field in the Invoke column heading to display the
drop-down list, where you can choose an expression.
7. Repeat steps 3 through 6 to add any additional URL transformation policies you want to globally
bind.
8. Click OK to save your changes. A message appears in the status bar, stating that the Policy has
been configured successfully.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Diameter Support for Rewrite

September 24, 2018

Contributed by:
C

The Rewrite feature now supports the Diameter protocol. You can configure Rewrite to modify Diam-
eter requests and response as you would HTTP or TCP requests and responses, allowing you to use
Rewrite to manage the flow of Diameter requests and make necessary modifications. For example, if
the “Origin-Host” value in a Diameter request is inappropriate, you can use Rewrite to replace it with
a value that is acceptable to the Diameter server.

To configure Rewrite to modify a Diameter request

To configure the Rewrite feature to replace the Origin-Host in a diameter request with a different value,
at the command prompt, type the following commands:

• <add rewrite action <actname> replace “DIAMETER.REQ.AVP(264,\“netscaler.example.net\”)”

For <actname>, substitute a name for your new action. The name can consist of from one to 127
characters in length, and can contain letters, numbers, and the hyphen (-) and underscore (_)
symbols. For NetScaler.example.net, substitute the Host-Origin that you want to use instead of
the original Host-Name.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1488

NetScaler 12.0

• add rewrite policy <polname> “diameter.req.avp(264).value.eq(\“host.example.com\”)”

<actname>
For <polname>, substitute a name for your new policy. As with <actname>, the name can
consist of from one to 127 characters in length, and can contain letters, numbers, and the
hyphen (-) and underscore (_) symbols. For host.example.com, substitute the name of the
Host-Origin that you want to change. For <actname>, substitute the name of the action that
you just created.
• bind lb vserver <vservername> -policyName <polname> -priority <priority> -type REQUEST
For <vservername>, substitute the name of the load balancing virtual server to which you want
to bind the policy. For <polname>, substitute the name of the policy you just created. For
<priority>, substitute a priority for the policy.

Example:

To create a Rewrite action and policy to modify all Diameter Host-Origins of “host.example.com” to
“NetScaler.example.net”, you could add the following action and policy, and bind the policy as shown.

1 > add rewrite action rw_act_replace_avp replace ”diameter.req.avp(264)”

”diameter.new.avp(264,\”netscaler.example.net\”)”
2 > add rewrite policy rw_diam_pol ”diameter.req.avp(264).value.eq(\”
client.realm2.net\”)” rw_act_replace_avp
3 > bind lb vserver vs1 -policyName rw_diam_pol -priority 10 -type
REQUEST
4
5 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

DNS Support for the Rewrite Feature

January 6, 2019

Contributed by:
C

You can configure the rewrite feature to modify DNS requests and responses, as you would for HTTP
or TCP requests and responses. You can use rewrite to manage the flow of DNS requests, and make
necessary modifications in the header, or in the answer section. For example, if the DNS response does

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1489

NetScaler 12.0

not have the AA bit set in the header flag, you can use rewrite to set the AA bit in the DNS response
and send it to the client.

DNS Expressions

In a rewrite configuration, you can use the following NetScaler expressions to refer to various portions
of a DNS request or response:

See Expressions and Descriptions

DNS Bind Points

The following global bind points are available for policies that contain DNS expressions.

Bind Points Description

DNS_REQ_OVERRIDE Override request policy queue.

DNS_REQ_DEFAULT Standard request policy queue.
DNS_RES_OVERRIDE Override response policy queue.
DNS_RES_DEFAULT Standard response policy queue.

In addition to the default bind points, you can create policy labels of type DNS_REQ or DNS_RES and
bind DNS policies to them.

Rewrite Action Types for DNS

• replace_dns_answer_section—This action replaces the DNS answers section with the defined
expression in the DNS policy.
• replace_dns_header_field—Checks the opcode type in the DNS request. Returns True or False,
indicating whether the opcode type in the DNS request matches the specified opcode type. This
action replaces the DNS header section with the defined expression in the DNS policy.

Configuring Rewrite Policies for DNS

The following procedure uses the NetScaler command line to configure a rewrite action and policy
and bind the policy to a rewrite-specific global bind point.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1490

NetScaler 12.0

Configure Rewrite action and policy, and bind the policy for DNS

At the command prompt, type the following commands:

1. add rewrite action <actName> <actType>

For <actname>, substitute a name for your new action. The name can be 1 to 127 characters
in length, and can contain letters, numbers, hyphen (-), and underscore (_) symbols. For
<actType>, specify the rewrite action types provided for DNS expressions.

2. add rewrite policy <polName> <rule> <actName>

For <polname>, substitute a name for your new policy. For <actname>, the name can be 1 to 127
characters in length, and can contain letters, numbers, hyphen (-), and underscore (_) symbols.
For <actname>, substitute the name of the action that you just created.

3. bind rewrite global <polName> <priority> < gotoPriorityExpression> -type <bindPoint>

For <polName>, substitute the name of the policy that you just created. For <priority>, specify
the priority of the policy. For <bindPoint>, substitute one of the rewrite -specific global bind
points.

Example:

Set the AA bit of DNS request to load balance virtual server.

The following commands configure the NetScaler appliance to act as an authoritative DNS server for
all the queries that it serves.

1 add rewrite action set_aa replace_dns_header_field dns.req.header.flags

.set(aa)
2 add rewrite policy pol !dns.req.header.flags.is_set(aa) set_aa
3 bind rewrite global pol 100 -type dns_res_override

Modify the response answer and header section.

If the server responds with an NX domain, you can set the rewrite action to replace the response with
specified IP address. A NOPOLICY-REWRITE enables you to invoke an enternal bank without process-
ing an expression (a rule). This entry is a dummy policy that does not contain a rule but directs the
entry to a policy label or virtual server specific policy banks.

1 add rewrite action set_aa_res replace_dns_header_field ”dns.res.header.

flags.set(aa)”
2 add rewrite action modify_nxdomain_res replace_dns_answer_section ”dns.
new_rrset_a(\”10.102.218.160\”,300)”
3 add rewrite policy set_res_aa true set_aa_res
4 add add rewrite policy modify_answer ”dns.RES.HEADER.RCODE.EQ(nxdomain)
&& dns.RES.QUESTION.TYPE.EQ(A)”

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1491

NetScaler 12.0

5 modify_nxdomain_res
6 add rewrite policylabel MODIFY_NODATA dns_res
7 bind rewrite policylabel MODIFY_NODATA modify_answer 10 END
8 bind rewrite policylabel MODIFY_NODATA set_res_aa 11 END
9 bind lb vserver v1 -policyName NOPOLICY-REWRITE -priority 11 -
gotoPriorityExpression END -type
10 RESPONSE -invoke policylabel MODIFY_NODATA

Limitations:

• Rewrite policies are evaluated only if the NetScaler appliance is configured as a DNS proxy server
and there is a cache miss.
• If the Recursion Available (RA) flag in the header is set to YES, the RA flag will not be modified in
the rewrites.
• If the RA flag in the header is set to YES, the CD flag in the header is modified regardless of any
rewrite action.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

String maps

January 6, 2019

Contributed by:
C

You can use string maps to perform pattern matching in all NetScaler features that use the default
policy syntax. A string map is a NetScaler entity that consists of key-value pairs. The keys and values
are strings in either ASCII or UTF-8 format. String comparison uses two new functions, MAP_STRING()
and IS_STRINGMAP_KEY().

A policy configuration that uses string maps performs better than one that does string matching
through policy expressions, and you need fewer policies to perform string matching with a large
number of key-value pairs. String maps are also intuitive, simple to configure, and result in a smaller
configuration.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1492

NetScaler 12.0

How String Maps Work

String maps are similar in structure to pattern sets (a pattern set defines a mapping of index values
to strings; a string map defines a mapping of strings to strings) and the configuration commands
for string maps (commands such as add, bind, unbind, remove, and show) are syntactically similar
to configuration commands for pattern sets. Also, as with index values in a pattern set, each key
in a string map must be unique across the map. The following table illustrates a string map called
url_string_map, which contains URLs as keys and values.

Key Value

/url_1.html http://www.redirect_url_1.com/url_1
.html
/url_2.html http://www.redirect_url_2.com/url_2
.html
/url_3.html http://www.redirect_url_1.com/url_1
.html

Table 1. String Map “url_string_map”

The following table describes the two functions that have been introduced to enable string matching
with keys in a string map. String matching is always performed with the keys. Additionally, the follow-
ing functions perform a comparison between the keys in the string map and the complete string that
is returned by the expression prefix. The examples in the descriptions refer to the preceding example.

For completed information about the two functions introduced for enabling string matching with keys
in a string map, see String Map Function table pdf.

Configuring a String Map

You first create a string map and then bind key-value pairs to it. You can create a string map from the
command line interface (CLI) or the GUI.

To configure a string map by using the command line interface

At the command prompt, do the following:

1. Create a string map.

add policy stringmap <name> -comment <string>

2. Bind a key-value pair to the string map.

bind policy stringmap <name> <key> <value>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1493

NetScaler 12.0

Example:

1 > bind policy stringmap url_string_map1 ”/url_1.html” ”http://www.

redirect_url_1.com/url_1.html”

To configure a string map by using the GUI

Create a string map and bind the key-value pair to the created entity.

Navigate to AppExpert > String Maps, click Add and specify the relevant details.

Example: responder policy with a redirect action

The following use case involves a responder policy with a redirect action. In the example below, the
first four commands create the string map url_string_map and bind the three key-value pairs used
in the earlier example. After creating the map and binding the key-value pairs, you create a respon-
der action (act_url_redirects) that redirects the client to the corresponding URL in the string map or
to www.default.com. You also configure a responder policy (pol_url_redirects) that checks whether
requested URLs match any of the keys in url_string_map and then performs the configured action.
Finally, you bind the responder policy to the content switching virtual server that receives the client
requests that are to be evaluated.

add stringmap url_string_map

bind stringmap url_string_map /url_1.html http://www.redirect_url_1.com/

url_1.html

bind stringmap url_string_map /url_2.html http://www.redirect_url_2.com/

url_2.html

bind stringmap url_string_map /url_3.html http://www.redirect_url_1.com/

url_1.html

add responder action act_url_redirects redirect ’HTTP.REQ.URL.MAP_STRING(”

url_string_map”)ALT ”www.default.com”’-bypassSafetyCheck yes

add responder policy pol_url_redirects TRUE act_url_redirects

bind cs vserver csw_redirect -policyname pol_url_redirects -priority 1 -

type request

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1494

NetScaler 12.0

URL Sets

September 24, 2018

Contributed by:
C

This feature enables you to blacklist one million URLs. The section includes the following topics:

• Getting Started
• Using Advanced Policy Expressions for URL Evaluation
• Configuring a URL Set
• URL Pattern Semantics
• Blacklisted URL Categories

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Getting Started

September 24, 2018

Contributed by:
C

To prevent access to restricted websites, a NetScaler appliance uses a specialized URL matching al-
gorithm. The algorithm uses a URL set that can contain a list of URLs up to one million (1,000,000)
blacklisted entries. Each entry can include metadata that defines URL categories and category groups
as indexed patterns. The appliance can also periodically download URLs of highly sensitive URL sets
managed by internet enforcement agencies (with government websites) or independent internet or-
ganizations such as the Internet Watch Foundation (IWF). Once the URL set is downloaded from a
website and imported into the appliance, the appliance encrypts the URL sets in the appliance (as
required by these agencies) and kept confidential so that the entries are not tampered.

The NetScaler appliance uses advanced policies to determine whether an incoming URL should be
blocked, allowed, or redirected. These policies use advanced expressions to evaluate incoming URLs
against blacklisted entries. An entry can include metadata. For entries that have no metadata, you
might want to use an expression that evaluates the URL on the basis of an exact string match. For

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1495

NetScaler 12.0

other URLs, you might want to use an expression that evaluates the URL’s metadata, in addition to an
expression that checks for an exact string match.

Use Case for Safe Internet Access Policies for ISPs/Telcos

A URL set enables an Internet Service Provider (ISP) or a Telco customer to enforce government man-
dated safe internet access policies such as:

1. Block access to illegal internet sites (child abuse, drugs, and so on)
2. Safe browsing for children

A NetScaler appliance enables you to periodically download URL sets managed by internet enforce-
ment agencies or independent internet organizations such as IWF (Internet Watch Foundation). The
appliance periodically downloads the list and updates it securely. The list is stored as confidential URL
sets so that it is not tampered or human readable. The periodically downloaded URL set functions as
a blacklisted set for URL evaluation purposes.

If you have a private URL set and the contents of the list are kept confidential and the network ad-
ministrator does not know about the blacklisted URLs present in the list. To make sure if the policy is
configured correctly and the correct list is referenced to evaluate an incoming URL, you configure an
internal URL called Canary URL and add it to the URL set. Using the Canary URL, the administrator can
request through the appliance use the private URL set to ensure it is looked up for every URL request.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Advanced Policy Expressions for URL Evaluation

September 24, 2018

Contributed by:
C

The following table describes the expressions you can use to evaluate incoming URLs with entries in
an URL set.

Note: HTTP.REQ.URL is generalized to be used as <URL expression>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1496

NetScaler 12.0

Expression Operation

<URL expression>.URLSET_MATCHES_ANY Evaluates to TRUE if the URL exactly matches

any entry in the URL set.
<URL expression> The GET_URLSET_METADATA() expression
.GET_URLSET_METADATA(<URLSET>) returns the associated metadata if the URL
exactly matches any pattern within the URL
set. An empty string is returned if there was no
match.
<URL expression>.GET_ Evaluates to TRUE if the matched metadata is
URLSET_METADATA(<URLSET>).EQ(< equal to <METADATA>.
METADATA>
<URL expression>
.GET_URLSET_METADATA(<URLSET>).
TYPECAST_LIST_T(‘,’).GET(0).EQ(<CATEGORY>) Evaluates to TRUE if the matched metadata is
at the beginning of the category. This pattern
can be used to encode separate fields within
metadata, but match only the 1st field.
HTTP.REQ.HOSTNAME.APPEND(HTTP.REQ.URL) Joins the host and URL parameters, which can
then be used as a <URL expression> for
matching.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

Configuring URL Set

September 24, 2018

Contributed by:
C
You can perform the following tasks to configure a URL set and restrict URLs on a NetScaler platform:
1.Import a URL set (download and encrypt it). Importing a URL set in a NetScaler appliance allows you
to download the URL file, adding the file to the appliance, and then encrypting the file. Until you add
the URL set to the system, it will not be visible to the user.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1497

NetScaler 12.0

You can download a set in the following ways:

• Download a URL set once from a specific URL using HTTP and HTTPS supported for the file down-
load.

• Download a URL set using FTP.

• Downloading a URL set periodically, using a scheduler that periodically downloads or imports
URL sets for example, IWF URL set. The time interval is set in seconds for example, *http://
10.29.102.200/urls.txt -interval 3600*.

Sample URL Set without a meta data

http://10.102.145.135/top10k

Sample URL Set with a meta data

http://10.102.145.135/blacklists/audio-video/categorized_av

The imported URL set is further categorized into different categories and category groups in the
database. This is valid only if categories exist in the metadata of the URL set file.

Note: There can be a chance that you might have URL patterns without metadata.

Once you have downloaded the file, it is pushed into the appliance and at this point of interval, you
can update, delete or display file properties. After the file is pushed into the appliance, you can modify
the entries by adding further rows as it remains static.

The imported set is then stored in an encrypted file format on the NetScaler directory. The imported
list contains millions of URL entries. Otherwise, the appliance returns an error message saying that the
value exceeds the limit. If the imported URL set has blacklisted entries with metadata, the metadata
it is detected by the appliance when it is imported.

Once you import a URL set and add it into the appliance, the URL set is available for advanced policies
to identify the correct URL set during incoming URL evaluation. HTTP.REQ.HOSTNAME.APPEND(HTTP.REQ.URL).UR
URL set name>)

2.Updating a URL set on the NetScaler appliance. Once you have pushed the file into the appliance,
at this interval you can manually update a URL file by using command line interface.

3.Exporting a URL set. If you prefer a backup of the URL set, you can export the list of URL patterns
and save a copy of it to a destination URL. Before you export, check whether the URL set is marked as
private. If is marked private, the URL set cannot be exported.

4.Removing a URL set. If you want to delete a URL set of blacklisted entries, you can use the remove
command to delete the URL set from the NetScaler appliance.

5.Displaying a URL set. You can display the properties of a URL set by using the show command.

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1498

NetScaler 12.0

1 show urlset
2
3
4 Name:  top100            PatternCount: 100         Delimiter:  
       RowSeparator:            Interval:  0
5
6  Done

To import a URL set with meta by using the command line interface

At command prompt, type:

1 import urlset <name> [-overwrite] [ ‒ delimiter <character>] [-

rowSeparator <character>] [-url] <url> [-interval <seconds>] [-
privateSet] [-canaryUrl <URL>]

Where,

delimiter is a CSV file record with default value set as 44.

rowSeparator is a CSV file row separator with default value set as 10.

Interval is the time interval in secs, rounded to the nearest 15 minutes at which the update of urlset
occurs.

CanaryURL is a URL used for testing when contents of the urlset is kept confidential.

To show URL set by using the command line interface

At the command prompt, type:

1 show urlset <name>

To export an URL set by using the command line interface

At the command prompt, type:

1 export urlset <name> <url>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1499

NetScaler 12.0

To add an URL set by using the command line interface

At the command prompt, type:

1 add urlset <urlset_name>

To update an URL set by using the command line interface

At the command prompt, type:

1 update urlset <name>

To remove a URL set command by using the command line interface

At the command prompt, type:

1 remove urlset <name>

Example

1 import policy urlset top1k -url http://10.78.79.80/alytra/top1k.csv  -

delimiter ”,” -rowSeparator ”n” -interval 10 -privateSet -overwrite
‒ canaryUrl http://www.in.gr  
2
3 add policy urlset top1k
4
5 update policy urlset top1k
6
7 sh policy urlset
8
9 sh policy urlset top1k
10
11 export policy urlset urlset1 -url http://www.example.com/PUT_file_1
12 import policy urlset top10k -url http://10.102.145.135/top10k -private
13
14 add policy urlset top10k
15
16 update policy urlset top10k
17
18 show policy urlset top10k

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1500

NetScaler 12.0

To import a URL set by using the GUI

Navigate to AppExpert > URL Sets, click Import to download the URL set.

To add a URL set by using the GUI

Navigate to AppExpert > URL Sets, click Add to create a URL set file for the downloaded URL set.

To edit a URL set by using the GUI

Navigate to AppExpert > URL Sets, select a URL set and click Edit to modify.

To Update a URL set by using the GUI

Navigate to AppExpert > URL Sets, select a URL set and click Update URL Set to update URL set with
the latest modifications made to the file.

To Export a URL set by using the GUI

Navigate to AppExpert > URL Sets, select a URL set and click Export URL Set to export the URL patterns
in a set to a destination URL and save it in that location.

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

URL Pattern Semantics

January 6, 2019

Contributed by:
C

The following table shows the URL patterns used for specifying the list of pages you to want to filter.
For example, the pattern, www.example.com/bar will only match the single page www.example.
com/bar. To cover all the pages where the URL starts with www.example.com/bar, you must explic-
itly add a ‘*’ at the end.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1501

NetScaler 12.0

For more information, seee Following is the semantics for a URL pattern to match the metadata map-
ping

1.
2. Citrix ADC
3. NetScaler 12.0
4. AppExpert

URL Categories

September 24, 2018

Contributed by:
C

Following is a list of blacklisted categories.

S.no Blacklisted Categories

1 Illegal Activities
2 Illegal Drugs
3 Medication
4 Marijuana
5 Terrorism/Extremists
6 Weapons
7 Hate/Slander
8 Violence/Suicide
9 Advocacy in general
10 Adult/Porn
11 Nudity
12 Sexual Services
13 Adult Search/Links
14 Hacking/Cracking
15 Malware
16 Remote Proxies

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1502

NetScaler 12.0

S.no Blacklisted Categories

17 Search Engine Caches

18 Translators
19 Dating
20 Weddings/Matrimony
21 Market Rates
22 Online Trading
23 Insurance
24 Financial Products
25 Gambling in general
26 Lottery
27 Online games
28 Games
29 Auctions
30 Shopping/Retail
31 Real Estate
32 IT Online Shopping
33 Web based Chat
34 Instant Messages
35 Web based Mail
36 E-Mail Subscriptions
37 Bulletin Boards
38 IT Bulletin Boards
39 Personal Web Pages/Blogs
40 Downloads
41 Program Downloads
42 Storage Services
43 Streaming Media
44 Employment
45 Career Advancement

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1503

NetScaler 12.0

S.no Blacklisted Categories

46 Side Business
47 Grotesque
48 Special Events
49 Popular Topics
50 Adult Magazine/News
51 Smoking
52 Drinking
53 Alcoholic Products
54 Fetish
55 Sexual Expression(text)
56 Costume Play/Enjoyment
57 Occult
58 Home & Family
59 Professional Sports
60 Sports in general
61 Life Events
62 Travel & Tourism
63 Public Agency Tourism
64 Public Transit
65 Accommodations
66 Music
67 Horoscope/Astrology/Fortune Telling
68 Entertainer/Celebrity
69 Dining/Gourmet
70 Entertainment/Venues/Activities
71 Traditional Religions
72 Religions
73 Politics
74 Advertisements/Banners

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1504

NetScaler 12.0

S.no Blacklisted Categories

75 Sweepstakes/Prizes
76 SPAM
77 News
78 Automotive
79 Business & Commercial
80 Computing & Internet
81 Education
82 Government
83 Health
84 Internet Telephony
85 Military
86 Peer to Peer/Torrents
87 Recreation & Hobbies
88 Reference
89 Search Engines & Portals
90 Sex Education
91 SMS & Mobile Telephony Services
92 Mobile Apps & Publishers
93 Spyware
94 Content Delivery Networks & Infrastructure
95 Kids Sites
96 Swimsuits & Lingerie
97 Arts & Cultural Events
98 Hosting Sites
99 Philanthropy & Non-Profit Organizations
100 Photo Search & Photo Sharing Sites
101 Ringtones
102 Fashion & Beauty
103 Mobile App Stores

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1505

NetScaler 12.0

S.no Blacklisted Categories

104 Parked Domains

105 Emoticons
106 Mobile Operators
107 Botnets
108 Infected Sites
109 Phishing Sites
110 Keyloggers
111 Mobile Malware
112 No Content
113 Agriculture
114 Architecture
115 Associations/Trade Groups/Unions
116 Books/eBooks
117 BOT Phone Home
118 DDNS
119 Unsupported URL
120 Law
121 Local Communities
122 Miscellaneous
123 Online Magazines
124 Pets/Veterinarian
125 Piracy & Copyright Theft
126 Private IP Addresses
127 Recycling/Environment
128 Science
129 Society & Culture
130 Transport Services & Freight
131 Photography & Film
132 Museums & History

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1506

NetScaler 12.0

S.no Blacklisted Categories

133 eLearning
134 Social Networks in General
135 Facebook
136 Facebook: Posting
137 Facebook: Commenting
138 Facebook: Friends
139 Facebook: Photo Upload
140 Facebook: Events
141 Facebook: Apps
142 Facebook: Chat
143 Facebook: Questions
144 Facebook: Video Upload
145 Facebook: Groups
146 Facebook: Games
147 LinkedIn
148 LinkedIn: Updates
149 LinkedIn: Mail
150 LinkedIn: Connections
151 LinkedIn: Jobs
152 Twitter
153 Twitter: Posting
154 Twitter: Mail
155 Twitter: Follow
156 YouTube
157 YouTube: Commenting
158 YouTube: Video Upload
159 YouTube: Sharing
160 Instagram
161 Instagram: Upload

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1507

NetScaler 12.0

S.no Blacklisted Categories

162 Instagram: Commenting

163 Instagram: Private Message
164 Tumblr
165 Tumblr: Posting
166 Tumblr: Commenting
167 Tumblr: Photo or Video Upload
168 Google+
169 Google+: Posting
170 Google+: Commenting
171 Google+: Photo Upload
172 Google+: Video Upload
173 Google+: Video Chat
174 Pinterest
175 Pinterest: Pin
176 Vine: Upload
177 Vine: Commenting
178 Vine: Message
179 Ask.fm
180 Ask.fm: Ask
181 Ask.fm: Answer
182 YikYak
183 YikYak: Posting
184 YikYak: Commenting
185 Wordpress
186 Wordpress: Posting
187 Wordpress: Upload

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1508

NetScaler 12.0

AppFlow

March 11, 2019

Contributed by:
C
The NetScaler appliance is a central point of control for all application traffic in the data center. It col-
lects flow and user-session level information valuable for application performance monitoring, analyt-
ics, and business intelligence applications. It also collects web page performance data and database
information. AppFlow transmits the information by using the Internet Protocol Flow Information eX-
port (IPFIX) format, which is an open Internet Engineering Task Force (IETF) standard defined in RFC
5101. IPFIX (the standardized version of Cisco’s NetFlow) is widely used to monitor network flow infor-
mation. AppFlow defines new Information Elements to represent application-level information, web
page performance data, and database information.
Using UDP as the transport protocol, AppFlow transmits the collected data, called flow records, to one
or more IPv4 collectors. The collectors aggregate the flow records and generate real-time or historical
reports.
AppFlow provides visibility at the transaction level for HTTP, SSL, TCP, SSL_TCP, and HDX Insight flows.
You can sample and filter the flow types that you want to monitor.
Note

For more information on HDX Insight, see HDX Insight.

AppFlow use actions and policies to send records for a selected flow to specific set of collectors. An
AppFlow action specifies which set of collectors will receive the AppFlow records. Policies, which are
based on Advanced expressions can be configured to select flows for which flow records will be sent
to the collectors specified by the associated AppFlow action.
To limit the types of flows, you can enable AppFlow for a virtual server. AppFlow can also provide
statistics for the virtual server.
You can also enable AppFlow for a specific service, representing an application server, and monitor
the traffic to that application server.
Note

This feature is supported only on NetScaler nCore builds.

How AppFlow Works

In the most common deployment scenario, inbound traffic flows to a Virtual IP address (VIP) on the
NetScaler appliance and is load balanced to a server. Outbound traffic flows from the server to a

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1509

NetScaler 12.0

mapped or subnet IP address on the NetScaler and from the VIP to the client. A flow is a unidirectional
collection of IP packets identified by the following five tuples: sourceIP, sourcePort, destIP, destPort,
and protocol.

The following figure describes how the AppFlow feature works.

Figure 1. NetScaler Flow Sequence

As shown in the figure, the network flow identifiers for each leg of a transaction depend on the direc-
tion of the traffic.

The different flows that form a flow record are:

Flow1: <Client-IP, Client-Port, VIP-IP, VIP-port, Protocol>

Flow2: <NS-MIP/SNIP, NS-port, Server-IP, Server-Port, Protocol>

Flow3: <Server-IP, Server-Port, NS-MIP/SNIP, NS-Port, Protocol>

Flow4: <VIP-IP, VIP-port, Client-IP, Client-Port, Protocol>

To help the collector link all four flows in a transaction, AppFlow adds a custom transactionID element
to each flow. For application-level content switching, such as HTTP, it is possible for a single client
TCP connection to be load balanced to different backend TCP connections for each request. AppFlow
provides a set of records for each transaction.

This topic includes the following details:

• Flow Records
• Templates

Flow Records

AppFlow records contain standard NetFlow or IPFIX information, such as time stamps for the begin-
ning and end of a flow, packet count, and byte count. AppFlow records also contain application-level
information (such as HTTP URLs, HTTP request methods and response status codes, server response
time, and latency), web page performance data (such as page load time, page render time, and time
spent on the page), and database information (such as database protocol, database response status
and database response size). IPFIX flow records are based on templates that need to be sent before
sending flow records.

Templates

AppFlow defines a set of templates, one for each type of flow. Each template contains a set of stan-
dard Information Elements (IEs) and Enterprise-specific Information Elements (EIEs). IPFIX templates

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1510

NetScaler 12.0

define the order and sizes of the Information Elements (IE) in the flow record. The templates are sent
to the collectors at regular intervals, as described in RFC 5101.

A template can include the following EIEs:

• transactionID

An unsigned 32-bit number identifying an application-level transaction. For HTTP, this corre-
sponds to a request and response pair. All flow records that correspond to this request and
response pair have the same transaction ID. In the most common case, there are four uniflow
records that correspond to this transaction. If the NetScaler generates the response by itself
(served from the integrated cache or by a security policy), there may be only two flow records
for this transaction.

• connectionID

An unsigned 32-bit number identifying a layer-4 connection (TCP or UDP). The NetScaler flows
are usually bidirectional, with two separate flow records for each direction of the flow. This
information element can be used to link the two flows.

For the NetScaler, connectionID is an identifier for the connection data structure to track the
progress of a connection. In an HTTP transaction, for instance, a given connectionID may have
multiple transactionID elements corresponding to multiple requests that were made on that
connection.

• tcpRTT

The round trip time, in milliseconds, as measured on the TCP connection. This can be used as
a metric to determine the client or server latency on the network.

• httpRequestMethod

An 8-bit number indicating the HTTP method used in the transaction. An options template with
the number-to-method mapping is sent along with the template.

• httpRequestSize

An unsigned 32-bit number indicating the request payload size.

• httpRequestURL

The HTTP URL requested by the client.

• httpUserAgent

The source of incoming requests to the Web server.

• httpResponseStatus

An unsigned 32-bit number indicating the response status code.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1511

NetScaler 12.0

• httpResponseSize

An unsigned 32-bit number indicating the response size.

• httpResponseTimeToFirstByte

An unsigned 32-bit number indicating the time taken to receive the first byte of the response.

• httpResponseTimeToLastByte

An unsigned 32-bit number indicating the time taken to receive the last byte of the response.

• flowFlags

An unsigned 64-bit flag used to indicate different flow conditions.

EIEs for web page performance data

• clientInteractionStartTime

Time at which the browser receives the first byte of the response to load any objects of the page
such as images, scripts, and stylesheets.

• clientInteractionEndTime

Time at which the browser received the last byte of response to load all the objects of the page
such as images, scripts, and stylesheets.

• clientRenderStartTime

Time at which the browser starts to render the page.

• clientRenderEndTime

Time at which browser finished rendering the entire page, including the embedded objects.

EIEs for database information

• dbProtocolName

An unsigned 8-bit number indicating the database protocol. Valid values are 1 for MS SQL and 2
for MySQL.

• dbReqType

An unsigned 8-bit number indicating the database request method used in the transaction. For
MS SQL, valid values are 1 is for QUERY, 2 is for TRANSACTION, and 3 is for RPC. For valid values
for MySQL, see the MySQL documentation.

• dbReqString

Indicates the database request string without the header.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1512

NetScaler 12.0

• dbRespStatus

An unsigned 64-bit number indicating the status of the database response received from the
web server.

• dbRespLength

An unsigned 64-bit number indicating the response size.

• dbRespStatString

The response status string received from the web server.

1.
2. Citrix ADC
3. NetScaler 12.0

Configuring the AppFlow Feature

January 10, 2019

Contributed by:
C

You configure AppFlow in the same manner as most other policy-based features. First, you enable the
AppFlow feature. Then you specify the collectors to which the flow records are sent. After that, you
define actions, which are sets of configured collectors. Then you configure one or more policies and
associate an action to each policy. The policy tells the Citrix ADC appliance to select requests the flow
records of which are sent to the associated action. Finally, you bind each policy either globally or to
specific vservers to put it into effect.

You can further set AppFlow parameters to specify the template refresh interval and to enable the
exporting of httpURL, httpCookie, and httpReferer information. On each collector, you must specify
the Citrix ADC IP address as the address of the exporter.

Note: For information about configuring the Citrix ADC as an exporter on the collector, see the docu-
mentation for the specific collector.

The configuration utility provides tools that help users define the policies and actions that determine
exactly how the Citrix ADC appliance export records for a particular flow to a set of collectors(action.)
The command line interface provides a corresponding set of CLI-based commands for experienced
users who prefer a command line.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1513

NetScaler 12.0

Enabling AppFlow

To be able to use the AppFlow feature, you must first enable it.

Note: AppFlow can be enabled only on nCore Citrix ADC appliances.

To enable the AppFlow feature by using the command line interface

At the command prompt, type one of the following commands:

1 enable ns feature AppFlow

To enable the AppFlow feature by using the configuration utility

Navigate to System > Settings, click Configure Advanced Features and select the AppFlow option.

Specifying a Collector

A collector receives AppFlow records generated by the Citrix ADC appliance. To send the AppFlow
records, you must specify at least one collector. By default, the collector listens to IPFIX messages on
UDP port 4739. You can change the default port, when configuring the collector. Similarly, by default,
NSIP is used as the source IP for appflow traffic. You can change this default source IP to a SNIP or MIP
address when configuring a collector. You can also remove unused collectors.

To specify a collector by using the command line interface

At the command prompt, type the following commands to add a collector and verify the configuration:

1 add appflow collector <name> -IPAddress <ipaddress> -port <port_number>

-netprofile <netprofile_name>
2
3 show appflow collector <name>

Example

1 add appflow collector col1 -IPaddress 10.102.29.251 -port 8000 -

netprofile n2

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1514

NetScaler 12.0

To specify multiple collectors by using the command line interface

At the command prompt, type the following commands to add multiple collectors:

1 add appflow collector <collector1> -IPAddress  <IP>

2
3 add appflow collector <collector2> -IPAddress  <IP>
4
5 add appflow action <action> -collectors  <collector1>  <collector2>
6
7 add appflow policy <policy>  true  <action>
8
9 bind lbvserver <lbvserver> -policy <policy> -priority <priority>

To specify one or more collectors by using the configuration utility

Navigate to System > AppFlow > Collectors, and create the AppFlow collector.

Configuring an AppFlow Action

An AppFlow action is a set collectors, to which the flow records are sent if the associated AppFlow
policy matches.

To configure an AppFlow action by using the command line interface

At the command prompt, type the following commands to configure an Appflow action and verify the
configuration:

1 add appflow action <name> --collectors <string> ... [-

clientSideMeasurements (Enabled|Disabled) ] [-comment <string>]
2
3 show appflow action

Example

1 add appflow action apfl-act-collector-1-and-3 -collectors collector-1

collecter-3

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1515

NetScaler 12.0

To configure an AppFlow action by using the configuration utility

Navigate to System > AppFlow > Actions, and create the AppFlow action.

Configuring an AppFlow Policy

After you configure an AppFlow action, you must next configure an AppFlow policy. An AppFlow policy
is based on a rule, which consists of one or more expressions.
Note: For creating and managing AppFlow policies, the configuration utility provides assistance that
is not available at the command line interface.

To configure an AppFlow policy by using the command line interface

At the command prompt, type the following command to add an AppFlow policy and verify the con-
figuration:

1 add appflow policy <name> <rule> <action>

2
3 show appflow policy <name>

Example

1 add appflow policy apfl-pol-tcp-dsprt client.TCP.DSTPORT.EQ(22) apfl-

act-collector-1-and-3

To configure an AppFlow policy by using the configuration utility

Navigate to System > AppFlow > Policies, and create the AppFlow policy.

To add an expression by using the Add Expression dialog box

1. In the Add Expression dialog box, in the first list box choose the first term for your expression.
• HTTP
The HTTP protocol. Choose this if you want to examine some aspect of the request that
pertains to the HTTP protocol.
• SSL
The protected Web site(s). Choose this if you want to examine some aspect of the request
that pertains to the recipient of the request.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1516

NetScaler 12.0

• CLIENT
The computer that sent the request. Choose this if you want to examine some aspect of
the sender of the request.
When you make your choice, the rightmost list box lists appropriate terms for the next part
of your expression.
2. In the second list box, choose the second term for your expression. The choices depend upon
which choice you made in the previous step, and are appropriate to the context. After you
make your second choice, the Help window below the Construct Expression window (which
was blank) displays help describing the purpose and use of the term you just chose.
3. Continue choosing terms from the list boxes that appear to the right of the previous list box,
or typing strings or numbers in the text boxes that appear to prompt you to enter a value, until
your expression is finished.

Binding an AppFlow Policy

To put a policy into effect, you must bind it either globally, so that it applies to all traffic that flows
through the Citrix ADC, or to a specific virtual server, so that the policy applies only to the traffic related
to that virtual server.
When you bind a policy, you assign it a priority. The priority determines the order in which the policies
you define are evaluated. You can set the priority to any positive integer.
In the Citrix ADC operating system, policy priorities work in reverse order—the higher the number, the
lower the priority. For example, if you have three policies with priorities of 10, 100, and 1000, the policy
assigned a priority of 10 is performed first, then the policy assigned a priority of 100, and finally the
policy assigned an order of 1000.
You can leave yourself plenty of room to add other policies in any order, and still set them to evaluate
in the order you want, by setting priorities with intervals of 50 or 100 between each policy when you
globally bind it. You can then add additional policies at any time without having to change the priority
of an existing policy.

To globally bind an AppFlow policy by using the command line interface

At the command prompt, type the following command to globally bind an AppFlow policy and verify
the configuration:

1 bind appflow global <policyName> <priority> [<gotoPriorityExpression [-

type <type>] [-invoke (<labelType> <labelName>)]
2
3 show appflow global

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1517

NetScaler 12.0

Example

1 bind appflow global af_policy_lb1_10.102.71.190 1 NEXT -type

REQ_OVERRIDE -invoke vserver google

To bind an AppFlow policy to a specific virtual server by using the command line interface

At the command prompt, type the following command to bind an appflow policy to a specific virtual
server and verify the configuration:

1 bind lb vserver <name> -policyname <policy_name> -priority <priority>

Example

1 bind lb vserver google -policyname af_policy_google_10.102.19.179 -

priority 251

To globally bind an AppFlow policy by using the configuration utility

Navigate to System > AppFlow, click AppFlow policy Manager and select the relevant Bind Point (De-
fault Global) and Connection Type, and then bind the AppFlow policy.

To bind an AppFlow policy to a specific virtual server by using the configuration utility

Navigate to Traffic Management > Load Balancing > Virtual Servers, select the virtual server, and click
Policies, and bind the AppFlow policy.

Enabling AppFlow for Virtual Servers

If you want to monitor only the traffic through certain virtual servers, enable AppFlow specifically for
those virtual servers. You can enable AppFlow for load balancing, content switching, cache redirec-
tion, SSL VPN, GSLB, and authentication virtual servers.

To enable AppFlow for a virtual server by using the command line interface

At the command prompt, type:

1 set cs vserver <name> <protocol> <IPAddress> <port> -appflowLog ENABLED

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1518

NetScaler 12.0

Example

1 set cs vserver Vserver-CS-1 HTTP 10.102.29.161 80 -appflowLog ENABLED

To enable AppFlow for a virtual server by using the configuration utility

Navigate to Traffic Management > Content Switching > Virtual Servers, select the virtual server, and
enable AppFlow Logging option.

Enabling AppFlow for a Service

You can enable AppFlow for services that are to be bound to the load balancing virtual servers.

To enable AppFlow for a service by using the command line interface

At the command prompt, type:

1 set service <name> -appflowLog ENABLED

Example

1 set service ser -appflowLog ENABLED

To enable AppFlow for a service by using the configuration utility

Navigate to Traffic Management > Load Balancing > Services, select the service, and enable AppFlow
Logging option.

Setting the AppFlow Parameters

You can set AppFlow parameters to customize the exporting of data to the collectors.

To set the AppFlow Parameters by using the command line interface

At the command prompt, type the following commands to set the AppFlow parameters and verify the
settings:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1519

NetScaler 12.0

1 set appflow param [-templateRefresh <secs>] [-appnameRefresh <secs>] [-

flowRecordInterval <secs>] [-udpPmtu <positive_integer>] [-httpUrl (
**ENABLED** | **DISABLED** )] [-httpCookie ( **ENABLED** | **
DISABLED** )] [-httpReferer ( **ENABLED** | **DISABLED** )] [-
httpMethod ( **ENABLED** | **DISABLED** )] [-httpHost ( **ENABLED**
| **DISABLED** )] [-httpUserAgent ( **ENABLED** | **DISABLED** )] [-
httpXForwardedFor ( **ENABLED** | **DISABLED** )][-clientTrafficOnly
( **YES** | **NO**)]
2
3 show appflow Param

Example

1 set appflow Param -templateRefresh 240 -udpPmtu 128 -httpUrl enabled

To set the AppFlow parameters by using the configuration utility

Navigate to System > AppFlow, click Change AppFlow Settings, and specify relevant AppFlow param-
eters.

Example: Configuring AppFlow for DataStream

The following example illustrates the procedure for configuring AppFlow for DataStream using the
command line interface.

1 enable feature appflow

2
3 add db user sa password freebsd
4
5 add lbvserver lb0 MSSQL 10.102.147.97 1433 -appflowLog ENABLED
6
7 add service sv0 10.103.24.132 MSSQL 1433 -appflowLog ENABLED
8
9 bind lbvserver lb0 sv0
10
11 add appflow collector col0 -IPAddress 10.102.147.90
12
13 add appflow action act0 -collectors col0
14
15 add appflow policy pol0 ”mssql.req.query.text.contains(”select”)” act0
16

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1520

NetScaler 12.0

17 bind lbvserver lb0 -policyName pol0 -priority 10

When the Citrix ADC appliance receives a database request, the appliance evaluates the request
against a configured policy. If a match is found, the details are sent to the AppFlow collector
configured in the policy.

1.
2. Citrix ADC
3. NetScaler 12.0

Exporting performance data of web pages to AppFlow collector

January 10, 2019

Contributed by:
C

The EdgeSight Monitoring application provides web page monitoring data with which you can monitor
the performance of various Web applications served in a Citrix ADC environment. You can now export
this data to AppFlow collectors to get an in-depth analysis of the web page applications. AppFlow,
which is based on IPFIX standard, provides more specific information about web application perfor-
mance than does EdgeSight monitoring alone.

You can configure both load balancing and content switching virtual servers to export EdgeSight Mon-
itoring data to AppFlow collectors. Before configuring a virtual server for AppFlow export, associate
an Appflow action with the EdgeSight Monitoring responder policy.

The following web page performance data is exported to AppFlow:

• Page Load Time. Elapsed time, in milliseconds, from when the browser starts to receive the
first byte of a response until the user starts to interact with the page. At this stage, all the page
content might not be loaded.
• Page Render Time.Elapsed time, in milliseconds, from when the browser receives the first byte
of response until either all page content has been rendered or the page load action has timed
out.
• Time Spent on the Page. Time spent by users on a page. Represents the period of time from
one page request to the next one.

AppFlow transmits the performance data by using the Internet Protocol Flow Information eXport (IP-
FIX) format, which is an open Internet Engineering Task Force (IETF) standard defined in RFC 5101.
The AppFlow templates use the following enterprise-specific Information Elements (EIEs) to export
the information:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1521

NetScaler 12.0

• Client Load End Time. Time at which the browser received the last byte of a response to load
all the objects of the page such as images, scripts, and stylesheets.
• Client Load Start Time.Time at which the browser receives the first byte of the response to load
any objects of the page such as images, scripts, and stylesheets.
• Client Render End Time. Time at which browser finished rendering the entire page, including
the embedded objects.
• Client Render Start Time. Time at which the browser started rendering the page.

Prerequisites for Exporting Performance Data of Web Pages to AppFlow Collectors

Before associating the AppFlow action with the AppFlow policy, verify that the following prerequisites
have been met:

• The AppFlow feature has been enabled and configured.

• The Responder feature has been enabled.
• The EdgeSight Monitoring feature has been enabled.
• EdgeSight Monitoring has been enabled on the load balancing or content switching virtual
servers bound to the services of applications for which you want to collect the performance
data.

Associating an AppFlow Action with the EdgeSight Monitoring Responder Policy

To export the web page performance data to the AppFlow collector, you must associate an AppFlow
action with the EdgeSight Monitoring responder policy. An AppFlow action specifies which set of col-
lectors receive the traffic.

To associate an AppFlow action with the EdgeSight Monitoring Responder policy by using the
command line interface

At the command prompt, type:

1 set responder policy <name> -appflowAction <action_Name>

Example

1 set responder policy pol -appflowAction actn

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1522

NetScaler 12.0

To associate an AppFlow action with the EdgeSight Monitoring Responder policy by using the
configuration utility

1. Navigate to AppExpert > Responder > Policies.

2. In the details pane, select an EdgeSight Monitoring responder policy, and then click Open.
3. In the Configure Responder Policy dialog box, in the AppFlow Action drop-down list, select
the AppFlow action associated with the collectors to which you want to send the web-page per-
formance data.
4. Click OK.

Configuring a Virtual Server to Export EdgeSight Statistics to Appflow Collectors

To export EdgeSight statistics information from a virtual server to the AppFlow collector, you must
associate an AppFlow action with the virtual server.

To associate an AppFlow action with a Load Balancing or Content Switching virtual server by
using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Virtual Servers. You can also navigate to
Traffic Management > Content Switching > Virtual Servers.
2. In the details pane, select a virtual server, or multiple virtual servers, and then click Enable
EdgeSight Monitoring.
3. In the Enable EdgeSight Monitoring dialog box, select the Export EdgeSight statistics to
Appflow check box.
4. From the Appflow Action drop-down list, select the AppFlow action. The AppFlow action de-
fines the list of AppFlow collectors to which it exports EdgeSight Monitoring statistics. If you
have selected multiple load balancing virtual servers, the same AppFlow Action will be asso-
ciated with the responder policies bound to them. You can later change the AppFlow Action
configured for each of the selected Load Balancing virtual server individually, if required.
5. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0

Session reliability on NetScaler high availability pair

January 10, 2019

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1523

NetScaler 12.0

Contributed by:
C

When a network disruption or a device failover occurs during an ICA session, session reconnection can
use one of two mechanisms: Session Reliability or Auto Client Reconnect.

Session Reliability, the preferred mode, is a seamless experience for the user. The disruption is barely
noticeable for brief network interruptions.

Auto Client Reconnect, the fallback option, involves restarting the client. This mechanism is disrup-
tive for the user and is not always supported.

Receivers can now reconnect their ICA sessions seamlessly using the ICA Session Reliability feature,
when HDX Insight is enabled.
This feature works both in standalone and in a NetScaler HA pair configuration and even when a
NetScaler failover happens.

Note

• NetScaler appliances should be running on software version 11.1 build 49.16 or later.
• You should not Enable or disable Session Reliability mode when the NetScaler appliances
have active connections.
• Enabling or Disabling the feature when connections are still active causes HDX Insight to
stop parsing those sessions after a failover occurs and result in loss of information about
the sessions.
• Session Reliability on a high availabilty setup is enabled by default for NetScaler software
version 11.1 49.16 or later. Session reliability is supported on a high availability setup only if
both the nodes of the setup run the same build (for example, release 11.1 build 53). In other
words, session reliability is not supported on a high availability setup if both the nodes run
different builds (for example, one node has release 11.1 build 53 whereas the other has re-
lease 11.1 build 56).

To configure Session reliability from NetScaler CLI:

1. At the command line, use the default system administrator credentials to log on to the system.
2. To enable Session Reliability on HA failover, at the prompt, type: set ica parameter EnableSRon-
HAFailover YES
3. To disable Session Reliability on HA failover, at the prompt, type: set ica parameter EnableSRon-
HAFailover NO

To Enable Session reliability on HA failover from NetScaler GUI:

1. In a web browser, type the IP address of the primary NetScaler instance in the HA pair (for ex-
ample, http://192.168.100.1).
2. In User Name and Password, enter the administrator credentials.
3. On the Configuration tab, navigate to System > Settings, and click Change ICA Parameters.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1524

NetScaler 12.0

4. In in the Change ICA parameters section, select Session Reliability on HA Failover.

5. Click OK.

Limitations

• Enabling this feature will result in increased bandwidth consumption which is due to ICA com-
pression being turned off by the feature, and the extra traffic between the primary and sec-
ondary nodes to keep them in sync.
• This feature is supported in Active-Passive mode only. Active-Active mode is not currently sup-
ported.
• When HDX Insight is enabled, and Session Reliability on HA knob is set to NO, only ACR reconnect
mode is supported in NetScaler high availability failover scenario. The HA knob does not disable
Session Reliability if HDX Insight is disabled.

The Session Reconnect Semantics table is as follows:

Session Reconnect Sematics

EnableSRonHAFailover Yes
Status (Default) EnableSRonHAFailover No

HDX Insight Enabled Session reconnect for ICA Session reconnect for ICA
Sessions works Sessions does not work
HDX Insight disabled Session reconnect for ICA Session reconnect for ICA
Sessions works Sessions works

Points to note

• Session Reliability for ICA sessions works out of the box with Gateway.
• Session Reliability for ICA sessions does not work ONLY when both the following conditions
are met:
– HDX Insight is enabled
– EnableSRonHAFailover is set to NO.
• Setting EnableSRonHAFailover knob to either YES or NO does not make any difference,
when HDX Insight is disabled.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1525

NetScaler 12.0

Application Firewall

September 20, 2018

Contributed by:
C

The following topics cover installation and configuration of the Citrix Application Firewall feature.

Introduction An overview of web security and how the Web

App Firewall works.
Configuration How to configure the Web App Firewall to
protect a web site, a web service, or a Web 2.0
site.
Signatures A detailed description of the signatures feature
and how to configure the signatures, add
signatures from a supported vulnerability
scanning tool, and define your own signatures,
with examples.
Overview of Security Checks A detailed description of all of the Web App
Firewall security checks, with configuration
information and examples.
Profiles A description of how profiles are configured
and used in the Web App Firewall.
Policies A description of how policies are used when
configuring the Web App Firewall, with
examples of useful policies.
Imports A description of how the Web App Firewall uses
different types of imported files, and how to
import and export files.
Global Configuration A description of Web App Firewall features that
apply to all profiles, and how to configure
them.
Use Cases Extended examples that demonstrate how to
set up the Web App Firewall to best protect
specific types of more complex web sites and
web services.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1526

NetScaler 12.0

Logs, Statistics, and Reports How to access and use the Web App Firewall
logs, the statistics, and the reports to assist in
configuring the Web App Firewall.

The Citrix Application Firewall offers easy to configure options to meet a wide range of application se-
curity requirements. Web App Firewall profiles, which consist of sets of security checks, can be used
to protect both the requests and the responses by providing deep packet-level inspections. Each pro-
file includes an option to select basic protections or advanced protections. Some protections might
require use of other files. For example, xml validation checks might require WSDL or schema files. The
profiles can also use other files, such as signatures or error objects. These files can be added locally,
or they can be imported ahead of time and saved on the appliance for future use. They can be shared
by multiple profiles.
Profiles work in conjunction with the Web App Firewall policies. Each policy identifies a type of traffic,
and that traffic is inspected for the security check violations specified in the profile that is associated
with the policy. The policies can have different bind points, which determine the scope of the policy.
For example, a policy that is bound to a specific virtual server is invoked and evaluated for only the
traffic flowing through that virtual server. The policies are evaluated in the order of their designated
priorities, and the first one that matches the request or response is applied.
• Quick Deployment of Web App Firewall Protection
You can use the following procedure for quick deployment of Web App Firewall security:
1. Add an appfw profile and select the appropriate type (html, xml, web2.0) for the security
requirements of the application.
2. Select the required level of security (basic or advanced).
3. Add or import the required files, such as signatures or WSDL.
4. Configure the profile to use the files, and make any other necessary changes to the default
settings.
5. Add an appfw policy for this profile.
6. Bind the policy to the target bind point and specify the priority.
• Web App Firewall entities
Following are brief overviews of the Web App Firewall entities. For details, see the Web App
Firewall Guide.
Profile—An Web App Firewall profile specifies what to look for and what to do. It inspects
both the request and the response to determine which potential security violations should be
checked and what actions should be taken when processing a transaction. A profile can pro-
tect an HTML, XML or HTML and XML payload. Depending on the security requirements of the

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1527

NetScaler 12.0

application, you can create either a basic or an advanced profile. A basic profile can protect
against known attacks. If higher security is required, you can deploy an advanced profile to al-
low controlled access to the application resources, blocking zero day attacks. However, a basic
profile can be modified to offer advanced protections, and vice versa. Multiple action choices
(for example, block, log, learn, and transform) are available. Advanced security checks might
use session cookies and hidden form tags for controlling and monitoring the client connections.
Web App Firewall profiles can learn the triggered violations and suggest the relaxation rules.

Basic Protections—A basic profile includes a preconfigured set of Start URL and Deny URL re-
laxation rules. These relaxation rules determine which requests should be allowed and which
should be denied. Incoming requests are matched against these lists and the configured actions
are applied. This allows the user to be able to secure applications with minimal configuration
for relaxation rules. The Start URL rules protect against forceful browsing. Known web server
vulnerabilities that are exploited by hackers can be detected and blocked by enabling a set of de-
fault Deny URL rules. Commonly launched attacks, such as Buffer Overflow, SQL, or Cross-site
scripting can also be easily detected.

Advanced Protections—As the name indicates, advanced protections are used for applications
that have higher security requirements. Relaxation rules are configured to allow access to only
specific data and block the rest. This positive security model mitigates unknown attacks, which
might not be detected by basic security checks. In addition to all the basic protections, an ad-
vanced profile keeps track of a user session by controlling the browsing, checking for cookies,
specifying input requirements for various form fields, and protecting against tampering of forms
or cross-site request forgery attacks. Learning, which observes the traffic and deploys the ap-
propriate relaxations, is enabled by default for many security checks. Although easy to use,
advanced protections require due consideration, because they offer tighter security but also
require more processing and do not allow use of caching, which can affect performance.

Import—Import functionality is useful when Web App Firewall profiles need to use external files,
that is, files hosted on an external or internal web server, or that have to be copied from a local
machine. Importing a file and storing it on the appliance is very useful, especially in situations
where you have to control access to external websites, or where compilation takes a long time,
large files have to be synced across HA deployments, or you can reuse a file by copying it across
multiple devices. For example:

– <WSDLs hosted on external web servers can be imported locally before blocking access to
external websites.
– <Large signature files generated by an external scan tool such as Cenzic can be imported
and precompiled, using schema on the Citrix appliance.
– <A customized HTML or XML error page can be imported from an external web server or
copied from a local file.

Signatures—Signatures are very powerful, because they use pattern matching to detect mali-

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1528

NetScaler 12.0

cious attacks and can be configured to check both the request and the response of a transaction.
They are a preferred option when a customizable security solution is needed. Multiple choices
(for example, block, log, learn, and transform) are available for the action to take when a signa-
ture match is detected. The Web App Firewall has a built-in default signature object consisting of
more than 1,300 signature rules, with an option to get the latest rules by using the auto-update
feature. Rules created by other scan tools can also be imported. The signature object can be
customized by adding new rules, which can work in conjunction with the other security checks
specified in the Web App Firewall profile. A signature rule can have multiple patterns and can
flag a violation only when all the patterns are matched, thereby avoiding false positives. Careful
selection of a literal fastmatch pattern for a rule can significantly optimize processing time.

Policies—Web App Firewall Policies are used to filter and separate the traffic into different types.
This provides the flexibility to implement different levels of security protections for the applica-
tion data. Access to highly sensitive data can be directed to advanced security-check inspec-
tions, while less sensitive data is protected by basic-level security inspections. Policies can also
be configured to bypass security-check inspection for harmless traffic. Higher security requires
more processing, so careful design of the policies can provide desired security along with opti-
mized performance. The priority of the policy determines the order in which it is evaluated, and
its bind point determines the scope of its application.

Highlights

1. <Ability to secure a wide range of applications by protecting different types of data, implement-
ing the right level of security for different resources, and still getting maximum performance.
2. Flexibility to add or modify a security configuration. You can tighten or relax security checks by
enabling or disabling basic and advanced protections.
3. Option to convert an HTML profile to an XML or Web2.0 (HTML+XML) profile and vice-versa, pro-
viding the flexibility to add security for different types of payload.
4. Easily deployed actions to block attacks, monitor them in logs, collect statistics, or even trans-
form some attack strings to render them harmless.
5. Ability to detect attacks by inspecting incoming requests, and to prevent leakage of sensitive
data by inspecting the responses sent by the servers.
6. Capability to learn from the traffic pattern to get recommendations for easily editable relaxation
rules that can be deployed to allow exceptions.
7. Hybrid security model that applies the power of customizable signatures to block attacks that
match specified patterns, and provides the flexibility to use the positive-security-model checks
for basic or advanced security protections.
8. Availability of comprehensive configuration reports, including information about PCI-DSS com-
pliance.

1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1529

NetScaler 12.0

2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

FAQs and Deployment Guide

March 8, 2019

Contributed by:
C

Q: Why is NetScaler App Firewall the preferred choice for securing applications?

**With the following features, the NetScaler App App Firewall offers a comprehensive security solu-
tion:

• Hybrid security model: NetScaler hybrid security model allows you to take advantage of both
a positive security model and a negative security model to come up with a configuration ideally
suited for your applications.
– Positive security model protects against Buffer Overflow, CGI-BIN Parameter Manipula-
tion, Form/Hidden Field Manipulation, Forceful Browsing, Cookie or Session Poisoning,
Broken ACLs, Cross-Site Scripting (XSS), Command Injection, SQL Injection, Error Trigger-
ing Sensitive Information Leak, Insecure Use of Cryptography, Server Misconfiguration,
Back Doors and Debug Options, Rate-Based Policy Enforcement, Well Known Platform Vul-
nerabilities, Zero-Day Exploits, Cross Site Request Forgery (CSRF), and leakage of Credit
Card and other sensitive data.
– Negative security model uses a rich set signatures to protect against L7 and HTTP applica-
tion vulnerabilities. The App Firewall is integrated with several third party scanning tools,
such as those offered by Cenzic, Qualys, Whitehat, and IBM. The built-in XSLT files allow
easy importation of rules, which can be used in conjunction with the native-format Snort
based rules. An auto-update feature gets the latest updates for new vulnerabilities.

The positive security model might be the preferred choice for protecting applications that have a high
need for security, because it gives you the option to fully control who can access what data. You allow
only what you want and block the rest. This model includes a built-in security check configuration,
which is deployable with few clicks. However, keep in mind that the tighter the security, the greater
the processing overhead.

The negative security model might be preferable for customized applications. The signatures allow
you to combine multiple conditions, and a match and the specified action are triggered only when

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1530

NetScaler 12.0

all the conditions are satisfied. You block only what you don’t want and allow the rest. A specific
fast-match pattern in a specified location can significantly reduce processing overhead to optimize
performance. The option to add your own signature rules, based on the specific security needs of
your applications, gives you the flexibility to design your own customized security solutions.

• Request as well as response side detection and protection: You can inspect the incoming
requests to detect any suspicious behavior and take appropriate actions, and you can check
the responses to detect and protect against leakage of sensitive data.

• Rich set of built-in protections for HTML, XML and JSON payloads: The App Firewall offers 19
different security checks. Six of them (such as Start URL and Deny URL) apply to both HTML and
XML data. Five checks (such as Field Consistency and Field Format) are specific to HTML, and
eight (such as XML Format and Web Service Interoperability) are specific to XML payloads. This
feature includes a rich set of actions and options. For example, URL Closure enables you to con-
trol and optimize the navigation through your website, to safeguard against forceful browsing
without having to configure relaxation rules to allow each and every legitimate URL. You have
the option to remove or x-out the sensitive data, such as credit-card numbers, in the response.
Be it SOAP Array attack protection, XML denial of Service (XDoS), WSDL scan prevention, Attach-
ment check, or any number of other XML attacks, you have the comfort of knowing that you have
an ironclad shield protecting your data when your applications are protected by the App Fire-
wall. The signatures allow you to configure rules using XPATH-Expressions to detect violations
in the body as well as the header of a JSON payload.

• GWT: Support for protecting Google Web Toolkit applications to safeguard against SQL, XSS and
Form Field Consistency check violations.

• Java-free, user friendly graphical user interface (GUI): An intuitive GUI and preconfigured
security checks make it easy to deploy security by clicking a few buttons. A wizard prompts and
guides you to create the required elements, such as profiles, policies, signatures, and bindings.
The HTML5 based GUI is free of any Java dependency. It’s performance is significantly better
than that of the older, Java based versions.

• Easy to Use and automatable CLI: Most of the configuration options that are available in GUI
are also available in the command line interface (CLI). The CLI commands can be executed by a
batch file and are easy to automate.

• Support for REST API: The NetScaler NITRO protocol supports a rich set of REST API’s to auto-
mate App Firewall configuration and collect pertinent statistics for ongoing monitoring of secu-
rity violations.

• Learning: The App Firewall’s ability to learn by monitoring traffic to fine tune security is very
user friendly. The learning engine recommends rules, which makes it easy to deploy relaxations
without proficiency in regular expressions.

• RegEx editor support: Regular expression offer an elegant solution to the dilemma of want-

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1531

NetScaler 12.0

ing to consolidate rules and yet optimize search. You can capitalize on the power of regular
expressions to configure URLs, field names, signature patterns, and so on. The rich built-in GUI
RegEx editor offers you a quick reference for the expressions and provides a convenient way to
validate and test your RegEx for accuracy.

• Customized error page: Blocked requests can be redirected to an error URL. You also have
the option to display a customized error object that uses supported variables and Citrix default
syntax (advanced PI expressions) to embed troubleshooting information for the client.

• PCI-DSS, stats, and other violation reports: The rich set of reports makes it easy to meet the
PCI-DSS compliance requirement, gather stats about traffic counters, and view violation reports
for all profiles or just one profile.

• Logging and click-to-rule from log: Detailed logging is supported for native as well as CEF for-
mat. The App Firewall offers you the ability to filter targeted log messages in the syslog viewer.
You can select a log message and deploy a corresponding relaxation rule by a simple click of a
button. You have the flexibility to customize log messages and also have support for generating
web logs. For additional details, see App Firewall Logstopic.

• Include violation logs in trace records: The ability to include log messages in the trace records
makes it very easy to debug unexpected behavior such as reset and block.

• Cloning: The useful Import/Export profile option allows you to clone the security configuration
from one NetScaler appliance to others. Export learned data options make it easy to export
the learned rules to an Excel file. You can then get them reviewed and approved by application
owner before applying them.

• An AppExpert template (a set of configuration settings) can be designed to provide appropriate

protection for your websites. You can simplify and expedite the process of deploying similar
protection on other appliances by exporting these cookie-cutter templates to a template.

For additional details, see AppExpert template topic.

• Sessionless security checks: Deploying sessionless security checks can help you reduce the
memory footprint and expedite the processing.
• Interoperability with other NetScaler features: The App Firewall works seamlessly with other
NetScaler features, such as rewrite, URL transformation, integrated caching, CVPN, and rate lim-
iting.
• Support of PI expressions in policies: You can leverage the power of advanced PI expressions
to design policies to implement different levels of security for different parts of your application.
• Support for IPv6: The App Firewall supports both IPv4 and IPv6 protocols.
• Geolocation based security protection: You have the flexibility of using Citrix default syntax
(PI Expressions) for configuring location based policies, which can be used in conjunction with a
built-in location database to customize firewall protection. You can identify the locations from

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1532

NetScaler 12.0

which malicious requests originate, and enforce the desired level of security-check inspections
for requests that originate from a specific geographical location.
• Performance: Request-side streaming significantly improves performance. As soon as a field
is processed, the resulting data is forwarded to the back end while evaluation continues for the
remaining fields. The improvement in processing time is especially significant when handling
large posts.
• Other security features: The App Firewall has several other security knobs that can help ensure
the security of your data. For example, the Confidential Field lets you block leakage of sensitive
information in the log messages, and Strip HTML Comment allows you to remove the HTML
comments from the response before forwarding it to the client. Field Types can be used to
specify what inputs are allowed in the forms submitted to your application.

Q: What do I need to do to configure App Firewall?

Do the following:

• Add an App Firewall profile and select the appropriate type (html, xml, web2.0) for the security
requirements of the application.
• Select the required level of security (basic or advanced).
• Add or import the required files, such as signatures or WSDL.
• Configure the profile to use the files, and make any other necessary changes to the default set-
tings.
• Add an App Firewall policy for this profile.
• Bind the policy to the target bind point and specify the priority.

Q: How do I know what profile type to choose?

The App Firewall profile offers protection for both HTML and XML payloads. Depending on the need
of your application, you can choose either a HTML profile or XML profile. If your application supports
both HTML and XML data, you can choose a Web2.0 profile.

Q: What is the difference between basic and advanced profiles? How do I decide which
one I need?

The decision to use a basic or an advance profile depends on the security need of your application. A
basic profile includes a preconfigured set of Start URL and Deny URL relaxation rules. These relaxation
rules determine which requests are allowed and which are denied. Incoming requests are matched
with the preconfigured rules, and the configured actions are applied. The user can secure applications
with minimal configuration of relaxation rules. The Start URL rules protect against forceful browsing.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1533

NetScaler 12.0

Known web server vulnerabilities that are exploited by hackers can be detected and blocked by en-
abling a set of default Deny URL rules. Commonly launched attacks, such as Buffer Overflow, SQL, or
Cross-Site Scripting can also be easily detected.

As the name indicates, advanced protections are for applications that have higher security require-
ments. Relaxation rules are configured to allow access to only specific data and block the rest. This
positive security model mitigates unknown attacks, which might not be detected by basic security
checks. In addition to all the basic protections, an advanced profile keeps track of a user session by
controlling the browsing, checking for cookies, specifying input requirements for various form fields,
and protecting against tampering of forms or Cross-Site Request Forgery attacks. Learning, which
observes the traffic and recommends the appropriate relaxations, is enabled by default for many se-
curity checks. Although easy to use, advanced protections require due consideration, because they
offer tighter security but also require more processing. Some advance security checks do not allow
use of caching, which can affect performance.

Keep the following points in mind when deciding whether to use basic or advanced profiles:

• Basic and advanced profiles are just starting templates. You can always modify the basic profile
to deploy advanced security features, and vice versa.
• Advanced security checks require more processing and can affect performance. Unless your
application needs advanced security, you might want to start with a basic profile and tighten
the security as required for your application.
• You do not want to enable all security checks unless your application needs it.

Q: What is a policy? How do I select the bind point and set the priority?

App Firewall policies can help you sort your traffic into logical groups for configuring different levels
of security implementation. Carefully select the bind points for the policies to determine which traffic
is matched against which policy. For example, if you want every incoming request to be checked for
SQL/XSS attacks, you can create a generic policy and bind it globally. Or, if you want to apply more
stringent security checks to the traffic of a virtual server hosting applications that contain sensitive
data, you can bind a policy to that virtual server.

Careful assignment of priorities can enhance the traffic processing. You want to assign higher priori-
ties to more specific policies and lower priorities to generic policies. Note that the higher the number,
the lower the priority. A policy with a priority of 10 is evaluated before a policy that has a priority of
15.

You can apply different levels of security for different kinds of contents, e.g. requests for static objects
like images and text can be by-passed by using one policy and requests for other sensitive contents
can be subjected to a much stringent check by using a second policy.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1534

NetScaler 12.0

Q: How do I go about configuring the rules to secure my application?

The App Firewall makes it very easy to design the right level of security for your web-site. You can have
multiple App Firewall policies, bound to different App Firewall profiles, to implement different levels
of security-check inspections for your applications. You can initially monitor the logs to observe what
security threats are being detected and which violations are being triggered. You can either manually
add the relaxation rules or take advantage of the App Firewall’s recommended learned rules to deploy
the required relaxations to avoid false positives.
The NetScaler App Firewall offers visualizer support in GUI, which makes rule management very easy.
You can easily view all the data on one screen, and take action on several rules with one click. The
biggest advantage of the visualizer is that it recommends regular expressions to consolidate several
rules. You can select a subset of the rules, basing your selection on the delimiter and Action URL.
Visualizer support is available for viewing 1) learned rules and 2) relaxation rules.
1) The visualizer for learned rules offers the option to edit the rules and deploy them as relaxations.
You can also skip (ignore) rules.
2) The visualizer for deployed relaxations offers you the option to add a new rule or edit an existing
one. You can also enable or disable a group of rules by selecting a node and clicking the Enable or
Disable button in the relaxation visualizer.

Q: What are signatures? How do I know which signatures to use?

A signature is an object that can have multiple rules. Each rule consists of one or more patterns that
can be associated with a specified set of actions. The App Firewall has a built-in default signature
object consisting of more than 1,300 signature rules, with an option to get the latest rules by using the
auto-update feature to get protection against new vulnerabilities. Rules created by other scan tools
can also be imported.
Signatures are very powerful because they use pattern matching to detect malicious attacks and can
be configured to check both the request and the response of a transaction. They are a preferred option
when a customizable security solution is needed. Multiple action choices (for example, block, log,
learn, and transform) are available for when a signature match is detected. The default signatures
cover rules to protect different types of applications, such as web-cgi, web-coldfusion, web-frontpage,
web-iis, web-php, web-client, web-activex, web-shell-shock, and web-struts. To match the needs of
your application, you can select and deploy the rules belonging to a specific category.
Signature-usage tips:
• You can just make a copy of the default signature object and modify it to enable the rules you
need and configure the actions you want.
• The signature object can be customized by adding new rules, which can work in conjunction
with other signature rules.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1535

NetScaler 12.0

• The signature rules can also be configured to work in conjunction with the security checks spec-
ified in the App Firewall profile. If a match indicating a violation is detected by a signature as
well as a security check, the more restrictive action is the one that gets enforced.
• A signature rule can have multiple patterns and be configured to flag a violation only when all
the patterns are matched, thereby avoiding false positives.
• Careful selection of a literal fast-match pattern for a rule can significantly optimize processing
time.

Q: Does the App Firewall work with other NetScaler features?

The App Firewall is fully integrated into the NetScaler appliance and works seamlessly with other fea-
tures. You can configure maximum security for your application by using other NetScaler security
features in conjunction with the App Firewall. For example, AAA-TM can be used to authenticate the
user, check the user’s authorization to access the content, and log the accesses, including invalid login
attempts. Rewrite can be used to modify the URL or to add, modify or delete headers, and Respon-
der can be used to deliver customized content to different users. You can define the maximum load
for your website by using Rate Limiting to monitor the traffic and throttle the rate if it is too high.
HTTP Denial-of-Service (DoS) protection can help distinguish between real HTTP clients and mali-
cious DoS clients. You can narrow the scope of security-check inspection by binding the App Firewall
policies to virtual servers, while still optimizing the user experience by using the Load Balancing fea-
ture to manage heavily used applications. Requests for static objects such as images or text can bypass
security check inspection, taking advantage of integrated caching or compression to optimize the
bandwidth usage for such content.

Q: How is the payload processed by the App Firewall and the other NetScaler features?

A diagram showing details of the L7 packet flow in a NetScaler appliance is available in the Processing
Order of Features section at Getting Started topic.

Q: What is the recommended workflow for App Firewall deployment?

Now that you know the advantages of using the state-of-the-art security protections of the NetScaler
App Firewall, you might want to collect additional information that can help you design the optimal
solution for your security needs. Citrix recommends that you do the following:

• Know your environment: Knowing your environment will help you to identify the best secu-
rity protection solution (signatures, security checks, or both) for your needs. Before you begin
configuration, you should gather the following information.
– OS: What kind of OS (MS Windows, Linux, BSD, Unix, others) do you have?

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1536

NetScaler 12.0

– Web Sever: What web server (IIS, Apache or NetScaler Enterprise Server) are you running?
– Application: What type of applications are running on your application server (for exam-
ple, ASP.NET, PHP, Cold Fusion, ActiveX, FrontPage, Struts, CGI, Apache Tomcat, Domino,
and WebLogic)?
– Do you have customized applications or off-the-shelf (for example, Oracle, SAP) applica-
tions? What version you are using?
– SSL: Do you require SSL? If so, what key size (512, 1024, 2048, 4096) is used for signing
certificates?
– Traffic Volume: What is the average traffic rate through your applications? Do you have
seasonal or time-specific spikes in the traffic?
– Server Farm: How many servers do you have? Do you need to use load balancing?
– Database: What type of database (MS-SQL, MySQL, Oracle, Postgres, SQLite, nosql,
Sybase, Informix etc.) do you use?
– DB Connectivity: What kind of data base connectivity do you have (DSN, per-file connec-
tion string, single file connection string) and what drivers are used?
• Identify your security needs: You might want to evaluate which applications or specific data
need maximum security protection, which ones are less vulnerable, and the ones for which se-
curity inspection can safely be bypassed. This will help you in coming up with an optimal config-
uration, and in designing appropriate policies and bind points to segregate the traffic. For exam-
ple, you might want to configure a policy to bypass security inspection of requests for static web
content, such as images, MP3 files, and movies, and configure another policy to apply advanced
security checks to requests for dynamic content. You can use multiple policies and profiles to
protect different contents of the same application.
• License requirement: Citrix offers a unified solution to optimize the performance of your appli-
cation by taking advantage of a rich set of features such as load balancing, content switching,
caching, compression, responder, rewrite, and content filtering, to name a few. Identifying the
features that you want can help you decide which license you need.
• Install and baseline a NetScaler appliance: Create a virtual server and run test traffic through
it to get an idea of the rate and amount of traffic flowing through your system. This information
will help you to identify your capacity requirement and select the right appliance (VPX, MPX, or
SDX).
• Deploy the App Firewall: Use the App Firewall wizard to proceed with a simple security config-
uration. The wizard walks you through several screens and prompts you to add a profile, policy,
signature, and security checks.
– Profile: Select a meaningful name and the appropriate type (HTML, XML or WEB 2.0) for
your profile. The policy and signatures will be auto-generated using the same name.
– Policy: The auto-generated policy has the default Expression (true), which selects all traf-
fic and is bound globally. This is a good starting point unless you have in mind a specific
policy that you want to use.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1537

NetScaler 12.0

– Protections: The wizard helps you take advantage of the hybrid security model, in which
you can use the default signatures offering a rich set of rules to protect different types
of applications. Simple edit mode allows you to view the various categories (CGI, Cold
Fusion, PHP, etc.). You can select one or more categories to identify a specific set of rules
applicable to your application. Use the Action option to enable all the signature rules in
the selected categories. Make sure that blocking is disabled, so that you can monitor the
traffic before tightening the security. Click Continue. In the Specify Deep protections
pane, you can make changes as needed to deploy the security check protections. In most
cases, basic protections are sufficient for initial security configuration. Run the traffic for
a while to collect a representative sample of the security-inspection data.
– Tightening the security: After deploying App Firewall and observing the traffic for a while,
you can start tightening the security of your applications by deploying relaxations and then
enabling blocking. Learning, Visualizer, and Click to deploy rules are useful features
that make it very easy to tweak your configuration to come up with just the right level
of relaxation. At this point, you can also change the policy expression and/or configure
additional policies and profiles to implement desired levels of security for different types
of content.
– Debugging: If you see unexpected behavior of your application, the App Firewall offers
various options for easy debugging:
* Log. If legitimate requests are getting blocked, your first step is to check the ns.log file
to see if any unexpected security-check violation is being triggered.
* Disable feature. If you do not see any violations but are still seeing unexpected be-
havior, such as an application resetting or sending partial responses, you can disable
the App Firewall feature for debugging. If the issue persists, it rules out the App Fire-
wall as a suspect.
* Trace records with log messages. If the issue appears to be App Firewall related and
needs closer inspection, you have the option to include security violation messages in
an nstrace. You can use “Follow TCP stream” in the trace to view the details of the indi-
vidual transaction, including headers, payload, and the corresponding log message,
together on the same screen. Details of how to use this functionality are available at
Appendixes.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1538

NetScaler 12.0

Introduction

September 18, 2018

Contributed by:
C

The NetScaler App App Firewall prevents security breaches, data loss, and possible unauthorized mod-
ifications to web sites that access sensitive business or customer information. It does so by filtering
both requests and responses, examining them for evidence of malicious activity, and blocking those
that exhibit such activity. Your site is protected not only from common types of attacks, but also from
new, as yet unknown attacks. In addition to protecting web servers and web sites from unauthorized
access and misuse by hackers and malicious programs, the App Firewall provides protection against
security vulnerabilities in legacy CGI code or scripts, other web frameworks, web server software, and
the underlying operating systems.

The NetScaler App Firewall is available as a stand-alone appliance, or as a feature on a NetScaler vir-
tual appliance (VPX). In the App Firewall documentation, the term NetScaler refers to the platform on
which the App Firewall is running, regardless of whether that platform is a dedicated firewall appli-
ance, a NetScaler on which other features have also been configured, or a NetScaler VPX.

To use the App Firewall, you must create at least one security configuration to block connections that
violate the rules that you set for your protected web sites. The number of security configurations
that you might want to create depends on the complexity of your web site. In some cases, a single
configuration is sufficient. In other cases, particularly those that include interactive web sites, web
sites that access database servers, online stores with shopping carts, you might need several different
configurations to best protect sensitive data without wasting significant effort on content that is not
vulnerable to certain types of attacks. You can often leave the defaults for the global settings, which
affect all security configurations, unchanged. However, you can change the global settings if they
conflict with other parts of your configuration or you prefer to customize them.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Web application security

September 18, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1539

NetScaler 12.0

Contributed by:
C

Web application security is network security for computers and programs that communicate by using
the HTTP and HTTPS protocols. This is an extremely broad area in which security flaws and weak-
nesses abound. Operating systems on both servers and clients have security issues and are vulnerable
to attack. Web server software and web site enabling technologies such as CGI, Java, JavaScript, PERL
and PHP have underlying vulnerabilities. Browsers and other client applications that communicate
with web-enabled applications also have vulnerabilities. Web sites that use any technology but the
simplest of HTML, including any site that allows interaction with visitors, often have vulnerabilities of
their own.

In the past, a breach in security was often just an annoyance, but today that is seldom the case. For
example, attacks in which a hacker gained access to a web server and made unauthorized modifica-
tions to (defaced) a web site used to be common. They were usually launched by hackers who had
no motivation beyond demonstrating their skills to fellow hackers or embarrassing the targeted per-
son or company. Most current security breaches, however, are motivated by a desire for money. The
majority attempt to accomplish one or both of the following goals: to obtain sensitive and potentially
valuable private information, or to obtain unauthorized access to and control of a web site or web
server.

Certain forms of web attacks focus on obtaining private information. These attacks are often possible
even against web sites that are secure enough to prevent an attacker from taking full control. The in-
formation that an attacker can obtain from a web site can include customer names, addresses, phone
numbers, social security numbers, credit card numbers, medical records, and other private informa-
tion. The attacker can then use this information or sell it to others. Much of the information obtained
by such attacks is protected by law, and all of it by custom and expectation. A breach of this type
can have extremely serious consequences for customers whose private information is compromised.
At best, these customers will have to exercise vigilance to prevent others from abusing their credit
cards, opening unauthorized credit accounts in their name, or appropriating their identities outright
(identity theft). At worst, the customers may face ruined credit ratings or even be blamed for criminal
activities in which they had no part.

Other web attacks are aimed at obtaining control of (or compromising) a web site or the server on
which it operates, or both. A hacker who gains control of a web site or server can use it to host unau-
thorized content, act as a proxy for content hosted on another web server, provide SMTP services to
send unsolicited bulk email, or provide DNS services to support such activities on other compromised
web servers. Most web sites that are hosted on compromised web servers promote questionable or
outright fraudulent businesses. For example, the majority of phishing web sites and child exploitation
web sites are hosted on compromised web servers.

Protecting your web sites and web services against these attacks requires a multilayered defense capa-
ble of both blocking known attacks with identifiable characteristics and protecting against unknown

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1540

NetScaler 12.0

attacks, which can often be detected because they look different from the normal traffic to your web
sites and web services.

Known web attacks

The first line of defense for your web sites is protection against the large number of attacks that are
known to exist and have been observed and analyzed by web security experts. Common types of
attacks against HTML-based web sites include:

• Buffer overflow attacks. Sending an extremely long URL, extremely long cookie, or other ex-
tremely long bit of information to a web server in hopes of causing it or the underlying operating
system to hang, crash, or provide the attacker with access to the underlying operating system. A
buffer overflow attack can be used to gain access to unauthorized information, to compromise
a web server, or both.
• Cookie security attacks. Sending a modified cookie to a web server, usually in hopes of ob-
taining access to unauthorized content by using falsified credentials.
• Forceful browsing. Accessing URLs on a web site directly, without navigating to the URLs by
means of hyperlinks on the home page or other common start URLs on the web site. Individual
instances of forceful browsing may simply indicate a user who bookmarked a page on your web
site, but repeated attempts to access nonexistent content, or content that users should never
access directly, often represent an attack on web site security. Forceful browsing is normally
used to gain access to unauthorized information, but can also be combined with a buffer over-
flow attack in an attempt to compromise your server.
• Web form security attacks. Sending inappropriate content to your web site in a web form. In-
appropriate content can include modified hidden fields, HTML or code in a field intended for
alphanumeric data only, an overly long string in a field that accepts only a short string, an al-
phanumeric string in a field that accepts only an integer, and a wide variety of other data that
your web site does not expect to receive in that web form. A web form security attack can be
used either to obtain unauthorized information from your web site or to compromise the web
site outright, usually when combined with a buffer overflow attack.

Two specialized types of attacks on web form security deserve special mention:

• SQL injection attacks. Sending an active SQL command or commands in a web form or as part
of a URL, with the goal of causing an SQL database to execute the command or commands. SQL
injection attacks are normally used to obtain unauthorized information.
• Cross-site scripting attacks. Using a URL or a script on a web page to violate the same-origin
policy, which forbids any script from obtaining properties from or modifying any content on
a different web site. Since scripts can obtain information and modify files on your web site,
allowing a script access to content on a different web site can provide an attacker the means to
obtain unauthorized information, to compromise a web server, or both.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1541

NetScaler 12.0

Attacks against XML-based web services normally fall into at least one of the following two categories:
attempts to send inappropriate content to a web service, or attempts to breach security on a web
service. Common types of attacks against XML-based web services include:

• Malicious code or objects. XML requests that contain code or objects that can either directly
obtain sensitive information or can give an attacker control of the web service or underlying
server.
• Badly-formed XML requests. XML requests that do not conform to the W3C XML specification,
and that can therefore breach security on an insecure web service
• Denial of service (DoS) attacks. XML requests that are sent repeatedly and in high volume,
with the intent of overwhelming the targeted web service and denying legitimate users access
to the web service.

In addition to standard XML-based attacks, XML web services and Web 2.0 sites are also vulnerable to
SQL injection and cross-site scripting attacks, as described below:

• SQL injection attacks. Sending an active SQL command or commands in an XML-based re-
quest, with the goal of causing an SQL database to execute that command or commands. As
with HTML SQL injection attacks, XML SQL injection attacks are normally used to obtain unau-
thorized information.
• Cross-site scripting attacks. Using a script included in an XML based application to violate
the same-origin policy, which does not allow any script to obtain properties from or modify any
content on a different application. Since scripts can obtain information and modify files by using
your XML application, allowing a script access to content belonging to a different application can
give an attacker the means to obtain unauthorized information, to compromise the application,
or both

Known web attacks can usually be stopped by filtering web site traffic for specific characteristics (sig-
natures) that always appear for a specific attack and should never appear in legitimate traffic. This
approach has the advantages of requiring relatively few resources and posing relatively little risk of
false positives. It is therefore a valuable tool in fighting attacks on web sites and web services, and
configuring basic signature protections that intercept most known web attacks is easy to do.

Unknown web attacks

The greatest threat against web sites and applications does not come from known attacks, but from
unknown attacks. Most unknown attacks fall into one of two categories: newly-launched attacks for
which security firms have not yet developed an effective defense (zero-day attacks), and carefully-
targeted attacks on a specific web site or web service rather than many web sites or web services
(spear attacks). These attacks, like known attacks, are usually intended to obtain sensitive private
information, compromise the web site or web service and allow it to be used for further attacks, or
both of those goals.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1542

NetScaler 12.0

Zero-day attacks are a major threat to all users. These attacks are usually of the same types as known
attacks; zero-day attacks often involve injected SQL, a cross-site script, a cross-site request forgery, or
another type of attack similar to known attacks. In most cases, they target vulnerabilities that the de-
velopers of the targeted software, web site, or web service either are unaware of or have just learned
about. Security firms have therefore usually not developed defenses against these attacks, and even
if they have, users have usually not obtained and installed the patches or performed the workarounds
necessary to protect against these attacks. The time between discovery of a zero-day attack and avail-
ability of a defense (the vulnerability window) is shrinking, but perpetrators can still count on hours
or even days in which many web sites and web services lack any specific protection against the attack.

Spear attacks are a major threat, but to a more select group of users. A common type of spear attack,
a spear phish, is usually targeted at customers of a specific bank or financial institution, or (less com-
monly) at employees of a specific company or organization. Unlike other phishes, which are often
crudely written forgeries that a user with any familiarity with the actual communications of that bank
or financial institution can recognize, spear phishes are letter perfect and extremely convincing. They
can contain information specific to the individual that, at first look, no stranger should know or be able
to obtain. The spear phisher is therefore able to convince his or her target to provide the requested in-
formation, which the phisher can then use to loot accounts, to process illegitimately obtained money
from other sources, or to gain access to other, even more sensitive information.

Both of these types of attack have certain characteristics that can usually be detected, although not
by using static patterns that look for specific characteristics, as do standard signatures. Detecting
these types of attacks requires more sophisticated and more resource-intensive approaches, such as
heuristic filtering and positive security model systems. Heuristic filtering looks, not for specific pat-
terns, but for patterns of behaviors. Positive security model systems model the normal behavior of
the web site or web service that they are protecting, and then block connections that do not fit within
that model of normal use. URL based and web-form based security checks profile normal use of your
web sites, and then control how users interact with your web sites, using both heuristics and posi-
tive security to block anomalous or unexpected traffic. Both heuristic and positive security, properly
designed and deployed, can catch most attacks that signatures miss. However, they require consid-
erably more resources than do signatures, and you must spend some time configuring them properly
to avoid false positives. They are therefore usually used, not as the primary line of defense, but as
backups to signatures or other less resource-intensive approaches.

By configuring these advanced protections in addition to signatures, you create a hybrid security
model, which enables the App Firewall to provide comprehensive protection against both known and
unknown attacks.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1543

NetScaler 12.0

How App Firewall works

January 6, 2019

Contributed by:
C

When you install the App Firewall, you create an initial security configuration, which consists of a pol-
icy, a profile, and a signatures object. The policy is a rule that identifies the traffic to be filtered, and
the profile identifies the patterns and types of behavior to allow or block when the traffic is filtered.
The simplest patterns, which are called signatures, are not specified within the profile, but in a signa-
tures object that is associated with the profile.

A signature is a string or pattern that matches a known type of attack. The App Firewall contains over a
thousand signatures in seven categories, each directed at attacks on specific types of web servers and
web content. Citrix updates the list with new signatures as new threats are identified. During configu-
ration, you specify the signature categories that are appropriate for the web servers and content that
you need to protect. Signatures provide good basic protection with low processing overhead. If your
applications have special vulnerabilities or you detect an attack against them for which no signature
exists, you can add your own signatures.

The more advanced protections are called security checks. A security check is a more rigorous, algo-
rithmic inspection of a request for specific patterns or types of behavior that might indicate an attack
or constitute a threat to your protected web sites and web services. It can, for example, identify a re-
quest that attempts to perform a certain type of operation that might breach security, or a response
that includes sensitive private information such as a social security number or credit card number.
During configuration, you specify the security checks that are appropriate for the web servers and con-
tent that you need to protect. The security checks are restrictive. Many of them can block legitimate
requests and responses if you do not add the appropriate exceptions (relaxations) when configuring
them. Identifying the needed exceptions is not difficult if you use the adaptive learning feature, which
observes normal use of your web site and creates recommended exceptions.

The App Firewall can be installed as either a Layer 3 network device or a Layer 2 network bridge be-
tween your servers and your users, usually behind your company’s router or firewall. It must be in-
stalled in a location where it can intercept traffic between the web servers that you want to protect
and the hub or switch through which users access those web servers. You then configure the network
to send requests to the App Firewall instead of directly to your web servers, and responses to the App
Firewall instead of directly to your users. The App Firewall filters that traffic before forwarding it to
its final destination, using both its internal rule set and your additions and modifications. It blocks
or renders harmless any activity that it detects as harmful, and then forwards the remaining traffic to
the web server. The following figure provides an overview of the filtering process.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1544

NetScaler 12.0

Note:
The figure omits the application of a policy to incoming traffic. It illustrates a security configura-
tion in which the policy is to process all requests. Also, in this configuration, a signatures object
has been configured and associated with the profile, and security checks have been configured
in the profile.

Figure 1. A Flowchart of App Firewall filtering

As the figure shows, when a user requests a URL on a protected web site, the App Firewall first exam-
ines the request to ensure that it does not match a signature. If the request matches a signature, the
App Firewall either displays the error object (a web page that is located on the App Firewall appliance
and which you can configure by using the imports feature) or forwards the request to the designated
error URL (the error page). Signatures do not require as many resources as do security checks, so
detecting and stopping attacks that are detected by a signature before running any of the security
checks reduces the load on the server.

If a request passes signature inspection, the App Firewall applies the request security checks that have
been enabled. The request security checks verify that the request is appropriate for your web site or
web service and does not contain material that might pose a threat. For example, security checks
examine the request for signs indicating that it might be of an unexpected type, request unexpected
content, or contain unexpected and possibly malicious web form data, SQL commands, or scripts.
If the request fails a security check, the App Firewall either sanitizes the request and then sends it
back to the NetScaler appliance (or NetScaler virtual appliance), or displays the error object. If the
request passes the security checks, it is sent back to the NetScaler appliance, which completes any
other processing and forwards the request to the protected web server.

When the web site or web service sends a response to the user, the App Firewall applies the response
security checks that have been enabled. The response security checks examine the response for leaks
of sensitive private information, signs of web site defacement, or other content that should not be
present. If the response fails a security check, the App Firewall either removes the content that should
not be present or blocks the response. If the response passes the security checks, it is sent back to
the NetScaler appliance, which forwards it to the user.

App Firewall features

The basic App Firewall features are policies, profiles, and signatures, which provide a hybrid security
model as described in “Known Web Attacks,” “Unknown Web Attacks,” and “How the App Firewall
Works.” Of special note is the learning feature, which observes traffic to your protected applications
and recommends appropriate configuration settings for certain security checks.

The imports feature manages files that you upload to the App Firewall. These files are then used by the
App Firewall in various security checks, or when responding to a connection that matches a security

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1545

NetScaler 12.0

check.

You can use the logs, statistics, and reports features to evaluate the performance of the App Firewall
and identify possible needs for additional protections.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

The App Firewall configuration interfaces

January 6, 2019

Contributed by:
C

All hardware and virtual versions of the NetScaler can be configured and managed from the NetScaler
command line interface or the web-based GUI. All features of most NetScaler features can be con-
figured using either of these tools. The NetScaler App Firewall is an exception: not all App Firewall
configuration tasks can be performed at the command line. Inexperienced users also find the GUI eas-
ier to use. In particular, the App Firewall wizard considerably reduces the complexity of configuring
the App Firewall. Unlike most NetScaler wizards, the App Firewall wizard can serve as your primary
interface to the App Firewall.

The command line interface is a modified UNIX shell based on the FreeBSD bash shell. To configure the
App Firewall from the command line interface, you type commands at the prompt and press the Enter
key, just as you do with any other Unix shell. For instructions for using the command line interface,
see [Command Reference](https://developer-docs.citrix.com/projects/netscaler-
command-reference/en/12.0/appfw/application-firewall-commands/).

The GUI is a web-based GUI interface to the appliance. The App Firewall configuration section is found
under Security > App Firewall. Figure 1 shows the navigation pane expanded to display the App Fire-
wall screens, and in the detail pane the main ![App Firewall screen].
(/en-us/netscaler/media/cu-screenshot-labeled.png)

The GUI has two main areas on all screens. The panel on the left, called the navigation pane, contains
a navigation tree, with which you navigate to the screens on which you configure the features that are
installed on your appliance. The screens to which you navigate appear to the right of the navigation
pane, in the details pane.

When you access the GUI, the details pane displays the System Overview screen. If, in the navigation
pane, you click plus sign next to the App Firewall folder, the App Firewall node expands to include the

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1546

NetScaler 12.0

main App Firewall elements that you can configure. If you click the first element, Profiles, the details
pane displays the configured profiles, if any profiles have been configured. At the bottom of the details
pane, you can click Add to configure a new profile. Other buttons at the bottom of the details pane are
grayed out until you select an existing profile. Screens for the other elements work in the same way.

If, instead of expanding the App Firewall node, you click the node itself, the details pane displays dif-
ferent options, one of which is the App Firewall wizard, as shown in Figure 1. Citrix recommends that
you use the wizard for initial configuration, and many users use it almost exclusively. It includes most
of the functionality that is available elsewhere in the GUI.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Configuring the App Firewall

September 18, 2018

Contributed by:
C

You can configure the NetScaler App Firewall by using any of the following methods:

• App Firewall Wizard. A dialog box consisting of a series of screens that step you through the
configuration process.
• NetScaler App Interface AppExpert Template. A NetScaler AppExpert template (a set of con-
figuration settings) that are designed to provide appropriate protection for web sites. This App-
Expert template contains appropriate App Firewall configuration settings for protecting many
web sites.
• NetScaler GUI. The NetScaler web-based configuration interface.
• NetScaler Command Line Interface. The NetScaler command line configuration interface.

Citrix recommends that you use the App Firewall Wizard. Most users will find it the easiest method to
configure the App Firewall, and it is designed to prevent mistakes. If you have a new NetScaler or VPX
that you will use primarily to protect web sites, you may find the Web Interface AppExpert template a
better option because it provides a good default configuration, not just for the App Firewall, but for the
entire appliance. Both the GUI and the command line interface are intended for experienced users,
primarily to modify an existing configuration or use advanced options.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1547

NetScaler 12.0

The App Firewall wizard

The App Firewall wizard is a dialog box that consists of several screens that prompt you to configure
each part of a simple configuration. The App Firewall then creates the appropriate configuration ele-
ments from the information that you give it. This is the simplest and, for most purposes, the best way
to configure the App Firewall.

To use the wizard, connect to the GUI with the browser of your choice. When the connection is estab-
lished, verify that the App Firewall is enabled, and then run the App Firewall wizard, which prompts
you for configuration information. You do not have to provide all of the requested information the first
time you use the wizard. Instead, you can accept default settings, perform a few relatively straight-
forward configuration tasks to enable important features, and then allow the App Firewall to collect
important information to help you complete the configuration.

For example, when the wizard prompts you to specify a rule for selecting the traffic to be processed,
you can accept the default, which selects all traffic. When it presents you with a list of signatures, you
can enable the appropriate categories of signatures and turn on the collection of statistics for those
signatures. For this initial configuration, you can skip the advanced protections (security checks). The
wizard automatically creates the appropriate policy, signatures object, and profile (collectively, the
security configuration), and binds the policy to global. The App Firewall then begins filtering connec-
tions to your protected websites, logging any connections that match one or more of the signatures
that you enabled and collecting statistics about the connections that each signature matches. After
the App Firewall processes some traffic, you can run the wizard again and examine the logs and statis-
tics to see if any of the signatures that you have enabled are matching legitimate traffic. After deter-
mining which signatures are identifying the traffic that you want to block, you can enable blocking
for those signatures. If your website or web service is not complex, does not use SQL, and does not
have access to sensitive private information, this basic security configuration will probably provide
adequate protection.

You may need additional protection if, for example, your website is dynamic. Content that uses scripts
may need protection against cross-site scripting attacks. Web content that uses SQL—such as shop-
ping carts, many blogs, and most content management systems—may need protection against SQL
injection attacks. Websites and web services that collect sensitive private information such as social
security numbers or credit card numbers may require protection against unintentional exposure of
that information. Certain types of web-server or XML-server software may require protection from
types of attacks tailored to that software. Another consideration is that specific elements of your web-
sites or web services may require different protection than do other elements. Examining the App
Firewall logs and statistics can help you identify the additional protections that you might need.

After deciding which advanced protections are needed for your websites and web services, you can
run the wizard again to configure those protections. Certain security checks require that you enter ex-
ceptions (relaxations) to prevent the check from blocking legitimate traffic. You can do so manually,

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1548

NetScaler 12.0

but it is usually easier to enable the adaptive learning feature and allow it to recommend the neces-
sary relaxation. You can use the wizard as many times as necessary to enhance your basic security
configuration and/or create additional security configurations.
The wizard automates some tasks that you would have to perform manually if you did not use the
wizard. It automatically creates a policy, a signatures object, and a profile, and assigns them the name
that you provided when you were prompted for the name of your configuration. The wizard also adds
your advanced-protection settings to the profile, binds the signatures object to the profile, associates
the profile with the policy, and puts the policy into effect by binding it to Global.
A few tasks cannot be performed in the wizard. You cannot use the wizard to bind a policy to a bind
point other than Global. If you want the profile to apply to only a specific part of your configuration,
you must manually configure the binding. You cannot configure the engine settings or certain other
global configuration options in the wizard. While you can configure any of the advanced protection
settings in the wizard, if you want to modify a specific setting in a single security check, it may be
easier to do so on the manual configuration screens in the GUI.
For more information on using the App Firewall Wizard, see “The App Firewall Wizard.”

NetScaler app interface appExpert template

AppExpert templates are a different and simpler approach to configuring and managing complex en-
terprise applications. The AppExpert display in the GUI consists of a table. Applications are listed
in the left-most column, with the NetScaler features that are applicable to that application appearing
each in its own column to the right. (In the AppExpert interface, those features that are associated with
an application are called application units.) In the AppExpert interface, you configure the interesting
traffic for each application, and turn on rules for compression, caching, rewrite, filtering, responder
and the App Firewall, instead of having to configure each feature individually.
The Web interface AppExpert template contains rules for the following App Firewall signatures and
security checks:
• “Deny URL check.” Detects connections to content that is known to pose a security risk, or to
any other URLs that you designate.
• “Buffer Overflow check.” Detects attempts to cause a buffer overflow on a protected web
server.
• “Cookie Consistency check.” Detects malicious modifications to cookies set by a protected
web site.
• “Form Field Consistency check.” Detects modifications to the structure of a web form on a
protected web site.
• “CSRF Form Tagging check.” Detects cross-site request forgery attacks.
• “Field Formats check.” Detects inappropriate information uploaded in web forms on a pro-
tected web site.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1549

NetScaler 12.0

• “HTML SQL Injection check.” Detects attempts to inject unauthorized SQL code.
• “HTML Cross-Site Scripting check.” Detects cross-site scripting attacks.

For information on installing and using an AppExpert Template, see “AppExpert Applications and Tem-
plates.”

The NetScaler GUI

The GUI is a web-based interface that provides access to all configuration options for the App Firewall
feature, including advanced configuration and management options that are not available from any
other configuration tool or interface. Specifically, many advanced Signatures options can be config-
ured only in the GUI. You can review recommendations generated by the learning feature only in the
GUI. You can bind policies to a bind point other than Global only in the GUI.

For a description of the GUI, see “The App Firewall Configuration Interfaces.” For more information on
using the GUI to configure the App Firewall, see “Manual Configuration By Using the GUI.”

For instructions on configuring the App Firewall by using the GUI, see “Manual Configuration By Using
the GUI.” For information on the NetScaler GUI, see “The App Firewall Configuration Interfaces.”

The NetScaler command line interface

The NetScaler command line interface is a modified UNIX shell based on the FreeBSD bash shell. To
configure the App Firewall from the command line interface, you type commands at the prompt and
press the Enter key, just as you do with any other Unix shell. You can configure most parameters and
options for the App Firewall by using the NetScaler command line. Exceptions are the signatures fea-
ture, many of whose options can be configured only by using the GUI or the App Firewall wizard, and
the learning feature, whose recommendations can only be reviewed in the GUI.

For instructions on configuring the App Firewall by using the NetScaler command line, see “Manual
Configuration By Using the Command Line Interface.”

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Enabling App Firewall

September 18, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1550

NetScaler 12.0

Contributed by:
C

Before you can create an App Firewall security configuration, you must make sure that the App Firewall
feature is enabled.

• If you are configuring a dedicated NetScaler App Firewall appliance or are upgrading an exist-
ing NetScaler or VPX, the feature is already enabled. You do not have to perform either of the
procedures described here.
• If you have a new NetScaler or VPX, you need to enable the App Firewall feature before you
configure it.
• If you are upgrading a NetScaler or VPX from a previous version of the NetScaler operating sys-
tem to the current version, you might need to enable the App Firewall feature before you con-
figure it.

Note:

If you are upgrading a NetScaler or VPX from a previous version, you might also need to update
the licenses on your ADC or VPX before you can enable the App Firewall. Check with your Citrix
representative or reseller to obtain the correct license.

You can enable the App Firewall by using the command line or the GUI.

To enable the App Firewall by using the command line interface

At the command prompt, type the following command:

enable ns feature AppFW

To enable the App Firewall by using the GUI

1. Navigate to System > Settings.

2. In the details pane, click Configure Basic Features.
3. In the Configure Basic Features dialog box, check the App Firewall check box.
4. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1551

NetScaler 12.0

The App Firewall wizard

November 14, 2018

Contributed by:
C

Unlike most wizards, the NetScaler App App Firewall Wizard is designed not just to simplify the initial
configuration process, but also to modify previously created configurations and to maintain your App
Firewall setup. A typical user runs the wizard multiple times, skipping some of the screens each time.

The App Firewall Wizard automatically creates profiles, policies, and signatures.

Opening the Wizard

To run the App Firewall Wizard, open the GUI and follow these steps:

1. Navigate to Security > Application Firewall.

2. In the details pane, under Getting Started, click Application Firewall Wizard. The wizard
opens.

For more information about the GUI, see The App Firewall Configuration Interfaces.

The Wizard screens

The App Firewall wizard displays the following screens on a tabular page:

1. Specify Name: on this screen, when creating a new security configuration, specify a meaningful
name and the appropriate type (HTML, XML or WEB 2.0) for your profile. The default policy and signa-
tures are auto-generated by using the same name.

Profile Name

The name can begin with a letter, number, or the underscore symbol, and can consist of from 1 to 31
letters, numbers, and the hyphen (-), period (.) pound (#), space ( ), at (@), equals (=), colon (:), and
underscore (_) symbols. Choose a name that makes it easy for others to tell what content your new
security configuration protects.

Note:

Because the wizard uses this name for both the policy and the profile, it is limited to 31 characters.
Manually created policies can have names up to 127 characters in length.

When modifying an existing configuration, you select Modify Existing Configuration and then, in the
Name drop-down list, select the name of the existing configuration that you want to modify.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1552

NetScaler 12.0

Note:

Only policies that are bound to global or to a bind point appear in this list; you cannot modify
an unbound policy by using the Application Firewall wizard. You must either manually bind it to
Global or a bind point, or modify it manually. (For manual modification, in the GUI Application
Firewall > Policies > Firewall pane, select the policy and click Open).

Profile Type

You also select a profile type on this screen. The profile type determines the types of advanced pro-
tection (security checks) that can be configured. Because certain kinds of content are not vulnerable
to certain types of security threats, restricting the list of available checks saves time during configura-
tion. The types of App Firewall profiles are:

• Web Application (HTML). Any HTML-based Web site that does not use XML or Web 2.0 technolo-
gies.
• XML Application (XML, SOAP). Any XML-based Web service.
• Web 2.0 Application (HTML, XML, REST). Any Web 2.0 site that combines HTML and XML-based
content, such as an ATOM-based site, a blog, an RSS feed, or a wiki.

Note: If you are unsure which type of content is used on your website, you can choose Web 2.0 Appli-
cation to ensure that you protect all types of web application content.

2. Specify Rule: on this screen, you specify the policy rule (expression) that defines the traffic the
current configuration examines. If you create an initial configuration to protect your websites and
web services, you can accept the default value, true, which selects all web traffic .

If you want this security configuration to examine, not all HTTP traffic that is routed through the appli-
ance, but specific traffic, you can write a policy rule specifying the traffic that you want it to examine.
Rules are written in NetScaler expressions language, which is a fully functional object-oriented pro-
gramming language. For more information, see Configure a Custom Policy Expression.

Note: In addition to the default expressions syntax, for backward compatibility the NetScaler oper-
ating system supports the NetScaler classic expressions syntax on NetScaler Classic and nCore ap-
pliances and virtual appliances. Classic expressions are not supported on NetScaler Cluster appli-
ances and virtual appliances. Current users who want to migrate their existing configurations to the
NetScaler cluster must migrate any policies that contain classic expressions to the default expressions
syntax.

• For a simple description of using the NetScaler expressions syntax to create App Firewall rules,
and a list of useful rules, see “Firewall Policies.”
• For a detailed explanation of how to create policy rules in NetScaler expressions syntax, see
“Policies and Expressions.”

4. Select Signatures: on this screen, you select the categories of signatures that you want to use to
protect your web sites and web services.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1553

NetScaler 12.0

This is not a mandatory step, and you can skip it if you want to and go to the Specify Deep Protections
screen. If the Select Signatures screen is skipped, only a profile and associated policies are created,
and the signatures are not created.

You can select Create New Signature or Select Existing Signature.

If you are creating a new security configuration, the signature categories that you select are enabled,
and by default they are recorded in a new signatures object. The new signatures object is assigned the
same name that you entered on the Specify name screen as the name of the security configuration.

If you have previously configured signatures objects and want to use one of them as the signatures ob-
ject associated with the security configuration that you are creating, click Select Existing Signature
and select a signatures object from the Signatures list.

If you are modifying an existing security configuration, you can click Select Existing Signature and
assign a different signatures object to the security configuration.

If you click Create New Signature, you can choose the edit mode as Simple or Advanced.

1. Specify Signature Protections (Simple mode)

The simple mode allows for easy configuration of the signature, with a preset list of protection defini-
tions for common applications such as IIS (Internet Information Server), PHP and ActiveX. The default
categories in Simple mode are:

• CGI. Protection against attacks on web sites that use CGI scripts in any language, including PERL
scripts, Unix shell scripts, and Python scripts.

• Cold Fusion. Protection against attacks on web sites that use the Adobe Systems® ColdFusion®
Web development platform.

• FrontPage. Protection against attacks on web sites that use the Microsoft® FrontPage® Web de-
velopment platform.

• PHP. Protection against attacks on web sites that use the PHP open-source Web development
scripting language.

• Client side. Protection against attacks on client-side tools used to access your protected web
sites, such as Microsoft Internet Explorer, Mozilla Firefox, the Opera browser, and the Adobe
Acrobat Reader.

• Microsoft IIS. Protection against attacks on Web sites that run the Microsoft Internet Information
Server (IIS)

• Miscellaneous. Protection against attacks on other server-side tools, such as Web servers and
database servers.

On this screen, you select the actions associated with the signature categories that you selected on
the Select Signatures screen. The actions that you can configure are:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1554

NetScaler 12.0

• Block
• Log
• Stats

By default the Log and Stats actions are enabled but not the Block action. To configure actions, click
Settings. You can change the action settings of all the selected categories by using the Action drop-
down menu.

1. Specify Signature Protections (Advanced mode)

The advanced mode allows for more granular control over the signature definitions and provides sig-
nificantly more information. Use the advanced mode if you want complete control over signature
definition.

The contents of this screen are the same as the contents of the Modify Signatures Object dialog box, as
described in “Configuring or Modifying a Signatures Object.” In this screen, you can configure actions
either by clicking the Actions drop-down menu or the actions menu, which appears as a cirle with
three dots.

7. Specify Deep Protections: on this screen, you choose the advanced protections (also called secu-
rity checks or simply checks) that you want to use to protect your web sites and web services. Which
checks are available depends on the profile type that you chose on the Specify Name screen. All
checks are available for Web 2.0 Application profiles.

For more information, see Overview of Security Checks and see “Advanced Form Protections Checks.”

You configure the actions for the advanced protections that you have enabled.The actions that you
can configure are:

• Block: blocks connections that match the signature. Disabled by default.

• Log: logs connections that match the signature for later analysis. Enabled by default.
• Stats: maintains statistics, for each signature, that show how many connections it matched and
provide certain other information about the types of connections that were blocked. Disabled
by default.
• Learn. Observe traffic to this website or web service, and use connections that repeatedly vio-
late this check to generate recommended exceptions to the check, or new rules for the check.
Available only for some checks. For more information about the learning feature see “Configur-
ing and Using the Learning Feature,” and how learning works and how to configure exceptions
(relaxations) or deploy learned rules for a check, see “Manual Configuration By Using the GUI.”

To configure actions, select the protection by clicking the check box, and then click Action Settings to
select the required actions. Select other parameters, if required, and then click OK to close the Action
Settings window.

To view all logs for a specific check, select that check, and then click Logs to display the Syslog Viewer,
as described in “App Firewall Logs.” If a security check is blocking legitimate access to your protected

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1555

NetScaler 12.0

web site or web service, you can create and implement a relaxation for that security check by selecting
a log that shows the unwanted blocking, and then clicking Deploy.

After you completing specifying Action Settings, click Finish to complete the wizard.

Following are four procedures that show how to perform specific types of configuration by using the
App Firewall wizard.

Create a New Configuration

Follow these steps to create a new firewall configuration and signature objects, by using the Appli-
caiton Firewall wizard.

1. Navigate to Security > Application Firewall.

2. In the details pane, under Getting Started, click Application Firewall Wizard.**The wizard
opens.

3. On the Specify Name screen, select Create New Configuration.

4. In the Name field, type a name, and then click Next.

5. In the Specify Rule screen, click Next again.

6. In the Select Signatures screen, select Create New Signature and Simple as the edit mode,
and then click Next.

7. In the Specify Signature Protections screen, configure the required settings. For more infor-
mation about which signatures to consider for blocking and how to determine when you can
safely enable blocking for a signature, see “Signatures.”

8. In the Specify Deep Protections screen configure the required actions and parameters in Ac-
tion Settings.

9. When you complete, click Finish to close the Application Firewall wizard.

Modify an Existing Configuration

Follow these steps to modify an existing configuration and existing signature categories.

1. Navigate to Security > Application Firewall.

2. In the details pane, under Getting Started, click Application Firewall Wizard. The wizard
opens.
3. On the Specify Name screen, select Modify Existing Configuration and, in the Name drop-down
list, choose the security configuration that you created during new configuration, and then click
Next.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1556

NetScaler 12.0

4. In the Specify Rule screen, click Next to keep the default value “true.” If you want to modify the
rule, follow the steps described in “Configure a Custom Policy Expresssion.”
5. In the Select Signatures screen, click Select Existing Signature. From the Existing Signature
drop-down menu, select the appropriate option, and then click Next. The advanced signature
protection screen appears.
Note: If you select an existing signature, the default edit mode for signature protected is ad-
vanced.
6. In the Specify Signature Protections screen, configure the required settings and click Next. For
more information about which signatures to consider for blocking and how to determine when
you can safely enable blocking for a signature, see “Signatures.”
7. In the Specify Deep Protections screen, configure the settings and click Next.
8. After you complete, click Finish to close the App Firewall Wizard.

Create a New Configuration without Signatures

Follow these steps to use the Application Firewall Wizard to skip the Select Signatures screen and
create a new configuration with just the profile and the associated policies but without any signatures.

1. Navigate to Security > Application Firewall.

2. In the details pane, under Getting Started, click Application Firewall Wizard.The wizard opens.
3. On the Specify Name screen, select Create New Configuration.
4. In the Name field, type a name, and then click Next.
5. In the Specify Rule screen, click Next again.
6. In the Select Signatures screen, click Skip.
7. In the Specify Deep Protections screen configure the required actions and parameters in Ac-
tion Settings.
8. When you complete, click Finish to close the Application Firewall Wizard.

Configure a Custom Policy Expression

Follow these steps to use the Application Firewall Wizard to create a specialized security configura-
tion to protect only specific content. In this case, you create a new security configuration instead of
modifying the initial configuration. This type of security configuration requires a custom rule, so that
the policy applies the configuration to only the selected Web traffic.

1. Navigate to Security > Application Firewall.

2. In the details pane, under Getting Started, click Application Firewall Wizard.
3. On the Specify Name screen, type a name for your new security configuration in the Name text
box, select the type of security configuration from the Type drop-down list, and then click Next.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1557

NetScaler 12.0

4. On the Specify Rule screen, enter a rule that matches only that content that you want this web
application to protect. Use the Frequently Used Expressions drop-down list and the Expres-
sion Editor to create a custom expression. When you complete, click Next.
5. In the Select Signatures screen, select the edit mode, and then click Next.
6. In the Specify Signature Protections screen, configure the required settings.
7. In the Specify Deep Protections screen configure the required actions and parameters in Ac-
tion Settings.
8. When you complete, click Finish to close the Application Firewall Wizard.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Manual configuration

September 18, 2018

Contributed by:
C

If you want to bind a profile to a bind point other than Global, you must manually configure the bind-
ing. Also, certain security checks require that you either manually enter the necessary exceptions or
enable the learning feature to generate the exceptions that your Web sites and Web services need.
Some of these tasks cannot be performed by using the App Firewall wizard.

If you are familiar with how the App Firewall works and prefer manual configuration, you can manually
configure a signatures object and a profile, associate the signatures object with the profile, create a
policy with a rule that matches the web traffic that you want to configure, and associate the policy
with the profile. You then bind the policy to Global, or to a bind point, to put it into effect, and you
have created a complete security configuration.

For manual configuration, you can use the GUI (a graphical interface) or the command line. Citrix
recommends that you use the GUI. Not all configuration tasks can be performed at the command line.
Certain tasks, such as enabling signatures and reviewing learned data, must be done in the GUI. Most
other tasks are easier to perform in the GUI.

Replicating configuration

When you use the GUI (GUI) or the command line interface (CLI) to manually configure the App Fire-
wall, the configuration is saved in the /nsconfig/ns.conf file. You can use the commands in that file to

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1558

NetScaler 12.0

replicate the configuration on another appliance. You can cut and paste the commands into the CLI
one by one, or you can save multiple commands in a text file in the /var/tmp folder and run them as
a batch file. Following is an example of running a batch file containing commands copied from the
/nsconfig/ns.conf file of a different appliance:
> batch -f /var/tmp/appfw_add.txt

Warning

Import commands are not saved in the ns.conf file. Before running commands from the ns.conf
file to replicate the configuration on another appliance, you must import all the objects used
in the configuration (for example, signatures, error page, WSDL, and Schema) to the appliance
on which you will replicate the configuration. The add command to add an App Firewall profile
saved in an ns.conf file might include the name of an imported object, but such a command
might fail when executed on another appliance if the referenced object does not exist on that
appliance.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Manual configuration by using the GUI

December 7, 2018
Contributed by:
C
If you need to configure the App Firewall feature manually, Citrix recommends that you use the GUI.

To create and configure a signatures object

Before you can configure the signatures, you must create a new signatures object from the appropriate
default signatures object template. Assign the copy a new name, and then configure the copy. You
cannot configure or modify the default signatures objects directly. The following procedure provides
basic instructions for configuring a signatures object. For more detailed instructions, see “Manually
Configuring the Signatures Feature.”
1. Navigate to Security > application firewall > Signatures.
2. In the details pane, select the signatures object that you want to use as a template, and then
click Add.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1559

NetScaler 12.0

Your choices are:

• *Default Signatures. Contains the signatures rules, the SQL injection rules, and the cross-
site scripting rules.
• *XPath Injection. Contains all of the items in the *Default Signatures, and in addition, con-
tains the XPath injection rules.

3. In the **Add Signatures Object **dialog box, type a name for your new signatures object, click
OK, and then click Close. The name can begin with a letter, number, or the underscore symbol,
and can consist of from one to 31 letters, numbers, and the hyphen (-), period (.) pound (#),
space ( ), at (@), equals (=), and underscore (_) symbols.

4. Select the signatures object that you created, and then click Open.

5. In the Modify Signatures Object dialog box, set the Display Filter Criteria options at the left
to display the filter items that you want to configure.

As you modify these options, the results that you specify are displayed in the Filtered Results
window at the right. For more information about the categories of signatures, see “Signatures.”

6. In the Filtered Results area, configure the settings for a signature by selecting and clearing the
appropriate checkboxes.

7. When finished, finished, click Close.

To create an App Firewall profile by using the GUI

Creating an App Firewall profile requires that you specify only a few configuration details.

1. Navigate to Security > application firewall > Profiles.

2. In the details pane, click Add.

3. In the Create App Firewall Profile dialog box, type a name for your profile.

The name can begin with a letter, number, or the underscore symbol, and can consist of from
one to 31 letters, numbers, and the hyphen (-), period (.) pound (#), space ( ), at (@), equals (=),
colon (:), and underscore (_) symbols.

4. Choose the profile type from the drop-down list.

5. Click Create, and then click Close.

To configure an App Firewall profile by using the GUI

1. Navigate to Security > application firewall > Profiles.

2. In the details pane, select the profile that you want to configure, and then click Edit.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1560

NetScaler 12.0

3. In the Configure App Firewall Profile dialog box, on the Security Checks tab, configure the
security checks.

• To enable or disable an action for a check, in the list, select or clear the checkbox for that
action.

• To configure other parameters for those checks that have them, in the list, click the blue
chevron to the far right of that check. In the dialog box that appears, configure the param-
eters. These vary from check to check.

You can also select a check and, at the bottom of the dialog box, click Open to display the
Configure Relaxation dialog box or Configure Rule dialog box for that check. These dialog
boxes also vary from check to check. Most of them include a Checks tab and a General
tab. If the check supports relaxations or user-defined rules, the Checks tab includes an
Add button, which opens yet another dialog box, in which you can specify a relaxation or
rule for the check. (A relaxation is a rule for exempting specified traffic from the check.) If
relaxations have already been configured, you can select one and click Open to modify it.

• To review learned exceptions or rules for a check, select the check, and then click Learned
Violations. In the Manage Learned Rules dialog box, select each learned exception or rule
in turn.

– To edit the exception or rule, and then add it to the list, click Edit & Deploy.
– To accept the exception or rule without modification, click Deploy.
– To remove the exception or rule from the list, click Skip.

• To refresh the list of exceptions or rules to be reviewed, click Refresh.

• To open the Learning Visualizer and use it to review learned rules, click Visualizer.

• To review the log entries for connections that matched a check, select the check, and then
click Logs. You can use this information to determine which checks are matching attacks
so that you can enable blocking for those checks. You can also use this information to
determine which checks are matching legitimate traffic, so that you can configure an ap-
propriate exemption to allow those legitimate connections. For more information about
the logs, see “Logs, Statistics, and Reports.”

• To completely disable a check, in the list, clear all of the checkboxes to the right of that
check.

4. On the Settings tab, configure the profile settings.

• To associate the profile with the set of signatures that you previously created and config-
ured, under Common Settings, choose that set of signatures in the Signatures drop-down
list.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1561

NetScaler 12.0

Note:

You may need to use the scroll bar on the right of the dialog box to scroll down to
display the Common Settings section.

• To configure an HTML or XML Error Object, select the object from the appropriate drop-
down list.
Note:

You must first upload the error object that you want to use in the Import pane.

• To configure the default XML Content Type, type the content type string directly into the
Default Request and Default Response text boxes, or click Manage Allowed Content Types
to manage the list of allowed content types.

5. If you want to use the learning feature, click Learning, and configure the learning settings for
the profile. For more information, see Configure and Learning feature..

6. Click OK to save your changes and return to the Profiles pane.

Configuring an App Firewall rule or relaxation

You configure two different types of information in this dialog box, depending upon which security
check you are configuring. In the majority of cases, you configure an exception (or relaxation) to the
security check. If you are configuring the Deny URL check or the Field Formats check, you configure
an addition (or rule). The process for either of these is the same.

To configure a relaxation or rule by using the GUI

1. Navigate to Security > application firewall > Profiles.

2. In the Profiles pane, select the profile you want to configure, and then click Edit.

3. In the Configure App Firewall Profile dialog box, click the Security Checks tab. The Secu-
rity Checks tab contains the complete list of App Firewall security checks, also called advanced
protections in some places.

4. In the Security Checks tab, click the check that you want to configure, and then click Open. The
Modify Check dialog box for the check that you chose is displayed, with the Checks tab selected.
The Checks tab contains a list of existing relaxations or rules for this check. The list might be
empty if you have not either manually added any relaxations or approved any relaxations that
were recommended by the learning engine. Beneath the list is a row of buttons that allow you
to add, modify, delete, enable, or disable the relaxations on the list.

5. To add or modify a relaxation or a rule, do one of the following:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1562

NetScaler 12.0

• To add a new relaxation, click Add.

• To modify an existing relaxation, select the relaxation that you want to modify, and then
click Open.

The Add Check Relaxation or Modify Check Relaxation dialog box for the selected check is
displayed. Except for the title, these dialog boxes are identical.

6. Fill in the dialog box as described below. The dialog boxes for each check are different; the list
below covers all elements that might appear in any dialog box.

• Enabled check box—Select to place this relaxation or rule in active use; clear to deactivate
it.

• Attachment Content Type—The Content-Type attribute of an XML attachment. In the text

area, enter a regular expression that matches the Content-Type attribute of the XML attach-
ments to allow.

• Action URL—In the text area, enter a PCRE-format regular expression that defines the URL
to which data entered into the web form is delivered.

• Cookie—In the text area, enter a PCRE-format regular expression that defines the cookie.

• Field Name—A web form field name element may be labeled Field Name, Form Field, or
another similar name. In the text area, enter a PCRE-format regular expression that defines
the name of the form field.

• Form Origin URL—In the text area, enter a PCRE-format regular expression that defines
the URL that hosts the web form.

• Form Action URL—In the text area, enter a PCRE-format regular expression that defines
the URL to which data entered into the web form is delivered.

• Name—An XML element or attribute name. In the text area, enter a PCRE-format regular
expression that defines the name of the element or attribute.

• URL—A URL element may be labeled Action URL, Deny URL, Form Action URL, Form Origin
URL, Start URL, or simply URL. In the text area, enter a PCRE-format regular expression that
defines the URL.

• Format—The format section contains multiple settings that include list boxes and text
boxes. Any of the following can appear:

– Type—Select a field type in the Type drop-down list. To add a new field type defini-
tion, click Manage—
– Minimum Length—Type a positive integer that represents the minimum length in
characters if you want to force users to fill in this field. Default: 0 (Allows field to be
left blank.)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1563

NetScaler 12.0

– Maximum length—To limit the length of data in this field, type a positive integer that
represents the maximum length in characters. Default: 65535

• Location—Choose the element of the request that your relaxation will apply to from the
drop-down list. For HTML security checks, the choices are:

– FORMFIELD—Form fields in web forms.

– HEADER—Request headers.
– COOKIE—Set-Cookie headers.

For XML security checks, the choices are:

– ELEMENT—XML element.
– ATTRIBUE—XML attribute.

• Maximum Attachment Size—The maximum size in bytes allowed for an XML attachment.

• Comments—In the text area, type a comment. Optional.

Note: For any element that requires a regular expression, you can type the regular expression,
use the
Regex Tokens menu to insert regular expression elements and symbols directly into the text box,
or click Regex Editor to open the Add Regular Expression dialog box, and use it to construct
the expression.

7. To remove a relaxation or rule, select it, and then click Remove.

8. To enable a relaxation or rule, select it, and then click Enable.

9. To disable a relaxation or rule, select it, and then click Disable.

10. To configure the settings and relationships of all existing relaxations in an integrated interactive
graphic display, click Visualizer, and use the display tools.

Note:

The Visualizer button does not appear on all check relaxation dialog boxes.

11. To review learned rules for this check, click Learning and perform the steps in To configure and
use the Learning feature

12. Click OK.

To configure the Learning feature by using the GUI

1. Navigate to Security > application firewall > Profiles.

2. In the Profiles pane, select the profile, and then click Edit.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1564

NetScaler 12.0

3. Click the Learning tab. At the top of the Learning tab is list of the security checks that are avail-
able in the current profile and that support the learning feature.

4. To configure the learning thresholds, select a security check, and then type the appropriate
values in the following text boxes:

• Minimum number threshold. Depending on which security check’s learning settings you
are configuring, the minimum number threshold might refer to the minimum number of
total user sessions that must be observed, the minimum number of requests that must be
observed, or the minimum number of times a specific form field must be observed, before
a learned relaxation is generated. Default: 1

• Percentage of times threshold. Depending on which security check’s learning settings

you are configuring, the percentage of times threshold might refer to the percentage of
total observed user sessions that violated the security check, the percentage of requests,
or the percentage of times a form field matched a particular field type, before a learned
relaxation is generated. Default: 0

5. To remove all learned data and reset the learning feature, so that it must start its observations
again from the beginning, click Remove All Learned Data.

Note:

This button removes only learned recommendations that have not been reviewed and ei-
ther approved or skipped. It does not remove learned relaxations that have been accepted
and deployed.

6. To restrict the learning engine to traffic from a specific set of IPs, click Trusted Learning Clients,
and add the IP addresses that you want to use to the list.

a) To add an IP address or IP address range to the Trusted Learning Clients list, click Add.
b) In the Add Trusted Learning Clients dialog box, Trusted Clients IP list box, type the IP
address or an IP address range in CIDR format.
c) In the Comments text area, type a comment that describes this IP address or range.
d) Click Create to add your new IP address or range to the list.
e) To modify an existing IP address or range, click the IP address or range, and then click
Open. Except for the name, the dialog box that appears is identical to the Add Trusted
Learning Clients dialog box.
f) To disable or enable an IP address or range, but leave it on the list, click the IP address or
range, and then click Disable or Enable, as appropriate.
g) To remove an IP address or range completely, click the IP address or range, and then click
Remove.

7. Click Close to return to the Configure application firewall Profile dialog box.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1565

NetScaler 12.0

8. Click Close to close the Configure application firewall Profile dialog box, and return to the
application firewall Profile screen.

To create and configure a policy by using the GUI

1. Navigate to Security > application firewall > Policies.

2. In the details pane, do one of the following:

• To create a new firewall policy, click Add. The Create App Firewall Policy is displayed.
• To edit an existing firewall policy, select the policy, and then click Edit.

The Create App Firewall Policy or Configure App Firewall Policy is displayed.

3. If you are creating a new firewall policy, in the Create App Firewall Policy dialog box, Policy
Name text box, type a name for your new policy.

The name can begin with a letter, number, or the underscore symbol, and can consist of from
one to 128 letters, numbers, and the hyphen (-), period (.) pound (#), space ( ), at (@), equals (=),
colon (:), and underscore (_) symbols.

If you are configuring an existing firewall policy, this field is read-only. You cannot modify it.

4. Select the profile that you want to associate with this policy from the Profile drop-down list.
You can create a new profile to associate with your policy by clicking New, and you can modify
an existing profile by clicking Modify.

5. In the Expression text area, create a rule for your policy.

• You can type a rule directly into the text area.

• You can click Prefix to select the first term for your rule, and follow the prompts.
• You can click Add to open the Add Expression dialog box, and use it to construct the rule.

6. Click Create or OK, and then click Close.

To create or configure an App Firewall rule (expression)

The policy rule, also called the expression, defines the web traffic that the App Firewall filters by using
the profile associated with the policy. Like other NetScaler policy rules (or expressions), App Firewall
rules use NetScaler expressions syntax. This syntax is powerful, flexible, and extensible. It is too com-
plex to describe completely in this set of instructions. You can use the following procedure to create
a simple firewall policy rule, or you can read it as an overview of the policy creation process.

1. If you have not already done so, navigate to the appropriate location in the App Firewall wizard
or the NetScaler GUI to create your policy rule:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1566

NetScaler 12.0

• If you are configuring a policy in the App Firewall wizard, in the navigation pane, click ap-
plication firewall, then in the details pane click application firewall Wizard, and then
navigate to the Specify Rule screen.
• If you are configuring a policy manually, in the navigation pane, expand application fire-
wall, Policies, and then Firewall. In the details pane, to create a new policy, click Add. To
modify an existing policy, select the policy, and then click Open.
2. On the Specify Rule screen, the Create application firewall Profile dialog box, or the Configure
Application Firewall Profile dialog box, click Prefix, and then choose the prefix for your expres-
sion from the drop-down list. Your choices are:
• HTTP. The HTTP protocol. Choose this if you want to examine some aspect of the request
that pertains to the HTTP protocol.
• SYS. The protected Web site(s). Choose this if you want to examine some aspect of the
request that pertains to the recipient of the request.
• CLIENT. The computer that sent the request. Choose this if you want to examine some
aspect of the sender of the request.
• SERVER. The computer to which the request was sent. Choose this if you want to examine
some aspect of the recipient of the request.
After you choose a prefix, the App Firewall displays a two-part prompt window that displays the
possible next choices at the top, and a brief explanation of what the selected choice means at
the bottom.
3. Choose your next term.
If you chose HTTP as your prefix, your only choice is REQ, which specifies the Request/Response
pair. (The App Firewall operates on the request and response as a unit instead of on each sepa-
rately.) If you chose another prefix, your choices are more varied. For help on a specific choice,
click that choice once to display information about it in the lower prompt window.
When you have decided which term you want, double-click it to insert it into the Expression
window.
4. Type a period after the term you just chose. You are then prompted to choose your next term, as
described in the previous step. When a term requires that you type a value, fill in the appropriate
value. For example, if you choose HTTP.REQ.HEADER(“”), type the header name between the
quotation marks.
5. Continue choosing terms from the prompts and filling in any values that are needed, until your
expression is finished.
Following are some examples of expressions for specific purposes.
• Specific web host. To match traffic from a particular web host:

1 HTTP.REQ.HEADER(”Host”).EQ(”shopping.example.com”)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1567

NetScaler 12.0

For shopping.example.com, substitute the name of the web host that you want to match.
• Specific web folder or directory. To match traffic from a particular folder or directory on
a Web host:

1 HTTP.REQ.URL.STARTSWITH(”https//www.example.com/folder”)

For www.example.com, substitute the name of the web host. For folder, substitute the
folder or path to the content that you want to match. For example, if your shopping cart is
in a folder called /solutions/orders, you substitute that string for folder.
• Specific type of content: GIF images. To match GIF format images:

1 HTTP.REQ.URL.ENDSWITH(”.gif”)

To match other format images, substitute another string in place of .gif.

• Specific type of content: scripts. To match all CGI scripts located in the CGI-BIN directory:

1 HTTP.REQ.URL.STARTSWITH(”https//www.example.com/CGI-BIN”)

To match all JavaScripts with .js extensions:

1 HTTP.REQ.URL.ENDSWITH(”.js”)

For more information about creating policy expressions, see “Policies and Expressions.”
Note:
If you use the command line to configure a policy, remember to escape any double quota-
tion marks within NetScaler expressions. For example, the following expression is correct
if entered in the GUI:

1 HTTP.REQ.HEADER(”Host”).EQ(”shopping.example.com”)

If entered at the command line, however, you must type this instead:

1 HTTP.REQ.HEADER(”Host”).EQ(”shopping.example.com”)

To add a firewall rule (expression) by using the Add Expression dialog box

The Add Expression dialog box (also referred to as the Expression Editor) helps users who are not
familiar with the NetScaler expressions language to construct a policy that matches the traffic that
they want to filter.
1. If you have not already done so, navigate to the appropriate location in the App Firewall wizard
or the NetScaler GUI:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1568

NetScaler 12.0

• If you are configuring a policy in the App Firewall wizard, in the navigation pane, click
App Firewall, then in the details pane click App Firewall Wizard, and then navigate to the
Specify Rule screen.
• If you are configuring a policy manually, in the navigation pane, expand App Firewall,
then Policies, and then Firewall. In the details pane, to create a new policy, click Add. To
modify an existing policy, select the policy, and then click Open.
2. On the Specify Rule screen, in the Create App Firewall Profile dialog box, or in the Configure
App Firewall Profile dialog box, click Add.
3. In the Add Expression dialog box, in the Construct Expression area, in the first list box, choose
one of the following prefixes:
• HTTP. The HTTP protocol. Choose this if you want to examine some aspect of the request
that pertains to the HTTP protocol. The default choice.
• SYS. The protected Web site(s). Choose this if you want to examine some aspect of the
request that pertains to the recipient of the request.
• CLIENT. The computer that sent the request. Choose this if you want to examine some
aspect of the sender of the request.
• SERVER. The computer to which the request was sent. Choose this if you want to examine
some aspect of the recipient of the request.
4. In the second list box, choose your next term. The available terms differ depending on the choice
you made in the previous step, because the dialog box automatically adjusts the list to contain
only those terms that are valid for the context. For example, if you selected HTTP in the previ-
ous list box, the only choice is REQ, for requests. Because the App Firewall treats requests and
associated responses as a single unit and filters both, you do not need to specific responses
separately. After you choose your second term, a third list box appears to the right of the sec-
ond. The Help window displays a description of the second term, and the Preview Expression
window displays your expression.
5. In the third list box, choose the next term. A new list box appears to the right, and the Help win-
dow changes to display a description of the new term. The Preview Expression window updates
to display the expression as you have specified it to that point.
6. Continue choosing terms, and when prompted filling in arguments, until your expression is com-
plete. If you make a mistake or want to change your expression after you have already selected
a term, you can simply choose another term. The expression is modified, and any arguments or
additional terms that you added after the term that you modified are cleared.
7. When you have finished constructing your expression, click OK to close the Add Expression dia-
log box. Your expression is inserted into the Expression text area.

To bind an App Firewall policy by using the GUI

1. Do one of the following:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1569

NetScaler 12.0

• Navigate to Security > App Firewall, and in the details pane, click application firewall
policy manager.
• Navigate to Security > application firewall > Policies > Firewall Policies, and in the de-
tails pane, click Policy Manager.
2. In the Application Firewall Manager dialog, choose the bind point to which you want to bind
the policy from the drop-down list. The choices are:
• Override Global. Policies that are bound to this bind point process all traffic from all in-
terfaces on the NetScaler appliance, and are applied before any other policies.
• LB Virtual Server. Policies that are bound to a load balancing virtual server are applied
only to traffic that is processed by that load balancing virtual server, and are applied be-
fore any Default Global policies. After selecting LB Virtual Server, you must also select the
specific load balancing virtual server to which you want to bind this policy.
• CS Virtual Server. Policies that are bound to a content switching virtual server are applied
only to traffic that is processed by that content switching virtual server, and are applied
before any Default Global policies. After selecting CS Virtual Server, you must also select
the specific content switching virtual server to which you want to bind this policy.
• Default Global. Policies that are bound to this bind point process all traffic from all inter-
faces on the NetScaler appliance.
• Policy Label. Policies that are bound to a policy label process traffic that the policy label
routes to them. The policy label controls the order in which policies are applied to this
traffic.
• None. Do not bind the policy to any bind point.
3. Click Continue. A list of existing App Firewall policies appears.
4. Select the policy you want to bind by clicking it.
5. Make any additional adjustments to the binding.
• To modify the policy priority, click the field to enable it, and then type a new priority. You
can also select Regenerate Priorities to renumber the priorities evenly.
• To modify the policy expression, double click that field to open the Configure App Fire-
wall Policy dialog box, where you can edit the policy expression.
• To set the Goto Expression, double click field in the Goto Expression column heading to
display the drop-down list, where you can choose an expression.
• To set the Invoke option, double click field in the Invoke column heading to display the
drop-down list, where you can choose an expression.
6. Repeat steps 3 through 6 to add any additional App Firewall policies you want to globally bind.
7. Click OK. A message appears in the status bar, stating that the policy has been successfully
bound.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1570

NetScaler 12.0

4. App Firewall

Manual configuration By using the command line interface

November 14, 2018

Contributed by:
C

You can configure many App Firewall features from the NetScaler command line. There are important
exceptions, however. You cannot enable signatures from the command line. There are over 1,000
default signatures in seven categories; the task is simply too complex for the command line interface.
You can configure the check actions and parameters for security checks from the command line, but
cannot enter manual relaxations. While you can configure the adaptive learning feature and enable
learning from the command line, you cannot review learned relaxations or learned rules and approve
or skip them. The command line interface is intended for advanced users who are thoroughly familiar
with the NetScaler appliance and the App Firewall feature.

To manually configure the App Firewall by using the NetScaler command line, use a telnet or secure
shell client of your choice to log on to the NetScaler command line.

To create a profile by using the command line interface

At the command prompt, type the following commands:

• add appfw profile <name> [-defaults ( basic | advanced )]

• set appfw profile <name> -type ( HTML | XML | HTML XML )
• save ns config

Example

The following example adds a profile named pr-basic, with basic defaults, and assigns a profile type
of HTML. This is the appropriate initial configuration for a profile to protect an HTML Web site.

1 add appfw profile pr-basic -defaults basic

2 set appfw profile pr-basic -type HTML
3 save ns config

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1571

NetScaler 12.0

To configure a profile by using the command line interface

At the command prompt, type the following commands:

• set appfw profile <name> <arg1> [<arg2> ...] where <arg1> represents a param-
eter and <arg2> represents either another parameter or the value to assign to the parameter
represented by <arg1>. For descriptions of the parameters to use when configuring specific
security checks, see Advanced Protections and its subtopics. For descriptions of the other pa-
rameters, see “Parameters for Creating a Profile.”
• save ns config

Example

The following example shows how to configure an HTML profile created with basic defaults to begin
protecting a simple HTML-based Web site. This example turns on logging and maintenance of statis-
tics for most security checks, but enables blocking only for those checks that have extremely low false
positive rates and require no special configuration. It also turns on transformation of unsafe HTML and
unsafe SQL, which prevents attacks but does not block requests to your Web sites. With logging and
statistics enabled, you can later review the logs to determine whether to enable blocking for a specific
security check.

1 set appfw profile -startURLAction log stats

2 set appfw profile -denyURLAction block log stats
3 set appfw profile -cookieConsistencyAction log stats
4 set appfw profile -crossSiteScriptingAction log stats
5 set appfw profile -crossSiteScriptingTransformUnsafeHTML ON
6 set appfw profile -fieldConsistencyAction log stats
7 set appfw profile -SQLInjectionAction log stats
8 set appfw profile -SQLInjectionTransformSpecialChars ON
9 set appfw profile -SQLInjectionOnlyCheckFieldsWithSQLChars ON
10 set appfw profile -SQLInjectionParseComments checkall
11 set appfw profile -fieldFormatAction log stats
12 set appfw profile -bufferOverflowAction block log stats
13 set appfw profile -CSRFtagAction log stats
14 save ns config

To create and configure a policy

At the command prompt, type the following commands:

• add appfw policy <name> <rule> <profile>

• save ns config

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1572

NetScaler 12.0

Example

The following example adds a policy named pl-blog, with a rule that intercepts all traffic to or from
the host blog.example.com, and associates that policy with the profile pr-blog. This is an appropriate
policy to protect a blog hosted on a specific hostname.

1 add appfw policy pl-blog ”HTTP.REQ.HOSTNAME.DOMAIN.EQ(”blog.example.com

”)” pr-blog

To bind an App Firewall policy

At the command prompt, type the following commands:

• bind appfw global <policyName> <priority>

• save ns config

Example

The following example binds the policy named pl-blog and assigns it a priority of 10.

1 bind appfw global pl-blog 10

2 save ns config

To configure session limit per PE

At the command prompt, type the following commands:

• set appfw settings <session limit>

Example

The following example configures the session limit per PE.

1 > set appfw settings -sessionLimit 500000‘

2
3 Done
4
5 Default value:100000   Max value:500000 per PE

1.
2. Citrix ADC

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1573

NetScaler 12.0

3. NetScaler 12.0
4. App Firewall

Signatures

December 14, 2018

Contributed by:
C

The App Firewall signatures function provides specific, configurable rules to simplify the task of pro-
tecting your web sites against known attacks. A signature represents a pattern that is a component
of a known attack on an operating system, web server, website, XML-based web service, or other re-
source. A rich set of preconfigured App Firewall built-in or Native rules offers an easy to use security
solution, leveraging the power of pattern matching to detect attacks and protect against application
vulnerabilities.

You can create your own signatures or use the signatures in the built-in templates. The App Firewall
has two built-in templates:

• Default Signatures: This template contains a preconfigured list of over 1,300 signatures, in ad-
dition to a complete list of SQL injection keywords, SQL special strings, SQL transform rules, and
SQL wildchar characters. It also contains denied patterns for cross-site scripting, and allowed
attributes and tags for cross-site scripting. This is a read-only template. You can view the con-
tents, but you cannot add, edit, or delete anything in this template. To use it, you must make
a copy. In your own copy, you can enable the signature rules that you want to apply to your
traffic, and specify the actions to be taken when the signature rules match the traffic.

The App Firewall signatures are derived from the rules published by Snort, which is an open source
intrusion prevention system capable of performing real-time traffic analysis to detect a variety of at-
tacks and probes.

• *Xpath Injection Patterns: This template contains a preconfigured set of literal and PCRE key-
words and special strings that are used to detect XPath (XML Path Language) injection attacks.

Blank Signatures: In addition to making a copy of the built-in *Default Signatures template, you can
use a blank signatures template to create a new signature object. The signature object that you create
with the blank signatures option does not have any native signature rules, but, just like the *Default
template, it has all the SQL/XSS built-in entities.

External-Format Signatures: The App Firewall also supports the use of external format signatures.
You can import the scan files of the third party scan tools by using the XSLT files that are supported

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1574

NetScaler 12.0

by the NetScaler App Firewall. A set of built-in XSLT files are available for the following scan tools to
translate these external format files to the Native format:

• Cenzic
• Deep Security for Web Apps
• IBM AppScan Enterprise
• IBM AppScan Standard.
• Qualys
• Whitehat
• Hewlett Packard Enterprise WebInspect

Protection options for your application

Tighter security increases processing overhead. Signatures provide the following deployment options
to help you to optimize the protection of your applications:

• Negative Security Model: With the negative security model, you use a rich set of preconfigured
signature rules to leverage the power of pattern matching to detect attacks and protect against
application vulnerabilities. You block only what you don’t want and allow the rest. You can add
your own signature rules, based on the specific security needs of your applications, to design
your own customized security solutions.

• Hybrid security Model: In addition to using signatures, you can use positive security checks
to create a configuration ideally suited for your applications. Use signatures to block what you
don’t want, and use positive security checks to enforce what is allowed.

To protect your application by using signatures, you must configure one or more profiles to use your
signatures object. In a hybrid security configuration, the SQL injection and Cross-Site scripting pat-
terns, and the SQL transformation rules, in your signatures object are used not only by the signature
rules, but also by the positive security checks configured in the App Firewall profile that is using the
signatures object.

The App Firewall examines the traffic to your protected web sites and web services to detect traffic
that matches a signature. A match is triggered only when every pattern in the rule matches the traffic.
When a match occurs, the specified actions for the rule are invoked. You can display an error page or
error object when a request is blocked. Log messages can help you to identify attacks being launched
against your application. If you enable statistics, the App Firewall maintains data about requests that
match an App Firewall signature or security check.

If the traffic matches both a signature and a positive security check, the more restrictive of the two
actions is enforced. For example, if a request matches a signature rule for which the block action is
disabled, but the request also matches an SQL Injection positive security check for which the action is

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1575

NetScaler 12.0

block, the request is blocked. In this case, the signature violation might be logged as <not blocked
>, although the request is blocked by the SQL injection check.

Customization: If necessary, you can add your own rules to a signatures object. You can also cus-
tomize the SQL/XSS patterns. The option to add your own signature rules, based on the specific se-
curity needs of your applications, gives you the flexibility to design your own customized security
solutions. You block only what you don’t want and allow the rest. A specific fast-match pattern in
a specified location can significantly reduce processing overhead to optimize performance. You can
add, modify, or remove SQL injection and cross-site scripting patterns. Built-in RegEx and expression
editors help you configure your patterns and verify their accuracy.

Auto-update: You can manually update the signature object to get the latest signature rules, or you
can leverage the auto-update feature so that the App Firewall can automatically update the signatures
from the cloud-based App Firewall updates service.
Note

If new signature rules are added during auto-update, they are disabled by default. You should
periodically review the updated signatures and enable the newly added rules that are pertinent
for protecting your applications.

You must configure CORS to host signatures on IIS servers.

Getting started

Using Citrix signatures to protect your application is quite easy and can be accomplished in a few
simple steps:

1. Add a signature object.

• You can use the Wizard that prompts you to create the entire App Firewall configuration, includ-
ing adding the profile and policy, selecting and enabling signatures, and specifying actions for
signatures and positive security checks. The signatures object is created automatically.
• You can create a copy of the signatures object from the *Default Signatures template, use a blank
template to create a new signature with your own customized rules, or add an external format
signature. Enable the rules and configure the actions that you want to apply.

2. Configure the target App Firewall profile to use this signatures object.

3. Send traffic to validate the functionality

Highlights

• The *Default signatures object is a template. It cannot be edited or deleted. To use it, you must
create a copy. In your own copy, you can enable the rules and the desired action for each rule as

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1576

NetScaler 12.0

required for your application. To protect the application, you must configure the target profile
to use this signature.
• Processing signature patterns has overhead. Try to enable only those signatures that are appli-
cable for protecting your application, rather than enabling all signature rules.
• Every pattern in the rule must match to trigger a signature match.
• You can add your own customized rules to inspect incoming requests to detect various types of
attacks, such as SQL injection or cross-site scripting attacks. You can also add rules to inspect
the responses to detect and block leakage of sensitive information such as credit card numbers.
• You can make a copy of an existing signatures object and tweak it, by adding or editing rules
and SQL/XSS patterns, to protect another application.
• You can use auto-update to download the latest version of the App Firewall default rules without
need for ongoing monitoring to check for the availability of the new update.
• A signature object can be used by more than one profile. Even after you have configured one
or more profile(s) to use a signature object, you can still enable or disable signatures or change
the action settings. You can manually create and modify your own custom signature rules. The
changes will apply to all the profiles that are currently configured to use this signature object.
• You can configure signatures to detect violations in various types of payloads, such as HTML,
XML, JSON, and GWT.
• You can export a configured signatures object and import it to another NetScaler appliance for
easy replication of your customized signature rules.

Signatures are patterns that are associated with a known vulnerability. You can use signature protec-
tion to identify the traffic that attempts to exploit these vulnerabilities, and take specific actions.

Signatures are organized into categories. You can optimize the performance and reduce the process-
ing overhead by enabling only the rules in the categories that are appropriate for protecting your ap-
plication.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Manually configuring the signatures feature

September 18, 2018

Contributed by:
C

To use signatures to protect your web sites, you must review the rules, and enable and configure the

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1577

NetScaler 12.0

ones that you want to apply. The rules are disabled by default. Citrix recommends that you enable all
rules that are applicable to the type of content that your web site uses.

To manually configure the signatures feature, use a browser to connect to the GUI. Then, create a
signatures object from a built-in template, an existing signatures object, or by importing a file. Next,
configure the new signatures object as explained in Configuring or Modifying a Signatures Object.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Adding or removing a signatures object

September 18, 2018

Contributed by:
C

You can add a new signatures object to the App Firewall by:

• Copying a built-in template.

• Copying an existing signatures object.
• Importing a signatures object from an external file.

You must use the GUI to copy a template or existing signatures object. You can use either the GUI or
the command line to import a signatures object. You can also use either the GUI or the command line
to remove a signatures object.

To create a signatures object from a template

1. Navigate to Security > Application Firewall > Signatures.

2. In the details pane, select the signatures object that you want to use as a template.

Your choices are:

• Default Signatures. Contains the signatures rules, the SQL injection rules, and the cross-
site scripting rules.
• XPath Injection. Contains the XPath injection patterns.
• Any existing signatures object.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1578

NetScaler 12.0

Attention:

If you do not choose a signatures type to use as a template, the App Firewall will prompt
you to create signatures from scratch.

3. Click Add.

4. In the Add Signatures Object dialog box, type a name for your new signatures object, and then
click OK. The name can begin with a letter, number, or the underscore symbol, and can consist
of from one to 31 letters, numbers, and the hyphen (-), period (.) pound (#), space ( ), at (@),
equals (=), and underscore (_) symbols.

5. Click Close.

To create a signatures object by importing a file

1. Navigate to Security > Application Firewall > Signatures.

2. In the details pane, click Add.
3. In the Add Signatures Object dialog box, select the format of the signatures you want to import.
• To import a NetScaler format signatures file, select the Native Format tab.
• To import an external signatures format file, select the External Format tab.
4. Choose the file that you want to use to create your new signatures object.
• To import a native NetScaler format signatures file, in the Import section select either Im-
port from Local File or Import from URL, then type or browse to the path or URL to the
file.
• To import a Cenzic, IBM AppScan, Qualys, or Whitehat format file, in the XSLT section select
Use Built-in XSLT File, Use Local File, or Reference from URL. Next, if you chose Use Built-in
XSLT File, select the appropriate file format from the drop-down list. If you chose Use Local
File or Reference from URL, then type or browse to the path or URL to the file.
5. Click Add, and then click Close.

To create a signatures object by importing a file by using the command line

At the command prompt, type the following commands:

• import appfw signatures <src> <name> [-xslt <string>] [-comment <string

>] [-overwrite] [-merge] [-sha1 <string>]
• save ns config

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1579

NetScaler 12.0

Example #1

The following example creates a new signatures object from a file named signatures.xml and assigns
it the name MySignatures.

1 import appfw signatures signatures.xml MySignatures

2 save ns config

To remove a signatures object by using the GUI

1. Navigate to Security > Application Firewall > Signatures.

2. In the details pane, select the signatures object that you want to remove.
3. Click Remove.

To remove a signatures object by using the command line

At the command prompt, type the following commands:

• rm appfw signatures <name>

• save ns config

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Configuring or modifying a signatures object

September 18, 2018

Contributed by:
C

You configure a signatures object after creating it, or modify an existing signatures object, to enable
or disable signature categories or specific signatures, and configure how the App Firewall responds
when a signature matches a connection.

To configure or modify a signatures object

1. Navigate to Security > Application Firewall > Signatures.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1580

NetScaler 12.0

2. In the details pane, select the signatures object that you want to configure, and then click Open.

3. In the Modify Signatures Object dialog box, set the Display Filter Criteria options at the left
to display the filter items that you want to configure.

As you modify these options, the results that you requested are displayed in the Filtered Results win-
dow at the right.

1 - To display only selected categories of signatures, check or clear

the appropriate signature-category check boxes. The signature
categories are:
2
3 | Name | Type of Attack that this Signature Protects Against
|
4 | ----------- |
----------------------------------------------------------------------
|
5 | cgi | CGI scripts. Includes Perl and UNIX shell scripts.
|
6 | client | Browsers and other clients.
|
7 | coldfusion | Web sites that use the Adobe Systems ColdFusion
application server. |
8 | frontpage | Web sites that use Microsoft ’ s FrontPage server.
|
9 | iis | Web sites that use the Microsoft Internet
Information Server (IIS). |
10 | misc | Miscellaneous attacks.
|
11 | php | Web sites that use PHP
|
12 | web-activex | Web sites that contain ActiveX controls.
|
13 | web-struts | Web sites that contain Apache struts, which are
java-ee based applets. |
14 - To display only signatures that have specific check actions enabled,
select the ON check box for each of those actions, clear the ON
check boxes for the other actions, and clear all of the OFF check
boxes. To display only signatures that have a specific check action
disabled, select their respective OFF check boxes and clear all of
the ON check boxes. To display signatures regardless of whether they
have a check action enabled or disabled, select or clear both the
ON and the OFF check boxes for that action. The check actions are:
15 | Criterion | Description

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1581

NetScaler 12.0

16 | --------- |
--------------------------------------------------------------------------
|
17 | Enabled | The signature is enabled. The App Firewall checks
only for signatures that are enabled when it processes traffic.
|
18 | Block | Connections that match this signature are blocked.

|
19 | Log | A log entry is produced for any connection that
matches this signature.
|
20 | Stats | The App Firewall includes any connection that matches
this signature in the statistics that it generates for that
check. |
21 - To display only signatures that contain a specific string, type the
string into the text box under the filter criteria, and then click
Search.
22 - To reset all display filter criteria to the default settings and
display all signatures, click Show All.

1. For information about a specific signature, select the signature, and then click the blue double
arrow in the More field. The Signature Rule Vulnerability Detail message box appears. It con-
tains information about the purpose of the signature and provides links to external web-based
information about the vulnerability or vulnerabilities that this signature addresses. To access
an external link, click the blue double arrow to the left of the description of that link.

2. Configure the settings for a signature by selecting the appropriate check boxes.

3. If you want to add a local signature rule to the signatures object, or modify an existing local
signature rule, see “The Signatures Editor.”

4. If you have no need for SQL injection, cross-site scripting, or Xpath injection patterns, click OK,
and then click Close. Otherwise, in the lower left-hand corner of the details pane, click Manage
SQL/XSS Patterns.

5. In the Manage SQL/XSS Patterns dialog box, Filtered Results window, navigate to the pattern
category and pattern that you want to configure. For information about the SQL injection pat-
terns, see “HTML SQL Injection Check.” For information about the cross-site scripting patterns,
see “HTML Cross-Site Scripting Check.

6. To add a new pattern:

a) Select the branch to which you want to add the new pattern.
b) Click the Add button directly below the lower section of the Filtered Results window.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1582

NetScaler 12.0

c) In the Create Signature Item dialog box, fill in the Element text box with the pattern that
you want to add. If you are adding a transformation pattern to the transform rules branch,
under Elements, fill in the From text box with the pattern that you want to change and the
To text box with the pattern to which you want to change the previous pattern.
d) Click OK.

7. To modify an existing pattern:

a) In the Filtered Results window, select the branch that contains the pattern that you want
to modify.
b) In the detail window beneath the Filtered Results window, select the pattern that you
want to modify.
c) Click Modify.
d) In the Modify Signature Item dialog box, Element text box, modify the pattern. If you
are modifying a transformation pattern, you can modify either or both patterns under Ele-
ments, in the From and the To text boxes.
e) Click OK.

8. To remove a pattern, select the pattern that you want to remove, then click the Remove button
below the details pane beneath the Filtered Results window. When prompted, confirm your
choice by clicking Close.

9. To add the patterns category to the XSS branch:

a) Select the branch to which you want to add the patterns category.
b) Click the Add button directly below the Filtered Results window.

Note: Currently you can add only one category, named patterns, to the XSS branch, so after
you click Add,you must accept the default choice, which is patterns.

3. Click OK.

10. To remove a branch, select that branch, and then click the Remove button directly below the
Filtered Results window. When prompted, confirm your choice by clicking OK.

Note: If you remove a default branch, you remove all of the patterns in that branch. Doing
so can disable the security checks that use that information.

11. When you are finished modifying the SQL injection, cross-site scripting, and XPath injection pat-
terns, click OK, and then click Close to return to the Modify Signatures Object dialog box.

12. Click OK at any point to save your changes, and when you are finished configuring the signatures
object, click Close.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1583

NetScaler 12.0

4. App Firewall

Protecting JSON applications using signatures

September 18, 2018

Contributed by:
C

JavaScript Object Notation (JSON) is a text-based open standard derived from the JavaScript scripting
language. JSON is preferred for human readable representation of simple data structures and associa-
tive arrays, called objects. It serves as an alternative to XML and is primarily used to transmit serialized
data structures for communicating with web applications. The JSON files are typically saved with a
.json extension.

The JSON payload is typically sent with the MIME type specified as application/json. The other “stan-
dard” content types for JSON are:

• application/x-javascript
• text/javascript
• text/x-javascript
• text/x-json

Using the NetScaler App Firewall signatures to protect JSON applications

To allow JSON requests, the appliance is preconfigured with the JSON content type as shown in the
following show-command output:

1 > sh appfw jsonContentType

2 1)      JSONContenttypevalue:  ”^application/json$” IsRegex:  REGEX
3 Done

The NetScaler App Firewall processes the post body for the following content-types only:

• application/x-www-form-urlencoded
• multipart/form-data
• text/x-gwt-rpc

The requests that are received with other content-type headers including application/json (or any
other allowed content type) are forwarded to the backend after header inspection. The post body in
such requests is not inspected for security check violations even when the profile’s security checks
such as SQL or XSS are enabled.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1584

NetScaler 12.0

In order to protect JSON applications and detect violations, App Firewall signatures can be used. All
requests that contain the allowed content-type header are processed by the App Firewall for signature
match. You can add your own customized signature rules to process JSON payload to perform various
security check inspections (for example, XSS, SQL, and Field Consistency), to detect violations in the
headers as well as the post body, and take specified actions.

Tip

Unlike the other built-in defaults, the preconfigured JSON content type can be edited or removed
by using the CLI or the GUI (GUI). If legitimate requests for JSON applications are getting blocked
and triggering content-type violations, check to make sure that the content type value is con-
figured accurately. For additional details regarding how App Firewall processes content-type
header, see Content type protection

To add or remove JSON content-type by using the command line interface

At the command prompt, type one of the following commands:

add appfw jsonContentType ^application/json$ IsRegEx REGEX

rm appfw JSONContentType ”^application/json$”

To managing JSON content types by using the GUI

Navigate to Security > App Firewall and, in the Settings section, select Manage JSON Content
Types.

In the Configure App Firewall JSON Content Type panel, add, edit, or delete JSON content types to
suit the needs of your applications.

Configuring signature protection to detect attacks in JSON payload

In addition to a valid JSON content type, you need to configure signatures to specify the pattern(s)
that, when detected in a JSON request, indicate a security breach. The specified actions, such as
block and log, are taken when an incoming request triggers a match for all the target patterns in the
signature rule.

To add a customized signature rule, Citrix recommends that you use the GUI. Navigate to System >
Security > App Firewall > Signatures. Double click the target signature object to access the Edit App
Firewall Signatures panel. Click on the Add button to configure the actions, category, log string, rule
patterns and so on. Although App Firewall inspects all allowed content-type payload for signature
match, you can optimize the processing by specifying the JSON expression in the rule. When you

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1585

NetScaler 12.0

Add a new rule pattern, select Expression in the drop-down options for Match and provide the target
match expression from your JSON payload to identify the specific requests that need to be inspected.
An expression must begin with a TEXT. prefix. You can add other rule patterns to specify additional
match patterns to identify the attack.
The following example shows a signature rule. If any cross-site script tag is detected in the POST body
of the JSON payload that matches the specified XPATH_JSON expression, a signature match is trig-
gered.

Example of a signature to detect XSS in JSON payload

1 <SignatureRule actions=”log,stats” category=”JSON” enabled=”ON” id=”

1000001” severity=”” source=”” type=”” version=”1”>
2
3   <PatternList>
4
5     <RequestPatterns>
6
7       <Pattern>
8
9         <Location area=”HTTP_POST_BODY”/>
10
11         <Match type=”Expression”>TEXT.XPATH_JSON(xp%/glossary/title%).
CONTAINS(”example glossary”)</Match>
12
13       </Pattern>
14
15       <Pattern>
16
17         <Location area=”HTTP_METHOD”/>
18
19         <Match type=”LITERAL”>POST</Match>
20
21       </Pattern>
22
23       <Pattern>
24
25         <Location area=”HTTP_POST_BODY”/>
26
27         <Match type=”CrossSiteScripting”/>
28
29        </Pattern>
30
31     </RequestPatterns>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1586

NetScaler 12.0

32
33   </PatternList>
34
35   <LogString>Cross-site scripting violation detected in json payload</
LogString>
36
37   <Comment/>
38
39 </SignatureRule>

Example of the payload

The following payload triggers the signature match, because it includes the cross-site scripting tag
<Gotcha!!>.

1 {
2 ”glossary”: {
3 ”title”: ”example glossary”,”GlossDiv”: {
4 ”title”: ”S”,”GlossList”: {
5 ”GlossEntry”: {
6 ”ID”: ”SGML”,”SortAs”: ”SGML”,”GlossTerm”: ”Standard Generalized
Markup Language”,”Acronym”: ”SGML”,”Abbrev”: ”ISO 8879:1986”,”
GlossDef”: {
7 ”para”: ”A meta-markup language, used to create markup languages **<
Gotcha!!>** such as DocBook.”,”GlossSeeAlso”: [”GML”, ”XML”] }
8 ,”GlossSee”: ”markup” }
9 }
10 }
11 }
12 }

Example of the log message

1 Aug 21 12:21:42 <local0.info> 10.217.31.239 08/21/2015:23:21:42 GMT ns

0-PPE-1 : APPFW APPFW_SIGNATURE_MATCH 1471 0 :  10.217.253.62 990-
PPE0 NtJnVMNnvPeQJnaUzXYW/GTvAQsA010 prof1 http://10.217.31.212/FFC/
login_post.php Signature violation rule ID 1000001: cross-site
scripting violation detected in json payload  <not blocked>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1587

NetScaler 12.0

Note

If you send the same payload after removing the cross-site script tag (<Gotcha!!>), the signature
rule match is not triggered.

Highlights

• To protect JSON payload, use App Firewall signatures to detect XSS, SQL and other violations.
• Verify that the JSON content type is configured on the appliance as the allowed content type.
• Make sure that the content type in the payload matches the configured JSON content type.
• Make sure that all the patterns configured in the signature rule match for the signature violation
to be triggered.
• When you add a signature rule, it MUST have at least one Rule pattern to match the Expression
in the JSON payload. All the PI expressions in signature rules must start with the prefix TEXT.
and must be Boolean.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Updating a signatures object

September 18, 2018

Contributed by:
C

You should update your signatures objects frequently to ensure that your App Firewall is providing pro-
tection against current threats. You should regularly update both the default App Firewall signatures
and any signatures that you import from a supported vulnerability scanning tool.

Citrix regularly updates the default signatures for the App Firewall. You can update the default signa-
tures manually or automatically. In either case, ask your Citrix representative or Citrix reseller for the
URL to access the updates. You can enable automatic updates of the Citrix native format signatures
in the “Engine Settings” and “Signature Auto Update Settings” dialog boxes.

Most makers of vulnerability scanning tools regularly update the tools. Most web sites also change
frequently. You should update your tool and rescan your web sites regularly, exporting the resulting
signatures to a file and importing them into your App Firewall configuration.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1588

NetScaler 12.0

Tip

When you update the App Firewall signatures from the NetScaler command line, you must first
update the default signatures, and then issue additional update commands to update each cus-
tom signatures file that is based on the default signatures. If you do not update the default sig-
natures first, a version mismatch error prevents updating of the custom signatures files.
Note

The following applies to merging a third-party signature object with a user-defined signature
object with Native rules and user-added rules:

When a version 0 signatures is merged with a new imported file, the resultant signatures will
remain as version 0.

This means all native (or built-in) rules in the imported file will be ignored after the merge. This
is to ensure that the version 0 signatures are maintained as is after a merge.

In order to include the native rules in the imported file for merge, you should update the existing
signatures from version 0 first before the merge. This means you need to abandon the version
0 nature of the existing signatures.

To update the App Firewall signatures from the source by using the command line

At the command prompt, type the following commands:

• update appfw signatures <name> [-mergedefault]
• save ns config

Example

The following example updates the signatures object named MySignatures from the default signa-
tures object, merging new signatures in the default signatures object with the existing signatures.
This command does not overwrite any user-created signatures or signatures imported from another
source, such as an approved vulnerability scanning tool.

1 update appfw signatures MySignatures -mergedefault

2 save ns config

Updating a signatures object from a Citrix format file

Citrix regularly updates the signatures for the App Firewall. You should regularly update the signatures
on your App Firewall to ensure that your App Firewall is using the most current list. Ask your Citrix
representative or Citrix reseller for the URL to access the updates.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1589

NetScaler 12.0

To update a signatures object from a Citrix format file by using the command line

At the command prompt, type the following commands:

• update appfw signatures <name> [-mergeDefault]

• save ns config

To update a signatures object from a Citrix format file by using the GUI

1. Navigate to Security > App Firewall > Signatures.

2. In the details pane, select the signatures object that you want to update.
3. In the Action drop-down list, select Merge.
4. In the Update Signatures Object dialog box, choose one of the following options.
• Import from URL—Choose this option if you download signature updates from a web URL.
• Import from Local File—Choose this option if you import signature updates from a file on
your local hard drive, network hard drive, or other storage device.
5. In the text area, type the URL, or type or browse to the local file.
6. Click Update. The update file is imported, and the Update Signatures dialog box changes to a
format nearly identical to that of the Modify Signatures Object dialog box. The Update Signa-
tures Object dialog box displays all branches with new or modified signature rules, SQL injec-
tion or cross-site scripting patterns, and XPath injection patterns if there are any.
7. Review and configure the new and modified signatures.
8. When you are finished, click OK, and then click Close.

Updating a signatures object from a supported vulnerability scanning tool

Note: Before you update a signatures object from a file, you must create the file by exporting
signatures from the vulnerability scanning tool.

To import and update signatures from a vulnerability scanning tool

1. Navigate to Security > App Firewall > Signatures.

2. In the details pane, select the signatures object that you want to update, and then click Merge.
3. In the Update Signatures Object dialog box, on the External Format tab, Import section,
choose one of the following options.
• Import from URL—Choose this option if you download signature updates from a Web URL.
• Import from Local File—Choose this option if you import signature updates from a file on
your local or a network hard drive or other storage device.
4. In the text area, type the URL, or browse or type the path to the local file.
5. In the XSLT section, choose one of the following options.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1590

NetScaler 12.0

• Use Built-in XSLT File—Choose this option if you want to use a built-in XSLT files.
• Use Local XSLT File—Choose this option to use an XSLT file on your local computer.
• Reference XSLT from URL—Choose this option to import an XSLT file from a web URL.
6. If you chose Use Built-in XSLT File, in the Built-In XSLT drop-down list select the file that you want
to use from the following options:
• Cenzic.
• Deep_Security_for_Web_Apps.
• Hewlett_Packard_Enterprise_WebInspect.
• IBM-AppScan-Enterprise.
• IBM-AppScan-Standard.
• Qualys.
• Whitehat.
7. Click Update. The update file is imported, and the Update Signatures dialog box changes to a
format nearly identical to that of the Modify Signatures Object dialog box, which is described
in “Configuring or Modifying a Signatures Object.” The Update Signatures Object dialog box
displays all branches with new or modified signature rules, SQL injection or cross-site scripting
patterns, and XPath injection patterns if there are any.
8. Review and configure the new and modified signatures.
9. When you are finished, click OK, and then click Close.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Exporting a signatures object to a file

September 18, 2018

Contributed by:
C

You export a signatures object to a file so that you can import it to another NetScaler.

To export a signatures object to a file

1. Navigate to Security > Application Firewall > Signatures.

2. In the details pane, select the signatures object that you want to configure.
3. In the Actions drop-down list, select Export.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1591

NetScaler 12.0

4. In the Export Signatures Object dialog box, Local File text box, type the path and name of the
file to which you want to export the signatures object, or use the Browse dialog to designate a
path and name.
5. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

The Signatures editor

September 18, 2018

Contributed by:
C

You can use the signatures editor, which is available in the GUI, to add a new user-defined (local) sig-
nature rule to an existing signatures object, or to modify a previously configured local signature rule.
Except that it is defined by the user (you), a local signature rule has the same attributes as a default
signature rule from Citrix, and it functions in the same way. You enable or disable it, and configure
the signature actions for it, just as you do for a default signature.

Add a local rule if you need to protect your web sites and services from a known attack that the existing
signatures do not match. For example, you might discover a new type of attack and determine its
characteristics by examining the logs on your web server, or you might obtain third-party information
about a new type of attack.

At the heart of a signature rule are the rule patterns, which collectively describe the characteristics
of the attack that the rule is designed to match. Each pattern can consist of a simple string, a PCRE-
format regular expression, or the built-in SQL injection or cross-site scripting patterns.

You might want to modify a signature rule by adding a new pattern or modifying an existing pattern to
match an attack. For example, you might find out about changes to an attack, or you might determine
a better pattern by examining the logs on your web server, or from third-party information.

To add or modify a local signature rule by using the Signatures Editor

1. Navigate to Security > Application Firewall > Signatures.

2. In the details pane, select the signatures object that you want to edit, and then click Open.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1592

NetScaler 12.0

3. In the Modify Signatures Object dialog box, in the middle of the screen beneath the Filtered
Results window, do one of the following:

• To add a new local signature rule, click Add.

• To modify an existing local signature rule, select that rule, and then click Open.

4. In the Add Local Signature Rule or the Modify Local Signature Rule dialog box, configure the
actions for a signature by selecting the appropriate check boxes.

• Enabled. Enables the new signature rule. If you do not select this, this new signature rule
is added to your configuration, but is inactive.
• Block. Blocks connections that violate this signature rule.
• Log. Logs violations of this signature rule to the NetScaler log.
• Stat. Includes violations of this signature rule in the statistics.
• Remove. Strips information that matches the signature rule from the response. (Applies
only to response rules.)
• X-Out. Masks information that matches the signature rule with the letter X. (Applies only
to response rules.)
• Allow Duplicates. Allows duplicates of this signature rule in this signatures object.

5. Choose a category for the new signature rule from the Category drop-down list.

You can also create a new category by clicking the icon to the right of the list and using the Add
Signature Rule Category dialog box to add a new category to the list, The rule you are modify-
ing is automatically added to the new category. For instructions, see “To add a signature rule
category.”

6. In the LogString text box, type a brief description of the signature rule to be used in the logs.

7. In the Comment text box, type a comment. (Optional)

8. Click More…, and modify the advanced options.

a) To strip HTML comments before applying this signature rule, in the Strip Comments drop-
down list choose All or Exclude Script Tag.
b) To set CSRF Referer Header checking, in the CSRF Referer Header checking radio button
array, select either the If Present or Always radio button.
c) To manually modify the Rule ID assigned to this local signature rule, modify the number in
the Rule ID text box. The ID must be a positive integer between 1000000 and 1999999 that
has not already been assigned to a local signature rule.
d) To assign a version number to the new signature rule, modify the number in the Version
Number text box.
e) To assign a Source ID, modify the string in the Source ID text box.
f) To specify the source, choose Local or Snort from the Source drop-down list, or click the
Add icon to the right of the list and add a new source.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1593

NetScaler 12.0

g) To assign a harm score to violations of this local signature rule, type a number between 1
and 10 in the Harm Score text box.
h) To assign a severity rating to this local signature rule, in the Severity drop-down list choose
High, Medium, or Low, or click the Add icon to the right of the list and add a new severity
rating.
i) To assign a violation type to this local signature rule, in the Type drop-down list choose
Vulnerable or Warning, or click the Add icon to the right of the list and add a new violation
type.

9. In the Patterns list, add or edit a pattern.

• To add a pattern, click Add. In the Create New Signature Rule Pattern dialog box, add
one or more patterns for your signature rule, and then click OK.
• To edit a pattern, select the pattern, and then click Open. In the Edit Signature Rule Pat-
tern dialog box, modify the pattern, and then click OK.

For more information about adding or editing patterns, see “Signature Rule Patterns.”

10. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

To add a signature rule category

September 18, 2018

Contributed by:
C

Putting signature rules into a category enables you to configure the actions for a group of signatures
instead of for each individual signature. You might want to do so for the following reasons:

• Ease of selection. For example, assume that all of signature rules in a particular group protect
against attacks on a specific type of web server software or technology. If your protected web
sites use that software or technology, you want to enable them all. If they do not, you do not
want to enable any of them.
• Ease of initial configuration. It is easiest to set defaults for a group of signatures as a category,
instead of one-by-one. You can then make any changes to individual signatures as needed.
• Ease of ongoing configuration. It is easier to configure signatures if you can display only those
that meet specific criteria, such as belonging to a specific category.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1594

NetScaler 12.0

1. Navigate to Security > App Firewall > Signatures.

2. In the details pane, select that signatures object that you want to configure, and then click Open.
3. In the Modify Signatures Object dialog box, in the middle of the screen, beneath the Filtered
Results window, click Add.
4. In the Add Local Signature Rule dialog box, click the icon to the right of the Category drop-
down list.
5. In the Add Signature Rule Category dialog box, New Category text box, type a name for your
new signature category. The name can consist of from one to 64 characters.
6. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Signature rule patterns

December 14, 2018

Contributed by:
C

You can add a new pattern to a signature rule or modify an existing pattern of a signature rule to spec-
ify a string or expression that characterizes an aspect of the attack that the signature matches. To
determine which patterns an attack exhibits, you can examine the logs on your web server, use a tool
to observe connection data in real time, or obtain the string or expression from a third-party report
about the attack.
Caution:

Any new pattern that you add to a signature rule is in an

AND relationship with the existing patterns. Do not add a new pattern to an existing signature
rule if you do not want a potential attack to have to match all of the patterns in order to match
the signature.

Each pattern can consist of a simple string, a PCRE-format regular expression, or the built-in SQL in-
jection or cross-site scripting pattern. Before you attempt to add a pattern that is based on a regular
expression, you should make sure that you understand PCRE-format regular expressions. PCRE ex-
pressions are complex and powerful; if you do not understand how they work, you can unintentionally
create a pattern that matches something that you did not want (a false positive) or that fails to match
something that you did want (a false negative).

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1595

NetScaler 12.0

If you are not already familiar with PCRE-format regular expressions, you can use the following re-
sources to learn the basics, or for help with some specific issue:

• “Mastering Regular Expressions”, Third Edition. Copyright (c) 2006 by Jeffrey Friedl. O’Reilly
Media, ISBN: 9780596528126.
• “Regular Expressions Cookbook”. Copyright (c) 2009 by Jan Goyvaerts and Steven Levithan.
O’Reilly Media, ISBN: 9780596520687
• PCRE Man page/Specification (text/official): http://www.pcre.org/pcre.txt
• PCRE Man Page/Specification (html/gammon.edu.au): http://www.gammon.com.au/pcre
/index.html
• Wikipedia PCRE entry: “http://en.wikipedia.org/wiki/PCRE”
• PCRE Mailing List (run by exim.org): http://lists.exim.org/mailman/listinfo/pcre
-dev

If you need to encode non-ASCII characters in a PCRE-format regular expression, the NetScaler plat-
form supports encoding of hexadecimal UTF-8 codes. For more information, see “PCRE Character
Encoding Format.”

To configure a signature rule pattern

1. Navigate to Security > Application Firewall > Signatures.

2. In the details pane, select that signatures object that you want to configure, and then click Open.

3. In the Modify Signatures Object dialog box, in the middle of the screen beneath the Filtered
Results window, either click Add to create a signature rule, or select an existing signature rule
and click Open.
Note:

You can modify only signature rules that you added. You cannot modify the default signa-
ture rules.

Depending on your action, either the Add Local Signature Rule or the Modify Local Signature
Rule dialog box appears. Both dialog boxes have the same contents.

4. Under the Patterns window in the dialog box, either click Add to add a new pattern, or select an
existing pattern from the list beneath the Add button and click Open. Depending on your action,
either the Create New Signature Rule Pattern or the Edit Signature Rule Pattern dialog box
appears. Both dialog boxes have the same contents.

5. In the Pattern Type drop-down list, choose the type of connection that the pattern is intended
to match.

• If the pattern is intended to match request elements or features, such as injected SQL code,
attacks on web forms, cross-site scripts, or inappropriate URLs, choose Request.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1596

NetScaler 12.0

• If the pattern is intended to match response elements or features, such as credit card num-
bers or safe objects, choose Response.

6. In the Location area, define the elements to examine with this pattern.

The Location area describes what elements of the HTTP request or response to examine for this
pattern. The choices that appear in the Location area depend upon the chosen pattern type.
If you chose Request as the pattern type, items relevant to HTTP requests appear; if you chose
Response, items relevant to HTTP responses appear.

In addition, as you choose a value from the Area drop-down list, the remaining parts of the Lo-
cation area change interactively. Following are all configuration items that might appear in this
section.

• Area Drop-down list of elements that describe a particular portion of the HTTP connection.
The choices are as follows:
– HTTP_ANY. All parts of the HTTP connection.
– HTTP_COOKIE. All cookies in the HTTP request headers after any cookie transforma-
tions are performed.
Note: Does not search HTTP response “Set-Cookie:” headers.
– HTTP_FORM_FIELD. Form fields and their contents, after URL decoding, percent de-
coding, and removal of excess whitespace. You can use the <Location> tag to further
restrict the list of form field names to be searched.
– HTTP_HEADER. The value portions of the HTTP header after any cross-site scripting
or URL decoding transformations.
– HTTP_METHOD. The HTTP request method.
– HTTP_ORIGIN_URL. The origin URL of a web form.
– HTTP_POST_BODY. The HTTP post body and the web form data that it contains.
– HTTP_RAW_COOKIE. All HTTP request cookie, including the “Cookie:” name portion.
Note: Does not search HTTP response “Set-Cookie:” headers.
– HTTP_RAW_HEADER. The entire HTTP header, with individual headers separated by
linefeed characters (\n) or carriage return/line-feed strings (\r\n).
– HTTP_RAW_RESP_HEADER. The entire response header, including the name and
value parts of the response header after URL transformation has been done, and
the complete response status. As with HTTP_RAW_HEADER, individual headers are
separated by linefeed characters (\n) or carriage return/line-feed strings (\r\n).
– HTTP_RAW_SET_COOKIE. The entire Set-Cookie header after any URL transforma-
tions have been performed
Note: URL transformation can change both the domain and path parts of the Set-
Cookie header.
– HTTP_RAW_URL. The entire request URL before any URL transformations are per-
formed, including any query or fragment parts.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1597

NetScaler 12.0

– HTTP_RESP_HEADER. The value part of the complete response headers after any URL
transformations have been performed.
– HTTP_RESP_BODY. The HTTP response body
– HTTP_SET_COOKIE. All “Set-Cookie” headers in the HTTP response headers.
– HTTP_STATUS_CODE. The HTTP status code.
– HTTP_STATUS_MESSAGE. The HTTP status message.
– HTTP_URL. The value portion of the URL in the HTTP headers, excluding any query or
fragment ports, after conversion to the UTF-* character set, URL decoding, stripping
of whitespace, and conversion of relative URLs to absolute. Does not include HTML
entity decoding.
• URL
Examines any URLs found in the elements specified by the
Area setting. Select one of the following settingss.
– Any. Checks all URLs.
– Literal. Checks URLs that contain a literal string. After you select Literal, a text box is
displayed. Type the literal string that you want in the text box.
– PCRE. Checks URLs that match a PCRE-format regular expression. After you select
this choice, the regular expression window is displayed. Type the regular expression
in the window. You can use the Regex Tokens to insert common regular expression
elements at the cursor, or you can click Regex Editor to display the Regular Expression
Editor dialog box, which provides more assistance in constructing the regular expres-
sion that you want.
– Expression. Checks URLs that match a NetScaler default expression.
• Field Name
Examines any form field names found in the elements specified by the
Area selection.
– Any. Checks all URLs.
– Literal. Checks URLs that contain a literal string. After you select Literal, a text box is
displayed. Type the literal string that you want in the text box.
– PCRE. Checks URLs that match a PCRE-format regular expression. After you select
this choice, the regular expression window is displayed. Type the regular expression
in the window. You can use the Regex Tokens to insert common regular expression
elements at the cursor, or you can click Regex Editor to display the Regular Expression
Editor dialog box, which provides more assistance in constructing the regular expres-
sion that you want.
– Expression. Checks URLs that match a NetScaler default expression.

7. In the Pattern area, define the pattern. A pattern is a literal string or PCRE-format regular expres-
sion that defines the pattern that you want to match. The Pattern area contains the following
elements:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1598

NetScaler 12.0

• Match
A drop-down list of search methods that you can use for the signature. This list differs
depending on whether the pattern type is Request or Response.

Request Match Types

PCRE. A PCRE-format regular expression.
NOTE: When you choose PCRE, the regular expression tools beneath the Pattern window are enabled.
These tools are not useful for most other types of patterns.

• Injection. Directs the App Firewall to look for injected SQL in the specified location. The Pattern
window disappears, because the App Firewall already has the patterns for SQL injection.

• CrossSiteScripting. Directs the App Firewall to look for cross-site scripts in the specified loca-
tion. The Pattern window disappears, because the App Firewall already has the patterns for
cross-site scripts.

• Expression. An expression in the NetScaler default expressions language. This is the same
expressions language that is used to create App Firewall policies and other policies on the
NetScaler appliance. Although the NetScaler expressions language was originally developed
for policy rules, it is a highly flexible general purpose language that can also be used to define
a signature pattern.

When you choose Expression, the NetScaler Expression Editor appears beneath Pattern window. For
more information about the Expression Editor and instructions on how to use it, see “To add a firewall
rule (expression) by using the Add Expression dialog box

Response Match Types:

• Literal. A literal string

• PCRE. A PCRE-format regular expression.

NOTE:

When you choose PCRE, the regular expression tools beneath the Pattern window are enabled.
These tools are not useful for most other types of patterns.

• Credit Card. A built-in pattern to match one of the six supported types of credit card number.

Note: The Expression match type is not available for Response-side signatures.

• Pattern Window (unlabeled)

In this window, type the pattern that you want to match, and fill in any additional data.

1 - Literal. Type the string you want to search for in the text area.
2 - PCRE. Type the regular expression in the text area. Use the **Regex
Editor** for more assistance in constructing the regular expression
that you want, or the Regex Tokens to insert common regular

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1599

NetScaler 12.0

expression elements at the cursor. To enable UTF-8 characters, click

UTF-8.
3 - Expression. Type the NetScaler advanced expression in the text area.
Use Prefix to choose the first term in your expression, or Operator
to insert common operators at the cursor. Click **Add** to open the
Add Expression dialog box for more assistance in constructing the
regular expression that you want. Click Evaluate to open the
Advanced Expression Evaluator to help determine what effect your
expression has.
4 - Offset. The number of characters to skip over before starting to
match on this pattern. You use this field to start examining a
string at some point other than the first character.
5 - Depth. How many characters from the starting point to examine for
matches. You use this field to limit searches of a large string to a
specific number of characters.
6 - Min-Length. The string to be searched must be at least the specified
number of bytes in length. Shorter strings are not matched.
7 - Max-Length. The string to be searched must be no longer than the
specified number of bytes in length. Longer strings are not matched.
8 - Search method. A check box labeled fastmatch. You can enable
fastmatch only for a literal pattern, to improve performance.

1. Click OK.

2. Repeat the previous four steps to add or modify additional patterns.

3. When finished adding or modifying patterns, click OK to save your changes and return to the
Signatures pane.

Caution:

Until you click OK in the Add Local Signature Rule or Modify Local Signature Rule dialog
box, your changes are not saved. Do not close either of these dialog boxes without clicking
OK unless you want to discard your changes.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Import and merge signature rules

March 28, 2019

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1600

NetScaler 12.0

Contributed by:
C

You can use the signature editor to import and merge rules through the Citrix ADC GUI. You can see all
the new, updated, duplicate, and invalid rules.

The signature editor displays the following in four new rows:

1. New Rules
2. Updated Rules
3. Duplicate Rules
4. Invalid Rules

The output of New Rules Only and Updated Rules Only filters appears in the Category filter pane of
the Edit window in signature editor.

You must import files through the GUI to see the corresponding links for new, duplicate, invalid, and
updated rules.

For example, you can use the Citrix ADC GUI to import the following signature files:

<http://1.1.1.1/testsite/signatures/sig-3100000.xml>.

To import signature rules:

1. In the NetScaler web GUI, go to Configuration > Security > Application Firewall > Signatures.
In the Signatures window, click Add. Then select File Format > Native, Import From >
URL and in the URL field, add the above link. For example; <http://1.1.1.1/testsite/
signatures/sig-3100000.xml>.

2. After you click Open, the signature file will open and you can see links for New Rule and Invalid
Rules.

3. If you import a 3^rd party signature rule from the following site, for example;
<http://1.1.1.1/FFC/sig_validation/trendmicro_sample2.xml> as shown below,
you can see 90 new Rules and nine duplicate Rules in the imported .xml file.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Signature updates in high availability deployment and build upgrades

September 18, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1601

NetScaler 12.0

Contributed by:
C

The signature update occurs on the primary node. While the signatures are updated on the primary
node, in parallel the updated files are simultaneously synchronized with the secondary node.

The *Default signature is always updated first and then the rest of the user-defined signatures are
updated.

Connecting to Amazon AWS

The default route NSIP is used to connect to the Amazon AWS. If there is a specific use case scenario
where SNIP is used, and if there are multiple SNIPs, the first one to receive the ARP response from the
hosting site will hold the route.

Signature updates during version upgrades

In case of an upgrade, if the NS has an older base version for the signatures, *Default signature is
automatically updated if a newer signature version is available.

If the schema has changed, the schema version of all the signature objects gets updated when the
version is upgraded.

However, for the base version of the user-defined signatures, the behavior is different in release 10.5
versus release 11.0.

In release 10.5, only the default signature was updated and the base version of the rest of the signa-
tures remained unchanged after the build upgrade.

In release 11.0, this behavior has changed. When the appliance is upgraded to install a new build, not
only the *Default signature object but all the other user-defined signatures that currently exist in the
appliance are also updated and will have the same version after the build upgrade.

In both 10.5 and 11.0 release builds, if auto-update is configured, the *Default Signatures as well as all
non-zero version signatures get auto-updated to the latest released signature version and will have
the same base version.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1602

NetScaler 12.0

Overview of security checks

September 18, 2018

Contributed by:
C

The App Firewall advanced protections (security checks) are a set of filters designed to catch complex
or unknown attacks on your protected web sites and web services. The security checks use heuris-
tics, positive security, and other techniques to detect attacks that may not be detected by signatures
alone. You configure the security checks by creating and configuring an App Firewall profile, which is
a collection of user-defined settings that tell the App Firewall which security checks to use and how
to handle a request or response that fails a security check. A profile is associated with a signatures
object and with a policy to create a security configuration.

The App Firewall provides twenty security checks, which differ widely in the types of attacks that they
target and how complex they are to configure. The security checks are organized into the following
categories:

• Common security checks. Checks that apply to any aspect of web security that either does not
involve content or is equally applicable to all types of content.
• HTML security checks. Checks that examine HTML requests and responses. These checks ap-
ply to HTML-based web sites and to the HTML portions of Web 2.0 sites, which contain mixed
HTML and XML content.
• XML security checks. Checks that examine XML requests and responses. These checks apply
to XML-based web services and to the XML portions of Web 2.0 sites.

The security checks protect against a wide range of types of attack, including attacks on operation
system and web server software vulnerabilities, SQL database vulnerabilities, errors in the design and
coding of web sites and web services, and failures to secure sites that host or can access sensitive
information.

All security checks have a set of configuration options, the check actions, which control how the App
Firewall handles a connection that matches a check. Three check actions are available for all security
checks. They are:

• Block. Block connections that match the signature. Disabled by default.

• Log. Log connections that match the signature, for later analysis. Enabled by default.
• Stats. Maintain statistics, for each signature, that show how many connections it matched and
provide certain other information about the types of connections that were blocked. Disabled
by default.

A fourth check action, Learn, is available for more than half of the check actions. It observes traffic to
a protected Web site or web service and uses connections that repeatedly violate the security check to

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1603

NetScaler 12.0

generate recommended exceptions (relaxations) to the check, or new rules for the check. In addition
to the check actions, certain security checks have parameters that control the rules that the check
uses to determine which connections violate that check, or that configure the App Firewall’s response
to connections that violate the check. These parameters are different for each check, and they are
described in the documentation for each check.

To configure security checks, you can use the App Firewall wizard, as described in “The App Firewall
Wizard,” or you can configure the security checks manually, as described in “Manual Configuration By
Using the GUI.” Some tasks, such as manually entering relaxations or rules or reviewing learned data,
can be done only by using the GUI, not the command line. Using the wizard is usually best configura-
tion method, but in some cases manual configuration might be easier if you are thoroughly familiar
with it and simply want to adjust the configuration for a single security check.

Regardless of which method you use to configure the security checks, each security check requires
that certain tasks be performed. Many checks require that you specify exceptions (relaxations) to pre-
vent blocking of legitimate traffic before you enable blocking for that security check. You can do this
manually, by observing the log entries after a certain amount of traffic has been filtered and then cre-
ating the necessary exceptions. However, it is usually much easier to enable the learning feature and
let it observe the traffic and recommend the necessary exceptions.

App Firewall uses packet engines (PE) during processing the transactions. Each packet engine has a
limit of 100K sessions which is sufficient for most deployment scenarios. However, when App Fire-
wall is processing heavy traffic and the session timeout is configured at a higher value, the sessions
might get accumulated. If the number of alive App Firewall sessions exceed the 100K per PE limit,
the App Firewall security check violations might not be sent to the Security Insight appliance. Low-
ering the session timeout to a smaller value, or using sessionless mode for the security checks with
sessionless URL closure or sessionless field consistency might help in preventing the sessions getting
accumulated. If this is not a viable option in scenarios where transactions might require longer ses-
sions, upgrading to a higher-end platform with more packet engine is recommended.

Support for cached AppFirewall is added, and the max session setting through the CLI per core is set
to 50K sessions.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Top level protections

November 19, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1604

NetScaler 12.0

Contributed by:
C

Four of the App Firewall protections are especially effective against common types of Web attacks,
and are therefore more commonly used than any of the others. They are:

• HTML Cross-Site Scripting. Examines requests and responses for scripts that attempt to access
or modify content on a different Web site than the one on which the script is located. When this
check finds such a script, it either renders the script harmless before forwarding the request or
response to its destination, or it blocks the connection.

• HTML SQL Injection. Examines requests that contain form field data for attempts to inject SQL
commands into an SQL database. When this check detects injected SQL code, it either blocks
the request or renders the injected SQL code harmless before forwarding the request to the Web
server.

Note: If both of the following conditions apply to your configuration, you should make certain
that your App Firewall is correctly configured:

– If you enable the HTML Cross-Site Scripting check or the HTML SQL Injection check (or
both), and
– Your protected Web sites accept file uploads or contain Web forms that can contain large
POST body data.

For more information about configuring the App Firewall to handle this case, see “Configuring
the Application Firewall.”

• Buffer Overflow. Examines requests to detect attempts to cause a buffer overflow on the Web
server.

• Cookie Consistency. Examines cookies returned with user requests to verify that they match
the cookies your Web server set for that user. If a modified cookie is found, it is stripped from
the request before the request is forwarded to the Web server.

The Buffer Overflow check is simple; you can usually enable blocking for it immediately. The other
three top-level checks are considerably more complex and require configuration before you can safely
use them to block traffic. Citrix strongly recommends that, rather than attempting to configure these
checks manually, you enable the learning feature and allow it to generate the necessary exceptions.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1605

NetScaler 12.0

HTML cross-site scripting check

September 18, 2018

Contributed by:
C

The HTML Cross-Site Scripting (XSS) check examines both the headers and the POST bodies of user
requests for possible cross-site scripting attacks. If it finds a cross-site script, it either modifies (trans-
forms) the request to render the attack harmless, or blocks the request.

To prevent misuse of the scripts on your protected web sites to breach security on your web sites,
the HTML Cross-Site Scripting check blocks scripts that violate the same origin rule, which states that
scripts should not access or modify content on any server but the server on which they are located.
Any script that violates the same origin rule is called a cross-site script, and the practice of using scripts
to access or modify content on another server is called cross-site scripting. The reason cross-site
scripting is a security issue is that a web server that allows cross-site scripting can be attacked with a
script that is not on that web server, but on a different web server, such as one owned and controlled
by the attacker.

Unfortunately, many companies have a large installed base of JavaScript-enhanced web content that
violates the same origin rule. If you enable the HTML Cross-Site Scripting check on such a site, you
have to generate the appropriate exceptions so that the check does not block legitimate activity.

The App Firewall offers various action options for implementing HTML Cross-Site Scripting protection.
In addition to the Block, Log, Stats and Learn actions, you also have the option to Transform cross-
site scripts to render an attack harmless by entity encoding the script tags in the submitted request.
You can configure Check complete URL’s for cross-site scripting parameter to specify if you want to
inspect not just the query parameters but the entire URL to detect XSS attack.

You can deploy relaxations to avoid false positives. The App Firewall learning engine can provide rec-
ommendations for configuring relaxation rules.

Following options are available for configuring an optimized HTML Cross-Site Scripting protection for
your application:

• Block—If you enable block, the block action is triggered if the XSS tags are detected in the re-
quest.
• Log—If you enable the log feature, the HTML Cross-Site Scripting check generates log messages
indicating the actions that it takes. If block is disabled, a separate log message is generated for
each header or form field in which the XSS violation was detected. However, only one message
is generated when the request is blocked. Similarly, one log message per request is generated
for the transform operation, even when XSS tags are transformed in multiple fields. You can

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1606

NetScaler 12.0

monitor the logs to determine whether responses to legitimate requests are getting blocked. A
large increase in the number of log messages can indicate attempts to launch an attack.
• Stats—If enabled, the stats feature gathers statistics about violations and logs. An unexpected
surge in the stats counter might indicate that your application is under attack. If legitimate re-
quests are getting blocked, you might have to revisit the configuration to see if you need to
configure new relaxation rules or modify the existing ones.
• Learn—If you are not sure which relaxation rules might be ideally suited for your application,
you can use the learn feature to generate HTML Cross-Site Scripting rule recommendations
based on the learned data. The App Firewall learning engine monitors the traffic and provides
learning recommendations based on the observed values. To get optimal benefit without com-
promising performance, you might want to enable the learn option for a short time to get a
representative sample of the rules, and then deploy the rules and disable learning.
• Transform cross-site scripts—If enabled, the App Firewall makes the following changes to re-
quests that match the HTML Cross-Site Scripting check:
– Left angle bracket (<) to HTML character entity equivalent (<)
– Right angle bracket (>) to HTML character entity equivalent (>)

This ensures that browsers do not interpret unsafe html tags, such as <script>, and thereby execute
malicious code. If you enable both request-header checking and transformation, any special charac-
ters found in request headers are also modified as described above. If scripts on your protected web
site contain cross-site scripting features, but your web site does not rely upon those scripts to operate
correctly, you can safely disable blocking and enable transformation. This configuration ensures that
no legitimate web traffic is blocked, while stopping any potential cross-site scripting attacks.

• Check complete URLs for cross-site scripting—If checking of complete URLs is enabled, the
App Firewall examines entire URLs for HTML cross-site scripting attacks instead of checking just
the query portions of URLs.
• Check Request headers—If Request header checking is enabled, the App Firewall examines the
headers of requests for HTML cross-site scripting attacks, instead of just URLs. If you use the GUI,
you can enable this parameter in the Settings tab of the App Firewall profile.

Important

As part of the streaming changes, the App Firewall processing of the Cross-site Scripting tags
has changed. This change is applicable to 11.0 builds onwards. This change is also pertinent
for the enhancement builds of 10.5.e that support request side streaming. In earlier releases,
presence of either open bracket (<), or close bracket (>), or both open and close brackets (<>)
was flagged as Cross-site Scripting Violation. The behavior has changed in the builds that include
support for request side streaming. Only the close bracket character (>) is no longer considered
as an attack. Requests are blocked even when an open bracket character (<) is present, and is
considered as an attack. The Cross-site scripting attack gets flagged.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1607

NetScaler 12.0

XSS Fine grained Relaxations

The App Firewall gives you an option to exempt a specific form field, header, or Cookie from cross-site
scripting inspection check. You can completely bypass the inspection for one or more of these fields
by configuring relaxation rules.

The App Firewall allows you to implement tighter security by fine tuning the relaxation rules. An ap-
plication might require the flexibility to allow specific patterns, but configuring a relaxation rule to
bypass the security inspection might make the application vulnerable to attacks, because the target
field is exempted from inspection for any cross-site scripting attack patterns. Cross-site scripting fine
grained relaxation provides the option to allow specific attributes, tags, and patterns. The rest of
the attributes, tags and patterns are blocked. For example, the App Firewall currently has a default
set of more than 125 denied patterns. Because hackers can use these patterns in Cross-site script at-
tacks, the App Firewall flags them as potential threats. You can relax one or more pattern(s) that are
considered safe for the specific location. The rest of the potentially dangerous XSS patterns are still
checked for the target location and continue to trigger the security check violations. You now have
much tighter control.

The commands used in relaxations have optional parameters for Value Type and Value Expression.
The value type can be left blank or you have an option to select Tag or Attribute or Pattern. If you
leave the value type blank, the configured field of the specified URL is exempted from the Cross-Site
Scripting check inspection. If you select a value type, you must provide a value expression. You
can specify whether the value expression is a regular expression or a literal string. When the input
is matched against the allowed and denied list, only the specified expressions configured in the relax-
ation rules are exempted.

The App Firewall has the following XSS built-in lists:

1. XSS Allowed Attributes: There are 52 default allowed attributes, such as, abbr, accesskey,
align, alt, axis, bgcolor, border, cellpadding, cellspacing, char, charoff, charset etc.
2. XSS Allowed Tags: There are 47 default allowed tags, such as, address, basefont, bgsound,
big, blockquote, bg, br, caption, center, cite, dd, del etc.
3. XSS Denied Patterns: There are 129 default denied patterns, such as, FSCommand, javascript:,
onAbort, onActivate etc.

Warning

App Firewall action URL’s are regular expressions. When configuring HTML cross-site scripting
relaxation rules, you can specify Name, and Value Expression to be literal or RegEx. Regular
expressions are powerful. Especially if you are not thoroughly familiar with PCRE-format regular
expressions, double-check any regular expressions you write. Make sure that they define exactly
the rule that you want to add as an exception, and nothing else. Careless use of wildcards, and
especially of the dot-asterisk ( .*) metacharacter/wildcard combination, can have results that you

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1608

NetScaler 12.0

do not want, such as blocking access to web content that you did not intend to block or allowing
an attack that the HTML Cross-Site Scripting check would otherwise have blocked.

Points to Consider:

• Value expression is an optional argument. A field name might not have any value expression.
• A field name can be bound to multiple value expressions.
• Value expressions should be assigned a value type. The XSS value type can be: 1) Tag, 2) At-
tribute, or 3) Pattern.
• You can have multiple relaxation rules per field name/URL combination
• The form field names and the action URL’s are not case sensitive.

Using the Command Line to Configure the HTML Cross-Site Scripting check

To configure HTML Cross-Site Scripting check actions and other parameters by using the command
line

If you use the command-line interface, you can enter the following commands to configure the HTML
Cross-Site Scripting Check:

• set appfw profile “Parameter descriptions provided at bottom of the page.”)

• <name> -crossSiteScriptingAction (([block] [learn] [log] [stats])| [**
none**])
• set appfw profile “Parameter descriptions provided at bottom of the page.”)
• <name> **-crossSiteScriptingTransformUnsafeHTML** (ON | OFF)
• set appfw profile Parameter descriptions provided at bottom of the page.
• <name> -crossSiteScriptingCheckCompleteURLs (ON | OFF)
• set appfw profile Parameter descriptions provided at bottom of the page.
• <name> -checkRequestHeaders (ON | OFF)

To configure a HTML Cross-Site Scripting check relaxation rule by using the command line

Use the bind or unbind command to add or delete binding, as follows:

• bind appfw profile <name> -crossSiteScripting <String> [isRegex (REGEX

| NOTREGEX)] <formActionURL> [-location <location>] [-valueType (
Tag|Attribute|Pattern)[<valueExpression>]    [-isValueRegex (REGEX |
NOTREGEX)]]
• unbind appfw profile <name> -crossSiteScripting <String> <formActionURL
> [-location <location>] [-valueType (Tag |Attribute|Pattern)[<valueExpression
>]]

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1609

NetScaler 12.0

Using the GUI to configure the HTML Cross-Site scripting check

In the GUI, you can configure the HTML Cross-Site Scripting check in the pane for the profile associated
with your application.

To configure or modify the HTML Cross-Site Scripting check by using the GUI

1. Navigate to Application Firewall > Profiles, highlight the target profile, and click Edit.
2. In the Advanced Settings pane, click Security Checks.

The security check table displays the currently configured action settings for all the security checks.
You have 2 options for configuration:

a. If you just want to enable or disable Block, Log, Stats, and Learn actions for the HTML Cross-Site
Scripting, you can select or clear check boxes in the table, click OK, and then click Save and Close to
close the Security Check pane.

b. If you want to configure additional options for this security check, double click HTML Cross-Site
Scripting, or select the row and click Action Settings, to display the following options:

Transform cross-site scripts—Transform unsafe script tags.

Check complete URLs for Cross-site scripting—Instead of checking just the query part of the URL,
check the complete URL for cross-site script violations.

After changing any of the above settings, click OK to save the changes and return to the Security
Checks table. You can proceed to configure other security checks if needed. Click OK to save all the
changes you have made in the Security Checks section, and then click Save and Close to close the
Security Check pane.

To enable or disable the Check request Header setting, in the Advanced Settings pane, click Profile
Settings. In Common Settings, Select or clear the Check Request Headers check box. Click OK. You
can either use the X icon at the top right hand side of the Profile Settings pane to close this section
or, if you have finished configuring this profile, you can click Done to return to the Application Fire-
wall > Profile

To configure a HTML Cross-Site Scripting relaxation rule by using the GUI

1. Navigate to Application Firewall > Profiles, highlight the target profile, and click Edit.
2. In the Advanced Settings pane, click Relaxation Rules.
3. In the Relaxation Rules table, double-click the HTML Cross-Site Scripting entry, or select it and
click Edit.
4. In the HTML Cross-Site Scripting Relaxation Rules dialogue box, perform Add, Edit, Delete,
Enable, or Disable operations for relaxation rules.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1610

NetScaler 12.0

Note

When you add a new rule, the Value Expression field is not displayed unless you select Tag or
Attribute or Pattern option in the Value Type Field.

To manage HTML Cross-Site Scripting relaxation rules by using the visualizer

For a consolidated view of all the relaxation rules, you can highlight the HTML Cross-Site Scripting
row in the Relaxation Rules table, and click Visualizer. The visualizer for deployed relaxations offers
you the option to Add a new rule or Edit an existing one. You can also Enable or Disable a group of
rules by selecting a node and clicking the corresponding buttons in the relaxation visualizer.

To view or customize the Cross-Site Scripting patterns by using the GUI

You can use the GUI to view or customize the default list of XSS allowed attributes or allowed tags. You
can also view or customize the default list of XSS denied Patterns.

The default lists are specified in Application Firewall > Signatures > Default Signatures. If you do
not bind any signature object to your profile, the default XSS allowed and denied list specified in the
Default Signatures object will be used by the profile for the Cross-Site Scripting security check process-
ing. The Tags, Attributes, and Patterns, specified in the default signatures object, are read-only. You
cannot edit or modify them. If you want to modify or change these, make a copy of the Default Signa-
tures object to create a User-Defined signature object. Make changes in the allowed or denied lists in
the new User-defined signature object and use this signature object in your profile that is processing
the traffic for which you want to use these customized allowed and denied lists.

For more information about Signatures, see the following topic..

1. To view default XSS patterns:

a. Navigate to Application Firewall > Signatures, select *Default Signatures, and click Edit. Then
click Manage SQL/XSS Patterns.

The Manage SQL/XSS Paths table shows following three rows pertaining to XSS :

xss/allowed/attribute

xss/allowed/tag

xss/denied/pattern

b. Select a row and click Manage Elements to display the corresponding XSS Elements (Tag, Attribute,
Pattern) used by the App Firewall Cross-Site Scripting check.

1. To customize XSS Elements: You can edit the User-Defined signature object to customize the
allowed Tag, allowed Attributes and denied Patterns. You can add new entries or remove the
existing ones.

a. Navigate to Application Firewall > Signatures, highlight the target User-defined signature, and
click Edit. Click Manage SQL/XSS Patterns to display the Manage SQL/XSS paths table.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1611

NetScaler 12.0

b. Select the target XSS row.

i. Click Manage Elements, to Add, Edit or Remove the corresponding XSS element.

ii. Click Remove to remove the selected row.

Warning

You must be very careful before you remove or modify any default XSS element, or delete the XSS
path to remove the entire row. The signature rules as well as the Cross-Site Scripting security
check rely on these elements for detecting attacks to protect your applications. Customizing the
XSS Elements can make your application vulnerable to Cross-Site Scripting attacks if the required
pattern is removed during editing.

Using the Learn Feature with the HTML Cross-Site Scripting Check

When the learn action is enabled, the App Firewall learning engine monitors the traffic and learns the
triggered violations. You can periodically inspect these learned rules. After due consideration, you
can deploy the learned rule as a HTML Cross-Site Scripting relaxation rule.

HTML Cross-Site Scripting Learning enhancement—An App Firewall learning enhancement was in-
troduced in release 11.0 of the NetScaler software. To deploy fine grained HTML Cross-Site Scripting
relaxation, the App Firewall offers fine grained HTML Cross-Site Scripting learning. The learning en-
gine makes recommendations regarding the observed Value Type (Tag, Attribute, Pattern) and the
corresponding Value expression observed in the input fields. In addition to checking the blocked re-
quests to determine whether the current rule is too restrictive and needs to be relaxed, you can review
the rules generated by the learning engine to determine which value type and value expressions are
triggering violations and need to be addressed in relaxation rules.

Note

The App Firewall’s learning engine can distinguish only the first 128 bytes of the name. If a form
has multiple fields with names that match for the first 128 bytes, the learning engine might not
be able to distinguish between them. Similarly, the deployed relaxation rule might inadvertently
relax all such fields from HTML Cross-Site Scripting inspection.
Tip

XSS tags which are longer than 12 characters are not learned or logged correctly.

If you need a larger taglength for learning, you can add a large non-appearing tag in
the AS_XSS_ALLOWED_TAGS_LIST for length ‘x’.

To view or use learned data by using the command line interface

At the command prompt, type one of the following commands:

• show appfw learningdata <profilename> crossSiteScripting

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1612

NetScaler 12.0

• rm appfw learningdata <profilename> -crossSiteScripting <string>  <

formActionURL>  [<location>]  [<valueType>  <valueExpression>]
• export appfw learningdata <profilename> **crossSiteScripting*

To view or use learned data by using the GUI

1. Navigate to Application Firewall > Profiles, highlight the target profile, and click Edit.
2. In the Advanced Settings pane, click Learned Rules. You can select the HTML Cross-Site
Scripting entry in the Learned Rules table and double-click it to access the learned rules. The
table displays the Field Name, Action URL, Value Type, Value and Hits columns. You can
deploy the learned rules or edit a rule before deploying it as a relaxation rule. To discard a rule,
you can select it and click the Skip button. You can edit only one rule at a time, but you can
select multiple rules to deploy or skip.

You also have the option to show a summarized view of the learned relaxations by selecting the HTML
Cross-Site Scripting entry in the Learned Rules table and clicking Visualizer to get a consolidated
view of all the learned violations. The visualizer makes it very easy to manage the learned rules. It
presents a comprehensive view of the data on one screen and facilitates taking action on a group of
rules with one click. The biggest advantage of the visualizer is that it recommends regular expressions
to consolidate multiple rules. You can select a subset of these rules, based on the delimiter and Action
URL. You can display 25, 50, or 75 rules in the visualizer, by selecting the number from a drop-down
list. The visualizer for learned rules offers the option to edit the rules and deploy them as relaxations.
Or you can skip the rules to ignore them.

Using the Log Feature with the HTML Cross-Site Scripting Check

When the log action is enabled, the HTML Cross-Site Scripting security check violations are logged in
the audit log as APPFW_XSS violations. The App Firewall supports both Native and CEF log formats.
You can also send the logs to a remote syslog server.

To access the log messages by using the command line

Switch to the shell and tail the ns.logs in the /var/log/ folder to access the log messages pertaining to
the HTML Cross-Site Scripting violations:

Shell
tail -f /var/log/ns.log | grep APPFW_XSS

Example of a Cross-Site Scripting security check violation log message in CEF log format

1 Jul 11 00:45:51 <local0.info> 10.217.31.98 CEF:0|Citrix|NetScaler|NS11

.0|APPFW|**APPFW_XSS**|6|src=10.217.253.62 geolocation=Unknown spt
=4840 method=GET request=http://aaron.stratum8.net/FFC/
CreditCardMind.html?abc\=%3Cdef%3E msg=**Cross-site script check
failed for field abc=\”Bad tag: def”** cn1=133 cn2=294 cs1=pr_ffc

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1613

NetScaler 12.0

cs2=PPE1 cs3=eUljypvLa0BbabwfGVE52Sewg9U0001 cs4=ALERT cs5=2015 act

=**not blocked**

Example of a Cross-Site Scripting security check violation log message in Native log format showing
transform action

1 Jul 11 01:00:28 <local0.info> 10.217.31.98 07/11/2015:01:00:28 GMT ns

0-PPE-0 : default APPFW **APPFW_XSS** 132 0 :  10.217.253.62 392-
PPE0 eUljypvLa0BbabwfGVE52Sewg9U0001 pr_ffc http://aaron.stratum8.
net/FFC/login.php?login_name=%3CBOB%3E&passwd=&drinking_pref=on &
text_area=&loginButton=ClickToLogin&as_sfid=
AAAAAAVFqmYL68IGvkrcn2pzehjfIkm5E6EZ9FL8YLvIW_41AvAATuKYe9N7uGThSpEAxbb0iBx55j
-FC4llF **Cross-site script special characters seen in fields <
transformed>**

To access the log messages by using the GUI

The NetScaler GUI includes a useful tool (Syslog Viewer) for analyzing the log messages. You have
multiple options for accessing the Syslog Viewer:
• Navigate to the Application Firewall > Profiles, select the target profile, and click Security
Checks. Highlight the HTML Cross-Site Scripting row and click Logs. When you access the
logs directly from the HTML Cross-Site Scripting check of the profile, the GUI filters out the log
messages and displays only the logs pertaining to these security check violations.
• You can also access the Syslog Viewer by navigating to NetScaler > System > Auditing. In the
Audit Messages section, click the Syslog messages link to display the Syslog Viewer, which dis-
plays all log messages, including other security check violation logs. This is useful for debugging
when multiple security check violations might be triggered during request processing.
• Navigate to Application Firewall > policies > Auditing. In the Audit Messages section, click the
Syslog messages link to display the Syslog Viewer, which displays all log messages, including
other security check violation logs.
The HTML based Syslog Viewer provides various filter options for selecting only the log messages that
are of interest to you. To select log messages for the HTML Cross-Site Scripting check, filter by se-
lecting APPFW in the dropdown options for Module. The Event Type list offers a rich set of options to
further refine your selection. For example, if you select the APPFW_XSS check box and click the Ap-
ply button, only log messages pertaining to the HTML Cross-Site Scripting security check violations
appear in the Syslog Viewer.
If you place the cursor in the row for a specific log message, multiple options, such as Module, Event
Type, Event ID, Client IP etc. appear below the log message. You can select any of these options to
highlight the corresponding information in the log message.
Click to Deploy functionality is available only in the GUI. You can use the Syslog Viewer to not only
view the logs but also to deploy HTML Cross-Site Scripting relaxation rules based on the log messages

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1614

NetScaler 12.0

for the App Firewall security check violations. The log messages must be in CEF log format for this
operation. Click to deploy functionality is available only for log messages that are generated by the
block (or not block) action. You cannot deploy a relaxation rule for a log message about the transform
operation.

To deploy a relaxation rule from the Syslog Viewer, select the log message. A check box appears in the
upper right corner of the Syslog Viewer box of the selected row. Select the check box, and then select
an option from the Action list to deploy the relaxation rule. Edit & Deploy, Deploy, and Deploy All
are available as Action options.

The HTML Cross-Site Scripting rules that are deployed by using the Click to Deploy option do not
include the fine grain relaxation recommendations.

To use Click to Deploy functionality in the GUI

1. In the Syslog Viewer, select APPFW in the Module options.

2. Select the APP_XSS as the Event Type to filter corresponding log messages.
3. Select the check box to identify the rule to deploy.
4. Use the Action drop-down list of options to deploy the relaxation rule.
5. Verify that the rule appears in the corresponding relaxation rule section.

Statistics for the HTML Cross-Site Scripting violations

When the stats action is enabled, the counter for the HTML Cross-Site Scripting check is incremented
when the App Firewall takes any action for this security check. The statistics are collected for Rate and
Total count for Traffic, Violations, and Logs. The size of an increment of the log counter can vary de-
pending on the configured settings. For example, if the block action is enabled, the request for a page
that contains 3 HTML Cross-Site Scripting violations increments the stats counter by one, because the
page is blocked as soon as the first violation is detected. However, if block is disabled, processing
the same request increments the statistics counter for violations and the logs by three, because each
violation generates a separate log message.

To display HTML Cross-Site Scripting check statistics by using the command line

At the command prompt, type:

> sh appfw stats

To display stats for a specific profile, use the following command:

> **stat appfw profile** <profile name>

To display HTML Cross-Site Scripting statistics by using the GUI

1. Navigate to Security > Application Firewall > Profiles > Statistics.

2. In the right pane, access the Statistics Link.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1615

NetScaler 12.0

3. Use the scroll bar to view the statistics about HTML Cross-Site Scripting violations and logs. The
statistics table provides real-time data and is updated every 7 seconds.

Highlights

Note the following points about the HTML Cross-Site Scripting check:
• Built-in Support for HTML Cross-Site Scripting attack Protection—The NetScaler App App
Firewall protects against Cross-Site Scripting attacks by monitoring a combination of allowed
attributes and tags, as well as denied patterns in the received payload. All the built-in default
allowed tags, allowed attributes and denied patterns used by the XSS check are specified in the
/netscaler/default_custom_settings.xml file.
• Customization—You can change the default list of tags, attributes, and patterns to customize
the Cross-Site Scripting security check inspection for the specific needs of your application.
Make a copy of the default signature object, modify existing entries, or add new ones. Bind
this signature object to your profile to make use of the customized configuration.
• Hybrid Security Model—Both signatures and deep security protections use the SQL/XSS pat-
terns specified in the signature object that is bound to the profile. If no signature object is bound
to the profile, the SQL/XSS patterns present in the default signature object are used.
• Transform—Note the following about the transform operation:
The transform operation works independently of the other Cross-Site Scripting action settings. If
transform is enabled and block, log, stats, and learn are all disabled, XSS tags will be transformed.
If the block action is enabled, it takes precedence over the transform action.
• Fine Grained Relaxation and Learning—Fine tune the relaxation rule to relax a subset of XSS
elements from security check inspection but detect the rest. The learning engine recommends
a specific value type and value expressions based on the observed data.
• Click to Deploy—Select one, or multiple XSS violation log messages in the syslog viewer and
deploy them as relaxation rules.
• Charset—The default charset for the profile should be set based on the need of the applica-
tion. By default, the profile charset is set to English US (ISO-8859-1). If a request is received
without the specified charset, the App Firewall processes the request as if it is ISO-8859-1. The
open bracket character (<) or the close bracket character (>) will not get interpreted as XSS tags
if these characters are encoded in other charsets. For example, if a request contains a UTF-8
character string “%uff1cscript%uff1e” but the charset is not specified on the request page, the
XSS violation might not get triggered unless the default charset for the profile is specified as
Unicode.
1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1616

NetScaler 12.0

4. App Firewall

HTML SQL injection check

December 13, 2018

Contributed by:
C

Many web applications have web forms that use SQL to communicate with relational database
servers. Malicious code or a hacker can use an insecure web form to send SQL commands to the
web server. The App Firewall HTML SQL Injection check provides special defenses against injection
of unauthorized SQL code that might break security. If the App Firewall detects unauthorized SQL
code in a user request, it either transforms the request, to render the SQL code inactive, or blocks the
request. The App Firewall examines the request payload for injected SQL code in three locations: 1)
POST body, 2) headers, and 3) cookies.

A default set of keywords and special characters provides known keywords and special characters
that are commonly used to launch SQL attacks. You can add new patterns, and you can edit the de-
fault set to customize the SQL check inspection. The App Firewall offers various action options for
implementing SQL Injection protection. In addition to the Block, Log, Stats and Learn actions, the
App Firewall profile also offers the option to transform SQL special characters to render an attack
harmless.

In addition to actions, there are several parameters that can be configured for SQL injection process-
ing. You can check for SQL wildcard characters. You can change the SQL Injection type and select one
of the 4 options (SQLKeyword, SQLSplChar, SQLSplCharANDKeyword, SQLSplCharORKeyword)
to indicate how to evaluate the SQL keywords and SQL special characters when processing the pay-
load. The SQL Comments Handling parameter gives you an option to specify the type of comments
that need to be inspected or exempted during SQL Injection detection.

You can deploy relaxations to avoid false positives. The App Firewall learning engine can provide rec-
ommendations for configuring relaxation rules.

Following options are available for configuring an optimized SQL Injection protection for your appli-
cation:

Block—If you enable block, the block action is triggered only if the input matches the SQL injection
type specification. For example, if SQLSplCharANDKeyword is configured as the SQL injection type,
a request is not blocked if it contains no key words, even if SQL special characters are detected in
the input. Such a request is blocked if the SQL injection type is set to either SQLSplChar, or SQL-
SplCharORKeyword.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1617

NetScaler 12.0

Log—If you enable the log feature, the SQL Injection check generates log messages indicating the
actions that it takes. If block is disabled, a separate log message is generated for each input field in
which the SQL violation was detected. However, only one message is generated when the request
is blocked. Similarly, one log message per request is generated for the transform operation, even
when SQL special characters are transformed in multiple fields. You can monitor the logs to determine
whether responses to legitimate requests are getting blocked. A large increase in the number of log
messages can indicate attempts to launch an attack.

Stats—If enabled, the stats feature gathers statistics about violations and logs. An unexpected surge in
the stats counter might indicate that your application is under attack. If legitimate requests are getting
blocked, you might have to revisit the configuration to see if you need to configure new relaxation rules
or modify the existing ones.

Learn—If you are not sure which SQL relaxation rules might be ideally suited for your application, you
can use the learn feature to generate recommendations based on the learned data. The App Firewall
learning engine monitors the traffic and provides SQL learning recommendations based on the ob-
served values. To get optimal benefit without compromising performance, you might want to enable
the learn option for a short time to get a representative sample of the rules, and then deploy the rules
and disable learning.

Transform SQL special characters—The App Firewall considers three characters, Single straight
quote (‘), Backslash (), and Semicolon (;) as special characters for SQL security check processing. The
SQL Transformation feature modifies the SQL Injection code in an HTML request to ensure that the
request is rendered harmless. The modified HTML request is then sent to the server. All default
transformation rules are specified in the /netscaler/default_custom_settings.xml file.

The transform operation renders the SQL code inactive by making the following changes to the re-
quest:

• Single straight quote (‘) to double straight quote (“).

• Backslash () to double backslash ().
• Semicolon (;) is dropped completely.

These three characters (special strings) are necessary to issue commands to an SQL server. Unless
an SQL command is prefaced with a special string, most SQL servers ignore that command. There-
fore, the changes that the App Firewall performs when transformation is enabled prevent an attacker
from injecting active SQL. After these changes are made, the request can safely be forwarded to your
protected web site. When web forms on your protected web site can legitimately contain SQL special
strings, but the web forms do not rely on the special strings to operate correctly, you can disable block-
ing and enable transformation to prevent blocking of legitimate web form data without reducing the
protection that the App Firewall provides to your protected web sites.

The transform operation works independently of the SQL Injection Type setting. If transform is en-
abled and the SQL Injection type is specified as SQL keyword, SQL special characters are transformed

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1618

NetScaler 12.0

even if the request does not contain any keywords.

Tip

You normally enable either transformation or blocking, but not both. If the block action is en-
abled, it takes precedence over the transform action. If you have blocking enabled, enabling
transformation is redundant.

Check for SQL Wildcard Characters—Wild card characters can be used to broaden the selections
of a structured query language (SQL-SELECT) statement. These wild card operators can be used in
conjunction with LIKE and NOT LIKE operators to compare a value to similar values. The percent (%),
and underscore (_) characters are frequently used as wild cards. The percent sign is analogous to the
asterisk (*) wildcard character used with MS-DOS and to match zero, one, or multiple characters in a
field. The underscore is similar to the MS-DOS question mark (?) wildcard character. It matches a
single number or character in an expression.

For example, you can use the following query to do a string search to find all customers whose names
contain the D character.

SELECT * from customer WHERE name like “%D%”:

The following example combines the operators to find any salary values that have 0 in the second and
third place.

SELECT * from customer WHERE salary like ‘_00%’:

Different DBMS vendors have extended the wildcard characters by adding extra operators. The
NetScaler App App Firewall can protect against attacks that are launched by injecting these wildcard
characters. The 5 default Wildcard characters are percent (%), underscore (_), caret (ˆ), opening
square bracket ([), and closing square bracket (]). This protection applies to both HTML and XML
profiles.

The default wildcard chars are a list of literals specified in the *Default Signatures:

• <wildchar type=”LITERAL”>%</wildchar>
• <wildchar type=”LITERAL”>_</wildchar>
• <wildchar type=”LITERAL”>^</wildchar>
• <wildchar type=”LITERAL”>[</wildchar>
• <wildchar type=”LITERAL”>]</wildchar>

Wildcard characters in an attack can be PCRE, like [ˆA-F]. The App Firewall also supports PCRE wild-
cards, but the literal wildcard chars above are sufficient to block most attacks.
Note

The SQL wildcard character check is different from the SQL special character check. This option
must be used with caution to avoid false positives.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1619

NetScaler 12.0

Check Request Containing SQL Injection Type—The App Firewall provides 4 options to implement
the desired level of strictness for SQL Injection inspection, based on the individual need of the applica-
tion. The request is checked against the injection type specification for detecting SQL violations. The
4 SQL injection type options are:

• SQL Special Character and Keyword—Both an SQL keyword and an SQL special character must
be present in the input to trigger SQL violation. This least restrictive setting is also the default
setting.
• SQL Special Character—At least one of the special characters must be present in the input to
trigger SQL violation.
• SQL key word—At least one of the specified SQL keywords must be present in the input to trig-
ger an SQL violation. Do not select this option without due consideration. To avoid false posi-
tives, make sure that none of the keywords are expected in the inputs.
• SQL Special Character or Keyword—Either the key word or the special character string must
be present in the input to trigger the security check violation.

Tip

If you configure the App Firewall to check for inputs that contain an SQL special character, the App
Firewall skips web form fields that do not contain any special characters. Since most SQL servers
do not process SQL commands that are not preceded by a special character, enabling this option
can significantly reduce the load on the App Firewall and speed up processing without placing
your protected web sites at risk.

SQL comments handling—By default, the App Firewall checks all SQL comments for injected SQL
commands. Many SQL servers ignore anything in a comment, however, even if preceded by an SQL
special character. For faster processing, if your SQL server ignores comments, you can configure the
App Firewall to skip comments when examining requests for injected SQL. The SQL comments han-
dling options are:

• ANSI—Skip ANSI-format SQL comments, which are normally used by UNIX-based SQL
databases. For example:
– – (Two Hypens) - This is a comment that begins with two hyphens and ends with end of
line.
– {} - Braces (Braces enclose the comment. The { precedes the comment, and the } follows it.
Braces can delimit single- or multiple-line comments, but comments cannot be nested)
– /* */ : C style comments (Does not allow nested comments). Please
note **/*!** <comment that begin with slash followed by asterisk
and exclamation mark is not a comment >  ***/**
– MySQL Server supports some variants of C-style comments. These enable you to write
code that includes MySQL extensions, but is still portable, by using comments of the fol-
lowing form: /! MySQL-specific code /
– . # : Mysql comments : This is a comment that begins with # character and ends with end

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1620

NetScaler 12.0

of the line
• Nested—Skip nested SQL comments, which are normally used by Microsoft SQL Server. For
example; – (Two Hypens), and /* */ (Allows nested comments)
• ANSI/Nested—Skip comments that adhere to both the ANSI and nested SQL comment stan-
dards. Comments that match only the ANSI standard, or only the nested standard, are still
checked for injected SQL.
• Check all Comments—Check the entire request for injected SQL without skipping anything.
This is the default setting.

Tip

In most cases, you should not choose the Nested or the ANSI/Nested option unless your back-
end database runs on Microsoft SQL Server. Most other types of SQL server software do not rec-
ognize nested comments. If nested comments appear in a request directed to another type of
SQL server, they might indicate an attempt to breach security on that server.

Check Request headers—Enable this option if, in addition to examining the input in the form fields,
you want to examine the request headers for HTML SQL Injection attacks. If you use the GUI, you can
enable this parameter in the Advanced Settings -> Profile Settings pane of the App Firewall profile.

Note

If you enable the Check Request header flag, you might have to configure relaxation rule for the
User-Agent header. Presence of the SQL keyword like and SQL special character semi-colon (;)
might trigger false positive and block requests that contain this header.
Warning

If you enable both request header checking and transformation, any SQL special characters
found in headers are also transformed. The Accept, Accept-Charset, Accept-Encoding, Accept-
Language, Expect, and User-Agent headers normally contain semicolons (;). Enabling both
Request header checking and transformation simultaneously might cause errors.

SQL fine grained relaxations

The App Firewall gives you an option to exempt a specific form field, header, or Cookie from SQL In-
jection inspection check. You can completely bypass the inspection for one or more of these fields by
configuring relaxation rules for the SQL Injection check.

The App Firewall allows you to implement tighter security by fine tuning the relaxation rules. An ap-
plication might require the flexibility to allow specific patterns, but configuring a relaxation rule to
bypass the security inspection might make the application vulnerable to attacks, because the target
field is exempted from inspection for any SQL attack patterns. SQL fine grained relaxation provides
the option to allow specific patterns and block the rest. For example, the App Firewall currently has

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1621

NetScaler 12.0

a default set of more than 100 SQL keywords. Because hackers can use these keywords in SQL Injec-
tion attacks, the App Firewall flags them as potential threats. You can relax one or more keyword(s)
that are considered safe for the specific location. The rest of the potentially dangerous SQL keywords
are still checked for the target location and continue to trigger the security check violations. You now
have much tighter control.

The commands used in relaxations have optional parameters for Value Type and Value Expression.
You can specify whether the value expression is a regular expression or a literal string. The value type
can be left blank or you have an option to select Keyword or SpecialString or WildChar.

Warning

Regular expressions are powerful. Especially if you are not thoroughly familiar with PCRE-format
regular expressions, double-check any regular expressions you write. Make sure that they define
exactly the URL that you want to add as an exception, and nothing else. Careless use of wildcards,
and especially of the dot-asterisk ( .*) metacharacter/wildcard combination, can have results that
you do not want, such as blocking access to web content that you did not intend to block or
allowing an attack that the HTML SQL Injection check would otherwise have blocked.

Points to Consider:

• Value expression is an optional argument. A field name might not have any value expression.
• A field name can be bound to multiple value expressions.
• Value expressions should be assigned a value type. The SQL value type can be: 1) Keyword, 2)
SpecialString, or 3) WildChar.
• You can have multiple relaxation rules per field name/URL combination.

Using the command line to configure the SQL injection check

To configure SQL Injection actions and other parameters by using the command line:

In the command line interface, you can use either the set appfw profile command or the add appfw
profile command to configure the SQL Injection protections. You can enable the block, learn, log,
stats action(s) and specify whether you want to transform the special characters used in SQL Injec-
tion attack strings to disable the attack. Select the type of SQL attack pattern (key words, wildcard
characters, special strings) you want to detect in the payloads, and indicate whether you want the
App Firewall to also inspect the request Headers for SQL Injection violations. Use the unset appfw
profile command to revert the configured settings back to their defaults. Each of the following com-
mands sets only one parameter, but you can include multiple parameters in a single command:

• set appfw profile “Parameter descriptions provided at bottom of the page.”

• <name> -SQLInjectionAction (([block] [learn] [log] [stats])| [none])
• set appfw profile “Parameter descriptions provided at bottom of the page.”
• <name> -SQLInjectionTransformSpecialChars (**ON** | OFF)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1622

NetScaler 12.0

• set appfw profile “Parameter descriptions provided at bottom of the page.”

• <name> -**SQLInjectionCheckSQLWildChars** (**ON** |**OFF**)
• set appfw profile “Parameter descriptions provided at bottom of the page.”
• **<name> -**SQLInjectionType** ([**SQLKeyword**] | [**SQLSplChar**] | 
[**SQLSplCharANDKeyword**] | [**SQLSplCharORKeyword**])
• set appfw profile “Parameter descriptions provided at bottom of the page.”
• <name> -**SQLInjectionParseComments** ([**checkall**] | [**ansi|nested
**] | [**ansinested**])
• **set appfw profile “Parameter descriptions provided at bottom of the page.”
• <name> -CheckRequestHeaders (ON | OFF)

To configure a SQL Injection relaxation rule by using the command line

Use the bind or unbind command to add or delete binding, as follows:

• bind appfw profile <name> -SQLInjection <String> [isRegex(REGEX|

NOTREGE)] <formActionURL> [-location <location>] [-valueType (Keywor
|SpecialString|Wildchar)[<valueExpression>][-isValueRegex (REGEX |
NOTREGEX)]]

• unbind appfw profile <name> -SQLInjection <String> <formActionURL>

[-location <location>] [-valueTyp (Keyword|SpecialString|Wildchar)[<
valueExpression>]]

Note

You can find the list of SQL keywords from default signature file contents by viewing the view
signature object, which has list of sql key words and sql special characters.

Using the GUI to configure the SQL injection security check

In the GUI, you can configure the SQL Injection security check in the pane for the profile associated
with your application.

To configure or modify the SQL Injection check by using the GUI

1. Navigate to Application Firewall > Profiles, highlight the target profile, and click Edit.
2. In the Advanced Settings pane, click Security Checks.

The security check table displays the currently configured action settings for all the security checks.
You have 2 options for configuration:

a. If you just want to enable or disable Block, Log, Stats, and Learn actions for HTML SQL Injection,
you can select or clear check boxes in the table, click OK, and then click Save and Close to close the
Security Check pane.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1623

NetScaler 12.0

b. If you want to configure additional options for this security check, double click HTML SQL Injection,
or select the row and click Action Settings, to display the following options:
Transform SQL Special character—Transform any SQL Special characters in the request.
Check for SQL Wildcard Characters—Consider SQL Wildcard characters in the payload to be attack
patterns.
Check Request Containing—Type of SQL injection (SQLKeyword, SQLSplChar, SQLSplCharANDKey-
word, or SQLSplCharORKeyword) to check.
SQL Comments Handling—Type of comments (Check All Comments, ANSI, Nested, or ANSI/Nested)
to check.
After changing any of the above settings, click OK to save the changes and return to the Security
Checks table. You can proceed to configure other security checks if needed. Click OK to save all the
changes you have made in the Security Checks section, and then click Save and Close to close the
Security Check pane.
1. To enable or disable the Check request Header setting, in the Advanced Settings pane, click
Profile Settings. In Common Settings, Select or clear the Check Request Headers check box.
Click OK. You can either use the X icon at the top right hand side of the Profile Settings pane to
close this section or, if you have finished configuring this profile, you can click Done to return to
the App Firewall > Profile.
To configure an SQL Injection relaxation rule by using the GUI
• Navigate to Application Firewall > Profiles, highlight the target profile, and click Edit.
• In the Advanced Settings pane, click Relaxation Rules.
• In the Relaxation Rules table, double-click the HTML SQL Injection entry, or select it and click
Edit.
• In the HTML SQL Injection Relaxation Rules dialogue box, perform Add, Edit, Delete, Enable,
or Disable operations for relaxation rules.
Note

When you add a new rule, the Value Expression field is not displayed unless you select Keyword
or SpecialString or WildChar option in the Value Type Field.

To manage SQL Injection relaxation rules by using the visualizer

For a consolidated view of all the relaxation rules, you can highlight the HTML SQL Injection row and
click Visualizer. The visualizer for deployed relaxations offers you the option to Add a new rule or
Edit an existing one. You can also Enable or Disable a group of rules by selecting a node and clicking
the corresponding buttons in the relaxation visualizer.
To view or customize the SQL Injection patterns by using the GUI
You can use the GUI to view or customize the SQL patterns.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1624

NetScaler 12.0

The default SQL patterns are specified in Application Firewall> Signatures > Default Signatures.
If you do not bind any signature object to your profile, the default SQL patterns specified in the De-
fault Signatures object will be used by the profile for the SQL Injection security check processing. The
rules and patterns, specified in the default signatures object, are read-only. You cannot edit or modify
them. If you want to modify or change these patterns, make a copy of the Default Signatures object
to create a User-Defined signature object. Make changes in the SQL patterns in the new User-defined
signature object and use this signature object in your profile that is processing the traffic for which
you want to use these customized SQL patterns.

For more information, see Signatures

1. To view default SQL patterns:

a. Navigate to Application Firewall > Signatures, select *Default Signatures, and click Edit.

Then click Manage SQL/XSS patterns.

The Manage SQL/XSS paths table shows following four rows pertaining to SQL Injection:

• Injection (not_alphanum, SQL)/ Keyword

• Injection (not_alphanum, SQL)/ specialstring

• Injection (not_alphanum, SQL)/ transformrules/transform

• Injection (not_alphanum, SQL)/ wildchar

b. Select a row and click Manage Elements to display the corresponding SQL patterns (keywords,
special strings, transformation rules or the wildcard characters) used by the App Firewall SQL injection
check.

2. noTo customize SQL patterns: You can edit the User-Defined signature object to customize the SQL
key words, special strings, and wildcard characters. You can add new entries or remove the existing
ones. You can modify the transformation rules for the SQL special strings.

a. Navigate to Application Firewall > Signatures, highlight the target User-defined signature, and
click Edit. Click Manage SQL/XSS patterns to display the Manage SQL/XSS paths table.

b. Select the target SQL Injection row.

i. Click Manage Elements, to Add, Edit or Remove the corresponding SQL element.

ii. Click Remove to remove the selected row.

Warning

You must be very careful before you remove or modify any default SQL element, or delete the SQL
path to remove the entire row. The signature rules as well as the SQL Inject security check rely
on these elements for detecting SQL Injection attacks to protect your applications. Customizing
the SQL patterns can make your application vulnerable to SQL attacks if the required pattern is

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1625

NetScaler 12.0

removed during editing.

Using the Learn feature with the SQL injection check

When the learn action is enabled, the App Firewall learning engine monitors the traffic and learns the
triggered violations. You can periodically inspect these learned rules. After due consideration, you
can deploy the learned rule as an SQL Injection relaxation rule.

SQL Injection Learning enhancement—An App Firewall learning enhancement was introduced in re-
lease 11.0 of the NetScaler software. To deploy fine grained SQL Injection relaxation, the App Firewall
offers fine grained SQL Injection learning. The learning engine makes recommendations regarding
the observed Value Type (keyword, SpecialString, Wildchar) and the corresponding Value expression
observed in the input fields. In addition to checking the blocked requests to determine whether the
current rule is too restrictive and needs to be relaxed, you can review the rules generated by the learn-
ing engine to determine which value type and value expressions are triggering violations and need to
be addressed in relaxation rules.
Important

The App Firewall’s learning engine can distinguish only the first 128 bytes of the name. If a form
has multiple fields with names that match for the first 128 bytes, the learning engine might not
be able to distinguish between them. Similarly, the deployed relaxation rule might inadvertently
relax all such fields from SQL Injection inspection.
Note To bypass SQL check in User-Agent header, use the following relaxation rule:

bind appfw profile your_profile_name -SQLInjection User-Agent “ .*” -location HEADER

To view or use learned data by using the command line interface

At the command prompt, type one of the following commands:

• show appfw learningdata <profilename> SQLInjection

• rm appfw learningdata <profilename> -SQLInjection <string>  <formActionURL
>  [<location>]  [<valueType>  <valueExpression>]
• export appfw learningdata <profilename> SQLInjection

To view or use learned data by using the GUI

1. Navigate to Application Firewall > Profiles, highlight the target profile, and click Edit.

2. In the Advanced Settings pane, click Learned Rules. You can select the HTML SQL Injection
entry in the Learned Rules table and double-click it to access the learned rules. You can deploy
the learned rules or edit a rule before deploying it as a relaxation rule. To discard a rule, you
can select it and click the Skip button. You can edit only one rule at a time, but you can select
multiple rules to deploy or skip.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1626

NetScaler 12.0

You also have the option to show a summarized view of the learned relaxations by selecting the HTML
SQL Injection entry in the Learned Rules table and clicking Visualizer to get a consolidated view of
all the learned violations. The visualizer makes it very easy to manage the learned rules. It presents a
comprehensive view of the data on one screen and facilitates taking action on a group of rules with one
click. The biggest advantage of the visualizer is that it recommends regular expressions to consolidate
multiple rules. You can select a subset of these rules, based on the delimiter and Action URL. You
can display 25, 50, or 75 rules in the visualizer, by selecting the number from a drop-down list. The
visualizer for learned rules offers the option to edit the rules and deploy them as relaxations. Or you
can skip the rules to ignore them.

Using the log feature with the SQL injection check

When the log action is enabled, the HTML SQL Injection security check violations are logged in the
audit log as APPFW_SQL violations. The App Firewall supports both Native and CEF log formats. You
can also send the logs to a remote syslog server.
To access the log messages by using the command line
Switch to the shell and tail the ns.logs in the /var/log/ folder to access the log messages pertaining to
the SQL Injection violations:
> Shell

## tail -f /var/log/ns.log | grep APPFW_SQL

Example of a HTML SQL Injection log message when the request is transformed

1 Jun 26 21:08:41 <local0.info> 10.217.31.98 CEF:0|Citrix|NetScaler|NS11

.0|APPFW|APPFW_SQL|6|src=10.217.253.62 geolocation=Unknown spt=54001
method=GET request=http://aaron.stratum8.net/FFC/login.php?
login_name\=%27+or&passwd\=and+%3B&drinking_pref\=on&text_area\=
select+*+from+%5C+%3B&loginButton\=ClickToLogin&as_sfid\=
AAAAAAXjnGN5gLH-hvhTOpIySEIqES7BjFRs5Mq0fwPp-3ZHDi5yWlRWByj0cVbMyy-
Ens2vaaiULKOcUri4OD4kbXWwSY5s7I3QkDsrvIgCYMC9BMvBwY2wbNcSqCwk52lfE0k
%3D&as_fid\=feeec8758b41740eedeeb6b35b85dfd3d5def30c msg= Special
characters seen in fields cn1=74 cn2=762 cs1=pr_ffc cs2=PPE1 cs3=9
ztIlf9p1H7p6Xtzn6NMygTv/QM0002 cs4=ALERT cs5=2015 act=transformed

Example of a HTML SQL Injection log message when the post request is blocked

1 Jun 26 21:30:34 <local0.info> 10.217.31.98 CEF:0|Citrix|NetScaler|NS11

.0|APPFW|APPFW_SQL|6|src=10.217.253.62 geolocation=Unknown spt=9459
method=POST request=http://aaron.stratum8.net/FFC/login_post.php msg
=SQL Keyword check failed for field text_area\=”(’)” cn1=78 cn2=834
cs1=pr_ffc cs2=PPE1 cs3=eVJMMPtZ2XgylGrHjkx3rZLfBCI0002 cs4=ALERT
cs5=2015 act=blocked

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1627

NetScaler 12.0

Note

As part of the streaming changes in 10.5.e build (enhancement builds) as well as 11.0 build on-
wards, we now process the input data in blocks. RegEx pattern matching is now restricted to
4K for contiguous character string matching. With this change, the SQL violation log messages
might include different information compared to the earlier builds. The keyword and special
character in the input could be separated by a large number of bytes. We now keep track of the
SQL keywords and special strings when processing the data, instead of buffering the entire input
value. In addition to the field name, the log message now includes the SQL keyword, or the SQL
special character, or both the SQL keyword and the SQL special character, as determined by the
configured setting. The rest of the input is no longer included in the log message, as shown in
the following example:

Example:

In 10.5, when the App Firewall detects the SQL violation, the entire input string might be included
in the log message, as shown below:

SQL Keyword check failed for field text=\”select a name from testbed1
;(;)\”.*<blocked>

In enhancement builds of 10.5.e that support request side streaming as well as 11.0 build on-
wards, we log only the field name, keyword and special character (if applicable) in the log mes-
sage, as shown below:

SQL Keyword check failed for field **text=”select(;)”<blocked>

This change is applicable to requests that contain application/x-www-form-urlencoded,

or multipart/form-data, or text/x-gwt-rpc content-types. Log messages generated during
processing of JSON or XML payloads are not affected by this change.

To access the log messages by using the GUI

The NetScaler GUI includes a useful tool (Syslog Viewer) for analyzing the log messages. You have
multiple options for accessing the Syslog Viewer:

• Navigate to the Application Firewall > Profiles, select the target profile, and click Security
Checks. Highlight the HTML SQL Injection row and click Logs. When you access the logs di-
rectly from the HTML SQL Injection check of the profile, the GUI filters out the log messages and
displays only the logs pertaining to these security check violations.
• You can also access the Syslog Viewer by navigating to NetScaler > System > Auditing. In the
Audit Messages section, click the Syslog messages link to display the Syslog Viewer, which dis-
plays all log messages, including other security check violation logs. This is useful for debugging
when multiple security check violations might be triggered during request processing.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1628

NetScaler 12.0

• Navigate to Application Firewall > policies > Auditing. In the Audit Messages section, click the
Syslog messages link to display the Syslog Viewer, which displays all log messages, including
other security check violation logs.

The HTML based Syslog Viewer provides various filter options for selecting only the log messages that
are of interest to you. To select log messages for the HTML SQL Injection check, filter by selecting
APPFW in the dropdown options for Module. The Event Type list offers a rich set of options to further
refine your selection. For example, if you select the APPFW_SQL check box and click the Apply but-
ton, only log messages pertaining to the SQL Injection security check violations appear in the Syslog
Viewer.

If you place the cursor in the row for a specific log message, multiple options, such as Module, Event
Type, Event ID, Client IP etc. appear below the log message. You can select any of these options to
highlight the corresponding information in the log message.

Click to Deploy functionality is available only in the GUI. You can use the Syslog Viewer to not only
view the logs but also to deploy HTML SQL Injection relaxation rules based on the log messages for the
App Firewall security check violations. The log messages must be in CEF log format for this operation.
Click to deploy functionality is available only for log messages that are generated by the block (or not
block) action. You cannot deploy a relaxation rule for a log message about the transform operation.

To deploy a relaxation rule from the Syslog Viewer, select the log message. A check box appears in the
upper right corner of the Syslog Viewer box of the selected row. Select the check box, and then select
an option from the Action list to deploy the relaxation rule. Edit & Deploy, Deploy, and Deploy All
are available as Action options.

The SQL Injection rules that are deployed by using the Click to Deploy option do not include the fine
grain relaxation recommendations.

To use Click to Deploy functionality in the GUI:

1. In the Syslog Viewer, select Application Firewall in the Module options.

2. Select the APP_SQL as the Event Type to filter corresponding log messages.
3. Select the check box to identify the rule to deploy.
4. Use the Action drop-down list of options to deploy the relaxation rule.
5. Verify that the rule appears in the corresponding relaxation rule section.

Statistics for the SQL Injection violations

When the stats action is enabled, the counter for the SQL Injection check is incremented when the App
Firewall takes any action for this security check. The statistics are collected for Rate and Total count
for Traffic, Violations, and Logs. The size of an increment of the log counter can vary depending on the
configured settings. For example, if the block action is enabled, the request for a page that contains 3
SQL Injection violations increments the stats counter by one, because the page is blocked as soon as

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1629

NetScaler 12.0

the first violation is detected. However, if block is disabled, processing the same request increments
the statistics counter for violations and the logs by three, because each violation generates a separate
log message.

To display SQL Injection check statistics by using the command line:

At the command prompt, type:

sh appfw stats

To display stats for a specific profile, use the following command:

>  stat appfw profile <profile name>

To display HTML SQL Injection statistics by using the GUI

1. Navigate to System > Security > Application Firewall.

2. In the right pane, access the Statistics Link.
3. Use the scroll bar to view the statistics about HTML SQL Injection violations and logs. The statis-
tics table provides real-time data and is updated every 7 seconds.

Highlights

Note the following points about the SQL Injection check:

• Built-in Support for SQL Injection Protection—The NetScaler App App Firewall protects
against SQL Injection by monitoring a combination of SQL keywords and special characters in
the form parameters. All SQL keywords, special characters, wildcard characters, and default
transformation rules are specified in the /netscaler/default_custom_settings.xml file.
• Customization—You can change the default key words, special characters, wildcard characters
and transformation rules to customize the SQL security check inspection for the specific needs
of your application. Make a copy of the default signature object, modify existing entries, or add
new ones. Bind this signature object to your profile to make use of the customized configura-
tion.
• Hybrid Security Model—Both signatures and deep security protections use the SQL/XSS pat-
terns specified in the signature object that is bound to the profile. If no signature object is bound
to the profile, the SQL/XSS patterns present in the default signature object are used.
• Transform—Note the following about the transform operation:
– The transform operation works independently of the other SQL Injection action settings.
If transform is enabled and block, log, stats, and learn are all disabled, SQL special charac-
ters will be transformed.
– When SQL Transformation is enabled, user requests are sent to the backend servers after
the SQL special characters are transformed in non-block mode. If the block action is en-
abled, it takes precedence over the transform action. If the injection type is specified as

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1630

NetScaler 12.0

SQL special character and block is enabled, the request is blocked despite the transform
action.
• Fine Grained Relaxation and Learning—Fine tune the relaxation rule to relax a subset of SQL
elements from security check inspection but detect the rest. The learning engine recommends
a specific value type and value expressions based on the observed data.
• Click to Deploy—Select one, or multiple SQL violation log messages in the syslog viewer and
deploy them as relaxation rules.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Buffer overflow check

September 18, 2018

Contributed by:
C

The Buffer Overflow check detects attempts to cause a buffer overflow on the web server. If the App
Firewall detects that the URL, cookies, or header are longer than the specified maximum length in a
request, it blocks that request because it might be an attempt to cause a buffer overflow.

The Buffer Overflow check prevents attacks against insecure operating-system or web-server software
that can crash or behave unpredictably when it receives a data string that is larger than it can handle.
Proper programming techniques prevent buffer overflows by checking incoming data and either re-
jecting or truncating overlong strings. Many programs, however, do not check all incoming data and
are therefore vulnerable to buffer overflows. This issue especially affects older versions of web-server
software and operating systems, many of which are still in use.

The Buffer Overflow security check allows you to configure the Block, Log, and Stats actions. In addi-
tion, you can also configure the following parameters:

• Maximum URL Length. The maximum length the App Firewall allows in a requested URL. Re-
quests with longer URLs are blocked. Possible Values: 0-65535. Default: 1024
• Maximum Cookie Length. The maximum length the App Firewall allows for all cookies in a re-
quest. Requests with longer cookies trigger the violations. Possible Values: 0-65535. Default:
4096
• Maximum Header Length. The maximum length the App Firewall allows for HTTP headers.
Requests with longer headers are blocked. Possible Values: 0-65535. Default: 4096

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1631

NetScaler 12.0

Using the command line to configure the Buffer Overflow security check

To configure Buffer Overflow security check actions and other parameters by using the command line
If you use the command-line interface, you can add the following Buffer Overflow Check arguments
to the set appfw profile <profileName> command:
• -bufferOverflowAction [[ block] [ log] [stats]] | [none]
• -bufferOverflowMaxURLLength <positiveInteger>
• -bufferOverflowMaxCookieLength <positiveInteger>
• -bufferOverflowMaxHeaderLength <positiveInteger>

Using the GUI to Configure the Buffer Overflow Security Check

In the GUI, you can configure the Buffer Overflow security check in the pane for the profile associated
with your application.
To configure or modify the Buffer Overflow security check by using the GUI
1. Navigate to Application Firewall > Profiles, highlight the target profile, and click Edit.
2. In the Advanced Settings pane, click Security Checks.
The security check table displays the currently configured action settings for all the security checks.
You have 2 options for configuration:
a. If you just want to enable or disable Block, Log, and Stats actions for Buffer Overflow, you can
select or clear check boxes in the table, click OK, and then click Save and Close to close the Security
Check pane.
b. If you want to configure additional options for this security check, double click Buffer Overflow,
or select the row and click Action Settings, to display the following options:
Maximum URL Length.
Maximum Cookie Length.
Maximum Header Length.
After changing any of the above settings, click OK to save the changes and return to the Security
Checks table. You can proceed to configure other security checks if needed. Click OK to save all the
changes you have made in the Security Checks section, and then click Save and Close to close the
Security Check pane.

Using the Log Feature with the Buffer Overflow Security Check

When the log action is enabled, the Buffer Overflow security check violations are logged in
the audit log as APPFW_BUFFEROVERFLOW_URL, APPFW_BUFFEROVERFLOW_COOKIE, and

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1632

NetScaler 12.0

APPFW_BUFFEROVERFLOW_HDR violations. The App Firewall supports both Native and CEF log
formats. You can also send the logs to a remote syslog server.

If you use the GUI to review the logs, you can use the click-to-deploy feature to apply relaxations indi-
cated by the logs.

To access the log messages by using the command line

Switch to the shell and tail the ns.logs in the /var/log/ folder to access the log messages pertaining to
the Buffer overflow violations:

1 > **Shell**
2 > **tail -f /var/log/ns.log | grep APPFW_BUFFEROVERFLOW**

Example of a CEF log message showing bufferOverflowMaxCookieLength violation in non-block mode

1 Oct 22 17:35:20 <local0.info> 10.217.31.98 CEF:0|Citrix|NetScaler|NS11

.0|APPFW|APPFW_BUFFEROVERFLOW_COOKIE|6|src=10.217.253.62 geolocation
=Unknown spt=41198 method=GET request=http://aaron.stratum8.net/FFC/
sc11.html msg=Cookie header length(43) is greater than maximum
allowed(16). cn1=119 cn2=465 cs1=owa_profile cs2=PPE1 cs3=wvOOOb+
cJ2ZRbstZpyeNXIqLj7Y0001 cs4=ALERT cs5=2015 act=not blocked

Example of a CEF log message showing bufferOverflowMaxURLLength violation in non-block mode

1 Oct 22 18:39:56 <local0.info> 10.217.31.98 CEF:0|Citrix|NetScaler|NS11

.0|APPFW|APPFW_BUFFEROVERFLOW_URL |6|src=10.217.253.62 geolocation=
Unknown spt=19171 method=GET request=http://aaron.stratum8.net/FFC/
sc11.html **msg=URL length(39) is greater than maximum allowed(20).
cn1=707 cn2=402 cs1=owa_profile cs2=PPE0 cs3=kW49GcKbnwKByByi3+
jeNzfgWa80000 cs4=ALERT cs5=2015 act=not blocked

Example of a Native Format Log message showing bufferOverflowMaxHeaderLength violation in block

mode

1 Oct 22 18:44:00 <local0.info> 10.217.31.98 10/22/2015:18:44:00 GMT ns

0-PPE-2 : default APPFW APPFW_BUFFEROVERFLOW_HDR 155 0 : 
10.217.253.62 374-PPE2 khhBEeY4DB8V2D3H2sMLkXmfWnA0002 owa_profile
Header(User-Agent) length(82) is greater than maximum allowed(10)**
: http://aaron.stratum8.net/ <blocked>

To access the log messages by using the GUI

The NetScaler GUI includes a useful tool (Syslog Viewer) for analyzing the log messages. You have
multiple options for accessing the Syslog Viewer:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1633

NetScaler 12.0

• Navigate to the Application Firewall > Profiles, select the target profile, and click Security
Checks. Highlight the Buffer Overflow row and click Logs. When you access the logs directly
from the Buffer Overflow Security Check of the profile, the GUI filters out the log messages and
displays only the logs pertaining to these security check violations.

• You can also access the Syslog Viewer by navigating to NetScaler > System > Auditing. In the
Audit Messages section, click the Syslog messages link to display the Syslog Viewer, which dis-
plays all log messages, including other security check violation logs. This is useful for debugging
when multiple security check violations might be triggered during request processing.

• Navigate to Application Firewall > policies > Auditing. In the Audit Messages section, click the
Syslog messages link to display the Syslog Viewer, which displays all log messages, including
other security check violation logs.

The XML based Syslog Viewer provides various filter options for selecting only the log mes-
sages that are of interest to you. To select log messages for the Buffer Overflow check,
filter by selecting APPFW in the dropdown options for Module. The Event Type list offers
three options, APPFW_BUFFEROVERFLOW_URL, APPFW_BUFFEROVERFLOW_COOKIE, and
APPFW_BUFFEROVERFLOW_HDR, to view all the log messages pertaining to buffer overflow se-
curity check. You can select one or more options to further refine your selection. For example, if
you select the APPFW_BUFFEROVERFLOW_COOKIE check box and click the Apply button, only log
messages pertaining to the Buffer Overflow security check violations for the Cookie header appear
in the Syslog Viewer. If you place the cursor in the row for a specific log message, multiple options,
such as Module, Event Type, Event ID, and Client IP, appear below the log message. You can select
any of these options to highlight the corresponding information in the log message.

Click-to-Deploy: The GUI provides click-to-deploy functionality, which is currently supported only
for the buffer overflow log messages pertaining to the URL Length violations. You can use the Syslog
Viewer to not only view the triggered violations, but also execute informed decisions based on the
observed lengths of the blocked messages. If the current value is too restrictive and is triggering false
positives, you can select a message and deploy it to replace the current value with the URL length
value seen in the message. The log messages must be in CEF log format for this operation. If the
relaxation can be deployed for a log message, a check box appears at the right edge of the Syslog
Viewer box in the row. Select the check box, and then select an option from the Action list to deploy
the relaxation. Edit & Deploy, Deploy, and Deploy All are available as Action options. You can use the
APPFW_BUFFEROVERFLOW_URL filter to isolate all the log messages pertaining to the configured
URL length violations.

If you select an individual log message, all three action options Edit & Deploy, Deploy, and Deploy
All are available. If you select Edit & Deploy, the Buffer Overflow settings dialogue is displayed.
The new URL length that was observed in the request is inserted into the Maximum URL length input
field. If you click Close without any edits, the current configured values remain unchanged. If you
click the OK button, the new value of the Maximum URL length replaces the previous value.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1634

NetScaler 12.0

Note

The block, log and stats action check boxes are unchecked in the displayed Buffer Overflow
settings dialogue, and need to be reconfigured if you select the Edit & Deploy option. Make sure
to enable these check boxes before clicking OK, otherwise the new URL length will get configured
but the actions will be set to none.

If you select the check boxes for multiple log messages, you can use the Deploy or Deploy All op-
tion. If the deployed log messages have different URL lengths, the configured value gets replaced
by the highest URL Length value observed in the selected messages. Deploying the rule results only
in changing the bufferOverflowMaxURLLength value. Configured actions are retained and remain
unchanged.

To use Click-to-Deploy functionality in the GUI

1. In the Syslog Viewer, select APPFW in the Module options.

2. Enable the APPFW_BUFFEROVERFLOW_URL check box as the Event Type to filter correspond-
ing log messages.
3. Enable the check box to select the rule.
4. Use the Action drop-down list of options to deploy the relaxation.
5. Navigate to Application Firewall > Profiles, select the target profile, and click Security Checks
to access the Buffer Overflow settings pane to verify that the Maximum URL Length value is
updated.

Statistics for the Buffer Overflow violations

When the stats action is enabled, the counter for the Buffer Overflow Security Check is incremented
when the App Firewall takes any action for this security check. The statistics are collected for Rate
and Total count for Traffic, Violations, and Logs. The size of an increment of the log counter can vary
depending on the configured settings. For example, if the block action is enabled, a request for a page
that contains three Buffer Overflow violations increments the stats counter by one, because the page
is blocked as soon as the first violation is detected. However, if block is disabled, processing the same
request increments the statistics counter for violations and the logs by three, because each violation
generates a separate log message.

To display Buffer Overflow Security Check statistics by using the command line

At the command prompt, type:

> sh appfw stats

To display stats for a specific profile, use the following command:

> stat appfw profile <profile name>

To display Buffer Overflow statistics by using the GUI

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1635

NetScaler 12.0

1. Navigate to System > Security > Application Firewall.

2. In the right pane, access the Statistics Link.
3. Use the scroll bar to view the statistics about Buffer Overflow violations and logs. The statistics
table provides real-time data and is updated every 7 seconds.

Highlights

• The buffer overflow security check allows you to configure limits to enforce the maximum length
of allowed URLs, Cookies and Headers.

• Block, Log and Stats actions enable you to monitor the traffic and configure optimal protection
for your application.

• Syslog viewer enables you to filter and view all the log messages pertaining to buffer overflow
violations.

• Click-to-Deploy functionality is supported for the bufferOverflowMaxURLLength violations.

You can select and deploy an individual rule, or you can select multiple log messages to tweak
and relax the current configured value of the maximum allowed length of the URL. The highest
value of the URL from the selected group is set as the new value, to allow all these requests that
are currently flagged as violations.

• The App Firewall now evaluates individual cookies when inspecting the incoming request. If
length of any one cookie received in the Cookie header exceeds the configured BufferOver-
flowMaxCookieLength, the Buffer Overflow violation is triggered.

Important

In release 10.5.e (in a few interim enhancement builds prior to 59.13xx.e build) as well as in the
11.0 release (in builds prior to 65.x), App Firewall processing of the Cookie header was changed.
In those releases, every cookie is evaluated individually, and if the length of any one cookie re-
ceived in the Cookie header exceeds the configured BufferOverflowMaxCookieLength, the Buffer
Overflow violation is triggered. As a result of this change, requests that were blocked in 10.5 and
earlier release builds might be allowed, because the length of the entire cookie header is not cal-
culated for determining the cookie length. ** In some situations, the total cookie size forwarded
to the server might be larger than the accepted value, and the server might respond with “400
Bad Request”.

Note that this change has been reverted. The behavior in the 10.5.e ->59.13xx.e and subsequent
10.5.e enhancement builds as well as in the 11.0 release 65.x and subsequent builds is now simi-
lar to that of the non-enhancement builds of release 10.5. The entire raw Cookie header is now
considered when calculating the length of the cookie. Surrounding spaces and the semicolon (;)
characters separating the name-value pairs are also included in determining the cookie length.**

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1636

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Cookie consistency check

September 18, 2018

Contributed by:
C

The Cookie Consistency check examines cookies returned by users, to verify that they match the cook-
ies that your web site set for that user. If a modified cookie is found, it is stripped from the request
before the request is forwarded to the web server. You can also configure the Cookie Consistency
check to transform all of the server cookies that it processes, by encrypting the cookies, proxying the
cookies, or adding flags to the cookies. This check applies to requests and responses.

An attacker would normally modify a cookie to gain access to sensitive private information by posing
as a previously authenticated user, or to cause a buffer overflow. The Buffer Overflow check protects
against attempts to cause a buffer overflow by using a very long cookie. The Cookie Consistency check
focuses on the first scenario.

If you use the wizard or the GUI, in the

Modify Cookie Consistency Check dialog box, on the
General tab you can enable or disable the following actions:

• Block
• Log
• Learn
• Statistics
• Transform. If enabled, the Transform action modifies all cookies as specified in the following
settings:
– Encrypt Server Cookies. Encrypt cookies set by your web server, except for any listed in
the Cookie Consistency check relaxation list, before forwarding the response to the client.
Encrypted cookies are decrypted when the client sends a subsequent request, and the
decrypted cookies are reinserted into the request before it is forwarded to the protected
web server. Specify one of the following types of encryption:
* None. Do not encrypt or decrypt cookies. The default.
* Decrypt only. Decrypt encrypted cookies only. Do not encrypt cookies.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1637

NetScaler 12.0

* Encrypt session only. Encrypt session cookies only. Do not encrypt persistent cook-
ies. Decrypt any encrypted cookies.
* Encrypt all. Encrypt both session and persistent cookies. Decrypt any encrypted
cookies.
Note: When encrypting cookies, the App Firewall adds the
HttpOnly flag to the cookie. This flag prevents scripts from accessing and parsing the
cookie. The flag therefore prevents a script-based virus or trojan from accessing a de-
crypted cookie and using that information to breach security. This is done regardless
of the
Flags to Add in Cookies parameter settings, which are handled independently of the
Encrypt Server Cookies parameter settings.
• Proxy Server Cookies. Proxy all non-persistent (session) cookies set by your web server, ex-
cept for any listed in the Cookie Consistency check relaxation list. Cookies are proxied by using
the existing App Firewall session cookie. The App Firewall strips session cookies set by the pro-
tected web server and saves them locally before forwarding the response to the client. When
the client sends a subsequent request, the App Firewall reinserts the session cookies into the
request before forwarding it to the protected web server. Specify one of the following settings:
– None. Do not proxy cookies. The default.
– Session only. Proxy session cookies only. Do not proxy persistent cookies
Note: If you disable cookie proxying after having enabled it (set this value to
None after it was set to
Session only), cookie proxying is maintained for sessions that were established before you
disabled it. You can therefore safely disable this feature while the App Firewall is process-
ing user sessions.
• Flags to Add in Cookies. Add flags to cookies during transformation. Specify one of the follow-
ing settings:
– None. Do not add flags to cookies. The default.
– HTTP only. Add the HttpOnly flag to all cookies. Browsers that support the HttpOnly flag
do not allow scripts to access cookies that have this flag set.
– Secure. Add the Secure flag to cookies that are to be sent only over an SSL connection.
Browsers that support the Secure flag do not send the flagged cookies over an insecure
connection.
– All. Add the HttpOnly flag to all cookies, and the Secure flag to cookies that are to be sent
only over an SSL connection.

If you use the command-line interface, you can enter the following commands to configure the Cookie
Consistency Check:

• set appfw profile <name> -cookieConsistencyAction [**block**] [**learn

**] [**log**] [**stats**] [**none**]
• set appfw profile <name> -cookieTransforms ([**ON**] | [**OFF**])

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1638

NetScaler 12.0

• set appfw profile <name> -cookieEncryption ([**none**] | [**decryptOnly

**] | [**encryptSession**] | [**encryptAll**])
• set appfw profile <name> -cookieProxying ([**none**] | [**sessionOnly
**])
• set appfw profile <name> -addCookieFlags ([**none**] | [**httpOnly**] |
[**secure**] | [**all**])

To specify relaxations for the Cookie Consistency check, you must use the GUI. On the Checks tab
of the Modify Cookie Consistency Check dialog box, click Add to open the Add Cookie Consistency
Check Relaxation dialog box, or select an existing relaxation and click Open to open the Modify Cookie
Consistency Check Relaxation dialog box. Either dialog box provides the same options for configuring
a relaxation.

Following are examples of Cookie Consistency check relaxations:

• Logon Fields. The following expression exempts all cookie names beginning with the string
logon_ followed by a string of letters or numbers that is at least two characters long and no
more than fifteen characters long:

1 ^logon_[0-9A-Za-z]{
2 2,15 }
3 $

• Logon Fields (special characters). The following expression exempts all cookie names begin-
ning with the string türkçe-logon_ followed by a string of letters or numbers that is at least two
characters long and no more than fifteen characters long:

1 ^txC3xBCrkxC3xA7e-logon_[0-9A-Za-z]{
2 2,15 }
3 $

• Arbitrary strings. Allow cookies that contain the string sc-item_, followed by the ID of an item
that the user has added to his shopping cart ([0-9A-Za-z]+), a second underscore (_), and finally
the number of these items he wants ([1-9][0-9]?), to be user-modifiable:

1 ^sc-item_[0-9A-Za-z]+_[1-9][0-9]?$

Caution: Regular expressions are powerful. Especially if you are not thoroughly familiar with PCRE-
format regular expressions, double-check any regular expressions you write. Make sure that they de-
fine exactly the URL you want to add as an exception, and nothing else. Careless use of wildcards, and
especially of the dot-asterisk (
.*) metacharacter/wildcard combination, can have results you do not want or expect, such as blocking
access to web content that you did not intend to block or allowing an attack that the Cookie Consis-
tency check would otherwise have blocked.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1639

NetScaler 12.0

Important

In release 10.5.e (in a few interim enhancement builds prior to 59.13xx.e build) as well as in the
11.0 release (in builds prior to 65.x), App Firewall processing of the Cookie header was changed.
In those releases, every cookie is evaluated individually, and if the length of any one cookie re-
ceived in the Cookie header exceeds the configured BufferOverflowMaxCookieLength, the Buffer
Overflow violation is triggered. As a result of this change, requests that were blocked in 10.5 and
earlier release builds might be allowed, because the length of the entire cookie header is not cal-
culated for determining the cookie length. In some situations, the total cookie size forwarded to
the server might be larger than the accepted value, and the server might respond with “400 Bad
Request”.

Note that this change has been reverted. The behavior in the 10.5.e ->59.13xx.e and subsequent
10.5.e enhancement builds as well as in the 11.0 release 65.x and subsequent builds is now simi-
lar to that of the non-enhancement builds of release 10.5. The entire raw Cookie header is now
considered when calculating the length of the cookie. Surrounding spaces and the semicolon (;)
characters separating the name-value pairs are also included in determining the cookie length.**

Note

Sessionless Cookie Consistency: The cookie consistency behavior has changed in release 11.0.
In earlier releases, the cookie consistency check invokes sessionization. The cookies are stored
in the session and signed. A “wlt_” suffix is appended to transient cookies and a “wlf_” suffix is
appended to the persistent cookies before they are forwarded to the client. Even if the client does
not return these signed wlf/wlt cookies, the App Firewall uses the cookies stored in the session
to perform the cookie consistency check.

In release 11.0, the cookie consistency check is sessionless. The App Firewall now adds a cookie
that is a hash of all the cookies tracked by the App Firewall. If this hash cookie or any other
tracked cookie is missing or tampered with, the App Firewall strips the cookies before forwarding
the request to the back end server and triggers a cookie-consistency violation. The server treats
the request as a new request and sends new Set-Cookie header(s).

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

App Firewall support for Google web toolkit

September 18, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1640

NetScaler 12.0

Contributed by:
C

Note: This feature is available in NetScaler release 10.5.e.

Web servers following Google Web Toolkit (GWT) Remote Procedure Call (RPC) mechanisms can be
secured by the NetScaler App App Firewall without a need for any specific configuration to enable the
GWT support.

What is GWT

The GWT is used for building and optimizing complex high-performance web applications by people
who do not have expertise in XMLHttpRequest, and JavaScript. This open source, free development
toolkit is used extensively for developing small and large scale applications and is quite frequently
used for displaying browser based data such as search results for flights, hotels, and so on. The GWT
provides a core set of Java APIs and widgets for writing optimized JavaScript scripts that can run on
most browsers and mobile devices. The GWT RPC framework makes it easy for the client and server
components of the web application to exchange Java objects over HTTP. GWT RPC services are not the
same as web services based on SOAP or REST. They are simply a lightweight method for transferring
data between the server and the GWT application on the client. GWT handles serialization of the Java
objects exchanging the arguments in the method calls and the return value.

For popular websites that use GWT, see

https://www.quora.com/What-web-applications-use-Google-Web-Toolkit-%28GWT%29

How a GWT request works

The GWT RPC request is pipe delimited and has variable number of arguments. It is carried as a pay-
load of HTTP POST and has the following values:

1. Content-type = text/x-gwt-rpc. Charset can be any value.

2. Method = POST.

The following example shows a valid payload for a GWT request:

1 5|0|8|http://localhost:8080/test/|16878339F02B83818D264AE430C20468| com
.test.client.TestService|testMethod|java.lang.String|java.lang.
Integer| myInput1|java.lang.Integer/3438268394|1|2|3|4|2|5|6|7|8|1|

The request can be divided into three parts:

**a) Header: 5|0|8|**

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1641

NetScaler 12.0

The first 3 digits “5 0 8 ” in the above

request, represent
“version, subversion,
and size of table”,
respectively. These
must be positive
integers.

b) String Table:

http://localhost:8080/test/|16878339F02B83818D264AE430C20468| com.test.
client.TestService|testMethod|java.lang.String|java.lang.Integer|myInput1|
java.lang.Integer/3438268394|

The members of the above pipe delimited string table contain the user-provided inputs. These inputs
are parsed for the App Firewall checks and are identified as follows:

• 1st : http://localhost:8080/test/

This is the Request URL. It should not contain the query part, because the GET method is not
allowed.

• 2nd : 16878339F02B83818D264AE430C20468

Unique HEX identifier. A request is considered malformed if this string has non-hex characters.

• rd : com.test.client.TestService

Service Class name

• 4th : testMethod

Service method name

5th onwards: java.lang.Integer myInput1 java.lang.Integer/3438268394

java.lang.String

• Data-types and data. Non-primitive data-types are specified as

<container>.<sub-cntnr>.name/<integer><identifier>

**c) Payload: 1|2|3|4|2|5|6|7|8|1|**

The payload consists of references to the elements in the string table. These integer values cannot be
larger than the number of elements in the string table.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1642

NetScaler 12.0

App Firewall protection for GWT applications

The App Firewall understands and interprets GWT RPC requests, inspects the payload for security
check violations, and takes specified actions.

The App Firewall headers and cookies checks for GWT requests are similar to those for other request
formats. After appropriate URL decoding and charset conversion, all the parameters in the string table
are inspected. The GWT request body does not contain field names, just the field values. The input
values can be validated against the specified format by using the App Firewall Field Format check,
which can also be used to control the length of the input. The Cross-site Scripting and SQL Injection
attacks in the inputs can be easily detected and thwarted by the App Firewall.

Learning and relaxation rules: Learning and deployment of relaxation rules are supported for GWT
requests. App Firewall rules are in the form of <actionURL> <fieldName> mapping. The GWT re-
quest format does not have the field names and thus requires special handling. The App Firewall
inserts dummy field names in the learned rules that can be deployed as relaxation rules. The -isRegex
flag works as it does for non-GWT rules.

• Action URL:

Multiple services responding to an RPC can be configured on the same web server. The HTTP
request has the URL of the web server, not of the actual service handling the RPC. Therefore,
relaxation is not applied on the basis of the HTTP request URL, because that would relax all the
services on that URL for the target field. For GWT requests, the App Firewall uses the URL of the
actual service found in the GWT payload, in the fourth field in the string table.

• Field name:

Since the GWT request body contains only field values, the App Firewall inserts dummy field
names such as 1, 2, and so on when recommending learned rules.

Example of a GWT learned rule

1 POST /abcd/def/gh HTTP/1.1

2 Content-type: text/x-gwt-rpc
3 Host: 10.217.222.75
4 Content-length: 157
5
6 5|0|8|http://localhost:8080/acdtest/|16878339
F02Baf83818D264AE430C20468|
7 com.test.client.TestService|testMethod|java.lang.String%3b|java.
lang.Integer|onblur|
8
9 The learn data will be as follows:
10 > sh learningdata pr1 crossSiteScripting
11 Profile: pr1 SecurityCheck: crossSiteScripting

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1643

NetScaler 12.0

12 1) Url: http://localhost:8080/acdtest/ >> From GWT Payload.

13 Field: 10
14 Hits: 1
15 Done

Example of a GWT relaxation rule

bind appfw profile pr1 -crossSiteScripting 1 abcd -isregex NOTREGEX

Log Messages: The App Firewall generates log messages for the security check violations that are
detected in the GWT requests. A log message generated by a malformed GWT request contains the
string “GWT” for easy identification.

Example of a Log message for malformed GWT request:

Dec 5 21:48:02 <local0.notice> 10.217.31.247 12/05/2014:21:48:02 GMT ns

0-PPE-0 : APPFW Message 696 0 : ”GWT RPC request with malformed payload. <
blocked>”

Difference in processing of GWT vs non-GWT requests:

The same payload can trigger different App Firewall security check violations for different Content-
types. Consider the following example:

5|0|8|http://localhost:8080/acdtest/|16878339F02Baf83818D264AE430C20468|com
.test.client.TestService|testMethod|java.lang.String%3b|java.lang.Integer|
select|

Content-type: application/x-www-form-urlencoded:

A request sent with this content type results in a SQL violation if the SQL Injection Type is configured
to use any of the four available options: SQLSplCharANDKeyword, SQLSplCharORKeyword, SQLKey-
word, or SQLSplChar. The App Firewall considers ‘&’ to be the field separator and ‘=’ to be the name-
value separator when processing the above payload. Since neither of these characters appears any-
where in the post body, the entire content is treated as a single field name. The field name in this
request contains both an SQL special character (;) and an SQL Keyword (select). Therefore violations
are caught for all four SQL Injection type options.

Content-type: text/x-gwt-rpc:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1644

NetScaler 12.0

A request sent with this content type triggers ’ to be the field separator for the above payload
an SQL violation only if the SQL injection type in the GWT request. Therefore, the post body is
is set to one of the following three divided into various form-field values, and
options:SQLSplCharORKeyword,SQLKeyword, form-field names are added (in accordance
or SQLSplChar. No violation is triggered if the with the convention described earlier).
SQL injection type is set to Because of this splitting, the SQL special
SQLSplCharANDKeyword, which is the default character and SQL keyword become parts of
option. The App Firewall considers the vertical separate form fields.
bar ‘

Form field 8: java.lang.String%3b -> %3b is the (;) char

Form Field 10: select

As a result, when SQL Injection Type is set to SQLSplChar, field 8 indicates the SQL violation. For
SQLKeyword, field 10 indicates the violation. Either of these two fields can indicate a violation if the
SQL Inject type is configured with the SQLSplCharORKeyword option, which looks for the presence
of either a keyword or a special character. No violation is caught for the default SQLSplCharAND-
Keyword option, because there is no single field that has a value that contains both SQLSplChar and
SQLKeyword together.

Tips:

• No special App Firewall configuration is needed to enable GWT support.

• The Content-type must be text/x-gwt-rpc.
• Learning and deploying of the relaxation rules for all the pertinent App Firewall security checks
applied to GWT payload works the same as it does for the other supported content-types.
• Only POST requests are considered valid for GWT. All other request methods are blocked if the
content-type is text/x-gwt-rpc.
• GWT requests are subject to the configured POST body limit of the profile.
• The sessionless setting for the security checks is not applicable and will be ignored.
• CEF log format is supported for the GWT log messages.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1645

NetScaler 12.0

Data leak prevention checks

September 18, 2018

Contributed by:
C

The data-leak-prevention checks filter responses to prevent leaks of sensitive information, such as
credit card numbers and social security numbers, to unauthorized recipients.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Credit card check

September 18, 2018

Contributed by:
C

If you have an application that accepts credit cards, or your websites have access to database servers
that store credit card numbers, you must use Data Leak Prevention (DLP) measures and configure
protection for each type of credit card that you accept.

The NetScaler App App Firewall Credit Card check prevents attackers from exploiting Data Leak Pre-
vention flaws to obtain credit card numbers of your customers. By following simple configuration
steps, you can enforce protection of one or more of the following credit cards: 1) Visa, 2) Master Card,
3) Discover, 4) American Express (Amex), 5) JCB, and 6) Diners Club.

The Credit Card security check examines server responses to identify instances of the target credit card
numbers, and applies a specified action when such a number is found. The action can be to transform
the response by X’ing out all but the last group of digits in the credit card number, or to block the
response if it contains more than a specified number of credit card numbers. If you specify both, the
block action takes precedence. The Maximum credit cards allowed per page setting determines when
the block action is invoked. The default setting, 0 (no credit card numbers allowed on the page), is
the safest, but you can allow up to 255. Depending on where the violation is detected in the response
and the block action gets triggered, you might get fewer than the maximum allowed number of credit
cards in the response.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1646

NetScaler 12.0

To avoid false positives, you can apply relaxations to exempt specific numbers from the Credit Card
check. For example, a social security number, purchase order number, or Google account number
might be similar to a credit card number. You can specify individual numbers or use a regular expres-
sion to indicate the string of digits to be bypassed when processing the response URL for credit card
inspection.

If you’re not sure which credit card numbers to exempt, you can use the learn feature to generate
recommendations based on the learned data. To get optimal benefit without compromising perfor-
mance, you might want to enable this option for a short time to get a representative sample of the
rules, and then deploy the relaxations and disable learning.

If you enable the log feature, the Credit Card check generates log messages indicating the actions
that it takes. You can monitor the logs to determine whether responses to legitimate requests are
getting blocked. A large increase in the number of log messages can indicate thwarted attempts to
gain access. By default, the doSecureCreditCardLogging parameter is ON, so the credit card number
is not included in the log message generated by the safe commerce (Credit Card) violation.

The stats feature gathers statistics about violations and logs. An unexpected surge in the stats counter
might indicate that your application is under attack.

To configure the Credit Card security check for protecting your application, configure the profile that
governs inspecting the traffic to and from this application.

Note:

A website that does not access a SQL database usually does not have access to sensitive private
information such as credit card numbers.

Using the command line to configure the credit card check

In the command line interface, you can use either the set appfw profile command or the add appfw
profile command to activate credit-card checking and specify which actions to perform. You can use
the unset appfw profile command to revert back to the default settings. To specify relaxations, use
the bind appfw command to bind credit card numbers to the profile.

To configure a credit card check by using the command line

Use either the set appfw profile command or the add appfw profile command, as follows:

• set appfw profile <name> -creditCardAction ( ([block][learn] [log][

stats])| [none])

• set appfw profile <name> -creditCard (VISA | MASTERCARD | DISCOVER |

AMEX | JCB | DINERSCLUB)

• set appfw profile <name> -creditCardMaxAllowed <integer>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1647

NetScaler 12.0

• set appfw profile <name> -creditCardXOut ([ON] | [OFF])<name> -doSecureCreditCard

([ON] | [OFF])

• To configure a Credit Card relaxation rule by using the command line

Use the bind command to bind the credit card number to the profile. To remove a credit card number
from a profile, use the unbind command, with the same arguments that you used for the bind com-
mand. You can use the show command to display the credit card numbers bound to a profile.
-
To bind a credit card number a profile

1 ‘bind appfw profile <profile-name> -creditCardNumber <any number/

regex> “ <url> ” ‘
2
3 **Example**: bind appfw profile test_profile -creditCardNumber
378282246310005 ‘http://www.example.com/credit\_card\_test.html‘
4
5 -
6 To unbind a credit card number from a profile
7
8 ‘unbind appfw profile <profile-name>
9 -creditCardNumber <credit card number / regex> “ <url>‘
10 -
11 To show the list of credit card numbers bound to a profile.
12
13 show appfw profile <profile>

Using the GUI to configure the credit card check

In the GUI, you configure the credit card security check in the pane for the profile associated with your
application.
To add or modify the Credit Card security check by using the GUI
1. Navigate to App Firewall > Profiles, highlight the target profile, and click Edit.
2. In the Advanced Settings pane, click Security Checks.
The security check table displays the currently configured action settings for all the security
checks. You have 2 options for configuration:
a) If you just want to enable or disable Block, Log, Stats, and Learn actions for Credit Card,
you can select or clear check boxes in the table, click OK, and then click Save and Close to
close the Security Check pane.
b) If you want to configure additional options for this security check, double click Credit Card,
or select the row and click Action Settings to display additional options as follows:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1648

NetScaler 12.0

• Out—Mask any credit card number detected in a response by replacing each digit,
except the digits in the final group, with the letter “X.
• Maximum credit cards allowed per page—Specify the number of credit cards that can
be forwarded to the client without triggering a block action.
• Protected Credit Cards. Select or clear a check box to enable or disable protection for
each type of credit card.
• You can also edit the Block, Log, Stats and Learn actions in the Credit Card Settings
pane.
After making any of the above changes, click OK to save the changes and return to the
Security Checks table. You can proceed to configure other security checks if needed.
Click OK to save all the changes you have made in the Security Checks section and
then click Save and Close to close the Security Check pane.

3. In the Advanced Settings pane, click Profile settings. To enable or disable secure logging of
credit card Numbers, select or clear the Secure Credit Card Logging check box. (By default, it
is selected).

Click OK to save the changes.

• To configure a Credit Card relaxation rule by using the GUI

1. Navigate to App Firewall > Profiles, highlight the target profile, and click Edit.
2. In the Advanced Settings pane, click Relaxation Rules. The Relaxation Rules table has
a Credit Card entry. You can double click, or select this row and click Edit to access the
Credit Card Relaxation Rules dialogue. You can perform Add, Edit, Delete, Enable, or
Disable operations for relaxation rules.

Using the learn feature with the credit card check

When the learn action is enabled, the App Firewall learning engine monitors the traffic and learns the
triggered violations. You can periodically inspect these learned rules. After due consideration, if you
want to exempt a specific string of digits from the Credit Card security check, you can by deploy the
learned rule as a relaxation rule.

• To view or use learned data by using the command line interface

show appfw learningdata <profilename> creditCardNumber

rm appfw learningdata <profilename> -creditcardNumber <credit card

number> “<url>”

export appfw learningdata <profilename> creditCardNumber

• To view or use learned data by using the GUI

1. Navigate to App Firewall > Profiles, highlight the target profile, and click Edit.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1649

NetScaler 12.0

2. In the Advanced Settings pane, click Learned Rules. You can select the Credit Card entry
in the Learned Rules table and double-click it to access the learned rules. You can deploy
the learned rules or edit a rule before deploying it as a relaxation rule. To discard a rule,
you can select it and click the Skip button. You can edit only one rule at a time, but you
can select multiple rules to deploy or skip.

You also have the option to show a summarized view of the learned relaxations by selecting
the Credit Card entry in the Learned Rules table and clicking Visualizer to get a consolidated
view of all the learned violations. The visualizer makes it very easy to manage the learned rules.
It presents a comprehensive view of the data on one screen and facilitates taking action on a
group of rules with one click. The biggest advantage of the visualizer is that it recommends
regular expressions to consolidate multiple rules. You can select a subset of these rules, based
on the delimiter and Action URL. You can display 25, 50, or 75 rules in the visualizer, by selecting
the number from a drop-down list. The visualizer for learned rules offers the option to edit the
rules and deploy them as relaxations. Or you can skip the rules to ignore them.

Using the log feature with the credit card check

When the log action is enabled, the Credit Card security check violations are logged in the audit log as
APPFW_SAFECOMMERCE or APPFW_SAFECOMMERCE_XFORM violations. The App Firewall supports
both Native and CEF log formats. You can also send the logs to a remote syslog server.

The default setting for doSecureCreditCardLogging is ON. If you change it to OFF, both credit card
number and type are included in the log message.

Depending on the settings configured for the Credit Card checks, the application-firewall generated
log messages might include the following information:

• Response was blocked or not blocked.

• Credit card numbers were transformed (X’d out). A separate log message is generated for each
transformed credit card number, so multiple log messages might be generated during process-
ing of a single response.

• Response contained the maximum number of potential credit card numbers.

• Credit card numbers and their corresponding types.

• To access the log messages by using the command line

Switch to the shell and tail the ns.logs in the /var/log/ folder to access the log messages pertain-
ing to the Credit Card violations:

– Shell

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1650

NetScaler 12.0

tail -f /var/log/ns.log grep SAFECOMMERCE

• To access the log messages by using the GUI

1. The NetScaler GUI includes a very useful tool (Syslog Viewer) for analyzing the log mes-
sages. You have a couple of options for accessing the Syslog Viewer: Navigate to the tar-
get profile > Security Checks. Highlight the Credit Card row and click Logs. When you
access the logs directly from the Credit Card security check of the profile, it filters out the
log messages and displays only the logs pertaining to these security check violations.

2. You can also access the Syslog Viewer by navigating to NetScaler > System > Auditing. In
the Audit Messages section, click the Syslog messages link to display the Syslog Viewer,
which displays all log messages, including other security check violation logs. This is use-
ful for debugging when multiple security check violations might be triggered during re-
quest processing.

The HTML based Syslog Viewer provides various filter options for selecting only the log
messages that are of interest to you. To access Credit Card security check violation log
messages, filter by selecting APPFW in the dropdown options for Module. The Event Type
displays a rich set of options to further refine your selection. For example, if you select the
APPFW_SAFECOMMERCE and APPFW_SAFECOMMERCE_XFORM check boxes and click the
Apply button, only log messages pertaining to the Credit Card security check violations
appear in the Syslog Viewer.

If you place the cursor in the row for a specific log message, multiple options, such as Mod-
ule and EventType, appear below the log message. You can select any of these options to
highlight the corresponding information in the logs.

Example of a Native format log message when the response is not blocked

1 May 29 01:26:31 <local0.info> 10.217.31.98 05/29/2015:01:26:31 GMT ns

0-PPE-0 :
2 default APPFW APPFW_SAFECOMMERCE 2181 0 : 10.217.253.62 1098-PPE0
3 4erNfkaHy0IeGP+nv2S9Rsdu77I0000 pr_ffc http://aaron.stratum8.net/FFC/
CreditCardMind.html
4 Maximum number of potential credit card numbers seen <not blocked>

Example of a CEF format log message when the response is transformed

1 May 28 23:42:48 <local0.info> 10.217.31.98

2 CEF:0|Citrix|NetScaler|NS11.0|APPFW|APPFW_SAFECOMMERCE_XFORM|6|src
=10.217.253.62

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1651

NetScaler 12.0

3 spt=25314 method=GET request=http://aaron.stratum8.net/FFC/

CreditCardMind.html
4 msg=Transformed (xout) potential credit card numbers seen in server
response
5 cn1=66 cn2=1095 cs1=pr_ffc cs2=PPE2 cs3=xzE7M0g9bovAtG/zLCrLd2zkVl80002
6 cs4=ALERT cs5=2015 act=transformed

Example of a CEF format log message when the response is blocked. The credit card number and type
can be seen in the log, because the doSecureCreditCardLogging parameter is disabled.

1 May 28 23:42:48 <local0.info> 10.217.31.98

2 CEF:0|Citrix|NetScaler|NS11.0|APPFW|APPFW_SAFECOMMERCE|6|src
=10.217.253.62
3 spt=25314 method=GET request=http://aaron.stratum8.net/FFC/
CreditCardMind.html
4 msg=Credit Card number 4505050504030302 of type Visa is seen in
response cn1=68
5 cn2=1095 cs1=pr_ffc cs2=PPE2 cs3=xzE7M0g9bovAtG/zLCrLd2zkVl80002 cs4=
ALERT cs5=2015
6 act=blocked

Statistics for the credit card violations

When the stats action is enabled, the corresponding counter for the Credit Card check is incremented
when the App Firewall takes any action for this security check. The statistics are collected for Rate and
Total count for Traffic, Violations, and Logs. The increment of the log counter can vary depending on
the configured settings. For example, if the block action is enabled and the Max Allowed credit card
setting is 0, the request for a page that contains 20 credit card numbers increments the stats counter
by one when the page is blocked as soon as the first credit card number is detected. However, if block
is disabled and transform is enabled, processing the same request increments the statistics counter
for logs by 20, because each credit card transformation generates a separate log message.

• To display Credit Card statistics by using command line

At the command prompt, type:

sh appfw stats

To display stats for a specific profile, use the following command:

stat appfw profile <profile name>

To display Credit Card statistics by using GUI

1. Navigate to System > Security > App Firewall.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1652

NetScaler 12.0

2. In the right pane, access the Statistics Link.

3. Use the scroll bar to view the statistics about Credit Card violations and logs. The statistics
table provides real-time data and is updated every 7 seconds.

Highlights

Note the following points about the Credit Card security check:

• The App Firewall enables you to protect credit card information and detect any attempts to ac-
cess this sensitive data.

• To use the Credit Card protection check, you must specify at least one type of credit card and
an action. The check is then applied to HTML, XML, and Web 2.0 profiles.

You can pipe the output of sh appfw profile grep CreditCard displays the configured
command and grep for CreditCard to see all settings of various parameters as well as the
the Credit Card specific configuration. For relaxation rules pertaining to the Credit Card
example, sh appfw profile my_profile check for the App Firewall profile named
my_profile.

• You can exclude specific numbers from Credit Card inspection without bypassing the security
check inspection for the rest of the credit card numbers.

• Relaxation is available for all App Firewall protected credit card patterns. In the GUI, you can
use the visualizer to specify Add, Edit, Delete, Enable, or Disable operations on relaxation rules.

• The App Firewall learning engine can monitor the outgoing traffic to recommend rules based
on observed violations. Visualizer support is also available for managing the learned credit card
rules in the GUI. You can edit and deploy the learned rules, or skip them after careful inspection.

• The setting for number of allowed credit cards applies to each response. It does not pertain to
the cumulative total of credit card numbers observed during the entire user session.

• The number of X’d out digits depends on the length of the credit card numbers. Ten digits are
X’d out for credit cards that have 13 through 15 digits. Twelve digits are X’d out for credit cards
that have 16 digits. If your application does not require sending the entire credit card number
in the response, Citrix recommends that you enable this action to mask the digits in the credit
card numbers.

• The X-out operation transforms all the credit cards and works independently of the configured
settings for the maximum number of allowed credit cards. For example, if there are 4 credit
cards in the response and the creditCardMaxAllowed parameter is set to 10, all 4 credit cards

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1653

NetScaler 12.0

are X’d-out, but they are not blocked. If the credit card numbers are spread out in the docu-
ment, a partial response with X’d-out numbers might be sent to the client before the response
is blocked.

• Do not disable the doSecureCreditCardLogging parameter before due consideration. When this
parameter is turned off, the credit card numbers are displayed and are accessible in the log
messages. These numbers are not masked in the logs, even if the X-out action is enabled. If
you are sending logs to a remote syslog server, and the logs are compromised, the credit card
numbers can be exposed.

• When the response page is blocked because of a Credit Card violation, the App Firewall does
not redirect to the error page.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Safe object check

September 18, 2018

Contributed by:
C

The Safe Object check provides user-configurable protection for sensitive business information, such
as customer numbers, order numbers, and country-specific or region-specific telephone numbers or
postal codes. A user-defined regular expression or custom plug-in tells the App Firewall the format of
this information and defines the rules to be used to protect it. If a string in a user request matches a
safe object definition, the App Firewall either blocks the response, masks the protected information,
or removes the protected information from the response before sending it to the user, depending on
how you configured that particular safe object rule.

The Safe Object check prevents attackers from exploiting a security flaw in your web server software
or on your web site to obtain sensitive private information, such as company credit card numbers or
social security numbers. If your web sites do not have access to these types of information, you do
not need to configure this check. If you have a shopping cart or other application that can access such
information, or your web sites have access to database servers that contain such information, you
should configure protection for each type of sensitive private information that you handle and store.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1654

NetScaler 12.0

Note:

A web site that does not access an SQL database usually does not have access to sensitive private
information.

The Safe Object Check dialog box is unlike that for any other check. Each safe object expression that
you create is the equivalent of a separate security check, similar to the Credit Card check, for that
type of information. If you use the wizard or the GUI, you add a new expression by clicking Add and
configuring the expression in the Add Safe Object dialog box. You modify an existing expression by
selecting it, then clicking Open, and then configuring the expression in the Modify Safe Object dialog
box.

In the Safe Object dialog box for each safe object expression, you can configure the following:

• Safe Object Name. A name for your new safe object. The name can begin with a letter, number,
or the underscore symbol, and can consist of from one to 255 letters, numbers, and the hyphen
(-), period (.) pound (#), space ( ), at sign (@), equals (=), colon (:), and underscore (_) symbols.

• Actions. Enable or disable the

Block,
Log, and
Statistics actions, and the following actions:

– X-Out. Mask any information that matches the safe object expression with the letter “X”.
– Remove. Remove any information that matches the safe object expression.

• Regular Expression. Enter a PCRE-compatible regular expression that defines the safe object.
You can create the regular expression in one of three ways: by typing the regular expression
directly into the text box, by using the Regex Tokens menu to enter regular expression elements
and symbols directly into the text box, or by opening the Regular Expressions Editor and using
it to construct the expression. The regular expression must consist of ASCII characters only. Do
not cut and paste characters that are not part of the basic 128-character ASCII set. If you want to
include non-ASCII characters, you must manually type those characters in PCRE hexadecimal
character encoding format.
Note: Do not use start anchors (ˆ) at the beginning of Safe Object expressions, or end anchors
($) at the end of Safe Object expressions. These PCRE entities are not supported in Safe Object
expressions, and if used, will cause your expression not to match what it was intended to match.

• Maximum Match Length. Enter a positive integer that represents the maximum length of the
string that you want to match. For example, if you want to match U.S. social security numbers,
enter the number eleven (11) in this field. That allows your regular expression to match a string
with nine numerals and two hyphens. If you want to match California driver’s license numbers,
enter the number eight (8).

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1655

NetScaler 12.0

Caution:

If you do not enter a maximum match length in this field, the App Firewall uses a default
value of one (1) when filtering for strings that match your safe object expressions. As a
result, most safe object expressions fail to match their target strings.

You cannot use the command-line interface to configure the Safe Object check. You must configure it
by using either the App Firewall wizard or the GUI.

Following are examples of Safe Object check regular expressions:

• Look for strings that appear to be U.S. social security numbers, which consist of three numerals
(the first of which must not be zero), followed by a hyphen, followed by two more numerals,
followed by a second hyphen, and ending with a string of four more numerals:

1 [1-9][0-9]{
2 2,2 }
3 -[0-9]{
4 2,2 }
5 -[0-9]{
6 4,4 }

• Look for strings that appear to be California driver’s license IDs, which start with a letter and are
followed by a string of exactly seven numerals:

1 [A-Za-z][0-9]{
2 7,7 }

• Look for strings that appear to be Example Manufacturing customer IDs which, consist of a string
of five hexadecimal characters (all the numerals and the letters A through F), followed by a hy-
phen, followed by a three-letter code, followed by a second hyphen, and ending with a string of
ten numerals:

1 [0-9A-Fa-f]{
2 5,5 }
3 -[A-Za-z]{
4 3,3 }
5 -[0-9]{
6 10,10 }

Caution: Regular expressions are powerful. Especially if you are not thoroughly familiar with
PCRE-format regular expressions, double-check any regular expressions you write to ensure that
they define exactly the type of string you want to add as a safe object definition, and nothing
else. Careless use of wildcards, and especially of the dot-asterisk (.*) metacharacter/wildcard

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1656

NetScaler 12.0

combination, can have results you did not want or expect, such as blocking access to web content
that you did not intend to block.
1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Advanced form protection checks

September 18, 2018

Contributed by:
C

The advanced Form Protection checks examine web form data to prevent attackers from compromis-
ing your system by modifying the web forms on your web sites or sending unexpected types and quan-
tities of data to your web site in a form.

Note

SQL, XSS, FFC, and FieldFormat protection checks are applied if the Exclude Upload Files From
Security Checks is unset.

A file upload is also a form element that has control-name name field that is submitted as part of form
submission.

Refer to this page, for more information: Forms

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Field formats check

January 6, 2019

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1657

NetScaler 12.0

The Field Formats check verifies the data that users send to your web sites in web forms. It examines
both the length and type of data to ensure that it is appropriate for the form field in which it appears.
If the App Firewall detects inappropriate web form data in a user request, it blocks the request.
By preventing an attacker from sending inappropriate web form data to your web site, the Field For-
mats check prevents certain types of attacks on your web site and database servers. For example, if
a particular field expects the user to enter a phone number, the Field Formats check examines the
user-submitted input to ensure that the data matches the format of a phone number. If a particular
field expects a first name, the Field Formats check ensures that the data in that field is of a type and
length appropriate for a first name. It does the same thing for each form field that you configure it to
protect.
This check applies to HTML requests only. It does not apply to XML requests. You can configure Field
Format Checks in HTML profiles or Web 2.0 profiles to inspect HTML payload for protecting your appli-
cations. The App Firewall also supports Field Format Check protection for Google Web Toolkit (GWT)
applications.
The Field Formats check requires that you enable one or more actions. The App Firewall examines the
submitted inputs and applies the specified actions.
Note

Field format rules are tightening rules. Adding them to relaxation list from learned data acts as
a blocking rule.

To relax field format rules, please remove particular “fieldname” from the fieldformat relaxations
list.
You have the option to set the default field formats to specify Field Type and the minimum and max-
imum length of data expected in each form field on each web form that you want to protect. You
can deploy relaxation rules to configure a Field Format for an individual field of a specific form. Mul-
tiple rules can be added to specify the field name, the action URL, and Field Formats. Specify Field
Formats to accept different types of inputs in different form fields. The learning feature can provide
recommendations for the relaxation rules.
Field Format Actions—You can enable Block, Log, Stats, and Learn actions. At least one of these
actions must be enabled to engage the Field Format Check protection.
• Block. If you enable block, the block action is triggered if the input does not conform to the
specified Field Format. If a rule was configured for the target field, the input is checked against
the specified rule. Otherwise, it is checked against the default field format specification. Any
mismatch in the Field Type or min/max length specification results in blocking the request.
• Log. If you enable the log feature, the Field Format check generates log messages indicating
the actions that it takes. You can monitor the logs to determine whether responses to legiti-
mate requests are getting blocked. A large increase in the number of log messages can indicate
malicious attempts to launch an attack.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1658

NetScaler 12.0

• Stats. If enabled, the stats feature gathers statistics about violations and logs. An unexpected
surge in the stats counter might indicate that your application is under attack, or you might have
to revisit the configuration to see if the specified field format is too restrictive.
• Learn. If you are not sure which Field Types or minimum and maximum length values might be
ideally suited for your application, you can use the learn feature to generate recommendations
based on the learned data. The App Firewall learning engine monitors the traffic and provides
field format recommendations based on the observed values. To get optimal benefit without
compromising performance, you might want to enable the learn option for a short time to get
a representative sample of the rules, and then deploy the rules and disable learning.
Note: The App Firewall’s learning engine can distinguish only the first 128 bytes of the name.
If a form has multiple fields with names that match for the first 128 bytes, the learning engine
might not be able to distinguish between them. Similarly, the deployed relaxation rule might
inadvertently relax all such fields.

Default Field Format—In addition to configuring the actions, you can configure the default Field For-
mat to specify the type of data expected in all the form fields for your application. A Field Type can be
selected as the Field Format type. Minimum length and Maximum length parameters can be used to
specify the length of the allowed inputs. As an alternative to Field Types, you can use Character Maps
to specify what’s allowed in a field (except in cluster deployments).

• Field Type—Field Types are named expression to which you assign assigned priority values.
Field Type expressions specify the allowed inputs and are matched against the submitted data
to determine whether the received values are consistent with the allowed values. The Field
Types are checked in the order of their priority numbers. A lower number indicates a higher
priority. The App Firewall gives you the option to add your own Field Types and assign them the
priorities you want. The priority value can range from 0 through 64000. The following built-in
Field Types are provided to help simplify the configuration process:

1 > sh appfw fieldtype

2 1) Name: integer Regex: ”^[+-]?[0-9]+$”
3 Priority: 30 Comment: Integer
4 Builtin: IMMUTABLE
5 2) Name: alpha Regex: ”^[a-zA-Z]+$”
6 Priority: 40 Comment: ”Alpha
characters”
7 Builtin: IMMUTABLE
8 3) Name: alphanum Regex: ”^[a-zA-Z0-9]+$”
9 Priority: 50 Comment: ”Alpha-numeric
characters”
10 Builtin: IMMUTABLE
11 4) Name: nohtml Regex: ”^[^&<>]*$”
12 Priority: 60 Comment: ”Not HTML”
13 Builtin: IMMUTABLE

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1659

NetScaler 12.0

14 5) Name: any Regex: ”^.*$”

15 Priority: 70 Comment: Anything
16 Builtin: IMMUTABLE
17 Done
18 >

Note: The built-in Field Types are IMMUTABLE. They cannot be modified or removed. Any
Field Types that you add are MODIFIABLE. You can edit them or remove them.

Configuring a Field Type as a default Field Format might be useful when you have a PCRE expres-
sion that can identify the valid inputs in all or most of the form fields for your application and
exclude the invalid inputs. For example, if all the inputs in your application forms are expected
to contain only numbers and letters, you might want to use the built-in Field Type alphanum as
the default Field Type. Any non-alphanumeric character such as a backslash () or semicolon (;)
in the input will trigger a violation. You can also add your own customized Field Types and use
them to configure default Field Formats. For example, if you want to make the lowercase “x”,
“y”, and “z” the only allowed alpha characters, you can configure a customized Field Type with
regular expression “ˆ[x-z]+$”. You could assign it a higher priority (lower priority number) then
the built-in Field Types and use it as the default Field Type.

• Minimum Length — The default minimum data length assigned to form fields in web forms that
do not have an explicit setting. This parameter is set to 0 by default, which allows the user to
leave the field blank. Any higher setting forces users to fill in the field.

Caution: If the minimum length value is 0 but the Field Type is integer, alpha, or alphanum,
a request is blocked if any input field is left empty, despite the minimum length setting. That
is because the regEx for these Field Types contains a + character, which means one or more
characters. Distinguishing an integer from an alpha character requires at least one character.

• Maximum Length—The default maximum data length assigned to form fields in web forms that
do not have an explicit setting. This parameter is set to 65535 by default.

Note: Characters vs bytes. The minimum and the maximum lengths for the field formats
represent the number of bytes, not the number of characters. Languages that have greater
than one-byte character representation can cause the limit to be exceeded with fewer char-
acters than the number configured for the maximum value. For example, with double-byte
character representation, the maximum value of 9 allows no more than 4 characters.
Tip: The GUI allows you to cut and paste UTF-8 characters directly into the GUI without
having to convert them to hex.

• Character Maps: In addition to recommending the Field Types, the App Firewall learning en-
gine offers you an additional option, Use Character Maps, to deploy the Format Check rules. A
Character Map is a set of all the characters allowed in a particular form field. You can fine tune
the Field format specification to allow or disallow specific characters by using Character Maps.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1660

NetScaler 12.0

A separate Character Map is generated for each form field. The alpha and numeric characters
are treated differently in Character Maps. If any alpha character is seen in the input, all alpha
characters [A-Za-z] will be allowed by the recommended PCRE expression in the Character Map.
Similarly, if any digit is included, all digits [0-9] will be allowed. Non-printable characters are
specified by using the x construct. Only single Byte characters with values between 0-255 are
considered for Character Map recommendations.

A Character Map can be more specific than the corresponding Field Type recommendation. In
some situations, Character Maps might be a better option, because they give you tighter control
over the set of characters allowed as inputs. The deployed character maps are displayed as
strings that start with prefix “CM” followed by digits. The priority for the Character Maps starts at
10000. As with user-added Field Types, you can add, edit or remove a Character Map. Character
Maps that are currently used in deployed rules cannot be modified or removed.

Note: Character Maps are not supported in cluster deployments.

Note

When you add a field formats rule with any built-in Field Type and use character map instead of
Field Type and save it, the changes do not get saved and rule still shows with Field Type.

When the character map matches one of the built-in type, the field type is reused instead of cre-
ating a new character map.

Using the command line to configure the field format check

In the command line interface, you can use the add appfw fieldtype command to add a new Field Type.
You can use either the set appfw profile command or the add appfw profile command to configure
the Field Format check and specify which actions to perform. You can use the unset appfw profile
command to revert the configured settings back to their defaults. To specify a Field Format rule, use
the bind appfw command to bind a Field Type to a form Field and the action URL, along with the
minimum and maximum length specifications.

To add, remove or view a Field Type by using the command line:

Use the add command to add a Field Type. You must specify the Name, Regular expression and Priority
when adding a new Field Type. You also have the option to add a Comment. You can use the show
command to display the configured Field Types. You can also delete a Field Type by using the remove
command, which requires only the Name of the Field Type.

add [appfw] fieldType <name> <regex> <priority> [-comment <string>]

where:

<regex> is a reqular expression

<priority> is a positive_integer

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1661

NetScaler 12.0

Example:

1 add fieldtype ”Cust_Zipcode” ”^[0-9]{

2 5 }
3 [-][0-9]{
4 4 }
5 $” 4
6
7 - show [appfw] fieldType [<name>]
8
9 Example: sh fieldtype
10
11 sh appfw fieldtype
12
13 sh appfw fieldtype cust_zipcode
14
15 - ‘rm [appfw] fieldType <name>‘
16
17 Example: rm fieldtype cusT_ziPcode
18
19 ‘rm appfw fieldtype cusT_ziPcode‘

Note: As shown above, use of “appfw” in the command is optional. For example, “Add Field-
Type” or “Add appfw fieldType” are both valid options. The names of the Field Types are case
insensitive due to normalization. As shown in the above examples, Cust_Zipcode, cust_zipcode,
and cUsT_ziPcode refer to the same Field Type.

To configure a Field Format check by using the command line

Use either the set appfw profile command or the add appfw profile command, as follows:

• set appfw profile <name> -fieldFormatAction (([block] [learn] [log] [

stats])| [none])
• set appfw profile <name>-defaultFieldFormatType <string>
• set appfw profile <name> -defaultFieldFormatMinLength <integer>
• set appfw profile <name> -defaultFieldFormatMaxLength <integer>

To configure a Field Format relaxation rule by using the command line

1 bind appfw profile <name> (-fieldFormat <string> <formActionURL> <

fieldType>
2 [-fieldFormatMinLength <positive_integer>] [-fieldFormatMaxLength <
positive_integer>]
3 [-isRegex ( REGEX | NOTREGEX )])

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1662

NetScaler 12.0

1 bind appfw profile pr_ffc -fieldFormat ”login_name” ”.*/login.php”

integer -fieldformatMinLength 3 -FieldformatMaxlength 6

Using the GUI to Configure the field formats security check

In the GUI, you can manage the Field Types. You can also configure the Field Formats security check
in the pane for the profile associated with your application.
To add, modify or remove a Field Type using the GUI
1. Navigate to Application Firewall node. In the Settings, click Manage Field Types to display the
Configure Application Firewall Field Type dialogue box.
2. Click Add to add a new Field Type. Follow the instructions in this pane and click Create. You can
also edit or delete any user-added Field Type if it is currently not being used by a deployed rule.
To add or modify the Field Formats security check by using the GUI
1. Navigate to Application Firewall > Profiles, highlight the target profile, and click Edit.
2. In the Advanced Settings pane, click Security Checks.
The security check table displays the currently configured action settings for all the security
checks. You have 2 options for configuration:
a) If you just want to enable or disable Block, Log, Stats, and Learn actions for Field Formats,
you can select or clear check boxes in the table, click OK, and then click Save and Close
to close the Security Check pane.
b) If you want to configure additional options for this security check, double click Field For-
mats, or select the row and click Action Settings, to display the following options for De-
fault Field Format:
• Field Type—Select the Field Type that you want to configure as the default Field Type.
You can select the built-in and user-defined Field Types. The deployed Character Maps
are also included in the list and can be selected.
• Minimum Length—Specify the minimum number of characters that must be in each
field. Possible values: 0-65535.
• Maximum Length— Specify the maximum number of characters that must be in each
field. Possible values: 1-65535.
You can also edit the Block, Log, Stats and Learn actions in the Field Formats Settings
pane.
After making any of the above changes, click OK to save the changes and return to the Security
Checks table. You can proceed to configure other security checks if needed. Click OK ** to save
all the changes you have made in the Security Checks section, and then click **Save and
Close to close the Security Check pane.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1663

NetScaler 12.0

• To configure a Field Formats relaxation rule by using the GUI

1. Navigate to Application Firewall > Profiles, highlight the target profile, and click Edit.

2. In the Advanced Settings pane, click Relaxation Rules. The Relaxation Rules table has a
Field Formats entry. You can double click, or select this row and click the Edit button, to
access the Field Formats Relaxation Rules dialogue. You can perform Add, Edit, Delete,
Enable, or Disable operations for relaxation rules.

For a consolidated view of all the relaxation rules, you can highlight the Field Formats row
and click Visualizer. The visualizer for deployed relaxations offers you the option to Add a
new rule or Edit an existing one. You can also Enable or Disable a group of rules by selecting
a node and clicking the corresponding buttons in the relaxation visualizer.

Using the learn feature with the Field Formats Check

When the learn action is enabled, the App Firewall learning engine monitors the traffic and learns the
triggered violations. You can periodically inspect these learned rules. After due consideration, you
can deploy the learned rule as a Field Format relaxation rule.

Field formats learning enhancement—An App Firewall learning enhancement was introduced in re-
lease 11.0. In the previous releases, once the learned field format recommendation is deployed, the
App Firewall learning engine stops monitoring the valid requests for the purpose of recommending
new rules on the basis of the new data points. This limits the configured security protection, because
the learning database does not include any representations of the new data seen in the valid requests
processed by the security check.

Violations are no longer coupled with learning. The learning engine learns and makes recommenda-
tions for the field formats regardless of the violations. In addition to checking the blocked requests
to determine whether the current field format is too restrictive and needs to be relaxed, the learn-
ing engine also monitors the allowed requests to determine whether the current field format is too
permissive, and allows elevating the security by deploying a more restrictive rule.

Following is a summary of the Field Formats learning behavior:

No Field format is bound—The behavior remains unchanged in this scenario. All learn data is sent to
the aslearn engine. The learning engine suggests a field format rule based on the data set.

Field format is bound: In the previous releases, observed data is sent to the aslearn engine only in
the case of a violation. The learning engine suggests a field format rule based on the data set. In the
11.0 release, all data is sent to aslearn engine even if no violation is triggered. The learning engine
suggests a field format rule based on the entire data set of all received inputs.

Use Case for learning enhancement:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1664

NetScaler 12.0

If the initial field format learned rules are based on a small sample of data, a few non typical values
might result in a recommendation that is too lenient for the target field. The ongoing learning allows
the App Firewall to observe data points from every request to collect a representative sample for the
learned recommendations. This is helpful in further tightening the security to deploy the optimal
input format with an adequate range value.

The field format learning makes use of the priority of the Field Types as well as the configured settings
of the following learning thresholds:

• FieldFormatMinThreshold—Minimum number of times a specific form field must be observed

before a learned relaxation is generated. Default: 1.
• FieldFormatPercentThreshold—Percentage of times a form field matched a particular Field
Type, before a learned relaxation is generated. Default: 0.

The field format rule recommendations are based on the following criteria:

• Field Type recommendations—The Field Type recommendations are determined by the as-
signed priorities of the existing Field Types and the specified Field Format thresholds. The pri-
orities determine the order in which the Field Types are matched against the inputs. A lower
number specifies a higher priority. For example, Field Type integer has the higher priority (30)
and is therefore evaluated before Field Type alphanum (50). The thresholds determine the num-
ber of inputs evaluated to collect a representative sample for the data point. Assigning the right
priority to the configured Field Types, and configuring an appropriate learningsetting value
for the fieldFormatPercentThreshold and fieldFormatMinThreshold parameters, is essential
for getting the correct Field Format recommendation. The Field Type with the highest priority,
based on the configured thresholds, is matched first against the inputs. If there is a match, this
Field Type is suggested without considering the other Field Types. For example, three default
Field Types, integer, alphanum, and any will match if all the inputs contain only numbers. How-
ever, integer will be recommended since it has the highest priority.
• Minimum and Maximum length recommendations—Calculations for the minimum and max-
imum lengths for the Field Format are done independently of the determination for the Field
Type. The field format length calculations are based on the average length of all the observed
inputs. Half of this calculated average is suggested as the min value, and twice the value of this
average is suggested as the max value. The range for the Minimum Length is 0-65535 and the
range for the Maximum Length is 1-65535. The configured value for the minimum length cannot
exceed the maximum length.
• Handling of space character—The Field Format check counts every space character when
checking for the Field Formats length. Leading or trailing spaces are not stripped, and multiple
consecutive spaces in the middle of the input string are no longer consolidated to a single
space during input processing.

Example to illustrate the Field Format recommendations:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1665

NetScaler 12.0

1 Total requests: 100

2 Number of Req with Field Type:
3 Int : 22 (22 int values) ‒ 22%
4 Alpha : 44 (44 alpha values) ‒ 44%
5 Alphanum: 14 (14 + 44 + 22 = 80 alphanum values) = 80%
6 noHTML: 10 (80 + 10 = 90 noHTML values) = 90%
7 any : 10 (90 + 10 = 100 any values) = 100%
8
9 % threshold Suggested Field Type
10 0-22 int
11 23-44 alpha
12 45-80 alphanum
13 81-90 noHTML
14 91-100 any

To view or use learned data by using the command line interface

1 show appfw learningdata <profilename> FieldFormat

2 rm appfw learningdata <profilename> -fieldFormat <string> <
formActionURL>
3 export appfw learningdata <profilename> FieldFormat

To view or use learned data by using the GUI

1. Navigate to Application Firewall > Profiles, highlight the target profile, and click Edit.

2. In the Advanced Settings pane, click Learned Rules. You can select the Field Formats entry
in the Learned Rules table and double-click it to access the learned rules. You can deploy the
learned rules or edit a rule before deploying it as a relaxation rule. To discard a rule, you can se-
lect it and click the Skip button. You can edit only one rule at a time, but you can select multiple
rules to deploy or skip.

You also have the option to show a summarized view of the learned relaxations by selecting
the Field Formats entry in the Learned Rules table and clicking Visualizer to get a consolidated
view of all the learned violations. The visualizer makes it very easy to manage the learned rules.
It presents a comprehensive view of the data on one screen and facilitates taking action on a
group of rules with one click. The biggest advantage of the visualizer is that it recommends
regular expressions to consolidate multiple rules. You can select a subset of these rules, based
on the delimiter and Action URL. You can display 25, 50, or 75 rules in the visualizer, by selecting
the number from a drop-down list. The visualizer for learned rules offers the option to edit the
rules and deploy them as relaxations. Or you can skip the rules to ignore them.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1666

NetScaler 12.0

Using the log feature with the field formats check

When the log action is enabled, the Field Formats security check violations are logged in the audit log
as APPFW_FIELDFORMAT violations. The App Firewall supports both Native and CEF log formats. You
can also send the logs to a remote syslog server.
To access the log messages by using the command line
Switch to the shell and tail the ns.logs in the /var/log/ folder to access the log messages pertaining
to the Field Formats violations:
• Shell
• tail -f /var/log/ns.log | grep APPFW_FIELDFORMAT
To access the log messages by using the GUI
The NetScaler GUI includes a very useful tool (Syslog Viewer) for analyzing the log messages. You have
multiple options for accessing the Syslog Viewer:
• Navigate to the Application Firewall > Profiles, select the target profile, and click Security
Checks. Highlight the Field Formats row and click Logs. When you access the logs directly from
the Field Formats security check of the profile, it filters out the log messages and displays only
the logs pertaining to these security check violations.
• You can also access the Syslog Viewer by navigating to NetScaler > System > Auditing. In the
Audit Messages section, click the Syslog messages link to display the Syslog Viewer, which
displays all log messages, including other security check violation logs. This is useful for debug-
ging when multiple security check violations might be triggered during request processing.
• Navigate to Application Firewall > policies > Auditing. In the Audit Messages section, click the
Syslog messages link to display the Syslog Viewer, which displays all log messages, including
other security check violation logs.
The HTML based Syslog Viewer provides various filter options for selecting only the log mes-
sages that are of interest to you. To access Field Formats security check violation log messages,
filter by selecting APPFW in the dropdown options for Module. The Event Type displays a rich set
of options to further refine your selection. For example, if you select the APPFW_FIELDFORMAT
check box and click the Apply button, only log messages pertaining to the Field Formats secu-
rity check violations appear in the Syslog Viewer.
If you place the cursor in the row for a specific log message, multiple options, such as Module and
EventType, appear below the log message. You can select any of these options to highlight the corre-
sponding information in the logs.
Example of a Native format log message when the request is not blocked

1 Jun 10 22:32:26 <local0.info> 10.217.31.98 06/10/2015:22:32:26 GMT ns

0-PPE-0 :

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1667

NetScaler 12.0

2 default APPFW APPFW_FIELDFORMAT 97 0 : 10.217.253.62 562-PPE0

3 x1MV+YnNGzQFM3Bsy2wti4bhXio0001 pr_ffc http://aaron.stratum8.net/FFC/
login_post.php
4 Field format check failed for field passwd=”65568888sz-*_” <not blocked
>
5 Example of a CEF format log message when the request is blocked
6 Jun 11 00:03:51 <local0.info> 10.217.31.98
7 CEF:0|Citrix|NetScaler|NS11.0|APPFW|APPFW_FIELDFORMAT|6|src
=10.217.253.62 spt=27076
8 method=POST requet=http://aaron.stratum8.net/FFC/maxlen_post.php msg=
Field format check
9 failed for field text_area=”” cn1=108 cn2=644 cs1=pr_ffc cs2=PPE0
10 cs3=GaUROfl1Nx1jJTvja5twH5BBqI0000 cs4=ALERT cs5=2015 act=blocked

Statistics for the field formats violations

When the stats action is enabled, the corresponding counter for the Field Formats check is incre-
mented when the App Firewall takes any action for this security check. The statistics are collected
for Rate and Total count for Traffic, Violations, and Logs. The increment of the log counter can vary
depending on the configured settings. For example, if the block action is enabled, the request for a
page that contains 3 Field Format violations increments the stats counter by one, because the page is
blocked as soon as the first Field Formats violation is detected. However, if block is disabled, process-
ing the same request increments the statistics counter for violations and the logs by 3, because each
Field Formats violation generates a separate log message.
To display Field Formats statistics by using command line
At the command prompt, type:
sh appfw stats

To display stats for a specific profile, use the following command:

stat appfw profile <profile name>

To display Field Formats statistics by using GUI

1. Navigate to System > Security > Application Firewall.
2. In the right pane, access the Statistics Link.
3. Use the scroll bar to view the statistics about Field Formats violations and logs. The statistics
table provides real-time data and is updated every 7 seconds.

Deployment tip

• Enable Field format actions log, learn and stats.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1668

NetScaler 12.0

• After running a representative sample of the traffic to your application, review the learned rec-
ommendations.
• If a Field Type is recommended by most of the learned rules, configure that Field Type as the
Default Field Type. For minimum and maximum lengths, use the widest range suggested by
these rules.
• Deploy rules for other fields for which different Field Types or different minimum/maximum
lengths are better suited.
• Enable blocking and disable learning.
• Monitor stats and logs. If a significant number of violations are still being triggered, you might
want to review the log messages to confirm that the violations represent malicious requests
that should have been blocked. If valid requests are being flagged as violations, you can either
edit the configured Field Format rule to further relax it or enable learning again to get recom-
mendations based on the new data points.
Note: You can fine tune your configuration by getting new learning recommendations.

Highlights

Note the following points about the Field Format security check:
• Protection—By configuring optimal field format rules, you can protect against many attacks.
For example, if you specify that a field can only have integers, hackers will not be able to launch
SQL Injection or XSS attacks by using this field, because the inputs required to launch such at-
tacks will not meet the configured field format requirement.
• Performance—You can limit the minimum and the maximum allowed length for the inputs in
the field format rules. This can prevent a malicious user from entering excessively large input
strings in an attempt to add processing overhead to the server, or worse, cause the server to
dump core because of stack overflow. By limiting the input size, you can shorten the time re-
quired for processing legitimate requests.
• Configuring Field Formats—You must enable one of the actions (block, log, stats, learn) to en-
gage the field Format protection. You can also specify the Field format rules to identify the al-
lowed inputs in your form fields.
• Selecting Character Maps vs. Field Types—Both Character Maps and Field Types use regular
expressions. However, a Character Map provides a more specific expression by narrowing down
the list of allowed characters. For example, for an input such as [email protected], the learn-
ing engine might recommend the Field Type nohtml but the Character Map [.@-Za-z] might be
more specific, because it narrows down the allowed set of non-alpha characters. The Charac-
ter Map option allows, in addition to alpha characters, only two non-alpha characters: period
(.) and at (@).
• Ongoing Learning—The App Firewall monitors and takes into account all the incoming data
(violations as well as allowed inputs) to build a learning table for recommending rules. The rules

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1669

NetScaler 12.0

are revised and updated as new incoming data arrives. New field format rules are suggested for
a field even if it already has a bound field format rule. If the configured Field Formats are too
restrictive and are blocking the valid requests, you can deploy a more relaxed Field Format.
Similarly, if the current Field Formats are too generic, you can further refine and tighten the
security by deploying a more restrictive Field Format.
• Overwriting Rules—If a rule has already been deployed for a field/URL combination, the GUI
allows the user to update the field format. A dialog box asks for confirmation to replace the
existing rule. If you are using the command line interface, you have to explicitly unbind the
previous binding and then bind the new rule.
• Multiple match—If multiple field formats match a given field name and its action URL, the App
Firewall arbitrarily selects one of them to apply.
• Buffer boundary—If a field value extends across multiple streaming buffers, and the format for
these two parts of the field value is different, a field format corresponding to “any” is sent to the
learn database.
• Field Format vs. Field Consistency Check—Both the Field Format check and the Field Con-
sistency check are form-based protection checks. The Field Formats check provides a different
type of protection than does the Form Field Consistency check. The Form Field Consistency
check verifies that the structure of the web forms returned by users is intact, that data format
restrictions configured in the HTML are respected, and that data in hidden fields has not been
modified. It can do this without any specific knowledge about your web forms other than what
it derives from the web form itself. The Field Formats check verifies that the data in each form
field matches the specific formatting restrictions that you configured manually, or that the learn-
ing feature generated and you approved. In other words, the Form Field Consistency check en-
forces general web form security, while the Field Formats check enforces the specific rules for
the allowed inputs for your web forms.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Form field consistency check

September 18, 2018

Contributed by:
C

The Form Field Consistency check examines the web forms returned by users of your web site, and
verifies that web forms were not modified inappropriately by the client. This check applies only to

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1670

NetScaler 12.0

HTML requests that contain a web form, with or without data. It does not apply to XML requests.

The Form Field Consistency check prevents clients from making unauthorized changes to the struc-
ture of the web forms on your web site when they fill out and submit a form. It also ensures that the
data a user submits meets the HTML restrictions for length and type, and that data in hidden fields is
not modified. This prevents an attacker from tampering with a web form and using the modified form
to gain unauthorized access to web site, redirect the output of a contact form that uses an insecure
script and thereby send unsolicited bulk email, or exploit a vulnerability in your web server software
to gain control of the web server or the underlying operating system. Web forms are a weak link on
many web sites and attract a wide range of attacks.

The Form Field Consistency check verifies all of the following:

• If a field is sent to the user, the check ensures that it is returned by the user.

• The check enforces HTML field lengths and types.

Note: The Form Field Consistency check enforces HTML restrictions on data type and
length but does not otherwise validate the data in web forms. You can use the Field
Formats check to set up rules that validate data returned in specific form fields on your
web forms.

• If your web server does not send a field to the user, the check does not allow the user to add
that field and return data in it.

• If a field is a read-only or hidden field, the check verifies that the data has not changed.

• If a field is a list box or radio button field, the check verifies that the data in the response corre-
sponds to one of the values in that field.

If a web form returned by a user violates one or more of the Form Field consistency checks, and you
have not configured the App Firewall to allow that web form to violate the Form Field Consistency
checks, the request is blocked.

If you use the wizard or the GUI, in the Modify Form Field Consistency Check dialog box, on the General
tab you can enable or disable the Block, Log, Learn, and Statistics actions.

You also configure Sessionless Field Consistency in the General tab. If Sessionless Field Consistency
is enabled, the App Firewall checks only the web form structure, dispensing with those parts of the
Form Field Consistency check that depend upon maintaining session information. This can speed the
Form Field Consistency check with little security penalty for web sites that use many forms. To use
Sessionless Field Consistency on all web forms, select On. To use it only for forms submitted with the
HTTP POST method, select postOnly

If you use the command-line interface, you can enter the following command to configure the Form
Field Consistency Check:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1671

NetScaler 12.0

• set appfw profile <name> -fieldConsistencyAction [block] [learn] [log]

[stats] [none]

To specify relaxations for the Form Field Consistency check, you must use the GUI. On the Checks tab
of the Modify Form Field Consistency Check dialog box, click Add to open the Add Form Field Consis-
tency Check Relaxation dialog box, or select an existing relaxation and click Open to open the Modify
Form Field Consistency Check Relaxation dialog box. Either dialog box provides the same options for
configuring a relaxation, as described in “Manual Configuration By Using the GUI.”

Following are examples of Form Field Consistency check relaxations:

Form Field Names:

• Choose form fields with the name UserType:

1 ^UserType$

• Choose form fields with names that begin with UserType_ and are followed by a string that be-
gins with a letter or number and consists of from one to twenty-one letters, numbers, or the
apostrophe or hyphen symbol:

1 ^UserType_[0-9A-Za-z][0-9A-Za-z’-]{
2 0,20 }
3 $

• Choose form fields with names that begin with Turkish-UserType_ and are otherwise the same
as the previous expression, except that they can contain Turkish special characters throughout:

1 ^T\xC3\xBCrk\xC3\xA7e-UserType_([0-9A-Za-z]|\\x[0-9A-Fa-f][0-9A-
Fa-f])+$

Note: See “PCRE Character Encoding Format” for a complete description of supported spe-
cial characters and how to encode them properly.

• Choose form field names that begin with a letter or number, consist of a combination of letters
and/or numbers only, and that contain the string Num anywhere in the string:

1 ^[0-9A-Za-z]*Num[0-9A-Za-z]*$

Form Field Action URLs:

• Choose URLs beginning with http://www.example.com/search.pl? and containing any string

after the query except for a new query:

1 ^http://www[.]example[.]com/search[.]pl?[^?]*$

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1672

NetScaler 12.0

• Choose URLs that begin with http://www.example-español.com and have paths and filenames
that consist of upper-case and lower-case letters, numbers, non-ASCII special characters, and
selected symbols in the path. The ñ character and any other special characters are represented
as encoded UTF-8 strings containing the hexadecimal code assigned to each special character
in the UTF-8 charset:

1 ^http://www[.]example-espa\xC3\xB1ol[.]com/(([0-9A-Za-z]|\\x[0-9A-
Fa-f][0-9A-Fa-f])([0-9A-Za-z_-]|\\x[0-9A-Fa-f][0-9A-Fa-f])*/)
*([0-9A-Za-z]|\\x[0-9A-Fa-f][0-9A-Fa-f])([0-9A-Za-z_-]|\\x[0-9A
-Fa-f][0-9A-Fa-f])*[.](asp|htp|php|s?html?)$

• Choose all URLs that contain the string /search.cgi?:

1 ^[^?<>]*/search[.]cgi\?[^?<>]*$

Caution: Regular expressions are powerful. Especially if you are not thoroughly familiar with
PCRE-format regular expressions, double-check any regular expressions you write. Make sure
that they define exactly the URL you want to add as an exception, and nothing else. Careless use
of wildcards, and especially of the dot-asterisk (
.*) metacharacter/wildcard combination, can have results you do not want or expect, such as
blocking access to web content that you did not intend to block or allowing an attack that the
Cookie Consistency check would otherwise have blocked.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

CSRF form tagging check

November 19, 2018

Contributed by:
C

The Cross Site Request Forgery (CSRF) Form Tagging check tags each web form sent by a protected
web site to users with a unique and unpredictable FormID, and then examines the web forms returned
by users to ensure that the supplied FormID is correct. This check protects against cross-site request
forgery attacks. This check applies only to HTML requests that contain a web form, with or without
data. It does not apply to XML requests.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1673

NetScaler 12.0

The CSRF Form Tagging check prevents attackers from using their own web forms to send high vol-
ume form responses with data to your protected web sites. This check requires relatively little CPU
processing capacity compared to certain other security checks that analyze web forms in depth. It
is therefore able to handle high volume attacks without seriously degrading the performance of the
protected web site or the App Firewall itself.
Before you enable the CSRF Form Tagging check, you should be aware of the following:
• You need to enable form tagging. The CSRF check depends on form tagging and does not work
without it.
• You should disable the NetScaler Integrated Caching feature for all web pages containing forms
that are protected by that profile. The Integrated Caching feature and CSRF form tagging are
not compatible.
• You should consider enabling Referer checking. Referer checking is part of the Start URL check,
but it prevents cross-site request forgeries, not Start URL violations. Referer checking also puts
less load on the CPU than does the CSRF Form Tagging check. If a request violates Referer check-
ing, it is immediately blocked, so the CSRF Form Tagging check is not invoked.
• The CSRF Form Tagging check does not work with web forms that use different domains in the
form-origin URL and form-action URL. For example, CSRF Form Tagging cannot protect a web
form with a form-origin URL of http://www.example.com and a form action URL of http
://www.example.org/form.pl, because example.com and example.org are different do-
mains.
If you use the wizard or the GUI, in the Modify CSRF Form Tagging Check dialog box, on the General
tab you can enable or disable the Block, Log, Learn and Statistics actions.
If you use the command-line interface, you can enter the following command to configure the CSRF
Form Tagging Check:
• set appfw profile <name> -fieldConsistencyAction [block] [log] [learn]
[stats] [none]

To specify relaxations for the CSRF Form Tagging check, you must use the GUI. On the Checks tab of the
Modify CSRF Form Tagging Check dialog box, click Add to open the Add CSRF Form Tagging Check
Relaxation dialog box, or select an existing relaxation and click Open to open the Modify CSRF Form
Tagging Check Relaxation dialog box. Either dialog box provides the same options for configuring a
relaxation.
An alert is generated when you set the NetScaler Appfirewall session limit to a value of 0 or lower,
because such a setting affects advanced protection check functionality that requires a properly func-
tioning App Firewall session.
Following are examples of CSRF Form Tagging check relaxations:
Note: The following expressions are URL expressions that can be used in both the Form Origin URL
and Form Action URL roles.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1674

NetScaler 12.0

• Choose URLs beginning with http://www.example.com/search.pl? and containing any

string after the query, except for a new query:

1 ^http://www[.]example[.]com/search
2 [.]pl?[^?]*$

• Choose URLs that begin with http://www.example-español.com and have paths and file-
names that consist of upper-case and lower-case letters, numbers, non-ASCII special charac-
ters, and selected symbols in the path. The ñ character and any other special characters are
represented as encoded UTF-8 strings containing the hexadecimal code assigned to each spe-
cial character in the UTF-8 charset:

1 http://www[.]example-espa\xC3\xB1ol[.]com/(([0-9A-Za-z]|\\x[0-9A-Fa-f
][0-9A-Fa-f])
2 ([0-9A-Za-z_-]|\\x[0-9A-Fa-f][0-9A-Fa-f])*/)*([0-9A-Za-z]|\\x[0-9A-Fa-f
][0-9A-Fa-f])([0-9A-Za-z_-]|\\x[0-9A-Fa-f][0-9A-Fa-f])*[.](asp|htp|
php|s?html?)$

• Choose all URLs that contain the string /search.cgi?:

1 ^[^?<>]*/search[.]cgi\?[^?<>]*$

Important

Regular expressions are powerful. If you are not thoroughly familiar with PCRE-format regular
expressions, double-check any regular expressions you write. Make sure that they define exactly
the URL that you want to add as an exception, and nothing else. Careless use of wildcards, and
especially of the dot-asterisk (.*) metacharacter/wildcard combination, can have results you do
not want, such as blocking access to web content that you did not intend to block or allowing an
attack that the check would otherwise have blocked.
Tip

When enableValidate referrer header is enabled under the Start URL Action, ensure that the Re-
ferrer Header URL is added to StartURL as well.
Note

When NetScaler reaches the appfw_session_limit and CSRF checks are enabled, the web
application freezes.

To prevent web application freeze, decrease the session timeout and increase the session limit
by using the following commands:

1 > From CLI: > set appfw settings ‒ sessiontimeout 300

2 > From shell: root@ns# nsapimgr_wr.sh -s appfw_session_limit=200000

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1675

NetScaler 12.0

Logging and generating SNMP alarms when appfw_session_limit is reached assists you in trou-
bleshooting and debugging issues.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Managing CSRF form tagging check relaxations

September 18, 2018

Contributed by:
C

You configure an exception (or relaxation) to the CSRF Form Tagging security check in the Add Cross-
Site Request Forgery Tagging Check Relaxation dialog box or the Modify Cross-Site Request Forgery
Tagging Check Relaxation dialog box.

To configure a CSRF form tagging check relaxation by using the GUI

1. Navigate to Security > Application Firewall > Profiles.

2. In the Profiles pane, select the profile you want to configure, and then click Open.

3. In the Configure App Firewall Profile dialog box, click the Security Checks tab. The Security
Checks tab contains the list of App Firewall security checks.

4. To add or modify a CSRF relaxation, do one of the following:

• To add a new relaxation, click Add.

• To modify an existing relaxation, select the relaxation that you want to modify, and then
click Open.

The Add Cross-Site Request Forgery Tagging Check Relaxation or Modify Cross-Site Request
Forgery Tagging Check Relaxation dialog box is displayed. Except for the title, these dialog
boxes are identical.

5. Fill in the dialog box as described below.

• Enabled check box—Select to place this relaxation or rule in active use; clear to deactivate
it.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1676

NetScaler 12.0

• Form Origin URL—In the text area, enter a PCRE-format regular expression that defines
the URL that hosts the form.

• Form Action URL—In the text area, enter a PCRE-format regular expression that defines
the URL to which data entered into the form is delivered.

• Comments—In the text area, type a comment. Optional.

Note: For any element that requires a regular expression, you can type the regular expres-
sion, use the Regex Tokens menu to insert regular expression elements and symbols di-
rectly into the text box, or click Regex Editor to open the Add Regular Expression dialog
box, and use it to construct the expression.

6. Click OK. The Add Cross-Site Request Forgery Tagging Check Relaxation or Modify Cross-
Site Request Forgery Tagging Check Relaxation dialog box closes and you return to the Mod-
ify Cross-Site Request Forgery Tagging Check dialog box.

7. To remove a relaxation or rule, select it, and then click Remove.

8. To enable a relaxation or rule, select it, and then click Enable.

9. To disable a relaxation or rule, select it, and then click Disable.

10. To configure the settings and relationships of all existing relaxations in an integrated interactive
graphic display, click Visualizer, and use the display tools.

11. To review and configure learned rules for the CSRF check, click Learningand perform the steps
in “To configure and use the Learning feature.”

12. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

URL protection checks

September 18, 2018

Contributed by:
C

The URL Protection checks examine request URLs to prevent attackers from aggressively attempting
to access multiple URLs (forceful browsing) or using a URL to trigger a known security vulnerability in
web server software or web site scripts.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1677

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Start URL check

September 20, 2018

Contributed by:
C

The Start URL check examines the URLs in incoming requests and blocks the connection attempt if
the URL does not meet the specified criteria. To meet the criteria, the URL must match an entry in the
Start URL list, unless the Enforce URL Closure parameter is enabled. If you enable this parameter, a
user who clicks a link on your Web site is connected to the target of that link.

The primary purpose of the Start URL check is to prevent repeated attempts to access random URLs on
a Web site, (forceful browsing) through bookmarks, external links, or jumping to pages by manually
typing in the URLs to skip the pages required to reach that part of the website. Forceful browsing can
be used to trigger a buffer overflow, find content that users were not intended to access directly, or
find a back door into secure areas of your Web server. The App Firewall enforces a website’s given
traversal or logic path by allowing access to only the URL’s that are configured as start URLs.

If you use the wizard or the GUI, in the Modify Start URL Check dialog box, on the
General tab you can enable or disable Block, Log, Statistics, Learn actions, and the following parame-
ters:

• Enforce URL Closure. Allow users to access any web page on your web site by clicking a hyper-
link on any other page on your web site. Users can navigate to any page on your web site that
can be reached from the home page or any designated start page by clicking hyperlinks.
Note: The URL closure feature allows any query string to be appended to and sent with the ac-
tion URL of a web form submitted by using the HTTP GET method. If your protected web sites
use forms to access an SQL database, make sure that you have the SQL injection check enabled
and properly configured.
• Sessionless URL Closure. From the client’s point of view, this type of URL closure functions
in exactly the same way as standard, session-aware URL Closure, but uses a token embedded
in the URL instead of a cookie to track the user’s activity, which consumes considerably fewer
resources. When sessionless URL closure is enabled, the App Firewall appends a “as_url_id” tag
to all the URL’s that are in URL closure.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1678

NetScaler 12.0

Note: When enabling sessionless (Sessionless URL Closure), you must also enable regular URL
closure (Enforce URL Closure) or sessionless URL closure does not work.
• Validate Referer Header. Verify that the Referer header in a request that contains web form
data from your protected web site instead of another web site. This action verifies that your
web site, not an outside attacker, is the source of the web form. Doing so protects against cross-
site request forgeries (CSRF) without requiring form tagging, which is more CPU-intensive than
header checks. The App Firewall can handle the HTTP Referer header in one of the following
four ways, depending on which option you select in the drop-down list:
– Off—Do not validate the Referer header.
– If-Present—Validate the Referer header if a Referer header exists. If an invalid Referer
header is found, the request generates a referer-header violation. If no Referer header ex-
ists, the request does not generate a referer-header violation. This option enables the App
Firewall to perform Referer header validation on requests that contain a Referer header,
but not block requests from users whose browsers do not set the Referer header or who
use web proxies or filters that remove that header.
– Always Except Start URLs—Always validate the Referer header. If there is no Referer
header and the requested URL is not exempted by the startURL relaxation rule, the
request generates a referer-header violation. If the Referer header is present but it is
invalid, the request generates a referer-header violation.
– Always Except First Request—Always validate the referer header. If there is no referer
header, only the URL that is accessed first is allowed. All other URL’s are blocked without a
valid referer header. If the Referer header is present but it is invalid, the request generates
a referer-header violation.

One Start URL setting, Exempt Closure URLs from Security Checks, is not configured in the Modify
Start URL Check dialog box, but is configured in the Settings tab of the Profile. If enabled, this setting
directs the App Firewall not to run further form based checks (such as Cross-Site Scripting and SQL
Injection inspection) on URLs that meet the URL Closure criteria.

Note

Although the referer header check and Start URL security check share the same action settings,
it is possible to violate the referer header check without violating the Start URL check. The dif-
ference is visible in the logs, which log referer header check violations separately from Start URL
check violations.

The Referer header settings (OFF, if-Present, AlwaysExceptStartURLs, and AlwaysExceptFirstRequest)

are arranged in order of least restrictive to most restrictive and work as follows:

OFF:

• Referer Header Not checked.

If-Present:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1679

NetScaler 12.0

• Request has no referer header -> Request is allowed.

• Request has referer header and the referer URL is in URL closure -> Request is allowed.
• Request has referer header and the referer URL is not in URL closure -> Request is blocked.

AlwaysExceptStartURLs:

• Request has no referer header and the request URL is a start URL -> Request is allowed.
• Request has no referer header and the request URL is not a start URL ->Request is blocked.
• Request has referer header and the referer URL is in URL closure -> Request is allowed.
• Request has referer header and the referer URL is not in URL closure -> Request is blocked.

AlwaysExceptFirstRequest:

• Request has no referer header and is the first request URL of the session -> Request is allowed.
• Request has no referer header and is not the first request URL of the session -> Request is
blocked.
• Request has referer header and is either the first request URL of the session or is in URL closure
-> Request is allowed.
• Request has referer header and is neither the first request URL of the session nor is in URL closure
-> Request is blocked.

If you use the command-line interface, you can enter the following commands to configure the Start
URL Check:

• set appfw profile <name> -startURLAction [block] [learn] [log] [stats]

[none]
• set appfw profile <name> -startURLClosure ([ON] | [OFF])
• set appfw profile <name> -sessionlessURLClosure ([ON] | [OFF])
• set appfw profile <name> -exemptClosureURLsFromSecurityChecks ([ON] | [
OFF)
• set appfw profile <name> -RefererHeaderCheck ([OFF] | [if-present] | [
AlwaysExceptStartURLs] | [AlwaysExceptFirstRequest])

To specify relaxations for the Start URL check, you must use the GUI. On the Checks tab of the Modify
Start URL Check dialog box, click Add to open the Add Start URL Check Relaxation dialog box, or select
an existing relaxation and click Open to open the Modify Start URL Check Relaxation dialog box. Either
dialog box provides the same options for configuring a relaxation.

Following are examples of Start URL check relaxations:

• Allow users to access the home page at www.example.com:

1 ^http://www[.]example[.]com$

• Allow users to access all static HTML (.htm and .html), server-parsed HTML (.htp and .shtml),
PHP (.php), and Microsoft ASP (.asp) format web pages at www.example.com:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1680

NetScaler 12.0

1 ^http://www[.]example[.]com/([0-9A-Za-z][0-9A-Za-z_-]*/)*
2 [0-9A-Za-z][0-9A-Za-z_.-]*[.](asp|htp|php|s?html?)$

• Allow users to access web pages with pathnames or file names that contain non-ASCII characters
at www.example-español.com:

1 ^http://www[.]example-espaxC3xB1ol[.]com/(([0-9A-Za-z]|x[0-9A-Fa-f
][0-9A-Fa-f])([0-9A-Za-z_-]|x[0-9A-Fa-f][0-9A-Fa-f])*/)*
2 ([0-9A-Za-z]|x[0-9A-Fa-f][0-9A-Fa-f])([0-9A-Za-z_-]|x[0-9A-Fa-f
][0-9A-Fa-f])*[.](asp|htp|php|s?html?)$

1 **Note**: In the above expression, each character class has been

grouped with the string
2 x[0-9A-Fa-f][0-9A-Fa-f], which matches all properly-constructed
character encoding strings but does not allow stray backslash
characters that are not associated with a UTF-8 character encoding
string. The double backslash () is an escaped backslash, which tells
the App Firewall to interpret it as a literal backslash. If you
included only one backslash, the App Firewall would instead
interpret the following left square bracket ([) as a literal
character instead of the opening of a character class, which would
break the expression.

• Allow users to access all GIF (.gif), JPEG (.jpg and .jpeg), and PNG (.png) format graphics at
www.example.com:

1 ^http://www[.]example[.]com/([0-9A-Za-z][0-9A-Za-z_-]*/)*
2 [0-9A-Za-z][0-9A-Za-z_.-]*[.](gif|jpe?g|png)$

• Allow users to access CGI (.cgi) and PERL (.pl) scripts, but only in the CGI-BIN directory:

1 ^http://www[.]example[.]com/CGI-BIN/[0-9A-Za-z][0-9A-Za-z_.-]*[.](
cgi|pl)$

• Allow users to access Microsoft Office and other document files in the docsarchive directory:

1 ^http://www[.]example[.]com/docsarchive/[0-9A-Za-z][0-9A-Za-z_
-.]*[.](doc|xls|pdf|ppt)$

Note

By default, all App Firewall URLs are considered to be regular expressions.

Caution: Regular expressions are powerful. Especially if you are not thoroughly familiar with PCRE-
format regular expressions, double-check any regular expressions that you write. Make sure that they

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1681

NetScaler 12.0

define exactly the URL you want to add as an exception, and nothing else. Careless use of wildcards,
and especially of the dot-asterisk (.*) metacharacter/wildcard combination, can have results you do
not want, such as blocking access to web content that you did not intend to block or allowing an
attack that the Start URL check would otherwise have blocked.
Tip

You can add the -and- to the allowed list of SQL keywords for URL naming scheme. For exam-
ple, example https://FQDN/bread-and-butter.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Deny URL check

September 20, 2018

Contributed by:
C

The Deny URL check examines and blocks connections to URLs that are commonly accessed by hack-
ers and malicious code. This check contains a list of URLs that are common targets of hackers or
malicious code and that rarely if ever appear in legitimate requests. You can also add URLs or URL
patterns to the list. The Deny URL check prevents attacks against various security weaknesses known
to exist in web server software or on many web sites.

The Deny URL check takes priority over the Start URL check, and thus denies malicious connection
attempts even when a Start URL relaxation would normally allow a request to proceed.

In the Modify Deny URL Check dialog box, on the General tab you can enable or disable the Block, Log,
and Statistics actions.

If you use the command-line interface, you can enter the following command to configure the Deny
URL Check:

• set appfw profile <name> -denyURLAction [block] [log] [stats] [none]

To create and configure your own deny URLs, you must use the GUI. On the Checks tab of the Modify
Deny URL Check dialog box, click Add to open the Add Deny URL dialog box, or select an existing user-
defined deny URL and click Open to open the Modify Deny URLdialog box. Either dialog box provides
the same options for creating and configuring a deny URL.

Following are examples of Deny URL expressions:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1682

NetScaler 12.0

• Do not allow users to access the image server at images.example.com directly:

1 ^http://images[.]example[.]com$

• Do not allow users to access CGI (.cgi) or PERL (.pl) scripts directly:

1 ^http://www[.]example[.]com/([0-9A-Za-z][0-9A-Za-z_-]*/)*
2 [0-9A-Za-z][0-9A-Za-z_.-]*[.](cgi|pl)$

• Here is the same deny URL, modified to support non-ASCII characters:

1 ^http://www[.]example[.]com/(([0-9A-Za-z]|x[0-9A-Fa-f][0-9A-Fa-f])
2 ([0-9A-Za-z_-]|x[0-9A-Fa-f][0-9A-Fa-f])*/)*([0-9A-Za-z]|x[0-9A-Fa-f
][0-9A-Fa-f])
3 ([0-9A-Za-z_-]|x[0-9A-Fa-f][0-9A-Fa-f])*[.](cgi|pl)$

Caution:
Regular expressions are powerful. Especially if you are not thoroughly familiar with PCRE-format
regular expressions, double-check any regular expressions you write. Make sure that they define
exactly the URL or pattern that you want to block, and nothing else. Careless use of wildcards,
and especially of the dot-asterisk (
.*) metacharacter/wildcard combination, can have results that you do not want, such as blocking
access to web content that you did not intend to block.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

XML protection checks

September 18, 2018

Contributed by:
C

The XML Protection checks examine requests for XML-based attacks of all types.

Caution: The XML security checks apply only to content that is sent with an HTTP content-type
header of text/xml. If the content-type header is missing, or is set to a different value, all XML
security checks are bypassed. If you plan to protect XML or Web 2.0 web applications, the web-
masters of each web server that hosts those applications should ensure that the proper HTTP

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1683

NetScaler 12.0

content-type header is sent.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

XML format check

September 18, 2018

Contributed by:
C

The XML Format check examines the XML format of incoming requests and blocks those requests that
are not well formed or that do not meet the criteria in the XML specification for properly-formed XML
documents. Some of those criteria are:

• An XML document must contain only properly-encoded Unicode characters that match the Uni-
code specification.
• No special XML syntax characters—such as < , > and &—can be included in the document except
when used in XML markup.
• All begin, end, and empty-element tags must be correctly nested, with none missing or overlap-
ping.
• XML element tags are case-sensitive. All beginning and end tags must match exactly.
• A single root element must contain all the other elements in the XML document.

A document that does not meet the criteria for well-formed XML does not meet the definition of an
XML document. Strictly speaking, it is not XML. However, not all XML applications and web services
enforce the XML well-formed standard, and not all handle poorly-formed or invalid XML correctly. In-
appropriate handling of a poorly-formed XML document can cause security breaches. The purpose
of the XML Format check is to prevent a malicious user from using a poorly-formed XML request to
breach security on your XML application or web service.

If you use the wizard or the GUI, in the Modify XML Format Check dialog box, on the General tab you
can enable or disable the Block, Log, and Statistics actions.

If you use the command-line interface, you can enter the following command to configure the XML
Format Check:

• set appfw profile <name> -xmlFormatAction [block] [log] [stats] [none]

You cannot configure exceptions to the XML Format check. You can only enable or disable it.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1684

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

XML denial-of-service check

September 20, 2018

Contributed by:
C

The XML Denial of Service (XML DoS or XDoS) check examines incoming XML requests to determine
whether they match the characteristics of a denial-of-service (DoS) attack, and blocks those requests
that do. The purpose of the XML DoS check is to prevent an attacker from using XML requests to launch
a denial-of-service attack on your web server or web site.

If you use the wizard or the GUI, in the Modify XML Denial-of-Service Check dialog box, on the General
tab you can enable or disable the Block, Log, Statistics, and Learn actions:

If you use the command-line interface, you can enter the following command to configure the XML
Denial-of-Service check:

• set appfw profile <name> -xmlDoSAction [block] [log] [learn] [stats] [

none]

To configure individual XML Denial-of-Service rules, you must use the GUI. On the Checks tab of the
Modify XML Denial-of-Service Check dialog box, select a rule and click Open to open the Modify XML
Denial-of-Service dialog box for that rule. The individual dialog boxes differ for the different rules but
are extremely simple. Some only allow you to enable or disable the rule; others allow you to modify
a number by typing a new value in a text box.

The individual XML denial-of-service rules are:

• Maximum Element Depth

Restrict the maximum number of nested levels in each individual element to 256. If this rule
is enabled, and the App Firewall detects an XML request with an element that has more than
the maximum number of allowed levels, it blocks the request. You can modify the maximum
number of levels to any value from one (1) to 65,535.

• Maximum Element Name Length

Restrict the maximum length of each element name to 128 characters. This includes the name

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1685

NetScaler 12.0

within the expanded namespace, which includes the XML path and element name in the follow-
ing format:

1 {
2 http://prefix.example.com/path/ }
3 target_page.xml

1 The user can modify the maximum name length to any value between one
(1) character and 65,535.

• Maximum # Elements

Restrict the maximum number of any one type of element per XML document to 65,535. You
can modify the maximum number of elements to any value between one (1) and 65,535.

• Maximum # Element Children

Restrict the maximum number of children (including other elements, character information,
and comments) each individual element is allowed to have to 65,535. You can modify the maxi-
mum number of element children to any value between one (1) and 65,535.

• Maximum # Attributes

Restrict the maximum number of attributes each individual element is allowed to have to 256.
You can modify the maximum number of attributes to any value between one (1) and 256.

• Maximum Attribute Name Length

Restrict the maximum length of each attribute name to 128 characters. You can modify the max-
imum attribute name length to any value between one (1) and 2,048.

• Maximum Attribute Value Length

Restrict the maximum length of each attribute value to 2048 characters. You can modify the
maximum attribute name length to any value between one (1) and 2,048.

• Maximum Character Data Length

Restrict the maximum character data length for each element to 65,535. You can modify the
length to any value between one (1) and 65,535.

• Maximum File Size

Restrict the size of each file to 20 MB. You can modify the maximum file size to any value.

• Minimum File Size

Require that each file be at least 9 bytes in length. You can modify the minimum file size to any
positive integer representing a number of bytes.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1686

NetScaler 12.0

• Maximum # Entity Expansions

Limit the number of entity expansions allowed to the specified number. Default: 1024.

• Maximum Entity Expansion Depth

Restrict the maximum number of nested entity expansions to no more than the specified num-
ber. Default: 32.

• Maximum # Namespaces

Limit the number of namespace declarations in an XML document to no more than the specified
number. Default: 16.

• Maximum Namespace URI Length

Limit the URL length of each namespace declaration to no more than the specified number of
characters. Default: 256.

• Block Processing Instructions

Block any special processing instructions included in the request. This rule has no user-
modifiable values.

• Block DTD

Block any document type definitions (DTD) included with the request. This rule has no user-
modifiable values.

• Block External Entities

Block all references to external entities in the request. This rule has no user-modifiable values.

• SOAP Array Check

Enable or disable the following SOAP array checks:

– Maximum SOAP Array Size. The maximum total size of all SOAP arrays in an XML request
before the connection is blocked. You can modify this value. Default: 20000000.
– Maximum SOAP Array Rank. The maximum rank or dimensions of any single SOAP array
in an XML request before the connection is blocked. You can modify this value. Default:
16.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1687

NetScaler 12.0

XML cross-site scripting check

September 20, 2018

Contributed by:
C

The XML Cross-Site Scripting check examines the user requests for possible cross-site scripting attacks
in the XML payload. If it finds a possible cross-site scripting attack, it blocks the request.

To prevent misuse of the scripts on your protected web services to breach security on your web ser-
vices, the XML Cross-Site Scripting check blocks scripts that violate the same origin rule, which states
that scripts should not access or modify content on any server but the server on which they are lo-
cated. Any script that violates the same origin rule is called a cross-site script, and the practice of
using scripts to access or modify content on another server is called cross-site scripting. The reason
cross-site scripting is a security issue is that a web server that allows cross-site scripting can be at-
tacked with a script that is not on that web server, but on a different web server, such as one owned
and controlled by the attacker.

The App Firewall offers various action options for implementing XML Cross-Site Scripting protection.
You have the option to configure Block, Log, and Stats actions.

The App Firewall XML XSS check is performed on the payload of the incoming requests and attack
strings are identified even if they are spread over multiple lines. The check looks for XSS attack strings
in the element and the attribute values. You can apply relaxations to bypass security check inspec-
tion under specified conditions. The logs and statistics can help you identify needed relaxations.

The CDATA section of the XML payload might be an attractive area of focus for the hackers because the
scripts are not executable outside the CDATA section. A CDATA section is used for content that is to be
treated entirely as character data. HTML mark up tag delimiters “<”, “>”, and “/>” will not cause the
parser to interpret the code as HTML elements. The following example shows a CDATA Section with
XSS attack string:

1 <![CDATA[rn
2 <script language=”Javascript” type=”text/javascript”>alert (”Got
you”)</script>rn
3 ]]>

Action Options

An action is applied when the XML Cross-Site Scripting check detects an XSS attack in the request. The
following options are available for optimizing XML Cross-Site Scripting protection for your application:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1688

NetScaler 12.0

• Block—Block action is triggered if the XSS tags are detected in the request.
• Log—Generate log messages indicating the actions taken by the XML Cross-Site Scripting
check. If block is disabled, a separate log message is generated for each location (ELEMENT,
ATTRIBUTE) in which the XSS violation is detected. However, only one message is generated
when the request is blocked. You can monitor the logs to determine whether responses to
legitimate requests are getting blocked. A large increase in the number of log messages can
indicate attempts to launch an attack.
• Stats—Gather statistics about violations and logs. An unexpected surge in the stats counter
might indicate that your application is under attack. If legitimate requests are getting blocked,
you might have to revisit the configuration to see if you need to configure new relaxation rules
or modify the existing ones.

Relaxation Rules

If your application requires you to bypass the Cross-Site Scripting check for a specific ELEMENT or AT-
TRIBUTE in the XML payload, you can configure a relaxation rule. The XML Cross-Site Scripting check
relaxation rules have the following parameters:

• Name—You can use literal strings or regular expressions to configure the name of the ELEMENT
or the Attribute. The following expression exempts all ELEMENTS beginning with the string
name_ followed by a string of uppercase or lowercase letters, or numbers, that is at least two
and no more than fifteen characters long:

^name_[0-9A-Za-z]{ 2,15 } $

Note

The names are case sensitive. Duplicate entries are not allowed, but you can use capitalization of
the names and differences in location to create similar entries. For example, each of the following
relaxation rules is unique:

1) XMLXSS: ABC IsRegex: NOTREGEX

Location: ATTRIBUTE State: ENABLED

2) XMLXSS: ABC IsRegex: NOTREGEX

Location: ELEMENT State: ENABLED

3) XMLXSS: abc IsRegex: NOTREGEX

Location: ELEMENT State: ENABLED

4) XMLXSS: abc IsRegex: NOTREGEX

Location: ATTRIBUTE State: ENABLED

• Location—You can specify the Location of the Cross-site Scripting Check exception in your XML
payload. The option ELEMENT is selected by default. You can change it to ATTRIBUTE.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1689

NetScaler 12.0

• Comment—This is an optional field. You can use up to a 255 character string to describe the
purpose of this relaxation Rule.

Warning

Regular expressions are powerful. Especially if you are not thoroughly familiar with PCRE-format
regular expressions, double-check any regular expressions you write. Make sure that they define
exactly the name that you want to add as an exception, and nothing else. Careless use of Regular
Expressions can have results that you do not want, such as blocking access to web content that
you did not intend to block or allowing an attack that the XML Cross-Site Scripting check would
otherwise have blocked.

Using the command line to configure the XML cross-site scripting check

To configure XML Cross-Site Scripting check actions and other parameters by using the command line

If you use the command-line interface, you can enter the following commands to configure the XML
Cross-Site Scripting Check:

> set appfw profile <name> -XMLXSSAction (([block] [log] [stats])| [none])

To configure a XML Cross-Site Scripting check relaxation rule by using the command line

You can add relaxation rules to bypass inspection of XSS script attack inspection in a specific location.
Use the bind or unbind command to add or delete the relaxation rule binding, as follows:

> bind appfw profile <name> -XMLXSS <string> [isRegex (REGEX | NOTREGEX)]
[-location ( ELEMENT | ATTRIBUTE )] ‒comment <string> [-state ( ENABLED |
DISABLED )]

> unbind appfw profile <name> -XMLXSS <String>

Example:

> bind appfw profile test_pr -XMLXSS ABC

After executing the above command, the following relaxation rule is configured. The rule is enabled,
the name is treated as a literal (NOTREGEX), and ELEMENT is selected as the default location:

1 1)      XMLXSS:  ABC             IsRegex:  NOTREGEX

2
3         Location:  ELEMENT       State:  ENABLED
4
5 ‘> unbind appfw profile test_pr -XMLXSS abc‘
6
7 ERROR: No such XMLXSS check
8
9 ‘> unbind appfw profile test_pr -XMLXSS ABC‘

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1690

NetScaler 12.0

10
11  Done

Using the GUI to configure the XML cross-site scripting check

In the GUI, you can configure the XML Cross-Site scripting check in the pane for the profile associated
with your application.

To configure or modify the XML Cross-Site Scripting check by using the GUI

1. Navigate to App Firewall > Profiles, highlight the target profile, and click Edit.
2. In the Advanced Settings pane, click Security Checks.

The security check table displays the currently configured action settings for all the security checks.
You have 2 options for configuration:

a) If you just want to enable or disable Block, Log, and Stats actions for the XML Cross-Site Scripting
check, you can select or clear check boxes in the table, click OK, and then click Save and Close to close
the Security Check pane.

b) You can double click XML Cross-Site Scripting, or select the row and click Action Settings, to dis-
play the action options. After changing any of the action settings, click OK to save the changes and
return to the Security Checks table.

You can proceed to configure other security checks if needed. Click OK to save all the changes you
have made in the Security Checks section, and then click Save and Close to close the Security Check
pane.

To configure a XML Cross-Site Scripting relaxation rule by using the GUI

1. Navigate to App Firewall > Profiles, highlight the target profile, and click Edit.
2. In the Advanced Settings pane, click Relaxation Rules.
3. In the Relaxation Rules table, double-click the XML Cross-Site Scripting entry, or select it and
click Edit.
4. In the XML Cross-Site Scripting Relaxation Rules dialogue box, perform Add, Edit, Delete,
Enable, or Disable operations for relaxation rules.

To manage XML Cross-Site Scripting relaxation rules by using the visualizer

For a consolidated view of all the relaxation rules, you can highlight the XML Cross-Site Scripting row
in the Relaxation Rules table, and click Visualizer. The visualizer for deployed relaxations offers you
the option to Add a new rule or Edit an existing one. You can also Enable or Disable a group of rules
by selecting a node and clicking the corresponding buttons in the relaxation visualizer.

To view or customize the Cross-Site Scripting patterns by using the GUI

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1691

NetScaler 12.0

You can use the GUI to view or customize the default list of XSS allowed attributes or allowed tags. You
can also view or customize the default list of XSS denied Patterns.

The default lists are specified in App Firewall > Signatures > Default Signatures. If you do not bind
any signature object to your profile, the default XSS Allowed and Denied list specified in the Default
Signatures object will be used by the profile for the Cross-Site Scripting security check processing. The
Tags, Attributes, and Patterns, specified in the default signatures object, are read-only. You cannot
edit or modify them. If you want to modify or change these, make a copy of the Default Signatures
object to create a User-Defined signature object. Make changes in the Allowed or Denied lists in the
new user-defined signature object and use this signature object in the profile that is processing the
traffic for which you want to use these customized allowed and denied lists.

For more information about signatures, see Signatures.

To view default XSS patterns:

1. Navigate to App Firewall > Signatures, select *Default Signatures, and click Edit. Then click
Manage SQL/XSS Patterns.

The Manage SQL/XSS Paths table shows following three rows pertaining to XSS :

1            xss/allowed/attribute
2
3            xss/allowed/tag
4
5            xss/denied/pattern

Select a row and click Manage Elements to display the corresponding XSS Elements (Tag, Attribute,
Pattern) used by the App Firewall Cross-Site Scripting check.

To customize XSS Elements: You can edit the user-defined signature object to customize the allowed
Tag, allowed Attributes and denied Patterns. You can add new entries or remove the existing ones.

1. Navigate to App Firewall > Signatures, highlight the target user-defined signature, and click
Edit. Click Manage SQL/XSS Patterns to display the Manage SQL/XSS paths table.
2. Select the target XSS row.

a) Click Manage Elements, to Add, Edit or Remove the corresponding XSS element.

b) Click Remove to remove the selected row.

Warning

Be very careful when you remove or modify any default XSS element, or delete the XSS path
to remove the entire row. The signatures, HTML Cross-Site Scripting security check, and XML
Cross-Site Scripting security check rely on these Elements for detecting attacks to protect your
applications. Customizing the XSS Elements can make your application vulnerable to Cross-Site

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1692

NetScaler 12.0

Scripting attacks if the required pattern is removed during editing.

Using the log feature with the XML cross-site scripting check

When the log action is enabled, the XML Cross-Site Scripting security check violations are logged in the
audit log as APPFW_XML_XSS violations. The App Firewall supports both Native and CEF log formats.
You can also send the logs to a remote syslog server.

To access the log messages by using the command line

Switch to the shell and tail the ns.logs in the /var/log/ folder to access the log messages pertaining to
the XML Cross-Site Scripting violations:

1 > Shell
2
3 > **tail -f /var/log/ns.log | grep APPFW_XML_XSS**

Example of a XML Cross-Site Scripting security check violation log message in Native log format
showing <blocked> action

1 Oct  7 01:44:34 <local0.warn> 10.217.31.98 10/07/2015:01:44:34 GMT ns

0-PPE-1 : default APPFW APPFW_XML_XSS 1154 0 :  10.217.253.69 3466-
PPE1 - owa_profile http://10.217.31.101/FFC/login.html Cross-site
script check failed for field script=”Bad tag: script” <blocked>

Example of a XML Cross-Site Scripting security check violation log message in CEF log format showing
<not blocked> action

1 Oct  7 01:46:52 <local0.warn> 10.217.31.98 CEF:0|Citrix|NetScaler|NS11

.0|APPFW|APPFW_XML_XSS|4|src=10.217.30.17 geolocation=Unknown spt
=33141 method=GET request=http://10.217.31.101/FFC/login.html msg=
Cross-site script check failed for field script=”Bad tag: script”
cn1=1607 cn2=3538 cs1=owa_profile cs2=PPE0 cs4=ERROR cs5=2015 act=**
not blocked**

To access the log messages by using the GUI

The NetScaler GUI includes a useful tool (Syslog Viewer) for analyzing the log messages. You have
multiple options for accessing the Syslog Viewer:

• Navigate to the App Firewall > Profiles, select the target profile, and click Security Checks.
Highlight the XML Cross-Site Scripting row and click Logs. When you access the logs directly
from the XML Cross-Site Scripting check of the profile, the GUI filters out the log messages and
displays only the logs pertaining to these security check violations.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1693

NetScaler 12.0

• You can also access the Syslog Viewer by navigating to NetScaler > System > Auditing. In the
Audit Messages section, click the Syslog messages link to display the Syslog Viewer, which dis-
plays all log messages, including other security check violation logs. This is useful for debugging
when multiple security check violations might be triggered during request processing.

• Navigate to App Firewall > policies > Auditing. In the Audit Messages section, click the Syslog
messages link to display the Syslog Viewer, which displays all log messages, including other
security check violation logs.

The XML based Syslog Viewer provides various filter options for selecting only the log messages that
are of interest to you. To select log messages for the XML Cross-Site Scripting check, filter by select-
ing APPFW in the dropdown options for Module. The Event Type list offers a rich set of options to
further refine your selection. For example, if you select the APPFW_XML_XSS check box and click the
Apply button, only log messages pertaining to the XML Cross-Site Scripting security check violations
appear in the Syslog Viewer.

If you place the cursor in the row for a specific log message, multiple options, such as Module, Event
Type, Event ID, Client IP etc. appear below the log message. You can select any of these options to
highlight the corresponding information in the log message.

Statistics for the XML cross-site scripting violations

When the stats action is enabled, the counter for the XML Cross-Site Scripting check is incremented
when the App Firewall takes any action for this security check. The statistics are collected for Rate
and Total count for Traffic, Violations, and Logs. The size of an increment of the log counter can vary
depending on the configured settings. For example, if the block action is enabled, a request for a page
that contains three XML Cross-Site Scripting violations increments the stats counter by one, because
the page is blocked as soon as the first violation is detected. However, if block is disabled, processing
the same request increments the statistics counter for violations and the logs by three, because each
violation generates a separate log message.

To display XML Cross-Site Scripting check statistics by using the command line

At the command prompt, type:

> **sh appfw stats**

To display stats for a specific profile, use the following command:

> **stat appfw profile** <profile name>

To display XML Cross-Site Scripting statistics by using the GUI

1. Navigate to System > Security > App Firewall.

2. In the right pane, access the Statistics Link.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1694

NetScaler 12.0

3. Use the scroll bar to view the statistics about XML Cross-Site Scripting violations and logs. The
statistics table provides real-time data and is updated every 7 seconds.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

XML SQL injection check

September 18, 2018

Contributed by:
C

The XML SQL injection check examines the user requests for possible XML SQL Injection attacks. If it
finds injected SQL in XML payloads, it blocks the requests.

A XML SQL attack can inject source code into a web application such that it can be interpreted and
executed as a valid SQL query to perform a database operation with malicious intent. For example,
XML SQL attacks can be launched to gain unauthorized access to the contents of a database or to
manipulate the stored data. XML SQL Injection attacks are not only common, but can also be very
harmful and costly.

Compartmentalizing the privileges of the database users can assist in protecting the database to some
extent. All database users should be given only the required privileges to complete their intended
tasks, so that they cannot execute SQL queries to perform other tasks. For example, a read-only user
should not be allowed to write or manipulate data tables. The App Firewall XML SQL Injection check
inspects all XML requests to provide special defenses against injection of unauthorized SQL code that
might break security. If the App Firewall detects unauthorized SQL code in any XML request of any
user, it can block the request.

The NetScaler App App Firewall inspects the presence of SQL keywords and special characters to iden-
tify the XML SQL Injection attack. A default set of keywords and special characters provides known
keywords and special characters that are commonly used to launch XML SQL attacks. The App Fire-
wall considers three characters, single straight quote (‘), backslash (), and semicolon (;) as special
characters for SQL security check processing. You can add new patterns, and you can edit the default
set to customize the XML SQL check inspection.

The App Firewall offers various action options for implementing XML SQL Injection protection. You
can Block the request, Log a message in the ns.log file with details regarding the observed violations,
and collect Stats to keep track of the number of observed attacks.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1695

NetScaler 12.0

In addition to actions, there are several parameters that can be configured for XML SQL injection
processing. You can check for SQL wildcard characters. You can change the XML SQL Injection
type and select one of the 4 options (SQLKeyword, SQLSplChar, SQLSplCharANDKeyword, SQL-
SplCharORKeyword) to indicate how to evaluate the SQL keywords and SQL special characters when
processing the XML payload. The XML SQL Comments Handling parameter gives you an option to
specify the type of comments that need to be inspected or exempted during XML SQL Injection detec-
tion.

You can deploy relaxations to avoid false positives. The App Firewall XML SQL check is performed on
the payload of the incoming requests, and attack strings are identified even if they are spread over
multiple lines. The check looks for SQL Injection strings in the element and the attribute values. You
can apply relaxations to bypass security check inspection under specified conditions. The logs and
statistics can help you identify needed relaxations.

Action options

An action is applied when the XML SQL Injection check detects an SQL Injection attack string in the
request. The following actions are available for configuring an optimized XML SQL Injection protection
for your application:

Block—If you enable block, the block action is triggered only if the input matches the XML SQL in-
jection type specification. For example, if SQLSplCharANDKeyword is configured as the XML SQL
injection type, a request is not blocked if it does not contain any key words, even if SQL special char-
acters are detected in the payload. Such a request is blocked if the XML SQL injection type is set to
either SQLSplChar, or SQLSplCharORKeyword.

Log—If you enable the log feature, the XML SQL Injection check generates log messages indicating
the actions that it takes. If block is disabled, a separate log message is generated for each location
(ELEMENT, ATTRIBUTE) in which the XML SQL violation was detected. However, only one message is
generated when the request is blocked. You can monitor the logs to determine whether responses to
legitimate requests are getting blocked. A large increase in the number of log messages can indicate
attempts to launch an attack.

Stats—If enabled, the stats feature gathers statistics about violations and logs. An unexpected surge in
the stats counter might indicate that your application is under attack. If legitimate requests are getting
blocked, you might have to revisit the configuration to see if you need to configure new relaxation rules
or modify the existing ones.

XML SQL parameters

In addition to the block, log and stats actions, you can configure the following parameters for XML SQL
Injection check:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1696

NetScaler 12.0

Check for XML SQL wildcard Characters—Wild card characters can be used to broaden the selections
of a structured query language (SQL-SELECT) statement. These wild card operators can be used in
conjunction with LIKE and NOT LIKE operators to compare a value to similar values. The percent (%),
and underscore (_) characters are frequently used as wild cards. The percent sign is analogous to the
asterisk (*) wildcard character used with MS-DOS and to match zero, one, or multiple characters in a
field. The underscore is similar to the MS-DOS question mark (?) wildcard character. It matches a
single number or character in an expression.

For example, you can use the following query to do a string search to find all customers whose names
contain the D character.

SELECT * from customer WHERE name like ”%D%”

The following example combines the operators to find any salary values that have 0 as the second and
third character.

SELECT * from customer WHERE salary like ’_00%

Different DBMS vendors have extended the wildcard characters by adding extra operators. The
NetScaler App App Firewall can protect against attacks that are launched by injecting these wildcard
characters. The 5 default Wildcard characters are percent (%), underscore (_), caret (ˆ), opening
square bracket ([), and closing square bracket (]). This protection applies to both HTML and XML
profiles.

The default wildcard chars are a list of literals specified in the *Default Signatures:

1 - <wildchar type= ” LITERAL ” >%<wildchar>

2 - <wildchar type= ” LITERAL ” >_<wildchar>
3 - <wildchar type= ” LITERAL ” >^<wildchar>
4 - <wildchar type= ” LITERAL ” >[<wildchar>
5 - <wildchar type= ” LITERAL ” >]<wildchar>

Wildcard characters in an attack can be PCRE, like [ˆA-F]. The App Firewall also supports PCRE wild-
cards, but the literal wildcard chars above are sufficient to block most attacks.
Note

The XML SQL wildcard character check is different from the XML SQL special character check.
This option must be used with caution to avoid false positives.

Check Request Containing SQL Injection Type—The App Firewall provides 4 options to implement
the desired level of strictness for SQL Injection inspection, based on the individual need of the applica-
tion. The request is checked against the injection type specification for detecting SQL violations. The
4 SQL injection type options are:

• SQL Special Character and Keyword—Both an SQL keyword and an SQL special character must
be present in the inspected location to trigger SQL violation. This least restrictive setting is also

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1697

NetScaler 12.0

the default setting.

• SQL Special Character—At least one of the special characters must be present in the processed
payload string to trigger SQL violation.
• SQL keyword—At least one of the specified SQL keywords must be present in the processed
payload string to trigger an SQL violation. Do not select this option without due consideration.
To avoid false positives, make sure that none of the keywords are expected in the inputs.
• SQL Special Character or Keyword—Either the keyword or the special character string must
be present in the payload to trigger the security check violation.

Tip

If you select the SQL Special Character option, the App Firewall skips strings that do not contain
any special characters. Since most SQL servers do not process SQL commands that are not pre-
ceded by a special character, enabling this option can significantly reduce the load on the App
Firewall and speed up processing without placing your protected web sites at risk.

SQL comments handling—By default, the App Firewall parses and checks all comments in XML data
for injected SQL commands. Many SQL servers ignore anything in a comment, even if preceded by
an SQL special character. For faster processing, if your XML SQL server ignores comments, you can
configure the App Firewall to skip comments when examining requests for injected SQL. The XML SQL
comments handling options are:

• ANSI—Skip ANSI-format SQL comments, which are normally used by UNIX-based SQL
databases.
• Nested—Skip nested SQL comments, which are normally used by Microsoft SQL Server.
• ANSI/Nested—Skip comments that adhere to both the ANSI and nested SQL comment stan-
dards. Comments that match only the ANSI standard, or only the nested standard, are still
checked for injected SQL.
• Check all Comments—Check the entire request for injected SQL, without skipping anything.
This is the default setting.

Tip

In most cases, you should not choose the Nested or the ANSI/Nested option unless your back-
end database runs on Microsoft SQL Server. Most other types of SQL server software do not rec-
ognize nested comments. If nested comments appear in a request directed to another type of
SQL server, they might indicate an attempt to breach security on that server.

Relaxation rules

If your application requires you to bypass the XML SQL Injection inspection for a specific ELEMENT or
ATTRIBUTE in the XML payload, you can configure a relaxation rule. The XML SQL Injection inspection
relaxation rules have the following parameters:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1698

NetScaler 12.0

• Name: You can use literal strings or regular expressions to configure the name of the ELEMENT
or the ATTRIBUTE. The following expression exempts all ELEMENTS beginning with the string
PurchaseOrder_ followed by a string of numbers that is at least two and no more than ten char-
acters long:

Comment: “Exempt XML SQL Check for Purchase Order Elements”

1     XMLSQLInjection:  ”PurchaseOrder_[0-9A-Za-z]{

2 2,10 }
3 ”
4
5     IsRegex:  REGEX          Location:  ELEMENT
6
7     State:  ENABLED

Note: The names are case sensitive. Duplicate entries are not allowed, but you can use capitalization
of the names and differences in location to create similar entries. For example, each of the following
relaxation rules is unique:

1 1)      XMLSQLInjection:  XYZ    IsRegex:  NOTREGEX

2
3         Location:  ELEMENT       State:  ENABLED
4
5 2)      XMLSQLInjection:  xyz    IsRegex:  NOTREGEX
6
7         Location:  ELEMENT       State:  ENABLED
8
9 3)      XMLSQLInjection:  xyz    IsRegex:  NOTREGEX
10
11         Location:  ATTRIBUTE     State:  ENABLED
12
13 4)      XMLSQLInjection:  XYZ    IsRegex:  NOTREGEX
14
15         Location:  ATTRIBUTE     State:  ENABLED

• Location: You can specify the Location of the XML SQL Inspection exception in your XML pay-
load. The option ELEMENT is selected by default. You can change it to ATTRIBUTE.
• Comment: This is an optional field. You can use up to a 255 character string to describe the
purpose of this relaxation Rule.

Warning

Regular expressions are powerful. Especially if you are not thoroughly familiar with PCRE-format
regular expressions, double-check any regular expressions you write. Make sure that they define

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1699

NetScaler 12.0

exactly the name that you want to add as an exception, and nothing else. Careless use of Regular
Expressions can have results that you do not want, such as blocking access to web content that
you did not intend to block or allowing an attack that the XML SQL Injection inspection would
otherwise have blocked.

Using the command line to configure the XML SQL Injection Check

To configure XML SQL Injection actions and other parameters by using the command line:

In the command line interface, you can use either the set appfw profile command or the add appfw
profile command to configure the XML SQL Injection protections. You can enable the block, log, and
stats action(s). Select the type of SQL attack pattern (key words, wildcard characters, special strings)
you want to detect in the payloads. Use the unset appfw profile command to revert the configured
settings back to their defaults. Each of the following commands sets only one parameter, but you can
include multiple parameters in a single command:

• set appfw profile <name> **-XMLSQLInjectionAction** (([block] [log] [

stats])| [none])
• set appfw profile <name> -XMLSQLInjectionCheckSQLWildChars (ON |OFF)
• set appfw profile <name> -XMLSQLInjectionType ([SQLKeyword] | [SQLSplChar
] |  [SQLSplCharANDKeyword] | [SQLSplCharORKeyword])
• set appfw profile <name> -XMLSQLInjectionParseComments ([checkall] | [
ansi|nested] | [ansinested])

To configure a SQL Injection relaxation rule by using the command line

Use the bind or unbind command to add or delete relaxation rules, as follows:

1 - bind appfw profile <name> -XMLSQLInjection <string> [isRegex (REGEX

| NOTREGEX)] [-location ( ELEMENT | ATTRIBUTE )] ‒ comment <string>
[-state ( ENABLED | DISABLED )]
2 - unbind appfw profile <name> -XMLSQLInjection <String>

Example:

1 > bind appfw profile test_profile -XMLSQLInjection ”PurchaseOrder_[0-9A

-Za-z]{
2 2,15 }
3 ” -isregex REGEX -location ATTRIBUTE
4
5 > unbind appfw profile test_profile ‒ XMLSQLInjection ”PurchaseOrder_
[0-9A-Za-z]{
6 2,15 }
7 ” -location ATTRIBUTE

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1700

NetScaler 12.0

Using the GUI to configure the XMLSQL injection security check

In the GUI, you can configure the XML SQL Injection security check in the pane for the profile associated
with your application.

To configure or modify the XML SQL Injection check by using the GUI

1. Navigate to App Firewall > Profiles, highlight the target profile, and click Edit.
2. In the Advanced Settings pane, click Security Checks.

The security check table displays the currently configured action settings for all the security checks.
You have 2 options for configuration:

a. If you just want to enable or disable Block, Log, and Stats actions for XML SQL Injection, you can
select or clear check boxes in the table, click OK, and then click Save and Close to close the Security
Check pane.

b. If you want to configure additional options for this security check, double click XML SQL Injection,
or select the row and click Action Settings, to display the following options:

Check for SQL Wildcard Characters—Consider SQL Wildcard characters in the payload to be attack
patterns.

Check Request Containing—Type of SQL injection (SQLKeyword, SQLSplChar, SQLSplCharANDKey-

word, or SQLSplCharORKeyword) to check.

SQL Comments Handling—Type of comments (Check All Comments, ANSI, Nested, or ANSI/Nested) to
check.

After changing any of the above settings, click OK to save the changes and return to the Security
Checks table. You can proceed to configure other security checks if needed. Click OK to save all the
changes you have made in the Security Checks section, and then click Save and Close to close the
Security Check pane.

To configure a XML SQL Injection relaxation rule by using the GUI

1. Navigate to App Firewall > Profiles, highlight the target profile, and click Edit.
2. In the Advanced Settings pane, click Relaxation Rules.
3. In the Relaxation Rules table, double-click the XML SQL Injection entry, or select it and click
Edit.
4. In the XML SQL Injection Relaxation Rules dialogue box, perform Add, Edit, Delete, Enable,
or Disable operations for relaxation rules.

To manage XML SQL Injection relaxation rules by using the visualizer

For a consolidated view of all the relaxation rules, you can highlight the XML SQL Injection row in
the Relaxation Rules table, and click Visualizer. The visualizer for deployed relaxations offers you the

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1701

NetScaler 12.0

option to Add a new rule or Edit an existing one. You can also Enable or Disable a group of rules by
selecting a node and clicking the corresponding buttons in the relaxation visualizer.

To view or customize the SQL Injection patterns by using the GUI:

You can use the GUI to view or customize the SQL patterns.

The default SQL patterns are specified in App Firewall > Signatures > *Default Signatures. If you
do not bind any signature object to your profile, the default SQL patterns specified in the Default Sig-
natures object will be used by the profile for XML SQL Injection security check processing. The rules
and patterns in the Default Signatures object are read-only. You cannot edit or modify them. If you
want to modify or change these patterns, create a user-defined signature object by making a copy of
the Default Signatures object and changing the SQL patterns. Use the user-defined signature object
in the profile that processes the traffic for which you want to use these customized SQL patterns.

For more information, see Signatures.

To view default SQL patterns:

a. Navigate to App Firewall > Signatures, select *Default Signatures, and click Edit. Then click
Manage SQL/XSS Patterns.

The Manage SQL/XSS Paths table shows following four rows pertaining to SQL Injection:

1 Injection (not_alphanum, SQL)/ Keyword

2
3 Injection (not_alphanum, SQL)/ specialstring
4
5 Injection (not_alphanum, SQL)/ transformrules/transform
6
7 Injection (not_alphanum, SQL)/ wildchar

b. Select a row and click Manage Elements to display the corresponding SQL patterns (keywords,
special strings, transformation rules or the wildcard characters) used by the App Firewall SQL injection
check.

To customize SQL Patterns: You can edit a user-defined signature object to customize the SQL key
words, special strings, and wildcard characters. You can add new entries or remove the existing ones.
You can modify the transformation rules for the SQL special strings.

a. Navigate to App Firewall > Signatures, highlight the target user-defined signature, and click Edit.
Click Manage SQL/XSS Patterns to display the Manage SQL/XSS paths table.

b. Select the target SQL row.

i. Click Manage Elements, to Add, Edit or Remove the corresponding SQL element.

ii. Click Remove to remove the selected row.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1702

NetScaler 12.0

Warning

You must be very careful when removing or modifying any default SQL element, or deleting the
SQL path to remove the entire row. The signature rules as well as the XML SQL Injection security
check rely on these elements for detecting SQL Injection attacks to protect your applications.
Customizing the SQL patterns can make your application vulnerable to XML SQL attacks if the
required pattern is removed during editing.

Using the log feature with the XML SQL injection check

When the log action is enabled, the XML SQL Injection security check violations are logged in the audit
log as APPFW_XML_SQL violations. The App Firewall supports both Native and CEF log formats. You
can also send the logs to a remote syslog server.

To access the log messages by using the command line:

Switch to the shell and tail the ns.logs in the /var/log/ folder to access the log messages pertaining to
the XML Cross-Site Scripting violations:

1 > Shell
2
3 > tail -f /var/log/ns.log | grep APPFW_XML_SQL

To access the log messages by using the GUI

The NetScaler GUI includes a useful tool (Syslog Viewer) for analyzing the log messages. You have
multiple options for accessing the Syslog Viewer:

• Navigate to App Firewall > Profiles, select the target profile, and click Security Checks. High-
light the XML SQL Injection row and click Logs. When you access the logs directly from the
XML SQL Injection check of the profile, the GUI filters out the log messages and displays only
the logs pertaining to these security check violations.

• You can also access the Syslog Viewer by navigating to System > Auditing. In the Audit Mes-
sages section, click the Syslog messages link to display the Syslog Viewer, which displays all
log messages, including other security check violation logs. This is useful for debugging when
multiple security check violations might be triggered during request processing.

• Navigate to App Firewall > Policies > Auditing. In the Audit Messages section, click the Syslog
messages link to display the Syslog Viewer, which displays all log messages, including other
security check violation logs.

The XML based Syslog Viewer provides various filter options for selecting only the log messages that
are of interest to you. To select log messages for the XML SQL Injection check, filter by selecting
APPFW in the dropdown options for Module. The Event Type list offers a rich set of options to further

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1703

NetScaler 12.0

refine your selection. For example, if you select the APPFW_XML_SQL check box and click the Apply
button, only log messages pertaining to the XML SQL Injection security check violations appear in
the Syslog Viewer.
If you place the cursor in the row for a specific log message, multiple options, such as Module, Event
Type, Event ID, and Client IP appear below the log message. You can select any of these options to
highlight the corresponding information in the log message.

Statistics for the XML SQL injection violations

When the stats action is enabled, the counter for the XML SQL Injection check is incremented when
the App Firewall takes any action for this security check. The statistics are collected for Rate and Total
count for Traffic, Violations, and Logs. The size of an increment of the log counter can vary depend-
ing on the configured settings. For example, if the block action is enabled, a request for a page that
contains three XML SQL Injection violations increments the stats counter by one, because the page
is blocked as soon as the first violation is detected. However, if block is disabled, processing the same
request increments the statistics counter for violations and the logs by three, because each violation
generates a separate log message.
To display XML SQL Injection check statistics by using the command line
At the command prompt, type:
> sh appfw stats

To display stats for a specific profile, use the following command:

> stat appfw profile <profile name>

To display XML SQL Injection statistics by using the GUI

1. Navigate to System > Security > App Firewall.
2. In the right pane, access the Statistics Link.
3. Use the scroll bar to view the statistics about XML SQL Injection violations and logs. The statis-
tics table provides real-time data and is updated every 7 seconds.
1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

XML attachment check

September 20, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1704

NetScaler 12.0

Contributed by:
C

The XML Attachment check examines incoming requests for malicious attachments, and it blocks
those requests that contain attachments that might breach applications security. The purpose of the
XML Attachment check is to prevent an attacker from using an XML attachment to breach security on
your server.

If you use the wizard or the GUI, in the Modify XML Attachment Check dialog box, on the General tab
you can enable or disable the Block, Learn, Log, Statistics, and Learn actions:

If you use the command-line interface, you can enter the following command to configure the XML
Attachment Check:

• set appfw profile <name> -xmlAttachmentAction [block] [learn] [log] [

stats] [none]

You must configure the other XML Attachment check settings in the GUI. In the
Modify XML Attachment Check dialog box, on the
Checks tab, you can configure the following settings:

• Maximum Attachment Size. Allow attachments that are no larger than the maximum attach-
ment size you specify. To enable this option, first select the Enabled check box, and then type
the maximum attachment size in bytes in the Size text box.
• Attachment Content Type. Allow attachments of the specified content type. To enable this
option, first select the Enabled check box, and then enter a regular expression that matches the
Content-Type attribute of the attachments that you want to allow.
– You can type the URL expression directly in the text window. If you do so, you can use
the Regex Tokens menu to enter a number of useful regular expressions at the cursor
instead of typing them manually.
– You can click Regex Editor to open the Add Regular Expression dialog box and use it
to construct the URL expression.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Web services interoperability check

September 18, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1705

NetScaler 12.0

Contributed by:
C

The Web Services Interoperability (WS-I) check examines both requests and responses for adherence
to the WS-I standard, and blocks those requests and responses that do not adhere to this standard.
The purpose of the WS-I check is to block requests that might not interact with other XML appropri-
ately. An attacker can use inconsistencies in interoperability to launch an attack on your XML applica-
tion.

If you use the wizard or the GUI, in the Modify Web Services Interoperability Check dialog box, on the
General tab you can enable or disable the Block, Log, Statistics, and Learn actions.

If you use the command-line interface, you can enter the following command to configure the Web
Services Interoperability check:

• set appfw profile <name> -xmlWSIAction [block] ][log] [learn] [stats] [

none]

To configure individual Web Services Interoperability rules, you must use the GUI. On the Checks tab
of the Modify Web Services Interoperability Check dialog box, select a rule and click Enable or Disable
to enable or disable the rule. You can also click Open to open the Web Services Interoperability Detail
message box for that rule. The message box displays read-only information about the rule. You cannot
modify or make other configuration changes to any of these rules.

The WS-I check uses the rules listed in WS-I Basic Profile 1.0. WS-I delivers best practices for develop-
ing interoperable Web Services solutions. WS-I checks are performed only on SOAP Messages.

Description of each WSI standard rule is provided below:

Rule Description

BP1201 Message body should be a soap:envelope with

namespace.
R1000 When an ENVELOPE is a Fault, the soap:Fault
element MUST NOT have element children
other than faultcode, faultstring, faultactor and
detail.
R1001 When an ENVELOPE is a Fault, the element
children of the soap:Fault element MUST be
unqualified.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1706

NetScaler 12.0

Rule Description

R1003 A RECEIVER MUST accept fault messages that

have any number of qualified or unqualified
attributes, including zero, appearing on the
detail element. The namespace of qualified
attributes can be anything other than the
namespace of the qualified document
element Envelope.
R1004 When an ENVELOPE contains a faultcode
element, the content of that element SHOULD
be either one of the fault codes defined in
SOAP 1.1 (supplying additional information if
necessary in the detail element), or a Qname
whose namespace is controlled by the fault’s
specifying authority (in that order of
preference).
R1005 An ENVELOPE MUST NOT contain
soap:encodingStyle attribute on any of the
elements whose namespace is the same as the
namespace of the qualified document
element Envelope.
R1006 An ENVELOPE MUST NOT contain
soap:encodingStyle attributes on any element
that is a child of soap:Body.
R1007 An ENVELOPE described in an rpc-literal
binding MUST NOT contain soap:encodingStyle
attribute on any element that is a grandchild of
soap:Body.
R1011 An ENVELOPE MUST NOT have any element
children of soap:Envelope following the
soap:Body element.
R1012 A MESSAGE MUST be serialized as either UTF-8
or UTF-16.
R1013 An ENVELOPE containing a
soap:mustUnderstand attribute MUST only use
the lexical forms 0 and 1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1707

NetScaler 12.0

Rule Description

R1014 The children of the soap:Body element in an

ENVELOPE MUST be namespace qualified.
R1015 A RECEIVER MUST generate a fault if they
encounter an envelope whose document
element is not soap:Envelope.
R1031 When an ENVELOPE contains a faultcode
element the content of that element SHOULD
NOT use of the SOAP 1.1 dot notation to refine
the meaning of the fault.
R1032 The soap:Envelope, soap:Header, and
soap:Body elements in an ENVELOPE MUST
NOT have attributes in the same namespace as
that of the qualified document
element Envelope
R1033 An ENVELOPE SHOULD NOT contain the
namespace declaration: xmlns:xml=http://
www.w3.org/XML/1998/namespace.
R1109 The value of the SOAPAction HTTP header field
in a HTTP request MESSAGE MUST be a quoted
string.
R1111 An INSTANCE SHOULD use a 200 OK HTTP
status code on a response message that
contains an envelope that is not a fault.
R1126 An INSTANCE MUST return a 500 Internal
Server Error HTTP status code if the response
envelope is a Fault.
R1132 A HTTP request MESSAGE MUST use the HTTP
POST method.
R1140 A MESSAGE SHOULD be sent using HTTP/1.1.
R1141 A MESSAGE MUST be sent using either HTTP/1.1
or HTTP/1.0.
R2113 An ENVELOPE MUST NOT include the
soapenc:arrayType attribute.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1708

NetScaler 12.0

Rule Description

R2211 An ENVELOPE described with an rpc-literal

binding MUST NOT have the xsi:nil attribute
with a value of 1 or true on the part accessors.
R2714 For one-way operations, an INSTANCE MUST
NOT return a HTTP response that contains an
envelope. Specifically, the HTTP response
entity-body must be empty.
R2729 An ENVELOPE described with an rpc-literal
binding that is a response MUST have a
wrapper element whose name is the
corresponding wsdl:operation name suffixed
with the stringResponse.
R2735 An ENVELOPE described with an rpc-literal
binding MUST place the part accessor
elements for parameters and return value in no
namespace.
R2738 An ENVELOPE MUST include all
soapbind:headers specified on a wsdl:input or
wsdl:output of a wsdl:operation of a
wsdl:binding that describes it.
R2740 A wsdl:binding in a DESCRIPTION SHOULD
contain a soapbind:fault describing each
known fault.
R2744 A HTTP request MESSAGE MUST contain a
SOAPAction HTTP header field with a quoted
value equal to the value of the soapAction
attribute of soapbind:operation, if present in
the corresponding WSDL description.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1709

NetScaler 12.0

XML message validation check

September 20, 2018

Contributed by:
C

The XML Message Validation check examines requests that contain XML messages to ensure that they
are valid. If a request contains an invalid XML message, the App Firewall blocks the request. The
purpose of the XML Validation check is to prevent an attacker from using specially constructed invalid
XML messages to breach the security of your application.

If you use the wizard or the GUI, in the Modify XML Message Validation Check dialog box, on the General
tab you can enable or disable the Block, Log, and Statistics actions.

If you use the command-line interface, you can enter the following command to configure the XML
Message Validation Check:

• set appfw profile <name> -xmlValidationAction [block] [log] [stats] [

none]

You must use the GUI to configure the other XML Validation check settings. In the
Modify XML Message Validation Check dialog box, on the
Checks tab, you can configure the following settings:

• XML Message Validation. Use one of the following options to validate the XML message:
– SOAP Envelope. Validate only the SOAP envelope of XML messages.
– WSDL. Validate XML messages by using an XML SOAP WSDL. If you choose WSDL validation,
in the WSDL Object drop-down list you must choose a WSDL. If you want to validate against
a WSDL that has not already been imported to the App Firewall, you can click the Import
button to open the Manage WSDL Imports dialog box and import your WSDL. See “WSDL
topic” for more information.
* If you want to validate the entire URL, leave the Absolute radio button in the End Point
Check button array selected. If you want to validate only the portion of the URL after
the host, select the Relative radio button.
* If you want the App Firewall to enforce the WSDL strictly, and not allow any additional
XML headers not defined in the WSDL, you must clear the Allow additional headers not
defined in the WSDL check box.
Caution: If you uncheck the
Allow Additional Headers not defined in the WSDL check box, and your WSDL does
not define all XML headers that your protected XML application or Web 2.0 applica-
tion expects or that a client sends, you may block legitimate access to your protected
service.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1710

NetScaler 12.0

– XML Schema. Validate XML messages by using an XML schema. If you choose XML schema
validation, in the XML Schema Object drop-down list you must choose an XML schema. If
you want to validate against an XML schema that has not already been imported to the App
Firewall, you can click the Import button to open the Manage XML Schema Imports dialog
box and import your WSDL. See WSDL for more information.
• Response Validation. By default, the App Firewall does not attempt to validate responses. If
you want to validate responses from your protected application or Web 2.0 site, select the Vali-
date Response check box. When you do, the Reuse the XML Schema specified in request valida-
tion check box and the XML Schema Object drop-down list are activated.
– Check the Reuse XML Schema check box to use the schema you specified for request vali-
dation to do response validation as well.
Note: If you check this check box, the
XML Schema Object drop-down list is grayed out.
– If you want to use a different XML schema for response validation, use the XML Schema
Object drop-down list to select or upload that XML schema.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

XML SOAP fault filtering check

September 18, 2018

Contributed by:
C

The XML SOAP fault filtering check examines responses from your protected web services and filters
out XML SOAP faults. This prevents leaking of sensitive information to attackers.

If you use the wizard or the GUI, in the Modify XML SOAP Fault Filtering Check dialog box, on the Gen-
eral tab you can enable or disable the Block, Log, and Statistics actions, and the Remove action, which
removes SOAP faults before forwarding the response to the user.

If you use the command-line interface, you can enter the following command to configure the XML
SOAP Fault Filtering Check:

set appfw profile <name> -XMLSOAPFaultAction [block] [log] [stats] [none]

You cannot configure exceptions to the XML SOAP Fault Filtering check. You can only enable or disable
it.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1711

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Managing content types

October 4, 2018

Contributed by:
C

Web servers usually add a Content-Type header that contains a MIME/type definition for the type of
content in each file that the web server serves to users. Web servers serve many different types of
content. For example, standard HTML is assigned the “text/html” MIME type. JPG images are assigned
the “image/jpeg” or “image/jpg” content type. A normal web server can serve dozens or hundreds of
different types of content, all defined in the Content Type header by an assigned MIME/type.

Many App Firewall filtering rules are designed to filter specific types of content. Because filtering rules
that apply to one type of content (such as HTML) are often inappropriate when filtering a different type
of content (such as images), the App Firewall attempts to determine the content type of requests and
responses before it filters them. When a web server or browser does not add a Content-Type header
to a request or response, the App Firewall applies a default content type to the connection and filters
the content accordingly.

The default content type is normally “application/octet-stream”, the most generic MIME/type defini-
tion.This MIME/type is appropriate for any type of content that a web server is likely to serve, but also
does not provide much information to the App Firewall to allow it to choose appropriate filtering. If a
protected web server on your network is configure to add accurate content type headers to the con-
tent it serves, or serves only one type of content, you can create a profile for that web server and assign
a different default content type to it to improve both the speed and the accuracy of filtering.

You can also configure a list of allowed request content types for a specific profile. When this feature is
configured, if the App Firewall filters a request that does not match one of the allowed content types,
it blocks the request. After upgrade from release 10.5 to 11.0, unknown content-types which are not
in the default allowed content-type list do not bind. You can add other content-types which you want
to be allowed to the relaxed rules.

Requests must always be of either the “application/x-www-form-urlencoded”, ”multipart/form-data”,

or “text/x-gwt-rpc” types. The App Firewall blocks any request that has any other content type desig-
nated.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1712

NetScaler 12.0

Note

You cannot include the “application/x-www-form-urlencoded” or “multipart/form-data” content

types on the allowed response content types list.

To set the default request content type by using the command line interface

At the command prompt, type the following commands:

• set appfw profile <name> -requestContentType <type>
• save ns config

Example

The following example sets the “text/html” content type as the default for the specified profile:

1 set appfw profile profile1 -requestContentType ”text/html”

2 save ns config

To remove the user-defined default request content type by using the command line
interface

At the command prompt, type the following commands:

• unset appfw profile <name> -requestContentType <type>
• save ns config

Example

The following example unsets the default content type of “text/html” for the specified profile, allowing
the type to revert to “application/octet-stream”:

1 unset appfw profile profile1 -requestContentType ”text/html”

2 save ns config

Note

Always use last content-type header for processing and remove remaining content-type headers
if any that ensures that the backend server receives a request with only one content-type.

To block requests that can be bypassed, add an App Firewall policy with rule as HTTP.REQ.HEADER
(“content-type”).COUNT.GT(1)’ and profile as appfw_block.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1713

NetScaler 12.0

If a request is received without a Content-Type header or if the request has Content-Type

header without any value, App Firewall applies the configured RequestContentType value and
processes the request accordingly.

To set the default response content type by using the command line interface

At the command prompt, type the following commands:

• set appfw profile <name> -responseContentType <type>
• save ns config

Example

The following example sets the “text/html” content type as the default for the specified profile:

1 set appfw profile profile1 -responseContentType ”text/html”

2 save ns config

To remove the user-defined default response content type by using the command line
interface

At the command prompt, type the following commands:

• unset appfw profile <name> -responseContentType <type>
• save ns config

Example

The following example unsets the default content type of “text/html” for the specified profile, allowing
the type to revert to “application/octet-stream”:

1 unset appfw profile profile1 -responseContentType ”text/html”

2 save ns config

To add a content type to the allowed content types list by using the command line
interface

At the command prompt, type the following commands:

• bind appfw profile <name> -ContentType <contentTypeName>
• save ns config

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1714

NetScaler 12.0

Example

The following example adds the “text/shtml” content type to the allowed content types list for the
specified profile:

1 bind appfw profile profile1 -contentType ”text/shtml”

2 save ns config

To remove a content type from the allowed content types list by using the command
line interface

At the command prompt, type the following commands:

• unbind appfw profile <name> -ContentType <contentTypeName>

• save ns config

Example

The following example removes the “text/shtml” content type from the allowed content types list for
the specified profile:

1 unbind appfw profile profile1 -contentType ”text/shtml”

2 save ns config

To manage the default and allowed content types by using the GUI

1. Navigate to Security > App Firewall > Profiles.

2. In the details pane, select the profile that you want to configure, and then click Edit. The Con-
figure App Firewall Profile dialog box is displayed.
3. The Configure App Firewall Profile dialog box, click the Settings tab.
4. On the Settings tab, scroll down about halfway to the Content Type area.
5. In the Content Type area, configure the default request or response content type:
• To configure the default request content type, type the MIME/type definition of the content
type you want to use in the Default Request text box.
• To configure the default response content type, type the MIME/type definition of the con-
tent type you want to use in the Default Response text box.
• To create a new allowed content type, click Add. The Add Allowed Content Type dialog
box is displayed.
• To edit an existing allowed content type, select that content type, and then click Open.
The Modify Allowed Content Type dialog box is displayed.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1715

NetScaler 12.0

6. To manage the allowed content types, click Manage Allowed Content Types.
7. To add a new content type or modify an existing content type, click Add or Open, and in the Add
Allowed Content Type or Modify Allowed Content Type dialog box, do the following steps.
a) Select/clear the Enabled check box to include the content type in, or exclude it from, the
list of allowed content types.
b) In the Content Type text box, type a regular expression that describes the content type that
you want to add, or change the existing content type regular expression.
Content types are formatted exactly as MIME type descriptions are.
Note: You can include any valid MIME type on the allowed contents type list. Since
many types of document can contain active content and therefore could potentially
contain malicious content, you should exercise caution when adding MIME types to
this list.
c) In the Comments text box, add an optional comment that describes the reason for adding
this particular MIME type to the allowed contents type list.
d) Click Create or OK to save your changes.
8. Click Close to close the Manage Allowed Content Types dialog box and return to the Settings
tab.
9. Click OK to save your changes.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Profiles

September 18, 2018

Contributed by:
C

A profile is a collection of security settings that are used to protect specific types of web content or
specific parts of your web site. In a profile, you determine how the App Firewall applies each of its
filters (or checks) to requests to your web sites, and responses from them. The App Firewall supports
two types of profile: four built-in (default) profiles that do not require further configuration, and user-
defined profiles that do require further configuration.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1716

NetScaler 12.0

Built-in profiles

The four App Firewall built-in profiles provide simple protection for applications and web sites that
either do not require protection, or that should not be directly accessed by users at all. These profile
types are:
• APPFW_BYPASS. Skips all App Firewall filtering and sends the unmodified traffic to the pro-
tected application or web site, or to the client.
• APPFW_RESET. Resets the connection, requiring that the client re-establish his or her session
by visiting a designated start page.
• APPFW_DROP. Drops all traffic to or from the protected application or web site, and sends no
response of any kind to the client.
• APPFW_BLOCK. Blocks traffic to or from the protected application or web site.
You use the built-in profiles exactly as you do user-defined profiles, by configuring a policy that selects
the traffic to which you want to apply the profile and then associating the profile with your policy.
Since you do not have to configure a built-in policy, it provides a quick way to allow or block specified
types of traffic or traffic that is sent to specific applications or web sites.

User-defined profiles

User-defined profiles are profiles that are build and configured by users. Unlike the default profiles,
you must configure a user-defined profile before it will be of use filtering traffic to and from your pro-
tected applications.
There are three types of user-defined profile:
• HTML. Protects HTML-based web pages.
• XML. Protects XML-based web services and web sites.
• Web 2.0. Protects Web 2.0 content that combines HTML and XML content, such as ATOM feeds,
blogs, and RSS feeds.
The App Firewall has a number of security checks, all of which can be enabled or disabled, and con-
figured in a number of ways in each profile. Each profile also has a number of settings that control
how it handles different types of content. Finally, rather than manually configuring all of the secu-
rity checks, you can enable and configure the learning feature. This feature observes normal traffic
to your protected web sites for a period of time, and uses those observations to provide you with a
tailored list of recommended exceptions (relaxations) to some security checks, and additional rules
for other security checks.
During initial configuration, whether by using the App Firewall Wizard or manually, you normally cre-
ate one general purpose profile to protect all content on your web sites that is not covered by a more
specific profile. After that, you can create as many specific profiles as you want to protect more spe-
cialized content.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1717

NetScaler 12.0

The Profiles pane consists of a table that contains the following elements:

Name. Displays all the App Firewall profiles configured in the appliance.

Bound signature. Displays the signatures object that is bound to the profile in the previous column,
if any.

Policies. Displays the App Firewall policy that invokes the profile in the leftmost column of that row,
if any.

Comments. Displays the comment associated with the profile in the leftmost column of that row, if
any.

Profile Type. Displays the type of profile. Types are Built-In, HTML, XML, and Web 2.0.

Above the table is a row of buttons and a drop-down list that allow you to create, configure, delete,
and view information about your profiles:

• Add. Add a new profile to the list.

• Edit. Edit the selected profile.
• Delete. Delete the selected profile from the list.
• Statistics. View the statistics for the selected profile.
• Action. Drop-down list that contains additional commands. Currently allows you to import a
profile that was exported from another App Firewall configuration.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Creating App Firewall profiles

September 20, 2018

Contributed by:
C

You can create an App Firewall profile in one of two ways: by using the command line, and by using the
GUI. Creating a profile by using the command line requires that you specify options on the command
line. The process is similar to that of configuring an existing profile, and with a few exceptions the two
commands take the same parameters.

Creating a profile by using the GUI requires that you specify only two options. You specify basic or
advanced defaults, the default configuration for the various security checks and settings that are part
of a profile, and choose the profile type to match the type of content that the profile is intended to

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1718

NetScaler 12.0

protect. You can also, optionally, add a comment. After you create the profile, you must then configure
it by selecting it in the data pane, and then clicking Edit.

If you plan to use the learning feature or to enable and configure a large number of advanced protec-
tions, you should choose advanced defaults. In particular, if you plan to configure either of the SQL
injection checks, either of the cross-site scripting checks, any check that provides protection against
Web form attacks, or the cookie consistency check, you should plan to use the learning feature. Unless
you include the proper exceptions for your protected Web sites when configuring these checks, they
can block legitimate traffic. Anticipating all of the necessary exceptions without creating any that are
too broad is difficult. The learning feature makes this task much easier. Otherwise, basic defaults are
quick and should provide the protection that your web applications need.

There are three profile types:

• HTML. Protects standard HTML-based web sites.

• XML. Protects XML-based web services and web sites.
• Web 2.0 (HTML XML). Protects sites that contain both HTML and XML elements, such as ATOM
feeds, blogs, and RSS feeds.

There are also a few restrictions on the name that you can give to a profile. A profile name cannot
be the same as the name assigned to any other profile or action in any feature on the NetScaler ap-
pliance. Certain action or profile names are assigned to built-in actions or profiles, and can never
be used for user profiles. A complete list of disallowed names can be found in the App Firewall Pro-
fileSupplemental Information. If you attempt to create a profile with a name that has already been
used for an action or a profile, an error message is displayed and the profile is not created.

To create an App Firewall profile by using the command line interface

At the command prompt, type the following commands:

• add appfw profile <name> [-defaults ( basic | advanced )]

• set appfw profile <name> -type ( HTML | XML | HTML XML )
• set appfw profile <name> -comment ”<comment>”
• save ns config

Example

The following example adds a profile named pr-basic, with basic defaults, and assigns a profile type
of HTML. This is the appropriate initial configuration for a profile to protect an HTML Web site.

1 add appfw profile pr-basic -defaults basic -comment ”Simple profile for
web sites.”
2 set appfw profile pr-basic -type HTML

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1719

NetScaler 12.0

3 save ns config

To create an App Firewall profile by using the GUI

Creating an App Firewall profile requires that you specify only a few configuration details.

1. Navigate to Security > Application Firewall > Profiles.

2. In the details pane, click Add.

3. In the Create App Firewall Profile dialog box, type a name for your profile.

The name can begin with a letter, number, or the underscore symbol, and can consist of from
one to 31 letters, numbers, and the hyphen (-), period (.) pound (#), space ( ), at (@), equals (=),
colon (:), and underscore (_) symbols.

4. Choose the profile type from the drop-down list.

5. Click Create, and then click Close.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Configuring App Firewall profiles

September 18, 2018

Contributed by:
C

To configure a user-defined App Firewall profile, first configure the security checks, which are called
deep protections or advanced protections in the App Firewall wizard. Certain checks require configura-
tion if you are to use them at all. Others have default configurations that are safe but limited in scope;
your web sites might need or benefit from a different configuration that takes advantage of additional
features of certain security checks.

After you have configured the security checks, you can also configure a number of other settings that
control the behavior, not of a single security check, but the App Firewall feature. The default configu-
ration is sufficient to protect most web sites, but you should review them to make sure that they are
right for your protected web sites.

For more information about the App Firewall security checks, see “Advanced Protections.”

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1720

NetScaler 12.0

To configure an App Firewall profile by using the command line

At the command prompt, type the following commands:

• set appfw profile <name> <arg1> [<arg2> ...]

where:

– <arg1> = a parameter and any associated options.

– <arg2> = a second parameter and any associated options.
– … = additional parameters and options.

For descriptions of the parameters to use when configuring specific security checks, see “Ad-
vanced Protections.”

• save ns config

Example

The following example shows how to enable blocking for the HTML SQL Injection and HTML Cross-Site
Scripting checks in a profile named
pr-basic. This command enables blocking for those actions while making no other changes to the
profile.

1 set appfw profile pr-basic -crossSiteScriptingAction block -

SQLInjectionAction block

To configure an App Firewall profile by using the GUI

1. Navigate to Security > Application Firewall > Profiles.

2. In the details pane, select the profile that you want to configure, and then click Edit.
3. In the Configure App Firewall Profile dialog box, on the Security Checks tab, configure the
security checks.
• To enable or disable an action for a check, in the list, select or clear the check box for that
action.
• To configure other parameters for those checks that have them, in the list, click the blue
chevron to the far right of that check. In the dialog box that appears, configure the param-
eters. These vary from check to check.
You can also select a check and, at the bottom of the dialog box, click Open to display the
Configure Relaxation dialog box or Configure Rule dialog box for that check. These dia-
log boxes also vary from check to check. Most of them include a Checks tab and a General
tab. If the check supports relaxations or user-defined rules, the Checks tab includes an

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1721

NetScaler 12.0

Add button, which opens yet another dialog box, in which you can specify a relaxation or
rule for the check. (A relaxation is a rule for exempting specified traffic from the check.) If
relaxations have already been configured, you can select one and click Open to modify it.
• To review learned exceptions or rules for a check, select the check, and then click Learned
Violations. In the Manage Learned Rules dialog box, select each learned exception or
rule in turn.
– To edit the exception or rule, and then add it to the list, click Edit & Deploy.
– To accept the exception or rule without modification, click Deploy.
– To remove the exception or rule from the list, click Skip.
• To refresh the list of exceptions or rules to be reviewed, click Refresh.
• open the Learning Visualizer and use it to review learned rules, click Visualizer.
• review the log entries for connections that matched a check, select the check, and then
click Logs. You can use this information to determine which checks are matching attacks,
so that you can enable blocking for those checks. You can also use this information to
determine which checks are matching legitimate traffic, so that you can configure an ap-
propriate exemption to allow those legitimate connections. For more information about
the logs, see “Logs, Statistics, and Reports.”
• To completely disable a check, in the list, clear all of the check boxes to the right of that
check.
4. On the Settings tab, configure the profile settings.
• To associate the profile with the set of signatures that you previously created and config-
ured, under Common Settings, choose that set of signatures in the Signatures drop-down
list.
Note: You may need to use the scroll bar on the right of the dialog box to scroll down
to display the Common Settings section.
• To configure an HTML or XML Error Object, select the object from the appropriate drop-
down list.
Note: You must first upload the error object that you want to use in the Imports pane.
For more information about importing error objects, see Imports
• To configure the default XML Content Type, type the content type string directly into the
Default Request and Default Response text boxes, or click Manage Allowed Content Types
to manage the list of allowed content types. “»More….”
5. If you want to use the learning feature, click Learning, and configure the learning settings for
the profile, as described in “Configuring and Using the Learning Feature”.
6. Click OK to save your changes and return to the Profiles pane.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1722

NetScaler 12.0

Changing an App Firewall profile type

September 20, 2018

Contributed by:
C

If you chose the wrong profile type for an App Firewall profile, or the type of content on the protected
web site has changed, you can change the profile type.

Note: When you change the profile type, you lose all configuration settings and learned relax-
ations or rules for the features that the new profile type does not support. For example, if you
change the profile type from Web 2.0 to XML, you lose any configuration options for Start URL,
Form Field Consistency Check, and the other HTML-specific security checks. The configuration
for any options that is supported by both the old and the new profile types remains unchanged.

To change an App Firewall profile type by using the command line interface

At the command prompt, type the following commands:

• set appfw profile <name> -type ( HTML | XML | HTML XML )

• save ns config

Example

The following example changes the type of a profile named pr-basic, from HTML to HTML XML, which
is equivalent to the Web 2.0 type in the GUI.

1 set appfw profile pr-basic -type HTML XML

2 save ns config

To change an App Firewall profile type by using the GUI

1. Navigate to Security > Application Firewall > Policies.

2. In the details pane, click Action, and then Change Profile Type.
3. In the Change App Firewall Profile Type dialog box, Profile Type drop-down list, select a new
profile type.
4. Click OK to save your changes and return to the Profiles pane.

1.
2. Citrix ADC

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1723

NetScaler 12.0

3. NetScaler 12.0
4. App Firewall

Exporting and importing an App Firewall profile

September 20, 2018

Contributed by:
C

You can replicate the entire configuration of an App Firewall profile (including all bound objects, such
as HTML error object, XML error object, WSDL or XML schema, signatures, and so on) across multiple
appliances. You can select a target profile and export the configuration to save it in your computer’s lo-
cal file system, or you can transfer the archived configuration to store it on a server. Similarly, you can
browse your computer’s local file system or import the archive from the server to select a previously
exported profile and import it into your NetScaler appliance.

The option to export the entire profile configuration and then import it into another appliance can
be useful in various use cases. For example, you might want to configure an App Firewall profile in
a test bed set-up to test and validate that it is working as expected. Once you are satisfied, you can
export the profile and import the profile configuration to your production NetScaler appliances. This
functionality is also useful for backing up your configuration. You can export the profile before making
changes, so that you can easily roll back the configuration to a known state if necessary.

Note

App Firewall profiles that are exported and archived from one build cannot be restored to a sys-
tem running a different build, because changes introduced in the newer releases can lead to
compatibility issues. If you attempt to restore an archived profile to a different build than the
one from which it was exported, an error message is logged in ns.log.

The export and import profile functionality is available in both the GUI (GUI) and the command line
interface (CLI). The GUI is recommended, because it offers easy to use Action options. With a click of
a button you can Export or Import the entire configuration of a profile.

Exporting App Firewall profiles with the CLI

If you use CLI to export a profile, you must archive the configuration and then export it. To import
a profile, you must import the archive into the NetScaler appliance and then execute the restore
command to extract the configuration. The following set of CLI commands can be used for exporting,
importing and managing the profile configurations.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1724

NetScaler 12.0

CLI commands to export archives:

• archive appfw profile <name> <archivename> [-comment <string>]

• export appfw archive <name> <target>

CLI commands to import archives:

• import appfw archive <src> <name> [-comment <string>]

• restore appfw profile <archivename>

CLI commands to manage archives:

• show appfw archive

• rm appfw archive <name>

Exporting a profile from one appliance and importing it to another requires five steps in CLI. The first
3 steps are performed on the source appliance on which profile configuration is originally created,
and the next 2 steps are performed on the target appliance on which the profile configuration is to be
replicated.

Export profile from the source NetScaler appliance:

Step 1: Create an archive of the configured profile.

Step 2: Export the archive to the NetScaler file system.

Step 3: Use a file transfer utility such as scp to transfer the exported archive file from NetScaler appli-
ance A to the target NetScaler appliance.

Import profile to the target NetScaler appliance:

Step 4: Execute the import command to import the archived file. You can import the archive from
your NetScaler’s local file system, or you can use HTTP or HTTPS protocol to import the archive from
a server by using the URL.

Step 5: Execute the restore command to restore the profile configuration from the imported archive

To export an App Firewall profile by using the command line interface:

First, archive the profile’s configuration, and then export the archive to a target location. At the com-
mand prompt, type the following commands:

archive appfw profile <profileName> <archiveName>

where:

• <profileName> is the name of the profile to archive.

• <archiveName> is the name of the archive file to create.

Execution of the above command creates 2 instances of the archive file. One in /var/tmp folder and
another in the /var/archive/appfw folder.

export appfw archive <archiveName> <target>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1725

NetScaler 12.0

where:

• <archiveName> is the name of the archive to export. (The same name as in the previous com-
mand.
• <target> is a file path starting with local: as the prefix, followed by <archiveName>.

Execution of the export command saves the exported archive file on the file system of your NetScaler
appliance in the /var/tmp folder.

Examples:

> archive appfw profile test_pr archived_test_pr

> export appfw archive archived_test_pr local:dutA_test_pr

After the above two commands are executed, the /var/tmp folder contains the archived_test_pr file
and the exported copy, dutA_test_pr, which are identical in size. From the CLI, you can drop into the
shell to navigate to the folder to verify that these files are there.

After exporting the archive file, you can use scp or some other such file transfer utility to transfer a copy
of the archive file from the NetScaler appliance on which they were created to your target NetScaler
appliance.

Importing App Firewall profiles with the CLI

After you have successfully scp’d the archived file from the source appliance to the target appliance,
you are ready to import the profile’s archive, and then execute the restore command to replicate the
profile’s configuration on the target appliance.

Log onto the target appliance. Drop into the shell and cd to the /var/tmp folder to verify that the size
of the scp’d file on this appliance matches the size of the original archived file on the source appliance.
Exit the shell to return to the command line.

To import a profile by using the CLI:

At the command prompt, type the following commands:

import appfw archive <src> <name> [-comment <string>]

where

• <src> is the location of the archive file after it has been transferred from the source appliance on
which it was created. You can use a local file system and file name. If you have placed the archive
on a server, you can use a URL to import the archived file. If the path or file name contains
spaces, enclose the URL in straight double quotation marks.
• <name> is the name of the archive file to be imported.
• <string> is an optional description of the purpose of the Archive.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1726

NetScaler 12.0

restore appfw profile <archiveName>

Examples:

A. Import from local file followed by restore:

> import appfw archive local:dutA_test_pr dut2_test_pr

> restore appfw profile dut2_test_pr

B. Import from URL followed by restore:

import appfw archive http://10.217.30.16/FFC/Profile_ImportExport/

dutA_test_pr.tgz my_archive
restore appfw profile my_archive

This example restores the test_pr profile along with all bound objects (such as signatures, html error
page, relaxation rules and so on) on the target NetScaler appliance.

You can use the following CLI commands to access man pages for additional details.

• man archive appfw profile

• man export appfw archive
• man import appfw archive
• man restore appfw profile
• man show appfw archive
• man rm appfw archive

Exporting and importing App Firewall profiles with the GUI

The GUI is easier to use than the CLI. The utility performs both archive and export operations when
you click Export. Similarly it executes both import and restore when you click Import. The GUI can
access the local file system of the computer from which you access the utility. You can export a copy
of the archive and save it on your local computer. You can then import this copy directly in the target
appliance without having to manually transfer the archive file from one appliance to the other(s).

To export an App Firewall profile by using the GUI:

1. Navigate to Configuration > Security > App Firewall > Profiles.

2. In the details pane, select a profile to export. Click Actions and select Export to download and
save a copy in your computer’s local file system.

To import an App Firewall profile by using the GUI:

1. Navigate to Configuration > Security > App Firewall > Profiles.

2. In the details pane, click Actions and select Import. In the Import App Firewall Profile pane,
the Import From* selection box gives you 2 options:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1727

NetScaler 12.0

URL: You can choose to import an archive by specifying a URL. When this option is selected, you must
provide an absolute path for the archived file in the URL input box.

File: You can choose to import an archive from the local File. When this option is selected, a Local
File selection field is displayed. You can browse your computer’s local files to select the target archive
file.

Click Create to import the specified archive. Successful completion of the import operation creates
the profile configuration on the target appliance.

Highlights

• You can replicate the entire configuration (including all import objects as well as configured
relaxation rules for the profile) on multiple appliances, without needing to repeat configuration
steps, by using export and import profile functionality.
• The imported objects, such as signatures, WSDL, Schema, error page and so on, are included in
the archived tar file and replicated on the target appliance.
• Customized field types are included in the archived tar file and replicated on the target appli-
ance.
• The policy bindings of the archived profile are not replicated when the configuration is restored.
You must configure the policy and bind it to the profile after importing the profile to the appli-
ance.
• The name of the archive file can be up to 31 character long. As with profile names, an archive
name must begin with an alphanumeric character or underscore and contain only alphanu-
meric and underscore (_), number (#), period (.), space ( ), colon (:), at (@), equals (=) or hyphen
(-) characters.
• Comments associated with the archive should be descriptive enough to convey the purpose of
the archived configuration. The maximum allowed length for a comment is 255 characters.
• The “clear config –force basic” command does not remove the archived profiles.
• The import and export profile functionality is supported in high availability (HA) deployments.

Debugging tips

• Monitor the /var/log/ns.log during command executions to see if there are any ERROR mes-
sages.
• Additional logs (_restore.log, remove.log, import.log) are generated in the /var/tmp/folder.
They can help debug issues during the corresponding operations. When these logs reach one
MB in size, the log messages are purged to shrink the log file to one fourth of the original size.
• If the import command fails when you are using the URL option instead of the local file system,
verify that DNS name server and route settings are accurately configured.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1728

NetScaler 12.0

• If you are using the HTTPS protocol to import the archive, the command might fail if the HTTPS
server requires client certificate authentication.
1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Configuring and using the Learning feature

September 18, 2018

Contributed by:
C
The learning feature is a repetitive pattern filter that observes activity on a web site or application
protected by the App Firewall, to determine what constitutes normal activity on that web site or ap-
plication. It then generates a list of up to 2,000 suggested rules or exceptions (relaxations) for each
security checks that includes support for the learning feature. Users normally find it easier to config-
ure relaxations by using the learning feature than by entering the necessary relaxations manually.
The security checks that support the learning feature are:
• Start URL check
• Cookie Consistency check
• Form Field Consistency check
• Field Formats check
• CSRF Form Tagging check
• HTML SQL Injection check
• HTML Cross-Site Scripting check
• XML Denial-of-Service check
• XML Attachment check
• Web Services Interoperability check
You perform two different types of activities when using the learning feature. First, you enable and
configure the feature to use it. You can use learning on all traffic to your protected web applications,
or you can configure a list of IPs (called the Add Trusted Learning Clients list) from which the learning
feature should generate recommendations. Second, after the feature has been enabled and has pro-
cessed a certain amount of traffic to your protected web sites, you review the list of suggested rules
and relaxations (learned rules) and mark each with one of the following designations:
• Edit & Deploy. The rule is pulled into the Edit dialog box so that you can modify it, and the
modified form is deployed.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1729

NetScaler 12.0

• Deploy. The unmodified learned rule is placed on the list of rules or relaxations for this security
check.
• Skip. The learned rule is placed on a list of rules or relaxations that are not deployed.
The learned rule is removed when skipped. However, as they are not added to relaxations,
they might get learned again.
Learning is not performed only when relaxations are in place, except for field format rules. When rules
are skipped, they are only removed from learned database. As relaxations are not added, they might
get learned again. When rules are deployed, they are removed from learned database and also re-
laxations are added for the rules. As relaxations are added, they would not be learned again. For
fieldformat protection, learning is performed irrespective of relaxations.
Although you can use the command line interface for basic configuration of the learning feature, the
feature is designed primarily for configuration through the App Firewall wizard or the GUI. You can
perform only limited configuration of the learning feature by using the command line.
The wizard integrates configuration of learning features with configuration of the App Firewall as a
whole, and is therefore the easiest method for configuring this feature on a new NetScaler appliance
or when managing a simple App Firewall configuration. The GUI visualizer and manual interface both
provide direct access to all learned rules for all security checks, and are therefore often preferable
when you must review learned rules for a large number of security checks.
The learning database is limited to 20 MB in size, which is reached after approximately 2,000 learned
rules or relaxations are generated per security check for which learning is enabled. If you do not regu-
larly review and either approve or ignore learned rules and this limit is reached, an error is logged to
the NetScaler log and no more learned rules are generated until you review the existing learned rules
and relaxations.
If learning stops because the database has reached its size limit, you can restart learning either by
reviewing the existing learned rules and relaxations or by resetting the learning data. After learned
rules or relaxations are approved or ignored, they are removed from the database. After you reset the
learning data, all existing learning data is removed from the database and it is reset to its minimum
size. When the database falls below 20 MB in size, learning restarts automatically.

To configure the learning settings by using the command line interface

Specify the App Firewall profile to be configured and, for each security check that you want to include
in that profile, specify the minimum threshold or the percent threshold. The minimum threshold is
an integer representing the minimum number of user sessions that the App Firewall must process
before it learns a rule or relaxation (default: 1). The percent threshold is an integer representing the
percentage of user sessions in which the App Firewall must observe a particular pattern (URL, cookie,
field, attachment, or rule violation) before it learns a rule or relaxation (default: 0). Use the following
commands:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1730

NetScaler 12.0

• set appfw learningsettings <profileName> [-startURLMinThreshold <

positive_integer>] [-startURLPercentThreshold <positive_integer>] [-
cookieConsistencyMinThreshold <positive_integer>] [-cookieConsistencyPercentThres
<positive_integer>] [-CSRFtagMinThreshold <positive_integer>] [-
CSRFtagPercentThreshold <positive_integer>] [-fieldConsistencyMinThreshold
<positive_integer>] [-fieldConsistencyPercentThreshold <positive_integer
>] [-crossSiteScriptingMinThreshold <positive_integer>] [-crossSiteScriptingPerce
<positive_integer>] [-SQLInjectionMinThreshold <positive_integer>] [-
SQLInjectionPercentThreshold <positive_integer>] [-fieldFormatMinThreshold
<positive_integer>] [-fieldFormatPercentThreshold <positive_integer>]
[-XMLWSIMinThreshold <positive_integer>] [-XMLWSIPercentThreshold <
positive_integer>] [-XMLAttachmentMinThreshold <positive_integer>] [-
XMLAttachmentPercentThreshold <positive_integer>]
• save ns config

Example

The following example enables and configures the learning settings in the profile pr-basic for the HTML
SQL Injection security check. This is an appropriate initial test bed learning configuration, where you
have complete control over the traffic that is sent to the App Firewall.

1 set appfw learningsettings pr-basic -SQLInjectionMinThreshold 10

2 set appfw learningsettings pr-basic -SQLInjectionPercentThreshold 70
3 save ns config

To reset learning settings to their defaults by using the command line interface

To remove any custom configuration of the learning settings for the specified profile and security
check, and return the learning settings to their defaults, at the command prompt type the following
commands:

• unset appfw learningsettings <profileName> [-startURLMinThreshold

] [-startURLPercentThreshold] [-cookieConsistencyMinThreshold] [-
cookieConsistencyPercentThreshold] [-CSRFtagMinThreshold ] [-CSRFtagPercentThresh
] [-fieldConsistencyMinThreshold ] [-fieldConsistencyPercentThreshold
] [-crossSiteScriptingMinThreshold ] [-crossSiteScriptingPercentThreshold
] [-SQLInjectionMinThreshold ] [-SQLInjectionPercentThreshold ] [-
fieldFormatMinThreshold] [-fieldFormatPercentThreshold ] [-XMLWSIMinThreshold
] [-XMLWSIPercentThreshold ] [-XMLAttachmentMinThreshold ] [-XMLAttachmentPercen
]

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1731

NetScaler 12.0

• save ns config

To display the learning settings for a profile by using the command line interface

At the command prompt, type the following command:

show appfw learningsettings <profileName>

To display unreviewed learned rules or relaxations for a profile by using the command
line interface

At the command prompt, type the following command:

show appfw learningdata <profileName> <securityCheck>

To remove specific unreviewed learned rules or relaxations from the learning database
by using the command line interface

At the command prompt, type the following command:

rm appfw learningdata <profileName> (-startURL <expression> | -cookieConsistency

<string> | (-fieldConsistency <string> <formActionURL>)| (-crossSiteScripting
<string> <formActionURL>)| (-SQLInjection <string> <formActionURL>)| (-
fieldFormat <string><formActionURL>)| (-CSRFTag <expression> <CSRFFormOriginURL
>)| -XMLDoSCheck <expression> | -XMLWSICheck <expression> | -XMLAttachmentCheck
<expression>)[-TotalXMLRequests]

Example

The following example removes all unreviewed learned relaxations for the pr-basic profile, HTML SQL
Injection security check, that apply to the LastName form field.

1 rm appfw learningdata pr-basic -SQLInjection LastName

To remove all unreviewed learned data by using the command line interface

At the command prompt, type the following command:

reset appfw learningdata

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1732

NetScaler 12.0

To export learning data by using the command line interface

At the command prompt, type the following command:

export appfw learningdata <profileName> <securitycheck>[-target <string>]

Example

The following example exports learned relaxations for the pr-basic profile and the HTML SQL Injection
security check to a comma-separated values (CSV) format file in the /var/learnt_data/ directory under
the filename specified in the -target parameter.

1 export appfw learningdata pr-basic SQLInjection -target sqli_ld

To configure the Learning feature by using the GUI

1. Navigate to Security > App Firewall > Profiles.

2. In the Profiles pane, select the profile, and then click Edit.

3. Click the Learning tab. At the top of the Learning tab is list of the security checks that are avail-
able in the current profile and that support the learning feature.

4. To configure the learning thresholds, select a security check, and then type the appropriate
values in the following text boxes:
Minimum number threshold. Depending on which security check’s learning settings you are
configuring, the minimum number threshold might refer to the minimum number of total user
sessions that must be observed, the minimum number of requests that must be observed, or the
minimum number of times a specific form field must be observed, before a learned relaxation
is generated. Default: 1

• Percentage of times threshold. Depending on which security check’s learning settings

you are configuring, the percentage of times threshold might refer to the percentage of
total observed user sessions that violated the security check, the percentage of requests,
or the percentage of times a form field matched a particular field type, before a learned
relaxation is generated. Default: 0

5. To remove all learned data and reset the learning feature, so that it must start its observations
again from the beginning, click Remove All Learned Data.
Note: This button removes only learned recommendations that have not been reviewed and
either approved or skipped. It does not remove learned relaxations that have been accepted
and deployed.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1733

NetScaler 12.0

6. To restrict the learning engine to traffic from a specific set of IPs, click Trusted Learning Clients,
and add the IP addresses that you want to use to the list.

a) To add an IP address or IP address range to the Trusted Learning Clients list, click Add.
b) In the Add Trusted Learning Clients dialog box, Trusted Clients IP list box, type the IP
address or an IP address range in CIDR format.
c) In the Comments text area, type a comment that describes this IP address or range.
d) Click Create to add your new IP address or range to the list.
e) To modify an existing IP address or range, click the IP address or range, and then click
Open. Except for the name, the dialog box that appears is identical to the Add Trusted
Learning Clients dialog box.
f) To disable or enable an IP address or range, but leave it on the list, click the IP address or
range, and then click Disable or Enable, as appropriate.
g) To remove an IP address or range completely, click the IP address or range, and then click
Remove.

7. Click Close to return to the Configure App Firewall Profile dialog box.

8. Click Close to close the Configure App Firewall Profile dialog box, and return to the App Fire-
wall Profile screen.

To review learned rules or relaxations by using the GUI

1. Navigate to Security > App Firewall > Profiles.

2. Select the security check for which you want to review learned rules or relaxations, and then
click Manage Rules.

3. In the Manage Learned Rules dialog box, choose how you want to review the learned rules.

• To review the actual learned patterns as displayed in the window, do nothing and proceed
to the next step.
• To review the learned data hierarchically as a branching tree, enabling you to choose gen-
eral patterns that match many of the learned patterns, click** Visualizer**.

4. If you have chosen to review actual learned patterns, perform the following steps.

5. Select the first learned relaxation and choose how to handle it.
- To modify and then accept the relaxation, click Edit & Deploy, edit the relaxation regular ex-
pression, and then click OK.
- To accept the relaxation without modifications, click Deploy.
- To remove the relaxation from the list without deploying it, click Skip.

a) Repeat the previous step to review each additional learned relaxation.

6. If you have chosen to use the Learning Visualizer, perform the following steps.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1734

NetScaler 12.0

a) In the branching hierarchical display, select a node that contains a learned pattern, and
choose how to handle it.

The screen area beneath the tree structure, under Regex of Selected Node, displays a gen-
eralized expression that matches all of the patterns in that node. If you want to display
an expression that matches just one of the branches or just one of the leaves, select that
branch or leaf.

• To modify and then accept the learned relaxation, click Edit & Deploy, edit the relax-
ation regular expression, and then click OK.

• To accept the relaxation without modifications, click Deploy.

• To remove the modification from the list without deploying it, click Skip.

b) Repeat the previous step to review other portions of the display.

7. Click Close to return to the Manage Learned Rules dialog box.

8. Click Close to return to the Configure App Firewall Profile dialog box.

9. Click Close to close the Configure App Firewall Profile dialog box, and return to the App Fire-
wall Profile screen.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Supplemental Information about profiles

February 15, 2019

Contributed by:
C

Following is supplemental information about particular aspects of App Firewall profiles. This infor-
mation explains how to include special characters in a security check rule or relaxation, and how to
use variables when configuring profiles.

Configuration variable support

Instead of using static values, to configure the App Firewall’s security checks and settings, you can now
use standard NetScaler named variables. By creating variables, you can more easily export and then

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1735

NetScaler 12.0

import configurations to new NetScaler appliances, or update existing NetScaler appliances from a
single set of configuration files. This simplifies updates when you use a test bed setup to develop a
complex App Firewall configuration that is tuned for your local network and servers and then transfer
that configuration to your production NetScaler appliances.
You create App Firewall configuration variables in the same manner as you do any other NetScaler
named variables, following standard NetScaler conventions. To create a named expression variable
by using the GUI, you use the Add Expression dialog box. To create a named expression variable by
using the NetScaler command line, you use the add expression command followed by the appropriate
parameter.
The following URLs and expressions can be configured with variables instead of static values:
• Start URL (-starturl)
• Deny URL ( -denyurl)
• Form Action URL for Form Field Consistency Check (-fieldconsistency)
• Action URL for XML SQL Injection Check (-xmlSQLInjection)
• Action URL for XML Cross-Site Scripting Check (-xmlXSS)
• Form Action URL for HTML SQL Injection Check (-sqlInjection)
• Form Action URL for Field Format Check (-fieldFormat)
• Form Origin URL and Form Action URL for Cross-Site Request Forgery (CSRF) Check (-csrfTag)
• Form Action URL for HTML Cross-Site Scripting Check (-crossSiteScripting)
• Safe Object (-safeObject)
• Action URL for XML Denial-of-Service (XDoS) check (-XMLDoS)
• URL for Web Services Interoperability check (-XMLWSIURL)
• <URL for XML Validation check (-XMLValidationURL)
• URL for XML Attachment check (-XMLAttachmentURL)
For more information, see “Policies and Expressions.”
To use a variable in the configuration, you enclose the variable name between two at (@) symbols and
then use it exactly as you would the static value that it replaces. For example, if you are configuring
the Deny URL check by using the GUI and want to add the named expression variable myDenyURL to
the configuration, you would type @myDenyURL@ into the Add Deny URL dialog box, Deny URL text
area. To do the same task by using the NetScaler command line, you would type add appfw profile
<name> -denyURLAction @myDenyURL@.

PCRE character encoding format

The NetScaler operating system supports direct entry of characters in the printable ASCII character
set only—characters with hexadecimal codes between HEX 20 (ASCII 32) and HEX 7E (ASCII 127). To
include a character with a code outside that range in your App Firewall configuration, you must enter
its UTF-8 hexadecimal code as a PCRE regular expression.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1736

NetScaler 12.0

A number of character types require encoding using a PCRE regular expression if you include them in
your App Firewall configuration as a URL, form field name, or Safe Object expression. They include:

• Upper-ASCII characters. Characters with encodings from HEX 7F (ASCII 128) to HEX FF (ASCII
255). Depending on the character map used, these encodings can refer to control codes, ASCII
characters with accents or other modifications, non-Latin alphabet characters, and symbols not
included in the basic ASCII set. These characters can appear in URLs, form field names, and safe
object expressions.

• Double-Byte characters. Characters with encodings that use two 8-byte words. Double-byte
characters are used primarily for representing Chinese, Japanese, and Korean text in electronic
format. These characters can appear in URLs, form field names, and safe object expressions.

• ASCII control characters. Non-printable characters used to send commands to a printer. All
ASCII characters with hexadecimal codes less than HEX 20 (ASCII 32) fall into this category. These
characters should never appear in a URL or form field name, however, and would rarely if ever
appear in a safe object expression.

The NetScaler appliance does not support the entire UTF-8 character set, but only the characters
found in the following eight charsets:

• English US (ISO-8859-1). Although the label reads, “English US,” the App Firewall supports all
characters in the ISO-8859-1 character set, also called the Latin-1 character set. This charac-
ter set fully represents most modern western European languages and represents all but a few
uncommon characters in the rest.

• Chinese Traditional (Big5). The App Firewall supports all characters in the BIG5 character set,
which includes all of the Traditional Chinese characters (ideographs) commonly used in modern
Chinese as spoken and written in Hong Kong, Macau, Taiwan, and by many people of Chinese
ethnic heritage who live outside of mainland China.

• Chinese Simplified (GB2312). The App Firewall supports all characters in the GB2312 charac-
ter set, which includes all of the Simplified Chinese characters (ideographs) commonly used in
modern Chinese as spoken and written in mainland China.

• Japanese (SJIS). The App Firewall supports all characters in the Shift-JIS (SJIS) character set,
which includes most characters (ideographs) commonly used in modern Japanese.

• Japanese (EUC-JP). The App Firewall supports all characters in the EUC-JP character set, which
includes all characters (ideographs) commonly used in modern Japanese.

• Korean (EUC-KR). The App Firewall supports all characters in the EUC-KR character set, which
includes all characters (ideographs) commonly used in modern Korean.

• Turkish (ISO-8859-9). The App Firewall supports all characters in the ISO-8859-9 character set,
which includes all letters used in modern Turkish.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1737

NetScaler 12.0

• Unicode (UTF-8). The App Firewall supports certain additional characters in the UTF-8 charac-
ter set, including those used in modern Russian.

When configuring the App Firewall, you enter all non-ASCII characters as PCRE-format regular expres-
sions using the hexadecimal code assigned to that character in the UTF-8 specification. Symbols and
characters within the normal ASCII character set, which are assigned single, two-digit codes in that
character set, are assigned the same codes in the UTF-8 character set. For example, the exclamation
point (!), which is assigned hex code 21 in the ASCII character set, is also hex 21 in the UTF-8 character
set. Symbols and characters from another supported character set have a paired set of hexadecimal
codes assigned to them in the UTF-8 character set. For example, the letter a with an acute accent (á)
is assigned UTF-8 code C3 A1.

The syntax you use to represent these UTF-8 codes in the App Firewall configuration is “xNN” for
ASCII characters; “\xNN\xNN” for non-ASCII characters used in English, Russian, and Turkish; and
“\xNN\xNN\xNN” for characters used in Chinese, Japanese, and Korean. For example, if you want
to represent a ! in an App Firewall regular expression as a UTF-8 character, you would type \x21. If you
want to include an á, you would type \xC3\xA1.

Note:
Normally you do not need to represent ASCII characters in UTF-8 format, but when those charac-
ters might confuse a web browser or an underlying operating system, you can use the character’s
UTF-8 representation to avoid this confusion. For example, if a URL contains a space, you might
want to encode the space as x20 to avoid confusing certain browsers and web server software.

Below are examples of URLs, form field names, and safe object expressions that contain non-ASCII
characters that must be entered as PCRE-format regular expressions to be included in the App Firewall
configuration. Each example shows the actual URL, field name, or expression string first, followed by
a PCRE-format regular expression for it.

• A URL containing extended ASCII characters.

Actual URL: http://www.josénuñez.com

Encoded URL: ^http://www\[.\]jos\xC3\xA9nu\xC3\xB1ez\[.\]com$

• Another URL containing extended ASCII characters.

Actual URL: http://www.example.de/trömso.html

Encoded URL: ^http://www[.]example\[.]de/tr\xC3\xB6mso[.]html$

• A form field name containing extended ASCII characters.

Actual Name: nome_do_usuário

Encoded Name: ^nome_do_usu\xC3\xA1rio$

• A safe object expression containing extended ASCII characters.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1738

NetScaler 12.0

Unencoded Expression [A-Z]{3,6}¥[1-9][0-9]{6,6}

Encoded Expression: [A-Z]{3,6}\xC2\xA5[1-9][0-9]{6,6}
You can find a number of tables that include the entire Unicode character set and matching UTF-8
encodings on the Internet. A useful web site that contains this information is located at the following
URL:

1 http://www.utf8-chartable.de/unicode-utf8-table.pl

For the characters in the table on this web site to display correctly, you must have an appropriate
Unicode font installed on your computer. If you do not, the visual display of the character may be
in error. Even if you do not have an appropriate font installed to display a character, however, the
description and the UTF-8 and UTF-16 codes on this set of web pages will be correct.

Inverted PCRE Expressions

In addition to matching content that contains a pattern, you can match content that does not con-
tain a pattern by using an inverted PCRE expression. To invert an expression, you simply include an
exclamation point (!) followed by white space as the first character in the expression.

Note: If an expression consists only of an exclamation point with nothing following, the exclama-
tion point is treated as a literal character, not syntax indicating an inverted expression.

The following App Firewall commands support inverted PCRE expressions:

• Start URL (URL)
• Deny URL (URL)
• Form Field Consistency (form action URL)
• Cookie Consistency (form action URL)
• Cross Site Request Forgery (CSRF) (form action URL)
• HTML Cross-site Scripting (form action URL)
• Field Format (form action URL)
• Field Type (type)
• Confidential Field (URL)
Note: If the security check contains an isRegex flag or check box, it must be set to YES or checked to
enable regular expressions in the field. Otherwise the contents of that field are treated as literal and
no regular expressions (inverted or not) are parsed.

Disallowed names for App Firewall profiles

The following names are assigned to built-in actions and profiles on the NetScaler appliance, and
cannot be used as names for a user-created App Firewall profile.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1739

NetScaler 12.0

• AGRESSIVE

• ALLOW

• BASIC

• CLIENTAUTH

• COMPRESS

• CSSMINIFY

• DEFLATE

• DENY

• DNS-NOP

• DROP

• GZIP

• HTMLMINIFY

• IMGOPTIMIZE

• JSMINIFY

• MODERATE

• NOCLIENTAUTH

• NOCOMPRESS
• NONE

• NOOP

• NOREWRITE

• RESET

• SETASLEARNNSLOG_ACT

• SETNSLOGPARAMS_ACT

• SETSYSLOGPARAMS_ACT

• SETTMSESSPARAMS_ACT
• SETVPNPARAMS_ACT

• SET_PREAUTHPARAMS_ACT

• default_DNS64_action

• dns_default_act_Cachebypass

• dns_default_act_Drop

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1740

NetScaler 12.0

• nshttp_default_profile

• nshttp_default_strict_validation

• nstcp_default_Mobile_profile

• nstcp_default_XA_XD_profile

• nstcp_default_profile

• nstcp_default_tcp_interactive_stream

• nstcp_default_tcp_lan

• nstcp_default_tcp_lan_thin_stream

• nstcp_default_tcp_lfp

• nstcp_default_tcp_lfp_thin_stream

• nstcp_default_tcp_lnp

• nstcp_default_tcp_lnp_thin_stream

• nstcp_internal_apps

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Policy labels

September 18, 2018

Contributed by:
C

A policy label consists of a set of policies, other policy labels, and virtual server-specific policy banks.
The App Firewall evaluates each policy bound to the policy label in order of priority. If the policy
matches, it filters the connection as specified in the associated profile. Then it does whatever the
Goto parameter specifies, which can be to terminate policy evaluation, go to the next policy, or go to
the policy with the specified priority. If the Invoke parameter is set, it terminates processing of the
current policy label and begins to process the specified policy label or virtual server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1741

NetScaler 12.0

To create an App Firewall policy label by using the command line

At the command prompt, type the following commands:

• add appfw policylabel <labelName> http_req

• save ns config

Example

The following example creates a policy label named policylbl1.

1 add appfw policylabel policylbl1 http_req

2 save ns config

To bind a policy to a policy label by using the command line

At the command prompt, type the following commands:

• bind appfw policylabel <labelName> <policyName> <priority> [<gotoPriorityExpressi

>] [-invoke (<labelType> <labelName>)]
• save ns config

Example

The following example binds the policy policy1 to the policy label policylbl1 with a priority of 1.

1 bind appfw policylabel policylbl1 policy1 1

2 save ns config

To configure an App Firewall policy label by using the GUI

1. Navigate to Security > Application Firewall > Policy Labels.

2. In the details pane, do one of the following:

• To add a new policy label, click Add.

• To configure an existing policy label, select the policy label and the click Open.

The Create App Firewall Policy Label or the Configure App Firewall Policy Label dialog box
opens. The dialog boxes are nearly identical.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1742

NetScaler 12.0

3. If you are creating a new policy label, in the Create App Firewall Policy Label dialog box, type a
name for your new policy label.

The name can begin with a letter, number, or the underscore symbol, and can consist of from
one to 127 letters, numbers, and the hyphen (-), period (.) pound (#), space ( ), at (@), equals (=),
colon (:), and underscore (_) symbols.

4. Select **Insert Policy **to insert a new row and display a drop-down list with all existing App
Firewall policies.

5. Select the policy you want to bind to the policy label, or select New Policy to create a new policy
and follow the instructions in To create and configure a policy by using the GUI. The policy that
you selected or created is inserted into the list of globally bound App Firewall policies.

6. Make any additional adjustments.

• To modify the policy priority, click the field to enable it, and then type a new priority. You
can also select Regenerate Priorities to renumber the priorities evenly.
• To modify the policy expression, double click that field to open the Configure App Firewall
Policy dialog box, where you can edit the policy expression.
• To set the Goto Expression, double click field in the Goto Expression column heading to
display the drop-down list, where you can choose an expression.
• To set the Invoke option, double click field in the Invoke column heading to display the
drop-down list, where you can choose an expression

7. Repeat steps 5 through 7 to bind any additional App Firewall policies you want to the policy
label.

8. Click Create or OK, and then click Close. A message appears in the status bar, stating that you
have successfully created or modified the policy label.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Policies

September 18, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1743

NetScaler 12.0

The App Firewall uses two types of policies: firewall policies and auditing policies. Firewall policies
control which traffic is sent to the App Firewall. Auditing policies control the log server to which App
Firewall logs are sent.

Firewall policies can be complex because the policy rule can consist of multiple expressions in the
NetScaler expressions language, which is a full-fledged object oriented programming language capa-
ble of defining with extreme precision exactly which connections to filter. Because firewall policies
operate within the context of the App Firewall, they must meet certain criteria that are connected to
how the App Firewall functions and what traffic is appropriately filtered by it. As long as you keep
these criteria in mind, however, firewall policies are similar to policies for other NetScaler features.
The instructions here do not attempt to cover all aspects of writing firewall policies, but only provide
an introduction to policies and cover those criteria that are unique to the App Firewall.

Auditing policies are simple because the policy rule is always ns_true. You need only specify the log
server that you want to send logs to, the logging levels that you want to use, and a few other criteria
that are explained in detail.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

App Firewall Policies

September 18, 2018

Contributed by:
C

A firewall policy is a rule associated with a profile. The rule is an expression or group of expressions
that define the types of request/response pairs that the App Firewall is to filter by applying the profile.
Firewall policy expressions are written in the NetScaler expressions language, an object-oriented pro-
gramming language with special features to support specific NetScaler functions. The profile is the
set of actions that the App Firewall is to use to filter request/response pairs that match the rule.

Firewall policies enable you to assign different filtering rules to different types of web content. Not
all web content is alike. A simple web site that uses no complex scripting and accesses and handles
no private data might require only the level of protection provided by a profile created with basic
defaults. Web content that contains JavaScript-enhanced web forms or accesses an SQL database
probably requires more tailored protection. You can create a different profile to filter that content
and create a separate firewall policy that can determine which requests are attempting to access that

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1744

NetScaler 12.0

content. You then associate the policy expression with a profile you created and globally bind the
policy to put it into effect.

The App Firewall processes only HTTP connections, and therefore uses a subset of the overall
NetScaler expressions language. The information here is limited to topics and examples that are
likely to be useful when configuring the App Firewall. Following are links to additional information
and procedures for firewall policies:

• For procedures that explain how to create and configure a policy, see Creating and Configuring
App Firewall Policies.
• For a procedure that explains in detail how to create a policy rule (expression), see To create or
configure an App Firewall rule (expression).
• For a procedure that explains how to use the Add Expression dialog box to create a policy rule,
see To add a firewall rule (expression) by using the Add Expression dialog box.
• For a procedure that explains how to view the current bindings for a policy, see Viewing a Fire-
wall Policy’s Bindings.
• For procedures that explain how to bind an App Firewall policy, see Binding App Firewall Poli-
cies.
• For detailed information about the NetScaler expressions language, see Policies and Expres-
sions.
Note

App Firewall evaluates the policies based on the configured priority and goto expressions. At
the end of the policy evaluation, the last policy that evaluates to true is used and the security
configuration of the corresponding profile is invoked for processing the request.

For example, Consider a scenario where there are 2 policies.

• Policy_1 is a generic policy with Expression=ns_true and has a corresponding profile_1

which is a basic profile. The priority is set to 100.
• Policy_2 is more specific with Expression=HTTP.REQ.URL.CONTAINS(“XYZ”) and has a cor-
responding profile_2 which is an advance profile. The GoTo Expression is set to NEXT and
the priority is set to 95 which is a higher priority compared to Policy_1.

In this scenario, if the target string “XYZ” is detected in the URL of the processed request, Policy_2
match is triggered as it has a higher priority even though Policy_1 is also a match. However, as
per the GoTo expression configuration of Policy_2, the policy evaluation continues and the next
policy Policy_1 is also processed. At the end of the policy evaluation, Policy_1 evaluates as true
and the basic security checks configured in Profile_1 are invoked.

If the Policy_2 is modified and the GoTo Expression is changed from

NEXT to
END, the processed request that has the target string “XYZ”, triggers the Policy_2 match due to

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1745

NetScaler 12.0

priority consideration and as per the GoTo expression configuration, the policy evaluation ends
at this point. Policy_2 evaluates as true and the advanced security checks configured in Profile_2
are invoked.

NEXT
END

Policy evaluation is completed in one pass. Once the policy evaluation is completed for the re-
quest and the corresponding profile actions are invoked, the request does not go through an-
other round of policy evaluation.
1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Creating and configuring App Firewall policies

November 14, 2018

Contributed by:
C

A firewall policy consists of two elements: a rule, and an associated profile. The rule selects the HTTP
traffic that matches the criteria that you set, and sends that traffic to the App Firewall for filtering. The
profile contains the filtering criteria that the App Firewall uses.

The policy rule consists of one or more expressions in the NetScaler expressions language. The
NetScaler expressions syntax is a powerful, object-oriented programming language that enables you
to precisely designate the traffic that you want to process with a specific profile. For users who are
not completely familiar with the NetScaler expressions language syntax, or who prefer to configure
their NetScaler appliance by using a web-based interface, the GUI provides two tools: the Prefix
menu and the Add Expression dialog box. Both help you to write expressions that select exactly the
traffic that you want to process. Experienced users who are thoroughly familiar with the syntax may
prefer to use the NetScaler command line to configure their NetScaler appliances.

Note: In addition to the default expressions syntax, for backward compatibility the NetScaler op-
erating system supports the NetScaler classic expressions syntax on NetScaler Classic and nCore
appliances and virtual appliances. Classic expressions are not supported on NetScaler Cluster
appliances and virtual appliances. Current NetScaler users who want to migrate existing config-

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1746

NetScaler 12.0

urations to the NetScaler Cluster must migrate any policies that contain classic expressions to
the default expressions syntax.

For detailed information about the NetScaler expressions languages, see “Policies and Expressions.”
You can create a firewall policy by using the GUI or the NetScaler command line.

To create and configure a policy by using the command line interface

At the command prompt, type the following commands:

• add appfw policy <name><rule> <profileName>
• save ns config

Example

The following example adds a policy named pl-blog, with a rule that intercepts all traffic to or from
the host blog.example.com, and associates that policy with the profile pr-blog. This is an appropriate
policy to protect a blog hosted on a specific hostname.

1 add appfw policy pl-blog ”HTTP.REQ.HOSTNAME.DOMAIN.EQ(”blog.example.com

”)” pr-blog

To create and configure a policy by using the GUI

1. Navigate to Security > App Firewall > Policies.

2. In the details pane, do one of the following:
• To create a new firewall policy, click Add. The Create App Firewall Policy is displayed.
• To edit an existing firewall policy, select the policy, and then click Edit.
The Create App Firewall Policy or Configure App Firewall Policy is displayed.
3. If you are creating a new firewall policy, in the Create App Firewall Policy dialog box, Policy
Name text box, type a name for your new policy.
The name can begin with a letter, number, or the underscore symbol, and can consist of from
one to 128 letters, numbers, and the hyphen (-), period (.) pound (#), space ( ), at (@), equals (=),
colon (:), and underscore (_) symbols.
If you are configuring an existing firewall policy, this field is read-only. You cannot modify it.
4. Select the profile that you want to associate with this policy from the Profile drop-down list. You
can create a new profile to associate with your policy by clicking New, and you can modify an
existing profile by clicking Modify.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1747

NetScaler 12.0

5. In the Expression text area, create a rule for your policy.

• You can type a rule directly into the text area.

• You can click Prefix to select the first term for your rule, and follow the prompts.
• You can click Add to open the Add Expression dialog box, and use it to construct the rule.

6. Click Create or OK, and then click Close.

To create or configure an App Firewall rule

The policy rule, also called the expression, defines the web traffic that the App Firewall filters by using
the profile associated with the policy. Like other NetScaler policy rules (or expressions), App Firewall
rules use NetScaler expressions syntax. This syntax is powerful, flexible, and extensible. It is too com-
plex to describe completely in this set of instructions. You can use the following procedure to create
a simple firewall policy rule, or you can read it as an overview of the policy creation process.

1. If you have not already done so, navigate to the appropriate location in the App Firewall wizard
or the NetScaler GUI to create your policy rule:

• If you are configuring a policy in the App Firewall wizard, in the navigation pane, click
App Firewall, then in the details pane click App Firewall Wizard, and then navigate to the
Specify Rule screen.
• If you are configuring a policy manually, in the navigation pane, expand App Firewall,
then Policies, and then Firewall. In the details pane, to create a new policy, click Add. To
modify an existing policy, select the policy, and then click Open.

2. On the Specify Rule screen, the Create App Firewall Profile dialog box, or the Configure App
Firewall Profile dialog box, click Prefix, and then choose the prefix for your expression from
the drop-down list. Your choices are:

• HTTP. The HTTP protocol. Choose this if you want to examine some aspect of the request
that pertains to the HTTP protocol.
• SYS. The protected Web site(s). Choose this if you want to examine some aspect of the
request that pertains to the recipient of the request.
• CLIENT. The computer that sent the request. Choose this if you want to examine some
aspect of the sender of the request.
• SERVER. The computer to which the request was sent. Choose this if you want to examine
some aspect of the recipient of the request.

After you choose a prefix, the App Firewall displays a two-part prompt window that displays the
possible next choices at the top, and a brief explanation of what the selected choice means at
the bottom.

3. Choose your next term.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1748

NetScaler 12.0

If you chose HTTP as your prefix, your only choice is REQ, which specifies the Request/Response
pair. (The App Firewall operates on the request and response as a unit instead of on each sepa-
rately.) If you chose another prefix, your choices are more varied. For help on a specific choice,
click that choice once to display information about it in the lower prompt window.

When you have decided which term you want, double-click it to insert it into the Expression
window.

4. Type a period after the term you just chose. You are then prompted to choose your next term, as
described in the previous step. When a term requires that you type a value, fill in the appropriate
value. For example, if you choose HTTP.REQ.HEADER(“”), type the header name between the
quotation marks.

5. Continue choosing terms from the prompts and filling in any values that are needed, until your
expression is finished.

Following are some examples of expressions for specific purposes.

• Specific web host. To match traffic from a particular web host:

1 HTTP.REQ.HEADER(”Host”).EQ(”shopping.example.com”)

For shopping.example.com, substitute the name of the web host that you want to match.

• Specific web folder or directory. To match traffic from a particular folder or directory on
a Web host:

1 HTTP.REQ.URL.STARTSWITH(”https//www.example.com/folder”)

For www.example.com, substitute the name of the web host. For folder, substitute the
folder or path to the content that you want to match. For example, if your shopping cart is
in a folder called /solutions/orders, you substitute that string for folder.

• Specific type of content: GIF images. To match GIF format images:

1 HTTP.REQ.URL.ENDSWITH(”.gif”)

To match other format images, substitute another string in place of .gif.

• Specific type of content: scripts. To match all CGI scripts located in the CGI-BIN directory:

1 HTTP.REQ.URL.STARTSWITH(”https//www.example.com/CGI-BIN”)

To match all JavaScripts with .js extensions:

1 HTTP.REQ.URL.ENDSWITH(”.js”)

For more information about creating policy expressions, see “Policies and Expressions.”

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1749

NetScaler 12.0

Note: If you use the command line to configure a policy, remember to escape any double
quotation marks within NetScaler expressions. For example, the following expression is
correct if entered in the GUI:

1 HTTP.REQ.HEADER(”Host”).EQ(”shopping.example.com”)

If entered at the command line, however, you must type this instead:

1 HTTP.REQ.HEADER(”Host”).EQ(”shopping.example.com”)

To add a firewall rule (expression) by using the Add Expression dialog box

The Add Expression dialog box (also referred to as the Expression Editor) helps users who are not fa-
miliar with the NetScaler expressions language to construct a policy that matches the traffic that they
want to filter.

1. If you have not already done so, navigate to the appropriate location in the App Firewall wizard
or the NetScaler GUI:
• If you are configuring a policy in the App Firewall wizard, in the navigation pane, click
App Firewall, then in the details pane click App Firewall Wizard, and then navigate to the
Specify Rule screen.
• If you are configuring a policy manually, in the navigation pane, expand App Firewall,
then Policies, and then Firewall. In the details pane, to create a new policy, click Add. To
modify an existing policy, select the policy, and then click Open.
2. On the Specify Rule screen, in the Create App Firewall Profile dialog box, or in the Configure
App Firewall Profile dialog box, click Add.
3. In the Add Expression dialog box, in the Construct Expression area, in the first list box, choose
one of the following prefixes:
• HTTP. The HTTP protocol. Choose this if you want to examine some aspect of the request
that pertains to the HTTP protocol. The default choice.
• SYS. The protected Web site(s). Choose this if you want to examine some aspect of the
request that pertains to the recipient of the request.
• CLIENT. The computer that sent the request. Choose this if you want to examine some
aspect of the sender of the request.
• SERVER. The computer to which the request was sent. Choose this if you want to examine
some aspect of the recipient of the request.
4. In the second list box, choose your next term. The available terms differ depending on the choice
you made in the previous step, because the dialog box automatically adjusts the list to contain
only those terms that are valid for the context. For example, if you selected HTTP in the previ-
ous list box, the only choice is REQ, for requests. Because the App Firewall treats requests and

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1750

NetScaler 12.0

associated responses as a single unit and filters both, you do not need to specific responses
separately. After you choose your second term, a third list box appears to the right of the sec-
ond. The Help window displays a description of the second term, and the Preview Expression
window displays your expression.
5. In the third list box, choose the next term. A new list box appears to the right, and the Help
window changes to display a description of the new term. The Preview Expression window
updates to display the expression as you have specified it to that point.
6. Continue choosing terms, and when prompted filling in arguments, until your expression is com-
plete. If you make a mistake or want to change your expression after you have already selected
a term, you can simply choose another term. The expression is modified, and any arguments or
additional terms that you added after the term that you modified are cleared.
7. When you have finished constructing your expression, click OK to close the Add Expression
dialog box. Your expression is inserted into the Expression text area.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Binding App Firewall policies

September 18, 2018

Contributed by:
C

After you have configured your App Firewall policies, you bind them to Global or a bind point to put
them into effect. After binding, any request or response that matches an App Firewall policy is trans-
formed by the profile associated with that policy.

When you bind a policy, you assign a priority to it. The priority determines the order in which the
policies you define are evaluated. You can set the priority to any positive integer. In the NetScaler OS,
policy priorities work in reverse order - the higher the number, the lower the priority.

Because the App Firewall feature implements only the first policy that a request matches, not any
additional policies that it might also match, policy priority is important for achieving the results that
you intend. If you give your first policy a low priority (such as 1000), you configure the App Firewall
to perform it only if other policies with a higher priority do not match a request. If you give your first
policy a high priority (such as 1), you configure the App Firewall to perform it first, and skip any other
policies that might also match. You can leave yourself plenty of room to add other policies in any

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1751

NetScaler 12.0

order, without having to reassign priorities, by setting priorities with intervals of 50 or 100 between
each policy when you bind your policies.

For more information about binding policies on the NetScaler appliance, see “Policies and Expres-
sions.”

To bind an App Firewall policy by using the command line interface

At the command prompt, type the following commands:

• bind appfw global <policyName>

• save ns config
• bind appfw profile <profile_name> -crossSiteScripting data

Example

The following example binds the policy named pl-blog and assigns it a priority of 10.

1 bind appfw global pl-blog 10 save ns config

To bind an App Firewall policy by using the GUI

1. Do one of the following:

• Navigate to Security > App Firewall, and in the details pane, click App Firewall policy man-
ager.
• Navigate to Security > App Firewall > Policies > Firewall Policies, and in the details pane,
click Policy Manager.
2. In the App Firewall Policy Manager dialog, choose the bind point to which you want to bind
the policy from the drop-down list. The choices are:
• Override Global. Policies that are bound to this bind point process all traffic from all in-
terfaces on the NetScaler appliance, and are applied before any other policies.
• LB Virtual Server. Policies that are bound to a load balancing virtual server are applied
only to traffic that is processed by that load balancing virtual server, and are applied be-
fore any Default Global policies. After selecting LB Virtual Server, you must also select the
specific load balancing virtual server to which you want to bind this policy.
• CS Virtual Server. Policies that are bound to a content switching virtual server are applied
only to traffic that is processed by that content switching virtual server, and are applied
before any Default Global policies. After selecting CS Virtual Server, you must also select
the specific content switching virtual server to which you want to bind this policy.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1752

NetScaler 12.0

• Default Global. Policies that are bound to this bind point process all traffic from all inter-
faces on the NetScaler appliance.
• Policy Label. Policies that are bound to a policy label process traffic that the policy label
routes to them. The policy label controls the order in which policies are applied to this
traffic.
• None. Do not bind the policy to any bind point.
3. Click Continue. A list of existing App Firewall policies appears.
4. Select the policy you want to bind by clicking it.
5. Make any additional adjustments to the binding.
• To modify the policy priority, click the field to enable it, and then type a new priority. You
can also select Regenerate Priorities to renumber the priorities evenly.
• To modify the policy expression, double click that field to open the Configure App Fire-
wall Policy dialog box, where you can edit the policy expression.
• To set the Goto Expression, double click field in the Goto Expression column heading to
display the drop-down list, where you can choose an expression.
• To set the Invoke option, double click field in the Invoke column heading to display the
drop-down list, where you can choose an expression
6. Repeat steps 3 through 6 to add any additional App Firewall policies you want to globally bind.
7. Click OK. A message appears in the status bar, stating that the policy has been successfully
bound.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Viewing a policy bindings

September 18, 2018

Contributed by:
C

You can quickly check to determine what bindings are in place for any firewall policy by viewing the
bindings in the GUI.

To view bindings for an App Firewall policy

1. Navigate to Security > Application Firewall > Policies > Firewall Policies

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1753

NetScaler 12.0

2. In the details pane, select the policy that you want to check, and then click Show Bindings. The
Binding Details for Policy: Policy message box is displayed, with a list of bindings for the selected
policy.
3. Click Close.
1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Supplemental information about App Firewall policies

September 18, 2018

Contributed by:
C
Following is supplemental information about particular aspects of App Firewall policies that system
administrators who manage the App Firewall might need to know.

Correct but unexpected behavior

Web application security and modern web sites are complex. In a number of scenarios, a NetScaler
policy might cause the App Firewall to behave differently in certain situations than a user who is fa-
miliar with policies would normally expect. Following are a number of cases where the App Firewall
may behave in an unexpected fashion.
• Request with a missing HTTP Host header and an absolute URL. When a user sends a request,
in the majority of cases the request URL is relative. That is, it takes as its starting point the Ref-
erer URL, the URL where the user’s browser is located when it sends the request. If a request
is sent without a Host header, and with a relative URL, the request is normally blocked both
because it violates the HTTP specification and because a request that fails to specify the host
could under some circumstances constitute an attack. If a request is sent with an absolute URL,
however, even if the Host header is missing, the request bypasses the App Firewall and is for-
warded to the web server. Although such a request violates the HTTP specification, it poses no
possible threat because an absolute URL contains the host.
1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1754

NetScaler 12.0

Auditing policies

September 18, 2018

Contributed by:
C

Auditing policies determine the messages that are generated and logged during an App Firewall ses-
sion. These messages are logged in SYSLOG format to the local NSLOG server or to an external logging
server. Different types of messages are logged on the basis of the level of logging selected.

To create an auditing policy, you must first create either an NSLOG server or a SYSLOG server. After
specifying the server, you create the policy and specify the type of log and the server to which logs are
sent.

To create an auditing server by using the command line interface

You can create two different types of auditing server: an NSLOG server or a SYSLOG server. The com-
mand names are different, but the parameters for the commands are the same.

To create an auditing server, at the command prompt, type the following commands:

• add audit syslogAction <name> <serverIP> [-serverPort <port>] -logLevel

<logLevel> ... [-dateFormat ( **MMDDYYYY** | **DDMMYYYY** )] [-logFacility
<logFacility>] [-tcp ( **NONE** | **ALL** )] [-acl ( **ENABLED**
| **DISABLED** )] [-timeZone ( **GMT_TIME** | **LOCAL_TIME** )] [-
userDefinedAuditlog ( **YES** | **NO** )] [-appflowExport ( **ENABLED**
| **DISABLED** )]
• save ns config

Example

The following example creates a syslog server named syslog1 at IP 10.124.67.91, with loglevels of emer-
gency, critical, and warning, log facility set to LOCAL1, that logs all TCP connections:

1 add audit syslogAction syslog1 10.124.67.91 -logLevel emergency

critical warning -logFacility
2 LOCAL1 -tcp ALL
3 save ns config

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1755

NetScaler 12.0

To modify or remove an auditing server by using the command line interface

• To modify an auditing server, type the set audit <type> command, the name of the auditing
server, and the parameters to be changed, with their new values.
• To remove an auditing server, type the rm audit <type> command and the name of the auditing
server.

Example

The following example modifies the syslog server named syslog1 to add errors and alerts to the log
level:

1 set audit syslogAction syslog1 10.124.67.91 -logLevel emergency

critical warning alert error
2 -logFacility LOCAL1 -tcp ALL
3 save ns config

To create or configure an auditing server by using the GUI

1. Navigate to Security > Firewall > Policies > Auditing.

2. In the details pane, clickApplication the Server tab.
3. Do one of the following:
• To add a new auditing server, click Add.
• To modify an existing auditing server, select the server, and then click Edit.
4. In the Create Auditing Server or Configure Auditing Server dialog box, set the following pa-
rameters:
• Name
• Auditing Type
• IP Address
• Port
• Log Levels
• Log Facility
• TCP Logging
• ACL Logging
• User-Configurable Log Messages
• AppFlow Logging
• Date Format
• Time Zone
5. Click Create or OK.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1756

NetScaler 12.0

To create an auditing policy by using the command line interface

You can create an NSLOG policy or a SYSLOG policy. The type of policy must match the type of server.
The command names for the two types of policy are different, but the parameters for the commands
are the same.

At the command prompt, type the following commands:

• add audit syslogPolicy <name> <-rule > <action>

• save ns config

Example

The following example creates a policy named syslogP1 that logs App Firewall traffic to a syslog server
named syslog1.

1 add audit syslogPolicy syslogP1 rule ”ns_true” action syslog1

2 save ns config

To configure an auditing policy by using the command line interface

At the command prompt, type the following commands:

• set audit syslogPolicy <name> [-rule <expression>] [-action <string>]

• save ns config

Example

The following example modifies the policy named syslogP1 to log App Firewall traffic to a syslog server
named syslog2.

1 set audit syslogPolicy syslogP1 rule ”ns_true” action syslog2

2 save ns config

To configure an auditing policy by using the GUI

1. Navigate to Security > Application Firewall > Policies > Auditing.

2. In the details pane, do one of the following:
• To add a new policy, click Add.
• To modify an existing policy, select the policy, and then click Edit.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1757

NetScaler 12.0

3. In the Create Auditing Policy or Configure Auditing Policy dialog box, set the following param-
eters:
• Name
• Auditing Type
• Server
4. Click Create or OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Imports

September 18, 2018

Contributed by:
C

Several App Firewall features make use of external files that you upload to the App Firewall when con-
figuring it. Using the GUI, you manage those files in the Imports pane, which has four tabs correspond-
ing to the four types of files you can import: HTML error objects, XML error objects, XML schemas, and
Web Services Description Language (WSDL) files. Using the NetScaler command line, you can import
these types of files, but you cannot export them.

HTML error object

When a user’s connection to an HTML or Web 2.0 page is blocked, or a user asks for a non-existent
HTML or Web 2.0 page, the App Firewall sends an HTML-based error response to the user’s browser.
When configuring which error response the App Firewall should use, you have two choices:

• You can configure a redirect URL, which can be hosted on any Web server to which users also
have access. For example, if you have a custom error page on your Web server, 404.html, you
can configure the App Firewall to redirect users to that page when a connection is blocked.
• You can configure an HTML error object, which is an HTML-based Web page that is hosted on
the App Firewall itself. If you choose this option, you must upload the HTML error object to the
App Firewall. You do that in the Imports pane, on the HTML Error Object tab.

The error object must be a standard HTML file that contains no non-HTML syntax except for App Fire-
wall error object customization variables. It cannot contain any CGI scripts, server-parsed code, or

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1758

NetScaler 12.0

PHP code. The customization variables enable you to embed troubleshooting information in the er-
ror object that the user receives when a request is blocked. While most requests that the App Firewall
blocks are illegitimate, even a properly configured App Firewall can occasionally block legitimate re-
quests, especially when you first deploy it or after you make significant changes to your protected Web
sites. By embedding information in the error page, you provide the user with the information that he
or she needs to give to the technical support person so that any issues can be fixed.
The App Firewall error page customization variables are:
• ${NS_TRANSACTION_ID}. The transaction ID that the App Firewall assigned to this transaction.
• ${NS_APPFW_SESSION_ID}. The App Firewall session ID.
• ${NS_APPFW_VIOLATION_CATEGORY}. The specific App Firewall security check or rule that was
violated.
• ${NS_APPFW_VIOLATION_LOG}. The detailed error message associated with the violation.
• ${COOKIE The contents of the specified cookie. For <CookieName>, substitute the name of
the specific cookie that you want to display on the error page. If you have multiple cookies
whose contents you want to display for troubleshooting, you can use multiple instances of this
customization variable, each with the appropriate cookie name.
Note: If you have blocking enabled for the Cookie Consistency Check, any blocked cookies are
not displayed on the error page because the App Firewall blocks them.
To use these variables, you embed them in the HTML or XML of the error page object as if they were
an ordinary text string. When the error object is displayed to the user, for each customization variable
the App Firewall substitutes the information to which the variable refers. An example HTML error page
that uses custom variables is shown below.

1 <!doctype html public ”-//w3c//dtd html 4.0//en”> <html> <head> <

title>Page Not Accessible</title> </head> <body> <h1>Page Not
Accessible</h1> <p>The page that you accessed is not available. You
can:</p> <ul> <li>return to the <b><a href=”[homePage]”>home page
</a></b>, re-establish your session, and try again, or,</li> <li>
report this incident to the help desk via <b><a href=”mailto:[
helpDeskEmailAddress]”>email</a></b> or by calling [
helpDeskPhoneNumber].</li> </ul> <p>If you contact the help desk,
please provide the following information:</p> <table cellpadding=8
width=80%> <tr><th align=”right” width=30%>Transaction ID:</th><td
align=”left” valign=”top” width=70%>${
2 NS_TRANSACTION_ID }
3 </td></tr> <tr><th align=”right” width=30%>Session ID:</th><td align=
”left” valign=”top” width=70%>${
4 NS_APPFW_SESSION_ID }
5 </td></tr> <tr><th align=”right” width=30%>Violation Category:</th><
td align=”left” valign=”top” width=70%>${

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1759

NetScaler 12.0

6 NS_APPFW_VIOLATION_CATEGORY }
7 </td></tr> <tr><th align=”right” width=30%>Violation Log:</th><td
align=”left” valign=”top” width=70%>${
8 NS_APPFW_VIOLATION_LOG }
9 </td></tr> <tr><th align=”right” width=30%>Cookie Name:</th><td align
=”left” valign=”top” width=70%>${
10 COOKIE(”[cookieName]”) }
11 </td></tr> </table> <body> <html>

To use this error page, copy it into a text or HTML editor. Substitute the appropriate local informa-
tion for the following variables, which are enclosed in square brackets to distinguish them from the
NetScaler variables. (Leave those unchanged.):

• [homePage]. The URL for your web site’s home page.

• [helpDeskEmailAddress]. The email address that you want users to use to report blocking
incidents.
• [helpDeskPhoneNumber]. The phone number that you want users to call to report blocking
incidents.
• [cookieName]. The name of the cookie whose contents you want to display on the error page.

XML error object

When a user’s connection to an XML page is blocked, or a user asks for a nonexistent XML application,
the App Firewall sends an XML-based error response to the user’s browser. You configure the error
response by uploading an XML-based error page to the App Firewall in the Imports Pane, on the XML
Error Object tab. All XML error responses are hosted on the App Firewall. You cannot configure a
redirect URL for XML applications.

Note:
You can use the same customization variables in an XML error object as in an HTML error object.

XML Schema

When the App Firewall performs a validation check on a user’s request for an XML or Web 2.0 appli-
cation, it can validate the request against the XML schema or design type document (DTD) for that
application and reject any request that does not follow the schema or DTD. Both an XML schema and
a DTD are standard XML configuration files that describe the structure of a specific type of XML docu-
ment.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1760

NetScaler 12.0

WSDL

When the App Firewall performs a validation check on a user’s request for an XML SOAP-based web
service, it can validate the request against the web services type definition (WSDL) file for that web
service. A WSDL file is a standard XML SOAP configuration file that defines the elements of a specific
XML SOAP web service.
1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Importing and exporting files

September 18, 2018

Contributed by:
C
You can import HTML or XML error objects, XML schemas, DTDs, and WSDLs to the App Firewall by
using the GUI or the command line. You can edit any of these files in a web-based text area after
importing them, to make small changes directly on the NetScaler instead of having to make them on
your computer and then reimport them. Finally, you can export any of these files to your computer,
or delete any of these files, by using the GUI.

Note: You cannot delete or export an imported file by using the command line.

To import a file by using the command line interface

At the command prompt, type the following commands:

• import appfw htmlerrorpage <src> <name>
• <save> ns config

Example

The following example imports an HTML error object from a file named error.html and assigns it the
name HTMLError.

1 import htmlerrorpage error.html HTMLError

2 save ns config

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1761

NetScaler 12.0

To import a file by using the GUI

Before you attempt to import an XML schema, DTD, or WSDL file, or an HTML or XML error object from
a network location, verify that the NetScaler can connect to the Internet or LAN computer where the
file is located. Otherwise, you cannot import the file or object.
1. Navigate to Security > Application Firewall > Imports.
2. Navigate to Application Firewall > Imports.
3. In the Application Firewall Imports pane, select the tab for the type of file you want to import,
and then click Add.
The tabs are HTML Error Page, XML Error Page, XML Schema or WSDL. The upload process is
identical on all four tabs from the user point of view.
4. Fill in the dialog fields.
• Name—A name for the imported object.
• Import From—Choose the location of the HTML file, XML file, XML schema or WSDL that
you want to import in the drop-down list:
– URL: A web URL on a website accessible to the appliance.
– File: A file on a local or networked hard disk or other storage device.
– Text: Type or paste the text of the custom response directly into a text field in the GUI.
The third text box changes to the appropriate value. The three possible values are provided
below.
• URL—Type the URL into the text box.
• File—Type the path and filename to the HTML file directly, or click Browse and browse to
the HTML file.
• Text—The third field is removed, leaving a blank space.
5. Click Continue. The File Contents dialog is displayed. If you chose URL or File, the File Contents
text box contains the HTML file that you specified. If you chose Text, the File Contents text box
is empty.
6. If you chose Text, type or copy and paste the custom response HTML that you want to import.
7. Click Done.
8. To delete an object, select the object, and then click Delete.

To export a file by using the GUI

Before you attempt to export an XML schema, DTD, or WSDL file, or an HTML or XML error object, verify
that the App Firewall appliance can access the computer where the file is to be saved. Otherwise, you

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1762

NetScaler 12.0

cannot export the file.

1. Navigate to Security > App Firewall > Imports.

2. In the App Firewall Imports pane, select the tab for the type of file you want to export.

The export process is identical on all four tabs from the user point of view.

3. Select the file that you want to export.

4. Expand the Action drop-down list, and select Export.

5. In the dialog box, choose Save File and click OK.

6. In the Browse dialog box, navigate to the local file system and directory where you want to save
the exported file, and click Save.

To edit an HTML or XML Error Object in the GUI

You edit the text of HTML and XML error objects in the GUI without exporting and then reimporting
them.

1. Navigate to Security > Application Firewall > Imports, and then select the tab for the type of
file that you want to modify.

2. Navigate to Application Firewall > Imports, and then select the tab for the type of file that you
want to modify.

3. Select the file that you want to modify, and then click Edit.

The text of the HTML or XML error object is displayed in a browser text area. You can modify the
text by using the standard browser-based editing tools and methods for your browser.

Note: The edit window is designed to allow you to make minor changes to your HTML or XML
error object. To make extensive changes, you may prefer to export the error object to your local
computer and use standard HTML or XML web page editing tools.

4. Click OK, and then click Close.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Global configuration

September 18, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1763

NetScaler 12.0

Contributed by:
C

The App Firewall global configuration affects all profiles and policies. The Global Configuration items
are:

• Engine Settings. A collection of global settings—session cookie name, session time-out, maxi-
mum session lifetime, logging header name, undefined profile, default profile, and import size
limit—that pertain to all connections that the App Firewall processes, rather than to a specific
subset of connections.
• Confidential Fields. A set of form fields in web forms that contain sensitive information that
should not be logged to the App Firewall logs. Form fields such as password fields on a logon
page or credit card information on a shopping cart checkout form are normally designated as
confidential fields.
• Field Types. The list of web form field types used by the Field Formats security check. Each of
these field types is defined by a PCRE-compliant regular expression that defines the type of data
and the minimum/maximum length of data that should be allowed in that type of form field.
• XML Content Types. The list of content types recognized as XML and subjected to XML-specific
security checks. Each of these content types is defined by a PCRE-compliant regular expression
that defines the exact MIME type assigned to that content.
• JSON Content Types. The list of content types recognized as JSON and subjected to JSON-
specific security checks. Each of these content types is defined by a PCRE-compliant regular
expression that defines the exact MIME type assigned to that content.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Engine settings

September 20, 2018

Contributed by:
C

The engine settings affect all requests and responses that the App Firewall processes. They include
the following items:

• Cookie name—The name of the cookie that stores the NetScaler session ID.
• Session timeout—The maximum inactive period allowed. If a user session shows no activity for
this length of time, the session is terminated and the user is required to reestablish it by visiting

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1764

NetScaler 12.0

a designated start page.

• Cookie post-encrypt prefix—The string that precedes the encrypted portion of any encrypted
cookies.
• Maximum session lifetime—The maximum amount of time, in seconds, that a session is al-
lowed to remain live. After this period is reached, the session is terminated and the user is re-
quired to reestablish it by visiting a designated start page. This setting cannot be less then the
session timeout. To disable this setting, so that there is no maximum session lifetime, set the
value to zero (0).
• Logging header name—The name of the HTTP header that holds the Client IP, for logging.
• Undefined profile—The profile applied when the corresponding policy action evaluates as un-
defined.
• Default profile—The profile applied to connections that do not match a policy.
• Import size limit—The maximum cumulative total byte count of all files imported to the appli-
ance, including signatures, WSDLs, schemas, HTML and XML error pages. During an import, if
the size of the imported object would cause the cumulative total sizes of all imported files to
exceed the configured limit, the import operation fails and the appliance displays the following
error message: ERROR: Import failed - exceeding the configured total size limit on the imported
objects.
• Learn message rate limit—The maximum number of requests and responses per second that
the learning engine is to process. Any additional requests or responses over this limit are not
sent to the learning engine.
• Entity decoding—Decode HTML entities when running App Firewall checks.
• Log malformed request—Enable logging of malformed HTTP requests.
• Use configurable secret key—Use a configurable secret key for App Firewall operations.
• Reset learned data—Remove all learned data from the App Firewall. Restarts the learning pro-
cess by collecting fresh data.
Two settings, Reset Learned Data and Signatures Auto-Update, are found in different places depending
on whether you use the command line or the GUI to configure your App Firewall. When using the com-
mand line, you configure Reset Learned Data by using the reset appfw learningdata command, which
takes no parameters and has no other functions. You configure Signatures Auto-Update in the set
appfw settings command: the -signatureAutoUpdate parameter enables or disables auto-updating
of the signatures, and -signatureUrl configures the URL which hosts the updated signatures file.
When using the GUI, you configure Reset Learned Data in Security > **App Firewall > Engine Settings;
the **Reset Learned Data button is at the bottom of the dialog box. You configure Signatures Auto-
Update for each set of signatures in Security > App Firewall > Signatures, by selecting the signatures
file, clicking the right mouse button and selecting Auto Update Settings.
Normally, the default values for the App Firewall settings are correct. If the default settings cause a
conflict with other servers or cause premature disconnection of your users, however, you might need
to modify them.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1765

NetScaler 12.0

The App Firewall session limit is configurable using the following command:

1 > set appfw settings -sessionLimit 500000

2 Done
3 Default value:100000   Max value:500000 per PE

To configure engine settings by using the command line interface

At the command prompt, type the following commands:

• set appfw settings [-sessionCookieName <name>] [-sessionTimeout <

positiveInteger> ] [-sessionLifetime <positiveInteger>][-clientIPLoggingHeader
<headerName> ] [-undefaction <profileName>] [-defaultProfile <profileName
>] [-importSizeLimit <positiveInteger>] [-logMalformedReq ( ON | OFF
)] [-signatureAutoUpdate ( ON | OFF )] [-signatureUrl <expression>]
[-cookiePostEncryptPrefix <string>] [-entityDecoding ( ON | OFF )] [-
useConfigurableSecretKey ( ON | OFF )][-learnRateLimit <positiveInteger
>]
• save ns config

Example

1 set appfw settings -sessionCookieName citrix-appfw-id -sessionTimeout

3600
2 -sessionLifetime 14400 -clientIPLoggingHeader NS-AppFW-Client-IP -
undefaction APPFW_RESET
3 -defaultProfile APPFW_RESET -importSizeLimit 4096
4 save ns config

To configure engine settings by using the GUI

1. Navigate to Security > App Firewall

2. In the details pane, click Change Engine Settings.
3. In the App Firewall Engine Settings dialog box, set the following parameters:
• Cookie Name
• Session Timeout
• Cookie Post Encrypt Prefix
• Maximum Session Lifetime
• Logging Header Name

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1766

NetScaler 12.0

• Undefined Profile
• Default Profile
• Import Size Limit
• Learn Messages Rate Limit
• Entity Decoding
• Log Malformed Request
• Use Secret Key
• Learn Message Rate Limit
• Signatures Auto Update
4. Click OK.
1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Confidential fields

September 18, 2018

Contributed by:
C
You can designate web-form fields as confidential to protect the information users type into them.
Normally, any information a user types into a web form on one of your protected web servers is logged
in the NetScaler logs. The information typed into a web-form field designated as confidential, how-
ever, is not logged. That information is saved only where the web site is configured to save such data,
normally in a secure database.
Common types of information that you may want to protect with a confidential field designation in-
clude:
• Passwords
• Credit card numbers, validation codes, and expiration dates
• Social security numbers
• Tax ID numbers
• Home addresses
• Private telephone numbers
In addition to being good practice, proper use of confidential field designations may be necessary
for PCI-DSS compliance on ecommerce servers, HIPAA compliance on servers that manage medical
information in the United States, and compliance with other data protection standards.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1767

NetScaler 12.0

Important:

In the following two cases, the Confidential Field designation does not function as expected:

• If a Web form has either a confidential field or an action URL longer than 256 characters, the
field or action URL is truncated in the NetScaler logs.
• With certain SSL transactions, the logs are truncated if either the confidential field or the action
URL is longer than 127 characters.

In either of these cases, the App Firewall masks a fifteen-character string with the letter “x,” instead
of the normal eight character string. To ensure that any confidential information is removed, the user
must use form field name and action URL expressions that match the first 256, or (in cases where SSL
is used) the first 127 characters.

To configure your App Firewall to treat a web-form field on a protected web site as confidential, you
add that field to the Confidential Fields list. You can enter the field name as a string, or you can enter
a PCRE-compatible regular expression specifying one or more fields. You can enable the confidential-
field designation when you add the field, or you can modify the designation later.

To add a confidential field by using the command line interface

At the command prompt, type the following commands:

• add appfw confidField <fieldName> <url> [-isRegex ( REGEX | NOTREGEX )]

[-comment ”<string>”] [-state ( ENABLED | DISABLED )]
• save ns config

Example

The following example adds all web form fields whose names begin withPassword to the confidential
fields list.

1 add appfw confidField Password ”https?://www[.]example[.]com/[^<>]*[^a-

z]password[0-9a-z._-]*[.](asp|cgi|htm|html|htp|js|php)” -isRegex
REGEX -state ENABLED
2 save ns config

To modify a confidential field by using the command line interface

At the command prompt, type the following commands:

• set appfw confidField <fieldName> <url> [-isRegex ( REGEX | NOTREGEX )

][-comment ”<string>”] [-state ( ENABLED | DISABLED )]

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1768

NetScaler 12.0

• ‘save ns config’

Example

The following example modifies the confidential field designation to add a comment.

1 set appfw confidField Password ”https?://www[.]example[.]com/[^<>]*[^a-

z]password[0-9a-z._-]*[.](asp|cgi|htm|html|htp|js|php)” -comment ”
Protect password fields.” -isRegex REGEX -state ENABLED
2 save ns config

To remove a confidential field by using the command line interface

At the command prompt, type the following commands:

• rm appfw confidField <fieldName> <url>

• save ns config

To configure a confidential field by using the GUI

1. Navigate to Security > Application Firewall.

2. In the details pane, under Settings, click Manage Confidential Fields.
3. In the Manage Confidential Fields dialog box, do one of the following:
• To add a new form field to the list, click Add.
• To change an existing confidential field designation, select the field, and then click Edit.
The App Firewall Confidential Fields dialog box appears.
Note:
If you select an existing confidential field designation and then click Add, the Cre-
ate Confidential Form Field dialog box displays the information for that confidential
field. You can modify that information to create your new confidential field.
4. In the dialog box, fill out the elements. They are:
• Enabled check box. Select or clear to enable/disable this confidential field designation.
• Is form field name a regular expression check box. Select or clear to enable PCRE-
format regular expressions in the form field name.
• Field Name. Enter a literal string or PCRE-format regular expression that either represents
a specific field name or that matches multiple fields with names that follow a pattern.
• Action URL. Enter a literal URL or a regular expression that defines one or more URLs of
the web page(s) on which the web form(s) that contains the confidential field are located.
• Comments. Enter a comment. Optional.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1769

NetScaler 12.0

5. Click Create or OK.

6. To remove a confidential field designation from the confidential fields list, select the confiden-
tial field listing you want to remove, then click Remove to remove it, and then click OK to confirm
your choice.
7. When you have finished adding, modifying, and removing confidential field designations, click
Close.

Examples

Following are some regular expressions that define form field names that you might find useful:

• ˆpasswd_ (Applies confidential-field status to all field names that begin with the “passwd_”
string.)

ˆ(([0-9a-zA-Z._-]* \x[0-9A-Fa-f][0-9A-Fa-f])+-
)?passwd_ (Applies
confidential-field status to all
field names that begin with
the string passwd_, or that
contain the string -passwd_
after another string that
might contain non-ASCII
special characters.)

Following are some regular expressions that define specific URL types that you might find useful. Sub-
stitute your own web host(s) and domain(s) for those in the examples.

• If the web form appears on multiple web pages on the web host www.example.com, but all of
those web pages are named logon.pl?, you could use the following regular expression:

1 https?://www[.]example[.]com/([0-9A-Za-z][0-9A-Za-z_.-]*/)*logon
[.]pl\?

• If the web form appears on multiple web pages on the web host www.example-español.com,
which contains the n-tilde (ñ) special character, you could use the following regular expression,
which represents the n-tilde special character as an encoded UTF-8 string containing C3 B1, the
hexadecimal code assigned to that character in the UTF-8 charset:

1 https?://www[.]example-espa\xC3\xB1ol[.]com/([0-9A-Za-z][0-9A-Za-
z_.-]*/)* logon[.]pl\?

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1770

NetScaler 12.0

• If the web form containing query.pl appears on multiple web pages on different hosts within the
example.com domain, you could use the following regular expression:

1 https?://([0-9A-Za-z][0-9A-Za-z_-.]*[.])*example[.]com/([0-9A-Za-
z][0-9A-Za-z_-.]*/)*logon[.]pl\?

• If the web form containing query.pl appears on multiple web pages on different hosts in different
domains, you could use the following regular expression:

1 https?://([0-9A-Za-z][0-9A-Za-z_-.]*[.])*[0-9A-Za-z][0-9A-Za-z_
-.]+[.][a-z]{
2 2,6 }
3 /([0-9A-Za-z][0-9A-Za-z_-.]*/)*logon[.]pl\?

• If the web form appears on multiple web pages on the web host www.example.com, but all of
those web pages are named logon.pl?, you could use the following regular expression:

1 https?://www[.]example[.]com/([0-9A-Za-z][0-9A-Za-z_-.]*/)*logon
[.]pl\?

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Field types

September 20, 2018

Contributed by:
C

A field type is a PCRE-format regular expression that defines a particular data format and minimum/-
maximum data lengths for a form field in a web form. Field types are used in the Field Formats check.

The App Firewall comes with several default field types, which are:

• integer. A string of any length consisting of numbers only, without a decimal point, and with an
optional preceding minus sign (-).

• alpha. A string of any length consisting of letters only.

• alphanum. A string of any length consisting of letters and/or numbers.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1771

NetScaler 12.0

• nohtml. A string of any length consisting of characters, including punctuation and spaces, that
does not contain HTML symbols or queries.

• any. Anything at all.

Important:

Assigning the any field type as the default field type, or to a field, allows active scripts, SQL
commands, and other possibly dangerous content to be sent to your protected web sites
and applications in that form field. You should use the any type sparingly, if you use it at
all.

You can also add your own field types to the Field Types list. For example, you might want to add a
field type for a social security number, postal code, or phone number in your country. You might also
want to add a field type for a customer identification number or store credit card number.

To add a field type to the Field Types list, you enter the field name as a literal string or PCRE-format
regular expression.

To add a field type by using the command line interface

At the command prompt, type the following commands:

• add appfw fieldType <name> <regex> <priority> [-comment ”<string>”]

• save ns config

Example

The following example adds a field type named SSN that matches US Social Security numbers to the
Field Types list, and sets its priority to 1.

1 add appfw fieldType SSN ”^[1-9][0-9]{

2 2,2 }
3 -[0-9 }
4 {
5 2,2 }
6 -[0-9]{
7 4,4 }
8 $” 1
9 save ns config

To modify a field type by using the command line interface

At the command prompt, type the following commands:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1772

NetScaler 12.0

• set appfw fieldType <name> <regex> <priority> [-comment ”<string>”]

• save ns config

Example

The following example modifies the field type to add a comment.

1 set appfw fieldType SSN ”^[1-9][0-9]{

2 2,2 }
3 -[0-9 }
4 {
5 2,2 }
6 -[0-9]{
7 4,4 }
8 $” 1 -comment ”US Social Security Number”
9 save ns config

To remove a field type by using the command line interface

At the command prompt, type the following commands:

• >rm appfw fieldType <name>

• save ns config

To configure a field type by using the GUI

1. Navigate to Security > Application Firewall.

2. In the details pane, under Settings, click Manage Field Types.
3. In the Manage Field Types dialog box, do one of the following:
• To add a new field type to the list, click Add.
• To change an existing field type, select the field type, and then click Edit.
The Configure Field Type dialog box appears.
Note:
If you select an existing field type designation and then click Add, the dialog box dis-
plays the information for that field type. You can modify that information to create
your new field type.
4. In the dialog box, fill out the elements. They are:
• Name
• Regular Expression
• Priority

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1773

NetScaler 12.0

• Comment
5. Click Create or OK.
6. To remove a field type from the Field Types list, select the field type listing you want to remove,
then click Remove to remove it, and then click OK to confirm your choice.
7. When you have finished adding, modifying, and removing field types, click Close.

Examples

Following are some regular expressions for field types that you might find useful:
^[1-9][0-9]{ 2,2 } -[0-9 } { 2,2 } -[0-9]{ 4,4 } $ U.S. Social Security
numbers

^\[A-C\]\[0-9\]{ 7,7 } $ California driver’s license numbers

^+[0-9]{ 1,3 } [0-9()-]{ 1,40 } $ International phone numbers with country

codes

^[0-9]{ 5,5 } -[0-9]{ 4,4 } $ U.S. ZIP code numbers.

^[0-9A-Za-z][0-9A-Za-z.+_-]{ 0,25 } @([0-9A-Za-z][0-9A-Za-z_-]*[.]){ 1,4 }

[A-Za-z]{ 2,6 } $ Email addresses‘.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

XML content types

September 18, 2018

Contributed by:
C
By default, the App Firewall treats files that follow certain naming conventions as XML. You can config-
ure the App Firewall to examine web content for additional strings or patterns that indicate that those
files are XML files. This can ensure that the App Firewall recognizes all XML content on your site, even
if certain XML content does not follow normal XML naming conventions, ensuring that XML content is
subjected to XML security checks.
To configure the XML content types, you add the appropriate patterns to the XML Content Types list.
You can enter a content type as a string, or you can enter a PCRE-compatible regular expression spec-
ifying one or more strings. You can also modify the existing XML content types patterns.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1774

NetScaler 12.0

To add an XML content type pattern by using the command line interface

At the command prompt, type the following commands:

• add appfw XMLContentType <XMLContenttypevalue> [-isRegex ( REGEX |

NOTREGEX )]
• save ns config

Example

The following example adds the pattern .*/xml to the XML Content Types list and designates it as a
regular expression.

1 add appfw XMLContentType ”.*/xml” -isRegex REGEX

To remove an XML content type pattern by using the command line interface

At the command prompt, type the following commands:

• rm appfw XMLContentType <XMLContenttypevalue>

• save ns config

To configure the XML content type list by using the GUI

1. Navigate to Security > App Firewall.

2. In the details pane, under Settings, click Manage XML Content Types.
3. In the Manage XML Content Types dialog box, do one of the following:
• To add a new XML content type, click Add.
• To modify an existing XML content type, select that type and then click Edit.
The Configure App Firewall XML Content Type dialog appears. Note: If you select an exist-
ing XML content type pattern and then click
Add, the dialog box displays the information for that XML content type pattern. You can
modify that information to create your new XML content type pattern.
4. In the dialog box, fill out the elements. They are:
• IsRegex. Select or clear to enable PCRE-format regular expressions in the form field name.
• XML Content Type Enter a literal string or PCRE-format regular expression that matches
the XML content type pattern that you want to add.
5. Click Create.
6. To remove an XML content type pattern from the list, select it, then click Remove to remove it,
and then click OK to confirm your choice.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1775

NetScaler 12.0

7. When you have finished adding and removing XML content type patterns, click Close.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

JSON content types

September 18, 2018

Contributed by:
C

By default, the App Firewall treats files with the content type “application/json” as JSON files.The de-
fault setting enables the App Firewall to recognize JSON content in requests and responses, and to
handle that content appropriately.

You can configure the App Firewall to examine web content for additional strings or patterns that indi-
cate that those files are JSON files. This can ensure that the App Firewall recognizes all JSON content
on your site, even if certain JSON content does not follow normal JSON naming conventions, ensuring
that JSON content is subjected to JSON security checks.

To configure the JSON content types, you add the appropriate patterns to the JSON Content Types
list. You can enter a content type as a string, or you can enter a PCRE-compatible regular expression
specifying one or more strings. You can also modify the existing JSON content types patterns.

To add a JSON content type pattern by using the command line interface

At the command prompt, type the following commands:

• add appfw JSONContentType <JSONContenttypevalue> [-isRegex ( REGEX |

NOTREGEX )]
• save ns config

Example

The following example adds the pattern .*/json to the JSON Content Types list and designates it as a
regular expression.

1 add appfw JSONContentType ”.*/json” -isRegex REGEX

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1776

NetScaler 12.0

To configure the JSON content type list by using the GUI

1. Navigate to Security > Application Firewall.

2. In the details pane, under Settings, click Manage JSON Content Types.
3. In the Manage JSON Content Types dialog box, do one of the following:
• To add a new JSON content type, click Add.
• To modify an existing JSON content type, select that type and then click Edit.
The Configure App Firewall JSON Content Type dialog appears.
Note: If you select an existing JSON content type pattern and then click
Add, the dialog box displays the information for that JSON content type pattern. You can
modify that information to create your new JSON content type pattern.
4. In the dialog box, fill out the elements. They are:
• IsRegex. Select or clear to enable PCRE-format regular expressions in the form field name.
• JSON Content Type Enter a literal string or PCRE-format regular expression that matches
the JSON content type pattern that you want to add.
5. Click Create or OK.
6. To remove a JSON content type pattern from the list, select it, then click Remove to remove it,
and then click OK to confirm your choice.
7. When you have finished adding and removing XML content type patterns, click Close.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Statistics and reports

September 20, 2018

Contributed by:
C

The information maintained in the logs and statistics, and displayed in the reports, provides important
guidance for configuring and maintaining the App Firewall.

The App Firewall statistics

When you enable the statistics action for App Firewall signatures or security checks, the App Firewall
maintains information about connections that match that signature or security check. You can view

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1777

NetScaler 12.0

the accumulated statistics information on the

Monitoring tab of the main logon page of your App Firewall appliance by selecting one of the following
choices in the Select Group list box:

• App Firewall. A summary of all statistics information gathered by your App Firewall appliance
for all profiles.
• App Firewall (per profile). The same information, but displayed per-profile rather than sum-
marized.

You can use this information to monitor how your App Firewall is operating and determine whether
there is any abnormal activity or abnormal amounts of hits on a signature or security check. If you
see such a pattern of abnormal activity, you can check the logs for that signature or security check, to
diagnose the issue, and then take corrective action.

The App Firewall reports

The App Firewall reports provide information about your App Firewall configuration and how it is han-
dling traffic for your protected web sites.

The PCI DSS report

The Payment Card Industry (PCI) Data Security Standard (DSS), version 1.2, consists of twelve security
criteria that most credit card companies require businesses who accept online payments via credit
and debit cards to meet. These criteria are designed to prevent identity theft, hacking, and other
types of fraud. If an internet service provider or online merchant does not meet the PCI DSS criteria,
that ISP or merchant risks losing authorization to accept credit card payments through its web site.

ISPs and online merchants prove that they are in compliance with PCI DSS by having an audit con-
ducted by a PCI DSS Qualified Security Assessor (QSA) Company. The PCI DSS report is designed to
assist them both before and during the audit. Before the audit, it shows which App Firewall settings
are relevant to PCI DSS, how they should be configured, and (most important) whether your current
App Firewall configuration meets the standard. During the audit, the report can be used to demon-
strate compliance with relevant PCI DSS criteria.

The PCI DSS report consists of a list of those criteria that are relevant to your App Firewall configura-
tion. Under each criterion, it lists your current configuration options, indicates whether your current
configuration complies with the PCI DSS criterion, and explains how to configure the App Firewall so
that your protected web site(s) will be in compliance with that criterion.

The PCI DSS report is located under System > Reports. To generate the report as an Adobe PDF file,
click Generate PCI DSS Report. Depending on your browser settings, the report is displayed in the
pop-up window or you are prompted to save it to your hard disk.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1778

NetScaler 12.0

Note:
To view this and other reports, you must have the Adobe Reader program installed on your com-
puter.

The PCI DSS report consists of the following sections:

• Description. A description of the PCI DSS Compliance Summary report.

• Firewall License and Feature Status. Tells you whether the App Firewall is licensed and en-
abled on your NetScaler appliance.

• Executive Summary. A table that lists the PCI DSS criteria and tells you which of those criteria
are relevant to the App Firewall.

• Detailed PCI DSS Criteria Information. For each PCI DSS criterion that is relevant to your App
Firewall configuration, the PCI DSS report provides a section that contains information about
whether your configuration is currently in compliance and, if it is not, how to bring it into com-
pliance.

• Configuration. Data for individual profiles, which you access either by clicking App Firewall
Configuration at the top of the report, or directly from the Reports pane. The App Firewall Con-
figuration report is the same as the PCI DSS report, with the PCI DSS-specific summary omitted,
and is described below.

The App Firewall configuration report

The App Firewall Configuration report is located under System > Reports. To display it, click Generate
App Firewall Configuration Report. Depending on your browser settings, the report is displayed in the
pop-up window or you are prompted to save it to your hard disk.

The App Firewall Configuration report starts with a Summary page, which consists of the following
sections:

• App Firewall Policies. A table that lists your current App Firewall policies, showing the policy
name, the content of the policy, the action (or profile) it is associated with, and global binding
information.
• App Firewall Profiles. A table that lists your current App Firewall profiles and indicates which
policy each profile is associated with. If a profile is not associated with a policy, the table dis-
plays INACTIVE in that location.

To download all report pages for all policies, at the top of the Profiles Summary page click Download
All Profiles. You display the report page for each individual profile by selecting that profile in the table
at the bottom of the screen. The Profile page for an individual profile shows whether each check action
is enabled or disabled for each check, and the other configuration settings for the check.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1779

NetScaler 12.0

To download a PDF file containing the PCI DSS report page for the current profile, click Download
Current Profile at the top of the page. To return to the Profiles Summary page, click App Firewall
Profiles. To go back to the main page, click Home. You can refresh the PCI DSS report at any time by
clicking Refresh in the upper right corner of the browser. You should refresh the report if you make
changes to your configuration.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

App Firewall logs

January 6, 2019

Contributed by:
C

The App Firewall generated log messages can be quite useful for keeping track of the configurational
changes, App Firewall policy invocations, and security check violations.

When the log action is enabled for security checks or signatures, the resulting log messages provide
information about the requests and responses that the App Firewall has observed while protecting
your web sites and applications. The most important information is the action taken by the App Fire-
wall when a signature or a security check violation was observed. For some security checks, the log
message can provide additional useful information, such as the location and the detected pattern
that triggered the violation. You can deploy security checks in non-block mode and monitor the logs
to determine whether the transactions that are triggering security violations are valid transactions
(false positives). If they are, you can either remove, or reconfigure the signature or security checks,
deploy relaxations, or take other appropriate measures to mitigate the false positives before you en-
able blocking for that signature or security check. An excessive increase in the number of violation
messages in logs can indicate a surge in malicious requests. This can alert you that your application
might be under attack to exploit a specific vulnerability that is detected and thwarted by App Firewall
protections.

NetScaler (Native) format logs

The App Firewall uses the NetScaler format logs (also called native format logs) by default. These logs
have the same format as those generated by other NetScaler features. Each log contains the following
fields:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1780

NetScaler 12.0

• Timestamp. Date and time when the connection occurred.

• Severity. Severity level of the log.
• Module. NetScaler module that generated the log entry.
• Event Type. Type of event, such as signature violation or security check violation.
• Event ID. ID assigned to the event.
• Client IP. IP address of the user whose connection was logged.
• Transaction ID. ID assigned to the transaction that caused the log.
• Session ID. ID assigned to the user session that caused the log.
• Message. The log message. Contains information identifying the signature or security check
that triggered the log entry.

You can search for any of these fields, or any combination of information from different fields. Your
selection is limited only by the capabilities of the tools you use to view the logs. You can observe the
App Firewall log messages in the GUI by accessing the NetScaler syslog viewer, or you can manually
connect to the NetScaler appliance and access logs from the command line interface, or you can drop
into shell and tail the logs directly from the /var/log/ folder.

Example of a Native Format Log message

1 Jun 22 19:14:37 <local0.info> 10.217.31.98 06/22/2015:19:14:37 GMT ns

0-PPE-1 :
2 default APPFW APPFW_XSS 60 0 : 10.217.253.62 616-PPE1 y/3
upt2K8ySWWId3Kavbxyni7Rw0000
3 pr_ffc http://aaron.stratum8.net/FFC/login.php?login_name=abc&passwd=
4 12345&drinking_pref=on&text_area=%3Cscript%3E%0D%0A&loginButton=
ClickToLogin&as_sfid=
5 AAAAAAWEXcNQLlSokNmqaYF6dvfqlChNzSMsdyO9JXOJomm2v
6 BwAMOqZIChv21EcgBc3rexIUcfm0vckKlsgoOeC_BArx1Ic4NLxxkWMtrJe4H7SOfkiv9NL7AG4juPIan

7 %3D&as_fid=feeec8758b41740eedeeb6b35b85dfd3d5def30c Cross-site script

check failed for
8 field text_area=”Bad tag: script” <blocked>

Common Event Format (CEF) Logs

The App Firewall also supports CEF logs. CEF is an open log management standard that improves
the interoperability of security-related information from different security and network devices and
applications. CEF enables customers to use a common event log format so that data can easily be col-
lected and aggregated for analysis by an enterprise management system. The log message is broken
into different fields so that you can easily parse the message and write scripts to identify important
information.

Analyzing the CEF Log Message

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1781

NetScaler 12.0

In addition to date, timestamp, client IP, log format, appliance, company, build version, module, and
security check information, App Firewall CEF Log messages include the following details:

• src – source IP address

• spt – source port number
• request – request URL
• act – action (e.g. blocked, transformed)
• msg – message (Message regarding the observed security check violation)
• cn1 – event ID
• cn2 – HTTP Transaction ID
• cs1 – profile name
• cs2 – PPE ID (e.g. PPE1)
• cs3 - Session ID
• cs4 – Severity (e.g. INFO, ALERT)
• cs5 – event year
• cs6 - Signature violation category
• method – Method (e.g. GET/POST)

For example, consider the following CEF format log message, which was generated when a Start URL
violation was triggered:

1 Jun 12 23:37:17 <local0.info> 10.217.31.98 CEF:0|Citrix|NetScaler|NS11

.0
2 |APPFW|APPFW_STARTURL|6|src=10.217.253.62 spt=47606 method=GET
3 request=http://aaron.stratum8.net/FFC/login.html msg=Disallow Illegal
URL. cn1=1340
4 cn2=653 cs1=pr_ffc cs2=PPE1 cs3=EsdGd3VD0OaaURLcZnj05Y6DOmE0002 cs4=
ALERT cs5=2015
5 act=blocked

The above message can be broken down into different components. Refer to the CEP log components
table.

Example of a request check violation in CEF log format: request is not blocked

1 Jun 13 00:21:28 <local0.info> 10.217.31.98 CEF:0|Citrix|NetScaler|NS11

.0|APPFW|
2 APPFW_FIELDCONSISTENCY|6|src=10.217.253.62 spt=761 method=GET request=
3 http://aaron.stratum8.net/FFC/login.php?login_name=abc&passwd=
4 123456789234&drinking_pref=on&text_area=&loginButton=ClickToLogin&
as_sfid
5 =
AAAAAAWIahZuYoIFbjBhYMP05mJLTwEfIY0a7AKGMg3jIBaKmwtK4t7M7lNxOgj7Gmd3SZc8KUj6CR

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1782

NetScaler 12.0

6 7W5kIWDRHN8PtK1Zc-txHkHNx1WknuG9DzTuM7t1THhluevXu9I4kp8%3D&as_fid=
feeec8758b4174
7 0eedeeb6b35b85dfd3d5def30c msg=Field consistency check failed for field
passwd cn1=1401
8 cn2=707 cs1=pr_ffc cs2=PPE1 cs3=Ycby5IvjL6FoVa6Ah94QFTIUpC80001 cs4=
ALERT cs5=2015 act=
9 not blocked

Example of a response check violation in CEF format: response is transformed

1 Jun 13 00:25:31 <local0.info> 10.217.31.98 CEF:0|Citrix|NetScaler|NS11

.0|APPFW|
2 APPFW_SAFECOMMERCE|6|src=10.217.253.62 spt=34041 method=GET request=
3 http://aaron.stratum8.net/FFC/CreditCardMind.html msg=Maximum number of
potential credit
4 card numbers seen cn1=1470 cn2=708 cs1=pr_ffc cs2=PPE1
5 cs3=Ycby5IvjL6FoVa6Ah94QFTIUpC80001 cs4=ALERT cs5=2015 act=transformed

Example of a request side signature violation in CEF format: request is blocked

1 Jun 13 01:11:09 <local0.info> 10.217.31.98 CEF:0|Citrix|NetScaler|NS11

.0|APPFW|
2 APPFW_SIGNATURE_MATCH|6|src=10.217.253.62 spt=61141 method=GET request=
3 http://aaron.stratum8.net/FFC/wwwboard/passwd.txt msg=Signature
violation rule ID 807:
4 web-cgi /wwwboard/passwd.txt access cn1=140 cn2=841 cs1=pr_ffc cs2=
PPE0
5 cs3=OyTgjbXBqcpBFeENKDlde3OkMQ00001 cs4=ALERT cs5=2015 cs6=web-cgi act=
blocked

Logging geolocation in the App Firewall violation messages

Geolocation, which identifies the geographic location from which requests originate, can help you
configure the App Firewall for the optimal level of security. To bypass security implementations such
as rate limiting, which rely on the IP addresses of the clients, malware or rogue computers can keep
changing the source IP address in requests. Identifying the specific region from where requests are
coming can help determine whether the requests are from a valid user or a device attempting to launch
cyberattacks. For example, if an excessively large number of requests are received from a specific area,
it is easy to determine whether they are being sent by users or a rogue machine. Geolocation analysis
of the received traffic can be very useful in deflecting attacks such as denial of service (DoS) attacks.

The App Firewall offers you the convenience of using the built-in NetScaler database for identifying
the locations corresponding to the IP addresses from which malicious requests are originating. You

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1783

NetScaler 12.0

can then enforce a higher level of security for requests from those locations. Citrix default syntax (PI)
expressions give you the flexibility to configure location based policies that can be used in conjunction
with the built-in location database to customize firewall protection, bolstering your defense against
coordinated attacks launched from rogue clients in a specific region.

You can use the NetScaler built-in database, or you can use any other database. If the database does
not have any location information for the particular client IP address, the CEF log shows geolocation
as an Unknown geolocation.

Note: Geolocation logging uses the Common Event Format (CEF). By default, CEF logging and GeoLo-
cationLogging are OFF. You must explicitly enable both parameters.

Example of a CEF log message showing geolocation information

1 June 8 00:21:09 <local0.info> 10.217.31.98 CEF:0|Citrix|NetScaler|NS11

.0|APPFW|
2 APPFW_STARTURL|6|src=10.217.253.62 geolocation=NorthAmerica.US.Arizona.
Tucson.*.*
3 spt=18655 method=GET request=http://aaron.stratum8.net/FFC/login.html
4 msg=Disallow Illegal URL. cn1=77 cn2=1547 cs1=test_pr_adv cs2=PPE1
5 cs3=KDynjg1pbFtfhC/nt0rBU1o/Tyg0001 cs4=ALERT cs5=2015 act=not blocked

Example of a log message showing geolocation= Unknown

1 June 9 23:50:53 <local0.info> 10.217.31.98 CEF:0|Citrix|NetScaler|NS11

.0|
2 APPFW|APPFW_STARTURL|6|src=10.217.30.251 geolocation=Unknown spt=5086
3 method=GET request=http://aaron.stratum8.net/FFC/login.html msg=
Disallow Illegal URL.
4 cn1=74 cn2=1576 cs1=test_pr_adv cs2=PPE2 cs3=
PyR0eOEM4gf6GJiTyauiHByL88E0002
5 cs4=ALERT cs5=2015 act=not blocked

Using the command line to configure the log action and other log parameters

To configure the log action for a security checks of a profile by using the command line

At the command prompt, type one of the following commands:

• set appfw profile <name> SecurityCheckAction ([log] | [none])

• unset appfw profile <name> SecurityCheckAction

Examples

set appfw profile pr_ffc StartURLAction log

unset appfw profile pr_ffc StartURLAction

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1784

NetScaler 12.0

To configure CEF logging by using the command line

The CEF logging is disabled by default. At the command prompt, type one of the following commands
to change or display the current setting:

• set appfw settings CEFLogging on

• unset appfw settings CEFLogging
• sh appfw settings | grep CEFLogging

To configure the logging of the credit card numbers by using the command line

At the command prompt, type one of the following commands:

• set appfw profile <name> -doSecureCreditCardLogging ([ON] | [OFF])

• unset appfw profile <name> -doSecureCreditCardLogging

To configure Geolocation logging by using the command line

1. Use the set command to enable GeoLocationLogging. You can enable the CEF logging at the
same time. Use the unset command to disable geolocation logging. The show command shows
the current settings of all the App Firewall parameters, unless you include the grep command
to show the setting for a specific parameter.

• set appfw settings GeoLocationLogging ON [CEFLogging ON]

• unset appfw settings GeoLocationLogging
• sh appfw settings | grep GeoLocationLogging

2. Specify the database

add locationfile /var/netscaler/inbuilt_db/Citrix_netscaler_InBuilt_GeoIP_DB

.csv

or

add locationfile <path to database file>

Customizing App Firewall Logs

Default format (PI) expressions give you the flexibility to customize the information included in the
logs. You have the option to include the specific data that you want to capture in the App Firewall
generated log messages. For example, if you are using AAA-TM authentication along with the App
Firewall security checks, and would like to know the accessed URL that triggered the security check
violation, the name of the user who requested the URL, the source IP address, and the source port
from which the user sent the request, you can use the following commands to specify customized log
messages that include all the data:

Default format (PI) expressions give you the flexibility to customize the information included in the
logs. You have the option to include the specific data that you want to capture in the App Firewall

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1785

NetScaler 12.0

generated log messages. For example, if you are using AAA-TM authentication along with the App
Firewall security checks, and would like to know the accessed URL that triggered the security check
violation, the name of the user who requested the URL, the source IP address, and the source port
from which the user sent the request, you can use the following commands to specify customized log
messages that include all the data:

1 > sh version
2 NetScaler NS12.1: Build 50.0013.nc, Date: Aug 28 2018, 10:51:08 (64-
bit)
3 Done

1 > add audit messageaction custom1 ALERT ’HTTP.REQ.URL + ” ” + HTTP.REQ.

USER.NAME + ” ” + CLIENT.IP.SRC + ”:” + CLIENT.TCP.SRCPORT’
2 Warning: HTTP.REQ.USER has been deprecated. Use AAA.USER instead.
3 Done

1 > add appfw profile test_profile

2 Done

1 > add appfw policy appfw_pol true test_profile -logAction custom1

2 Done

Configuring Syslog policy to segregate App Firewall logs

The App Firewall offers you an option to isolate and redirect the App Firewall security log messages
to a different log file. This might be desirable if the App Firewall is generating a large number of logs,
making it difficult to view other NetScaler log messages. You can also use this option when you are
interested only in viewing the App Firewall log messages and do not want to see the other log mes-
sages.

To redirect the App Firewall logs to a different log file, configure a syslog action to send the App Firewall
logs to a different log facility. You can use this action when configuring the syslog policy, and bind it
globally for use by App Firewall.

Example:

1. Switch to the shell and use an editor such as vi to edit the /etc/syslog.conf file. Add a new entry
to use local2.* to send logs to a separate file as shown in the following example:

local2.\* /var/log/ns.log.appfw

2. Restart the syslog process. You can use the grep command to identify the syslog process ID
(PID), as shown in the following example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1786

NetScaler 12.0

root@ns\## ps -A | grep syslog

1063 ?? Ss 0:03.00 /usr/sbin/syslogd -b 127.0.0.1 -n -v -v -8 -C

root@ns## kill -HUP 1063

3. From the command line interface, configure the syslog action and policy. Bind it as a global App
Firewall policy.

> add audit syslogAction sysact 1.1.1.1 -logLevel ALL -logFacility LOCAL2

> add audit syslogPolicy syspol1 ns_true sysact1

> bind appfw global syspol1 100

1. All App Firewall security check violations will now be redirected to the /var/log/ns.log.appfw
file. You can tail this file to view the App Firewall violations that are getting triggered during the
processing of the ongoing traffic.

root@ns## tail -f ns.log.appfw

Warning: If you have configured the syslog policy to redirect the logs to a different log facility, the App
Firewall log messages no longer appear in the /var/log/ns.log file.

Viewing the App Firewall logs

You can view the logs by using the syslog viewer, or by logging onto the NetScaler appliance, opening
a UNIX shell, and using the UNIX text editor of your choice.

To access the log messages by using the command line

Switch to the shell and tail the ns.logs in the /var/log/ folder to access the log messages pertaining to
the App Firewall security check violations:

• Shell
• tail -f /var/log/ns.log

You can use the vi editor, or any Unix text editor or text search tool, to view and filter the logs for
specific entries. For example, you can use grep command to access the log messages pertaining to
the Credit Card violations:

• tail -f /var/log/ns.log | grep SAFECOMMERCE

To access the log messages by using the GUI

The NetScaler GUI includes a very useful tool (Syslog Viewer) for analyzing the log messages. You have
multiple options for accessing the Syslog Viewer:

• To view log messages for a specific security check of a profile, navigate to App Firewall > Pro-
files, select the target profile, and click Security Checks. Highlight the row for the target security

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1787

NetScaler 12.0

check and click Logs. When you access the logs directly from the selected security check of the
profile, it filters out the log messages and displays only the logs pertaining to the violations for
the selected security check. Syslog viewer can display App Firewall logs in the Native format as
well as the CEF format. However, in order for the syslog viewer to filter out the target profile
specific log messages, the logs must be in the CEF log format when accessed from the profile.
• You can also access the Syslog Viewer by navigating to NetScaler > System > Auditing. In the
Audit Messages section, click Syslog messages link to display the Syslog Viewer, which displays
all log messages, including all App Firewall security check violation logs for all profiles. This is
useful for debugging when multiple security check violations might be triggered during request
processing.
• Navigate to App Firewall > policies > Auditing. In the Audit Messages section, click Syslog mes-
sages link to display the Syslog Viewer, which displays all log messages, including all security
check violation logs for all profiles.

The HTML based Syslog Viewer provides the following filter options for selecting only the log messages
that are of interest to you:

• File—The current /var/log/ns.log file is selected by default, and the corresponding mes-
sages appear in the Syslog Viewer. A list of other log files in the /var/log directory are available
in a compressed .gz format. To download and un-compress an archived log file, just select the
log file from the dropdown option. The log messages pertaining to the selected file are then dis-
played in the syslog viewer. To refresh the display, click the Refresh icon (a circle of two arrows).

• Module list box—You can select the NetScaler module whose logs you want to view. You can
set it to APPFW for App Firewall logs.

• Event Type list box—This box contains a set of check boxes for selecting the type of event you
are interested in. For example, to view the log messages pertaining to the signature violations,
you can select the APPFW_SIGNATURE_MATCH check box. Similarly, you can select a check box
to enable the specific security check that is of interest to you. You can select multiple options.

• Severity—You can select a specific severity level to show just the logs for that severity level.
Leave all the check boxes blank if you want to see all logs.

To access the App Firewall security check violation log messages for a specific security check, fil-
ter by selecting APPFW in the dropdown options for Module. The Event Type displays a rich set
of options to further refine your selection. For example, if you select the APPFW_FIELDFORMAT
check box and click the Apply button, only log messages pertaining to the Field Formats secu-
rity check violations appear in the Syslog Viewer. Similarly, if you select the APPFW_SQL and
APPFW_STARTURL check boxes and click the Apply button, only log messages pertaining to
these two security check violations will appear in the syslog viewer.

If you place the cursor in the row for a specific log message, multiple options, such as Module, Event-
Type, EventID, ClientIP, TransactionID, and so on appear below the log message. You can select any

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1788

NetScaler 12.0

of these options to highlight the corresponding information in the logs.

Click to Deploy: This functionality is available only in the GUI. You can use the Syslog Viewer to not
only view the logs but also to deploy relaxation rules based on the log messages for the App Firewall
security check violations. The log messages must be in CEF log format for this operation. If the re-
laxation rule can be deployed for a log message, a check box appears at the right edge of the Syslog
Viewer box in the row. Select the check box, and then select an option from the Action list to deploy
the relaxation rule.
Edit & Deploy,
Deploy, and
Deploy All are available as Action options. For example, you can select an individual log message
to edit and deploy. You can also select the check boxes for multiple log messages from one or more
security checks and use the Deploy or Deploy All option. Click to Deploy functionality is currently
supported for the following security checks:
• StartURL
• URL Buffer overflow
• SQL Injection
• XSS
• Field consistency
• Cookie consistency
To use Click to Deploy functionality in the GUI
1. In the Syslog Viewer, select APPFW in the Module options.
2. Select the security check for which to filter corresponding log messages.
3. Enable the check box to select the rule.
4. Use the Action drop-down list of options to deploy the relaxation rule.
5. Verify that the rule appears in the corresponding relaxation rule section.
Note:
SQL Injection and XSS rules that are deployed by using Click Deploy option do not include the
fine grain relaxation recommendations.

Highlights

• CEF Log Format support—The CEF log format option provides a convenient option to moni-
tor, parse, and analyze the App Firewall log messages to identify attacks, fine tune configured
settings to decrease false positives, and gather statistics.
• Click to Deploy—The Syslog viewer provides an option to filter, evaluate, and deploy relaxation
rules for single or multiple security check violations from one convenient location.
• Option to customize log message—You can use advanced PI expressions to customize log mes-
sages and include the data you want to see in the logs.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1789

NetScaler 12.0

• Segregate App Firewall specific logs—You have an option to filter and redirect application-
firewall specific logs to a separate log file.
• Remote Logging—You can redirect the log messages to a remote syslog server.
• Geolocation Logging—You can configure the App Firewall to include the geolocation of the area
from where the request is received. A built-in geolocation database is available, but you have
the option to use an external geolocation database. The NetScaler appliance supports both IPv4
and IPv6 static geolocation databases.
• Information rich log message—Following are some examples of the type of information that
can be included in the logs, depending on the configuration:
– An App Firewall policy was triggered.
– A security check violation was triggered.
– A request was considered to be malformed.
– A request or the response was blocked or not blocked.
– Request data (such as SQL or XSS special characters) or response data (such as Credit card
numbers or safe object strings) was transformed.
– The number of credit cards in the response exceeded the configured limit.
– The credit card number and type.
– The log strings configured in the signature rules, and the signature ID.
– Geolocation information about the source of the request.
– Masked (X’d out) user input for protected confidential fields.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Appendices

September 18, 2018

Contributed by:
C

The following supplemental material provides additional detail about complex or peripheral App Fire-
wall tasks.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1790

NetScaler 12.0

PCRE character encoding format

September 18, 2018

Contributed by:
C

The NetScaler operating system supports direct entry of characters in the printable ASCII character
set only—characters with hexadecimal codes between HEX 20 (ASCII 32) and HEX 7E (ASCII 127). To
include a character with a code outside that range in your App Firewall configuration, you must enter
its UTF-8 hexadecimal code as a PCRE regular expression.

A number of character types require encoding using a PCRE regular expression if you include them in
your App Firewall configuration as a URL, form field name, or Safe Object expression. They include:

• Upper-ASCII characters. Characters with encodings from HEX 7F (ASCII 128) to HEX FF (ASCII
255). Depending on the character map used, these encodings can refer to control codes, ASCII
characters with accents or other modifications, non-Latin alphabet characters, and symbols not
included in the basic ASCII set. These characters can appear in URLs, form field names, and safe
object expressions.

• Double-Byte characters. Characters with encodings that use two 8-byte words. Double-byte
characters are used primarily for representing Chinese, Japanese, and Korean text in electronic
format. These characters can appear in URLs, form field names, and safe object expressions.

ASCII control characters. Non-printable characters used to send commands to a printer. All
ASCII characters with hexadecimal codes less than HEX 20 (ASCII 32) fall into this category. These
characters should never appear in a URL or form field name, however, and would rarely if ever
appear in a safe object expression.

The NetScaler appliance does not support the entire UTF-8 character set, but only the characters
found in the following eight charsets:

• English US (ISO-8859-1). Although the label reads, “English US,” the App Firewall supports all
characters in the ISO-8859-1 character set, also called the Latin-1 character set. This charac-
ter set fully represents most modern western European languages and represents all but a few
uncommon characters in the rest.

• Chinese Traditional (Big5). The App Firewall supports all characters in the BIG5 character set,
which includes all of the Traditional Chinese characters (ideographs) commonly used in modern
Chinese as spoken and written in Hong Kong, Macau, Taiwan, and by many people of Chinese
ethnic heritage who live outside of mainland China.

• Chinese Simplified (GB2312). The App Firewall supports all characters in the GB2312 charac-
ter set, which includes all of the Simplified Chinese characters (ideographs) commonly used in

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1791

NetScaler 12.0

modern Chinese as spoken and written in mainland China.

• Japanese (SJIS). The App Firewall supports all characters in the Shift-JIS (SJIS) character set,
which includes most characters (ideographs) commonly used in modern Japanese.

• Japanese (EUC-JP). The App Firewall supports all characters in the EUC-JP character set, which
includes all characters (ideographs) commonly used in modern Japanese.

• Korean (EUC-KR). The App Firewall supports all characters in the EUC-KR character set, which
includes all characters (ideographs) commonly used in modern Korean.

• Turkish (ISO-8859-9). The App Firewall supports all characters in the ISO-8859-9 character set,
which includes all letters used in modern Turkish.

• Unicode (UTF-8). The App Firewall supports certain additional characters in the UTF-8 charac-
ter set, including those used in modern Russian.

When configuring the App Firewall, you enter all non-ASCII characters as PCRE-format regular expres-
sions using the hexadecimal code assigned to that character in the UTF-8 specification. Symbols and
characters within the normal ASCII character set, which are assigned single, two-digit codes in that
character set, are assigned the same codes in the UTF-8 character set. For example, the exclamation
point (!), which is assigned hex code 21 in the ASCII character set, is also hex 21 in the UTF-8 character
set. Symbols and characters from another supported character set have a paired set of hexadecimal
codes assigned to them in the UTF-8 character set. For example, the letter a with an acute accent (á)
is assigned UTF-8 code C3 A1.

The syntax you use to represent these UTF-8 codes in the App Firewall configuration is “xNN” for ASCII
characters; “xNNxNN” for non-ASCII characters used in English, Russian, and Turkish; and “xNNxN-
NxNN” for characters used in Chinese, Japanese, and Korean. For example, if you want to represent a
! in an App Firewall regular expression as a UTF-8 character, you would type x21. If you want to include
an á, you would type xC3xA1.

Note:

Normally you do not need to represent ASCII characters in UTF-8 format, but when those charac-
ters might confuse a web browser or an underlying operating system, you can use the character’s
UTF-8 representation to avoid this confusion. For example, if a URL contains a space, you might
want to encode the space as \x20 to avoid confusing certain browsers and web server software.

Below are examples of URLs, form field names, and safe object expressions that contain non-ASCII
characters that must be entered as PCRE-format regular expressions to be included in the App Firewall
configuration. Each example shows the actual URL, field name, or expression string first, followed by
a PCRE-format regular expression for it.

• A URL containing extended ASCII characters. Actual URL: http://www.josénuñez.com

Encoded URL: ^http://www[.]jos\xC3\xA9nu\xC3\xB1ez[.]com$

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1792

NetScaler 12.0

• Another URL containing extended ASCII characters. Actual URL:http://www.example.de/

trömso.html Encoded URL: ^http://www[.]example\[.]de/tr\\xC3\\xB6mso[.]
html$

A form field name containing extended ASCII characters. Actual Name: nome_do_usuário Encoded
Name: ^nome_do_usu\xC3\xA1rio$
A safe object expression containing extended ASCII characters. Unencoded Expression [A-Z]{ 3,6
} ¥\[1-9\][0-9]{ 6,6 } Encoded Expression: [A-Z]{ 3,6 } \xC2\xA5[1-9][0-9]{ 6,6
}

You can find a number of tables that include the entire Unicode character set and matching UTF-8
encodings on the Internet. A useful web site that contains this information is located at the following
URL:

1 http://www.utf8-chartable.de/unicode-utf8-table.pl

For the characters in the table on this web site to display correctly, you must have an appropriate
Unicode font installed on your computer. If you do not, the visual display of the character may be
in error. Even if you do not have an appropriate font installed to display a character, however, the
description and the UTF-8 and UTF-16 codes on this set of web pages will be correct.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Whitehat WASC signature types for WAF use

September 18, 2018

Contributed by:
C

The NetScaler App Firewall accepts and generates blocking rules for all vulnerability types that the
Whitehat scanners generate. However, certain vulnerabilities are most applicable to a web App Fire-
wall. Following are lists of those vulnerabilities, categorized by whether they are addressed by WASC
1.0, WASC 2.0, or best practices signature types.

WASC 1.0 signature types

• HTTP Request Smuggling

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1793

NetScaler 12.0

• HTTP Response Splitting

• HTTP Response Smuggling
• Null Byte Injection
• Remote File Inclusion
• URL Redirector Abuse

WASC 2.0 signature types

• Abuse of Functionality
• Brute Force
• Content Spoofing
• Denial of Service
• Directory Indexing
• Information Leakage
• Insufficient Anti-automation
• Insufficient Authentication
• Insufficient Authorizatio
• Insufficient Session Expiration
• LDAP Injection
• Session Fixation

Best Practices

• Autocomplete Attribute
• Insufficient Cookie Access Control
• Insufficient Password Strength
• Invalid HTTP Method Usage
• Non-HttpOnly Session Cookie
• Persistent Session Cookie
• Personally Identifiable Information
• Secured Cachable HTTP Messages
• Unsecured Session Cookie

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1794

NetScaler 12.0

Streaming support for request processing

March 14, 2019

Contributed by:
C
Note:

This feature is available in NetScaler release 10.5.e.

The NetScaler App Firewall now uses request side streaming, which results in a significant perfor-
mance boost. Instead of buffering the entire request before processing it, the App Firewall now looks
at the incoming data, field by field, to inspect the input of each field for any configured security check
violation (SQL, XSS, Field Consistency, Field Formats, etc.). As soon as the processing of the data for
a field is completed, it is forwarded to the backend while the evaluation continues for the remaining
fields. This significantly improves the processing time specially when handling large posts where the
forms have large number of fields.
Note:

Citrix Web App Firewall supports a maximum post size of 20 MB without streaming. For better
resource utilization, Citrix recommends you to enable streaming option for payloads greater than
20 MB. Also, the back-end server must accept the chunked requests when streaming is enabled.

Although the streaming process is transparent to the users, minor configuration adjustments are re-
quired due to the following changes:

RegEx Pattern Match: RegEx pattern match is now restricted to 4K for contiguous character string
match.

Field Name Match: App Firewall learning engine can only distinguish the first 128 bytes of the name
for learning. If a form has multiple fields with names that have identical string match for the first
128 bytes, the learning engine may not be able to distinguish between them. Similarly, the deployed
relaxation rule might inadvertently relax all such fields.

Removing white spaces, percent decoding, unicode decoding, and charset conversion which is done
during canonicalization is carried out prior to security check inspection. The 128 byte limit is applica-
ble to the canonicalized representation of the field name in UTF-8 character format. The ASCII char-
acters are 1 byte but the UTF-8 representation of the characters in some international languages may
range from 1-4 bytes. If each character in the name takes 4 bytes when converted to UTF-8 format,
only first 32 characters in the name may be distinguished by the learned rule for such a language.

Field Consistency Check: When the field Consistency check is enabled, all the forms in the session
are now stored based on the “as_fid” tag inserted by the App Firewall without consideration for the
“action_url.”

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1795

NetScaler 12.0

• Mandatory Form tagging for Form Field consistency: When the field consistency check is en-
abled, the form tag must be enabled also. The Field Consistency protection might not work if
form tagging is turned off.
• Sessionless Form Field Consistency: The App Firewall no longer carries out the “GET” to
“POST” conversion of forms when sessionless field consistency parameter is enabled. The
form tag is required for sessionless field consistency also.
• Tampering of as_fid: If a form is submitted after tampering as_fid, it now triggers field consis-
tency violation even if no other field was tampered. In non-streaming requests, this was allowed
because the forms could be validated using the “action_url” stored in the session.

Signatures: The signatures now have the following specifications:

• Location: It is now a mandatory requirement that location must be specified for each pattern.
All patterns in the rule MUST have a <Location> tag.

• Fast Match: All signature rules must have a fast match pattern. If there is no fast match pattern,
an attempt will be made to select one if possible. Fast match must be a literal string but some
PCRE’s can be used for fast match if they contain a usable literal string.

• Deprecated Locations: Following locations are no longer supported in signature rules.

– HTTP_ANY
– HTTP_RAW_COOKIE
– HTTP_RAW_HEADER
– HTTP_RAW_RESP_HEADER
– HTTP_RAW_SET_COOKIE

XSS/SQL Transform: Raw data is used for transformation because the SQL special characters ( single
quote(‘), backslash (), and semicolon (;)), and XSS tags ((<) and(>)) are same in all languages and do not
need canonicalization of data. All representations of these characters, such as HTML entity encoding,
percent encoding, or ASCII are evaluated for transform operation.

The App Firewall no longer inspects both the attribute name and value for the XSS transform opera-
tion. Now only XSS attribute names are transformed when streaming is engaged.

Processing XSS Tags: As part of the streaming changes in 10.5.e build onwards, the App Firewall
processing of the Cross-site Scripting tags has changed. In earlier releases, presence of either open
bracket (<), or close bracket (>), or both open and close brackets (<>) was flagged as Cross-site Script-
ing Violation. The behavior has changed in 10.5.e build onwards. Presence of only the open bracket
character (<), or only the close bracket character (>) is no longer considered as an attack. It is when an
open bracket character (<) is followed by a close bracket character (>), the Cross-site scripting attack
gets flagged. Both characters must be present in the right order (< followed by >) to trigger Cross-site
scripting violation.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1796

NetScaler 12.0

Note

Change in SQL violation log Message: As part of the streaming changes in 10.5.e build onwards,
we now process the input data in blocks. RegEx pattern matching is now restricted to 4K for con-
tiguous character string matching. With this change, the SQL violation log messages might in-
clude different information compared to the earlier builds. The keyword and special character
in the input could be separated by a large number of bytes. We now keep track of the SQL key-
words and special strings when processing the data, instead of buffering the entire input value.
In addition to the field name, the log message now includes the SQL keyword, or the SQL special
character, or both the SQL keyword and the SQL special character, as determined by the con-
figured setting. The rest of the input is no longer included in the log message, as shown in the
following example:

Example:

In 10.5, when the App Firewall detects the SQL violation, the entire input string might be included
in the log message, as shown below:

SQL Keyword check failed for field text=”select a name from testbed1\;\(\;\)”.*<blocked>

In 11.0, we log only the field name, keyword and special character (if applicable) in the log mes-
sage, as shown below:

SQL Keyword check failed for field text=”select(;)”<blocked>

This change is applicable to requests that contain application/x-www-form-urlencoded,

or multipart/form-data, or text/x-gwt-rpc content-types. Log messages generated during
processing of JSON or XML payloads are not affected by this change.

RAW POST Body: The security check inspections are always done on RAW POST body.
Form ID: The App Firewall inserted “as_fid” tag, which is a computed hash of the form, will no longer
be unique for the user session. It will now have an identical value for a specific form irrespective of
the user or the session.
Charset: If a request does not have a charset, the default charset specified in the application profile
is used when processing the request.
Counters:
Counters with prefix “se_” and “appfwreq_” are added to track the streaming engine and the App
Firewall streaming engine request counters respectively.
nsconsmg -d statswt0 -g se_err_
nsconsmg -d statswt0 -g se_tot_
nsconsmg -d statswt0 -g se_cur_
nsconsmg -d statswt0 -g appfwreq_err_

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1797

NetScaler 12.0

nsconsmg -d statswt0 -g appfwreq_tot_

nsconsmg -d statswt0 -g appfwreq_cur_

_err counters: indicate the rare event which should have succeeded but failed due to either memory
allocation problem or some other resource crunch.

_tot counters: ever increasing counters.

_cur counters: counters indicating current values that keep changing based on usage from current
transactions.

Tips:

• The App Firewall security checks should work exactly the same as before.
• There is no set ordering for the processing of the security checks.

• The response side processing is not affected and remains unchanged.

• Streaming is not engaged if CVPN is used.

Important

Calculating the Cookie length: In release 10.5.e (in a few interim enhancement builds prior to
59.13xx.e build) as well as in the 11.0 release (in builds prior to 65.x), App Firewall processing of the
Cookie header was changed. In those releases, every cookie is evaluated individually, and if the
length of any one cookie received in the Cookie header exceeds the configured BufferOverflow-
MaxCookieLength, the Buffer Overflow violation is triggered. As a result of this change, requests
that were blocked in 10.5 and earlier release builds might be allowed, because the length of the
entire cookie header is not calculated for determining the cookie length. In some situations, the
total cookie size forwarded to the server might be larger than the accepted value, and the server
might respond with “400 Bad Request”.

Note that this change has been reverted. The behavior in the 10.5.e ->59.13xx.e and subse-
quent 10.5.e enhancement builds as well as in the 11.0 release 65.x and subsequent builds
is now similar to that of the non-enhancement builds of release 10.5. The entire raw Cookie
header is now considered when calculating the length of the cookie. Surrounding spaces
and the semicolon (;) characters separating the name-value pairs are also included in de-
termining the cookie length.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1798

NetScaler 12.0

Trace HTML requests with security logs

January 6, 2019

Contributed by:
C
Note:

This feature is available in NetScaler release 10.5.e.

Troubleshooting a problem, which requires analysis of data received in the client request can be quite
challenging specially when there is heavy traffic flowing through the box. Diagnosing issues which
may affect the functionality or security of the application require a quick response.

The NetScaler now offers the option to isolate traffic for a specific App Firewall profile and collect
nstrace for the HTML requests that trigger a log or block action or malformed requests that might be
causing reset or aborts. The nstrace collected in –appfw mode will include details of the entire request
including the App Firewall generated log messages. You can use “Follow TCP stream” in the trace to
view the details of the individual transaction including headers, payload, as well as the corresponding
log message, together in the same screen.

This gives you a comprehensive overview regarding your traffic. Having a detailed view of the request,
payload, and associated log records can be very useful to analyze security check violation. You can
easily identify the pattern that is triggering the violation. If the pattern should be allowed, you can
take a decision to modify the configuration and/or add a relaxation rule.

This enhancement helps in troubleshooting the NetScaler and offers the following benefits:

1. Isolate traffic for specific profile: This enhancement can be quite useful when you need to
isolate traffic for only one profile or specific transactions of a profile for troubleshooting. You
no longer have to skim through the entire data collected in the trace or need special filters to
isolate requests that are of interest to you which can be tedious especially with heavy traffic.
You now have the option to view only the data that you are interested in.
2. Collect data for specific requests: The trace can be collected for a specified duration. You can
collect trace for only a couple of requests to isolate, analyze, and debug specific transactions if
needed.
3. Identify resets or aborts: Unexpected closing of connections are not easily visible. The trace
collected in –appfw mode captures a reset or an abort, triggered by the App Firewall. This allows
a quicker isolation of issue when you do not see a security check violation message. Malformed
requests or other non-RFC compliant requests terminated by App Firewall will now be easier to
identify.
4. View decrypted SSL traffic: HTTPS traffic is captured in plain text to allow for easier trou-
bleshooting.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1799

NetScaler 12.0

5. Provides comprehensive view: Allows you to look at the entire request at the packet level,
check the payload, look at the logs to check what security check violation is being triggered
and identify the match pattern in the payload. If the payload consists of any unexpected data,
junk strings, or non-printable characters (null character, \r or \n etc), they are easy to discover
in the trace.
6. Modify configuration: The debugging can provide useful information to decide if the observed
behavior is the correct behavior or the configuration should be modified.
7. Expedite response time: Faster debugging on target traffic can improve the response time to
provide explanations and/or root cause analysis by Citrix engineering and support team.

Please see any task topic in eDocs for documenting tasks. Manual Configuration by using the com-
mand line interface

To configure debug tracing for a profile by using the command line interface

Step 1. Enable tracing for the profile. You can use the show command to verify the configured setting.

• set appfw profile <profile> -trace ON

Step 2. Start collecting trace. You can continue to use all the options which are applicable for the
nstrace command.

• start nstrace -mode APPFW

Stop collecting the trace

• stop nstrace

Location of the trace: The nstrace is stored in a time-stamped folder which is created in the /var/n-
strace directory and can be viewed using wireshark. You can tail the /var/log/ns.log to see the log
messages providing details regarding the location of the new trace.

Tips:

• When –appfw mode option is used, the nstrace will only collect the data for the profile(s) for
which “trace” was enabled.

• Enabling trace on the profile will not automatically start collecting the traces till you explicitly
execute the “start nstrace” command to collect the trace.

• Although, enabling trace on a profile may not have any adverse effect on the performance of the
App Firewall but you may want to enable this feature only for the duration for which you want
to collect the data. It is recommended that you turn the –trace flag off after you have collected
the trace. This will prevent the risk of inadvertently getting data from profiles for which you had
enabled this flag in the past.

• The Block or Log action must be enabled for the security check for the transaction record to be
included in the nstrace.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1800

NetScaler 12.0

• Resets and aborts will be logged independently of security checks actions when trace is “On”
for the profile(s).

• This feature is only applicable for troubleshooting the requests received from the client. The
traces in –appfw mode do not include the responses received from the server.

• You can continue to use all the options which are applicable for the nstrace command. For ex-
ample,

start nstrace -tcpdump enabled -size 0 -mode appFW

• If a request triggers multiple violations, the nstrace for that record will include all the corre-
sponding log messages.

• CEF log message format is supported for this functionality.

• Signature violations triggering block and/or log action for request side checks will also be in-
cluded in the trace.

• Only HTML (non-XML) requests are collected in the trace.

Example of a Log record in the trace:

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

App Firewall support for cluster configurations

September 18, 2018

Contributed by:
C
Note:

App Firewall support for Striped and partially striped configurations was introduced in NetScaler
release 11.0.

A cluster is a group of NetScaler appliances that are configured and managed as a single system. Each
appliance in the cluster is called a node. Depending on the number of nodes the configurations are
active on, cluster configurations are referred to as striped, partially striped, or spotted configurations.
The App Firewall is fully supported in all configurations.

The two main advantages of striped and partially striped virtual server support in cluster configura-
tions are the following:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1801

NetScaler 12.0

1. Session failover support—Striped and partially striped virtual server configurations support ses-
sion failover. The advanced App Firewall security features, such as Start URL Closure and the
Form Field Consistency check, maintain and use sessions during transaction processing. In or-
dinary high availability configurations, or in spotted cluster configurations, when the node that
is processing the App Firewall traffic fails, all the session information is lost and the user has
to reestablish the session. In striped virtual server configurations, user sessions are replicated
across multiple nodes. If a node goes down, a node running the replica becomes the owner.
Session information is maintained without any visible impact to the user.
2. Scalability—Any node in the cluster can process the traffic. Multiple nodes of the cluster can pro-
cess the incoming requests served by the striped virtual server. This improves the App Firewall’s
ability to handle multiple simultaneous requests, thereby improving the overall performance.

Security checks and signature protections can be deployed without the need for any additional
cluster-specific App Firewall configuration. You just do the usual App Firewall configuration on the
configuration coordinator (CCO) node for propagation to all the nodes.

Note:

The session information is replicated across multiple nodes, but not across all the nodes in the
striped configuration. Therefore, failover support accommodates a limited number of simulta-
neous failures. If multiple nodes fail simultaneously, the App Firewall might lose the session
information if a failure occurs before the session is replicated on another node.

Highlights

• App Firewall offers scalability, high throughput, and session failover support in cluster deploy-
ments.
• All App Firewall security checks and signature protections are supported in all cluster configu-
rations.
• Character-Maps are not yet supported for a cluster. The learning engine recommends Field-
Types in learned rules for the Field Format security check.
• Stats and learned rules are aggregated from all the nodes in a cluster.
• Distributed Hash Table (DHT) provides the caching of the session and offers the ability to repli-
cate session information across multiple nodes. When a request comes to the virtual server, the
NetScaler appliance creates App Firewall sessions in the DHT, and can also retrieve the session
information from the DHT.
• Clustering is licensed with the Enterprise and Platinum licenses. This feature is not available
with the Standard license.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1802

NetScaler 12.0

4. App Firewall

Debugging and troubleshooting

September 18, 2018

Contributed by:
C

Refer to the following troubleshooting and debugging information related to each of the App Firewall
functionality:

• Application Firewall - High CPU

• Memory
• Large File Upload Failure
• Learning
• Signatures
• Trace log
• Miscellaneous

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

High CPU

December 18, 2018

Contributed by:
C

Following are some of the functionality and high CPU related debugging issues encoutered and the
best practices to follow when working with App Firewall:

• Check Policy hits, Bindings, Network configuration, App Firewall configuration

• Identify misconfiguration

• Identify vserver that is serving the affected traffic

• Inspect logs in the following log files for security violations and recent configuration changes

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1803

NetScaler 12.0

• /var/log/ns.log

• /var/nslog/import.log

• /var/nslog/aslearn.log

tail -f /var/log/ns.log grep APPFW_SIGNATURE_MATCH

Example:

1 Jun 13 01:11:09 <local0.info> 10.217.31.98 CEF:0|Citrix|NetScaler|NS11

.0|APPFW| APPFW_SIGNATURE_MATCH|6|src=10.217.253.62 spt=61141 method
=GET request= http://aaron.stratum8.net/FFC/wwwboard/passwd.txt msg=
Signature violation rule ID 807: web-cgi /wwwboard/passwd.txt access
cn1=140 cn2=841 cs1=pr_ffc cs2=PPE0 cs3=
OyTgjbXBqcpBFeENKDlde3OkMQ00001 cs4=ALERT cs5=2015 cs6=web-cgi act=
not blocked

• Isolate the traffic that is effected

• Isolate the profile

• Isolate the security check

• Isolate the URL, vserver and traffic parameters

• Conditional profile level trace helps identify the traffic and violation records

• set appfw profile <profile> -trace ON

• start nstrace -mode APPFW -size 0
• stop nstrace

Note: Ensure that the trace is collected with -size 0 option.

• Check appfw, dht, IP reputation activity counters

• nsconmsg -g as_ -g appfwreq_ -g iprep -d current

• Monitor window size for resets in connection

• Appfw sets the window size to 9845 when NetScaler resets the connection due to an invalid http
message.

Examples:

• Malformed request received - connection reset

• High CPU related issues
• Check data sheets for system limits

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1804

NetScaler 12.0

• Inspect for cpu usage, appfw, DHT and memory related activity. Monitor appfw sessions
• nsconmsg -g cc_cpu_use -g appfwreq -g as -g dht -g mem_AS_OBJ -g mem_AS_COMPONENT
-d current

• Monitor memory allocated and freed from App Firewall components and objects during the target
time period. It helps in isolating the protection leading to high CPU usage.

- Profiler output

- Observe logs

• Isolate appfw check leading to high CPU

- startURLClosure

- Formfiledconsistency

- CSRF

- Cookie protections

- Referer header check

Ascertain that autoupdate of signatures is not leading to high CPU (Disable to confirm).

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Memory

September 18, 2018

Contributed by:
C

Following are some of the best practices to follow when encountered with App Firewall usage memory
related issues:

nsconmsg command usage:

• Look for global memory statistics to ascertain that there is enough memory in the system and there
are no memory allocation failures by executing the following command:

* *- nsconmsg -d memstats

• Observe current allocated and maximum memory limits for appsecure, IP reputation, cache and
compression by executing the following command:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1805

NetScaler 12.0

- nsconmsg -d memstats | egrep -i APPSECURE|IPREP|CACHE|CMP

• Check appfw, DHT, IP reputation activity counters by executing the following command:
- nsconmsg -g as -g appfwreq_ -g iprep -d current
• Check all App Firewall error counters by executing the following command:
- nsconmsg -g as_ -g appfwreq_ -g iprep_ -d stats | grep err
• Check all system error counters by executing the following command:
- nsconmsg -g err -d current
• Inspect for CPU, APPFWREQ, AS and DHT counters by executing the following command:
• nsconmsg -g cc_cpu_use -g appfwreq -g as -g dht -d current
• Check the configured Cache memory by executing the following command:
• show cacheparameter
• Check the configured memory by executing the following command:
• nsconmsg -d memstats | egrep -i CACHE
• Identify distribution of memory in App Firewall components and objects:
Display AS_OBJ_ memory:
• nsconmsg -K newnslog -d stats | grep AS_OBJ | egrep -v AppFW_cpu0|total
| sort -k3

Display AS_COMPONENT_ memory:

• nsconmsg -K newnslog -d stats | grep AS_COMPONENT | egrep -v AppFW_cpu0
|total | sort ‒k3

• Check for number of alive sessions by executing the following command:

Monitor/plot active session counts:
• nsconmsg -g as_alive_sessions -d current
Monitor/plot total allocated, free, updated sessions:
• nsconmsg -g as_tot_alloc_sessions -g as_tot_free_sessions -d current
• nsconmsg -g as_tot_update_sessions -d current
If required, reduce session timeout to ensure that session limits are not used by executing the follow-
ing command:
- set appfwsettings -sessionTimeout <300>
If required, set maximum lifetime of session by executing the following command:
- set appfwsettings -sessionLifetime <7200>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1806

NetScaler 12.0

Checking allocated and used memory

To check the total allocated memory and used memory:

• Use the nsconmsg –d memstats command. Observe the MEM_APPSECURE field.

• Use the stat appfw command to obtain meory consumption information.

App Firewall does not automatically delete the logs after certain period of time or size.

• All AppFw logs are archived in the */var/log/ns.log* file. The ns.log file
performs the rollover task.

For more information, refer to the following link: <http://support.citrix.com/article/

CTX121898>

Increasing App Firewall memory:

• There is no CLI option to increase App Firewall memory. App Firewall memory is platform-
specific.
• You may use the nsapimgr option to increase memory but it is not recommended.

The max allowed memory for App Firewall is determined by the platform and disabling IC does not
impact memory allocation.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Large file upload failure

September 18, 2018

Contributed by:
C

When you encounter large file upload failures, ensure that you check the following:

– Misconfigured appfw postbody limit

– Enabled file upload scanning leading to increased processing time

– Hitting system limits

• Since release 11.0, the streaming flag can be enabled on per profile basis to avoid buffering by
executing the following command:

- set appfw profile <profile name> -streaming on

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1807

NetScaler 12.0

• Ensure that the backend server supports chunked requests.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Learning

September 18, 2018

Contributed by:
C

Following are some of the best practices recommended when encountered with Learning functional-
ity issues:

Aslearn process:

• Verify that the process aslearn is running.

• Check top command output

• Check output of ps command by executing the following command:

- ps -ax | grep aslearn | grep -v ”grep”

Example:

1  root@ns\# ps -ax | grep aslearn | grep -v ”grep”

2
3 1439  ??  Ss     0:03.86 /netscaler/aslearn -start -f /netscaler/
aslearn.conf

• Identify recent configuration commands executed prior to the observed problem by verifying the
ns.log file:

• /var/log/ns.log

• Inspect aslearn logs to check for aslearn messages:

• /var/log/aslearn.log

• Isolate the profile and security check that is effected

• Identify the GUI and CLI command which is failing by executing the following command:

• show appfw learningdata <profileName> <securityCheck>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1808

NetScaler 12.0

Examples:

• show learningdata test_profile starturl

• show learningdata test_profile crosssiteScripting

• show learningdata test_profile sqLInjection

• show learningdata test_profile csRFtag

• show learningdata test_profile fieldformat

• show learningdata test_profile fieldconsistency

• Perform integrity check of sqlite from ns prompt:

• nsshell ## sqlite3 /varnslog/asl/<profile_name_in_lowercase>.db pragma

integrity_check;

Examples:

1 - root@ns# sqlite3 /varnslog/asl/tsk0247284.db pragma integrity_check;

2
3 - Error: file is encrypted or is not a database
4
5 - root@ns# sqlite3 /var/nslog/asl/tsk0247284.db pragma integrity_check;

Ok

• Deploy or remove rules to start learning again:

• If 2000 learn items (per protection) are reached, you cannot start learning any more for that
protection

• If 20 MB size is reached for the database, stop learning for all protections

• Restart aslearn process

*/netscaler/aslearn -start -f/netscaler/aslearn.conf*

• Check the space in the /var folder by executing the following:

• du -h /var

• Check the learning threshold limits by executing the following command:

• show appfwlearningsettings <profile_name> <securityCheck>

• Collect learned data by executing the following command:

• export appfwlearningdata <profile_name> <securityCheck>

• Ascertain that learned data is uploaded in the collector.

1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1809

NetScaler 12.0

2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Signatures

September 18, 2018

Contributed by:
C

Getting started with signatures

To add signature:

1. Select the Default-signature and click add to make a copy.

2. Give a meaningful name. The new sig object is added as a User-Defined object.

3. Enable the target rules that are pertinent to your specific need.

– The rules are disabled by default.

– more rules require more processing

4; Configure the actions:

– Block and Log actions are enabled by default. Stats is another option

5; Set the signature to be used by your profile.

Tips for using signatures

• Optimize the processing overhead by enabling only those signatures that are applicable for protect-
ing your application.

• Every pattern in the rule must match to trigger a signature match.

• You can add your own customized rules to inspect incoming requests to detect various types of at-
tacks, such as SQL injection or cross-site scripting attacks.

• You can also add rules to inspect the responses to detect and block leakage of sensitive information
such as credit card numbers.

• Add multiple security check conditions to create your own customized check.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1810

NetScaler 12.0

Best practices for using signatures

Following are some of the best practices you can follow when encountered with issues related to Sig-
natures:

• Verify that the import command has succeeded on primary as well as secondary.

• Verify that CLI and GUI outputs are consistent.

• Check ns.log to identify any errors during signature import and auto update.

• Check if the DNS name server is configured properly.

• Check schema version incompatibility.

• Check if the device is unable to access the Signature Update URL hosted on AWS for auto-update.

• Check for the version mismatch between Default signature and user-added ones.

• Check for version mismatch between signature objects on the primary and secondary nodes.

• Monitor for High CPU Utilization (disable auto-update to rule out issue with signature update).

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Trace Log

September 18, 2018

Contributed by:
C

To record trace logs:

1. Enable tracing for the profile. You can use the show command to verify the configured setting.

set appfw profile <profile> -trace ON

2. Start collecting trace. You can continue to use all the options which are applicable for the nstrace
command.

start nstrace -mode APPFW

3. Stop collecting the trace

stop nstrace

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1811

NetScaler 12.0

Location of the trace: The nstrace is stored in a time-stamped folder which is created in the /var/n-
strace directory and can be viewed using wireshark. You can tail the /var/log/ns.log file to see the log
messages providing details regarding the location of the new trace.

Advantages of trace logs:

– Isolate traffic for specific profile

– Collect data for specific requests

– Identify resets or aborts

• View decrypted SSL traffic: HTTPS traffic is captured in plain text to allow for easier trou-
bleshooting.

– Provides comprehensive view: Allows you to look at the entire request at the packet level, check the
payload, view logs to check what security check violation is being triggered and identify the match
pattern in the payload. If the payload consists of any unexpected data, junk strings, or non-printable
characters (null character, \r or \n etc), they are easy to discover in the trace.

– Expedite response time: Faster debugging on target traffic to do root cause analysis.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

Miscellaneous

September 18, 2018

Contributed by:
C

Following are the resolutions for some of the issues that you might encounter when using App Fire-
wall.

• App Firewall sets window size to 9845 when resetting connection for invalid http messages.

– Malformed request received - connection reset [Client/Server sending invalid content-length

header]

– Unknown content-type in request headers

• System Limit: the application appears frozen

– Occurs when maximum session limit is reached. (100K)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1812

NetScaler 12.0

– Less system memory for operation.

• IP Reputation feature not working

– The iprep process takes about five minutes to start after you enable the reputation feature. The IP
reputation feature might not work for that duration.

• Unexpected App Firewall violations being triggered

– Session timeout has a default value of 900 seconds. If session timeout is set to a low value, browser
may trigger false positives for checks which rely on sessionization (e.g CSRF, FFC). Check for session
timeout and look at the session ID (cs3 in CEF logs). If the sessionID is different, the session timeout
could be the reason.

– If form is dynamically generated by javascript, it may trigger false FFC violations.

• Empty field name in FFC violation logs (prior to 11.0 release)

This may be seen in scenarios where we come across a form field which is not in the forms in our
session.

Scenarios where this may occur:

– The session has timed out from when the form was sent to the client and when it was received.

– The form was generated on the client side using a java script.

1.
2. Citrix ADC
3. NetScaler 12.0
4. App Firewall

References

September 18, 2018

Contributed by:
C

Refer to the following additional reosurces for more information and useful tips when using App Fire-
wall:

• HowNetScaler App Firewall Modifies Application DataTraffic

– Conditional headers modified by App Firewall.

– Integrated caching and App Firewall interoperability.

• TraceHTML Requests with App Firewall Security Violation Logs on NetScalerAppliance

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1813

NetScaler 12.0

–Isolating request and debugging the end-to-end transaction.

• Top Level Protection

• security relaxations

–Information about configuring and deploying.

• Application
• Firewall
• Logs

– Details regarding anatomy of the App Firewall log messages.

• <https://regex101.com/>

– Configuring Regular expressions.

• Datasheets

– Using recommended memory and CPU for system.

– Ensuring enough memory for App Firewall and configuring cache limit appropriately.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Cache Redirection

September 28, 2018

Contributed by:
C

In a typical deployment, different clients ask web servers for the same content repeatedly. To relieve
the origin web server of processing each request, a NetScaler appliance with cache redirection en-
abled can serve this content from a cache server instead of from the origin server.

The NetScaler appliance analyzes incoming requests, sends requests for cacheable data to cache
servers, and sends non-cacheable requests and dynamic HTTP requests to origin servers.

Cache redirection is a policy-based feature. By default, requests that match a policy are sent to the
origin server, and all other requests are sent to a cache server. For testing or maintenance, you might
want to skip policy evaluation and direct all requests to the cache or to the origin server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1814

NetScaler 12.0

You can combine content switching with cache redirection to cache selective content and serve con-
tent from specific cache servers for specific types of requested content.
A NetScaler appliance configured for cache redirection can be deployed at the edge of a network, in
front of the origin server, or anywhere along the network backbone. In an edge deployment, com-
monly used by Internet Service Providers (ISPs), cable companies, content delivery distribution net-
works, and enterprise networks, the NetScaler appliance resides directly in front of the clients. In a
server-side deployment, the NetScaler appliance is closer to the origin servers.
Cache redirection is used most commonly with the HTTP service type, but it also supports the secure
HTTPS protocol.
1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Cache redirection policies

September 19, 2018

Contributed by:
C
A cache redirection virtual server applies cache redirection policies to each incoming request. By
default, if a request matches one of the configured policies, it is considered non-cacheable, and the
NetScaler appliance sends it to the origin server. Other requests are sent to a cache server. This be-
havior can be reversed, so that requests that match configured cache redirection policies are sent to
cache servers.
The appliance provides a set of policies for cache redirection. If these built-in policies are not adequate
for your deployment, you can configure user-defined cache redirection policies.
Note

Once you have determined which built-in cache redirection policies to use, or have created user-
defined policies, proceed with configuring cache redirection. To use this feature, you must con-
figure at least one cache redirection virtual server, and, for normal operation, you must bind at
least one cache redirection policy to that virtual server.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1815

NetScaler 12.0

Built-in cache redirection policies

September 19, 2018

Contributed by:
C

The NetScaler appliance provides built-in cache redirection policies that handle typical cache
requests. These policies are based on HTTP methods, the URL or URL tokens of the incoming request,
the HTTP version, or the HTTP headers and their values in the request.

Built-in cache redirection policies can be directly bound to a virtual server and do not need further
configuration.

Cache redirection policies use two types of appliance expressions languages, classic and default syn-
tax. For more information about these languages, see Policies and expressions.

Built-in classic cache redirection policies

Built-in cache redirection policies based on classic expressions are called

classic cache redirection policies. For a complete description of classic expressions and how to config-
ure them, see
Policies and Expressions.

The classic cache redirection policies evaluate basic characteristics of traffic and other data. For exam-
ple, classic cache redirection policies can determine whether an HTTP request or response contains
a particular type of header or URL.

The NetScaler appliance provides the following built-in classic cache redirection policies:

Built-In Policy Name Description

bypass-non-get Bypass the cache if the request uses an HTTP

method other than GET.
bypass-cache-control Bypass the cache if the request header
contains a Cache-Control: no-cache or
Cache-Control: no-store header, or if the HTTP
request contains a pragma header.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1816

NetScaler 12.0

Built-In Policy Name Description

bypass-dynamic-url Bypass the cache if the URL suggests that the

content is dynamic, as indicated by the
presence of any of the following extensions:
cgi, asp, exe, cfm, ex, shtml, or htx. Also bypass
the cache if the URL starts with any of the
following: /cgi-bin/, /bin/, or /exec/.
bypass-urltokens Bypass the cache because the request is
dynamic, as indicated by one of the following
tokens in the URL: ?, !, or =.
bypass-cookie Bypass the cache for any URL that has a cookie
header and an extension other than .gif or .jpg.

Built-in default syntax cache redirection policies

Built-in cache redirection policies based on default syntax expressions are called
default syntax cache redirection policies. For a complete description of default syntax expressions and
how to configure them, see
Policies and Expressions.

In addition to the same types of evaluations done by classic cache redirection policies, default syntax
cache redirection policies enable you to analyze more data (for example, the body of an HTTP request)
and to configure more operations in the policy rule (for example, directing the request to either cache
or origin server).

NetScaler appliances provide the following two built-in actions for the default syntax cache redirec-
tion policies:

• CACHE
• ORIGIN

As implied by their names, they direct the request to the cache server or the origin server, respectively.

Note

If you are using the built-in default syntax cache redirection policy, you cannot modify the action.

The NetScaler appliance provides the following built-in default syntax cache redirection policies:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1817

NetScaler 12.0

Built-In Policy Name Description

bypass-non-get_adv Bypass the cache if the request uses an HTTP

method other than GET.
bypass-cache-control_adv Bypass the cache if the request header
contains a Cache-Control: no-cache or
Cache-Control: no-store header, or if the HTTP
request contains a pragma header.
bypass-dynamic-url_adv Bypass the cache if the URL suggests that the
content is dynamic, as indicated by the
presence of any of the following extensions:
cgi, asp, exe, cfm, ex, shtml, or htx. Also bypass
the cache if the URL starts with any of the
following: /cgi-bin/, /bin/, or /exec/.
bypass-urltokens_adv Bypass the cache because the request is
dynamic, as indicated by one of the following
tokens in the URL: ?, !, or =.
bypass-cookie_adv Bypass the cache for any URL that has a cookie
header and an extension other than .gif or .jpg.

Display the built-in cache redirection policies

You can display the available cache redirection polices by using the command line interface or the
configuration utility.

Display the built-in cache redirection policies by using the CLI

At the command prompt, type:

show cr policy [<policyName>]

Example:

1 > show cr policy

2 1) Cache-By-Pass RULE: NS_NON_GET Policy:bypass-non-get
3 2) Cache-By-Pass RULE: (NS_CACHECONTROL_NOSTORE ||
NS_CACHECONTROL_NOCACHE || NS_HEADER_PRAGMA) Policy:bypass-cache-
control
4 3) Cache-By-Pass RULE: (NS_EXT_CGI || NS_EXT_ASP || NS_EXT_EXE ||
NS_EXT_CFM || NS_EXT_EX || NS_EXT_SHTML || NS_EXT_HTX) || (

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1818

NetScaler 12.0

NS_URL_PATH_CGIBIN || NS_URL_PATH_EXEC || NS_URL_PATH_BIN)

Policy:bypass-dynamic-url
5 4) Cache-By-Pass RULE: NS_URL_TOKENS Policy:bypass-
urltokens
6 5) Cache-By-Pass RULE: (NS_HEADER_COOKIE && NS_EXT_NOT_GIF &&
NS_EXT_NOT_JPEG) Policy:bypass-cookie
7 Done

Display the built-in cache redirection policies by using the GUI

1. Navigate to Traffic Management > Cache Redirection > Policies. The configured cache redirec-
tion policies appear in the details pane.
2. Select one of the configured policies to view details.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Configure a cache redirection policy

September 19, 2018

Contributed by:
C

A cache redirection policy includes one or more expressions (also called rules). Each expression rep-
resents a condition that is evaluated when the client request is compared to the policy.

You do not explicitly configure actions for cache redirection policies. By default, the NetScaler appli-
ance considers any request that matches a policy to be non-cacheable and directs the request to the
origin server instead of the cache.

Cache redirection policies based on the classic policy format are called classic cache redirection poli-
cies. Each such policy has a name and includes a classic expression or a set of classic expressions that
are combined by using logical operators.

For classic cache redirection policies, you do not explicitly configure actions for the policies. By de-
fault, the NetScaler appliance considers any request that matches a policy to be non-cacheable and
directs the request to the origin server instead of the cache.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1819

NetScaler 12.0

Cache redirection policies based on the newer policy format are called
Advanced redirection policies. Such policy has a name and includes a default syntax expression, or
a set of default syntax expressions that are combined by using logical operators, and the following
built-in actions:

• CACHE
• ORIGIN

For more information about classic expressions and default syntax expressions, see
Policies and Expressions.

Add a cache redirection policy by using the CLI

At the command prompt, type the following commands to add a cache redirection policy and verify
the configuration:

1 - add cr policy <policyName> **-rule** <expression>

2 - show cr policy [<policyName>]

Examples:

Policy with a simple expression:

1 > add cr policy Policy-CRD-1 -rule ”REQ.HTTP.URL != /*.jpeg”

2 Done
3 > show cr policy Policy-CRD-1
4 Cache-By-Pass RULE: REQ.HTTP.URL != ’/*.jpeg’ Policy:Policy-
CRD-1
5 Done

Policy with a compound expression:

1 > add cr policy Policy-CRD-2 -rule ”REQ.HTTP.METHOD == POST && (REQ.

HTTP.URL == /*.cgi || REQ.HTTP.URL != /*.gif)”
2 Done
3 > show cr policy Policy-CRD-2
4 Cache-By-Pass RULE: REQ.HTTP.METHOD == POST && (REQ.HTTP.URL
== ’/*.cgi’ || REQ.HTTP.URL != ’/*.gif’) Policy:Policy-
CRD-2
5 Done

Policy that evaluates a header:

1 > add cr policy Policy-CRD-3 -rule ”REQ.HTTP.HEADER If-Modified-Since

EXISTS”

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1820

NetScaler 12.0

2 Done
3 > show cr policy Policy-CRD-3
4 Cache-By-Pass RULE: REQ.HTTP.HEADER If-Modified-Since EXISTS
Policy:Policy-CRD-3
5 Done

Add a default syntax cache redirection policy by using the CLI

At the command prompt, type the following commands to add a cache redirection policy and verify
the configuration:

1 - add cr policy <policyName> **-rule** <expression> [-action<string>]

[-logAction<string>]
2 - show cr policy [<policyName>]

Examples:

Policy with a simple expression:

1 > add cr policy crpol1 -rule !(HTTP.REQ.URL.ENDSWITH(”.jpeg ” )) -action

origin
2 Done
3 > show cr policy crpoll
4 Policy: crpol1 Rule: !(HTTP.REQ.URL.ENDSWITH(”.jpeg”)) Action:
ORIGIN
5 Done

Policy with a compound expression:

1 > add cr policy crpol11 -rule ”http.req.method.eq(post) && (HTTP.REQ.

URL.ENDSWITH(”.gif”) || HTTP.REQ.URL.ENDSWITH(”.cgi”))” -action
cache
2 Done
3 > show cr policy crpol11
4 Policy: crpol11 Rule: http.req.method.eq(post) && (HTTP.REQ
.URL.ENDSWITH(”.gif”) || HTTP.REQ.URL.ENDSWITH(”.cgi”))
Action: CACHE
5 Done

Policy that evaluates a header:

1 > add cr policy crpol12 -rule http.req.header(”If-Modified-Since”).

exists -action origin
2 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1821

NetScaler 12.0

3 > show cr policy crpol12

4 Policy: crpol12 Rule: http.req.header(”If-Modified-Since”).
exists Action: ORIGIN
5 Done

Modify or remove a cache redirection policy by using the CLI

• To modify a cache redirection policy, use the set cr policy command, which is just like add cr
policy command, except that you enter the name of an existing policy.
• To remove a policy, use the rm cr policy command, which accepts only the <name> argu-
ment. If the policy is bound to a virtual server, you have to unbind the policy, before you can
remove it.

For the details of unbinding a cache redirection policy, see “Unbind a policy from a cache redirection
virtual server.”

Configure a cache redirection policy with a simple expression by using the GUI

1. Navigate to Traffic Management > Cache Redirection > Policies.

2. In the details pane, click Add.

3. In the Create Cache Redirection Policy dialog box, in the Name* text box, type the name of the
policy, and then in the Expression area, click Add.

4. To configure a simple expression, enter the expression. Following is an example of an expression

that checks for a .jpeg extension in a URL:

• Expression Type-General
• Flow Type -REQ
• Protocol -HTTP
• Qualifier -URL
• Operator - !=
• Value* - /*.jpeg

The simple expression in the following example checks for an If-Modified-Since header in a re-
quest:

• Expression Type -General

• Flow Type -REQ
• Protocol -HTTP
• Qualifier -HEADER
• Operator -EXISTS

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1822

NetScaler 12.0

• Header Name -If-Modified-Since

5. When you are finished entering the expression, click OK or Create, and then click Close.

Configure a cache redirection policy with a compound expression by using the GUI

1. Navigate to Traffic Management > Cache Redirection > Policies.

2. In the details pane, click Add.

3. In the Name text box, enter a name for the policy.

The name can begin with a letter, number, or the underscore symbol, and can consist of from
one to 127 letters, numbers, and the hyphen (-), period (.) pound (#), space ( ), at (@), equals (=),
and underscore (_) symbols. You should choose a name that will make it easy for others to tell
what type of content this policy was created to detect.

4. Choose the type of compound expression that you want to create. Your choices are:

• Match Any Expression. The policy matches the traffic if one or more individual expres-
sions match the traffic.

• Match All Expressions. The policy matches the traffic only if every individual expression
matches the traffic.

• Tabular Expressions. Switches the Expressions list to a tabular format with three
columns. In the rightmost column, you place one of the following operators:

– The AND [ && ] operator, to require that, to match the policy, a request must match
both the current expression and the following expression.

The OR [ ] operator, to require that, to

match the policy, a request
must match either the current
expression or the following
expression, or both. Only if
the request does not match
either expression does it not
match the policy.

You can also group expressions in nested subgroups by selecting an existing expression
and clicking one of the following operators:

– The BEGIN SUBGROUP [+ ( ] operator, which tells the NetScaler appliance to begin

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1823

NetScaler 12.0

a nested subgroup with the selected expression. (To remove this operator from the
expression, click -( .)
– The END SUBGROUP [+ ) ] operator, which tells the NetScaler appliance to end the
current nested subgroup with the selected expression. (To remove this operator from
the expression, click -) .)

• Advanced Free-Form. Switches off the Expressions Editor entirely and turns the Expres-
sions list into a text area in which you can type a compound expression. This is both the
most powerful and the most difficult method of creating a policy expression, and is rec-
ommended only for those thoroughly familiar with the NetScaler appliance classic expres-
sions language.

For more information about creating classic expressions in the Advanced Free-Form text
area, see “Configuring Classic Policies and Expressions”.

Caution: If you switch to Advanced Free Form expression editing mode, you cannot switch
back to any of the other modes. Do not choose this expression editing mode unless you
are sure that you want to use it.

5. If you chose Match Any Expression, Match All Expressions, or Tabular Expressions, click Add to
display the Add Expression dialog box.

You should leave the expression type set to General for cache redirection policies.

6. In the Flow Type drop-down list, choose a flow type for your expression.

The flow type determines whether the policy examines incoming or outgoing connections. You
have two choices:

• REQ. Configures the NetScaler appliance to examine incoming connections, or requests.

• RES. Configures the appliance to examine outgoing connections, or responses.

7. In the Protocol drop-down list, choose a protocol for your expression.

The protocol determines the type of information that the policy examines in the request or re-
sponse. Depending upon whether you chose REQ or RES in the previous drop-down list, either
all four or only three of the following choices are available:

• HTTP. Configures the appliance to examine the HTTP header.

• SSL. Configures the appliance to examine the SSL client certificate. Available only if you
chose REQ (requests) in the previous drop-down list.
• TCP. Configures the appliance to examine the TCP header.
• IP. Configures the appliance to examine the source or destination IP address.

8. Choose a qualifier for your expression from the Qualifier drop-down list.

The contents of the Qualifier drop-down list depend on which protocol you chose. The following
table describes the choices available for each protocol.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1824

NetScaler 12.0

Table 1. Cache Redirection Policy Qualifiers Available for Each Protocol

Protocol Qualifier Definition

HTTP METHOD HTTP method used in the

request.
- URL Contents of the URL header.
- URLTOKENS URL tokens in the HTTP
header.
- VERSION HTTP version of the
connection.
- HEADER Header portion of the HTTP
request.
- URLLEN Length of the contents of the
URL header.
- URLQUERY Query portion of the contents
of the URL header.
- URLQUERYLEN Length of the query portion of
the URL header.
SSL CLIENT.CERT SSL client certificate as a
whole.
- CLIENT.CERT.SUBJECT Contents of the client
certificate subject field.
- CLIENT.CERT.ISSUER Client certificate issuer.
- CLIENT.CERT.SIGALGO Signature algorithm used in
the client certificate.
- CLIENT.CERT.VERSION Client certificate version.
- CLIENT.CERT.VALIDFROM Date from which the client
certificate is valid. (The start
date.)
- CLIENT.CERT.VALIDTO Date after which the client
certificate is no longer valid.
(The end date.)
- CLIENT.CERT.SERIALNUMBER Client certificate serial
number.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1825

NetScaler 12.0

Protocol Qualifier Definition

- CLIENT.CIPHER.TYPE Encryption method used in

the client certificate.
- CLIENT.CIPHER.BITS Number of significant bits in
the encryption key.
- CLIENT.SSL.VERSION SSL version of the client
certificate.
TCP SOURCEPORT Source port of the TCP
connection.
- DESTPORT Destination port of the TCP
connection.
- MSS Maximum segment size (MSS)
of the TCP connection.
IP SOURCEIP Source IP address of the
connection.
- DESTIP Destination IP address of the
connection.

9. Choose the operator for your expression from the Operator drop-down list.

Your choices depend on the qualifier you chose in the previous step. The complete list of oper-
ators that can appear in this drop-down list is:

• == . Matches the following text string exactly.

• != . Does not match the following text string.

• . Is greater than the following integer.

• CONTAINS . Contains the following text string.

• CONTENTS . The contents of the designated header, URL, or URL query.

• EXISTS . The specified header or query exists.

• NOTCONTAINS . Does not contain the following text string.

• NOTEXISTS . The specified header or query does not exist.

If you want this policy to operate on requests sent to a specific Host, you can leave the default,
the equals (==) sign.

10. If the Value text box is visible, type the appropriate string or number into the text box.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1826

NetScaler 12.0

For example, if you want this policy to select requests sent to the host shopping.example.com,
you would type that string in the Value text box.

11. If you chose HEADER as the qualifier, type the header you want in the Header Name text box.

12. Click OK to add your expression to the Expression list.

13. Repeat steps 4 through 11 to create additional expressions.

14. Click Close to close the Add Expression dialog box and return to the Create Cache Redirection
Policy dialog box.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Cache redirection configurations

September 19, 2018

Contributed by:
C

Depending on your deployment and network topology, you can configure one of the following types
of cache redirection:

• Transparent. A transparent cache can reside on a variety of points along a network backbone
to alleviate traffic along the delivery route. In transparent mode, the cache redirection virtual
server intercepts all traffic flowing to the NetScaler appliance and applies cache redirection poli-
cies to determine whether content should be served from the cache or from the origin server.
• Forward proxy. A forward proxy cache server resides on the edge of an enterprise LAN and faces
the WAN. In the forward proxy mode, the cache redirection virtual server resolves the hostname
of the incoming request by using a DNS server and forwards requests for non-cacheable content
to the resolved origin servers. Cacheable requests are sent to the configured cache servers.
• Reverse proxy. Reverse proxy caches are configured for specific origin servers. Incoming traffic
directed to the reverse proxy, can either be served from a cache server or be sent to the origin
server with or without modification to the URL.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1827

NetScaler 12.0

Configure transparent redirection

September 19, 2018

Contributed by:
C

When you configure transparent cache redirection, the NetScaler appliance evaluates all traffic it re-
ceives, to determine whether it is cacheable. This mode alleviates traffic along the delivery route and
is often used when the cache server resides on the backbone of an ISP or carrier.

By default, cacheable requests are sent to a cache server, and non-cacheable requests to the origin
server. For example, when the NetScaler appliance receives a request that is directed to a web server,
it compares the HTTP headers in the request with a set of policy expressions. If the request does not
match the policy, the appliance forwards the request to a cache server. If the request does match a
policy, the appliance forwards the request, unchanged, to the web server.

For details on how to modify this default behavior, see “Direct policy hits to the cache instead of the
origin.”

To configure transparent redirection, first enable cache redirection and load balancing, and configure
edge mode. Then, create a cache redirection virtual server with a wildcard IP address (*), so that this
virtual server can receive traffic coming to the appliance on any IP address the appliance owns. To this
virtual server, bind cache redirection policies that describe the types of requests that should not be
cached. Then, create a load balancing virtual server that will receive traffic from the cache redirection
virtual server for cacheable requests. Finally, create a service that represents a physical cache server
and bind it to the load balancing virtual server.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Enable cache redirection and load balancing

September 19, 2018

Contributed by:
C

The appliance cache redirection and load balancing features are not enabled by default. They must
be enabled before any cache redirection configuration can take effect.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1828

NetScaler 12.0

Enable cache redirection and load balancing by using the CLI

At the command prompt, type the following command to enable cache redirection and load balancing
and verify the settings:

1 - enable ns feature cr lb
2 - show ns feature

Example:

1 > enable ns feature cr lb

2 Done
3 > show ns feature
4
5 Feature Acronym Status
6 ------- ------- ------
7 1) Web Logging WL ON
8 2) Surge Protection SP ON
9 3) Load Balancing LB ON
10 4) Content Switching CS ON
11 5) Cache Redirection CR ON
12 6) Sure Connect
13
14 ...
15 ...
16 ...
17
18 23) HTML Injection HTMLInjection ON
19 24) appliance Push push OF
20 Done

Enable cache redirection and load balancing by using the GUI

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

2. To enable cache redirection, in the details pane, under Modes and Features, click Configure ad-
vanced features.
a) In Configure Advanced Features dialog box, select the check box next to the Cache Redi-
rection, and then click OK.
b) In Enable/Disable Feature(s)? dialog box, click Yes.
3. To enable load balancing, in the details pane, under Modes and Features, click Configure basic
features.
a) In Configure Basic Features dialog box, select the check box next to the Load Balancing,
and then click OK.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1829

NetScaler 12.0

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

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Configure edge mode

September 19, 2018

Contributed by:
C

When deployed at the edge of a network, the NetScaler appliance dynamically learns about the
servers on that network. Edge mode enables the appliance to dynamically learn about up to 40,000
HTTP servers and proxy TCP connections for these servers.

This mode turns on the collection of statistics for the dynamically learned services and is typically
used in transparent deployments for cache redirection.

Enable edge mode by using the CLI

At the command prompt, type the following commands to enable edge mode and verify the setting:

1 - enable ns mode Edge

2 - show ns mode

Example:

1 > enable ns mode edge

2 Done
3
4 > show ns mode
5
6 Mode Acronym Status
7 ------- ------- ------
8 ...
9 ...
10 ...
11 6) MAC-based forwarding MBF ON
12 7) Edge configuration Edge ON
13 8) Use Subnet IP USNIP OFF

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1830

NetScaler 12.0

14 ...
15 ...
16 ...
17 16) Bridge BPDUs BridgeBPDUs OFF
18 Done

Enable edge mode by using the GUI

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

2. In the details pane, under Modes and Features, click Configure modes.
3. In Configure Modes dialog box, select the check box next to the Edge Configuration, and then
click OK.
4. In Enable/Disable Feature(s)? dialog box, click Yes.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Configure a cache redirection virtual server

September 19, 2018

Contributed by:
C

By default, a cache redirection virtual server forwards cacheable requests to the load balancing virtual
server for the cache, and forwards non-cacheable requests to the origin server (except in a reverse
proxy configuration, in which non-cacheable requests are sent to a load balancing virtual server).
There are three types of cache redirection virtual servers: transparent, forward proxy, and reverse
proxy.

A transparent cache redirection virtual server uses an IP address of * and a port number, usually 80,
that can accept HTTP traffic sent to any IP address that the appliance represents. As a result, you
can configure only one transparent cache redirection virtual server. Any additional cache redirection
virtual servers that you configure must be forward proxy or reverse proxy redirection servers.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1831

NetScaler 12.0

add a cache redirection virtual server in transparent mode by using the cli

At the command prompt, type the following commands to add a cache redirection virtual server and
verify the configuration:

1 - add cr vserver <name> <serviceType> [<IPAddress> <port> ] [-

cacheType <cacheType>] [-redirect <redirect>]
2 - show cr vserver [<name>]

Example:

1add cr vserver Vserver-CRD-1 HTTP * 80 -cacheType TRANSPARENT -redirect

POLICY
2 > show cr vserver Vserver-CRD-1
3 Vserver-CRD-1 (*:80) - HTTP Type: CONTENT
4 State: UP ARP:DISABLED
5 Client Idle Timeout: 180 sec
6 Down state flush: ENABLED
7 Disable Primary Vserver On Down : DISABLED
8 Default: Content Precedence: RULE Cache:
TRANSPARENT
9 On Policy Match: ORIGIN L2Conn: OFF OriginUSIP: OFF
10 Redirect: POLICY Reuse: ON Via: ON ARP: OFF
11 Done

Modify or remove a cache redirection virtual server by using the CLI

• To modify a virtual server, use the set cr vserver command, which is just like using the add cr
vserver command, except that you enter the name of an existing virtual server.
• To remove a virtual server, use the rm cr vserver command, which accepts only the <name>
argument.

Add a cache redirection virtual server in transparent mode by using the GUI

1. Navigate to Traffic Management > Cache Redirection > Virtual Servers.

2. In the details pane, click Add.

3. In the Create Virtual Server (Cache Redirection) dialog box, specify values for the following pa-
rameters as shown:

• Name*—name
• Port*—port

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1832

NetScaler 12.0

*A required parameter

4. In the Protocol drop-down list, select a supported protocol (for example, HTTP). If the virtual
server is to receive traffic on a port other than the standard port for the selected protocol, enter
a new value in the Port field.

5. Click the Advanced tab.

6. Verify that Cache Type is set to TRANSPARENT and Redirect is set to POLICY.

7. Click Create, and then click Close. The Cache Redirection Virtual Servers pane displays the new
virtual server.

8. Select the new cache redirection virtual server to display the details of its configuration.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Bind policies to the cache redirection virtual server

September 19, 2018

Contributed by:
C

Cache redirection policies are not automatically bound to the cache redirection virtual server. A policy
based cache redirection virtual server cannot function unless you bind at least one policy to it.

Bind policies to a cache redirection virtual server by using the CLI

At the command prompt, type:

1 - bind cr vserver <name> -policyName <string>

2 - show cr vserver [<name>]

Example:

1 > bind cr vserver Vserver-CRD-1 -policyName bypass-cache-control

2 Done
3 > bind cr vserver Vserver-CRD-1 -policyName bypass-dynamic-url
4 Done
5 > bind cr vserver Vserver-CRD-1 -policyName bypass-urltokens

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1833

NetScaler 12.0

6 Done
7 > bind cr vserver Vserver-CRD-1 -policyName bypass-cookie
8 Done
9
10 > show cr vserver Vserver-CRD-1
11 Vserver-CRD-1 (*:80) - HTTP Type: CONTENT
12 State: UP ARP:DISABLED
13 Client Idle Timeout: 180 sec
14 Down state flush: ENABLED
15 Disable Primary Vserver On Down : DISABLED
16 Default: Content Precedence: RULE Cache:
TRANSPARENT
17 On Policy Match: ORIGIN L2Conn: OFF OriginUSIP: OFF
18 Redirect: POLICY Reuse: ON Via: ON ARP: OFF
19
20 1) Cache bypass Policy: bypass-cache-control
21 2) Cache bypass Policy: bypass-dynamic-url
22 3) Cache bypass Policy: bypass-urltokens
23 4) Cache bypass Policy: bypass-cookie
24 Done

Bind a user-defined policy to a cache redirection virtual server by using the GUI

1. Navigate to Traffic Management > Cache Redirection > Virtual Servers.

2. Click the virtual server that you want to configure, and click Open.
3. On the Policies tab, select type of the policy and then click Insert Policy.
4. Under Policy Name column, select the policy that you want to bind.
5. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Unbind a policy from a cache redirection virtual server

September 19, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1834

NetScaler 12.0

When you unbind a policy from the cache redirection virtual server, the NetScaler appliance no longer
applies the policy when evaluating client requests.

Unbind a policy from a cache redirection virtual server by using the command CLI

At the command prompt, type:

1 - unbind cr vserver <name> -policyName <string>

2 - show cr vserver [<name>]

Example:

1 unbind cr vserver Vserver-CR-1 -policyName bypass-non-get

2 > show cr vserver Vserver-CRD-1
3 Vserver-CRD-1 (*:80) - HTTP Type: CONTENT
4 State: UP ARP:DISABLED
5 Client Idle Timeout: 180 sec
6 Down state flush: ENABLED
7 Disable Primary Vserver On Down : DISABLED
8 Default: Content Precedence: RULE Cache:
TRANSPARENT
9 On Policy Match: ORIGIN L2Conn: OFF OriginUSIP: OFF
10 Redirect: POLICY Reuse: ON Via: ON ARP: OFF
11
12 1) Cache bypass Policy: bypass-cache-control
13 Done

Unbind a user-defined policy from a cache redirection virtual server by using the GUI

1. Navigate to Traffic Management > Cache Redirection > Virtual Servers.

2. Click the virtual server that you want to configure, and then click Open.
3. On the Policies tab, under Policy Name, select the policy that you want to unbind.
4. Click Unbind Policy, and then click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1835

NetScaler 12.0

Create a load balancing virtual server

September 19, 2018

Contributed by:
C

The cache redirection virtual server on the NetScaler appliance can send requests to either a cache
server farm, if the request is cacheable, or to the origin server farm if the request is not cacheable.

Each cache server is represented on the appliance by a service, which is bound to a load balancing
virtual server that receives requests from the cache redirection virtual server and forwards those re-
quests to the servers.

For details on configuring load balancing virtual servers and other configuration options, see “Load
Balancing.”

Create a load balancing virtual server by using the CLI

At the command prompt, type the following commands to create a load balancing virtual server and
verify the configuration:

1 - add lb vserver <name> <serviceType> [<IPAddress>] [<port>]

2 - show lb vserver [<name>]

Example:

1 > add lb vserver Vserver-LB-CR HTTP 10.102.20.30 80

2 Done
3 > show lb vserver Vserver-LB-CR
4 Vserver-LB-CR (10.102.20.30:80) - HTTP Type: ADDRESS
5 State: DOWN
6 Last state change was at Fri Jul 2 08:47:52 2010
7 Time since last state change: 0 days, 00:00:08.470
8 Effective State: DOWN
9 Client Idle Timeout: 180 sec
10 Down state flush: ENABLED
11 Disable Primary Vserver On Down : DISABLED
12 Port Rewrite : DISABLED
13 No. of Bound Services : 0 (Total) 0 (Active)
14 Configured Method: LEASTCONNECTION
15 Mode: IP
16 Persistence: NONE
17 Vserver IP and Port insertion: OFF

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1836

NetScaler 12.0

18 Push: DISABLED Push VServer:

19 Push Multi Clients: NO
20 Push Label Rule: none
21 Done

Create a load balancing virtual server by using the GUI

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.

2. In the details pane, click Add.

3. In the Create Virtual Server (Load Balancing) dialog box, specify values for the following param-
eters as shown:

• Name*-name
• IP Address*- IPAddress
• Port*-port

*A required parameter

4. In the Protocol list, select a supported protocol (for example, HTTP). If the virtual server is to
receive traffic on a port other than the well-known port for the selected protocol, enter a new
value in the Port field.

5. Click Create, and then click Close. The Load Balancing Virtual Servers pane displays the new
virtual server.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Configure an HTTP service

September 19, 2018

Contributed by:
C

On the NetScaler appliance, a service represents a physical server on the network. In the transparent
cache redirection configuration, the service represents the cache server. Cacheable requests are sent
by the cache redirection virtual server to the load balancing virtual server, which in turn forwards each
request to the correct service, which passes it on to the cache server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1837

NetScaler 12.0

Configure an HTTP service by using the CLI

At the command prompt, type the following commands to create an HTTP service and verify the con-
figuration:

1 - add service <name> <IP> <serviceType> <port> -cacheType <cacheType>

2 - show service [<name>]

Example:

1 > add service Service-HTTP-1 10.102.29.40 HTTP 80 -cacheType

TRANSPARENT
2 Done
3 > show service Service-HTTP-1
4 Service-HTTP-1 (10.102.29.40:80) - HTTP
5 State: DOWN
6 Last state change was at Fri Jul 2 09:14:17 2010
7 Time since last state change: 0 days, 00:00:13.820
8 Server Name: 10.102.29.40
9 Server ID : 0 Monitor Threshold : 0
10 Max Conn: 0 Max Req: 0 Max Bandwidth: 0 kbits
11 Use Source IP: NO
12 Client Keepalive(CKA): NO
13 Access Down Service: NO
14 TCP Buffering(TCPB): NO
15 HTTP Compression(CMP): YES
16 Idle timeout: Client: 180 sec Server: 360 sec
17 Client IP: DISABLED
18 Cache Type: TRANSPARENT Redirect Mode:
19 Cacheable: NO
20 SC: OFF
21 SP: ON
22 Down state flush: ENABLED
23
24 1) Monitor Name: tcp-default
25 State: DOWN Weight: 1
26 Probes: 3 Failed [Total: 3 Current: 3]
27 Last response: Failure - Time out during TCP connection
establishment stage
28 Response Time: N/A
29 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1838

NetScaler 12.0

Modify or remove a service by using the CLI

• To modify a service, use the set service command, which is just like using the add service com-
mand, except that you enter the name of an existing service.
• To remove a service, use the rm service command, which accepts only the <name> argument.

Add an HTTP service by using the GUI

1. Navigate to Traffic Management > Load Balancing > Services

2. In the details pane, click Add.

3. In the Create Service dialog box, specify values for the following parameters as shown:

• Service Name*—name
• Server*— IP
• Port*—port

*A required parameter

4. In the Protocol* drop-down list, select a supported protocol (for example, HTTP).

5. Click Create, and then click Close.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Bind/unbind a service to/from a load balancing virtual server

September 19, 2018

Contributed by:
C

You must bind a service to the load balancing virtual server. This enables the load balancer to forward
the request to the server that the service represents. If your configuration changes, you can unbind a
service from the load balancing virtual server.

Bind a service to a load balancing virtual server by using the CLI

At the command prompt, type:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1839

NetScaler 12.0

1 - bind lb vserver <name> <serviceName>

2 - show lb vserver [<name>]

Example:

1 > bind lb vserver vserver-LB-CR service-HTTP-1

2 Done
3 > show lb vserver Vserver-LB-CR
4 Vserver-LB-CR (10.102.20.30:80) - HTTP Type: ADDRESS
5 State: DOWN
6 Last state change was at Fri Jul 2 08:47:52 2010
7 Time since last state change: 0 days, 00:42:25.610
8 Effective State: DOWN
9 Client Idle Timeout: 180 sec
10 Down state flush: ENABLED
11 Disable Primary Vserver On Down : DISABLED
12 Port Rewrite : DISABLED
13 No. of Bound Services : 1 (Total) 0 (Active)
14 Configured Method: LEASTCONNECTION
15 Mode: IP
16 Persistence: NONE
17 Vserver IP and Port insertion: OFF
18 Push: DISABLED Push VServer:
19 Push Multi Clients: NO
20 Push Label Rule: none
21
22 1) Service-HTTP-1 (10.102.29.40: 80) - HTTP State: DOWN Weight: 1
23 Done

Unbind a service from a load balancing virtual server by using the CLI

To unbind a service, use the unbind lb vserver command instead of bind lb vserver.

Bind/unbind a service from a load balancing virtual server by using the GUI

1. Navigate to Traffic Management > Load Balancing > Virtual Servers

2. In the details pane, select the virtual server from which you want to bind/unbind the service,
and then click Open.
3. On the Services tab, in the Active column, select/clear the check box next to the Service Name.
4. Click OK.

1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1840

NetScaler 12.0

2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Disable the use the proxy port setting for transparent caching

September 19, 2018

Contributed by:
C
If the use source IP (USIP) option is disabled on a cache service configured on the NetScaler appliance,
the appliance forwards client requests to the cache service by using a appliance-owned subnet IP
(SNIP) address or mapped IP (MIP) address as the source IP address and a random port as the source
port. The randomly selected port is called the proxy port.
However, if you want to configure a fully transparent cache (a cache configuration in which the cache
service receives the client’s IP address and port number), you must not only enable the USIP option,
either globally or on the cache service, but also disable the Use Proxy Port setting, either globally or
on the cache service. Disabling the Use Proxy Port setting enables the appliance to use the client’s
source port as the source port when it connects to the cache service, and ensures a fully transparent
cache configuration.
For more information about configuring the Use Proxy Port option globally or on a service, see Con-
figuring the Source Port for Server-Side Connections.
1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Assign a port range to the NetScaler appliance

September 19, 2018

Contributed by:
C
Sharing of the client IP address may create a conflict that makes network devices, such as routers,
cache servers, origin servers, and other NetScaler appliances, unable to determine the appliance, and
therefore the client, to which the response should be sent.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1841

NetScaler 12.0

A method to solve this problem is to assign a source port range to the NetScaler appliance. This al-
lotment enables network devices to unambiguously identify the NetScaler appliance that sent the
request.

Assign a source port range to a NetScaler appliance by using the CLI

At the command prompt, type:

set ns param -crPortRange <startPortNumber-endPortNumber>

Assign a source port range to a NetScaler appliance by using the appliance GUI

1. In the navigation pane, click System, and then click Settings.

2. In the Settings group, click the Change global system settings link.
3. In the Cache Redirection Port Range group, specify the port range for the appliance by typing a
port number for Start Port and a port number for End Port.
4. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Enable load balancing virtual servers to redirect requests to cache

September 19, 2018

Contributed by:
C

If a load balancing virtual server is configured to listen on a particular IP address and port combina-
tion, it takes precedence over the cache redirection virtual server for any requests destined for that
address-port combination. Therefore, the cache redirection virtual server does not process those re-
quests.

If you want to override this functionality and let the cache redirection virtual server decide whether
the request should be served from the cache or not, configure the particular load balancing virtual
server to be cacheable.

Such a configuration is typically used when an ISP uses a NetScaler appliance at the edge of its net-
work and all traffic flows through the appliance.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1842

NetScaler 12.0

Enable load balancing virtual servers to redirect requests to the cache by using the CLI

At the command prompt, type:

1 - set lb vserver <name> [-cacheable ( YES | NO)]

2 - show lb vserver [<name>]

Example:

1 set lb vserver Vserver-LB-CR ‒ cacheable YES

2 > show lb vserver vserver-LB-CR
3 Vserver-LB-CR (10.102.20.30:80) - HTTP Type: ADDRESS
4 State: DOWN
5 Last state change was at Fri Jul 2 08:47:52 2010
6 Time since last state change: 0 days, 01:05:51.510
7 Effective State: DOWN
8 Client Idle Timeout: 180 sec
9 Down state flush: ENABLED
10 Disable Primary Vserver On Down : DISABLED
11 Port Rewrite : DISABLED
12 No. of Bound Services : 1 (Total) 0 (Active)
13 Configured Method: LEASTCONNECTION
14 Mode: IP
15 Persistence: NONE
16 Cacheable: YES PQ: OFF SC: OFF
17 Vserver IP and Port insertion: OFF
18 Push: DISABLED Push VServer:
19 Push Multi Clients: NO
20 Push Label Rule: none
21
22 1) Service-HTTP-1 (10.102.29.40: 80) - HTTP State: DOWN Weight: 1
23 Done

For transparent cache redirection, the appliance intercepts all traffic and evaluates every request to
determine whether it is cacheable. Non-cacheable requests are sent unchanged to the origin server.

When using transparent cache redirection, you may want to turn off cache redirection for load balanc-
ing virtual servers that always direct traffic to origin servers.

Turn off caching for a load balancing virtual server by using the CLI

To turn off caching for a load balancing virtual, use the unset lb vserver command instead of set lb
vserver. Specify a value of NO value for the cacheable parameter.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1843

NetScaler 12.0

Enable or disable load balancing virtual servers to redirect requests to the cache by
using the GUI

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.

2. In the details pane, select the virtual server from which you want to enable/disable the caching,
and then click Open.
3. On the Advanced tab, select/clear Cache Redirection check box.
4. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Configure forward proxy redirection

September 19, 2018

Contributed by:
C

A forward proxy is a single point of contact for a client or group of clients. In this configuration, the
NetScaler appliance redirects non-cacheable requests to an origin server and redirects cacheable re-
quests to either a forward proxy cache or a transparent cache.

When the appliance is configured as a forward proxy, users must modify their browsers so that the
browser sends requests to the forward proxy instead of the destination servers.

A forward proxy cache redirection virtual server on the appliance compares the request with a policy
for caching. If the request is not cacheable, the appliance queries a DNS load balancing virtual server
for resolution of the destination, and then sends the request to the origin server. If the request is
cacheable, the appliance forwards the request to a load balancing virtual server for the cache.

The appliance relies on a host domain name or IP address in the request’s HOST header to determine
the requested destination. If there is no HOST header in the request, the appliance inserts a HOST
header based on the destination IP address in the request.

Typically, the NetScaler appliance acts as a forward proxy in an enterprise LAN. In such a configuration,
the appliance resides at the edge of an enterprise LAN and intercepts client requests before they are
fanned out to the WAN. Configuring the appliance in the forward proxy mode reduces traffic on the
WAN.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1844

NetScaler 12.0

To configure forward proxy cache redirection, first enable load balancing and cache redirection on
the appliance. Then, configure a DNS load balancing virtual server and associated services. Also con-
figure a load balancing virtual server and bind to it appropriate services for the cache. Configure a
forward proxy cache redirection virtual server and bind the DNS and load balancing virtual servers to
it. You must also configure caching policies and bind them to the cache redirection virtual server. To
complete the setup, configure the client browsers to use the forward proxy.
For details on how to enable cache redirection and load balancing on the appliance, see “Enable cache
redirection and load balancing.”
For details on how to create a load balancing virtual server, see “Create a load balancing virtual server.”
For details on how to configure services that represent the cache server, see “Configure an HTTP ser-
vice.”
For details on how to bind the service to a virtual server, see “Bind/unbind a service to/from a load
balancing virtual server.”
For details on how to create a forward proxy cache redirection server, see “Configure a cache redirec-
tion virtual server”, and create a virtual server of type TRANSPARENT or FORWARD.
For details on binding cache redirection policies to the cache redirection virtual server, see “Configure
a cache redirection policy.”
1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Create a DNS service

September 19, 2018

Contributed by:
C
A DNS service is a representation, on the NetScaler appliance, of a physical DNS server in the network.
A DNS load balancing virtual server sends DNS requests to the DNS server in the network through such
a service.

Create a DNS service by using the CLI

At the command line, type the following commands to create a DNS service and verify the configura-
tion :

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1845

NetScaler 12.0

1 - add service <name> <IP> <serviceType> <port>

2 - show service [<name>]

Example:

1 add service Service-DNS-1 10.102.29.41 DNS 53

2 show service Service-DNS-1
3 Service-DNS-1 (10.102.29.41:53) - DNS
4 State: DOWN
5 Last state change was at Fri Jul 2 10:14:32 2010
6 Time since last state change: 0 days, 00:00:13.550
7 Server Name: 10.102.29.41
8 Server ID : 0 Monitor Threshold : 0
9 Max Conn: 0 Max Req: 0 Max Bandwidth: 0 kbits
10 Use Source IP: NO
11 Client Keepalive(CKA): NO
12 Access Down Service: NO
13 TCP Buffering(TCPB): NO
14 HTTP Compression(CMP): NO
15 Idle timeout: Client: 120 sec Server: 120 sec
16 Client IP: DISABLED
17 Cacheable: NO
18 SC: OFF
19 SP: OFF
20 Down state flush: ENABLED
21
22 1) Monitor Name: ping-default
23 State: DOWN Weight: 1
24 Probes: 3 Failed [Total: 3 Current: 3]
25 Last response: Failure - Probe timed out.
26 Response Time: 2000.0 millisec
27 Done

Add a DNS service by using the GUI

1. Navigate to Traffic Management > Load Balancing > Services.

2. In the details pane, click Add.

3. In the Create Service dialog box, specify values for the following parameters as shown:

• Service Name*—name
• Server*—IP
• Port*—port

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1846

NetScaler 12.0

*A required parameter

1. In the Protocol* drop down list, select a supported protocol (for example, DNS).

2. Click Create, and then click Close.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Create a DNS load balancing virtual server

September 19, 2018

Contributed by:
C

The DNS virtual server enables the forward proxy to perform DNS resolution before forwarding a client
request to an origin server. The DNS load balancing virtual server is associated with the DNS service
that represents the physical DNS server on the network.

Create a DNS load balancing virtual server by using the CLI

At the command line, type the following commands to create a DNS load balancing virtual server and
verify the configuration:

1 - add lb vserver <name> <serviceType>

2 - show lb vserver [<name>]

Example:

1 > add lb vserver Vserver-DNS-1 DNS

2 Done
3 > show lb vserver Vserver-DNS-1
4 Vserver-DNS-1 (0.0.0.0:0) - DNS Type: ADDRESS
5 State: DOWN
6 Last state change was at Fri Jul 2 10:32:28 2010
7 Time since last state change: 0 days, 00:00:08.10
8 Effective State: DOWN ARP:DISABLED
9 Client Idle Timeout: 120 sec
10 Down state flush: ENABLED
11 Disable Primary Vserver On Down : DISABLED

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1847

NetScaler 12.0

12 No. of Bound Services : 0 (Total) 0 (Active)

13 Configured Method: LEASTCONNECTION
14 Mode: IP
15 Persistence: NONE
16 Done

Create a DNS load balancing virtual server by using the GUI

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.

2. In the details pane, click Add.
3. In the Create Virtual Server (Load Balancing) dialog box, in the Name box, type a name for the
virtual server.
4. In the Protocol* drop down list, select a supported protocol (for example, DNS).
5. Click Create, and then click Close. The DNS Virtual Servers pane displays the new virtual server.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Bind the DNS service to the virtual server

September 19, 2018

Contributed by:
C

For the DNS server to respond to DNS requests, the service representing the DNS server must be bound
to the DNS virtual server.

Bind the DNS service to the load balancing virtual server by using the CLI

At the command prompt, type the following commands to bind the DNS service to the load balancing
virtual server and verify the configuration:

1 - bind lb vserver <name> <serviceName>

2 - show lb vserver <name>

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1848

NetScaler 12.0

1 > bind lb vserver Vserver-DNS-1 Service-DNS-1

2 Done
3 > show lb vserver Vserver-DNS-1
4 Vserver-DNS-1 (0.0.0.0:0) - DNS Type: ADDRESS
5 State: DOWN
6 Last state change was at Fri Jul 2 10:32:28 2010
7 Time since last state change: 0 days, 00:12:16.80
8 Effective State: DOWN ARP:DISABLED
9 Client Idle Timeout: 120 sec
10 Down state flush: ENABLED
11 Disable Primary Vserver On Down : DISABLED
12 No. of Bound Services : 1 (Total) 0 (Active)
13 Configured Method: LEASTCONNECTION
14 Mode: IP
15 Persistence: NONE
16
17 1) Service-DNS-1 (10.102.29.41: 53) - DNS State: DOWN Weight: 1
18 Done
19 >

Unbind a DNS service from the load balancing virtual server by using the CLI

Use the unbind lb vserver command instead of bind lb vserver.

Bind/Unbind a DNS service to/from a load balancing virtual server by using the GUI

1. Navigate to Traffic Management > Load Balancing > Virtual Servers

2. In the details pane, select the virtual server to/from which you want to bind/unbind the DNS
service, and then click Open.
3. On the Services tab, in the Active column, select/clear the check box next to the Service Name.
4. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1849

NetScaler 12.0

Configure a client web browser to use a forward proxy

September 19, 2018

Contributed by:
C

When you configure the NetScaler appliance as forward proxy cache redirection virtual server in the
network, you must configure the client Web browser to send requests to the forward proxy. Typically,
when you use a forward proxy, the only route to the servers in the network is through the forward
proxy.

Refer the documentation for your browser to configure the browser to use a forward proxy. Specify the
IP address and port number of the forward proxy cache redirection virtual server for this configuration.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Configure reverse proxy redirection

September 19, 2018

Contributed by:
C

A reverse proxy resides in front of one or more Web servers and shields the origin server from client
requests. Often, a reverse proxy cache is a front-end for all client requests to a server. An administrator
assigns a reverse proxy cache to a specific origin server. This is unlike transparent and forward proxy
caches, which cache frequently requested content for all requests to any origin server, and the choice
of a server is based on the request.

Unlike a transparent proxy cache, the reverse proxy cache has its own IP address and can replace
destination domains and URLs in a non-cacheable request with new destination domains and URLs.

You can deploy reverse proxy cache redirection at the origin-server side or at the edge of a network.
When deployed at the origin server, the reverse proxy cache redirection virtual server is a front-end
for all requests to the origin server.

In the reverse proxy mode, when the appliance receives a request, a cache redirection virtual server
evaluates the request and forwards it to either a load balancing virtual server for the cache or a load

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1850

NetScaler 12.0

balancing virtual server for the origin. The incoming request can be transformed by changing the host
header or the host URL before they it is sent to the backend server.

To configure reverse proxy cache redirection, first enable cache redirection and load balancing. Then,
configure a load balancing virtual server and services to send cacheable requests to the cache servers.
Also configure a load balancing virtual server and associated services for the origin servers. Then,
configure a reverse proxy cache redirection virtual server and bind relevant cache redirection policies
to it. Finally, configure mapping policies and bind them to the reverse proxy cache redirection virtual
server.

The mapping policies have an associated action that enables the cache redirection virtual server to
forward any non-cacheable request to the load balancing virtual server for the origin.

Be sure to create the default cache server destination.

For details on how to enable cache redirection and load balancing on the appliance, see Enable cache
redirection and load balancing.

For details on how to create a load balancing virtual server, see Create a load balancing virtual server.

For details on how to configure services that represent the cache server, see Configure an HTTP ser-
vice.

For details on how to bind the service to a virtual server, see Bind/unbind a service to/from a load
balancing virtual server.

For details on how to create a reverse proxy cache redirection server, see Configure a cache redirection
virtual server, and create a virtual server of type REVERSE.

For details on binding built-in cache redirection policies to the cache redirection virtual server, see
Bind policies to the cache redirection virtual server.

Configure mapping policies

If an incoming request is non-cacheable, the reverse-proxy cache redirection virtual server replaces
the domain and URL in the request with the domain and URL of a target origin server and forwards
the request to the load balancing virtual server for the origin.

A mapping policy enables the reverse proxy cache redirection virtual server to replace the destination
domain and URL and forward the request to the load balancing virtual server for the origin.

A mapping policy must first translate the domain and the URL, and then pass the request on to the
origin load balancing virtual server.

A mapping policy can map a domain, a URL prefix, and a URL suffix, as follows:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1851

NetScaler 12.0

• Domain mapping: You can map a domain without a prefix or suffix. The domain mapping is
the default mapping for the virtual server (for example, mapping www.mycompany.com to
www.myrealcompany.com).
• Prefix mapping: You can replace a specified pattern prefixed as part of the URL (for example,
mapping www.mycompany.com/sports/index.html to www.mycompany.com/news/index.html).
• Suffix mapping: You can replace the file suffix in the URL (for example, mapping www.mycompany.com/sport
to www.mycompany.com/sports/index.asp).

The source and the destination strings being mapped must be similar. If you specify a source domain,
you must specify a destination domain, and if you specify a source suffix, you must specify a destina-
tion suffix. Similarly, if you specify an exact URL from the source, the target URL must also be an exact
URL.

Once you configure mapping policies for the reverse proxy mode, you must bind them to the cache
redirection virtual server.

You can use combinations of the source URL, target URL, and source and target domains to configure
all three types of domain mapping.

Configure a mapping policy for reverse proxy mode by using the CLI

At the command prompt, type the following command to add a policy map and verify the configura-
tion:

1 - add policy map <mapPolicyName> -sd <string> [-su <string>] [-td <
string>] [-tu <string>]
2 - show policy map [<mapPolicyName>]

Example:

The following command maps a domain in a client request to a target domain:

1 > add policy map myMappingPolicy -sd www.mycompany.com -td www.

myrealcompany.com
2 Done
3 > show policy map myMappingPolicy
4 1) Name: myMappingPolicy
5 Source Domain: www.mycompany.com Source Url:
6 Target Domain: www.myrealcompany.com Target Url:
7 Done

Following is an example of mapping a URL suffix to a different URL suffix:

1 > add policy map myOtherMappingPolicy -sd www.mycompany.com -td www.

myrealcompany.com -su /news.html -tu /realnews.html

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1852

NetScaler 12.0

2 Done
3 > show policy map myOtherMappingPolicy
4 1) Name: myOtherMappingPolicy
5 Source Domain: www.mycompany.com Source Url: /news.html
6 Target Domain: www.myrealcompany.com Target Url: /realnews.
html
7 Done

Configure a mapping policy for reverse proxy mode by using the GUI

1. Navigate to Traffic Management > Cache Redirection > Map Policies.

2. In the details pane, click Add.

3. In the Create Map Policy dialog box, specify values for the following parameters as shown:

• Name*- mapPolicyName
• Source Domain*-sd
• Target Domain*-td
• Source URL-su
• Target URL-tu

*A required parameter

4. Click Create, and then click Close. The Map pane displays the new mapping policy.

Bind the mapping policy to the cache redirection virtual server by using the CLI

At the command prompt, type the following commands to bind the mapping policy to the cache redi-
rection virtual server and verify the configuration:

1 - bind cr vserver <name> -policyName <string> [<targetVserver>]

2 - show cr vserver <name>

Example:

1 > bind cr vserver Vserver-CRD-3 -policyName myMappingPolicy Vserver-LB-

CR
2 Done
3 > show cr vserver Vserver-CRD-3
4 Vserver-CRD-3 (10.102.29.50:88) - HTTP Type: CONTENT
5 State: UP
6 Client Idle Timeout: 180 sec
7 Down state flush: ENABLED

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1853

NetScaler 12.0

8 Disable Primary Vserver On Down : DISABLED

9 Default: Vserver-LB-CR Content Precedence: RULE Cache:
REVERSE
10 On Policy Match: ORIGIN L2Conn: OFF OriginUSIP: OFF
11 Redirect: POLICY Reuse: ON Via: ON ARP: OFF
12
13 1) Policy: Target: Vserver-LB-CR Priority: 0 Hits: 0
14 1) Map: myMappingPolicy Target: Vserver-LB-CR
15 Done

Bind the mapping policy to the cache redirection virtual server by using the GUI

1. Navigate to Traffic Management > Cache Redirection > Virtual Servers.

2. In the details pane, select the virtual server from which you want to bind the mapping policy,
and then click Open.
3. In the Configure Virtual Server(Cache Redirection), on the Policies tab, select Map, and then
click Insert Policy.
4. In the Policy Name column, select the policy from drop down list.
5. In the Target column, click the down arrow, and then select the vserver from drop down list.
6. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Selective cache redirection

September 19, 2018

Contributed by:
C

Selective cache redirection sends requests for particular types of content, for example, images, to one
cache server or group of cache servers and sends other types of content to a different cache server or
group of cache servers. You can configure advanced cache redirection in transparent, reverse proxy,
or forward proxy modes.

In selective cache redirection, the NetScaler appliance intercepts a client request and forwards non-
cacheable requests to the original destination in the client request. For cacheable requests, the appli-

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1854

NetScaler 12.0

ance sends the requests to the destination cache server that can serve content of a specific content
type.

Selective cache redirection involves configuring content switching policies in addition to cache redi-
rection policies. The appliance first evaluates the cache redirection policies that are bound to the
cache redirection virtual server. If a request matches a cache redirection policy, the cache redirec-
tion virtual server sends the request to the origin server or a load balancing virtual server for the ori-
gin. If no cache redirection policies match the request, the appliance evaluates the content switching
policies bound to the cache redirection virtual server. If a content switching policy matches the re-
quest, the cache redirection virtual server redirects the request to a load balancing virtual server for
the cache.

To configure selective cache redirection, first enable cache redirection, load balancing, and content
switching on the NetScaler appliance. Then, configure a load balancing virtual server for the cache
and an associated HTTP service. After this, configure a cache redirection virtual server and bind both
the cache redirection and content switching policies to it. Once you have bound the policies, you can
configure the virtual server to give precedence to either rule based or URL based content-switching
policies.

When configured for transparent mode cache redirection in an edge deployment topology, the appli-
ance sends all cacheable HTTP traffic to a transparent cache farm. Clients access the Internet through
the appliance, which is configured as a Layer 4 switch that receives traffic on port 80.

The appliance can direct requests for images (for example, .gif and .jpg files) to one server in the trans-
parent cache farm, and all other requests for static content to other servers in the farm. For this con-
figuration, you configure content switching policies to send images to the image cache and send all
other cacheable content to a default cache.
Note

The configuration described here is for transparent selective cache redirection. Therefore, it does
not require a load balancing virtual server for the origin, as would a reverse proxy configuration.

To configure this type of selective cache redirection, first enable cache redirection, load balancing,
and content switching. Then, configure a load balancing virtual server for the cache and configure an
associated HTTP service. Then, configure a cache redirection virtual server and create and bind both
cache redirection and content switching policies to this virtual server.

For details on how to enable cache redirection and load balancing on the appliance, see Enable cache
redirection and load balancing.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1855

NetScaler 12.0

Enable content switching

September 19, 2018

Contributed by:
C

To configure selective cache redirection, after you enable both the load balancing and cache redirec-
tion features on the appliance, you must enable content switching.

Enable content switching by using the CLI

At the command prompt, type:

1 - enable ns feature CS
2
3 - show ns feature

Example:

1 > enable ns feature cs

2 Done
3 > show ns feature
4
5 Feature Acronym Status
6 ------- ------- ------
7 1) Web Logging WL ON
8 2) Surge Protection SP ON
9 3) Load Balancing LB ON
10 4) Content Switching CS ON
11 5) Cache Redirection CR ON
12 ...
13 ...
14 ...
15 23) HTML Injection HTMLInjection ON
16 24) appliance Push push OFF
17 Done

Enable cache redirection and load balancing by using the GUI

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

2. In the details pane, under Modes and Features, click Configure basic features.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1856

NetScaler 12.0

3. In Configure Basic Features dialog box, select the check box next to the Content Switching, and
then click OK.
4. In Enable/Disable Feature(s)? dialog box, click Yes.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Configure a load balancing virtual server for the cache

September 19, 2018

Contributed by:
C

Create a load balancing virtual server and an HTTP service for each type of cache server that will be
used. For example, if you want to serve JPEG files from one cache server and GIF files from another
cache server, and use a third cache server for the rest of the content, create an HTTP service and
virtual server for each of the three types of cache servers. Then bind each service to its respective
virtual server.

For details on how to create a load balancing virtual server, see Create a load balancing virtual server.

For details on how to configure services that represent the cache server, see Configure an HTTP ser-
vice.

For details on how to bind the service to a virtual server, see Bind/unbind a service to/from a load
balancing virtual server.

For details on how to create a transparent proxy cache redirection server, see Configure a cache redi-
rection virtual server, and create a virtual server of type TRANSPARENT.

For details on binding built-in cache redirection policies to the cache redirection virtual server, see
Bind policies to the cache redirection virtual server.

Configure a cache redirection policy for a specific type of content

To identify requests that contain a .gif or .jpeg extension as cacheable, you configure a cache redirec-
tion policy and bind it to the cache redirection virtual server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1857

NetScaler 12.0

Note

If a request matches a policy, the NetScaler appliance forwards it to the origin server. As a result,
in the following procedure, you configure policies to match requests that do
not have “.gif” or “.jpeg” extensions.

To configure cache redirection for a specific type of content, configure a policy that uses a simple
expression, as described in Configure a cache redirection policy.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Configure policies for content switching

September 19, 2018

Contributed by:
C

You must create a content switching policy to identify specific types of content to be cached in one
cache server or farm and identify other types of content to serve from another cache server or farm.
For example, you can configure a policy to determine the location for image files with .gif and .jpeg
extensions.

After defining the content switching policy, you bind it to a cache redirection virtual server and spec-
ify a load balancing virtual server. Requests that match the policy are forwarded to the named load
balancing virtual server. Requests that do not match the content switching policy are forwarded to
the default load balancing virtual server for the cache.

For more details about the content switching feature and configuring content switching policies, see
Content switching.

You must first create the content switching policy and then bind it to the cache redirection virtual
server.

Create a content switching policy by using the command CLI

At the command line, type:

1 - add cs policy <policyName> [-url <string> | -rule <expression>]

2 - show cs policy [<policyName>]

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1858

NetScaler 12.0

Examples:

1 > add cs policy Policy-CS-JPEG -rule ”REQ.HTTP.URL == ’/*.jpeg’”

2 Done
3 > show cs policy Policy-CS-JPEG
4 Rule: REQ.HTTP.URL == ’/*.jpeg’ Policy: Policy-CS-JPEG
5 Hits: 0
6 Done
7 >
8
9 > add cs policy Policy-CS-GIF -rule ”REQ.HTTP.URL == ’/ *.gif’”
10 Done
11 > show cs policy Policy-CS-GIF
12 Rule: REQ.HTTP.URL == ’/ *.gif’ Policy: Policy-CS-GIF
13 Hits: 0
14 Done
15 >
16
17 > add cs policy Policy-CS-JPEG-URL -url /*.jpg
18 Done
19 > show cs policy Policy-CS-JPEG-URL
20 URL: /*.jpg Policy: Policy-CS-JPEG-URL
21 Hits: 0
22 Done
23 >
24
25 > add cs policy Policy-CS-GIF-URL -url /*.gif
26 Done
27 > show cs policy Policy-CS-GIF-URL
28 URL: /*.gif Policy: Policy-CS-GIF-URL
29 Hits: 0
30 Done

Create a URL-based content switching policy by using the GUI

1. Navigate to Traffic Management > Content Switching > Policies.

2. In the details pane, click Add.
3. In the Create Content Switching Policy dialog box, in the Name text box, type a name for the
policy.
4. Select the URL radio button.
5. In the Value text box, type the string value (for example, /sports).
6. Click Create and click Close. The policy you created appears in the Content Switching Policies
page.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1859

NetScaler 12.0

Create a rule-based content switching policy by using the GUI

1. Navigate to Traffic Management > Content Switching > Policies.

2. In the details pane, click Add.

3. In the Create Content Switching Policy dialog box, in the Name text box, type a name for the
policy.

4. Select the Expression radio button, and then click Configure.

5. In the Create Expression dialog box, choose the expression syntax that you want to use.

• If you want to use default syntax, accept the default and proceed to the next step.
• If you want to use classic syntax, click Switch to Classic Syntax.

The Expression portion of the dialog box changes to match your choice. The default syntax Ex-
pression view has fewer elements than does the classic syntax Expression view. In the default
syntax Expression view, instead of a preview window, a button provides access to an expres-
sion evaluator. The evaluator evaluates the expression you entered, to verify that it is valid, and
displays an analysis of the expression’s effect.

6. Enter your policy expressions.

For information about using the advanced syntax, see Configure advanced policy expression:
Get started.

7. Click Create and click Close. The policy you created appears in the Content Switching Policies
pane.

Bind the content switching policy to a cache redirection virtual server by using the CLI

At the command prompt, type the following commands to bind the content switching policy to a cache
redirection virtual server and verify the configuration:

1 - bind cs vserver <name> <targetVserver> [-policyName <string>]

2 - show cs vserver [<name>]

Example:

1 > bind cs vserver Vserver-CR-1 lbcachejpeg -policyName Policy-CS-JPEG

2 Done
3 > bind cs vserver Vserver-CR-1 lbcachegif -policyName Policy-CS-GIF
4 Done
5 > show cs vserver Vserver-CR-1
6 Vserver-CR-1 (10.102.29.60:80) - HTTP Type: CONTENT
7 State: UP

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1860

NetScaler 12.0

8 Last state change was at Fri Jul 2 12:53:45 2010

9 Time since last state change: 0 days, 00:00:58.920
10 Client Idle Timeout: 180 sec
11 Down state flush: ENABLED
12 Disable Primary Vserver On Down : DISABLED
13 Port Rewrite : DISABLED
14 State Update: DISABLED
15 Default: Content Precedence: RULE
16 Cacheable: YES
17 Vserver IP and Port insertion: OFF
18 Case Sensitivity: ON
19 Push: DISABLED Push VServer:
20 Push Label Rule: none
21
22 1) Policy: Policy-CS-JPEG Target: lbcachejpeg Priority: 0
Hits: 0
23 2) Policy: Policy-CS-GIF Target: lbcachegif Priority: 0
Hits: 0
24 Done
25 >

Bind the content switching policy to a cache redirection virtual server by using the GUI

1. Navigate to Traffic Management > Content Switching > Virtual Servers.

2. In the details pane, select the virtual server for which you want to bind the policy (for example,
Vserver-CS-1), and then click Open.
3. In the Configure Virtual Server (Content Switching) dialog box, on the Policies tab, click CSW,
and then click Insert Policy.
4. In the Policy Name column, select the policy that you want to configure for the content switching
virtual server.
5. In the Target column, click the green arrow, and select the target load balancing virtual server
from the list.
6. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1861

NetScaler 12.0

Configure precedence for policy evaluation

September 19, 2018

Contributed by:
C

You can configure a content switching policy based on either a rule, which is a generic configuration to
accommodate various content types, or a URL, which is more specific and defines exactly the type of
content that has to be sent to a particular cache server. Essentially, the same content can be defined
by either a rule based policy or a URL based policy.

Once you bind content switching policies of either type to a cache redirection virtual server, you can
configure the virtual server to give precedence to either rule based or URL based policies. This will, in
turn, decide which servers the particular requests are directed to.

To configure precedence for policy evaluation, use the precedence parameter, which specifies the type
of policy (URL or RULE) that takes precedence on the content redirection virtual server.

Possible values: RULE, URL

Default value: RULE

Configure precedence for policy evaluation by using the CLI

At the command prompt, type the following commands to configure precedence for policy evaluation
and verify the configuration:

1 - set cr vserver <name> [-precedence (RULE | URL)]

2 - show cr vserver <name>

Example:

1 > set cr vserver Vserver-CRD-1 -precedence URL

2 Done
3 > show cr vserver Vserver-CRD-1
4 Vserver-CRD-1 (*:80) - HTTP Type: CONTENT
5 State: UP ARP:DISABLED
6 Client Idle Timeout: 180 sec
7 Down state flush: ENABLED
8 Disable Primary Vserver On Down : DISABLED
9 Default: Content Precedence: URL Cache: TRANSPARENT
10 On Policy Match: ORIGIN L2Conn: OFF OriginUSIP: OFF
11 Redirect: POLICY Reuse: ON Via: ON ARP: OFF
12

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1862

NetScaler 12.0

13 1) Cache bypass Policy: bypass-cache-control

14 2) Cache bypass Policy: Policy-CRD
15 Done
16 >

Configure precedence for policy evaluation by using the GUI

1. Navigate to Traffic Management > Content Switching > Virtual Servers.

2. In the details pane, select the virtual server for which you want to configure precedence, (for
example, Vserver-CS-1), and then click Open.
3. In the Configure Virtual Server (Content Switching) dialog box, on the Advanced tab, next to
Precedence, click Rule or URL, and then click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Administer a cache redirection virtual server

September 19, 2018

Contributed by:
C

To administer a cache redirection virtual server, you need to view cache redirection statistics. You
might need to enable or disable cache redirection servers, or direct policy hits to the cache instead of
the origin. Administrative tasks also include backing up a cache redirection virtual server and manag-
ing client connections.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

View cache redirection virtual server statistics

September 19, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1863

NetScaler 12.0

Contributed by:
C

You can view properties of a cache redirection virtual server and statistics on the traffic that has passed
through a cache redirection virtual server. You can also view the cache redirection virtual servers and
policies that you have bound to load balancing virtual servers.

To view statistics for a specific cache redirection virtual servers, use the name parameter to specify
the name of the virtual server for which statistics will be displayed. Otherwise, statistics for all cache
redirection virtual servers are displayed. Maximum Length: 127

View statistics for a cache redirection virtual server by using the CLI

At the command prompt, type:

stat cr vserver [<name>]

Example:

1 > stat cr vserver Vserver-CRD-1

2
3 Vserver Summary
4 IP port Protocol State
5 Vser...CRD-1 0.0.0.0 80 HTTP UP
6
7 VServer Stats:
8 Rate (/s)
Total
9 Requests 0
0
10 Responses 0
0
11 Request bytes 0
0
12 Response bytes 0
0
13
14 Done
15 >

View statistics for a cache redirection virtual server by using the GUI

1. Navigate to Traffic Management > Cache Redirection > Virtual Servers

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1864

NetScaler 12.0

2. In the details pane, select the virtual server for which you want to view statistics, (for example,
Vserver-CRD-1), and then click Statistics.

Omit the server name to display basic statistics for all cache redirection virtual servers. Include the
server name to display detailed statistics for that virtual server, including number and size of requests
and responses that pass through the virtual server

View the statistics of a cache redirection virtual server by using the monitoring and
dashboard utilities

1. To view the statistics by using the monitoring utilities, click the Monitoring tab.
2. In the Select Group drop-down menu, choose CR Virtual Servers. A list of cache redirection
virtual servers appears.
3. To view the statistics by using the dashboard utilities, click the Dashboard tab.
4. Click Applet Client or Web Start Client next to Statistical Utility.
5. In the Select Group drop-down menu, choose CR Virtual Servers. The dashboard displays sum-
mary statistics for the cache redirection virtual servers.
6. To see a chart of virtual server activity, click Chart. A graphical representation of the virtual
server statistics appears.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Enable or disable a cache redirection virtual server

September 19, 2018

Contributed by:
C

When you create a cache redirection virtual server, it is enabled by default. If you disable a cache
redirection virtual server, its state changes to OUT OF SERVICE and it stops redirecting cacheable client
requests. However, the NetScaler appliance continues to respond to ARP and ping requests for the IP
address of this virtual server.

Enable or disable a cache redirection virtual server by using the CLI

At the command line, type one of the following commands:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1865

NetScaler 12.0

1 - enable cr vserver <name>

2 - show cr vserver <name>
3 - disable cr vserver <name>
4 - show cr vserver <name>

Examples:

1 > enable cr vserver Vserver-CRD-1

2 Done
3 > show cr vserver Vserver-CRD-1
4 Vserver-CRD-1 (*:80) - HTTP Type: CONTENT
5 State: UP ARP:DISABLED
6 Client Idle Timeout: 180 sec
7 Down state flush: ENABLED
8 Disable Primary Vserver On Down : DISABLED
9 Default: Content Precedence: URL Cache: TRANSPARENT
10 On Policy Match: ORIGIN L2Conn: OFF OriginUSIP: OFF
11 Redirect: POLICY Reuse: ON Via: ON ARP: OFF
12
13 1) Cache bypass Policy: bypass-cache-control
14 2) Cache bypass Policy: Policy-CRD
15 Done
16 >
17
18 > disable cr vserver Vserver-CRD-1
19 Done
20 > show cr vserver Vserver-CRD-1
21 Vserver-CRD-1 (*:80) - HTTP Type: CONTENT
22 State: OUT OF SERVICE ARP:DISABLED
23 Client Idle Timeout: 180 sec
24 Down state flush: ENABLED
25 Disable Primary Vserver On Down : DISABLED
26 Default: Content Precedence: URL Cache: TRANSPARENT
27 On Policy Match: ORIGIN L2Conn: OFF OriginUSIP: OFF
28 Redirect: POLICY Reuse: ON Via: ON ARP: OFF
29
30 1) Cache bypass Policy: bypass-cache-control
31 2) Cache bypass Policy: Policy-CRD
32 Done
33 >

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1866

NetScaler 12.0

Enable or disable a cache redirection virtual server by using the GUI

1. Navigate to Traffic Management > Cache Redirection > Virtual Servers.

2. In the navigation pane, expand Cache Redirection, and then click Virtual Servers.
3. In the details pane, select the virtual server that you want to enable or disable, (for example,
Vserver-CRD-1), and then click Statistics.
4. In the Proceed dialog box, click Yes.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Direct policy hits to the cache instead of the origin

September 19, 2018

Contributed by:
C

By default, when a request matches a policy, the NetScaler appliance forwards the request either to
the origin server directly, or to a load balancing virtual server for the origin, depending on how you
have configured cache redirection.

You can change the default behavior so that when a request matches a policy, the request is forwarded
to a load balancing virtual server for the cache.

To change the destination for a policy hit to the origin or the cache, use the onPolicyMatch parameter,
which specifies where to send requests that match the cache redirection policy.

The valid options are:

1. CACHE - Directs all matching requests to the cache.

2. ORIGIN - Directs all matching requests to the origin server.

Note

For this option to work, you must select the cacheredirection type as POLICY.

Possible values: CACHE, ORIGIN

Default value: ORIGIN

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1867

NetScaler 12.0

Change the destination for a policy hit to the origin or the cache by using the CLI

At the command prompt, type the following commands to change the destination for a policy hit and
verify the configuration:

1 - set cr vserver <name> [-onPolicyMatch (ORIGIN | CACHE)]

2 - show cr vserver <name>

Example:

1 > set cr vserver Vserver-CRD-1 -onPolicyMatch CACHE

2 Done
3 > show cr vserver Vserver-CRD-1
4 Vserver-CRD-1 (*:80) - HTTP Type: CONTENT
5 State: UP ARP:DISABLED
6 Client Idle Timeout: 180 sec
7 Down state flush: ENABLED
8 Disable Primary Vserver On Down : DISABLED
9 Default: Content Precedence: URL Cache: TRANSPARENT
10 On Policy Match: CACHE L2Conn: OFF OriginUSIP: OFF
11 Redirect: POLICY Reuse: ON Via: ON ARP: OFF
12
13 1) Cache bypass Policy: bypass-cache-control
14 2) Cache bypass Policy: Policy-CRD
15 Done

Change the destination for a policy hit to the origin or the cache by using the GUI

1. Navigate to Traffic Management > Cache Redirection > Virtual Servers.

2. In the details pane, select the virtual server for which you want to change the destination for a
policy hit, (for example, Vserver-CRD-1), and then click Open.
3. In Configure Virtual Server (Cache Redirection) dialog box, click Advanced tab.
4. Select CACHE or ORIGIN from the Redirect To drop-down list.
5. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1868

NetScaler 12.0

Back up a cache redirection virtual server

September 19, 2018

Contributed by:
C

Cache redirection can fail if the primary virtual server fails, or if it is unable to handle excessive traffic.
You can specify a backup virtual server to take over the processing of traffic when the primary virtual
server fails.

To specify a backup cache redirection virtual server, use the backupVServer parameter, which specifies
Backup Virtual Server. Maximum Length: 127

Specify a backup cache redirection virtual server by using the CLI

At the command prompt, type the following commands to specify a backup cache redirection virtual
server and verify the configuration:

1 - set cr vserver <name> [-backupVServer <string>]

2 - show cr vserver <name>

Example:

1 > set cr vserver Vserver-CRD-1 -backupVServer Vserver-CRD-2

2 Done
3 > show cr vserver Vserver-CRD-1
4 Vserver-CRD-1 (*:80) - HTTP Type: CONTENT
5 State: UP ARP:DISABLED
6 Client Idle Timeout: 180 sec
7 Down state flush: ENABLED
8 Disable Primary Vserver On Down : DISABLED
9 Default: Content Precedence: URL Cache: TRANSPARENT
10 On Policy Match: CACHE L2Conn: OFF OriginUSIP: OFF
11 Redirect: POLICY Reuse: ON Via: ON ARP: OFF
12 Backup: Vserver-CRD-2
13
14 1) Cache bypass Policy: bypass-cache-control
15 2) Cache bypass Policy: Policy-CRD
16 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1869

NetScaler 12.0

Specify a backup cache redirection virtual server by using the GUI

1. Navigate to Traffic Management > Cache Redirection > irtual Servers.

2. In the details pane, select the virtual server for which you want to change the destination for a
policy hit, (for example, Vserver-CRD-1), and then click Open.
3. In Configure Virtual Server (Cache Redirection) dialog box, select the Advanced tab.
4. In the Backup Virtual Server drop-down list, select the virtual server.
5. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Manage client connections for a virtual server

September 19, 2018

Contributed by:
C

You can configure timeouts on a cache redirection virtual server so that client connections are not kept
open indefinitely. You can also insert Via headers in requests. To possibly reduce network congestion,
you can reuse open TCP connections. You can enable or disable delayed cleanup of cache redirection
virtual server connections.

You can configure the appliance to send ICMP responses to PING requests according to your settings.
On the IP address corresponding to the virtual server, set the ICMP RESPONSE to VSVR_CNTRLD, and
on the virtual server, set the ICMP VSERVER RESPONSE.

The following settings can be made on a virtual server:

• When you set ICMP VSERVER RESPONSE to PASSIVE on all virtual servers, appliance always re-
sponds.
• When you set ICMP VSERVER RESPONSE to ACTIVE on all virtual servers, appliance responds
even if one virtual server is UP.
• When you set ICMP VSERVER RESPONSE to ACTIVE on some and PASSIVE on others, appliance
responds even if one virtual server set to ACTIVE is UP.

This document includes the following information:

• Configure client timeout

• Insert Via headers in the requests

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1870

NetScaler 12.0

• Reuse TCP connections

• Configure delayed connection cleanup

Configure client timeout

You can specify expiration of client requests by setting a timeout value for the cache redirection virtual
server. The timeout value is the number of seconds for which the cache redirection virtual server waits
to receive a response for the client request.

To configure a time-out value, use the cltTimeout parameter, which specifies the time, in seconds,
after which the NetScaler appliance closes any idle client connections. The default value is 180sec for
HTTP/SSL-based services and 9000sec for TCP-based services.

Configure client timeout by using the CLI

At the command prompt, type the following commands to configure client timeout and verify the
configuration:

1 - set cr vserver <name> [-cltTimeout <secs>]

2 - show cr vserver <name>

Example:

1 > set cr vserver Vserver-CRD-1 -cltTimeout 6000

2 Done
3 > show cr vserver Vserver-CRD-1
4 Vserver-CRD-1 (*:80) - HTTP Type: CONTENT
5 State: UP ARP:DISABLED
6 Client Idle Timeout: 6000 sec
7 Down state flush: ENABLED
8 Disable Primary Vserver On Down : DISABLED
9 Default: Content Precedence: URL Cache: TRANSPARENT
10 On Policy Match: CACHE L2Conn: OFF OriginUSIP: OFF
11 Redirect: POLICY Reuse: ON Via: ON ARP: OFF
12 Backup: Vserver-CRD-2
13
14 1) Cache bypass Policy: bypass-cache-control
15 2) Cache bypass Policy: Policy-CRD
16 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1871

NetScaler 12.0

Configure client timeout by using the GUI

1. Navigate to Traffic Management > Cache Redirection > Virtual Servers.

2. In the details pane, select the virtual server for which you want to configure client timeout, (for
example, Vserver-CRD-1), and then click Open.
3. In Configure Virtual Server (Cache Redirection) dialog box, select the Advanced tab.
4. In the Client Time-out(secs) text box, enter the time-out value in seconds.
5. Click OK.

Insert Via headers in the requests

A Via header lists the protocols and recipients between the start and end points for a request or a
response and informs the server of proxies through which the request was sent. You can configure
the cache redirection virtual server to insert a Via header in each HTTP request. The via parameter is
enabled by default when you create a cache redirection virtual server.

To enable or disable Via-header insertion in client requests, use the via parameter, which specifies the
state of the system in inserting a Via header in the HTTP requests.

Possible values: ON, OFF

Default value: ON

Enable or disable Via-header insertion in client requests by using the CLI

At the command prompt, type:

1 - set cr vserver <name> [-via (ON|OFF)]

2 - show cr vserver <name>

Example:

1 > set cr vserver Vserver-CRD-1 -via ON

2 Done
3 > show cr vserver Vserver-CRD-1
4 Vserver-CRD-1 (*:80) - HTTP Type: CONTENT
5 State: UP ARP:DISABLED
6 Client Idle Timeout: 6000 sec
7 Down state flush: ENABLED
8 Disable Primary Vserver On Down : DISABLED
9 Default: Content Precedence: URL Cache: TRANSPARENT
10 On Policy Match: CACHE L2Conn: OFF OriginUSIP: OFF
11 Redirect: POLICY Reuse: ON Via: ON ARP: OFF
12 Backup: Vserver-CRD-2

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1872

NetScaler 12.0

13
14 1) Cache bypass Policy: bypass-cache-control
15 2) Cache bypass Policy: Policy-CRD
16 Done
17 >

Enable or disable Via-header insertion in client requests by using the GUI

1. Navigate to Traffic Management > Cache Redirection > Virtual Servers.

2. In the details pane, select the virtual server for which you want to configure client timeout, (for
example, Vserver-CRD-1), and then click Open.
3. In Configure Virtual Server (Cache Redirection) dialog box, select the Advanced tab.
4. Select the Via check box.
5. Click OK.

Reuse TCP connections

You can configure the NetScaler appliance to reuse TCP connections to the cache and origin servers
across client connections. This can improve performance by saving the time required to establish a
session between the server and the appliance. The reuse option is enabled by default when you create
a cache redirection virtual server.

To enable or disable the reuse of TCP connections, use the reuse parameter, which specifies the state
of reuse of TCP connections to the cache or origin servers across client connections.

Possible values: ON, OFF

Default value: ON

Enable or disable the reuse of TCP connections by using the CLI

At the command prompt, type:

1 - set cr vserver <name> [-reuse (ON|OFF)]

2 - show cr vserver <name>

Example:

1 > set cr vserver Vserver-CRD-1 -reuse ON

2 Done
3 > show cr vserver Vserver-CRD-1
4 Vserver-CRD-1 (*:80) - HTTP Type: CONTENT

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1873

NetScaler 12.0

5 State: UP ARP:DISABLED
6 Client Idle Timeout: 6000 sec
7 Down state flush: ENABLED
8 Disable Primary Vserver On Down : DISABLED
9 Default: Content Precedence: URL Cache: TRANSPARENT
10 On Policy Match: CACHE L2Conn: OFF OriginUSIP: OFF
11 Redirect: POLICY Reuse: ON Via: ON ARP: OFF
12 Backup: Vserver-CRD-2
13
14 1) Cache bypass Policy: bypass-cache-control
15 2) Cache bypass Policy: Policy-CRD
16 Done

Enable or disable the reuse of TCP connections by using the GUI

1. Navigate to Traffic Management > Cache Redirection > Virtual Servers.

2. In the details pane, select the virtual server for which you want to configure client timeout, (for
example, Vserver-CRD-1), and then click Open.
3. In Configure Virtual Server (Cache Redirection) dialog box, select the Advanced tab.
4. Select the Reuse check box.
5. Click OK.

Configure delayed connection cleanup

The down state flush option performs delayed cleanup of connections on a cache redirection virtual
server. The down state flush option is enabled by default when you create a cache redirection virtual
server.

To enable or disable the down state flush option, set the downStateFlush parameter.

Possible values: ENABLED, DISABLED

Default value: ENABLED

Enable of disable the down state flush option by using the CLI

At the command prompt, type the following commands to configure delayed connection clean up and
verify the configuration:

1 - set cr vserver <name> [-downStateFlush (ENABLED | DISABLED)]

2 - show cr vserver <name>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1874

NetScaler 12.0

Example:

1 > set cr vserver Vserver-CRD-1 -downStateFlush ENABLED

2 Done
3 > show cr vserver Vserver-CRD-1
4 Vserver-CRD-1 (*:80) - HTTP Type: CONTENT
5 State: UP ARP:DISABLED
6 Client Idle Timeout: 6000 sec
7 Down state flush: ENABLED
8 Disable Primary Vserver On Down : DISABLED
9 Default: Content Precedence: URL Cache: TRANSPARENT
10 On Policy Match: CACHE L2Conn: OFF OriginUSIP: OFF
11 Redirect: POLICY Reuse: ON Via: ON ARP: OFF
12 Backup: Vserver-CRD-2
13
14 1) Cache bypass Policy: bypass-cache-control
15 2) Cache bypass Policy: Policy-CRD
16 Done

Enable or disable the reuse of TCP connections by using the GUI

1. Navigate to Traffic Management > Cache Redirection > Virtual Servers.

2. In the details pane, select the virtual server for which you want to configure client timeout, (for
example, Vserver-CRD-1), and then click Open.
3. In Configure Virtual Server (Cache Redirection) dialog box, click Advanced tab.
4. Select the Down state flush check box.
5. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

N-Tier cache redirection

January 6, 2019

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1875

NetScaler 12.0

To efficiently handle large amounts of cached data, typically several gigabytes per second, an Internet
Service Provider (ISP) deploys several dedicated cache servers. The cache redirection feature of the
NetScaler appliance can help load balance the cache servers, but a single appliance or a couple of
appliances might not efficiently handle the large volume of traffic.

You can solve the problem by deploying the NetScaler appliances in two tiers (layers), where the ap-
pliances in the upper tier load balance those in the lower tier and the appliances in the lower tier load
balance the cache servers. This arrangement is called n-tier cache redirection.

For purposes such as auditing and security, an ISP has to track client details such as the IP address,
information provided, and the time of the interaction. Therefore, client connections through a
NetScaler appliance have to be fully transparent. However, if you configure transparent cache
redirection, with the NetScaler appliances deployed in parallel, the IP address of the client has to
be shared among all the appliances. Sharing of the client IP address creates a conflict that makes
network devices, such as routers, cache servers, origin servers, and other NetScaler appliances,
unable to determine the appliance, and therefore the client, to which the response should be sent.

How N-tier cache redirection Is implemented

To solve the problem, appliance n-tier cache redirection splits the source port range among the ap-
pliances in the lower tier and includes the client IP address in the request sent to the cache servers.
The upper-tier NetScaler appliances are configured to do sessionless load balancing in order to avoid
unnecessary load on the appliances.

When the lower-tier NetScaler appliance communicates with a cache server, it uses a mapped IP ad-
dress (MIP) to represent the source IP address. Therefore, the cache server can identify the appliance
from which it received the request and send the response to the same appliance.

The lower-tier NetScaler appliance inserts the client IP address into the header of the request sent to
the cache server. The client IP in the header helps the appliance to determine the client to which the
packet should be forwarded when it receives the response from a cache server, or the origin server in
case of a cache miss. The origin server determines the response to be sent according to the client IP
inserted in the request header.

The origin server sends the response to an upper-tier appliance, including the source port number
from which the origin server received the request. The entire source port range, 1024 to 65535, is dis-
tributed among the lower-tier NetScaler appliances. Each lower-tier appliance is exclusively assigned
a group of addresses within the range. This allotment enables the upper-tier appliance to unambigu-
ously identify the lower-tier NetScaler appliance that sent the request to the origin server. The upper-
tier appliance can therefore forward the response to the correct lower-tier appliance.

The upper-tier NetScaler appliances are configured to do policy-based routing, and the routing poli-
cies are defined to determine the IP address of the destination appliance from the source port range.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1876

NetScaler 12.0

Setup necessary for configuring N-Tier CRD

The following setup is necessary for the functioning of n-tier cache redirection:

For each upper-tier NetScaler appliance:

• Enable Layer 3 mode.

• Define policies for policy-based routes (PBRs) so that traffic is forwarded according to the range
of the destination port.
• Configure a load balancing virtual server.
• Configure the virtual server to listen to all the traffic coming from the client. Set the Service
Type/Protocol to be ANY and IP Address as asterisk (*).
• Enable sessionless load balancing with MAC-based redirection mode to avoid unnecessary load
on the upper-tier NetScaler appliances.
• Make sure that the Use Proxy Port option is enabled.
• Create a service for each lower-tier appliance and bind all the services to the virtual server.

For each lower-tier NetScaler appliance,

• Configure the cache redirection port range on the appliance. Assign an exclusive range to each
lower-tier appliance.
• Configure a load balancing virtual server and enable MAC-based redirection.
• Create a service for each cache server that is to be load balanced by this appliance. When creat-
ing the service, enable insertion of client IP in the header. Then, bind all the services to the load
balancing virtual server.
• Configure a transparent mode cache redirection virtual server with the following settings:
– Enable the Origin USIP option.
– Add a source IP expression to include the client IP in the header.
– Enable the Use Port Range option.

How N-tier cache redirection works during a cache hit

The following figure shows how cache redirection works when a client request is cacheable and the
response is sent from a cache server.

Figure 1. Cache Redirection in Case of a Cache Hit

Two NetScaler appliances, L1NS1 and L1NS2, are deployed in the upper tier, and four NetScaler ap-
pliances, L2NS1, L2NS2, L2NS3, and L2NS4, are deployed in the lower tier. Client A sends a request,
which is forwarded by the router. Cache servers CRS1, CRS2, and CRS3 service the cache requests.
Origin Server O services the uncached requests.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1877

NetScaler 12.0

Traffic flow

1. Client sends a request, and the router forwards it to L1NS1.

2. L1NS1 load balances the request to L2NS2.
3. L2NS2 load balances the request to the cache server CRS1, and the request is cacheable. L2NS2
includes the client IP in the request header.
4. CRS1 sends the response to L2NS2 because L2NS2 used its MIP as the source IP address when
connecting to CRS1.
5. With the help of the client IP address in the request header, L2NS2 identifies the client from
which the request came. L2NS2 directly sends the response to the router, avoiding unnecessary
load on the appliance in the upper tier.
6. The router forwards the response to Client A.

How N-tier cache redirection works during a cache bypass

The following figure shows how cache redirection works when a client request is sent to an origin
server for a response.

Figure 2. Cache Redirection in Case of a Cache Bypass

Two NetScaler appliances, L1NS1 and L1NS2, are deployed in the upper tier, and four NetScaler ap-
pliances, L2NS1, L2NS2, L2NS3, and L2NS4, are deployed in the lower tier. Client A sends a request,
which is forwarded by the router. Cache servers CRS1, CRS2, and CRS3 service the cache requests.
Origin Server O services the uncached requests.

Traffic flow

1. Client sends a request, and the router forwards it to L1NS1.

2. L1NS1 load balances the request to L2NS2.
3. The request is uncacheable (cache bypass). Therefore, L2NS2 sends the request to the origin
server through the router.
4. The origin server sends the response to an upper-tier appliance, L1NS2.
5. According to the PBR policies, L1NS2 forwards the traffic to the appropriate appliance in the
lower tier, L2NS2.
6. L2NS2 uses the client IP address in the request header to identify the client from which the
request came and sends the response directly to the router, avoiding unnecessary load on the
appliance in the upper tier.
7. The router forwards the response to Client A.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1878

NetScaler 12.0

How N-tier cache redirection works during a cache miss

The following figure shows how cache redirection works when a client request is not cached.

Figure 3. Cache Redirection in Case of a Cache Miss

Two NetScaler appliances, L1NS1 and L1NS2, are deployed in the upper tier, and four NetScaler ap-
pliances, L2NS1, L2NS2, L2NS3, and L2NS4, are deployed in the lower tier. Client A sends a request,
which is forwarded by the router. Cache servers CRS1, CRS2, and CRS3 service the cache requests.
Origin Server O services the uncached requests.

Traffic flow

1. Client sends a request, and the router forwards it to L1NS1.

2. L1NS1 load balances the request to L2NS2.
3. L2NS2 load balances the request to the cache server CRS1 because the request is cacheable.
4. CRS1 does not have the response (cache miss). CRS1 forwards the request to the origin server
through the appliance in the lower tier. L2NS3 intercepts the traffic.
5. L2NS3 takes the client IP from the header and forwards the request to the origin server. The
source port included in the packet is the L2NS3 port from which the request is sent to the origin
server.
6. The origin server sends the response to an upper-tier appliance, L1NS2.
7. According to the PBR policies, L1NS2 forwards the traffic to the appropriate appliance in the
lower tier, L2NS3.
8. L2NS3 forwards the response to the router.
9. The router forwards the response to Client A.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Configure the upper-tier NetScaler appliances

September 19, 2018

Contributed by:
C

Configure each of the upper-tier NetScaler appliances as follows.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1879

NetScaler 12.0

Configure an upper-tier appliance for n-tier cache redirection by using the command
CLI

At the command prompt, type the following commands:

1 - add service \<name\>@ \<serviceIP\> \<serviceType\> \<port\>

2
3 Run this command for each service to be added.
4
5 - add lb vserver \<name\>@ ANY \* \<port\> -persistenceType \<
persistenceMethod\> -lbMethod \<lbMethod\> -m MAC -sessionless
ENABLED -cltTimeout \<client\_Timeout\_Value\>
6
7
8 - bind lb vserver \<name\>@ \<serviceName\>
9
10 Run this command for each service to be bound.
11
12 - enable ns mode l3
13
14 - add ns pbr \<name\> \<action\> -srcPort \<sourcePortNumber\> -
destPort \<startPortNumber-endPortNumber\> -nexthop \<
serviceIpAddress\> -protocol TCP
15
16 - apply ns pbrs
17
18 Run this command after adding all the necessary PBRs.

Configure an upper-tier appliance for n-tier cache redirection by using the GUI

1. Enable L3 mode:
a) In the navigation pane, click System, and then click Settings.
b) In the Settings group, click the Configure modes link.
c) Select the Layer 3 Mode (IP Forwarding) check box.
d) Click OK.
2. Configure policy-based routing (PBR):
a) Navigate to System > Network > PBRs.
b) In the Policy-Based Routing (PBRs) pane, click Add.
c) Type a name for the PBR.
d) Select the action as Allow.
e) In the Next Hop box, type the IP address of the service, which represents a lower-tier ap-
pliance.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1880

NetScaler 12.0

f) Select TCP from the Protocol drop-down list.

g) Type the source port and the range of the destination port corresponding to the lower-tier
appliance being added.
h) Click Create.
i) In the details pane, select the PBR and click Apply.
j) Repeat Step (i) to Step (vii) for each lower-tier appliance.
3. Create a service for each lower-tier appliance:
a) Navigate to Traffic Management > Load Balancing > Services.
b) In the details pane, click Add.
c) Specify the name, protocol, IP address, and port. The protocol should be ANY.
d) Click Create.
4. Configure a load balancing virtual server:
a) Navigate to Traffic Management > Load Balancing > Virtual Servers.
b) In the details pane, click Add.
c) Specify the name, protocol, IP address, and port. The protocol should be ANY and the IP
address should be *.
d) In the Services tab, select the services that represent the lower-tier NetScaler appliances.
e) In the Advanced tab, select the Redirection Mode as MAC Based and select the Sessionless
check box.
f) Click Create.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Cache Redirection

Configure the lower-tier NetScaler appliances

September 19, 2018

Contributed by:
C

Configure each of the lower-tier NetScaler appliances as follows.

Configure a lower-tier appliance for n-tier cache redirection by using the CLI

At the command prompt, type the following commands:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1881

NetScaler 12.0

1 - add service <name>@ <cacheServiceIP> <serviceType> <port> -cip

ENABLED ”ClientIP” ‒ cachetype transparent
2
3 Repeat for each cache server.
4
5 - add lb vserver <name>@ <serviceType> -m MAC
6
7 - bind lb vserver <name>@ <cacheServiceName>
8
9 Repeat for each cache server.
10
11 - add cr vserver <name> <serviceType> * <port> -srcIPExpr ”HTTP.REQ.
HEADER(”ClientIP”)” -originusip ON  ‒ usePortRange ON
12
13 - set ns param-crPortRange <startPortNumber-endPortNumber>

Configure a lower-tier appliance for n-tier cache redirection by using the GUI

1. Create a service for each cache server. To create a service:

a) Navigate to Traffic Management > Load Balancing > Services.
b) In the details pane, click Add, and specify the name and protocol. Clear the Directly Ad-
dressable check box.
c) In the Advanced tab, select the Override Global check box and the Client IP check box, and
then in the Header box, type ClientIP.
d) In the Cache Type box, select Transparent Cache.
e) Click Create.
2. Configure a load balancing virtual server:
a) Navigate to Traffic Management > Load Balancing > Virtual Services.
b) In the details pane, click Add and specify the name, protocol, IP address, and port. The IP
address should be an asterisk (*).
c) In the Services tab, select the services that represent the cache servers.
d) In the Advanced tab, for Redirection Mode, select MAC Based.
e) Click Create.
3. Configure a cache redirection virtual server:
a) Navigate to Traffic Management > Load Balancing > Virtual Services.
b) In the details pane, click Add and specify the name, protocol, IP address, and port. The IP
address should be *.
c) For Cache Type, select Transparent.
d) On the Advanced tab, in the Cache Server box, select the new load balancing virtual server
and check the Origin USIP and Use Port Range check boxes. In the Source IP Expression

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1882

NetScaler 12.0

box, type HTTP.REQ.HEADER(“ClientIP”).

e) Click Create.
4. Assign a source port range for the appliance:
a) In the navigation pane, click System, and then click Settings.
b) In the Settings group, click the Change global system settings link.
c) In the Cache Redirection Port Range group, specify the port range for the appliance by
typing a port number for Start Port and a port number for End Port.
d) Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Clustering

September 17, 2018

Contributed by:
C
Note

This feature is available with a NetScaler enterprise or platinum edition license.

A NetScaler cluster is a group of nCore appliances working together as a single system image. Each
appliance of the cluster is called a node. The cluster can have one appliance or as many as 32 NetScaler
nCore hardware or virtual appliances as nodes.

The client traffic is distributed between the nodes to provide high availability, high throughput, and
scalability.

To create a cluster, you must add the appliances as cluster nodes, set up communication between
the nodes, set up links to the client and server networks, configure the appliances, and configure the
distribution of client and server traffic.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1883

NetScaler 12.0

NetScaler appliance configuration support in a cluster

March 26, 2019

Contributed by:
C

Clustering of NetScaler appliances is supported from NetScaler 10 onwards.

The following table lists the NetScaler appliance configurations that are not supported in NetScaler
10 and also gives the status of the features in subsequent releases.

Important

• Unless specified otherwise in this table, all NetScaler appliance features are supported in a
cluster.

• The “Node-level” entry in the table indicates that the feature is supported only on individual
cluster nodes.

Cluster Con-
figuration 10 10.1 10.5 11.0 11.1 12.0

SSL FIPS No No No No No No
SSL No No No No No No
Certificate
Bundle
Content No Yes Yes Yes Yes Yes
switching
actions;
Note: The
content
switching
feature is
supported
from
NetScaler
10.1
onwards.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1884

NetScaler 12.0

Cluster Con-
figuration 10 10.1 10.5 11.0 11.1 12.0

Policy- No Yes Yes Yes Yes Yes

based
logging for
content
switching
policies
Rate No Yes Yes Yes Yes Yes
limiting
Action No Yes Yes Yes Yes Yes
analytics
Branch No Yes Yes Yes Yes Yes
Repeater
load
balancing
GSLB No No Yes Yes Yes Yes
RTSP No No No No Yes Yes
DNSSEC No No No No No No
DNS64 No No No No No No
FTP No No No Yes; Note: Yes Yes
Supported
from
NetScaler
11.0 Build
62.x
onwards.
TFTP No No No No No Yes
Connection No No No No No No
mirroring
Integrated Node-Level Node-level Node-level Node-level Node-Level Node-Level
caching
Large No Node-level Node-level Node-level Node-Level Node-Level
shared
cache

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1885

NetScaler 12.0

Cluster Con-
figuration 10 10.1 10.5 11.0 11.1 12.0

Application No No Node-level Yes Yes Yes

firewall
HTTP Node-level Node-level Node-level Node-level Node-Level Node-Level
Denial-of-
Service
Protection
(HDOSP)
Priority Node-level Node-level Node-level Node-level Node-Level Node-Level
queuing
(PQ)
Sure con- Node-level Node-level Node-level Node-level Node-Level Node-Level
nect (SC)
AppQoE NA Node-level Yes Yes Yes Yes
Surge Node-level Node-level Node-level Node-level Node-Level Node-Level
protection
MPTCP No No Yes Yes Yes Yes
Striped Yes Yes Yes Yes; Note: Yes; Note: Yes; Note:
SNIPs Supported Supported Supported
in L2 in L2 in L2
clusters. clusters. clusters.
Not Not Not
supported supported supported
in L3 in L3 in L3
clusters. clusters. clusters.
MSR Yes Yes Yes Yes; Note: Yes; Note: Yes; Note:
Supported Supported Supported
in L2 in L2 in L2
clusters. clusters. clusters.
Not Not Not
supported supported supported
in L3 in L3 in L3
clusters. clusters. clusters.
IS-IS (IPv4 No Yes Yes Yes Yes Yes
and IPv6)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1886

NetScaler 12.0

Cluster Con-
figuration 10 10.1 10.5 11.0 11.1 12.0

Jumbo No No Yes Yes; Note: Yes Yes

Frames Supported
in L2
clusters.
Not
supported
in L3
clusters.
IP-IP No Yes Yes Yes Yes Yes
tunneling
Link load No No Yes Yes Yes Yes
balancing
FIS No No Yes Yes Yes Yes
(Failover
Interface
Set)
Link redun- No No Yes Yes Yes Yes
dancy
(LR)
NAT46 No No No No No No
NAT64 No No No No No No
RNAT6 No No No No Yes Yes
LSN/CGNAT No No No No No No
IPv6 No No No No No Yes
ReadyLogo
Traffic No No Yes Yes; Note: Yes; Note: Yes; Note:
domains Supported Supported Supported
in L2 in L2 in L2
clusters. clusters. clusters.
Not Not Not
supported supported supported
in L3 in L3 in L3
clusters. clusters. clusters.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1887

NetScaler 12.0

Cluster Con-
figuration 10 10.1 10.5 11.0 11.1 12.0

Route No No No No Yes; Only Yes; Note:

monitor with DR. Supported
in L2
clusters.
Not
supported
in L3
clusters.
GRE No No No No No No
tunneling
(CB)
Layer 2 No No Yes Yes Yes Yes
mode
Net profiles No No Yes Yes Yes Yes
HTTPS No Yes Yes Yes Yes Yes
callout
AAA-TM No Node-level Node-level Node-level Yes Yes
AppFlow No Node-level Node-level Node-level Node-Level Node-Level
Web Insight No No No No Yes Yes
HDX Insight No No No No Yes Yes
VMAC/VRRP No No Yes Yes Yes Yes
NetScaler No No No No No No
Push
Stateful No No No No No No
Connection
Failover
Graceful No No No No No No
Shutdown
DBS No No No No No No
AutoScale
DSR using No No No No No No
TOS

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1888

NetScaler 12.0

Cluster Con-
figuration 10 10.1 10.5 11.0 11.1 12.0

Finer Node-level Node-level Node-level Node-level Node-Level Node-Level

Startup-RR
Control
XML XSM No No No No No No
DHCP RA No No No No No No
Bridge No No Yes; Note: Yes Yes Yes
Group Supported
from
NetScaler
10.5 Build
52.1115.e
onwards.
Network No No No No No No
Bridge
Web No No No Yes Yes Yes
Interface on (check FAQ);
NetScaler Note:
appliance Supported
(WIonNS) from
NetScaler
11.0 Build
62.x
onwards.
EdgeSight No No No No Deprecated Deprecated
Monitoring
Metrics No No No No No No
tables -
Local
DNS Node-level Node-level Node-level Node-level NodeLevel NodeLevel
Caching
Call Home Node-level Node-level Node-level Node-level Node Level Node Level

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1889

NetScaler 12.0

Cluster Con-
figuration 10 10.1 10.5 11.0 11.1 12.0

NetScaler No No Node-level Yes Yes Yes

Gateway
ICA Proxy
mode
NetScaler No No Node-level Node-level Node Level Node Level
Gateway
(SSL VPN /
full VPN
and CVPN)
CloudBridge No No No No No Yes
Connector
Policy No No No No Yes Yes
Based
Routing
(PVR/PVR6)
Subscriber No No No No No No
awarness
Dynamic No No No Yes with v4 Yes with v6 Yes with v6
Routing protocol protocols protocols
support (ospfv3, (ospfv3,
RIPng, RIPng,
ISIS6, ISIS6,
BGP6) BGP6)
support support
SYSLOG- No No No No No Yes
TCP, load
balancing
of sys-
log servers,
SNIP
support,
and FQDN
support for
syslog

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1890

NetScaler 12.0

NetScaler appliance configurations supported from NetScaler 10 onwards

Load balancing, load balancing persistency, DNS load balancing, SIP, maxClient, Spillover (connec-
tion and dynamic), Spillover based on bandwidth, DataStream, Compression control, Content filter-
ing, TCP buffering, Cache redirection, Distributed Denial-of-Service (DDoS), Client Keep-alive, Basic
networking (IPv4 and IPv6), OSPF (IPv4 and IPv6), RIP (IPv4 and IPv6), RIP (IPv4 and IPv6), VLAN,
ICMP, Fragmentation, MBF, ACL, Simple ACL, MSR, Path MTU discovery, IP-IP, SNMP, Policies (clas-
sic and advanced), Rewrite, Responder, HTTP callout, Web server logging, Audit logging (nslog and
syslog), USIP, Location commands, HTML injection, NITRO API, AppExpert, KRPC.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Prerequisites for cluster nodes

October 9, 2018

Contributed by:
C

NetScaler appliances that are to be added to a cluster must satisfy the following criteria:

• All appliances must have the same software version and build.

• All appliances must be of the same platform type. This means that a cluster must have either all
hardware appliances (MPX) or virtual appliances (VPX) or SDX NetScaler appliance instances.

Note

– For a cluster of hardware appliances (MPX), the appliances must be of the same model
type.

– For the formation of the heterogeneous cluster, all appliances must be of MPX platform
type.

– For a cluster of virtual appliances (VPX), the appliances must be deployed on the fol-
lowing hypervisors: XenServer, Hyper-V, VMware ESX, and KVM.

– Clusters of SDX NetScaler appliance instances are supported in NetScaler 10.1 and later
releases. To create a cluster of SDX NetScaler appliance instances, see “Set up a cluster
of Citrix NetScaler instances”.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1891

NetScaler 12.0

– Jumbo frames are supported on a NetScaler cluster that is made up of NetScaler ap-
pliance SDX instances.

– You can create L3 clusters of SDX instances.

• (For releases prior to NetScaler 11.0) All appliances must be on the same network. In NetScaler
11.0 and later releases, appliances can belong to different networks.

• All appliances must have the same licenses. Also, depending on the NetScaler appliance ver-
sion, there are some additional aspects to address:

– For releases prior to NetScaler 10.5 Build 52.x:

* A separate cluster license file is required. This file must be copied to the /nsconfig/li-
cense/ directory of the configuration coordinator.
* Because of the separate cluster license file, the cluster feature is available irrespective
of the NetScaler appliance license.
– For releases after NetScaler 10.5 Build 52.x:
* No separate cluster license is required.
* Cluster is licensed with the Enterprise and Platinum licenses. Cluster is not available
for Standard license.

• Be initially configured and connected to a common client-side and server-side network.

Note

For a cluster of virtual appliances, that has large configurations, it is recommended to use 6 GB
RAM for each node of the cluster.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Cluster overview

January 6, 2019

Contributed by:
C

A NetScaler cluster is formed by grouping NetScaler appliances together. Based on the network lo-
cation of the NetScaler appliances that you intend adding to the cluster, you must be aware of the
following cluster setups:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1892

NetScaler 12.0

Note

Unless specified otherwise, cluster features and configurations are the same for L2 and L3 clus-
ters.

• L2 cluster: In this cluster deployment, all cluster nodes belong to the same network.

• L3 cluster (also referred to as ‘cluster in INC mode’): In this cluster deployment, cluster nodes
can belong to different networks. The cluster nodes from a specific network must be grouped
into nodegroups that include only nodes from that network. From the following figure, we see
that nodes n1, n2, n3 are in the same network and are grouped into Nodegroup1.

Similarly, the case for nodes n4 and n5, that are grouped in Nodegroup2. In the third network,
there are two nodegroups. Nodegroup3 includes n6 and n7 and Nodegroup4 includes n8 and
n9.
Note

Supported from NetScaler 11.0 onwards.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Synchronization across cluster nodes

January 6, 2019

Contributed by:
C

All configurations on a NetScaler cluster are performed on the cluster IP address, which is the man-
agement address of the cluster. This cluster IP address is owned by a cluster node that is referred to
as the cluster configuration coordinator as shown in the following figure:

The configurations that are available on the configuration coordinator are automatically propagated
to the other cluster nodes and therefore all cluster nodes have the same configurations.

• NetScaler appliance allows only a few configurations to be performed on individual cluster

nodes through their NSIP address. In these cases, you must ensure configuration consistency
manually across all nodes in the cluster. These configurations are not propagated across the
other cluster nodes. For more information on operations supported on each cluster nodes, see
“Operations Supported on Individual Cluster Nodes”.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1893

NetScaler 12.0

• The following commands when executed on the cluster IP address are not propagated to other
cluster nodes:
– shutdown. Shuts down only the configuration coordinator.
– reboot. Reboots only the configuration coordinator.
– rm cluster instance. Removes the cluster instance from the node that you are executing
the command on.
• For a command to propagate to other cluster nodes:
– The quorum must be configured on cluster instance.
– The majority of the cluster quorum with (n/2 + 1) of the cluster nodes must be active for
the cluster to be operational.
– A cluster can run with a minimum number of nodes when majority rule (n/2 + 1) is relaxed.

When a node is added to a cluster, the configurations and the files (SSL certificates, licenses, DNS,
and so on) that are available on the cluster configuration coordinator are synchronized to the newly
added cluster node. When an existing cluster node, that was intentionally disabled or that had failed,
is once again added, the cluster compares the configurations available on the node with the configu-
rations available on the configuration coordinator. If there is a mismatch in configurations, the node
is synchronized by using one of the following:

• Full synchronization. If the difference between configurations exceeds 255 commands, all the
configurations of the configuration coordinator are applied to the node that is rejoining the clus-
ter. The node remains operationally unavailable for the duration of the synchronization.
• Incremental Synchronization. If the difference between configurations is less than or equal
to 255 commands, only the configurations that are not available are applied to the node that is
rejoining the cluster. The operational state of the node remains unaffected.

Note

You can also manually synchronize the configurations and files. For more information, see “
Synchronizing Cluster Configurations” and “
Synchronizing Cluster Files”.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Striped, partially striped, and spotted configurations

March 19, 2019

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1894

NetScaler 12.0

Contributed by:
C

By virtue of command propagation, all nodes in a cluster have the same configurations. However,
you may want some configurations to be available only on certain cluster nodes. While you cannot
restrict the nodes on which the configurations are available, you can specify the nodes on which the
configurations are active.

For example, you can:

• define a SNIP address to be active on only one node, or

• define a SNIP address to be active on all nodes, or
• define a VIP address to be active on only one node, or
• define a VIP address to be active on all nodes, or
• define a VIP address to be active only on two nodes of a 3-node cluster

Depending on the number of nodes the configurations are active on, cluster configurations are re-
ferred to as striped, partially striped, or spotted configurations.

Figure 1. Three-node cluster with striped, partially striped, and spotted configurations

The following table provides more details on the types of configurations:

Configuration Type Active on Applicable to Configurations

Striped configuration All the cluster nodes All entries No specific

configurtion required
to make an entity
striped. By default, all
entities defined on a
cluster IP address are
striped on all the
cluster nodes.
Partially striped A subset of cluster Refer Cluster Bind the entities that
configuration nodes Nodegroups. you want to be
partially striped, to a
node group. The
configuration is active
only on the cluste
nodes that belong to
the node group.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1895

NetScaler 12.0

Configuration Type Active on Applicable to Configurations

Spotted configuration Single cluster node SNIP address; SNMP A spotted

Engine ID; Hostname configuration can be
of cluster nodes; defined using one of
Entities that can be two approaches.
bound to a node SNIP address When
group creating the SNIP
address, specify the
node on which you
want the SNIP
address to be active,
as the owner node.
Example, add ns ip
10.102.29.106
255.255.255.0 -type
SNIP -ownerNode 2
(assuming node NS2
ID is 2). Note: You
cannot change the
ownership of a
spotted SNIP address
at run time. To
change the
ownership, you must
first delete the SNIP
address and add it
again by specifying
the new owner.
Entities that can be
bound to a node
group. By binding
the entity to a
single-member node
group.

Note

When you disable USIP, Citrix recommends you to use spotted SNIP addresses. You can use

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1896

NetScaler 12.0

striped SNIP addresses only if there is a shortage of IP addresses. The use of striped IP addresses
can result in ARP flux issues if no spotted IP addresses are present in the same subnet for ARP
resolution.

When you enable USIP, Citrix recommends you to use striped SNIP addresses as a gateway for
server initiated traffic.
1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Communication in a cluster setup

January 6, 2019

Contributed by:
C

The interfaces of NetScaler appliances that are added to a cluster, are prefixed with a node ID. This
helps identify the cluster node to which the interface belongs. Therefore, the interface identifier c/u,
where c is the controller number and u is the unit number, now becomes n/c/u, where n is the node
ID. For example, in the following figure, interface 1/2 of node n1 is represented as 0/1/2, interface 1/1
of node n2 is represented as 1/1/1, and interface 1/4 of node n3 is represented as 2/1/4.

Figure 1. Interface naming convention in a cluster

• Server communication-
The cluster communicates with the server through the physical connections between the cluster
node and the server-side connecting device. The logical grouping of these physical connections
is called the server data plane.
• Client communication- The cluster communicates with the client through the physical connec-
tions between the cluster node and the client-side connecting device. The logical grouping of
these physical connections is called the client data plane.
• Inter-node communication- The cluster nodes can also communicate with each other. The
manner in which they communicate depends on whether the node exists on the same network
or across networks.
– Cluster nodes within the same network communicate with each other by using the cluster
backplane. The backplane is a set of interfaces in which one interface of each node is con-
nected to a common switch, which is called the cluster backplane switch. The different
types of traffic that goes through backplane, which is used by internode communication
are:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1897

NetScaler 12.0

* Node to Node Messaging (NNM)

* Steered traffic
* Configuration propagation and synchronization
– Each node of the cluster uses a special MAC cluster backplane switch address to commu-
nicate with other nodes through the backplane. The cluster special MAC is of the form:
(**0x02 0x00 0x6F **), where is the cluster instance ID, is the node number of the NetScaler
appliance that are added to a cluster.

The following figures shows the communication interfaces in L2 clusters and L3 clusters.

Figure 2. Cluster communication interfaces - L2 cluster

Figure 3. Cluster communication interfaces - L3 cluster

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Traffic distribution in a cluster setup

January 6, 2019

Contributed by:
C

In a cluster setup, external networks view the collection of NetScaler appliances as a single entity. So,
the cluster must select a single node that must receive the traffic. The cluster does this selection by
using Equal Cost Multiple Path (ECMP) or cluster link aggregation traffic distribution mechanism. The
selected node is called the flow receiver.
Note

For an L3 cluster (nodes across different networks), only ECMP traffic distribution can be used.

The flow receiver gets the traffic and then, using internal cluster logic determines the node that must
process the traffic. This node is called the flow processor. The flow receiver steers the traffic to the flow
processor over the backplane (if the flow receiver and the flow processor are on the same network) or
through the tunnel (if the flow receiver and the flow processor are on different networks).

Note

• The flow receiver and flow processor must be nodes capable of serving traffic.
• From NetScaler 11 onwards, you can disable steering on the cluster backplane. For more

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1898

NetScaler 12.0

information, see “Disabling Steering on the Cluster Backplane”.

Figure 1. Traffic distribution in a cluster

The above figure shows a client request flowing through the cluster. The client sends a request to a
virtual IP (VIP) address. A traffic distribution mechanism configured on the client data plane selects
one of the cluster nodes as the flow receiver. The flow receiver receives the traffic, determines the
node that must process the traffic, and steers the request to that node (unless the flow receiver selects
itself as the flow processor).
The flow processor establishes a connection with the server. The server processes the request and
sends the response to the subnet IP (SNIP) address that sent the request to the server.
• If the SNIP address is a striped or partially striped IP address, the traffic distribution mechanism
configured on the server data plane selects one of the cluster nodes as the flow receiver. The
flow receiver receives the traffic, determines the flow processor, and steers the request to the
flow processor through the cluster backplane.
• If the SNIP address is a spotted IP address, the node that owns the SNIP address receives the
response from the server.
In an asymmetric cluster topology (all cluster nodes are not connected to the external switch), you
must use linksets either exclusively or combined with ECMP or cluster link aggregation. For more
information, see “Using Linksets”.
1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Cluster nodegroups

January 6, 2019
Contributed by:
C
Note

Nodegroups are supported from NetScaler 10.1 onwards.

As the name indicates, a cluster nodegroup is a group of cluster nodes.

Figure 1. NetScaler cluster with nodegroups
The above figure shows a cluster which has nodegroups NG1 and NG2 that include 3 cluster nodes
each. The cluster also has 3 nodes that are not part of any nodegroup.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1899

NetScaler 12.0

A nodegroup can be configured for the following:

• To define spotted and partially striped configurations. For more information, see “Nodegroups
for Spotted and Partially-Striped Configurations”.
• To configure redundancy of nodegroups. For more information, see “Configuring Redundancy
for Nodegroups”.
Note: Supported from NetScaler 10.5 Build 52.1115.e onwards.
• To define an L3 cluster (also called a cluster in INC mode). In an L3 cluster, cluster nodes can be
from different networks. You must group nodes that belong to a network in a single nodegroup.
For example, if n1, n2, n3 are in network1 and n4, n5, n6 are in network2, then NG1 must include
nodes of network1 and NG2 must include nodes of network2. For setting up an L3 cluster, see
“Creating a NetScaler cluster”.

Note

• Supported from NetScaler 11 onwards.

• The above functions of a nodegroup are mutually exclusive. This means that a nodegroup
can provide only one of the above mentioned functionality.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Cluster and node states

January 6, 2019

Contributed by:
C

For a cluster to be functional, a majority of the nodes (n/2 + 1) must be operationally active (operational
state is ACTIVE). Check table below.
Important

From NetScaler release 10.5, you can configure the cluster to be functional even when the major-
ity criteria is not satisfied. This configuration must be performed when creating a cluster.

For more information on states of a cluster node, refer to

States of a cluster node.

1.
2. Citrix ADC

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1900

NetScaler 12.0

3. NetScaler 12.0
4. Clustering

Routing in a cluster

September 18, 2018

Contributed by:
C

Routing in a cluster works in much the same way as routing in a standalone system. A few points to
note:

• All routing configurations must be performed from the cluster IP address and the configurations
are propagated to the other cluster nodes.

• Routing runs only on spotted SNIP addresses and NSIP addresses.

• Routes are limited to the maximum number of ECMP routes supported by the upstream router.

• Node-specific routing configurations must be performed by using the owner-node argument as

follows:

1 !
2 interface vlan97
3 !
4 router ospf
5 owner-node 0
6 ospf router-id 97.131.0.1
7 exit-owner-node
8 owner-node 1
9 ospf router-id 97.131.0.2
10 exit-owner-node
11 owner-node 2
12 ospf router-id 97.131.0.3
13 exit-owner-node
14 redistribute kernel
15 network 97.0.0.0/8 area 0
16 !

• Retrieve node-specific routing configurations by specifying the node(s) in the owner-node argu-
ment as follows:

1 > vtysh

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1901

NetScaler 12.0

2 ns# owner-node 0 1
3 ns(node-0 1)# show cluster state
4 ns(node-0 1)# exit-owner-node

• Clear node-specific routing configurations by specifying the node(s) in the owner-node argu-
ment as follows:

1 > vtysh
2 ns# owner-node 0 1
3 ns(node-0 1)# clear config
4 ns(node-0 1)# exit-owner-node

• Routing protocol daemons can run and adjacencies can be formed on active and inactive nodes
of a cluster.

• Only active nodes advertise host routes to striped VIP addresses. Spotted VIP addresses are
advertised by active owner node.

• Active and inactive nodes can learn dynamic routes and install them into the routing table.

• Routes learnt on a node are propagated to other nodes in the cluster only if route propagation
is configured. This is mostly needed in asymmetric topologies where the unconnected nodes
may not be able to form adjacencies.

1 ns(config)# ns route-install propagate

Note*

Make sure that route propagation is not configured in a symmetric cluster topology as it
can result in making the node unavailable to the cluster.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

IP addressing for a cluster

September 18, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1902

NetScaler 12.0

In addition to the standard types of NetScaler appliance-owned IP addresses—NetScaler appliance

NSIP, Virtual IP (VIP), and Subnet IP (SNIP)—a clustered NetScaler appliance can have a cluster man-
agement IP (CLIP) address. It can also have striped and spotted IP addresses.

CLIP address. An IP address owned by the cluster coordinator node (CCO). The CLIP address can float
between different nodes in a cluster setup. If the CLIP is moved to a different node of the cluster, that
node becomes the CCO. The CCO is the NetScaler appliance that is responsible for management tasks
in the cluster. A network administrator uses the CLIP address to connect to the cluster to perform
configuration and management tasks, such as accessing unified GUI, reporting, tracing packet flow,
and collecting logs. The CCO node does not have an NSIP address. Only configurations performed on
the CCO through the cluster IP address are propagated to other nodes in the cluster.

Striped IP address. A logical IP address available on all nodes of the cluster, it can be either a VIP or
SNIP address.

Spotted IP address. A logical IP (preferably SNIP address) is available only on one node. A spotted
IP address has visibility on only that node. To minimize traffic-steering overhead, Citrix recommends
that you use spotted SNIP address for backend communication with the server.

For example, in a four-node cluster group, you must configure each node with a spotted SNIP address.
For more information on how to configure a spotted IP configuration, see Striped, Partially Striped,
and Spotted Configurations.

You can define a SNIP address to be active on only one node, or active on all nodes. If a virtual IP
address and Subnet IP address is available only on a specific node, it is of spotted configuration or if
the Subnet IP address and Virtual server IP address are available on all nodes, it is defined as striped
configuration.

Note

In a four-node cluster setup, you must configure a spotted SNIP address on each node. For more
information about configuring a spotted IP configuration, see Striped, Partially Striped, and Spot-
ted Configurations.

In an L3 cluster setup, only spotted SNIP configuration is supported, as shown in the following table.

IP Address NSIP VIP SNIP

Spotted Yes Yes Yes

Striped No Yes Yes

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1903

NetScaler 12.0

4. Clustering

Configuring layer 3 clustering

January 6, 2019
Contributed by:
C

Understanding L3 Cluster

The demand to expand the high availability deployment and increase the scalability of the client traffic
across different networks guided to establish L3 cluster. The L3 cluster lets you to group NetScaler
appliances across individual subnets (L2 cluster).
L3 cluster is also referred to as “cluster in Independent Network Configuration (INC) mode”. In L3
cluster deployment, the cluster nodes in the same network are grouped together to form a Nodegroup.
L3 cluster uses GRE tunneling to steer the packets across networks. The heartbeat messages across
L3 clusters will be routed.
This document includes the following details:
• Architecture
• Example

Architecture

The L3 cluster architecture comprises of the following components:

• Nodegroup. The cluster nodes from each network (n1, n2) and (n3, n4), as depicted in below
figure, are grouped together to form a Nodegroup. These Nodegroups are terminated to the
layer 3 switch on either side of the network.
– The cluster communicates with the client through the physical connections between the
cluster node and the client-side connecting device. The logical grouping of these physical
connections is called the client data plane.
– The cluster communicates with the server through the physical connections between the
cluster node and the server side connecting device. The logical grouping of these physical
connections is called the server data plane.
• Backplane Switch. Cluster nodes within the same network communicate with each other by
using the cluster backplane. The backplane is a set of interfaces in which one interface of each
node is connected to a common switch, which is called the cluster backplane switch.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1904

NetScaler 12.0

• GRE Tunnel. The ** packets between nodes in a L3 cluster are exchanged over an unencrypted
GRE tunnel that uses the NSIP addresses of the source and destination nodes for routing. The
steering mechanism will change for nodes belonging to different network. The packets are
steered through a GRE tunnel to the node on the other subnet, instead of rewriting the MAC.

Example

Consider an example of an L3 cluster deployment consisting of the following:

• Three NetScaler appliances (n1, n2, and n3) nodes are grouped together into Nodegroup1.
• Similarly, the nodes n4 and n5 are grouped in Nodegroup2. In the third network, there are two
nodegroups. Nodegroup3 includes n6 and n7 and Nodegroup4 includes n8 and n9.
• The NetScaler appliances that belong to the same network are combined together to form a
Nodegroup.

Points to Consider before Configuring L3 Cluster

Consider the following points before configuring L3 cluster on a NetScaler appliance:

• The backplane is not mandatory while configuring L3 subnets. If the backplane is not specified,
the node will not go to backplane fail state.

Note

If you have some cluster nodes in the L2 network, it is mandatory to enable steering on the
cluster backplane, else the nodes will go to backplane fail state.

• The external traffic distribution in L3 cluster supports only Equal Cost Multiple Path (ECMP).

• The following parameters are processed when steering is disabled is an L3 cluster deployment:

– ICMP errors
– Fragmentation
– Striped SNIPs or MIPs

• The entities (route, route6, pbr, and pbr6) can be bound to configuration nodegroup.

• VLAN, RNAT, and IP tunnel cannot be bound to a config nodegroup.

• Config nodegroup should always have property STRICT “YES.

• The cluster nodes should not be added to a config nodegroup via “add cluster node” command.

• The “clear config extended+” command will not clear the entities (route, route6, pbr,
pb6, rnat, IP tunnel, ip6tunnel). These entities should be cleared when an “add cluster instance
–INC enabled” command is configured.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1905

NetScaler 12.0

Configuring L3 Cluster

In an L3 cluster configuration, the cluster command has different attributes to configure that is based
on nodes, and nodegroups. The L3 cluster configuration also includes an IPv6 profile apart from IPv4
profiles.

Configuring L3 cluster on a NetScaler appliance consists of the following tasks:

• Create a cluster instance

• Create a nodegroup in L3 cluster
• Add a NetScaler appliance to the cluster and group with nodegroup
• Add cluster IP address to the node
• Enable the cluster instance
• Save the configuration
• Add a new node to an existing nodegroup
• Create a new nodegroup in L3 cluster
• Group new nodes to the newly created nodegroup
• Join the node to the cluster

Configuring the following by Using the Command Line

• To create a cluster instance by using the NetScaler CLI

add cluster instance <clid> DISABLED> -processLocal DISABLED>

-inc <ENABLED <ENABLED

• To create a nodegroup in L3 cluster

add cluster nodegroup <ng>

• To add a NetScaler appliance to the cluster and to associate with nodegroup

add cluster node <nodeid> <nodeip> -nodegroup <ng>

• To add the cluster IP address on this node

add ns ip <IPAddress> <netmask> -type clip

• Enable the cluster instance

enable cluster instance <clId>

• Save the configuration

save ns config

• Warm reboot the appliance

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1906

NetScaler 12.0

reboot -warm

• To add a new node to an existing nodegroup

add cluster node <nodeid> <nodeip> -nodegroup <ng>

• To create a new nodegroup in L3 cluster

add cluster nodegroup <ng>

• To group new nodes to the newly created nodegroup

add cluster node <nodeid> <nodeip> -nodegroup <ng>

• To join the node to the cluster

1 **join cluster ‒ clip** \<ip\_addr\> -password \<password\>**

2
3 add cluster instance 1 ‒ inc ENABLED ‒ processLocal ENABLED
4
5    Done

Note

The “inc” parameter should be ENABLED for an L3 cluster.

1 add cluster nodegroup ng1

2
3    Done
4
5 > add cluster node 0 1.1.1.1 ‒ state ACTIVE ‒ nodegroup ng1
6
7    Done
8
9 > add ns ip 1.1.1.100 255.255.255.255 ‒ type clip
10
11    Done
12
13 > enable cluster instance 1
14
15    Done
16
17 > save ns config
18
19    Done
20
21 > add cluster node 1 1.1.1.2 ‒ state ACTIVE ‒ nodegroup ng1
22
23    Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1907

NetScaler 12.0

24
25 > add cluster nodegroup ng2
26
27    Done
28
29 > add cluster node 4 2.2.2.1 ‒ state ACTIVE ‒ nodegroup ng2
30
31    Done
32
33 > add cluster node 5 2.2.2.2 ‒ state ACTIVE ‒ nodegroup ng2
34
35    Done
36
37 > join cluster -clip 1.1.1.100 -password nsroot

Advertising Cluster IP address of a Layer 3 Cluster

You must configure the cluster IP address to be advertised to the upstream router to make the cluster
configuration accessible from any subnet. The cluster IP address is advertised as a kernel route by
the dynamic routing protocols configured on a node.

Advertising the cluster IP address consists of the following tasks:

• Enable the host route option of the cluster IP address. The host route option pushes the clus-
ter IP address to ZebOS routing table for kernel route redistribution through dynamic routing
protocols.
• Configuring a dynamic routing protocol on a node. A dynamic routing protocol advertises
the cluster IP address to the upstream router. For more information on configuring a dynamic
routing protocol, see Configuring Dynamic Routes.

To enable the host route option of the cluster IP Address by using the NetScaler CLI

At the command prompt, type:

1 - **add nsip** \<IPAddress\> \<netmask\> -**hostRoute ENABLED**

2 - **show nsip** \<IPAddress\>
3
4 > add ns ip 10.102.29.60 255.255.255.255 -hostRoute ENABLED
5
6    Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1908

NetScaler 12.0

Spotted, partially striped configurations on L3 cluster

The spotted and partially striped configurations on L3 cluster slightly differs from L2 cluster. The con-
figuration might differ from node to node as the nodes reside on different subnets. The network con-
figurations can be node specific in L3 cluster, hence you have to configure the spotted or partially
striped configurations based on the below-mentioned parameters.

To configure spotted, partially striped configurations on a NetScaler appliance over L3 cluster perform
the following tasks:

1 - Add a cluster ownergroup to an IPv4 static routing table

2 - Add a cluster ownergroup to an IPv6 static routing table
3 - Add a cluster ownergroup to an IPv4 policy based routing (PBR)
4 - Add a cluster ownergroup to an IPv6 PBR
5 - Add a VLAN
6 - Bind a VLAN to a specific ownergroup of cluster nodegroup

Configuring the following by Using the Command Line

• To add a cluster ownergroup to an IPv4 static route table of the NetScaler appliance

add route <network> <netmask> <gateway> -ownergroup <ng>

• To add a cluster ownergroup to an IPv6 static route table of the NetScaler appliance

add route6 <network> -ownergroup <ng>

• To add a cluster ownergroup to an IPv4 PBR

add pbr <name> <action> -ownergroup <ng>

• To add a cluster ownergroup to an IPv6 PBR

add pbr6 <name> <action> -ownergroup <ng>

• To add a VLAN

add vlan <id>

• To bind a VLAN to a specific ownergroup of cluster nodegroup

bind vlan <id> -ifnum – ipv6_addr > [-ownergroup <ng>]

[IPAddress <ip_addr

The following commands are sample examples of spotted and partially striped configurations
which can be configured by using the NetScaler CLI.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1909

NetScaler 12.0

1 > add route 10.102.29.0 255.255.255.0 10.102.29.2 ‒ ownergroup ng2

2
3     Done
4
5 > add route6 fe80::9404:60ff:fedd:a464/64 ‒ ownergroup ng1
6
7     Done
8
9 > add pbr pbr1 allow ‒ ownergroup ng1
10
11     Done
12
13 > add pbr6 pbr2 allow ‒ ownergroup ng2
14
15     Done
16
17 > add vlan 2
18
19     Done
20
21 > bind vlan 2 ‒ ifnum 1/2 ‒ [IPAddress 10.102.29.80 | fe80::9404:60
ff:fedd:a464/64-ownergroup ng1
22
23     Done

Configure nodegroup

In an L3 cluster, to replicate the same set of configurations on more than one nodegroup, the following
commands are used:

Configuring the following by Using the Command Line

• To add an IPv4 static route to the routing table of the NetScaler appliance

add route <network> <netmask> <gateway> -ownerGroup <ng>

Sample Configuration

1 add route 0 0 10.102.53.1 ‒ ownerGroup ng1

2
3 add route 0 0 10.102.53.1 ‒ ownerGroup ng2

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1910

NetScaler 12.0

To support the above configuration, a new nodegroup ‘all’ has to be defined and you have to configure
the following commands:

Configuring the following by Using the Command Line

• To add a new nodegroup to cluster with strict parameter

add cluster nodegroup** <name> -strict <YES NO>

• To bind a cluster node or an entity to the given nodegroup

bind cluster nodegroup <name> -node <nodeid>

• To add IPv4 static route to all ownergroup

add route <network> <netmask> <gateway> -ownerGroup <ng>

Sample configuration:

1 add cluster nodegroup all ‒ strict YES

2
3 bind cluster nodegroup all ‒ node 1
4
5 bind cluster nodegroup all ‒ node 2
6
7 add route 0 0 10.102.53.1 ‒ ownerGroup all

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Setting up a NetScaler cluster

September 18, 2018

Contributed by:
C

NetScaler appliances that you want to add to the cluster must satisfy the criteria specified in “Prereq-
uisites for Cluster Nodes”. Before actually setting up a cluster, you must be aware of cluster basics.
For information, see “Cluster Overview”.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1911

NetScaler 12.0

Forming a cluster requires you to set up inter-node communication, create the cluster (by adding the
first NetScaler appliance), and then add the other cluster nodes. Each of these steps is explained with
relevant details in subsequent topics.

Note

While there are some differences in setting up an L2 and L3 cluster, there are many similarities
too. The subsequent topics explain the setup for both cluster types while highlighting the con-
figurations that are specific to L3 clusters.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Setting up inter-node communication

September 18, 2018

Contributed by:
C

The nodes in a cluster setup communicate with one another using the following inter-node communi-
cation mechanisms:

• Nodes that are within the network (same subnet) communicate with each other through the
cluster backplane. The backplane must be explicitly set up. See the detailed steps listed below.
• Across networks, steering of packets is done through a GRE tunnel and other node-to-node com-
munication is routed across nodes as required.
Note:
– A cluster can include nodes from different networks from NetScaler 11.0 onwards.
– In an L3 cluster deployment, packets between NetScaler appliance nodes are exchanged
over an unencrypted GRE tunnel that uses the NSIP addresses of the source and destina-
tion nodes for routing. When this exchange occurs over the internet, in the absence of
an IPSec tunnel, the NSIPs will be exposed on the internet and this could result in secu-
rity issues. Citrix advises customers to establish their own IPSec solution when using a L3
cluster.

To set up the cluster backplane, do the following for every node

1. Identify the network interface that you want to use for the backplane.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1912

NetScaler 12.0

2. Connect an Ethernet or optical cable from the selected network interface to the cluster back-
plane switch.
For example, to use interface 1/2 as the backplane interface for node 4, connect a cable from the 1/2
interface of node 4 to the backplane switch.

Important points to note when setting up the cluster backplane

• Do not use the appliance’s management interface (0/x) as the backplane interface. In a cluster,
the interface 0/1/x is read as:
0 -> node ID 0
1/x -> NetScaler appliance interface
• Backlane interfaces must not be used for the client or server data planes.
• Configure a link aggregate (LA) channel to optimize the throughput of the cluster backplane.
• Citrix recommends that you dedicate a separate switch for the backplane, so that large amounts
of traffic can be handled seamlessly.
• Backplane interfaces of all nodes of a cluster must be connected to the same switch and bound
to the same L2 VLAN.
• If you have multiple clusters with the same cluster instance ID, make sure that the backplane
interfaces of each cluster are bound to a different VLAN.
• The backplane interface is always monitored, regardless of the HA monitoring settings of that
interface.
• The state of MAC spoofing on the different virtualization platforms can affect the steering mech-
anism on the cluster backplane. Therefore, make sure the appropriate state is configured:
– XenServer - Disable MAC spoofing
– Hyper-V - Enable MAC spoofing
– VMware ESX - Enable MAC spoofing (also make sure “Forged Transmits” is enabled)
• The MTU for the cluster backplane is automatically updated. However, if jumbo frames are con-
figured on the cluster, the MTU of the cluster backplane must be explicitly configured. The value
must be set to 78 + X, where X is the maximum MTU of the client and server data planes. For ex-
ample, if MTU of server data plane is 7500 and of the client data plane is 8922, then the MTU of
cluster backplane must be set to 78 + 8922 = 9000. To set this MTU, use the following command:

1 > set interface <backplane_interface> -mtu <value>

• The MTU for interfaces of the backplane switch must be specified to be greater than or equal to
1578 bytes, if the cluster has features like MBF, L2 policies, ACLs, routing in CLAG deployments,
and vPath.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1913

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Creating a NetScaler cluster

September 18, 2018

Contributed by:
C

To create a cluster, start by taking one of the NetScaler appliances that you want to add to the cluster.
On this node, you must create the cluster instance and define the cluster IP address. This node is
the first cluster node and is called the cluster configuration coordinator. All configurations that are
performed on the cluster IP address are stored on this node and then propagated to the other cluster
nodes.

The responsibility of configuration coordination in a cluster is not fixed to a specific node. It can
change over time depending on the following factors:

• The priority of the node. The node with the highest priority (lowest priority number) is made
the configuration coordinator. Therefore, if a node with a priority number lower than that of
the existing configuration coordinator is added, the new node takes over as the configuration
coordinator.
Note

Node priority can be configured from NetScaler 10.1 onwards.

• If the current configuration coordinator goes down. The node with the next lowest priority num-
ber takes over as the configuration coordinator. If the priority is not set or if there are multiple
nodes with the lowest priority number, the configuration coordinator is selected from one of
the available nodes.
Note

The configurations of the appliance (including SNIP addresses and VLANs) are cleared by implic-
itly executing the
clear ns config extended command. However, the default VLAN and NSVLAN are not cleared from
the appliance. Therefore, if you want the NSVLAN on the cluster, make sure it is created before
the appliance is added to the cluster.
For an L3 cluster (cluster nodes on different networks), networking configurations are not cleared

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1914

NetScaler 12.0

from the appliance.

Important

HA Monitor (HAMON) on a cluster setup is used to monitor the health of an interface on each
node. The HAMON parameter should be enabled on each node to monitor the state of the inter-
face. If the operational state of the HAMON enabled interface goes down due to any reason, the
respective cluster node is marked as unhealthy (NOT UP) and that node cannot serve traffic.

To create a cluster by using the command line interface

1. Log on to an appliance (for example, appliance with NSIP address 10.102.29.60) that you want
to add to the cluster.

2. Add a cluster instance.

add cluster instance <clId> -quorumType <NONE | MAJORITY> -inc <ENABLED

| DISABLED>

Note

• The cluster instance ID must be unique within a LAN.

• For an L3 cluster, make sure the inc parameter is set to ENABLED. The “inc” parameter
must be disabled for an L2 cluster.

3. [Only for an L3 cluster] Create a nodegroup. In the next step, the newly added cluster node must
be associated with this nodegroup.

Note

This nodegroup will include all or a subset of the NetScaler appliances that belong to the
same network.

add cluster nodegroup <name>

4. Add the NetScaler appliance to the cluster.

add cluster node <nodeId> <IPAddress> -state <state> -backplane <

interface_name> -nodegroup <name>

Note For an L3 cluster:

• The nodegroup parameter must be set to the name of the nodegroup created above.
• The backplane parameter is mandatory for nodes that are associated with a node-
group that has more than one node, so that the nodes within the network can com-
municate with each other.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1915

NetScaler 12.0

Example

Adding a node for an L2 cluster (all cluster nodes are in the same network).

1 > add cluster node 0 10.102.29.60 -state PASSIVE -backplane 0/1/1

Adding a node for an L3 cluster which includes a single node from each network. Here, you do not
have to set the backplane.

1 > add cluster node 0 10.102.29.60 -state PASSIVE -nodegroup ng1

Adding a node for an L3 cluster which includes multiple nodes from each network. Here, you have to
set the backplane so that nodes within a network can communciate with each other.

1 > add cluster node 0 10.102.29.60 -state PASSIVE -backplane 0/1/1 -

nodegroup ng1

1. Add the cluster IP address (for example, 10.102.29.61) on this node.

add ns ip <IPAddress> <netmask> -type clip

Example

1 > add ns ip 10.102.29.61 255.255.255.255 -type clip

2. Enable the cluster instance.

enable cluster instance <clId>

3. Save the configuration.

save ns config

4. Warm reboot the appliance.

reboot -warm

Verify the cluster configurations by using the show cluster instance command. Verify that the output
of the command displays the NSIP address of the appliance as a node of the cluster.

To create a cluster by using the configuration utility

1. Log on to an appliance (for example, an appliance with NSIP address 10.102.29.60) that you
intend to add to the cluster.
2. Navigate to System > Cluster.
3. In the details pane, click the Manage Cluster link.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1916

NetScaler 12.0

4. In the Cluster Configuration dialog box, set the parameters required to create a cluster. For a
description of a parameter, hover the mouse cursor over the corresponding text box.
5. Click Create.
6. In the Configure cluster instance dialog box, make sure that the Enable cluster instance check
box is selected.
7. In the Cluster Nodes pane, select the node and click Open.
8. In the Configure Cluster Node dialog box, set the State.
9. Click OK, and then click Save.
10. Warm reboot the appliance.
1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Adding a node to the cluster

September 18, 2018

Contributed by:
C
You can seamlessly scale the size of a cluster to include a maximum of 32 nodes. When a NetScaler
appliance is added to the cluster, the configurations from that appliance are cleared (by internally ex-
ecuting the clear ns config -extended command). The SNIP addresses, MTU settings of the backplane
interface, and all VLAN configurations (except the default VLAN and NSVLAN) are also cleared from the
appliance.
The cluster configurations are then synchronized on this node. There can be an intermittent drop in
traffic while the synchronization is in progress.
Important

Before you add a NetScaler appliance to a cluster:

• Set up the backplane interface for the node. Check preceding topic.
• Check if the licenses that are available on the appliance match those availabe on the con-
figuration coordinator. The appliance is added only if the licenses match.
• If you want the NSVLAN on the cluster, make sure that the NSVLAN is created on the appli-
ance before it is added to the cluster.
• <Citrix recommends that you add the node as a passive node. Then, after joining the node
to the cluster, complete the node specific configuration from the cluster IP address. Run

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1917

NetScaler 12.0

the force cluster sync command if the cluster has only spotted IP addresses, has L3 VLAN
binding, or has static routes.
• When an appliance with a preconfigured link aggregate (LA) channel is added to a cluster,
the LA channel continues to exist in the cluster environment. The LA channel is renamed
from LA/x to nodeId/LA/x, where LA/x is the LA channel identifier.

To add a node to the cluster by using the command line interface

1. Log on to the cluster IP address and, at the command prompt, do the following:
• Add the appliance (for example, 10.102.29.70) to the cluster.
add cluster node <nodeId> <IPAddress> -state <state> -backplane <
interface_name> -nodegroup <name>
Note For an L3 cluster:
– The nodegroup parameter must be set to a nodegroup that has nodes of the same
network.
* If this node belongs to the same network as the first node that was added,
then configure the nodegroup that was used for that node.
* If this node belongs to a different network, then create a nodegroup and
bind this node to the nodegroup.
* The backplane parameter is mandatory for nodes that are associated
with a nodegroup that has more than one node, so that the nodes within
the network can communicate with each other.

Example

1 ‘‘‘
2 > add cluster node 1 10.102.29.70 -state PASSIVE -backplane 1/1/1
3 ‘‘‘

Save the configuration.

1 save ns config 1. Log on to the newly added node (for example,

10.102.29.70) and do the following:
2 - Join the node to the cluster.
3
4 ‘‘‘join cluster -clip <ip_addr> -password <password>‘‘‘
5
6 **Example**
7
8 ‘‘‘

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1918

NetScaler 12.0

9 join cluster -clip 10.102.29.61 -password nsroot

10 ‘‘‘

1. Perform the following configurations:

• If the node is added to a cluster that has only spotted IPs, the configurations are synchro-
nized before the spotted IP addresses are assigned to that node. In such cases, L3 VLAN
bindings can be lost. To avoid this loss, either add a striped IP or add the L3 VLAN bindings.
• Define the required spotted configurations.
• Set the MTU for the backplane interface.

2. Save the configuration.

1 save ns config

3. Warm reboot the appliance.

1 reboot -warm

To add a node to the cluster by using the configuration utility

1. Log on to the cluster IP address.

2. Navigate to System > Cluster > Nodes.
3. In the details pane, click Add to add the new node (for example, 10.102.29.70).
4. In the Create Cluster Node dialog box, configure the new node. For a description of a parame-
ter, hover the mouse cursor over the corresponding text box.
5. Click Create. When prompted to perform a warm reboot, click Yes.

To join a previously added node to the cluster by using the configuration utility

If you have used the command line to add a node to the cluster, but have not joined the node to the
cluster, you can use the following procedure.

Note

When a node joins the cluster, it takes over its share of traffic from the cluster and hence an ex-
isting connection can get terminated.

1. Log on to the node that you want to join to the cluster (for example, 10.102.29.70).
2. Navigate to System > Cluster.
3. In the details pane, under Get Started, click the Join Cluster link.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1919

NetScaler 12.0

4. In the Join to existing cluster dialog box, set the cluster IP address and the nsroot password of
the configuration coordinator. For a description of a parameter, hover the mouse cursor over
the corresponding text box.
5. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Viewing the details of a cluster

September 18, 2018

Contributed by:
C

You can view the details of the cluster instance and the cluster nodes by logging on to the cluster IP
address.

To view details of a cluster instance by using the command line interface

Log on to the cluster IP address and, at the command prompt, type:

1 show cluster instance <clId>

Note

When executed from the NSIP address of a cluster node that is not the configuration coordinator,
this command displays the status of the cluster on this node.

To view details of a cluster node by using the command line interface

Log on to the cluster IP address and, at the command prompt, type:

1 show cluster node <nodeId>

To view details of a cluster instance by using the configuration utility

1. Log on to the cluster IP address.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1920

NetScaler 12.0

2. Navigate to System > Cluster.

3. In the details pane, under Get Started, click the Manage Cluster link to view the details of the
cluster.

To view details of a cluster node by using the configuration utility

1. Log on to the cluster IP address.

2. Navigate to System > Cluster > Nodes.
3. In the details pane, click the node for which you want to view the details.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Distributing traffic across cluster nodes

September 18, 2018

Contributed by:
C

After you have created the NetScaler cluster and performed the required configurations, you must
deploy Equal Cost Multiple Path (ECMP) or cluster Link Aggregation (LA) on the client data plane (for
client traffic) or server data plane (for server traffic). These mechanisms distribute external traffic
across the cluster nodes.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Using Equal Cost Multiple Path (ECMP)

January 6, 2019

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1921

NetScaler 12.0

By using the Equal Cost Multiple Path (ECMP) mechanism on a cluster deployment, active cluster
nodes advertise the virtual server IP addresses. The cluster node which receives the advertised traffic
steers the traffic to the node that must process the traffic. There can be redundant steering in spot-
ted and partially striped virtual servers. Therefore, from NetScaler 11 onwards, spotted and partially
striped virtual server IP addresses advertise the owner nodes, which reduce the redundant steering.

You must have detailed knowledge of routing protocols to use ECMP. For more information, see “Con-
figuring Dynamic Routes. For more information on routing in a cluster, see “Routing in a Cluster”.

To use ECMP, you must first perform the following:

• Enable the required routing protocol (OSPF, RIP, BGP, or ISIS) on the cluster IP address.
• Bind the interfaces and the spotted IP address (with dynamic routing enabled) to a VLAN.
• Configure the selected routing protocol and redistribute the kernel routes on the ZebOS by using
the vtysh shell.

You must perform similar configurations on the cluster IP address and on the external connecting
device.
Note

• Make sure that the licenses on the cluster support dynamic routing, otherwise ECMP does
not work.
• ECMP is not supported for wildcard virtual servers since RHI needs a VIP address to adver-
tise to a router and wildcard virtual servers do not have associated VIP addresses.

Figure 1. ECMP topology

As seen in the above figure, the ECMP router can reach the VIP address via SNIP0, SNIP1, or SNIP2.

To configure ECMP on the cluster by using the command line interface

1. Log on to the cluster IP address.

2. Enable the routing protocol.

enable ns feature <feature>

Example: To enable the OSPF routing protocol.

1 > enable ns feature ospf

3. Add a VLAN.

add vlan <id>

Example

1 > add vlan 97

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1922

NetScaler 12.0

4. Bind the interfaces of the cluster nodes to the VLAN.

bind vlan <id> -ifnum <interface_name>

Example

1 > bind vlan 97 -ifnum 0/1/2 1/1/2 2/1/2

5. Add a spotted SNIP address for each node and enable dynamic routing on it.

add ns ip <SNIP> <netmask> -ownerNode <positive_integer> -dynamicRouting

ENABLED

Example

1 > add ns ip 97.131.0.1 255.0.0.0 -ownerNode 0 -dynamicRouting

ENABLED -type SNIP
2
3 > add ns ip 97.131.0.2 255.0.0.0 -ownerNode 1 -dynamicRouting
ENABLED -type SNIP
4
5 > add ns ip 97.131.0.3 255.0.0.0 -ownerNode 2 -dynamicRouting
ENABLED -type SNIP

6. Bind one of the spotted SNIP addresses to the VLAN. When you bind one spotted SNIP address to
a VLAN, all other spotted SNIP addresses defined on the cluster in that subnet are automatically
bound to the VLAN.

bind vlan <id> -IPAddress <SNIP> <netmask>

Example

1 > bind vlan 97 -ipAddress 97.131.0.1 255.0.0.0

Note

You can use NSIP addresses of the cluster nodes instead of adding SNIP addresses. If so,
you do not have to perform steps 3 - 6.

7. Configure the routing protocol on ZebOS using vtysh shell.

Example: To configure OSPF routing protocol on node IDs 0, 1, and 2.

1 > vtysh ! interface vlan97 ! router ospf owner-node 0

ospf router-id 97.131.0.1 exit-owner-node owner-node 1
ospf router-id 97.131.0.2 exit-owner-node owner-node 2
ospf router-id 97.131.0.3 exit-owner-node redistribute
kernel network 97.0.0.0/8 area 0 !

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1923

NetScaler 12.0

Note

For VIP addresses to be advertised, RHI setting must done by using the vserverRHILevel
parameter as follows:

add ns ip <IPAddress> <netmask> -type VIP -vserverRHILevel <vserverRHILevel

>

For OSPF specific RHI settings, there are additional settings that can be done as follows:

add ns ip <IPAddress> <netmask> -type VIP -ospfLSAType ( TYPE1 | TYPE5

)-ospfArea <positive_integer>

Use the add ns ip6 command to perform the above commands on IPv6 addresses.

8. Configure ECMP on the external switch. The following sample configurations are provided for
the Cisco® Nexus 7000 C7010 Release 5.2(1) switch. Similar configurations must be performed
on other switches.

1 //For OSPF (IPv4 addresses) Global config: Configure terminal

feature ospf Interface config: Configure terminal
interface Vlan10 no shutdown ip address 97.131.0.5/8
Configure terminal router ospf 1 network 97.0.0.0/8 area
0.0.0.0 --------------------------------- //For OSPFv3 (IPv6
addresses) Global config: Configure terminal feature ospfv3
Configure terminal interface Vlan10 no shutdown
ipv6 address use-link-local-only ipv6 router ospfv3 1 area
0.0.0.0 Configure terminal router ospfv3 1

Router monitoring cluster nodes in ECMP deployment

In a cluster setup, on an owner node that has a spotted SNIP address configuration, you can now dis-
able the ownerDownResponse option. By default, the option is enabled, allowing the node to respond
to an ICMP/ARP/ICMP6/ND6 request coming from the upstream router. You can now disable this op-
tion to allow the router to monitor if a cluster node is active or inactive. When the router sends a
request, if the option is disabled, it identifies the owner node to be inactive and unavailable for traffic
distribution.

To configure ECMP for static routes traffic distribution by using the command line interface

add ns ip <ipddress> <netmask> -ownernode <node-id> ‒ownerDownResponse

disable

1.
2. Citrix ADC

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1924

NetScaler 12.0

3. NetScaler 12.0
4. Clustering

Use Case: ECMP with BGP routing

September 18, 2018

Contributed by:
C

To configure ECMP with BGP routing protocol, perform the following steps:

1. Log on to the cluster IP address.

2. Enable BGP routing protocol.

1 > enable ns feature bgp

3. Add VLAN and bind the required interfaces.

1 > add vlan 985

2 > bind vlan 985 -ifnum 0/0/1 1/0/1

4. Add the spotted IP address and bind them to the VLAN.

1 > add ns ip 10.100.26.14 255.255.255.0 -ownerNode 1 -

dynamicRouting ENABLED
2 > add ns ip 10.100.26.15 255.255.255.0 -ownerNode 2 -
dynamicRouting ENABLED
3 > bind vlan 985 -ipAddress 10.100.26.10 255.255.255.0

5. Configure BGP routing protocol on ZebOS using vtysh shell.

1 > vtysh
2 conf t
3 router bgp 65535
4 neighbor 10.100.26.1 remote-as 65535

6. Configure BGP on the external switch. The following sample configurations are provided for
the Cisco® Nexus 7000 C7010 Release 5.2(1) switch. Similar configurations must be performed
on other switches.

1 router bgp 65535

2 no synchronization

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1925

NetScaler 12.0

3 bgp log-neighbor-changes
4 neighbor 10.100.26.14 remote-as 65535
5 neighbor 10.100.26.15 remote-as 65535
6 no auto-summary
7 dont-capability-negotiate
8 dont-capability-negotiate
9 no dynamic-capability

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Using cluster link aggregation

January 6, 2019
Contributed by:
C
Cluster link aggregation, as the name suggests, is a group of interfaces of cluster nodes. It is an ex-
tension of NetScaler appliance link aggregation. The only difference is that, while link aggregation
requires the interfaces to be from the same device, in cluster link aggregation, the interfaces are from
different nodes of the cluster. For more information about link aggregation, see “Configuring Link
Aggregation”.
Important

• Cluster link aggregation is supported for a cluster of hardware (MPX) appliances.

• Cluster link aggregation is supported for a cluster of virtual (VPX) appliances that are de-
ployed on ESX and KVM hypervisors, with the following restrictions:

• Dedicated interfaces need to be used. This means that the interfaces must not be shared
with other virtual machines.

• If the cluster link aggregation member interfaces are manually disabled or if cluster link
aggregation itself is manually disabled, then interface power down capability is achieved
only by LACP timeout mechanism.

• Jumbo MTU is not supported on LACP cluster link aggregation.

Note: Cluster link aggregation is not supported on VPX appliances that are deployed on
XenServer, AWS, and Hyper-V.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1926

NetScaler 12.0

• Starting from 12. 0 release, cluster link aggregation is supported on NetScaler appliance
SDX appliances.
• The number of interfaces that can be bound to cluster LA is 16 (from each node), and the
maximum number of interfaces in cluster LA can be (16 * n), where n is the number of nodes
in a cluster. The total number of interfaces in cluster LA depends on the number of interfaces
for every port channel on upstream switch.

For example, consider a three-node cluster where all three nodes are connected to the upstream
switch. A cluster LA channel (CLA/1) is formed by binding interfaces 0/1/2, 1/1/2, and 2/1/2.

Figure 1. Cluster Link Aggregation topology

A cluster LA channel has the following attributes:

• Each channel has a unique MAC agreed upon by cluster nodes.

• The channel can bind both local and remote nodes’ interfaces.
• A maximum of four cluster LA channels are supported in a cluster.
• Backplane interfaces cannot be part of a cluster LA channel.
• When an interface is bound to a cluster LA channel, the channel parameters have precedence
over the network interface parameters. A network interface can be bound to one channel only.
• Management access to a cluster node, must not be configured on a cluster LA channel (for ex-
ample, CLA/1) or its member interfaces. This is because when the node is INACTIVE, the cor-
responding cluster LA interface is marked as power down and therefore looses management
access.

Figure 2. Traffic distribution flow using cluster LA

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Static cluster link aggregation

September 18, 2018

Contributed by:
C

You must configure a static cluster LA channel on the cluster IP address and on the external connecting
device. If possible, configure the upstream switch to distribute traffic based on IP address or port
instead of MAC address.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1927

NetScaler 12.0

To configure a static cluster LA channel by using the command line interface

1. Log on to the cluster IP address.

Note

Make sure that you configure the cluster LA channel on the cluster IP address before con-
figuring link aggregation on the external switch. Otherwise, the switch will forward traffic
to the cluster even though the cluster LA channel is not configured. This can lead to loss
of traffic.

2. Create a cluster LA channel.

add channel <id> -speed <speed>

Example

1 > add channel CLA/1 -speed 1000

Note

You must not specify the speed as AUTO. Rather, you must explicitly specify the speed as 10,
100, 1000, or 10000. Only interfaces that have the speed matching the <speed> attribute
in the cluster LA channel are added to the active distribution list.

3. Bind the required interfaces to the cluster LA channel. Make sure that the interfaces are not used
for the cluster backplane.

bind channel <id> <ifnum>

Example

1 > bind channel CLA/1 0/1/2 1/1/2 2/1/2

4. Verify the configurations.

show channel <id>

Example

1 > show channel CLA/1

Note

You can bind the cluster LA channel to a VLAN by using the bind vlan command. The inter-
faces of the channel are automatically bound to the VLAN.

5. Configure static LA on the external switch. The following sample configurations are provided
for the Cisco® Nexus 7000 C7010 Release 5.2(1). Similar configurations must be performed on
other switches.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1928

NetScaler 12.0

1
2 Global config:
3 Configure terminal
4
5 Interface level config:
6
7 interface Ethernet2/47
8 switchport
9 switchport access vlan 10
10 channel-group 7 mode on
11 no shutdown
12
13 interface Ethernet2/48
14 switchport
15 switchport access vlan 10
16 channel-group 7 mode on
17 no shutdown

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Dynamic cluster link aggregation

September 18, 2018

Contributed by:
C

Dynamic cluster LA channel uses Link Aggregation Control Protocol (LACP).

You must perform similar configurations on the cluster IP address and on the external connecting
device. If possible, configure the upstream switch to distribute traffic based on IP address or port
instead of MAC address.

Points to remember:

• Enable LACP (by specifying the LACP mode as either ACTIVE or PASSIVE).

Note

Make sure the LACP mode is not set as PASSIVE on both the NetScaler cluster and the ex-

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1929

NetScaler 12.0

ternal connecting device.

• Specify the same LACP key on each interface that you want to be the part of the channel. For
creating a cluster LA channel, the LACP key can have a value from 5 through 8. For example, if
you set the LACP key on interfaces 0/1/2, 1/1/2, and 2/1/2 to 5, CLA/1 is created. The interfaces
0/1/2, 1/1/2, and 2/1/2 are automatically bound to CLA/1. Similarly, if you set the LACP key to 6,
CLA/2 channel is created.

• Specify the LAG type as Cluster.

To configure a dynamic cluster LA channel by using the command line interface

On the cluster IP address, for each interface that you want to add to the cluster LA channel, type:

set interface <id> -lacpMode <lacpMode> -lacpKey <positive_integer> -

lagType CLUSTER

Example: To configure a cluster LA channel CLA/1 of 3 interfaces.

1 > set interface 0/1/2 -lacpMode active -lacpKey 5 -lagType Cluster

2 > set interface 1/1/2 -lacpMode active -lacpKey 5 -lagType Cluster
3 > set interface 2/1/2 -lacpMode active -lacpKey 5 -lagType Cluster

Note

Optionally, you can enable

Link Redundancy in a Cluster with LACP.

Similarly, configure dynamic LA on the external switch. The following sample configurations are pro-
vided for the Cisco® Nexus 7000 C7010 Release 5.2(1). Similar configurations must be performed on
other switches.

1
2 Global config:
3 Configure terminal
4 feature lacp
5 Interface level config:
6
7 interface Ethernet2/47
8 switchport
9 switchport access vlan 10
10 channel-group 7 mode active
11 no shutdown
12
13 interface Ethernet2/48
14 switchport

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1930

NetScaler 12.0

15 switchport access vlan 10

16 channel-group 7 mode active
17 no shutdown

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Link redundancy in a cluster with LACP

January 6, 2019

Contributed by:
C

A NetScaler cluster provides link redundancy for LACP to ensure that all nodes have the same partner
key.

To understand the need for link redundancy, let us consider the example of the following cluster setup
along with the accompanying cases (with attention to case 3):

In this setup, interfaces I1, I2, I3 and I4 are bound to LACP channel with KEY 5. On the partner side,
I1 and I2 are connected to Switch 1 to form a single LA channel with KEY 1. Similarly, I3 and I4 are
connected to Switch 2 to form a single LA channel with KEY 2.

Now let us consider the following cases to understand the need for link redundancy:

• Case 1: Switch 1 is up and Switch 2 is down

In this case, cluster LA on both the nodes would stop receiving LACPDUs from Key2 and would
start receiving LACPDUs from Key1. On both the nodes, cluster LA is connected to KEY 1 and I1
and I2 will be UP and channel on both the nodes would be UP.

• Case 2: Switch1 goes down and Switch2 becomes UP

In this case, cluster LA on both the nodes would stop receiving LACPDUs from Key1 and would
start receiving LACPDUs from Key2. On both the nodes, cluster LA is connected to Key2 and I3
and I4 will be UP and channel on both the nodes would be UP.

• Case 3: Both Switch1 and Switch2 are UP

In this case, it is possible that cluster LA on node1 chooses Key1 as its partner and cluster LA on
node2 chooses Key2 as its partner. This means that I1 on node1 and I4 on node2 are receiving
traffic which is undesirable. This can happen because the LACP state machine is node-level and

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1931

NetScaler 12.0

chooses its partners on first-come first-serve basis.

To solve these concerns, link redundancy of dynamic cluster LA is supported. To configure link
redundancy on a channel or interface, you must enable it
and optionally specify the threshold throughput as follows:
set channel CLA/1 -linkRedundancy ON -lrMinThroughput <positive_integer>
The throughput of the partner channels is checked against the configured threshold through-
put. The partner channel that satisfies the threshold throughput is selected in first-in-first-out
(FIFO) manner. If none of the partner channel meets the threshold, or if threshold throughput
is not configured, the partner channel with the maximum number of links is selected.
Note

The threshold throughput can be configured from NetScaler 11 onwards.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Managing the NetScaler cluster

September 18, 2018

Contributed by:
C
After you have created a cluster and configured the required traffic distribution mechanism, the clus-
ter is able to serve traffic. During the lifetime of the cluster, you can perform cluster tasks such as con-
figuring nodegroups, disabling nodes of a cluster, discovering NetScaler appliances, viewing statis-
tics, synchronizing cluster configurations, cluster files, and the time across the nodes, and upgrading
or downgrading the software of cluster nodes.
1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Configuring linksets

January 6, 2019

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1932

NetScaler 12.0

Contributed by:
C

Linksets must be used when some cluster nodes are not physically connected to the external network.
In such a cluster topology, the unconnected cluster nodes use the interfaces specified in the linkset to
communicate with the external network through the cluster backplane. Linksets are typically used in
scenarios when the connecting devices have insufficient ports to connect the cluster nodes.

Note

Linksets are a mandatory configuration in the following scenarios:

• For deployments that require MAC-Based Forwarding (MBF).

• To improve manageability of ACL and L2 policies involving interfaces. You must define a linkset
of the interfaces and add ACL and L2 policies based on linksets.

Linksets must be configured only through the cluster IP address.

For example, consider a three node cluster where the upstream switch has only two ports available.
Using linksets, you can connect two nodes to the switch and leave the third node unconnected. In
the following figure, a linkset (LS/1) is formed by binding the interfaces 0/1/2 and 1/1/2. NS2 is the
unconnected node of the cluster.

Figure 1. Linksets topology

The linkset informs NS2 that it can use interfaces 0/1/2 and 1/1/2 to communicate with the network
devices. All traffic to and from NS2 is now routed through interfaces 0/1/2 or 1/1/2.

Figure 2. Traffic distribution flow using linksets

To configure a linkset by using the command line interface

1. Log on to the cluster IP address.

2. Create a linkset.

add linkset <id>

Example

1 add linkset LS/1

3. Bind the required interfaces to the linkset. Make sure the interfaces are not used for the cluster
backplane.

bind linkset <id> -ifnum <interface_name> ...

Example

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1933

NetScaler 12.0

1 > bind linkset LS/1 -ifnum 0/1/2 1/1/2

4. Verify the linkset configurations.

show linkset <id>

Example

1 > show linkset LS/1

Note

You can bind the linkset to a VLAN by using the bind vlan command. The interfaces of the
linkset are automatically bound to the VLAN.

To configure a linkset by using the configuration utility

1. Log on to the cluster IP address.

2. Navigate to System > Network > Linksets.
3. In the details pane, click Add.
4. In the Create Linkset dialog box:
• Specify the name of the linkset by setting the Linkset parameter.
• Specify the Interfaces to be added to the linkset and click Add. Repeat this step for each
interface you want to add to the linkset.
5. Click Create, and then click Close.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Nodegroups for spotted and partially-striped configurations

January 6, 2019

Contributed by:
C

By virtue of the default cluster behavior, all configurations performed on the cluster IP address are
available on all nodes of the cluster. However, there might be cases where you need some configura-
tions to be available only on specific cluster nodes.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1934

NetScaler 12.0

You can achieve this requirement by defining a nodegroup that includes the specific cluster nodes,
and then binding the configuration to that nodegroup. This ensures that the configuration is active
only on those cluster nodes. These configurations are called partially-striped or spotted (if active only
one a single node). For more information, see Striped, Partially Striped, and Spotted Configurations.

For example, consider a cluster with three nodes. You create a nodegroup NG0 that includes node n1
and another nodegroup NG1 that includes n2 and n3. Bind load balancing virtual servers .77 to NG0
and load balancing virtual server .69 to NG1.

This means that virtual server .77 will be active only on n1 and consequently only n1 will receive traffic
that is directed to .77. Similarly, virtual server .69 will be active only on nodes n2 and n3 and conse-
quently only n2 and n3 will receive traffic that is directed to .69.

Figure 1. NetScaler cluster with nodegroups configured for spotted and partial-striped configurations

The entities or configurations that you can bind to a nodegroup are:

• Load balancing, content switching, cache redirection, authentication, authorization, and audit-
ing virtual servers

Note

FTP load balancing virtual servers cannot be bound to nodegroups.

• VPN virtual server (Supported from NetScaler 10.5 Build 50.10 onwards)

• Global Server Load Balancing (GSLB) sites and other GSLB entities (Supported from NetScaler
10.5 Build 52.11 onwards)

• Limit identifiers and stream identifiers

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Behavior of nodegroups

September 18, 2018

Contributed by:
C

Due to the interoperability of nodegroups with different NetScaler features and entities, there are
some behavioral aspects to be noted. Nodes in a nodegroup can also be backed up. Read on for more
information.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1935

NetScaler 12.0

General behavior of a cluster nodegroup

• A nodegroup that has entities bound to it cannot be removed.

• A cluster node that belongs to a nodegroup with entities bound to it, cannot be removed.

• A cluster instance that has nodegroups with entities bound to it, cannot be removed.

• You cannot add an entity that has a dependency on another entity that is not part of the node-
group. If you need to do so, first remove the dependency. Then, add both the entities to the
nodegroup and reassociate the entities.

Examples:

– Assume you have a virtual server, VS1, whose backup is virtual server VS2. To add VS1 to
a nodegroup, first make sure that VS2 is removed as the backup server of VS1. Then, bind
each server individually to the nodegroup, and then configure VS2 as the backup for VS1.
– Assume you have a content switching virtual server, CSVS1, whose target load balancing
virtual server is LBVS1. To add CSVS1 to a nodegroup, first remove LBVS1 as the target.
Then, bind each server individually to the nodegroup, and then configure LBVS1 as the
target.
– Assume you have a load balancing virtual server, LBVS1, that has a policy which invokes
another load balancing virtual server, LBVS2. To add either one of the virtual servers, first
remove the association. Then, bind each server individually to the nodegroup, and then
reassociate the virtual servers.

• You cannot bind an entity to a nodegroup that has no nodes and that has the strict option en-
abled. Consequently, you cannot unbind the last node of a nodegroup that has entities bound
to it and that has the strict option enabled.

• The strict option cannot be modified for a nodegroup that has no nodes but has entities bound
to it.

Backing up nodes in a nodegroup

By default, a nodegroup is designed to provide back up nodes for members of a nodegroup. If a node-
group member goes down, a cluster node that is not a member of the nodegroup dynamically replaces
the failed node. This node is called the replacement node.

Note: For a single-member nodegroup, a backup node is automatically preselected when an entity is
bound to the nodegroup.

When the original member of the nodegroup comes up, the replacement node, by default, is replaced
by the original member node.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1936

NetScaler 12.0

From NetScaler 10.5 Build 50.10 onwards, however, the NetScaler appliance allows you to change this
replacement behavior. When you enable the sticky option, the replacement node is retained even
after the original member node comes up. The original node takes over only when the replacement
node goes down.
You can also disable the backup functionality. To do this, you must enable the strict option. In this
scenario, when a nodegroup member goes down, no other cluster node is picked up as a backup node.
The original node continues being part of the nodegroup when it comes up. This option ensures that
entities bound to a nodegroup are active only on nodegroup members.
Note

The strict and sticky option can be set only when creating a nodegroup.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Configuring nodegroups for spotted and partially-striped configurations

September 18, 2018

Contributed by:
C
To configure a nodegroup for spotted and partially-striped configurations you must first create a node-
group and then bind the required nodes to the nodegroup. You must then associate the required en-
tities to that nodegroup. The entities that are bound to the nodegroup will be:
• Spotted - If bound to a nodegroup that has a single node.
• Partially Striped - If bound to a nodegroup that has more than one node.
Some points to remember:
• GSLB is supported on a cluster only when GSLB sites are bound to nodegroups that have a single
cluster node. For more information, see Setting Up GSLB in a Cluster.
• NetScaler Gateway is supported on a cluster only when the VPN virtual servers are bound to
nodegroups that have a single cluster node. The sticky option must be enabled on the node-
group.
• For versions prior to NetScaler 11, application firewall is supported only on individual cluster
nodes (spotted configuration). Application firewall profiles can be associated only with virtual
servers that are bound to nodegroups that have a single cluster node. This means that applica-
tion You are not allowed to do the following:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1937

NetScaler 12.0

– Bind application firewall profiles to striped or partially striped virtual servers.

– Bind the policy to a global bind point or to user-defined policy labels.
– Unbind, from a nodegroup, a virtual server that has application firewall profiles.
• NetScaler 11 introduced application firewall support for striped and partially-striped configura-
tions. For more information, see Application Firewall Support for Cluster Configurations.

Check NetScaler appliance Features Supported in a Cluster to see the NetScaler versions from which
GSLB, Citrix Gateway, and application firewall are supported in a cluster.

To configure a nodegroup by using the command line interface

1. Log on to the cluster IP address.

2. Create a nodegroup. Type:

add cluster nodegroup <name> -strict (**YES** | **NO**)

Example

1 add cluster nodegroup NG0 -strict YES

3. Bind the required nodes to the nodegroup. Type the following command for each member of
the nodegroup:

bind cluster nodegroup <name> -node <nodeId>

Example

To bind nodes with IDs 1, 5, and 6.

1 > bind cluster nodegroup NG0 -node 1

2 > bind cluster nodegroup NG0 -node 5
3 > bind cluster nodegroup NG0 -node 6

4. Bind the entity to the nodegroup. Type the following command once for every entity that you
want to bind:

bind cluster nodegroup <name> (-vServer <string> | -identifierName <

string> | -gslbSite <string> -service <string>)

Note

The gslbSite and service parameters are available from NetScaler 10.5 onwards.

Example

To bind virtual servers VS1 and VS2 and rate limit identifier named identifier1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1938

NetScaler 12.0

1 > bind cluster nodegroup NG0 -vServer VS1

2 > bind cluster nodegroup NG0 -vServer VS2
3 > bind cluster nodegroup NG0 -identifierName identifier1

5. Verify the configurations by viewing the details of the nodegroup. Type:

show cluster nodegroup <name>

Example

1 > show cluster nodegroup NG0

To configure a nodegroup by using the configuration utility

1. Log on to the cluster IP address.

2. Navigate to System > Cluster > Node Groups.
3. In the details pane, click Add.
4. In the Create Node Group dialog box, configure the nodegroup:
a) Under Cluster Nodes, click the Add button.
• The Available list displays the nodes that you can bind to the nodegroup and the Con-
figured list displays the nodes that are bound to the nodegroup.
• Click the + sign in the Available list to bind the node. Similarly, click the - sign in the
Configured list to unbind the node.
b) Under Virtual Servers, select the tab corresponding to the type of virtual server that you
want to bind to the nodegroup. Click the Add button.
• The Available list displays the virtual servers that you can bind to the nodegroup and
the Configured list displays the virtual servers that are bound to the nodegroup.
• Click the + sign in the Available list to bind the virtual server. Similarly, click the - sign
in the Configured list to unbind the virtual server.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Configuring redundancy for nodegroups

January 6, 2019

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1939

NetScaler 12.0

Contributed by:
C
Note

Supported from NetScaler 10.5 Build 52.1115.e onwards.

Nodegroups can be configured such that when one nodegroup goes down, another nodegroup can
take over and process traffic. For example, when a nodegroup NG1 goes down, NG2 takes over.

Note

This functionality can be used to configure datacenter redundancy where each nodegroup is con-
figured as a datacenter.

To achieve this use case, cluster nodes must be logically grouped into nodegroups, where some node-
groups must be configured as ACTIVE and others as SPARE. The active nodegroup with the highest
priority (that is, the lowest priority number) is made operationally active and therefore serves traffic.
When a node from this operationally active nodegroup goes down, the node count of this nodegroup
is compared with the node count of the other active nodegroups in order of their priority. If a node-
group has a higher or equal node count, that nodegroup is made operationally active. Else, the spare
nodegroups are checked.

Note

• Only one state-specific nodegroup can be active at a given point in time.

• A cluster node inherits the state of the nodegroup. So, if a node with “SPARE” state is added
to nodegroup with state as “ACTIVE”, the node automatically behaves as an active node.
• The preemption parameter that is defined for the cluster instance decides whether the ini-
tial active nodegroup will take control when the it comes up again.
• A spare node group can take up a node group and host active traffic when an active node
group goes down.

The following figure shows a nodegroup setup that has nodegroup redundancy defined. NG1 is initially
the active nodegroup. When it loses one of the nodes, the spare nodegroup (NG3) with the highest
priority starts serving traffic.

Figure 1. NetScaler cluster with nodegroup redundancy configured

Configuring redundancy for nodegroups

1. Log on to the cluster IP address.

2. Create the active nodegroup and bind the required cluster nodes.

1 add cluster nodegroup NG1 -state ACTIVE

2 bind cluster nodegroup NG1 -node n1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1940

NetScaler 12.0

3 bind cluster nodegroup NG1 -node n2

4 bind cluster nodegroup NG1 -node n3

1. Create the spare nodegroup and bind the requisite nodes.

1 add cluster nodegroup NG2 -state SPARE -priority 20

2 bind cluster nodegroup NG2 -node n4
3 bind cluster nodegroup NG2 -node n5
4 bind cluster nodegroup NG2 -node n6

1. Create another spare nodegroup and bind the requisite nodes.

1 add cluster nodegroup NG3 -state SPARE -priority 10

2 bind cluster nodegroup NG3 -node n7
3 bind cluster nodegroup NG3 -node n8
4 bind cluster nodegroup NG3 -node n9

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Disabling steering on the cluster backplane

September 18, 2018

Contributed by:
C
Note

Supported from NetScaler 11 onwards.

The default behavior of a NetScaler cluster is to direct the traffic that it receives (flow receiver) to an-
other node (flow processor) that must then process the traffic. This process of directing the traffic
from flow receiver to flow processor occurs over the cluster backplane and is called steering.

If required, you can disable steering so that the process becomes local to the flow receiver and there-
fore makes the flow receiver as the flow processor. Such a configuration setup can come handy when
you have a high latency link.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1941

NetScaler 12.0

Note

This configuration is applicable only for striped virtual servers.

• For partially striped virtual servers, if the flow receiver is a non-owner node, the traffic is steered
to a owner node. If however, the flow receiver is a owner node, then steering is disabled.
• For spotted virtual servers, flow receiver is the flow processor, and hence there is no need for
steering.
Some points to remember when disabling the steering mechanism:
• Striped SNIPs are not supported as steering is disabled.
• MPTCP and FTP does not work.
• L2 mode must be disabled.
• If USIP is enabled, traffic may not reach back to the same node as the steering is disabled.
• Traffic that is directed to the cluster IP address is steered to the configuration coordinator.
• When a node joins or leaves a cluster, it is possible that more than 1/N connections will be af-
fected. This is due to the fact that a change in the nodes available, may cause the routes to be
rehashed. As a result, the traffic will be routed to another node and due to the non-availability
of steering, the traffic will not be processed.
Steering can be disabled at the individual virtual server level or at the global level. The global config-
uration takes precedence over the virtual server setting.
• Disabling backplane steering for all striped virtual servers
Configured at cluster instance level. Traffic meant for any striped virtual server will not be
steered on cluster backplane.
add cluster instance \<clId\> -processLocal ENABLED

• Disabling backplane steering for a specific striped virtual server

Configured on a striped virtual server. Traffic meant for the virtual server will not be steered on
cluster backplane.
add lb vserver <name> <serviceType> -processLocal ENABLED

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Synchronizing cluster configurations

September 18, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1942

NetScaler 12.0

Contributed by:
C

NetScaler appliance configurations that are available on the configuration coordinator are synchro-
nized to the other nodes of the cluster when:

• A node joins the cluster

• A node rejoins the cluster
• A new command is executed through the cluster IP address.

Additionally, you can forcefully synchronize the configurations that are available on the configuration
coordinator (full synchronization) to a specific cluster node. Make sure you synchronize one cluster
node at a time, otherwise the cluster can get affected.

To synchronize cluster configurations by using the command line interface

At the command prompt of the appliance on which you want to synchronize the configurations, type:

force cluster sync

To synchronize cluster configurations by using the configuration utility

1. Log on to the appliance on which you want to synchronize the configurations.

2. Navigate to System > Cluster.
3. In the details pane, under Utilities, click Force cluster sync.
4. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Synchronizing time across cluster nodes

September 18, 2018

Contributed by:
C

The cluster uses Precision Time Protocol (PTP) to synchronize the time across cluster nodes. PTP uses
multicast packets to synchronize the time. If there are some issues in time synchronization, you must
disable PTP and configure Network Time Protocol (NTP) on the cluster.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1943

NetScaler 12.0

To enable/disable PTP by using the command line interface

At the command prompt of the cluster IP address, type:

1 set ptp -state disable

To enable/disable PTP by using the configuration utility

1. Log on to the cluster IP address.

2. Navigate to System > Cluster.
3. In the details pane, under Utilities, click Configure PTP Settings.
4. In the Enable/Disable PTP dialog box, select whether you want to enable or disable PTP.
5. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Synchronizing cluster files

September 18, 2018

Contributed by:
C

The files available on the configuration coordinator are called cluster files. These files are automati-
cally synchronized on the other cluster nodes when the node is added to the cluster and periodically,
during the lifetime of the cluster. Additionally, you can manually synchronize the cluster files.

The directories and files from the configuration coordinator that are synchronized are:

• /nsconfig/ssl/
• /var/netscaler/ssl/
• /var/vpn/bookmark/
• /nsconfig/dns/
• /nsconfig/htmlinjection/
• /netscaler/htmlinjection/ens/
• /nsconfig/monitors/
• /nsconfig/nstemplates/
• /nsconfig/ssh/

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1944

NetScaler 12.0

• /nsconfig/rc.netscaler
• /nsconfig/resolv.conf
• /nsconfig/inetd.conf
• /nsconfig/syslog.conf
• /nsconfig/snmpd.conf
• /nsconfig/ntp.conf
• /nsconfig/httpd.conf
• /nsconfig/sshd_config
• /nsconfig/hosts
• /nsconfig/enckey
• /var/nslw.bin/etc/krb5.conf
• /var/nslw.bin/etc/krb5.keytab
• /var/lib/likewise/db/
• /var/download/
• /var/wi/tomcat/webapps/
• /var/wi/tomcat/conf/Catalina/localhost/
• /var/wi/java_home/lib/security/cacerts
• /var/wi/java_home/jre/lib/security/cacerts
• /nsconfig/license/
• /nsconfig/rc.conf

Tip

Files (certificates and key files) that are copied to the cluster configuration coordinator manually
(or through the shell) are not automatically available on the other cluster nodes. You must exe-
cute the “sync cluster files” command from the cluster IP address before executing a command
that depends on these file(s).

To synchronize cluster files by using the command line interface

At the command prompt of the cluster IP address, type:

sync cluster files <mode>

To synchronize cluster files by using the configuration utility

1. Log on to the cluster IP address.

2. Navigate to System > Cluster.
3. In the details pane, under Utilities, click Synchronize cluster files.
4. In the Synchronize cluster files dialog box, select the files to be synchronized in the Mode drop-
down box.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1945

NetScaler 12.0

5. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Viewing the statistics of a cluster

September 18, 2018

Contributed by:
C

You can view the statistics of a cluster instance and cluster nodes to evaluate the performance or to
troubleshoot the operation of the cluster.

To view the statistics of a cluster instance by using the command line interface

At the command prompt of the cluster IP address, type:

1 stat cluster instance <clId>

To view the statistics of a cluster node by using the command line interface

At the command prompt of the cluster IP address, type:

1 stat cluster node <nodeid>

Note

When executed from the cluster IP address, this command displays the cluster level statistics.
However, when executed from the NSIP address of a cluster node, the command displays node
level statistics.

To view the statistics of a cluster instance by using the configuration utility

1. Log on to the cluster IP address.

2. Navigate to System > Cluster.
3. In the details pane, in the center of the page, click Statistics.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1946

NetScaler 12.0

To view the statistics of a cluster node by using the configuration utility

1. Log on to the cluster IP address.

2. Navigate to System > Cluster > Nodes.
3. In the details pane, select a node and click Statistics to view the statistics of the node. To view
the statistics of all the nodes, click Statistics without selecting a specific node.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Discovering NetScaler appliances

September 18, 2018

Contributed by:
C

You can discover the appliances present in the same subnet as the current node. The required dis-
covered appliances can then be selectively added to the cluster. This operation can be performed to
either create a new cluster or to add nodes to an existing cluster.

Note

• The discover operation can be performed only through the configuration utility.
• This operation cannot discover NetScaler appliances from different networks.
• When performing this operation to add nodes to an existing cluster, the L3 VLAN configu-
rations will be cleared from the node. You must make sure to define these configurations
once the appliance is added to the cluster.

To discover appliances by using the configuration utility

1. Log on to the cluster IP address.

2. Navigate to System > Cluster > Nodes.
3. In the details pane, at the bottom of the page, click Discover NetScalers.
4. In the Discover NetScalers dialog box, set the following parameters:
• IP address range - Specify the range of IP addresses within which you want to discover
appliances. For example, you can search for all NSIP addresses between 10.102.29.4 to
10.102.29.15 by specifying this option as 10.102.29.4 - 15.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1947

NetScaler 12.0

• Backplane interface - Specify the interfaces to be used as the backplane interface. This is
an optional parameter. If you do not specify this parameter, you must update it after the
node is added to the cluster.
5. Click OK.
6. Select the appliances that you want to add to the cluster.
7. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Disabling a cluster node

September 18, 2018

Contributed by:
C

You can temporarily remove a node from a cluster by disabling the cluster instance on that node. A
disabled node is not synchronized with the cluster configurations. When the node is enabled again,
the cluster configurations are automatically synchronized on it. For more information, see Synchro-
nization across cluster nodes.

A disabled node cannot serve traffic and all existing connections on this node are terminated.

Note

If the configurations of a disabled non-configuration coordinator node are modified (through the
NSIP address of the node), the configurations are not automatically synchronized on that node.
You must manually synchronize the configurations as described in
Synchronizing Cluster Configurations.

To disable a cluster node by using the command line interface

At the command prompt of the node that you want to disable, type:

disable cluster instance <clId>

Note

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1948

NetScaler 12.0

To disable the cluster, run the

disable cluster instance command on the cluster IP address.

To disable a cluster node by using the configuration utility

1. On the node that you want to disable, navigate to System > Cluster, and click Manage Cluster.

2. In the Configure cluster instance dialog box, unselect the Enable cluster instance check box.

Note

To disable the cluster instance on all the nodes, perform the above procedure on the cluster
IP address.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Removing a cluster node

September 18, 2018

Contributed by:
C

When a node is removed from the cluster, the cluster configurations are cleared from the node (by
internally executing the clear ns config -extended command). The SNIP addresses, MTU settings of
the backplane interface, and all VLAN configurations (except the default VLAN and NSVLAN) are also
cleared from the appliance.

Note

• If the deleted node was the cluster configuration coordinator, another node is automatically
selected as the cluster configuration coordinator, and the cluster IP address is assigned to
that node. All the current cluster IP address sessions will be invalid and you will have to
start a new session.
• To delete the whole cluster, you must remove each node individually. When you remove
the last node, the cluster IP address(es) are deleted.
• When an active node is removed, the traffic serving capability of the cluster is reduced by
one node. Existing connections on this node are terminated.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1949

NetScaler 12.0

To remove a cluster node by using the command line interface

For NetScaler 10.1 and later versions

Logon to the cluster IP address and at the command prompt, type:

rm cluster node <nodeId>

Note

If the cluster IP address is unreachable from the node, execute the

rm cluster instance command on the NSIP address of that node itself.

For NetScaler 10

1. Log on to the node that you want to remove from the cluster and remove the reference to the
cluster instance.

1 rm cluster instance <clId>

2
3 save ns config

2. Log on to the cluster IP address and remove the node from which you removed the cluster in-
stance.

1 rm cluster node <nodeId>

2
3 save ns config

Make sure you do not run the rm cluster node command from the local node as this results
in inconsistent configurations between the configuration coordinator and the node.

To remove a cluster node by using the configuration utility

On the cluster IP address, navigate to System > Cluster > Nodes, select the node you want to remove
and click Remove.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1950

NetScaler 12.0

Removing a node from a cluster deployed using cluster link aggregation

September 18, 2018

Contributed by:
C

To remove a node from a cluster that uses cluster link aggregation as the traffic distribution mecha-
nism, you must make sure that the node is made passive so that it does not receive any traffic and
then, on the upstream switch, remove the corresponding interface from the channel.

For detailed information on cluster link aggregation, see Using Cluster Link Aggregation.

To remove a node from a cluster that uses cluster link aggregation as the traffic
distribution mechanism

1. Log on to the cluster IP address.

2. Set the state of the cluster node that you want to remove to PASSIVE.

set cluster node <nodeId> -state PASSIVE

3. On the upstream switch, remove the corresponding interface from the channel by using switch-
specific commands.

Note

You do not have to manually remove the nodes interface on the cluster link aggregation
channel. It is automatically removed when the node is deleted in the next step.

4. Remove the node from the cluster.

rm cluster node <nodeId>

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Detecting jumbo probe on a cluster

September 18, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1951

NetScaler 12.0

Contributed by:
C

If a Jumbo frame is enabled on a Cluster interface, the backplane interface should be large enough to
support the all packets in the Jumbo frame. This is achieved by setting the Maximum Transmission
Unit (MTU) of the backplane as:

Backplane_MTU = maximum (all cluster interface MTU’s) + 78

To verify the above configuration, you must send a jumbo probe (of the above computational size)
to all peer nodes of a Cluster setup. If the probe does not succeed, the appliance displays a warning
message in the output of the “show cluster instance” command.

In the command interface mode, type the following command:

1 > show cluster instance

2 Cluster ID: 1
3 Dead Interval: 3 secs
4 Hello Interval: 200 msecs
5 Preemption: DISABLED
6 Propagation: ENABLED
7 Quorum Type: MAJORITY
8 INC State: DISABLED
9 Process Local: DISABLED
10 Cluster Status: ENABLED(admin), ENABLED(operational), UP

Warning

The MTU for a backplane interface must be large enough to handle all packets in the frame. It
must be equal to <MTU_VAL>. If the recommended value is not user configurable, you must re-
view the MTU value of jumbo interfaces.
|Sl. no | Member Nodes |Health |Admin State |Operation State|
|—- |—- |—- |—- |—- |
| 1 | Node ID: 1; Node IP: 10.102.53.167 | UP | Active | ACTIVE (Configuration Coordinator) |
| 2 | Node ID: 2; Node IP: 10.102.53.168 | UP | Active | Active |

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1952

NetScaler 12.0

Route monitoring for dynamic routes in cluster

May 20, 2019

Contributed by:
C

You can use a route monitor to make a Cluster node dependent on the internal routing table whether
it contains or does not contain dynamically learnt route. In a Cluster system, a route monitor on each
node checks the internal routing table to ensure there is a route entry for reaching a particular network
is always present. If the route entry is not present, the state of the route monitor changes to DOWN.

In a cluster deployment, if the client-side or server side-link of a node goes down, traffic is steered to
this node through the peer nodes for processing. The steering of traffic is implemented by configuring
dynamic routing and adding static ARP entries, pointing to the special MAC address of each node, on
all the nodes. If there are a large number of nodes in a cluster deployment, adding and managing
static ARP entries with special MAC addresses on all the nodes is a cumbersome task. Now, nodes
implicitly use special MAC addresses for steering packets. Therefore, static ARP entries pointing to
special MAC addresses are no longer required to be added to the cluster nodes.

To bind a cluster node using the command line interface

At the command prompt, type:

1 bind cluster node <nodeId> (-routeMonitor <ip_addr|ipv6_addr|*> [<

netmask>])
2 unbind cluster node <nodeId> (-routeMonitor <ip_addr|ipv6_addr|*> [<
netmask>])

Consider a scenario where Node 1 is bound to route monitor 1.1.1.0 255.255.255.0. When a dynamic
route fails, Node 1 become INACTIVE. Health status is available in the Show Cluster Node command
by node id as show below.

1 Node ID: 1
2 IP:  10.102.169.96
3 Backplane:  1/1/2
4 Health: NOT UP
5 Reason(s): Route Monitor(s) of the node have failed
6 Route Monitor -  Network: 1.1.1.0   Netmask: 255.255.255.0   State:
DOWN

1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1953

NetScaler 12.0

2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Monitoring cluster setup using SNMP MIB with SNMP link

September 18, 2018

Contributed by:
C

SNMP mib is device specific information that has been configured on the SNMP agent for the purpose
of identifying a NetScaler appliance, such as appliance name, administrator, location. In a cluster
setup, you can now configure the SNMP MIB in any node by including the “ownerNode” parameter in
the set snmp mib command. Without this parameter, the set snmp mib command applies only to the
Cluster Coordinator (CCO) node.

To display the MIB configuration for a cluster node other than the CCO, include the “ownerNode” pa-
rameter in the show snmp mib command

Configuring SNMP MIB on CLIP

To configure and view MIB configuration on CLIP by using the command line interface.

1 set snmp mib [-contact <string>] [-name <string>] [-location <string>]

2       [-customID <string>] [-ownerNode <positive_integer>]
3 Done
4 show snmp mib [-ownerNode <positive_integer>]
5
6  > set mib -contact John -name NS59 -location San Jose -customID 123 -
ownerNode 3
7 Done
8 > sh mib -ownerNode 3
9         --------------------
10          Cluster Node ID: 3
11         --------------------
12         NetScaler system MIB:
13         sysDescr:    NetScaler NS11.1: Build 46.4.a.nc, Date: Jun  7
2016, 10:27:29
14         sysUpTime:   124300
15         sysObjectID: .1.3.6.1.4.1.5951.1.1
16         sysContact:  John

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1954

NetScaler 12.0

17         sysName:     NS59

18         sysLocation: San Jose
19         sysServices: 72
20         Custom ID: 123
21  Done
22
23 > unset mib -contact -name -location -customID -ownerNode 3
24  Done
25 > sh mib -ownerNode 3
26         --------------------
27          Cluster Node ID: 3
28         --------------------
29         NetScaler system MIB:
30         sysDescr:    NetScaler NS11.1: Build 46.4.a.nc, Date: Jun 7
2016, 10:27:29
31         sysUpTime:   146023
32         sysObjectID: .1.3.6.1.4.1.5951.1.1
33         sysContact:  WebMaster (default)
34         sysName:     NetScaler
35         sysLocation: POP (default)
36         sysServices: 72
37         Custom ID: Default
38  Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Monitoring command propagation failures in a cluster deployment

May 20, 2019

Contributed by:
C

In a cluster deployment of NetScaler appliances, you can use the new command “show prop status”
for faster monitoring and troubleshooting of issues related to command-propagation failure on non-
CCO nodes. This command displays up to 20 of the most recent command propagation failures on all
non-CCO nodes. You can use either the NetScaler appliance command line or the NetScaler GUI to
perform this operation after accessing them through the CLIP address or through the NSIP address of
any node in the cluster deployment.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1955

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Graceful shutdown of nodes

September 18, 2018

Contributed by:
C

In a cluster, if a node leaves the system or if a node joins the system, some of the existing connections
(1/Nth connections, where N is the cluster size) at cluster level or specific virtual server level are lost.
To address the loss, you must gracefully handle the existing connections. This is done by configur-
ing “retain connections on cluster” option in the CLIP address and specifying timeout interval in the
node’s NSIP.

Graceful handling of connections is applicable in two scenarios:

1. Cluster upgrade
2. New Node Addition

Graceful handling of Nodes in cluster upgrade

To upgrade a cluster, you must upgrade one node at a time. Before upgrading a node, you must set it
to passive state and then set it to active state after the upgrade. To avoid terminating existing connec-
tions when upgrading the node, shut it down gracefully with a configured timeout interval. Otherwise,
1/Nth (where N is the cluster size) of the cluster’s connections are terminated.
Note

If existing sessions are not completed within the configured timeout interval, they get terminated
after the grace time.

Following are the steps to gracefully handle nodes in a cluster upgrade scenario:

1. Consider a cluster setup of five nodes (n0, n1, n2, n3, n4).

2. Before you shut down a node, you must configure “retainConnectionsOnCluster” option to re-
tain all existing connections of this node at cluster level or virtual server level for specific time
interval.

example

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1956

NetScaler 12.0

On CLIP

set cluster instance <clusterID> ‒retainConnectionsOnCluster YES

OR

set lb vserver <vserver name> ‒retainConnectionsOnCluster Yes

3. Now, log on to the NSIP address of node n3 and set the node n3 to PASSIVE with a timeout
internal.

Example

set cluster node n3 ‒state PASSIVE ‒delay 60

saveconfig

4. After the grace period expires, close all connections, shut down n3 and reboot the NetScaler
appliance.

5. Upgrade the appliance. Then, with the CLI connected to the appliance’s NSIP address, set the
node to ACTIVE.

Example

set cluster node n3 ‒state ACTIVE

saveconfig

6. Repeat steps 4 to 6 for all nodes in the cluster.

7. After all nodes are upgraded and set to ACTIVE, reset the retainConnectionsOnCluster option
from the CLIP address.

Example

set cluster instance <clusterID> -retainConnectionsOnCluster NO

OR

set lb vserver <vserver name> ‒retainConnectionsOnCluster NO

saveconfig

Note

If there is a version mismatch when upgrading a Cluster, cluster propagation is automatically

disabled and no commands are allowed on the CLIP.

Graceful handling of nodes during a new node addition

If you have an appliance that is already serving traffic, and you want to add this appliance as a node
to a cluster without terminating its existing connections, set the option to retain existing connections

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1957

NetScaler 12.0

either at Global level or specific virtual sever level and save the configuration. Now set the option to
retain connections to NO, to allow existing connections from other nodes to be reassigned to the new
node.
Following are the steps to gracefully handle nodes if a node newly added:
1. You must save the existing configuration that has “retainConnectionsOnCluster” option en-
abled to retain all existing connections of this node at cluster level or virtual server level for
specific time interval.
On CLIP
set cluster instance x – retainConnectionsOnCluster YES
OR
set lb vserver xxxx –retainConnectionsOnCluster Yes
2. Add a new node n5 to the cluster setup.
3. Disable “the retainConnectionOnCluster” option to “NO” for distributing existing connections from
other nodes to the newly added node n5.
On CLIP
set cluster instance x – retainConnectionsOnCluster NO
OR
set lb vserver xxxx –retainConnectionsOnCluster NO
Note: The backplane steering depends on the type of traffic distribution mechanism (ECMP, CLAG,
and USIP) on a cluster setup. The increase in backplane steering is based on the traffic type.

Configuring graceful shutdown of nodes in a cluster

To configure graceful shutdown of nodes in a cluster, do the following:

1. Configure “retainConnectionsonCluster” option at Global (Cluster) level.
2. Configure “retainConnectionsonCluster” option at virtual server level.
3. Set the node (leaving the system) to the passive state with a graceful timeout interval specified
in the node’s NSIP address.
4. Monitor the existing connections to make sure all transactions are completed within the grace
period.

To retain existing connections at the global (cluster) level by using the command line

You can retain existing connections either at global level or at a specific virtual server level. This option
is configured to retain all existing connections at global level. By default, this option is disabled.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1958

NetScaler 12.0

At the command prompt type:

1 set cluster instance <clusterID> ‒ retainConnectionsOnCluster YES

2
3 set cluster instance 60 ‒ retainConnectionsOnCluster YES

To retain existing connections of a specific virtual server in the cluster by using the command
line

This option is configured to retain existing connections specific to a load balancing virtual server. To
retain those connections, we enable this option at the virtual server level. By default, this option is
disabled.

At the command prompt, type:

1 set lb vserver <clusterID> ‒ retainConnectionsOnCluster Yes

2
3 set lb vserver v1 ‒ retainConnectionsOnCluster Yes

To set a cluster node to passive state by using the command line

To set a cluster node to passive state with a gracefully timeout interval. This setting is performed in
the node’s NSIP as propagation is disabled during cluster upgrade.

At the command prompt, type:

1 set cluster node <clusterID> -state passive

2 -backplane <interface_name>@
3 -priority <positive_integer>
4 -delay <mins>
5
6 set cluster node 4 ‒ state PASSIVE -delay 60
7
8 set cluster instance 60 ‒ retainConnectionsOnCluster YES
9 set lb vserver v1 ‒ retainConnectionsOnCluster Yes
10 set cluster node 4 ‒ state PASSIVE -delay 60

To configure graceful shutdown of nodes by using the NetScaler GUI

1. Navigate to Configuration > System > Cluster and click Manage Cluster.
2. On the Manage Cluster page, select Retain Connections on Cluster option.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1959

NetScaler 12.0

3. Click OK, and then click Done.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

IPv6 ready logo support for clusters

September 18, 2018

Contributed by:
C

You can test clustered appliances for IPv6 Ready Logo certification. Modified commands for testing
IPv6 core protocols, such as for ND test cases, Router Solicitation processing, and sending route adver-
tisement and router redirection messages are available in a clustered setup. Following are the IPv6
functionalities available for testing the IPv6 core protocols.

Following are the modified functionalities available to pass IPv6 core protocols, such as ND test cases,
Router Solicitation processing and sending Route advertisement and router redirection messaging in
IPv6readylogo phase2 test suite.

• Link Local SNIPs

• Address Resolution and Neighbor Unreachability
• Router and Prefix Discovery
• Router Redirection
• DoDAD

With these modified commands, the following configurations are supported in a clustered appliance.

Supportable configurations for testing IPv6 core protocols

For a clustered setup to pass IPv6 Ready Logo test cases, you can execute the following configurations
on the Cluster Management IP address (CLIP).

• global IP6 configuration

• basic IPv6 configuration
• additional IPv6 configurations

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1960

NetScaler 12.0

Global configuration

A global IPv6 configuration enables you to set the global IPv6 parameters (such as relearning,
routeRedirection, ndBasereachTime, nRetransmissionTime, natprefix, td, and doodad) to run the
basic IPv6 configuration.

At the command prompt, type the following:

1 set ipv6 [-ralearning ( ENABLED | DISABLED )] [-routerRedirection (

ENABLED | DISABLED )] [-ndBasereachTime<positive_integer>][-
ndRetransmissionTime <positive_integer>] [-natprefix <ipv6_addr|*>[-
td<positive_integer>]] [-doDAD ( ENABLED | DISABLED )]

Basic IPv6 configuration

The basic IPv6 configuration enables you to create an IPv6 address and bind to a VLAN interface. You
must perform the following configurations to test the IPv6 core protocols.

To add a VLAN to the clustered setup by using the NetScaler command line

At the command prompt, type:

1  add vlan <id>

To add another VLAN to the clustered set up by using the NetScaler command line

At the command prompt, type:

1  add vlan <id>

To bind an interface to a VLAN by using the NetScaler command line

At the command prompt, type:

1 bind vlan <id> -ifnum <interface_name>

To bind an interface to a VLAN by using the NetScaler command line

This command adds the global prefix as on-link prefix into RA information for subsequent Router Ad-
vertisements. At the command prompt, type:

1 bind vlan <id> -ifnum <interface_name>

To add IPv6 SNIP address on a VLAN by using the NetScaler command line

At the command prompt, type the following:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1961

NetScaler 12.0

1 add ns ip6 <IPv6Address>@ [-scope ( global | link-local )][-type <type>

  

To add IPv6 address on VLAN by using the NetScaler command line

At the command prompt, type the following:

1 add ns ip6 <IPv6Address>@ [-scope ( global | link-local )][-type <type>

  

To bind IPv6 address to VLAN by using the NetScaler command line

At the command prompt, type the following:

1 bind vlan <id> [-ifnum <interface_name> [-tagged]][-IPAddress <ip_addr|

ipv6_addr|  

To bind IPv6 address to VLAN by using the NetScaler command line

At the command prompt, type the following:

1 bind vlan <id> [-ifnum <interface_name> [-tagged]][-IPAddress <ip_addr|

ipv6_addr|  

To display link local IPv6 address attached to VLAN by using the NetScaler command line

At the command prompt, type the following:

1 sh VLAN

Example 1

1 add vlan 2
2 add vlan 3
3 bind vlan 2 -ifnum 1/2
4 bind vlan 3 -ifnum 1/3
5 add ip6 fe80::9404:60ff:fedd:a464/64 -vlan 2 -scope link-local -type
SNIP
6 add ip6 fe80::c0ee:7bff:fede:263f/64 -vlan 3 -scope link-local -type
SNIP
7 add ip6 3ffe:501:ffff:100:9404:60ff:fedd:a464/64 -vlan 2
8 add ip6 3ffe:501:ffff:101:c0ee:7bff:fede:263f/64 -vlan 3
9 bind vlan 2 -ipAddress 3ffe:501:ffff:100:9404:60ff:fedd:a464/64
10 bind vlan 3 -ipAddress 3ffe:501:ffff:101:c0ee:7bff:fede:263f/64

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1962

NetScaler 12.0

Example 2

1 sh vlan
2 1)      VLAN ID: 2      VLAN Alias Name:
3         Interfaces : 1/6
4         IPs :
5              3ffe:501:ffff:100:2e0:edff:fe15:ea2a/64
6 3)      VLAN ID: 3      VLAN Alias Name:
7         Link-local IPv6 addr: fe80::9404:60ff:fedd:a464/64
8         Interfaces : 1/5
9         IPs :
10              3ffe:501:ffff:101:2e0:edff:fe15:ea2b/64
11  Done

Additional IPv6 cluster configuration

To test IPv6 core protocols, you can use the following new or modified IPv6 configurations.

To set VLAN specific Router Advertisement parameters by using the NetScaler command line

At the command prompt, type:

1 set nd6RAvariables -vlan <positive_integer> [-ceaseRouterAdv ( YES | NO

)] [-sendRouterAdv ( YES | NO )] [-srcLinkLayerAddrOption ( YES | NO
)][-onlyUnicastRtAdvResponse ( YES | NO )] [-managedAddrConfig (
YES | NO)] [-otherAddrConfig ( YES | NO )] [-currHopLimit <
positive_integer>][-maxRtAdvInterval <positive_integer>] [-
minRtAdvInterval<positive_integer>] [-linkMTU <positive_integer>] [-
reachableTime<positive_integer>] [-retransTime <positive_integer>]
[-defaultLifeTime<integer>]

To set an on-link global prefix’s configurable parameters by using the NetScaler command line

At the command prompt, type:

1 set onLinkIPv6Prefix <ipv6Prefix> [-onlinkPrefix ( YES | NO )][-

autonomusPrefix ( YES | NO )] [-depricatePrefix ( YES | NO )][-
decrementPrefixLifeTimes ( YES | NO )] [-prefixValideLifeTime   <
positive_integer>] [-prefixPreferredLifeTime <positive_integer>]

To add configurable parameters to an on-link global prefix by using the NetScaler command line

At the command prompt, type:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1963

NetScaler 12.0

1 add onLinkIPv6Prefix <ipv6Prefix> [-onlinkPrefix ( YES | NO )][-

autonomusPrefix ( YES | NO )] [-depricatePrefix ( YES | NO )][-
decrementPrefixLifeTimes ( YES | NO )]-prefixValideLifeTime <
positive_integer>][-prefixPreferredLifeTime <positive_integer>]

To set on-link link IPv6 prefix’s configurable parameters by using the NetScaler command line

At the command prompt, type the following:

1 help set onLinkIPv6Prefix

To bind an on-link link IPv6 prefix’s configurable parameters by using the NetScaler command line

At the command prompt, type:

1 help bind nd6RAvariables

To show nd6RAvariables by using the NetScaler command line

At the command prompt, type:

1 help sh nd6RAvariables

Example

1 > sh nd6RAvariables
2   1) Vlan : 1
3      SendAdvert     : NO   CeaseAdv       : NO        SourceLLAddress:
YES
4      UnicastOnly    : NO   ManagedFlag    : NO        OtherConfigFlag:
NO
5      CurHopLimit    : 64   MaxRtrAdvInterv: 600       MinRtrAdvInterv:
198
6      LinkMTU        : 0    ReachableTime  : 0          RetransTimer   :
0
7      DefaultLifetime: 1800 LastRAsentTime : 0          NextRAdelay    :
0
8
9   2) Vlan : 2
10      SendAdvert     : NO   CeaseAdv       : NO         SourceLLAddress:
YES
11      UnicastOnly    : NO   ManagedFlag    : NO         OtherConfigFlag:
NO
12      CurHopLimit    : 64   MaxRtrAdvInterv: 600        MinRtrAdvInterv:
198

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1964

NetScaler 12.0

13      LinkMTU        : 0    ReachableTime  : 0          RetransTimer   :

0
14      DefaultLifetime: 1800 LastRAsentTime : 0          NextRAdelay    :
0  
15 Done
16 >
17 > sh nd6Ravariables ‒ vlan 2
18   1) Vlan : 2
19      SendAdvert     : NO   CeaseAdv       : NO         SourceLLAddress:
YES
20      UnicastOnly    : NO   ManagedFlag    : NO         OtherConfigFlag:
NO
21      CurHopLimit    : 64   MaxRtrAdvInterv: 600        MinRtrAdvInterv:
198
22      LinkMTU        : 0    ReachableTime  : 0          RetransTimer   :
0
23      DefaultLifetime: 1800 LastRAsentTime : 0          NextRAdelay    :
0
24      Prefix :
25 3ffe:501:ffff:100::/64
26 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Managing cluster heartbeat messages

September 18, 2018

Contributed by:
C

Managing heartbeat messages in a cluster is similar to managing them in a high availability (HA) con-
figuration. Nodes can send and receive heartbeat messages to and from each other on all interfaces
that are enabled. To avoid increased traffic resulting from hearbeat messages, you can now disable
the heartbeat option on node interfaces. However, the heartbeat option on the backplane interface
cannot be disabled, because it is required for maintaining connectivity among the cluster nodes.

For more information about managing heart messages, see Managing High Availability Heartbeat Mes-
sages on a NetScaler Appliance.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1965

NetScaler 12.0

To manage heartbeat messages on a node interface by using the NetScaler CLI

At the command prompt, type:

1 set interface <ID> [-HAHeartBeat (ON | OFF)]

2 Show interface <ID>

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Configuring owner node response status

September 18, 2018

Contributed by:
C

In a cluster setup, on a node has a spotted SNIP address, you can configure the ownerDownResponse
option. By default, the option is enabled, allowing the spotted IP address to respond to PING or ARP
requests (coming from the upstream router) when the node is inactive. If you disable the option, the
IP address cannot respond to the router requests when the owner node is inactive.

To know how this feature is used for monitoring static routes in ECMP deployment, see Using Equal
Cost Multiple Path (ECMP) topic.

To set owner node response status by using the NetScaler CLI

At the command prompt, type:

1 add ns ip <IPAddress> [-ownerNode <positive_integer>] [-

ownerDownResponse (YES | NO )] [-td <positive_integer>]

Example

1 add ns ip 2.2.2.2 255.255.255.0 -ownernode 6 ‒ ownerdownResponse YES

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1966

NetScaler 12.0

To set owner node response status by using the NetScaler GUI

1. Navigate to System > Network > IPs and click Add to create a spotted SNIP address.
2. On the Create IP Address page, select or clear the ownerDownResponse check box.

To edit owner node response status by using the NetScaler GUI

Navigate to System > Network > IPs, select an IP address, and click Edit to select or clear the own-
erDownResponse check box.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Monitor static route (MSR) support for inactive nodes in a spotted

cluster configuration

September 18, 2018

Contributed by:
C

In a cluster set up with MSR option enabled on the route, only active nodes can probe to a static route
and reach a network while inactive and spare nodes have no link to the route and cannot probe to it.
You can now configure an inactive or spare node to send PING and ARP probe to IPv4 route and send
ping6 and nd6 probe to IPv6 route. You can perform this only in a Spotted Cluster configuration in
which the SNIP address is active and owned exclusively only by one node.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

VRRP interface binding in a single node active cluster

September 18, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1967

NetScaler 12.0

Contributed by:
C

When you migrate a high availability (HA) setup to a cluster setup, all configurations must be compat-
ible and must be supportable in the cluster. To achieve this, you can now configure virtual router IDs
(VRIDs and VRID6s) on a node interface.

Important: Currently, only a single-node active cluster system supports VRIDs and VRID6s.

For instructions for configuring VRIDs and VRID6s, see Configuring Virtual MAC Addresses.

To configure a virtual router ID on a single-node active cluster, add the VRID or VRID6 and bind it to
the cluster-node interface.

To add a VRID by using the NetScaler CLI

At the command prompt, type:

1 add vrID <ID>

To bind a VRID to the cluster-node interface by using the NetScaler CLI

At the command prompt, type:

1 Bind vrid <ID> -ifnum <interface_name> | -trackifNum <interface_name

2
3 Add vrID 100
4 Bind vrid 100 ‒ ifnum 1/1  1/2
5 done

To add a VRID6 by using the NetScaler CLI

At the command prompt, type:

1 add vrID6 <ID>

To bind a VRID6 to cluster node interface by using the NetScaler CLI

At the command prompt, type:

1 bind vrid6 <ID> -ifnum <interface_name> | -trackifNum <interface_name>

2
3 Add vrID6 100
4 Bind vrid6 100 ‒ ifnum 1/1  1/2
5 Done

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1968

NetScaler 12.0

4. Clustering

Cluster setup and usage scenarios

September 18, 2018

Contributed by:
C

This section aims at explaining some scenarios in which the NetScaler cluster can be setup and also
how it can be configured for different features and network topologies. These are just some scenarios
that we have documented. Provide feedback if you want some other scenarios to be included.

• Creating a Two-Node Cluster

• Migrating an HA Setup to a Cluster Setup
• Transitioning between a L2 and L3 Cluster [From NetScaler 11 onwards]
• Setting Up GSLB in a Cluster [From NetScaler 10.5 onwards]
• Using Cache Redirection in a Cluster
• Using L2 Mode in a Cluster Setup
• Using Cluster LA Channel with Linksets
• Backplane on LA Channel
• Common Interface for Client and Server and Dedicated Interfaces for Backplane
• Common Switch for Client, Server, and Backplane
• Common Switch for Client and Server and Dedicated Switch for Backplane
• Different Switch for Every Node
• Sample Cluster Configurations

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Creating a two-node cluster

September 18, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1969

NetScaler 12.0

A two-node cluster is an exception to the rule that a cluster is functional only when a minimum of (n/2
+1) nodes, where n is the number of cluster nodes, are able to serve traffic. If that formula were applied
to a two-node cluster, the cluster would fail if one node went down (n/2 +1=2).

A two-node cluster is functional even if only one node is able to serve traffic.

Creating a two node cluster is the same as creating any other cluster. You must add one node as the
configuration coordinator and the other node as the other cluster node.
Note

Incremental configuration synchronization is not supported in a two-node cluster. Only full syn-
chronization is supported.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Migrating an HA setup to a cluster setup

September 18, 2018

Contributed by:
C

Migrating an existing high availability (HA) setup to a cluster setup requires you to first remove the
NetScaler appliances from the HA setup and create a backup of the HA configuration file. You must
then use the two appliances to create a cluster and upload the backed-up configuration file to the
cluster.
Note

• Before uploading the backed-up HA configuration file to the cluster, you must modify it to
make it cluster compatible. Refer to the relevant step of the procedure below.
• Use the batch -f <backup_filename> command to upload the backed-up configuration file.

The above approach is a very basic migration solution which results in downtime for the deployed ap-
plication. As such, it must be used only in deployments where there is no consideration to application
availability.

However, in most deployments, the availability of the application is of paramount importance. For
such cases, you must use the approach where an HA setup can be migrated to a cluster setup without
any resulting downtime. In this approach, an existing HA setup is migrated to a cluster setup by first
removing the secondary appliance and using that appliance to create a single-node cluster. After the

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1970

NetScaler 12.0

cluster becomes operational and serves traffic, the primary appliance of the HA setup is added to the
cluster.

To convert a HA setup to cluster setup (without any downtime) by using the command
line interface

Let us consider the example of a HA setup with primary appliance (NS1) - 10.102.97.131 and secondary
appliance (NS2) - 10.102.97.132.

1. Make sure the configurations of the HA pair are stable.

2. Log on to any one of the HA appliances, go to the shell, and create a copy of the ns.conf file (for
example, ns_backup.conf).

3. Log on to the secondary appliance, NS2, and clear the configurations. This operation removes
NS2 from the HA setup and makes it a standalone appliance.

1 > clear ns config full

Note

• This step is required to make sure that NS2 does not start owning VIP addresses, now
that it is a standalone appliance.
• At this stage, the primary appliance, NS1, is still active and continues to serve traffic.

4. Create a cluster on NS2 (now no longer a secondary appliance) and configure it as a PASSIVE
node.

1 > add cluster instance 1

2
3 > add cluster node 0 10.102.97.132 -state PASSIVE -backplane 0/1/1
4
5 > add ns ip 10.102.97.133 255.255.255.255 -type CLIP
6
7 > enable cluster instance 1
8
9 > save ns config
10
11 > reboot -warm

5. Modify the backed-up configuration file as follows:

• Remove the features that are not supported on a cluster. For the list of unsupported fea-
tures, see NetScaler appliance Features Supported by a Cluster. This is an optional step.
If you do not perform this step, the execution of unsupported commands will fail.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1971

NetScaler 12.0

• Remove the configurations that have interfaces, or update the interface names from the
c/u convention to the n/c/u convention.

Example

1 > add vlan 10 -ifnum 0/1

2
3 should be changed to
4
5 > add vlan 10 -ifnum 0/0/1 1/0/1

• The backup configuration file can have SNIP addresses or MIP addresses. These addresses
are striped on all the cluster nodes. It is recommended that you add spotted IP addresses
for each node.

Example

1 > add ns ip 1.1.1.1 255.255.255.0 -ownerNode 0

2
3 > add ns ip 1.1.1.2 255.255.255.0 -ownerNode 1

• Update the hostname to specify the owner node.

Example

1 > set ns hostname ns0 -ownerNode 0

2
3 > set ns hostname ns1 -ownerNode 1

• Change all other relevant networking configuration that depend on spotted IPs. For ex-
ample, L3 VLAN, RNAT configuration which uses SNIPs as NATIP, INAT rules that refers to
SNIPs/MIPs).

6. On the cluster, do the following:

• Make the topological changes to the cluster by connecting the cluster backplane, the clus-
ter link aggregation channel, and so on.

• Apply configurations from the backed-up and modified configuration file to the configura-
tion coordinator through the cluster IP address.

1 > batch -f ns_backup.conf

• Configure external traffic distribution mechanisms like ECMP or cluster link aggregation.

7. Switch the traffic from the HA setup to the cluster.

• Log on to the primary appliance, NS1, and disable all the interfaces on it.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1972

NetScaler 12.0

1 > disable interface <interface_id>

• Log on to the cluster IP address and configure NS2 as an ACTIVE node.

1 > set cluster node 0 -state ACTIVE

Note

There might be a small amount (in the order of seconds) of downtime between disabling
the interfaces and making the cluster node active.

8. Log on to the primary appliance, NS1, and remove it from the HA setup.
• Clear all the configurations. This operation removes NS1 from the HA setup and makes it
a standalone appliance.

1 > clear ns config full

• Enable all the interfaces.

1 > enable interface <interface_id>

9. Add NS1 to the cluster.

• Log on to the cluster IP address and add NS1 to the cluster.

1 > add cluster node 1 10.102.97.131 -state PASSIVE -backplane

1/1/1

• Log on to NS1 and join it to the cluster by sequentially executing the following commands:

1 > join cluster -clip 10.102.97.133 -password nsroot

2
3 > save ns config
4
5 > reboot -warm

10. Log on to NS1 and perform the required topological and configuration changes.
11. Log on to the cluster IP address and set NS1 as an ACTIVE node.

1 > set cluster node 1 -state ACTIVE

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1973

NetScaler 12.0

Transitioning between a L2 and L3 Cluster

October 9, 2018

Contributed by:
C
Note

Supported from NetScaler 11 onwards.

An L2 cluster is one where all the nodes are from the same network and an L3 cluster is one that can
include nodes from different networks. You can seamlessly transition from one type of cluster to the
other without any downtime for the applications that are deployed on the NetScaler appliance.

Transitioning a cluster from L2 to L3

You can transition to an L3 cluster when you want the cluster to include nodes from other networks.

On the cluster IP address, do the following:

1. Create a nodegroup.

Example

1 > add cluster nodegroup NG0

This nodegroup is used in the next step to group all the nodes from the existing L2 cluster.

2. Transition the L2 cluster to an L3 cluster.

Example

1 > set cluster instance 1 -inc ENABLED -nodegroup NG0

This command achieves the dual purpose of transitioning to L3 cluster and also adding all the
nodes of the L2 cluster to the nodegroup.

3. Now, you can add more nodes to the cluster as explained in “Adding a Node to the Cluster”.

Transitioning a cluster from L3 to L2

You can transition to an L2 cluster when you want to retain nodes that belong to a single network.

On the cluster IP address, do the following:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1974

NetScaler 12.0

1. Remove the cluster nodes from the networks that you do not want to retain.

Example

1 > rm cluster node <nodeId>

2. Transition the L3 cluster to a L2 cluster.

Example

1 > set cluster instance 1 -inc DISABLED

The cluster now includes nodes only of a single network.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Setting up GSLB in a cluster

September 18, 2018

Contributed by:
C
Note

Supported from NetScaler 10.5 Build 52.11 onwards.

To set up GSLB in a cluster you must bind the different GSLB entities to a node group. The node group
must have a single member node.

Note

• The parent-child topology of GSLB is not supported in a cluster.

• If you have configured the static proximity GSLB method, make sure that the static proxim-
ity database is present on all the cluster nodes. This happens by default if the database file
is available at the default location. However, if the database file is maintained in a directory
other than /var/netscaler/locdb/, you must manually synch the file to all the cluster nodes.

To set up GSLB in a cluster by using the command line interface:

Log on to the cluster IP address and perform the following operations at the command prompt:

1. Configure the different GSLB entities. For information, see GSLB Configuration Entities.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1975

NetScaler 12.0

Note

When creating the GSLB site, make sure that you specify the cluster IP address and public
cluster IP address (needed only when the cluster is deployed behind a NAT device). These
parameters are required to ensure the availability of the GSLB auto-sync functionality.

add gslb site <siteName> <siteType> <siteIPAddress> -publicIP <ip_addr>

-clip <ip_addr> <publicCLIP>

2. Create a cluster node group.

add cluster nodegroup <name> [-sticky ( YES | NO )]

Note

Enable the sticky option if you want to set up GSLB based on VPN users.

3. Bind a single cluster node to the node group.

bind cluster nodegroup <name> -node <nodeId>

4. Bind the local GSLB site to the nodegroup.

bind cluster nodegroup <name> -gslbSite <string>

Note

Make sure that the IP address of the local GSLB site IP address is striped (available across
all cluster nodes).

5. Bind the ADNS (or ADNS-TCP) service or the DNS (or DNS-TCP) load balancing virtual server to
the node group.

To bind the ADNS service:

bind cluster nodegroup <name> -service <string>

To bind the DNS load balancing virtual server:

bind cluster nodegroup <name> -vServer <string>

6. Bind the GSLB virtual server to the node group.

bind cluster nodegroup <name> -vServer <string>

7. [Optional] To setup GSLB based on VPN users, bind the VPN virtual server to the GSLB node
group.

bind cluster nodegroup <name> -vServer <string>

8. Verify the configurations.

show gslb runningConfig

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1976

NetScaler 12.0

To set up GSLB in a cluster by using the graphical user interface:

Log on to the cluster IP address and perform the following operations in the Configuration tab:

1. Configure the GSLB entities.

Navigate to Traffic Management > GSLB to perform the required configurations.

2. Create a node group and perform other node group related configurations.

Navigate to System > Cluster > Node Groups to perform the required configurations.

For the detailed configurations to be performed, see the description provided in the CLI procedure
mentioned above.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Using cache redirection in a cluster

September 18, 2018

Contributed by:
C

Cache redirection in a cluster works in the same way as it does on a standalone NetScaler appliance.
The only difference is that the configurations are done on the cluster IP address. For more information
on cache redirection, see “Cache Redirection.”

Points to remember when using cache redirection in transparent mode on a cluster:

• Before configuring cache redirection, make sure that you have connected all nodes to the exter-
nal switch and that you have linksets configured. Otherwise, client requests will be dropped.

• When MAC mode is enabled on a load balancing virtual server, make sure MBF mode is enabled
on the cluster by using the enable ns mode MBF command. Otherwise, the requests are sent to
origin server directly instead of being sent to the cache server.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1977

NetScaler 12.0

Using L2 mode in a cluster setup

September 18, 2018

Contributed by:
C
Note

Supported from NetScaler 10.5 and later releases.

To use L2 mode in a cluster setup, you must make sure of the following:

• Spotted IP addresses must be available on all the nodes as required.

• Linksets must be used to communicate with the external network.
• Asymmetric topologies or asymmetric cluster LA groups are not supported.
• Cluster LA group is recommended.
• Traffic is distributed between the cluster nodes only for deployments where services exist.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Using cluster LA channel with linksets

January 6, 2019

Contributed by:
C

In an asymmetric cluster topology, some cluster nodes are not connected to the upstream network.
In such a case, you must use linksets. To optimize the performance, you can bind the interfaces that
are connected to the switch as a cluster LA channel and then bind the channel to a linkset.

To understand how a combination of cluster LA channel and linksets can be used, consider a three-
node cluster for which the upstream switch has only two ports available. You can connect two of the
cluster nodes to the switch and leave the other node unconnected.
Note

Similarly, you can also use a combination of ECMP and linksets in an asymmetric topology.

Figure 1. Linksets and cluster LA channel topology

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1978

NetScaler 12.0

To configure cluster LA channel and linksets by using the NetScaler appliance

command line

1. Log on to the cluster IP address.

2. Bind the connected interfaces to a cluster LA channel.

1 add channel CLA/1 ‒ ifnum 0/1/2 1/1/2

3. Bind the cluster LA channel to the linkset.

1 add linkset LS/1 -ifnum CLA/1

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Backplane on LA channel

January 6, 2019
Contributed by:
C
In this deployment, LA channels are used for the cluster backplane.
• NS0 - nodeId: 0, NSIP: 10.102.29.60
• NS1 - nodeId: 1, NSIP: 10.102.29.70
• NS2 - nodeId: 2, NSIP: 10.102.29.80

To deploy a cluster with the backplane interfaces as LA channels

1. Create a cluster of nodes NS0, NS1, and NS2.

a) Log on to the first node that you want to add to the cluster and do the following:

1 create cluster instance 1

2 add cluster node 0 10.102.29.60 -state ACTIVE
3 enable cluster instance 1
4 add ns ip 10.102.29.61 255.255.255.255 -type CLIP
5 save ns config
6 reboot -warm

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1979

NetScaler 12.0

b) Log on to the cluster IP address and do the following:

1 add cluster node 1 10.102.29.70 -state ACTIVE

2 add cluster node 2 10.102.29.80 -state ACTIVE

c) Log on to the nodes 10.102.29.70 and 10.102.29.80 to join the nodes to the cluster.

1 join cluster -clip 10.102.29.61 -password nsroot

2 save ns config
3 reboot -warm

As seen in the above commands the interfaces 0/1/1, 1/1/1, and 2/1/1 are configured as the back-
plane interfaces of the three cluster nodes.

2. Log on to the cluster IP address and do the following:

a) Create the LA channels for nodes NS0 and NS1.

1 add channel 0/LA/1 -ifnum 0/1/1 0/1/2

2 add channel 1/LA/2 -ifnum 1/1/1 1/1/2

b) Configure the backplane for the cluster nodes.

1 set cluster node 0 -backplane 0/LA/1

2 set cluster node 1 -backplane 1/LA/2
3 set cluster node 2 -backplane 2/1/1

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Common interfaces for client and server and dedicated interfaces for
backplane

January 6, 2019

Contributed by:
C

This is a one-arm deployment of the NetScaler cluster. In this deployment, the client and server net-
works use the same interfaces to communicate with the cluster. The cluster backplane uses dedicated
interfaces for inter-node communication.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1980

NetScaler 12.0

• NS0 - nodeId: 0, NSIP: 10.102.29.60

• NS1 - nodeId: 1, NSIP: 10.102.29.70

• NS2 - nodeId: 2, NSIP: 10.102.29.80

To deploy a cluster with a common interface for the client and server and a different inter-
face for the cluster backplane

1. Create a cluster of nodes NS0, NS1, and NS2.

2. Log on to the first node that you want to add to the cluster and do the following:

1 create cluster instance 1

2 add cluster node 0 10.102.29.60 -state ACTIVE -backplane 0/1/1
3 enable cluster instance 1
4 add ns ip 10.102.29.61 255.255.255.255 -type CLIP
5 save ns config
6 reboot -warm

3. Log on to the cluster IP address and do the following:

1 add cluster node 1 10.102.29.70 -state ACTIVE -backplane 1/1/1

2 add cluster node 2 10.102.29.80 -state ACTIVE -backplane 2/1/1

4. Log on to the nodes 10.102.29.70 and 10.102.29.80 to join the nodes to the cluster.

1 join cluster -clip 10.102.29.61 -password nsroot

2 save ns config
3 reboot -warm

As seen in the above commands the interfaces 0/1/1, 1/1/1, and 2/1/1 are configured as the back-
plane interfaces of the three cluster nodes.

1. On the cluster IP address, create VLANs for the backplane interfaces and for the client and server
interfaces.

1 //For the backplane interfaces

2 add vlan 10
3 bind vlan 10 0/1/1 1/1/1 2/1/1
4
5 //For the interfaces that are connected to the client and server
networks.
6 add vlan 20
7 bind vlan 20 0/1/2 1/1/2 2/1/2

2. On the switch, create VLANs for the interfaces corresponding to the backplane interfaces and the
client and server interfaces. The following sample configurations are provided for the Cisco®

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1981

NetScaler 12.0

Nexus 7000 C7010 Release 5.2(1) switch. Similar configurations must be performed on other
switches.

1 //For the backplane interfaces. Repeat for each interface...

2 interface Ethernet2/47
3 switchport access vlan 100
4 switchport mode access
5 end
6
7 //For the interfaces connected to the client and server networks.
Repeat for each interface...
8 interface Ethernet2/47
9 switchport access vlan 200
10 switchport mode access
11 end

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Common switch for client, server, and backplane

January 6, 2019

Contributed by:
C

In this deployment, the client, server, and backplane use dedicated interfaces on the same switch to
communicate with the NetScaler cluster.

• NS0 - nodeId: 0, NSIP: 10.102.29.60

• NS1 - nodeId: 1, NSIP: 10.102.29.70

• NS2 - nodeId: 2, NSIP: 10.102.29.80

To deploy a cluster with a common switch for the client, server, and backplane

1. Create a cluster of nodes NS0, NS1, and NS2.

2. Log on to the first node that you want to add to the cluster and do the following:

1 create cluster instance 1

2 add cluster node 0 10.102.29.60 -state ACTIVE -backplane 0/1/1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1982

NetScaler 12.0

3 enable cluster instance 1

4 add ns ip 10.102.29.61 255.255.255.255 -type CLIP
5 save ns config
6 reboot -warm

3. Log on to the cluster IP address and do the following:

1 add cluster node 1 10.102.29.70 -state ACTIVE -backplane 1/1/1

2 add cluster node 2 10.102.29.80 -state ACTIVE -backplane 2/1/1

4. Log on to the nodes 10.102.29.70 and 10.102.29.80 to join the nodes to the cluster.

1 join cluster -clip 10.102.29.61 -password nsroot

2 save ns config
3 reboot -warm

As seen in the above commands the interfaces 0/1/1, 1/1/1, and 2/1/1 are configured as the back-
plane interfaces of the three cluster nodes.

1. On the cluster IP address, create VLANs for the backplane, client, and server interfaces.

1 //For the backplane interfaces

2 add vlan 10
3 bind vlan 10 0/1/1 1/1/1 2/1/1
4
5 //For the client-side interfaces
6 add vlan 20
7 bind vlan 20 0/1/2 1/1/2 2/1/2
8
9 //For the server-side interfaces
10 add vlan 30
11 bind vlan 30 0/1/3 1/1/3 2/1/3

2. On the switch, create VLANs for the interfaces corresponding to the backplane interfaces and the
client and server interfaces. The following sample configurations are provided for the Cisco®
Nexus 7000 C7010 Release 5.2(1) switch. Similar configurations must be performed on other
switches.

1 //For the backplane interfaces. Repeat for each interface...

2 interface Ethernet2/47
3 switchport access vlan 100
4 switchport mode access
5 end
6
7 //For the client interfaces. Repeat for each interface...

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1983

NetScaler 12.0

8 interface Ethernet2/48
9 switchport access vlan 200
10 switchport mode access
11 end
12
13 //For the server interfaces. Repeat for each interface...
14 interface Ethernet2/49
15 switchport access vlan 300
16 switchport mode access
17 end

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Common switch for client and server and dedicated switch for
backplane

January 6, 2019

Contributed by:
C

In this deployment, the clients and servers use different interfaces on the same switch to communi-
cate with the NetScaler cluster. The cluster backplane uses a dedicated switch for inter-node commu-
nication.

• NS0 - nodeId: 0, NSIP: 10.102.29.60

• NS1 - nodeId: 1, NSIP: 10.102.29.70

• NS2 - nodeId: 2, NSIP: 10.102.29.80

To deploy a cluster with the same switch for the clients and servers and a different switch
for the cluster backplane

1. Create a cluster of nodes NS0, NS1, and NS2.

• Log on to the first node that you want to add to the cluster and do the following:

1 create cluster instance 1

2 add cluster node 0 10.102.29.60 -state ACTIVE -backplane
0/1/1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1984

NetScaler 12.0

3 enable cluster instance 1

4 add ns ip 10.102.29.61 255.255.255.255 -type CLIP
5 save ns config
6 reboot -warm

• Log on to the cluster IP address and do the following:

1 add cluster node 1 10.102.29.70 -state ACTIVE -backplane

1/1/1
2 add cluster node 2 10.102.29.80 -state ACTIVE -backplane
2/1/1

• Log on to the nodes 10.102.29.70 and 10.102.29.80 to join the nodes to the cluster.

1 join cluster -clip 10.102.29.61 -password nsroot

2 save ns config
3 reboot -warm

As seen in the above commands the interfaces 0/1/1, 1/1/1, and 2/1/1 are configured as the back-
plane interfaces of the three cluster nodes.

2. On the cluster IP address, create VLANs for the backplane, client, and server interfaces.

1 //For the backplane interfaces

2 add vlan 10
3 bind vlan 10 0/1/1 1/1/1 2/1/1
4
5 //For the client-side interfaces
6 add vlan 20
7 bind vlan 20 0/1/2 1/1/2 2/1/2
8
9 //For the server-side interfaces
10 add vlan 30
11 bind vlan 30 0/1/3 1/1/3 2/1/3

3. On the switch, create VLANs for the interfaces corresponding to the backplane interfaces and the
client and server interfaces. The following sample configurations are provided for the Cisco®
Nexus 7000 C7010 Release 5.2(1) switch. Similar configurations must be performed on other
switches.

1 //For the backplane interfaces. Repeat for each interface...

2 interface Ethernet2/47
3 switchport access vlan 100
4 switchport mode access
5 end

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1985

NetScaler 12.0

6
7 //For the client interfaces. Repeat for each interface...
8 interface Ethernet2/48
9 switchport access vlan 200
10 switchport mode access
11 end
12
13 //For the server interfaces. Repeat for each interface...
14 interface Ethernet2/49
15 switchport access vlan 300
16 switchport mode access
17 end

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Different switch for every node

January 6, 2019

Contributed by:
C

In this deployment, each cluster node is connected to a different switch and trunk links are configured
between the switches.

The cluster configurations will be the same as the other deployments scenarios. Most of the client-side
configurations will be done on the client-side switches.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Sample cluster configurations

September 18, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1986

NetScaler 12.0

Contributed by:
C

The following example can be used to configure a four-node cluster with ECMP
, cluster LA, or Linksets.

1. Create the cluster.

• Log on to first node.

• Add the cluster instance.

1 add cluster instance 1

• Add the first node to the cluster.

1 add cluster node 0 10.102.33.184 -backplane 0/1/1

• Enable the cluster instance.

1 enable cluster instance 1

• Add the cluster IP address.

1 add ns ip 10.102.33.185 255.255.255.255 -type CLIP

• Save the configurations.

1 save ns config

• Warm reboot the appliance.

1 reboot -warm

2. Add the other three nodes to the cluster.

• Log on to cluster IP address.

• Add the second node to the cluster.

1 add cluster node 1 10.102.33.187 -backplane 1/1/1

• Add the third node to the cluster.

1 add cluster node 2 10.102.33.188 -backplane 2/1/1

• Add the fourth node to the cluster.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1987

NetScaler 12.0

1 add cluster node 3 10.102.33.189 -backplane 3/1/1

3. Join the added nodes to the cluster. This step is not applicable for the first node.

• Log on to each newly added node.

• Join the node to the cluster.

1 join cluster -clip 10.102.33.185 -password nsroot

• Save the configuration.

1 save ns config

• Warm reboot the appliance.

1 reboot -warm

4. Configure the NetScaler cluster through the cluster IP address.

1 // Enable load balancing feature

2 enable ns feature lb
3
4 // Add a load balancing virtual server
5 add lb vserver first_lbvserver http
6 ....
7 ....

5. Configure any one of the following (ECMP, cluster LA, or Linkset) traffic distribution mechanisms
for the cluster.

ECMP

• Log on to the cluster IP address.

• Enable the OSPF routing protocol.

1 enable ns feature ospf

• Add a VLAN.

1 add vlan 97

• Bind the interfaces of the cluster nodes to the VLAN.

1 bind vlan 97 -ifnum 0/1/4 1/1/4 2/1/4 3/1/4

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1988

NetScaler 12.0

• Add a spotted SNIP on each node and enable dynamic routing on it.

1 add ns ip 1.1.1.10 255.255.255.0 -ownerNode 0 -

dynamicRouting ENABLED
2 add ns ip 1.1.1.11 255.255.255.0 -ownerNode 1 -
dynamicRouting ENABLED
3 add ns ip 1.1.1.12 255.255.255.0 -ownerNode 2 -
dynamicRouting ENABLED
4 add ns ip 1.1.1.13 255.255.255.0 -ownerNode 3 -
dynamicRouting ENABLED

• Bind one of the SNIP addresses to the VLAN.

1 bind vlan 97 -ipAddress 1.1.1.10 255.255.255.0

• Configure the routing protocol on ZebOS by using vtysh shell.

Static cluster LA

– Log on to the cluster IP address.

– Add a cluster LA channel.

1 add channel CLA/1 -speed 1000

– Bind the interfaces to the cluster LA channel.

1 bind channel CLA/1 0/1/5 1/1/5 2/1/5 3/1/5

– Perform equivalent configuration on the switch.

Dynamic cluster LA

* Log on to the cluster IP address.

* Add the interfaces to the cluster LA channel.

1 set interface 0/1/5 -lacpmode active -lacpkey 5 -lagtype

cluster
2 set interface 1/1/5 -lacpmode active -lacpkey 5 -lagtype
cluster
3 set interface 2/1/5 -lacpmode active -lacpkey 5 -lagtype
cluster
4 set interface 3/1/5 -lacpmode active -lacpkey 5 -lagtype
cluster

* Perform equivalent configuration on the switch.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1989

NetScaler 12.0

Linksets. Assume that the node with nodeId 3 is not connected to the switch. You
must configure a linkset so that the unconnected node can use the other node inter-
faces to communicate with the switch.

a) Log on to the cluster IP address.

b) Add a linkset.

1 add linkset LS/1

c) Bind the connected interfaces to the linkset.

1 bind linkset LS/1 -ifnum 0/1/6 1/1/6 2/1/6

6. Update the state of the cluster nodes to ACTIVE.

1 set cluster node 0 -state ACTIVE

2 set cluster node 1 -state ACTIVE
3 set cluster node 2 -state ACTIVE
4 set cluster node 3 -state ACTIVE

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Using VRRP in a cluster setup

September 18, 2018

Contributed by:
C

Virtual Router Redundancy Protocol (VRRP) is supported in a cluster setup for both IPv4 and IPv6. The
two VRRP features supported in a cluster setup are Interface based VRRP and IP based VRRP.

Interface based VRRP

The Interface based VRRP feature is applicable only to a two-node cluster with one node active state
and the other serving as a spare.

In this feature, the same VMAC address is configured on both the nodes of the cluster. This VMAC
address is used in GARP advertisements and ARP responses for the IP addresses configured on a node.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1990

NetScaler 12.0

This feature is useful in an active-spare two-node cluster setup that has external devices/routers that
do not accept GARP advertisements.

With the same VMAC address on both cluster nodes, when the active node goes down and the spare
node takes over as active, the MAC address for the IP addresses on the new active node remain un-
changed and the ARP tables on the external devices/routers do not need to be updated.

Configuring Interface based VRRP for IPv4

Perform the following tasks on a cluster setup to configure interface based VRRP for IPv4:

• Add a VRID. A VRID is an integer used by the Cluster setup to form a VMAC address.
• Bind the VRID to node interfaces. Bind the interfaces to the created VRID. The bound interfaces
(in the current active node) use the VMAC address in GARP advertisements and ARP responses
for its IPv4 addresses. You must associate the VRID to the interfaces of both nodes of the active-
spare cluster setup. This is because unlike in a high availability setup, interface IDs differ in a
cluster setup.

To add a VRID by using NetScaler appliance Command line

1 - add vrid <ID>
2 - show vrid <ID>

To bind the VRID to an interface by using the NetScaler appliance Command line

At the command prompt, type:

1 - bind vrid <ID> -ifnum <interface_name>
2 - show vrid <ID>

To add a VRID and bind it to interfaces by using the NetScaler GUI

1. Navigate to System > Network > VMAC and, on the VMAC tab, click Add.

2. On the Create VMAC page, specify a value in the Virtual Router ID* field, bind interfaces in the
Associate Interfaces section, and then click Create.

“‘

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1991

NetScaler 12.0

add vrid 300

Done
bind vrid 300 -ifnum 1/1/2 2/1/3
Done

Configuring interface based VRRP for IPv6

Perform the following tasks on a cluster setup to configure interface based VRRP for IPv6:

• Add a VRID6. A VRID6 is an integer used by the Cluster setup to form a VMAC6 address. The
generic VMAC6 address is in the form of 00:00:5e:00:01:<VRID6>.
• Bind the VRID6 to node interfaces. Bind the interfaces to the created VRID6. The bound in-
terfaces (in the current active node) use the VMAC6 address in GARP advertisements and ARP
responses for its IPv6 addresses. You must associate the VRID6 to the interfaces of both nodes
of the active-spare cluster setup. This is because unlike in a high availability setup, interface
IDs differ in a cluster setup.

To add a VRID6 by using NetScaler appliance Command line

1 - add vrid6 <ID>
2 - show vrid6 <ID>

To bind the VRID6 to an interface by using the NetScaler appliance Command line

At the command prompt, type:

• bind vrid6 <ID> -ifnum <interface_name>
• show vrid6 <ID>

To add a VRID6 and bind it to interfaces by using the NetScaler GUI

1. Navigate System > Network > VMAC and, on the VMAC6 tab, click Add.

2. On the Create VMAC6 page, specify a value in the Virtual Router ID* field, bind interfaces in the
Associate Interfaces section, and then click Create.

1 > add vrid6 100

2 Done
3 > bind vrid6 100 -ifnum 0/1/1 1/1/2 2/1/3
4 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1992

NetScaler 12.0

IP based VRRP

In IP based VRRP, striped VIP addresses bound to the same VRID are configured on all nodes of a cluster
setup. These VIP addresses are active on all the nodes

One of the cluster nodes acts as the VRID owner and sends out the VRRP advertisement to other nodes.
In case of failure of the VRID owner node, another node in the cluster assumes the ownership of the
VRID and starts sending VRRP advertisements. You can also assign a specific cluster node as the owner
of the VRID.

Configuring IP based VRRP for IPv4

Perform the following tasks on a cluster setup for configuring IP based VRRP for IPv4:

• Add a VRID. A VRID is an integer used by the Cluster setup to form a VMAC address. The
generic VMAC address is in the form of 00:00:5e:00:02:<VRID>.
• (Optional) Assign a node as the owner of the VMAC address. You can set the owner node
parameter (while adding or modifying VRID6) to the ID of the cluster node to assign it as the
owner of the VMAC address. If the assigned owner node fails, one of the UP cluster nodes is
dynamically elected as the owner of the VMAC address.
• Bind the VRID to the VIP address of the nodes. Bind the created VRID to the striped VIP ad-
dress.

To add a VRID by using the NetScaler appliance Command line

1 - add vrid <ID> [-ownerNode <positive_integer>]

2 - show vrid <ID>

To bind the VRID to VIP address by using the NetScaler appliance Command line

• set ns ip <IPv4Address> -vrid <ID>

• show vrid <ID>

To add a VRID by using the NetScaler GUI

1. Navigate to System > Network > VMAC and, on the VMAC tab, click Add.
2. On the Create VMAC page, specify a value in the Virtual Router ID field and then click Create.

To bind the VRID to a VIP address by using the NetScaler GUI

1. Navigate to System > Network > IPs, on the IPV4s tab, select a VIP address and click Edit.

2. Set the Virtual Router ID parameter while editing the VIP configuration.

1 > add vrid 90

2 Done
3 > set ns ip 192.0.2.90 ‒ vrid 90

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1993

NetScaler 12.0

4 Done

Configuring IP based VRRP for IPv6

Perform the following tasks on a cluster setup for configuring IP based VRRP for IPv6:

• Add a VRID6. A VRID6 is an integer used by the Cluster setup to form a VMAC6 address. The
generic VMAC6 address is in the form of 00:00:5e:00:02:<VRID6>.
• (Optional) Assign a node as the owner of the VMAC6 address. You can set the owner node
parameter (while adding or modifying VRID6) to the ID of the cluster node to assign it as the
owner of the VMAC6 address. If the assigned owner node fails, one of the UP cluster nodes is
dynamically elected as the owner of the VMAC6 address.
• Bind the VRID6 to the VIP6 address of the nodes. Bind the created VRID6 to the striped VIP6
address.

To add a VRID6 by using the NetScaler appliance Command line

• add vrid6 <ID> [-ownerNode <positive_integer>]

• show vrid6 <ID>

To bind the VRID6 to VIP6 address by using the NetScaler appliance Command line

• set ns ip6 <IPv6Address> -vrid6 <ID>

• show vrid6 <ID>

To add a VRID6 by using the NetScaler GUI

1. Navigate to System > Network > VMAC and, on the VMAC6 tab, click Add.
2. On the Create VMAC6 page, specify a value in the Virtual Router ID field and then click Create.

To bind the VRID6 to a VIP6 address by using the NetScaler GUI

1. Navigate to System > Network > IPs, on the IPV6s tab, select a VIP address and click Edit.

2. Set the Virtual Router ID parameter while editing the VIP6 configuration.

1 > add vrid6 90

2 Done
3 > set ns ip6 2001:db8::5001 ‒ vrid6 90
4 Done

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1994

NetScaler 12.0

Upgrading or downgrading the NetScaler cluster

September 18, 2018

Contributed by:
C

All the nodes of a NetScaler cluster must be running the same software version. Therefore, to upgrade
or downgrade the cluster, you must upgrade or downgrade each NetScaler appliance of the cluster,
one node at a time.

A node that is being upgraded or downgraded is not removed from the cluster. The node continues
to be a part of the cluster and serves traffic uninterrupted, except for the down-time when the node
reboots after it is upgraded or downgraded.

However, due to software version mismatch among the cluster nodes, configuration propagation is
disabled on the cluster and is enabled only after all the cluster nodes are of the same version. Since
configuration propagation is disabled during upgrading on downgrading a cluster, you cannot per-
form any configurations through the cluster IP address during this time.

Important

• Configurations can be lost on downgrading the cluster.

• When you are upgrading a cluster to NetScaler 11.0 build 64.x from an earlier NetScaler 11.0
build, cluster configuration propagation is disabled. This exception arises because the clus-
ter version in build 64.x is different from the one in previous NetScaler 11.0 builds.

Traditionally, this issue occurred only during an upgrade of a cluster to a different NetScaler ver-
sion (for example, from 10.5 to 11.0). It must be noted that normally the cluster version matches
the NetScaler version.

Note

Configuration propagation remains disabled until all the cluster nodes are upgraded to Build
64.x.

Points to note before upgrading or downgrading the cluster

• You cannot add cluster nodes while upgrading or downgrading the cluster software version.

• You can perform node-level configurations through the NSIP address of individual nodes, but
make sure to perform the same configurations on all the nodes to maintain them in synch.

• You cannot execute the “start nstrace” command from the cluster IP address when the cluster

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1995

NetScaler 12.0

is being upgraded. However, you can get the trace of individual nodes by performing this oper-
ation on individual cluster nodes through their NSIP address.

• Owing to changes in cluster licensing that were made in NetScaler 10.5 Build 52.11 see Prerequi-
sites for cluster nodes, look into the following:

– If the cluster is setup in a build prior to NetScaler 10.5 Build 52.11, the cluster will work with
the separate cluster license file. No changes are required.

– If the cluster is setup in NetScaler 10.5 Build 52.11 or later releases and then downgraded to
a build prior to NetScaler 10.5 Build 52.11, the downgraded cluster will not work as it now
expects a separate cluster license file.

• While upgrading from any NetScaler 10.1 build to a later release, syncookie must be disabled
on all TCP profiles (using the “set ns tcpProfile <name> -synCookie DISABLED” command) and
after that a striped SNIP must be added on the CLIP subnet. Once upgraded, syncookie can be
enabled again.

• While upgrading the NetScaler appliance from a NetScaler 10.1 build to a NetScaler 10.5 build,
do not execute the “show audit messages” command as this can cause the NetScaler appliance
to become unresponsive.

• NetScaler 10.5 54.x and 55.x builds are not suitable for cluster deployment. This is because, for
services that need probing, SYN packets are processed locally (on the flow receiver) even though
syncookie is disabled.

• When a cluster is being upgraded, it is possible that the upgraded nodes have some additional
features activated that are not available on the nodes that are not upgraded. This results in a
license mismatch warning while the cluster is being upgraded. This warning will be automati-
cally resolved when all the cluster nodes are upgraded.

Important

• Citrix recommends that you wait for the previous node to become active before upgrading
or downgrading the next node.

• Citrix recommends that the cluster configuration node must be upgraded/downgraded last
to avoid multiple disconnect of cluster IP sessions.

To upgrade or downgrade the software of the cluster nodes

1. Make sure the cluster is stable and the configurations are synchronized on all the nodes.

2. Access each node through its NSIP address and perform the following:

• Upgrade or downgrade the cluster node. For detailed information about upgrading and

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1996

NetScaler 12.0

downgrading the software of an appliance, see Upgrade and downgrade a NetScaler ap-
pliance.

• Save the configurations.

• Reboot the appliance.

3. Repeat step 2 for each of the other cluster nodes.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Operations supported on individual cluster nodes

September 18, 2018

Contributed by:
C

As a rule, NetScaler appliances that are a part of a cluster cannot be individually configured from their
NSIP address. However, there are some operations that are an exception to this rule. These opera-
tions, when executed from the NSIP address, are not propagated to other cluster nodes.

The operations are:

cluster instance (set rm enable disable)

cluster node (set rm)

nstrace (start show stop)

interface (set enable disable)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1997

NetScaler 12.0

route (add rm set unset)

arp (add rm send -all)

• force cluster sync

• sync cluster files

• disable ntp sync

• save ns config

• reboot

• shutdown

For example, when you execute the command disable interface 1/1/1 from the NSIP address of a cluster
node, the interface is disabled only on that node. Since the command is not propagated, the interface
1/1/1 remains enabled on all the other cluster nodes.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Support for heterogeneous cluster

September 21, 2018

Contributed by:
C

NetScaler appliance now supports heterogeneous cluster in a cluster deployment. A heterogeneous

cluster spans nodes of different NetScaler hardware and you can have a combination of different plat-
forms in the same cluster.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1998

NetScaler 12.0

Important

The formation or supportability of a heterogeneous cluster is possible and limited only to MPX
hardware platforms.

The supportability and formation of the heterogeneous cluster depend on certain NetScaler models.
The following table lists the platforms that are supported in the formation of a heterogeneous cluster.

Supported MPX Hardware

Platforms to form
Number of Packet Engines MPX Hardware Platforms Heterogeneous Cluster

5 MPX 11500 MPX 14020

7 MPX 11515 MPX 14040
9 MPX 11530 MPX 14060

Note

If you run the “join cluster” command from the node that has an unequal number of packet en-
gines, the following error message appears: “Mismatch in the number of active PPEs between
CCO and local node”.

Limitations of using heterogeneous cluster

1. The number of packet engines present on all of the MPX hardware appliances should be same
in the cluster deployment.
2. The extra management CPU setting should be same on all the cluster nodes.
3. The newly added node should have the same capacity on the data planes and backplane, as
that of existing cluster nodes.
4. If there are mixed platform devices supporting different ciphers, then the cluster would agree
upon a common cipher list.
1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

FAQs

November 6, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 1999

NetScaler 12.0

Contributed by:
C

A list of the frequently asked questions about clustering (NetScaler 11.0, 10.5, 10.1). Click a question to
view its answer.

How many NetScaler appliances can be included in a single NetScaler cluster?

A NetScaler cluster can include one appliance or as many as 32 NetScaler appliance nCore hardware or
virtual appliances. Each of these nodes must satisfy the criteria specified in Prerequisites for Cluster
Nodes.

Can a NetScaler appliance be a part of multiple clusters?

No. A NetScaler appliance can belong to can belong to one cluster only.

What is a cluster IP address? What is its subnet mask?

The cluster IP address is the management address of a NetScaler cluster. All cluster configurations
must be performed by accessing the cluster through this address. The subnet mask of the cluster IP
address is fixed at 255.255.255.255.

How can I make a specific cluster node as the cluster configuration coordinator?

To manually set a specific node as the cluster configuration coordinator, you must set the priority of
that node to the lowest numeric value (highest priority). To understand, let us consider a cluster with
three nodes that have the following priorities:

n1 - 29, n2 - 30, n3 - 31

Here, n1 is the configuration coordinator. If you want to make n2 the configuration coordinator, you
must set its priority to a value that is lower than n1, for example, 28. On saving the configuration, n2
becomes the configuration coordinator.

Note

n2 with its original priority value of 30 will also become the configuration coordinator when
n1 goes down, as the node with the next lowest priority value is selected in the event that the
configuration coordinator goes down.

Why are the network interfaces of a cluster represented in 3-tuple (n/u/c) notation instead of the
regular 2-tuple (u/c) notation?

When a NetScaler appliance is part of a cluster, you must be able to identify the node to which the
interface belongs. Therefore, the network interface naming convention for cluster nodes is modified
from u/c to n/u/c, where n denotes the node Id.

How can I set the hostname for a cluster node?

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2000

NetScaler 12.0

The hostname of a cluster node must be specified by executing the set ns hostname command
through the cluster IP address. For example, to set the hostname of the cluster node with ID 2, the
command is:

set ns hostname hostName1 -ownerNode 2

Can I automatically detect NetScaler appliances so that I can add them to a cluster?

Yes. The configuration utility allows you to discover appliances that are present in the same subnet as
the NSIP address of the configuration coordinator. For more information, see Discovering NetScaler
Appliances.

Is the traffic serving capability of a cluster affected if a node is removed or disabled or reboot or
shutdown or made inactive?

Yes. When any of these operations are performed on an active node of the cluster, the cluster will have
one less node to serve traffic. Also, existing connections on this node are terminated.

I have multiple standalone appliances, each of which has different configurations. Can I add
them to a single cluster?

Yes. You can add appliances that have different configurations to a single cluster. However, when the
appliance is added to the cluster, the existing configurations are cleared. To use the configurations
that are available on each of the individual appliances, you must:

1. Create a single *.conf file for all the configurations.

2. Edit the configuration file to remove features that are not supported in a cluster environment.
3. Update the naming convention of interfaces from 2-tuple (u/c) format to 3-tuple (n/u/c) format.
4. Apply the configurations to the configuration coordinator node of the cluster by using the batch-
command.

Can I migrate the configurations of a standalone NetScaler appliance or an HA setup to the clus-
tered setup?

No. When a node is added to a clustered setup, its configurations are implicitly cleared by using
the clear ns config command (with the extended option). In addition, the SNIP addresses and all
VLAN configurations (except default VLAN and NSVLAN) are cleared. Therefore, it is recommended
that you back up the configurations before adding the appliance to a cluster. Before using the backed-
up configuration file for the cluster, you must:

1. Edit the configuration file to remove features that are not supported in a cluster environment.
2. Update the naming convention of interfaces from two-tuple (x/y) format to three-tuple (x/y/z)
format.
3. Apply the configurations to the configuration coordinator node of the cluster by using the batch
command.

Are backplane interfaces part of the L3 VLANs?

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2001

NetScaler 12.0

Yes, by default, backplane interfaces have presence on all the L3 VLANs that are configured on the
cluster.

How can I configure a cluster that includes nodes from different networks?
Note

Supported from NetScaler 11.0 onwards.

A cluster that includes nodes from different networks is called a L3 cluster (sometimes referred to as
a cluster in INC mode). In an L3 cluster, all nodes that belong to a single network must be grouped
together in a single nodegroup. Therefore, if a cluster includes two nodes each from three different
networks, you will have to create 3 nodegroups (one for each network) and associate each of these
nodegroups with the nodes that belong to that network. For configuration information, see the steps
to setup a cluster.

How can I configure/un-configure the NSVLAN on a cluster?

Do either one of the following:

• To make the NSVLAN available in a cluster, make sure that each appliance has the same NSVLAN
configured before it is added to cluster.

• To remove the NSVLAN from a cluster node, first remove the node from the cluster and then
delete the NSVLAN from the appliance.

I have a cluster setup where some NetScaler appliance nodes are not connected to the external
network. Can the cluster still function normally?

Yes. The cluster supports a mechanism called linksets, which allows unconnected nodes to serve traf-
fic by using the interfaces of connected nodes. The unconnected nodes communicate with the con-
nected nodes through the cluster backplane. For more information, see Using Linksets.

How can deployments that require MAC-Based Forwarding (MBF) be supported in a clustered
setup?

Deployments that use MBF must use linksets. For more information, see Using Linksets.

Can I execute commands from the NSIP address of a cluster node?

No. Access to individual cluster nodes through the NSIP addresses is read-only. Therefore, when you
log on to the NSIP address of a cluster node you can only view the configurations and the statistics.
You cannot configure anything. However, there are some operations you can execute from the NSIP
address of a cluster node. For more information, see Operations Supported on Individual Nodes.

Can I disable configuration propagation among cluster nodes?

No, you cannot explicitly disable the propagation of cluster configurations among cluster nodes. How-
ever, during a software upgrade or downgrade, a version mismatch error can automatically disable
configuration propagation.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2002

NetScaler 12.0

Can I change the NSIP address or change the NSVLAN of a NetScaler appliance when it is a part
of the cluster?

No. To make such changes you must first remove the appliance from the cluster, perform the changes,
and then add the appliance to the cluster.

Does the NetScaler cluster support L2 and L3 VLANs?

Yes. A cluster supports VLANs between cluster nodes. The VLANs must be configured on the cluster IP
address.

• L2 VLAN. You can create a layer2 VLAN by binding interfaces that belong to different nodes of
the cluster.

• L3 VLAN. You can create a layer3 VLAN by binding IP addresses that belong to different nodes
of the cluster. The IP addresses must belong to the same subnet. Make sure that one of the
following criteria is satisfied. Otherwise, the L3 VLAN bindings can fail.

– All nodes have an IP address on the same subnet as the one bound to the VLAN.
– The cluster has a striped IP address and the subnet of that IP address is bound to the VLAN.

When you add a new node to a cluster that has only spotted IPs, the sync happens before spotted IP
addresses are assigned to that node. In such cases, L3 VLAN bindings can be lost. To avoid this loss,
either add a striped IP or add the L3 VLAN bindings on the NSIP of the newly added node.

How can I configure SNMP on a NetScaler cluster?

SNMP monitors the cluster, and all the nodes of the cluster, in the same way that it monitors a stan-
dalone appliance. The only difference is that SNMP on a cluster must be configured through the clus-
ter IP address. When generating hardware specific traps, two additional varbinds are included to iden-
tify the node of the cluster: node ID and NSIP address of the node.

What details must I have available when I contact technical support for cluster-related issues?

The NetScaler appliance provides a show techsupport -scope cluster command that extracts config-
uration data, statistical information, and logs of all the cluster nodes. You must run this command on
the cluster IP address.

The output of this command is saved in a file named collector_cluster_<nsip_CCO>_P_<date-

timestamp>.tar.gz which is available in the /var/tmp/support/cluster/ directory of the configuration
coordinator.

Send this archive to the technical support team to debug the issue.

Can I use striped IP addresses as the default gateway of servers?

In case of cluster deployments, make sure the default gateway of the server points to a striped IP
address (if you are using a NetScaler appliance-owned IP address). For example, in case of LB deploy-
ments with USIP enabled, the default gateway must be a striped SNIP address.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2003

NetScaler 12.0

Can I view routing configurations of a specific cluster node from the cluster IP address?

Yes. You can view and clear the configurations specific to a node by specifying the owner node while
entering the vtysh shell.

For example, to view the output of a command on nodes 0 and 1, the command is as follows:

1 \> vtysh
2
3 ns# owner-node 0 1
4 ns(node-0 1)\# show cluster state
5 ns(node-0 1)\# exit-cluster-node
6 ns\#

How can I specify the node for which I want to set the LACP system priority?
Note

Supported from NetScaler 10.1 onwards.

In a cluster, you must set that node as the owner node by using the set lacp command.

For example: To set the LACP system priority for node with ID 2:

set lacp -sysPriority 5 -ownerNode 2

How are IP tunnels configured in a cluster setup?

Note

Supported from NetScaler 10.1 onwards.

Configuring IP tunnels in a cluster is the same as on a standalone appliance. The only difference is
that in a cluster setup, the local IP address must be a striped SNIP or MIP address.

How can I add a failover interface set (FIS) on the nodes of a NetScaler cluster?
Note

Supported from NetScaler 10.5 onwards.

On the cluster IP address, specify the ID of the cluster node on which the FIS must be added, using the
command as follows:

add fis <name> -ownerNode <nodeId>

Notes

• The FIS name for each cluster node must be unique.

• A cluster LA channel can be added to a FIS. You must make sure that the cluster LA channel
has a local interface as a member interface.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2004

NetScaler 12.0

For more information on FIS, see Configuring failover interface set.

How are net profiles configured in a cluster setup?

Note

Supported from NetScaler 10.5 onwards.

You can bind spotted IP addresses to a net profile. This net profile can then be bound to spotted load
balancing virtual server or service (that is defined using a nodegroup). The following recommenda-
tions must be followed, failing which, the net profile configurations are not honored and the USIP/US-
NIP settings will be used:

Note

• If the strict parameter of the nodegroup is set to Yes, the net profile must contain a mini-
mum of one IP address from each nodegroup member.
• If the strict parameter of the nodegroup is set to No, the net profile must include at least
one IP address from each of the cluster nodes.

How can I configure WIonNS in a cluster setup?

Note

Supported from NetScaler 11.0 Build 62.x onwards.

To use WIonNS on a cluster, you must do the following:

1. Make sure that the Java package and the WI package are present in the same directory on all
the cluster nodes.
2. Create a load balancing virtual server that has persistency configured.
3. Create services with IP addresses as the NSIP address of each of the cluster nodes that you want
to serve WI traffic. This step can only be configured using the NetScaler CLI.
4. Bind the services to the load balancing virtual server.

Note

If you are using WIonNS over a VPN connection, make sure that the load balancing virtual server
is set as WIHOME.

Can the cluster LA channel be used for management access?

No. Management access to a cluster node, must not be configured on a cluster LA channel (for exam-
ple, CLA/1) or its member interfaces. This is because when the node is INACTIVE, the corresponding
cluster LA interface is marked as power down and therefore looses management access.

How cluster nodes communicate to each other and what are the different types of traffic that
goes through backplane?

A backplane is a set of interfaces in which one interface of each node is connected to a common switch,

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2005

NetScaler 12.0

which is called the cluster backplane switch. The different types of traffic that goes through back-
plane, which is used by internode communication are:

• Node to Node Messaging (NNM)

• Steered traffic
• Configuration propagation and synchronization

Each node of the cluster uses a special MAC cluster backplane switch address to communicate
with other nodes through the backplane. The cluster special MAC is of the form: 0x02 0x00 0x6F
<cluster_id> <node_id> <reserved>, where <cluster_id> is the cluster instance ID, <node_id> is the
node number of the NetScaler appliance that are added to a cluster.
Note

The amount of traffic that is handled by a backplane will have negligible CPU overhead.

What gets routed over GRE tunnel for Layer 3 cluster?

Only steered data traffic goes over the GRE tunnel. The packets are steered through the GRE tunnel to
the node on the other subnet.

How Node to Node Messaging (NNM) and heartbeat messages are exchanged, and how are they
routed?

The NNM, heartbeat messages, and cluster protocol are non-steering traffic. These messages are not
sent through the tunnel, but they are routed directly.

What are the MTU recommendations when Jumbo frames are enabled for layer 3 cluster tun-
neled traffic?

The following are the layer 3 cluster recommendations of Jumbo MTU over GRE tunnel:

• The Jumbo MTU can be configured among cluster nodes across the L3 path to accommodate
GRE tunnel overhead.
• The fragmentation does not happen for full sized packets which need to be steered.
• Steering of traffic continues to work even if Jumbo frames are not allowed, but with more over-
head due to fragmentation.

How the global hash key is generated and shared across all nodes?

The rsskey for a standalone appliance is generated at the boot time. In a cluster setup, the first node
holds the rsskey of the cluster. Every new node joining to the cluster will synchronize the rsskey.

What is the need of “set rsskeytype –rsskey symmetric” command for *:*, USIP on, useproxyport
off, topologies?

This is not specific to cluster, applies to a standalone appliance as well. With USIP ON, and use proxy
port disabled, symmetric rsskey reduces both Core to Core (C2C) steering and node to node steering.

1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2006

NetScaler 12.0

2. Citrix ADC
3. NetScaler 12.0
4. Clustering

Troubleshooting the NetScaler cluster

September 18, 2018

Contributed by:
C

If a failure occurs in a NetScaler cluster, the first step in troubleshooting is to get information on the
cluster instance and the cluster nodes by running the show cluster instance <clId> and show cluster
node <nodeId> commands respectively.

If you are not able to find the issue by using the above two approaches, you can use one of the follow-
ing:

• Isolate the source of the failure. Try bypassing the cluster to reach the server. If the attempt
is successful, the problem is probably with the cluster setup.

• Check the commands recently executed. Run the history command to check the recent con-
figurations performed on the cluster. You can also review the ns.conf file to verify the configu-
rations that have been implemented.

• Check the ns.log files. Use the log files, available in the /var/log/ directory of each node, to
identify the commands executed, status of commands, and the state changes.

• Check the newnslog files. Use the newnslog files, available in the /var/nslog/ directory of each
node, to identify the events that have occurred on the cluster nodes. You can view multiple
newnslog files as a single file, by copying the files to a single directory, and then running the
following command:

1 nsconmsg -K newnslog-node<id> -K newnslog.node<id> -d current

If you still cannot resolve the issue, you can try tracing the packets on the cluster or use the show
techsupport -scope cluster command to send the report to the technical support team.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2007

NetScaler 12.0

Tracing the packets of a NetScaler cluster

January 6, 2019

Contributed by:
C

The NetScaler appliance operating system provides a utility called nstrace to get a dump of the packets
that are received and sent out by an appliance. The utility stores the packets in trace files. You can
use these files to debug problems in the flow of packets to the cluster nodes. The trace files must be
viewed with the Wireshark application.

Some salient aspects of the nstrace utility are:

• Can be configured to trace packets selectively by using classic expressions and default expres-
sions.
• Can capture the trace in multiple formats: nstrace format (.cap) and TCP dump format (.pcap).
• Can aggregate the trace files of all cluster nodes on the configuration coordinator.
• Can merge multiple trace files into a single trace file (only for .cap files).

You can use the nstrace utility from the NetScaler appliance command line or the NetScaler appliance
shell.

To trace packets of a standalone appliance

Run the start nstrace command on the appliance. The command creates trace files in the /var/n-
strace/<date-timestamp> directory. The trace file names are of the form nstrace<id>.cap.

You can view the status by executing the show nstrace command. You can stop tracing the packets by
executing the stop nstrace command.

Note

You can also run the nstrace utility from the NetScaler appliance shell by executing the
nstrace.sh file. However, it is recommended that you use the nstrace utility through the NetScaler
appliance command line interface.

To trace packets of a cluster

You can trace the packets on all the cluster nodes and obtain all the trace files on the configuration
coordinator.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2008

NetScaler 12.0

Run the start nstrace command on the cluster IP address. The command is propagated and executed
on all the cluster nodes. The trace files are stored in individual cluster nodes in the /var/nstrace/<date-
timestamp> directory. The trace file names are of the form nstrace<id>_node<id>.cap.

You can use the trace files of each node to debug the nodes operations. But if you want the trace
files of all cluster nodes in one location, you must run the stop nstrace command on the cluster IP
address. The trace files of all the nodes are downloaded on the cluster configuration coordinator in
the /var/nstrace/<date-timestamp> directory as follows:

Merge multiple trace files

You can prepare a single file from the trace files (supported only for .cap files) obtained from the cluster
nodes. The single trace files gives you a cumulative view of the trace of the cluster packets. The trace
entries in the single trace file are sorted based on the time the packets were received on the cluster.

To merge the trace files, at the NetScaler appliance shell, type:

nstracemerge.sh -srcdir <DIR> -dstdir <DIR> -filename <name> -filesize <num>

where,

• srcdir is the directory from which the trace files are merged. All trace files within this directory
are merged into a single file.
• dstdir is the directory where the merged trace file are created.
• filename is the name of the trace file that is created.
• filesize is the size of the trace file.

Examples

Following are some examples of using the nstrace utility to filter packets.

• To trace the packets on the backplane interfaces of three nodes:

Using classic expressions:

1 start nstrace -filter ”INTF == 0/1/1 && INTF == 1/1/1 && INTF ==
2/1/1”

Using default expressions:

1 start nstrace -filter ”CONNECTION.INTF.EQ(”0/1/1”) && CONNECTION.

INTF.EQ(”1/1/1”) && CONNECTION.INTF.EQ(”2/1/1”)”

• To trace the packets from a source IP address 10.102.34.201 or from a system whose source port
is greater than 80 and the service name is not “s1”:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2009

NetScaler 12.0

Using classic expressions

1 start nstrace -filter ”SOURCEIP == 10.102.34.201 || (SVCNAME !=

s1 && SOURCEPORT > 80)”

Using default expressions

1 start nstrace -filter ”CONNECTION.SRCIP.EQ(10.102.34.201) || (

CONNECTION.SVCNAME.NE(”s1”) && CONNECTION.SRCPORT.GT(80))”

Note

For more information about filters used in nstrace, see nstrace.

Capturing SSL Session Keys During a Trace

When you run the “start nstrace” command, you can set the new “capsslkeys” parameter to capture
the SSL master keys for all SSL sessions. If you include this parameter, a file named nstrace.sslkeys
is generated along with the packet trace. This file can be imported into Wireshark to decrypt the SSL
traffic in the corresponding trace file.

This functionality is similar to web browsers exporting session keys that can later be imported into
Wireshark for decrypting SSL traffic.

Advantages of using SSL session keys

Following are the advantages of using SSL session keys:

1. Generates smaller trace files that do not include the extra packets created by the SSLPLAIN
mode of capturing.
2. Provides the ability to view plaintext [SP(1] from the trace and choose whether to share the mas-
ter keys file or protect sensitive data by not sharing it.

Limitations of using SSL session keys

Following are the limitations of using SSL session keys:

1. SSL sessions cannot be decrypted if initial packets of the session are not captured.
2. SSL sessions cannot be captured if the Federal Information Processing Standard (FIPS) mode is
enabled.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2010

NetScaler 12.0

To capture SSL session keys by using the command line interface (CLI)

At the command prompt, type the following commands to enable or disable SSL session keys in a
trace file and verify trace operation.

1 > start nstrace -capsslkeys ENABLED

2 > show nstrace
3 Example
4 > start nstrace -capsslkeys ENABLED
5 > show nstrace
6       State:  RUNNING          Scope:  LOCAL            TraceLocation: 
”/var/nstrace/04May2016_17_51_54/...”
7       Nf:  24                  Time:  3600              Size:  164
               Mode:  TXB NEW_RX
8       Traceformat:  NSCAP      PerNIC:  DISABLED        FileName:
 04May2016_17_51_54 Link:  DISABLED
9       Merge:  ONSTOP           Doruntimecleanup:  ENABLED TraceBuffers:
  5000      SkipRPC:  DISABLED
10       SkipLocalSSH:  DISABLED  Capsslkeys:  ENABLED     InMemoryTrace: 
DISABLED
11  Done

To configure SSL session keys by using the NetScaler GUI

1. Navigate to Configuration > System > Diagnostics > Technical Support Tools and click Start
new Trace to start tracing encrypted packets on an appliance.
2. On the Start Trace page, select the Capture SSL Master Keys check box.
3. Click OK and Done.

To import the SSL Master Keys into Wireshark

On the Wireshark GUI, navigate to Edit > Preferences > Protocols > SSL > (Pre)-Master-Secret log
filename and specify the master key files obtained from the appliance.

1.
2. Citrix ADC
3. NetScaler 12.0
4. Clustering

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2011

NetScaler 12.0

Troubleshooting common issues

September 18, 2018

Contributed by:
C

While joining a node to the cluster, I get the following message, “ERROR: Invalid interface
name/number.” What must I do to resolve this error?

This error occurs if you provided an invalid or incorrect backplane interface while using the add cluster
nodecommand to add the node. To resolve this error, verify the interface you provided while adding
the node. Make sure that you have not specified the appliance’s management interface as the back-
plane interface, and that the <nodeId> bit of the interface is the same as the node’s Id. For example,
if the nodeId is 3, the backplane interface must be 3/<c>/<u>.

While joining a node to the cluster, I get the following message, “ERROR: Clustering cannot be
enabled, because the local node is not a member of the cluster.” What must I do to resolve this
error?

This error occurs when you try to join a node without adding the node’s NSIP to the cluster. To re-
solve this error, you must first add the node’s NSIP address to the cluster by using the add cluster
node command and then execute the join cluster command.

While joining a node to the cluster, I get the following message, “ERROR: Connection refused.”
What must I do to resolve this error?

This error can occur due to the following reasons:

• Connectivity problems. The node cannot connect to the cluster IP address. Try pinging the
cluster IP address from the node that you are trying to join.

• Duplicate cluster IP address. Check to see if the cluster IP address exists on some non-cluster
node. If it does, create a new cluster IP address and try re-joining the cluster.

While joining a node to the cluster, I get the following message, “ERROR: License mismatch be-
tween the configuration coordinator and the local node.” What must I do to resolve this error?

The appliance that you are joining to the cluster must have the same licenses as the configuration
coordinator. This error occurs when the licenses on the node you are joining do not match the licenses
on the configuration coordinator. To resolve this error, run the following commands on both the nodes
and compare the outputs.

From the command line:

• show ns hardware

• show ns license

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2012

NetScaler 12.0

From the shell:

• nsconmsg -g feature -d stats

• ls /nsconfig/license

• View the contents of the /var/log/license.log file

What must I do when the configurations of a cluster node are not in synch with the cluster con-
figurations?

In most cases, the configurations are automatically synchronized between all the cluster nodes. How-
ever, if you feel that the configurations are not synchronized on a specific node, you must force the
synchronization by executing the force cluster sync command from the node that you want to syn-
chronize. For more information, see Synchronizing Cluster Configurations.

When configuring a cluster node, I get the following message, “ERROR: Session is read-only; connect
to the cluster IP address to modify the configuration.”

All configurations on a cluster must be done through the cluster IP address and the configurations are
propagated to the other cluster nodes. All sessions established through the NSIP address of individual
nodes are read-only.

Why does the node state show “INACTIVE” when the node health shows “UP”?

A healthy node can be in the INACTIVE state for a number of reasons. A scan of ns.log or error counters
can help you determine the exact reason.

How can I resolve the health of a node when its health shows “NOT UP”?

Node health “Not UP” indicates that there are some issues with the node. To know the root cause,
you must run the show cluster node command. This command displays the node properties and the
reason for the node failure.

What must I do when the health of a node shows as “NOT UP” and the reason indicates that
configuration commands have failed on a node?

This issue arises when some commands are not executed on the cluster nodes. In such cases, you
must make sure that the configurations are synchronized using one of the following options:

• If some of the cluster nodes are in this state, you must perform the force cluster synchronization
operation on those nodes. For more information, see Synchronizing Cluster Configurations.

• If all cluster nodes are in this state, you must disable and then enable the cluster instance on all
the cluster nodes.

When I run the set vserver command, I get the following message, “No such resource.” What
must I do to resolve this issue?

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2013

NetScaler 12.0

The set vserver command is not supported in clustering. The unset vserver, enable vserver, disable
vserver, and rm vserver commands are also not supported. However, the show vserver command
is supported.

I cannot configure the cluster over a Telnet session. What must I do?

Over a telnet session, the cluster IP address can be accessed only in read-only mode. Therefore, you
cannot configure a cluster over a telnet session.

I notice a significant time difference across the cluster nodes. What must I do to resolve this
issue?

When PTP packets are dropped due to backplane switch or if the physical resources are over-
committed in a virtual environment, the time will not get synchronized.

To synchronize the times, you must do the following on the cluster IP address:

1. Disable PTP.

set ptp -state disable

2. Configure Network Time Protocol (NTP) for the cluster. For more information, see Setting up
Clock Synchronization.

What must I do, if there is no connectivity to the cluster IP address and the NSIP address of a
cluster node?

If you cannot access to the cluster IP address or the NSIP of a cluster node, you must access the appli-
ance through the serial console. If the NSIP address is reachable, you can SSH to the cluster IP address
from the shell by executing the following command at the shell prompt:

## ssh nsroot@<cluster IP address>

What must I do to recover a cluster node that has connectivity issues?

To recover a node that has connectivity issues:

1. Disable the cluster instance on that node (since you cannot execute commands from the NSIP
of a cluster node).

2. Execute the commands required to recover the node.

3. Enable the cluster instance on that node.

Some nodes of the cluster have two default routes. How can I remove the second default route
from the cluster node?

To delete the additional default route, do the following on each node that has the extra route:

1. Disable the cluster instance.

disable cluster instance <clId>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2014

NetScaler 12.0

2. Remove the route.

rm route <network> <netmask> <gateway>

3. Enable the cluster instance.

enable cluster instance <clId>

The cluster functionality gets affected when an existing cluster node comes online. What must I
do to resolve this issue?

If RPC password of node is changed from the cluster IP address when that node is out of the cluster,
then, when the node comes online, there is a mismatch in rpc credentials and this could affect cluster
functionality. To solve this issue, use the set ns rpcNode command to update the password on the
NSIP of the node which has come online.

1.
2. Citrix ADC
3. NetScaler 12.0

Content Switching

January 6, 2019

Contributed by:
C

In today’s complex Web sites, you may want to present different content to different users. For exam-
ple, you may want to allow users from the IP range of a customer or partner to have access to a special
Web portal. You may want to present content relevant to a specific geographical area to users from
that area. You may want to present content in different languages to the speakers of those languages.
You may want to present content tailored to specific devices, such as smartphones, to those who use
the devices. The NetScaler content switching feature enables the appliance to distribute client re-
quests across multiple servers on the basis of specific content that you wish to present to those users.

To configure content switching, first create a basic content switching setup, and then customize it to
meet your needs. This entails enabling the content switching feature, setting up load balancing for
the server or servers that host each version of the content that is being switched, creating a content
switching virtual server, creating policies to choose which requests are directed to which load bal-
ancing virtual server, and binding the policies to the content switching virtual server. You can then
customize the setup to meet your needs by setting precedence for your policies, protecting your setup
by configuring a backup virtual server, and improving the performance of your setup by redirecting
requests to a cache.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2015

NetScaler 12.0

How Content Switching Works

Content Switching enables the NetScaler appliance to direct requests sent to the same Web host to dif-
ferent servers with different content. For example, you can configure the appliance to direct requests
for dynamic content (such as URLs with a suffix of .asp, .dll, or .exe) to one server and requests for
static content to another server. You can configure the appliance to perform content switching based
on TCP/IP headers and payload.

You can also use content switching to configure the appliance to redirect requests to different servers
with different content on the basis of various client attributes. Some of those client attributes are:

• Device Type. The appliance examines the user agent or custom HTTP header in the client re-
quest for the type of device from which the request originated. Based on the device type, it
directs the request to a specific Web server. For example, if the request came from a cell phone,
the request is directed to a server that is capable of serving content that the user can view on
his or her cell phone. A request from a computer is directed to a different server that is capable
of serving content designed for a computer screen.
• Language. The appliance examines the Accept-Language HTTP header in the client request and
determines the language used by the client’s browser. The appliance then sends the request to
a server that serves content in that language. For example, using content switching based on
language, the appliance can send someone whose browser is configured to request content in
French to a server with the French version of a newspaper. It can send someone else whose
browser is configured to request content in English to a server with the English version.
• Cookie. The appliance examines the HTTP request headers for a cookie that the server set pre-
viously. If it finds the cookie, it directs requests to the appropriate server, which hosts custom
content. For example, if a cookie is found that indicates that the client is a member of a cus-
tomer loyalty program, the request is directed to a faster server or one with special content. If
it does not find a cookie, or if the cookie indicates that the user is not a member, the request is
directed to a server for the general public.
• HTTP Method. The appliance examines the HTTP header for the method used, and sends the
client request to the right server. For example, GET requests for images can be directed to an
image server, while POST requests can be directed to a faster server that handles dynamic con-
tent.
• Layer 3/4 Data. The appliance examines requests for the source or destination IP, source or des-
tination port, or any other information present in the TCP or UDP headers, and directs the client
request to the right server. For example, requests from source IPs that belong to customers can
be directed to a custom web portal on a faster server, or one with special content.

A typical content switching deployment consists of the entities described in the following diagram.

Figure 1. Content Switching Architecture

A content switching configuration consists of a content switching virtual server, a load balancing setup

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2016

NetScaler 12.0

consisting of load balancing virtual servers and services, and content switching policies. To configure
content switching, you must configure a content switching virtual server and associate it with policies
and load balancing virtual servers. This process creates a content group—a group of all virtual servers
and policies involved in a particular content switching configuration.

Content switching can be used with HTTP, HTTPS, TCP, and UDP connections. For HTTPS, you must
enable SSL Offload.

When a request reaches the content switching virtual server, the virtual server applies the associated
content switching policies to that request. The priority of the policy defines the order in which the
policies bound to the content switching virtual server are evaluated. If you are using default syntax
policies, when you bind a policy to the content switching virtual server, you must assign a priority to
that policy. If you are using NetScaler classic policies, you can assign a priority to your policies, but
are not required to do so. If you assign priorities, the policies are evaluated in the order that you set.
If you do not, the NetScaler appliance evaluates your policies in the order in which they were created.

In addition to configuring policy priorities, you can manipulate the order of policy evaluation by using
Goto expressions and policy bank invocations. For more details about default syntax policy configu-
ration, see “Configuring Default Syntax Policies.”

After it evaluates the policies, the content switching virtual server routes the request to the appropri-
ate load balancing virtual server, which sends it to the appropriate service.

Content switching virtual servers can only send requests to other virtual servers. If you are using an
external load balancer, you must create a load balancing virtual server for it and bind its virtual server
as a service to the content switching virtual server.

1.
2. Citrix ADC
3. NetScaler 12.0

Configuring basic content switching

February 11, 2019

Contributed by:
C

Before you configure content switching, you must understand how content switching is set up and
how the services and virtual servers are connected.

To configure a basic, functional content switching setup, first enable the content switching feature.
Then, create at least one content group. For each content group, create a content switching virtual

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2017

NetScaler 12.0

server to accept requests to a group of web sites that use content switching. Also create a load bal-
ancing setup, which includes a group of load balancing virtual servers to which the content switching
virtual server directs requests. To specify which requests to direct to which load balancing virtual
server, create at least two content switching policies, one for each type of request that is to be redi-
rected. When you have created the virtual servers and policies, bind the policies to the content switch-
ing virtual server. You can also bind a policy to multiple content switching virtual servers. When you
bind a policy, you specify the load balancing virtual server to which requests that match the policy
are to be directed.

In addition to binding individual policies to a content switching virtual server, you can bind policy
labels. If you create additional content groups, you can bind a policy or policy label to more than one
of the content switching virtual servers.

Note

After creating a content group, you can modify its content switching virtual server to customize
the configuration. For information on modifying the configuration of an existing content switch-
ing virtual server, see “
Customizing the Basic Content Switching Configuration.” For information on disabling and re-
enabling entities, unbinding policies, and removing entities, see “
Managing a Content Switching Setup.”

This section includes the following details:

• Enabling Content Switching

• Creating Content Switching Virtual Servers
• Configuring a Load Balancing Setup for Content Switching
• Configuring a Content Switching Action
• Configuring Content Switching Policies
• Configuring Content Switching Policy Labels
• Binding Policies to a Content Switching Virtual Server
• Configuring Policy Based Logging for Content Switching
• Verifying the Configuration

1.
2. Citrix ADC
3. NetScaler 12.0

Enabling content switching

September 19, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2018

NetScaler 12.0

Contributed by:
C

To use the content switching feature, you must enable content switching. You can configure content
switching entities even though the content switching feature is disabled. However, the entities will
not work.

To enable content switching by using the command line interface

At the command prompt, type the following commands to enable content switching and verify the
configuration:

• enable ns feature CS

• show ns feature

Example

1 > enable feature ContentSwitch

2 Done
3 > show feature
4
5 Feature Acronym Status
6 ------- ------- ------
7 1) Web Logging WL OFF
8 2) Surge Protection SP ON
9 3) Load Balancing LB ON
10 4) Content Switching CS ON
11 .
12 .
13 .
14 22) Responder RESPONDER ON
15 23) HTML Injection HTMLInjection ON
16 24) NetScaler Push push OFF
17 Done

To enable content switching by using the configuration utility

Navigate to System > Settings and, in the Modes and Features group, select Configure Basic Fea-
tures, and select Content Switching.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2019

NetScaler 12.0

Creating content switching virtual servers

September 19, 2018

Contributed by:
C

You can add, modify, and remove content switching virtual servers. The state of a virtual server is
DOWN when you create it, because the load balancing virtual server is not yet bound to it.

To create a virtual server by using the command line interface

At the command prompt, type:

add cs vserver \<name\> \<protocol\> \<IPAddress\> \<port\>

Example

1 add cs vserver Vserver-CS-1 HTTP 10.102.29.161 80

To add a content switching virtual server by using the configuration utility

Navigate to Traffic Management > Content Switching > Virtual Servers, and add a virtual server.

1.
2. Citrix ADC
3. NetScaler 12.0

Configuring a load balancing setup for content switching

September 19, 2018

Contributed by:
C

The content switching virtual server redirects all requests to a load balancing virtual server. You must
create one load balancing virtual server for each version of the content that is being switched. This is
true even when your setup has only one server for each version of the content, and you are therefore
not doing any load balancing with those servers. You can also configure actual load balancing with
multiple load-balanced servers that mirror each version of the content. In either scenario, the content

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2020

NetScaler 12.0

switching virtual server needs to have a specific load balancing virtual server assigned to each version
of the content that is being switched.
The load balancing virtual server then forwards the request to a service. If it has only one service
bound to it, it selects that service. If it has multiple services bound to it, it uses its configured load
balancing method to select a service for the request, and forwards that request to the service that it
selected.
To configure a basic load balancing setup, you need to perform the following tasks:
• Create load balancing virtual servers
• Create services
• Bind services to the load balancing virtual server
For more information on load balancing, see Load Balancing. For detailed instructions on setting up
a basic load balancing configuration, see Set up basic load balancing.
1.
2. Citrix ADC
3. NetScaler 12.0

Configuring a content switching action

September 19, 2018

Contributed by:
C
You specify the target load balancing virtual server for a content switching policy when binding the
policy to the content switching virtual server. Consequently, you have to configure one policy for each
load balancing virtual server to which to direct traffic.
However, if your content switching policy uses a default syntax rule, you can configure an action for
the policy. In the action, you can specify the name of the target load balancing virtual server, or you
can configure a request-based expression that, at run time, computes the name of the load balancing
virtual server to which to send the request. The action expression must be specified in the default
syntax.
The expression option can drastically reduce the size of your content switching configuration, because
you need only one policy per content switching virtual server. Content switching policies that use an
action can also be bound to multiple content switching virtual servers, because the target load bal-
ancing virtual server is no longer specified in the content switching policy. The ability to bind a single
policy to multiple content switching virtual servers helps to further reduce the size of your content
switching configuration.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2021

NetScaler 12.0

After you create an action, you create a content switching policy and specify the action in the policy,
so that the action is performed when that policy matches a request.

Note

You can also, for a content switching policy that uses a default syntax rule, specify the target load
balancing virtual server when binding the policy to a content switching virtual server, instead of
using a separate action. For domain-based policies, URL-based policies, and rule based policies
that use classic expressions, an action is not available. So, for these types of policies, you specify
the name of the target load balancing virtual server when binding the policy to a content switch-
ing virtual server. For more information, see “
Binding Policies to a Content Switching Virtual Server.”

Configuring an Action that Specifies the Name of the Target Load Balancing Virtual
Server

If you choose to specify the name of the target load balancing virtual server in a content switching
action, you need as many content switching policies as you have target load balancing virtual servers.
Content switching decisions, in this case, are based on the rule in the content switching policy, and the
action merely specifies the target load balancing virtual server. When a request matches the policy,
the request is forwarded to the specified load balancing virtual server.

To create and verify a content switching action that specifies the name of the target load
balancing virtual server, by using the command line interface

At the command prompt, type:

• add cs action <name> -targetLBVserver <string> [-comment <string>]

• show cs action <name>

Example

1 > add cs action mycsaction -targetLBVserver mylbvserver -comment ”

Forwards requests to mylbvserver.”
2 Done
3 > show cs action mycsaction
4 Name: mycsaction
5 Target LB Vserver: mylbvserver
6 Hits: 0
7 Undef Hits: 0
8 Action Reference Count: 0
9 Comment: ”Forwards requests to mylbvserver.”

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2022

NetScaler 12.0

10
11 Done
12 >

To configure a content switching action that specifies the name of the target load balancing
virtual server, by using the configuration utility

1. Navigate to Traffic Management > Content Switching > Actions.

2. Configure a content switching action, and specify the name of the target load balancing virtual
server.

Configuring an Action that Specifies an Expression for Selecting the Target at Run Time

If you choose to configure a request-based expression that can dynamically compute the name of the
target load balancing virtual server, you need to configure only one content switching policy to select
the appropriate virtual server. The rule for the policy can be a simple TRUE (the policy matches all
requests) because, in this case, content switching decisions are based on the expression in the action.
By configuring an expression in an action, you can drastically reduce the size of your content switching
configuration.

If you choose to configure a request-based expression for computing the name of the target load bal-
ancing virtual server at run time, you must carefully consider how to name the load balancing virtual
servers in the configuration. You must be able to derive their names by using the request-based policy
expression in the action.

For example, if you are switching requests on the basis of the URL suffix (file extension of the re-
quested resource), when naming the load balancing virtual servers, you can follow the convention
of appending the URL suffix to a predetermined string, such as mylb_. For example, load balancing
virtual servers for HTML pages and PDF files could be named mylb_html and mylb_pdf, respectively.
In that case, the rule that you can use in the content switching action, to select the appropriate load
balancing virtual server, is “mylb_“+HTTP.REQ.URL.SUFFIX. If the content switching virtual server re-
ceives a request for an HTML page, the expression returns mylb_html, and the request is switched to
virtual server mylb_html.

To create a content switching action that specifies an expression, by using the command line
interface

At the command line, type the following commands to create a content switching action that specifies
an expression and verify the configuration:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2023

NetScaler 12.0

1 - add cs action \<name\> -targetVserverExpr \<expression\>) \[-comment

\<string\>\]
2 - show cs action \<name\>

Example

1 > add cs action mycsaction1 -targetvserverExpr ’”mylb_” + HTTP.REQ.URL.

SUFFIX’
2 Done
3 > show cs action mycsaction1
4 Name: mycsaction1
5 Target Vserver Expression: ”mylb_” + HTTP.REQ.URL.SUFFIX
6 Target LB Vserver: No_Target
7 …
8 Done
9 >

To configure a content switching action that specifies an expression by using the configuration
utility

1. Navigate to Traffic Management > Content Switching > Actions.

2. Configure a content switching action, and specify an expression that will dynamically compute
the name of the target load balancing virtual server.

1.
2. Citrix ADC
3. NetScaler 12.0

Configuring content switching policies

March 6, 2019

Contributed by:
C

A content switching policy defines a type of request that is to be directed to a load balancing virtual
server. These policies are applied in the order of the priorities assigned to them or (if you are using
NetScaler appliance classic policies and do not assign priorities when binding them) in the order in
which the policies were created.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2024

NetScaler 12.0

The policies can be:

• Domain-based policies. The NetScaler appliance compares the domain of an incoming URL
with the domains specified in the policies. The appliance then returns the most appropriate
content. Domain-based policies must be classic policies; default syntax policies are not sup-
ported for this type of content switching policy.

• URL-based policies. The appliance compares an incoming URL with the URLs specified in the
policies. The appliance then returns the most appropriate URL-based content, which is usually
the longest matching configured URL. URL-based policies must be classic policies; default syn-
tax policies are not supported for this type of content switching policy.

• Rule-based policies. The appliance compares incoming data to expressions specified in the
policies. You create rule-based policies by using either a classic expression or a default syn-
tax expression. Both classic and default syntax policies are supported for rule-based content
switching policies.

Note

A rule based policy can be configured with an optional action. A policy with an action can
be bound to multiple virtual servers or policy labels.

If you set a priority when binding your policies to the content switching virtual server, the poli-
cies are evaluated in order of priority. If you do not set specific priorities when binding your
policies, the policies are evaluated in the order in which they were created.

For information about NetScaler appliance classic policies and expressions, see “Configuring Classic
Policies and Expressions.”

For information about Default Syntax policies, see “Configuring Advanced Policy Expressions”

To create a content switching policy by using the command line interface

At the command prompt, type one of the following commands:

• add cs policy <policyName> -domain <domain>

• add cs policy <policyName> -url <URLValue>
• add cs policy <policyName> -rule <RULEValue>
• add cs policy <policyName> -rule <RULEValue> -action <actionName>

Example:

1 add cs policy Policy-CS-1 -url ”http://example.com”

2
3 add cs policy Policy-CS-1 -domain ”example.com”
4

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2025

NetScaler 12.0

5 add cs policy Policy-CS-1 -rule ”CLIENT.IP.SRC.SUBNET(24).EQ

(10.217.84.0)”
6
7 add cs policy Policy-CS-2 -rule ”SYS.TIME.BETWEEN(GMT 2009 Nov,GMT 2009
Dec)”
8
9 add cs policy Policy-CS-3 -rule ”http.req.method.eq(GET)” -action act1

To rename a content switching policy by using the command line interface

At the command prompt, type:

rename cs policy <policyName> <newName>

Example:

1 rename cs policy myCSPolicy myCSPolicy1

To rename a content switching policy by using the configuration utility

Navigate to Traffic Management > Content Switching > Policies, select a policy and, in the Action
list, select Rename.

To create a content switching policy by using the configuration utility

Navigate to Traffic Management > Content Switching > Policies, and configure a content switching
policy.

1.
2. Citrix ADC
3. NetScaler 12.0

Configuring content switching policy labels

September 19, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2026

NetScaler 12.0

A policy label is a user-defined bind point to which policies are bound. When a policy label is invoked,
all the policies bound to it are evaluated in the order of the priority that you assigned to them. A policy
label can include one or more policies, each of which can be assigned its own result. A match on one
policy in the policy label can result in proceeding to the next policy, invoking a different policy label
or appropriate resource, or an immediate end to policy evaluation and return of control to the policy
that invoked the policy label. You can create policy labels for default syntax policies only.
For information about policy labels, see the “Creating Policy Labels.”
A content switching policy label consists of a name, a label type, and a list of policies bound to the
policy label. The policy label type specifies the protocol that was assigned to the policies bound to
the label. It must match the service type of the content switching virtual server to which the policy
that invokes the policy label is bound. For example, you can bind TCP Payload policies to a policy
label of type TCP only. Binding TCP Payload policies to a policy label of type HTTP is not supported.
Each policy in a content switching policy label is associated with either a target (which is equivalent to
the action that is associated with other types of policies, such as rewrite and responder policies) or a
gotoPriorityExpression option and/or an invoke option. That is, for a given policy in a content switch-
ing policy label, you can specify a target, or you can set the gotoPriorityExpression option and/or the
invoke option. Additionally, if multiple policies evaluate to true, only the target of the last policy that
evaluates to true is considered.
You can use either the NetScaler appliance CLI or the configuration utility to configure content switch-
ing policy labels. In the NetScaler appliance CLI, you first create a policy label by using the add cs
policylabel command. Then, you bind policies to the policy label, one policy at a time, by using the
bind cs policylabel command. In the NetScaler appliance GUI, you perform both tasks in a single dia-
log box.

To create a content switching policy label by using the command line interface

At the command prompt, type:

add cs policylabel <labelName> <cspolicylabelTypetype>

Example

1 add cs policylabel testpollab http

To rename a content switching policy label by using the command line interface

At the command prompt, type:

rename cs policylabel <labelName> <newName>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2027

NetScaler 12.0

Example

1 rename cs policylabel oldPolicyLabelName newPolicyLabelName

To rename a content switching policy label by using the configuration utility

Navigate to Traffic Management > Content Switching > Policy Labels , select a policy label and, in the
Action list, select Rename.

To bind a policy to a content switching policy label by using the command line interface

At the command prompt, type the following commands to bind a policy to a policy label and verify
the configuration:

bind cs policylabel [-gotoPriorityExpression [-invoke <labeltype>

<labelName> <policyName> <expression>] <labelName>] ]
<priority>[ [-targetVserver
<string>]

• show cs policylabel <labelName>

Example

1 bind cs policylabel testpollab test_Pol 100 -targetVserver LBVIP

2 show cs policylabel testpollab
3 Label Name: testpollab
4 Label Type: HTTP
5 Number of bound policies: 1
6 Number of times invoked: 0
7 Policy Name: test_Pol
8 Priority: 100
9 Target Virtual Server: LBVIP

Note: If a policy is configure with an action, the target virtual server (targetVserver), go to priority
expression (gotoPriorityExpression), and invoke (invoke) parameters are not required. If a policy
is not configure with an action, you need to configure at least one of the following parameters:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2028

NetScaler 12.0

targetVserver, gotoPriorityExpression, and invoke.

To unbind a policy from a policy label by using the command line interface

At the command prompt, type the following commands to unbind a policy from a policy label and
verify the configuration:

• unbind cs policylabel <labelName> <policyName>

• show cs policylabel <labelName>

Example

1 unbind cs policylabel testpollab test_Pol

2 show cs policylabel testpollab
3 Label Name: testpollab
4 Label Type: HTTP
5 Number of bound policies: 0
6 Number of times invoked: 0

To remove a policy label by using the command line interface

At the command prompt, type:

rm cs policylabel <labelName>

To manage a content switching policy label by using the configuration utility

Navigate to Traffic Management > Content Switching > Policy Labels, configure a policy label, bind
policies to the label, and optionally specify a priority, gotoPriority expression, and an invoke option.

1.
2. Citrix ADC
3. NetScaler 12.0

Binding policies to a content switching virtual server

September 19, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2029

NetScaler 12.0

Contributed by:
C

After you create your content switching virtual server and policies, you bind each policy to the content
switching virtual server. When binding the policy to the content switching virtual server, you specify
the target load balancing virtual server.

Note

If your content switching policy uses a default syntax rule, you can configure a content switching
action for the policy. If you configure an action, you must specify the target load balancing virtual
server when you are configuring the action, not when you are binding the policy to the content
switching virtual server. For more information about configuring a content switching action, see
Configuring a Content Switching Action.

To bind a policy to a content switching virtual server and select a target load balancing
virtual server by using the command line interface

At the command prompt, type:

1 bind cs vserver \<name\>\[-lbvserver\<string\> -targetLBVServer\<string

\> -policyname \<string\> -priority \<positive\_integer\>\] \[-
gotoPriorityExpression \<expression\>\] \[-type ( REQUEST | RESPONSE
)\] \[-invoke (\<labelType\> \<labelName\>) \]

Example:

1 bind cs vserver csw-vip2 -policyname csw-ape-policy2 -priority 14 -

gotoPriorityExpression NEXT
2
3 bind cs vserver csw-vip3 -policyname rewrite-policy1 -priority 17 -
gotoPriorityExpression
4 ’q.header(”a”).count’ -flowtype REQUEST -invoke policylabel label1

1 bind cs vserver Vserver-CS-1 Vserver-LB-1 -policyname Policy-CS-1 -

priority 20

Note

The parameters, target load balancing virtual server (targetVserver), go to priority expression
(gotoPriorityExpression), and invoke method (invoke) cannot be used if a policy has an action.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2030

NetScaler 12.0

To bind a policy to a content switching virtual server and select a target load balancing
virtual server by using the configuration utility

Navigate to Traffic Management > Content Switching > Virtual Servers, open a virtual server and,
in the
Content Switching Policy Binding section, bind a policy to the virtual server, and specify a target load
balancing virtual server.

1.
2. Citrix ADC
3. NetScaler 12.0

Configuring policy based logging for content switching

September 19, 2018

Contributed by:
C

You can configure policy based logging for a content switching policy. Policy based logging enables
you to specify a format for log messages. The contents of the log message are defined by using a
default syntax expression in the content switching policy. When the content switching action specified
in the policy is performed, the NetScaler appliance constructs the log message from the expression
and writes the message to the log file. Policy based logging is particularly useful if you want to test
and troubleshoot a configuration in which content switching actions identify the target load balancing
virtual server at run time.
Note

If multiple policies bound to a given virtual server evaluate to TRUE and are configured with an
audit message action, the NetScaler appliance does not perform all the audit message actions. It
performs only the audit message action that is configured for the policy whose content switching
action is performed.

To configure policy based logging for a content switching policy, you must first configure an audit
message action. For more information about configuring an audit message action, see Configuring
the NetScaler appliance for Audit Logging. After you configure the audit message action, you specify
the action in a content switching policy.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2031

NetScaler 12.0

To configure policy based logging for a content switching policy by using the command
line interface

At the command line, type the following commands to configure policy based logging for a content
switching policy and verify the configuration:

• set cs policy <policyName> -logAction <string>

• show cs policy <policyName>

Example

1 > set cs policy cspol1 -logAction csLogAction

2 Done
3 > show cs policy cspol1
4
5 Policy: cspol1 Rule: TRUE Action: csact1
6 LogAction: csLogAction
7 Hits: 0
8
9 1) CS Vserver: csvs1
10 Priority: 10
11 Done
12 >

To configure policy based logging for a content switching policy by using the
configuration utility

Navigate to Traffic Management > Content Switching > Policies, open a policy and, in the Log Action
list, select a log action for the policy.

1.
2. Citrix ADC
3. NetScaler 12.0

Verifying the configuration

November 2, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2032

NetScaler 12.0

To verify that your content switching configuration is correct, you need to view the content switching
entities. To verify proper operation after your content switching configuration has been deployed, you
can view the statistics that are generated as the servers are accessed.

Viewing the Properties of Content Switching Virtual Servers

You can view the properties of content switching virtual servers that you have configured on the
NetScaler appliance. You can use the information to verify whether the virtual server is correctly
configured and, if necessary, to troubleshoot. In addition to details such as name, IP address, and
port, you can view the various policies bound to a virtual server, and its traffic-management settings.

The content switching policies are displayed in the order of their priority. If more than one policy has
the same priority, they are shown in the order in which they are bound to the virtual server.

Note

If you have configured the content switching virtual server to forward traffic to a load balancing
virtual server, you can also view the content switching policies by viewing the properties of the
load balancing virtual server.

To view the properties of content switching virtual servers by using the command line interface

To list basic properties of all content switching virtual servers in your configuration, or detailed prop-
erties of a specific content switching virtual server, at the command prompt, type one of the following
commands:

• show cs vserver
• show cs vserver \<name\>

Example

1 1.
2 show cs vserver Vserver-CS-1
3 Vserver-CS-1 (10.102.29.161:80) - HTTP Type: CONTENT
4 State: UP
5 Last state change was at Thu Jun 30 10:48:59 2011
6 Time since last state change: 6 days, 20:03:00.760
7 Client Idle Timeout: 180 sec
8 Down state flush: ENABLED
9 Disable Primary Vserver On Down : DISABLED
10 Appflow logging: DISABLED
11 Port Rewrite : DISABLED
12 State Update: DISABLED

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2033

NetScaler 12.0

13 Default: Content Precedence: RULE

14 Vserver IP and Port insertion: OFF
15 Case Sensitivity: ON
16 Push: DISABLED Push VServer:
17 Push Label Rule: none
18
19 ...
20 1) Policy : __ESNS_PREBODY_POLICY Priority:0
21 2) Policy : __ESNS_POSTBODY_POLICY Priority:0
22
23 1) Compression Policy Name: __ESNS_CMP_POLICY Priority: 2147483647
24 GotoPriority Expression: END
25 Flowtype: REQUEST
26
27 2) Rewrite Policy Name: __ESNS_REWRITE_POLICY Priority: 2147483647
28 GotoPriority Expression: END
29 Flowtype: REQUEST
30
31 3) Cache Policy Name: dfbx Priority: 10
32 GotoPriority Expression: END
33 Flowtype: REQUEST
34
35 4) Responder Policy Name: __ESNS_RESPONDER_POLICY Priority: 2147483647
36 GotoPriority Expression: END
37
38 1) Policy: wiki Target: LBVIP2 Priority: 25 Hits: 0
39 2) Policy: plain Target: LBVIP1 Priority: 90 Hits: 0
40 3) Policy: DispOrderTest2 Target: KerbAuthLBVS Priority: 91 Hits: 0
41 4) Policy: test_Pol Target: LBVIP1 Priority: 92 Hits: 0
42 5) Policy: PolicyNameTesting Target: LBVIP1 Priority: 100 Hits: 0
43 Done
44 >
45
46 show cs vserver
47 1) Vserver-CS-1 (10.102.29.161:80) - HTTP Type: CONTENT
48 State: UP
49 …
50 Appflow logging: DISABLED
51 Port Rewrite : DISABLED
52 State Update: DISABLED
53
54 2) apubendpt (10.111.111.1:80) - HTTP Type: CONTENT
55 State: UP
56 …
57 Client Idle Timeout: 180 sec

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2034

NetScaler 12.0

58 Down state flush: DISABLED

59 …
60
61 3) apubendpt1 (10.111.111.2:80) - HTTP Type: CONTENT
62 State: UP
63 …
64 Disable Primary Vserver On Down : DISABLED
65 Appflow logging: DISABLED
66 Port Rewrite : DISABLED
67 State Update: DISABLED
68 …

Viewing Content Switching Policies

You can view the properties of the content switching policies that you defined, such as the name,
domain, and URL or expression, and use the information to find any mistakes in the configuration, or
to troubleshoot if something is not working as it should.

To view the properties of content switching policies by using the command line interface

To list either basic properties of all content switching policies in your configuration or detailed prop-
erties of a specific content switching policy, at the command prompt, type one of the following com-
mands:

• show cs policy
• show cs policy \<PolicyName\>

Example

1 show cs policy
2
3 show cs policy Policy-CS-1

To view the properties of content switching policies by using the configuration utility

Navigate to Traffic Management > Content Switching > Policies, select a policy and, in the Action
list, select Show Bindings.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2035

NetScaler 12.0

Viewing a Content Switching Virtual Server Configuration by Using the Visualizer

The Content Switching Visualizer is a tool that you can use to view a content switching configuration
in graphical format. You can use the visualizer to view the following configuration items:

• A summary of the load balancing virtual servers to which the content switching virtual server is
bound.
• All services and service groups that are bound to the load balancing virtual server and all moni-
tors that are bound to the services.
• The configuration details of any displayed element.
• Any policies bound to the content switching virtual server. These policies need not be content
switching policies. Many types of policies, such as Rewrite policies, can be bound to a content
switching virtual server.

After you configure the various elements in a content switching and load balancing setup, you can
export the entire configuration to an application template file.

Note

The Visualizer requires a graphical interface, so it is available only through the configuration util-
ity.

To view a content switching configuration by using the Visualizer in the configuration utility

1. Navigate to Traffic Management > Content Switching > Virtual Servers.

2. In the details pane, select the virtual server that you want to view, and then click Visualizer.
3. In the Content Switching Visualizer window, you can adjust the viewable area as follows:
• Click the Zoom In and Zoom Out icons to increase or decrease the viewable area.
• Click the Save Image icon to save the graph as an image file.
• In the Search in text field, begin typing the name of the item you are looking for. When you
have typed enough characters to identify the item, its location is highlighted. To restrict
the search, click the drop-down menu and select the type of element that you want to
search for.
4. To view configuration details for entities that are bound to this virtual server, you can do the
following:
• To view policies that are bound to the virtual server, in the tool bar at the top of the dialog
box select one or more feature-specific policy icons. If policy labels are configured, they
appear in the main view area.
• To view the configuration details for a bound service or service group, click the icon for the
service, click the Related Tasks tab, and then click Show Member Services.
• To view the configuration details for a monitor, click the icon for the monitor, click the
Related Tasks tab, and then click View Monitor.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2036

NetScaler 12.0

5. To view detailed statistics for any virtual server in the content switching configuration, click the
virtual server for which you want to view statistics, then click the Related Tasks tab, and then
click Statistics.
6. To view a comparative list of the parameters whose values either differ or are not defined across
service containers for a load balancing virtual server, click the icon for a container, click the
Related Tasks tab, and then click Service Attributes Diff.
7. To view monitor binding details for the services in a container, in the Service Attributes Diff di-
alog box, in the Group column for the container, click Details. This comparative list helps you
determine which service container has the configuration you want to apply to all the service
containers.
8. To view the number of requests received per second at a given point in time by the virtual servers
in the configuration, and the number of hits per second at a given point in time for rewrite,
responder, and cache policies, click Show Stats. The statistical information is displayed on the
respective nodes in the Visualizer. This information is not updated in real time. It has to be
refreshed manually. To refresh the information, click Refresh Stats.
Note: This option is available only on NetScaler appliance nCore builds.
9. To copy configuration details for an element to a document or spreadsheet, click the icon for
that element, click Related Tasks, click Copy Properties, and then paste the information into a
document.
10. To export the entire configuration that is displayed in the Visualizer to an application template
file, click the icon for the content switching virtual server, click Related Tasks, and then click
Create Template. When creating the application template, you can configure variables in some
policy expressions and actions. For more information about creating the application template
file and configuring variables for a template, see AppExpert.

1.
2. Citrix ADC
3. NetScaler 12.0

Customizing the basic content switching configuration

December 5, 2018

Contributed by:
C

After you configure a basic content switching setup, you might need to customize it to meet your re-
quirements. If your web servers are UNIX-based and rely on case sensitive pathnames, you can con-
figure case sensitivity for policy evaluation. You can also set precedence for evaluation of the content
switching policies that you configured. You can configure HTTP and SSL content switching virtual

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2037

NetScaler 12.0

servers to listen on multiple ports instead of creating separate virtual servers. If you want to config-
ure content switching for a specific a virtual LAN, you can configure a content switching virtual server
with a listen policy.

Configuring case sensitivity for policy evaluation

You can configure the content switching virtual server to treat URLs as case sensitive in URL-based
policies. When case sensitivity is configured, the NetScaler appliance considers case when evaluating
policies. For example, if case sensitivity is off, the URLs /a/1.htm and /A/1.HTM are treated as identical.
If case sensitivity is on, those URLs are treated as separate and can be switched to different targets.

To configure case sensitivity by using the command line interface

At the command prompt, type:

set cs vserver \<name\> -caseSensitive (ON|OFF)

Example:

1 set cs vserver Vserver-CS-1 -caseSensitive ON

To configure case sensitivity by using the configuration utility

1. Navigate to Traffic Management > Content Switching > Virtual Servers, and open a virtual
server.
2. In Advanced Settings, select Traffic Settings, and then select Case Sensitive.

Setting the precedence for policy evaluation

Precedence refers to the order in which policies that are bound to a virtual server are evaluated. You
do not normally have to configure precedence: the default precedence works correctly in many cases.
If you want to make sure that one policy or set of policies is applied first, however, and another policy
or set of policies is applied only if the first set does not match a request, you can configure either
URL-based precedence or rule-based precedence.

Precedence with URL-Based policies

If there are multiple matching URLs for the incoming request, the precedence (priority) for URL-based
policies is:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2038

NetScaler 12.0

1. Domain and exact URL

2. Domain, prefix, and suffix
3. Domain and suffix
4. Domain and prefix
5. Domain only
6. Exact URL
7. Prefix and suffix
8. Suffix only
9. Prefix only
10. Default

If you configure precedence based on URL, the request URL is compared to the configured URLs. If
none of the configured URLs match the request URL, then rule-based policies are checked. If the re-
quest URL does not match any rule-based policies, or if the content group selected for the request is
down, then the request is processed as follows:

• If you configure a default group for the content switching virtual server, then the request is for-
warded to the default group.
• If the configured default group is down or if no default group is configured, then an “HTTP 404
Not Found” error message is sent to the client.

Note

You should configure URL-based precedence if the content type (for example, images) is the same
for all clients. However, if different types of content must be served based on client attributes
(such as Accept-Language), you must use rule-based precedence.

Precedence with Rule-Based policies

If you configure precedence based on rules, which is the default setting, the request is tested on the
basis of the rule-based policies you have configured. If the request does not match any rule-based
policies, or if the content group selected for the incoming request is down, the request is processed
in the following manner:

• If a default group is configured for the content switching virtual server, the request is forwarded
to the default group.
• If the configured default group is down or if no default group is configured, an “HTTP 404 Not
Found” error message is sent to the client.

To configure precedence by using the command line interface

At the command prompt, type:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2039

NetScaler 12.0

set cs vserver \<name\> -precedence ( RULE | URL )

Example:

1 set cs vserver Vserver-CS-1 -precedence RULE

To configure precedence by using the configuration utility

1. Navigate to Traffic Management > Content Switching > Virtual Servers, and open a virtual
server.
2. In Advanced Settings, select Traffic Settings, and then specify Precedence.

Support for multiple ports for HTTP and SSL type content switching virtual servers

You can configure the NetScaler appliance so that HTTP and SSL content switching virtual servers
listen on multiple ports, without having to configure separate virtual servers. This feature is especially
useful if you want to base a content switching decision on a part of the URL and other L7 parameters.
Instead of configuring multiple virtual servers with the same IP address and different ports, you can
configure one IP address and specify the port as *. As a result, the configuration size is also reduced.

To configure an HTTP or SSL content switching virtual server to listen on multiple ports by
using the command line

At the command prompt, type:

add cs vserver <name> <serviceType> <IPAddress> Port *

Example

1 > add cs vserver cs1 HTTP 10.102.92.215 *

2 Done
3 > sh cs vserver cs1
4 cs1 (10.102.92.215:*) - HTTP Type: CONTENT
5 State: UP
6 Last state change was at Tue May 20 01:15:49 2014
7 Time since last state change: 0 days, 00:00:03.270
8 Client Idle Timeout: 180 sec
9 Down state flush: ENABLED
10 Disable Primary Vserver On Down : DISABLED
11 Appflow logging: ENABLED
12 Port Rewrite : DISABLED
13 State Update: DISABLED

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2040

NetScaler 12.0

14 Default: Content Precedence: RULE

15 Vserver IP and Port insertion: OFF
16 L2Conn: OFF Case Sensitivity: ON
17 Authentication: OFF
18 401 Based Authentication: OFF
19 Push: DISABLED Push VServer:
20 Push Label Rule: none
21 IcmpResponse: PASSIVE
22 RHIstate: PASSIVE
23 TD: 0
24 Done

To configure an HTTP or SSL content switching virtual server to listen on multiple ports by
using the configuration utility

1. Navigate to Traffic Management > Content Switching > Virtual Servers, and create a virtual
server of type HTTP or SSL.
2. Use an asterisk (*) to specify the port.

Configuring per-VLAN Wildcarded virtual servers

If you want to configure content switching for traffic on a specific virtual local area network (VLAN),
you can create a wildcarded virtual server with a listen policy that restricts it to processing traffic only
on the specified VLAN.

To configure a wildcarded virtual server that listens to a specific VLAN by using the command
line interface

At the command prompt, type:

• add cs vserver <name> <serviceType> IPAddress * Port * -listenpolicy <expression>

[-listenpriority <positive_integer>]

Example:

1 add cs vserver Vserver-CS-vlan1 ANY * *

2 -listenpolicy ”CLIENT.VLAN.ID.EQ(2)” -listenpriority 10

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2041

NetScaler 12.0

To configure a wildcarded virtual server that listens to a specific VLAN by using the
configuration utility

Navigate to Traffic Management > Content Switching > Virtual Servers, and configure a virtual
server. Specify a listen policy that restricts it to processing traffic only on the specified VLAN.

After you have created this virtual server, you bind it to one or more services as described in Binding
Services to the Virtual Server.

Configuring the Microsoft SQL server version setting

You can specify the version of Microsoft® SQL Server® for a content switching virtual server that is of
type MSSQL. The version setting is recommended if you expect some clients to not be running the
same version as your Microsoft SQL Server product. The version setting provides compatibility be-
tween the client-side and server-side connections by ensuring that all communication conforms to
the server’s version.

To set the Microsoft SQL Server version parameter by using the command line interface

At the command prompt, type the following commands to set the Microsoft SQL Server version pa-
rameter for a content switching virtual server and verify the configuration:

• set cs vserver \<name\> -mssqlServerVersion \<mssqlServerVersion\>

• show cs vserver \<name\>

Example

1 > set cs vserver myMSSQLcsvip -mssqlServerVersion 2008R2 Done > show cs

vserver myMSSQLcsvip myMSSQLcsvip (192.0.2.13:1433) - MSSQL Type:
CONTENT State: UP . . . . . . MSsql Server Version: 2008R2 . . . . .
. Done >

To set the Microsoft SQL server version parameter by using the configuration utility

1. Navigate to Traffic Management > Content Switching > Virtual Servers, configure a virtual
server and specify the protocol as MYSQL.
2. In Advanced Settings, select MySQL, and specify the Server Version.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2042

NetScaler 12.0

Content switching for diameter protocol

January 6, 2019
Contributed by:
C
For Diameter-protocol traffic, you can configure the NetScaler appliance (or virtual appliance) to act
as a relay agent that load balances and forwards a packet to the appropriate destination on the ba-
sis of the message content (AVP value in the message). Since the appliance does not perform any
application-level processing, it provides relaying services for all diameter applications as specified by
the configured content switching policies. Therefore, the appliance advertises the Relay Application
ID in the capability exchange answer (CEA) message when the client establishes a diameter connec-
tion. You must configure a content switching virtual server, load balancing virtual servers, and ser-
vices to represent the diameter nodes. When a request reaches the content switching virtual server,
the virtual server applies the content switching policies associated with that type of request. After
evaluating the policies, the content switching virtual server routes the request to the appropriate load
balancing virtual server, which sends it to the appropriate service.
A diameter interface provides a connection between the different diameter nodes. The following sam-
ple deployment uses Cx and Rx interfaces. A Cx interface provides a connection between a CSCF and
an HSS. An Rx interface provides a connection between a CSCF and a PCRF. All the messages reach the
NetScaler appliance. Depending on whether the message is for a Cx or an Rx interface, and on the con-
tent switching policies defined, the NetScaler appliance selects an appropriate load balancing server
pool.

Sample Configuration

1. For each entity, create a service, a load balancing server, and bind the service to the virtual
server.

1 add service svc_pcrf[1-3] 1.1.1.1[1-3] DIAMETER 3868

2 add service svc_hss[1-3] 1.1.1.2[1-3] DIAMETER 3868
3 add lb vserver vs_rx DIAMETER -persistenceType DIAMETER ‒
persistavpno 263
4 add lb vserver vs_cx DIAMETER -persistenceType DIAMETER ‒
persistavpno 263
5 bind lb vserver vs_rx svc_pcrf[1-3]
6 bind lb vserver vs_cx svc_hss[1-3]

2. Create a content switching virtual server and two actions (one for each load balancing virtual
server). Create two content switching policies and bind these policies to the content switching

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2043

NetScaler 12.0

virtual server, specifying a priority for each policy.

1 add
cs vserver cs_diameter DIAMETER 10.1.1.10 3868
2 add
cs action cx_action -targetLBVserver vs_cx
3 add
cs action rx_action ‒ targetLBvserver vs_rx
4 add
cs policy cx_policy -rule ”DIAMETER.REQ.AUTH_APPLICATION_ID.EQ
(16777216)” -action cx_action
5 add cs policy rx_policy -rule ”DIAMETER.REQ.AUTH_APPLICATION_ID.EQ
(16777236)” -action rx_action
6 bind cs vserver cs_diameter -policyName rx_policy -priority 100
7 bind cs vserver cs_diameter -policyName cx_policy -priority 110

1.
2. Citrix ADC
3. NetScaler 12.0

Protecting the content switching setup against failure

November 2, 2018
Contributed by:
C
Content switching may fail when the content switching virtual server goes DOWN or fails to handle
excessive traffic, or for other reasons. To reduce the chances of failure, you can take the following
measures to protect the content switching setup against failure:

Configuring a Backup Virtual Server

If the primary content switching virtual server is marked DOWN or DISABLED, the NetScaler appliance
can direct requests to a backup content switching virtual server. It can also send a notification mes-
sage to the client regarding the site outage or maintenance. The backup content switching virtual
server is a proxy and is transparent to the client.
When configuring the backup virtual server, you can specify the configuration parameter Disable Pri-
mary When Down to ensure that, when the primary virtual server comes back up, it remains the sec-
ondary until you manually force it to take over as the primary. This is useful if you want to ensure that
any updates to the database on the server for the backup are preserved, enabling you to synchronize
the databases before restoring the primary virtual server.
You can configure a backup content switching virtual server when you create a content switching
virtual server or when you change the optional parameters of an existing content switching virtual

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2044

NetScaler 12.0

server. You can also configure a backup content switching virtual server for an existing backup con-
tent switching virtual server, thus creating cascaded backup content switching virtual servers. The
maximum depth of cascaded backup content switching virtual servers is 10. The appliance searches
for a backup content switching virtual server that is up and accesses that content switching virtual
server to deliver the content.
Note: If a content switching virtual server is configured with both a backup content switching
virtual server and a redirect URL, the backup content switching virtual server takes precedence
over the redirect URL. The redirect is used when the primary and backup virtual servers are down.

To set up a backup content switching virtual server by using the command line interface

At the command prompt, type:

1 set cs vserver <name> -backupVserver <string> -disablePrimaryOnDown (ON

|OFF)

Example

1 set cs vserver Vserver-CS-1 -backupVserver Vserver-CS-2 -

disablePrimaryOnDown ON

To set up a backup content switching virtual server by using the configuration utility

1. Navigate to Traffic Management > Content Switching > Virtual Servers, configure a virtual server
and specify the protocol as MYSQL.
2. In Advanced Settings, select Protection, and specify a Backup Virtual Server.

Diverting Excess Traffic to a Backup Virtual Server

The spillover option diverts new connections arriving at a content switching virtual server to a backup
content switching virtual server when the number of connections to the content switching virtual
server exceeds the configured threshold value. The threshold value is dynamically calculated, or you
can set the value. The number of established connections (in case of TCP) at the virtual server is com-
pared with the threshold value. When the number of connections reaches the threshold, new connec-
tions are diverted to the backup content switching virtual server.

If the backup content switching virtual servers reach the configured threshold and are unable to take
the load, the primary content switching virtual server diverts all requests to the redirect URL. If a redi-

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2045

NetScaler 12.0

rect URL is not configured on the primary content switching virtual server, subsequent requests are
dropped.

To configure a content switching virtual server to divert new connections to a backup virtual
server by using the command line interface

At the command prompt, type:

1 set cs vserver \<name\> -soMethod \<methodType\> -soThreshold \<

thresholdValue\> -soPersistence \<persistenceValue\> -
soPersistenceTimeout \<timeoutValue\>

Example

1 set cs vserver Vserver-CS-1 -soMethod Connection -soThreshold 1000 -

soPersistence enabled -soPersistenceTimeout 2

To set a content switching virtual server to divert new connections to a backup virtual server
by using the configuration utility

1. Navigate to Traffic Management > Content Switching > Virtual Servers, configure a virtual server
and specify the protocol as MYSQL.
2. In Advanced Settings, select Protection, and configure spillover.

Configuring a Redirection URL

You can configure a redirect URL to communicate the status of the NetScaler appliance in the event
that a content switching virtual server of type HTTP or HTTPS is DOWN or DISABLED. This URL can be
local or remote.

Redirect URLs can be absolute URLs or relative URLs. If the configured redirect URL contains an abso-
lute URL, the HTTP redirect is sent to the configured location, regardless of the URL specified in the
incoming HTTP request. If the configured redirect URL contains only the domain name (relative URL),
the HTTP redirect is sent to a location after appending the incoming URL to the domain configured in
the redirect URL.

Citrix recommends using an absolute URL. That is, a URL ending in /, for example www.example.com/
instead of a relative URL. A relative URL redirection might result in the vulnerability scanner reporting
a false positive.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2046

NetScaler 12.0

Note: If a content switching virtual server is configured with both a backup virtual server and a redirect
URL, the backup virtual server takes precedence over the redirect URL. A redirect URL is used when
the primary and backup virtual servers are down.

When redirection is configured and the content switching virtual server is unavailable, the appliance
issues an HTTP 302 redirect to the user’s browser.

To configure a redirect URL for when the content switching virtual server is unavailable by
using the command line interface

At the command prompt, type:

1 set cs vserver \<name\> -redirectURL \<URLValue\>

Example

1 set cs vserver Vserver-CS-1 -redirectURL http://www.newdomain.com/

mysite/maintenance

To configure a redirect URL for when the content switching virtual server is unavailable by
using the configuration utility

1. Navigate to Traffic Management > Content Switching > Virtual Servers, configure a virtual server
and specify the protocol as MYSQL.
2. In Advanced Settings, select Protection, and specify a Redirect URL.

Configuring the State Update Option

The content switching feature enables the distribution of client requests across multiple servers on
the basis of the specific content presented to the users. For efficient content switching, the content
switching virtual server distributes the traffic to the load balancing virtual servers according to the
content type, and the load balancing virtual servers distribute the traffic to the physical servers ac-
cording to the specified load balancing method.

For smooth traffic management, it is important for the content switching virtual server to know the sta-
tus of the load balancing virtual servers. The state update option helps to mark the content switching
virtual server DOWN if the load balancing virtual server bound to it is marked DOWN. A load balancing
virtual server is marked DOWN if all the physical servers bound to it are marked DOWN.

When State Update is disabled:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2047

NetScaler 12.0

The status of the content switching virtual server is marked as UP. It remains UP even if there is no
bound load balancing virtual server that is UP.

When State Update is enabled:

When you add a new content switching virtual server, initially, its status is shown as DOWN. When
you bind a load balancing virtual server whose status is UP, the status of the content switching virtual
server becomes UP.

If more than one load balancing virtual server is bound and if one of them is specified as the default,
the status of the content switching virtual server reflects the status of the default load balancing virtual
server.

If more than one load balancing virtual server is bound without any of them being specified as the
default, the status of the content switching virtual server is marked UP only if all the bound load bal-
ancing virtual servers are UP.

To configure the state update option by using the command line interface

At the command prompt, type:

1 add cs vserver \<name\> \<protocol\> \<ipAddress\> \<port\> -

stateUpdate ENABLED

Example

1 add cs vserver csw_vserver HTTP 10.18.250.154 80 -stateupdate ENABLED

-cltTimeout 180

To configure the state update option by using the configuration utility

1. Navigate to Traffic Management > Content Switching > Virtual Servers, configure a virtual server
and specify the protocol as MYSQL.
2. In Advanced Settings, select Traffic Settings, and then select State Update.

Flushing the Surge Queue

When a physical server receives a surge of requests, it becomes slow to respond to the clients that
are currently connected to it, which leaves users dissatisfied and disgruntled. Often, the overload
also causes clients to receive error pages. To avoid such overloads, the NetScaler appliance provides

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2048

NetScaler 12.0

features such as surge protection, which controls the rate at which new connections to a service can
be established.

The appliance does connection multiplexing between clients and physical servers. When it receives a
client request to access a service on a server, the appliance looks for an already established connection
to the server that is free. If it finds a free connection, it uses that connection to establish a virtual
link between the client and the server. If it does not find an existing free connection, the appliance
establishes a new connection with the server, and establishes a virtual link between client and the
server. However, if the appliance cannot establish a new connection with the server, it sends the client
request to a surge queue. If all the physical servers bound to the load balancing or content switching
virtual server reach the upper limit on client connections (max client value, surge protection threshold
or maximum capacity of the service), the appliance cannot establish a connection with any server. The
surge protection feature uses the surge queue to regulate the speed at which connections are opened
with the physical servers. The appliance maintains a different surge queue for each service bound to
the virtual server.

The length of a surge queue increases whenever a request comes for which the appliance cannot es-
tablish a connection, and the length decreases whenever a request in the queue gets sent to the server
or a request gets timed out and is removed from the queue.

If the surge queue for a service or service group becomes too long, you may want to flush it. You can
flush the surge queue of a specific service or service group, or of all the services and service groups
bound to a load balancing virtual server. Flushing a surge queue does not affect the existing connec-
tions. Only the requests present in the surge queue get deleted. For those requests, the client has to
make a fresh request.

You can also flush the surge queue of a content switching virtual server. If a content switching virtual
server forwards some requests to a particular load balancing virtual server, and the load balancing vir-
tual server also receives some other requests, when you flush the surge queue of the content switch-
ing virtual server, only the requests received from this content switching virtual server are flushed;
the other requests in the surge queue of the load balancing virtual server are not flushed.

Note: You cannot flush the surge queues of cache redirection, authentication, VPN or GSLB vir-
tual servers or GSLB services.
Do not use the Surge Protection feature if Use Source IP (USIP) is enabled.

To flush a surge queue by using the command line interface

The flush ns surgeQ command works in the following manner:

• You can specify the name of a service, service group, or virtual server whose surge queue has to
be flushed.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2049

NetScaler 12.0

• If you specify a name while executing the command, surge queue of the specified entity will be
flushed. If more than one entity has the same name, the appliance flushes surge queues of all
those entities.
• If you specify the name of a service group, and a server name and port while executing the com-
mand, the appliance flushes the surge queue of only the specified service group member.
• You cannot directly specify a service group member (<serverName> and <port>) without
specifying the name of the service group (<name>) and you cannot specify <port> without a
<serverName>. Specify the <serverName> and <port> if you want to flush the surge queue for
a specific service group member.
• If you execute the command without specifying any names, the appliance flushes the surge
queues of all the entities present on the appliance.
• If a service group member is identified with a server name, you must specify the server name in
this command; you cannot specify its IP address.

At the command prompt, type:

1 flush ns surgeQ [-name <name>] [-serverName <serverName> <port>].

Examples

1 1. flush ns surgeQ ‒ name SVC1ANZGB ‒ serverName 10.10.10.1 80

2 The above command flushes the surge queue of the service or virtual
server that is named SVC1ANZGB and has IP address as 10.10.10
3
4 2. flush ns surgeQ
5 The above command flushes all the surge queues on the appliance.

To flush a surge queue by using the configuration utility

Navigate to Traffic Management > Content Switching > Virtual Servers, select a virtual server and, in
the Action list, select Flush Surge Queue.

1.
2. Citrix ADC
3. NetScaler 12.0

Managing a content switching setup

January 6, 2019

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2050

NetScaler 12.0

Contributed by:
C

After a content switching setup is configured, it may require periodic changes. When operating sys-
tems or software are updated, or hardware wears out and is replaced, you may need to take down
your setup. Load on your setup may increase, requiring additional resources. You may also modify
the configuration to improve performance.

These tasks may require unbinding policies from the content switching virtual server, or disabling or
removing content switching virtual servers. After you have made changes to your setup, you may need
to re-enable servers and rebind policies. You might also want to rename your virtual servers.

Unbinding Policies from the Content Switching Virtual Server

When you unbind a content switching policy from its virtual server, the virtual server no longer in-
cludes that policy when determining where to direct requests.

To unbind a policy from a content switching virtual server by using the command line interface

At the command prompt, type:

unbind cs vserver <name> -policyname <string>

Example:

1 unbind cs vserver Vserver-CS-1 -policyname Policy-CS-1

To unbind a policy from a content switching virtual server by using the configuration utility

1. Navigate to Traffic Management > Content Switching > Virtual Servers, and open the virtual
server.
2. Click in the Policies section, select the policy, and click Unbind.

Removing Content Switching Virtual Servers

You normally remove a content switching virtual server only when you no longer require the virtual
server. When you remove a content switching virtual server, the NetScaler appliance first unbinds all
policies from the content switching virtual server, and then removes it.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2051

NetScaler 12.0

To remove a content switching virtual server by using the command line interface

At the command prompt, type:

rm cs vserver <name>

Example:

1 rm cs vserver Vserver-CS-1

To remove a content switching virtual server by using the configuration utility

Navigate to Traffic Management > Content Switching > Virtual Servers, select a virtual server, and
click Delete.

Disabling and Re-Enabling Content Switching Virtual Servers

Content switching virtual servers are enabled by default when you create them. You can disable a
content switching virtual server for maintenance. If you disable the content switching virtual server,
the state of the content switching virtual server changes to Out of Service. While out of service, the
content switching virtual server does not respond to requests.

To disable or re-enable a virtual server by using the command line interface

At the command prompt, type one of the following commands:

• disable cs vserver <name>

• enable cs vserver <name>

Example:

1 disable cs vserver Vserver-CS-1

2
3 enable cs vserver Vserver-CS-1

To disable or re-enable a virtual server by using the configuration utility

Navigate to Traffic Management > Content Switching > Virtual Servers, select a virtual server and,
in the Action list, select Enable or Disable.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2052

NetScaler 12.0

Renaming Content Switching Virtual Servers

You can rename a content switching virtual server without unbinding it. The new name is propagated
automatically to all affected parts of the NetScaler appliance configuration.

To rename a virtual server by using the command line interface

At the command prompt, type:

rename cs vserver <name> <newName>

Example:

1 rename cs vserver Vserver-CS-1 Vserver-CS-2

To rename a virtual server by using the configuration utility

Navigate to Traffic Management > Content Switching > Virtual Servers, select a virtual server and,
in the Action list, select Rename.

Managing Content Switching Policies

You can modify an existing policy by configuring rules or changing the URL of the policy, or you can
remove a policy. You can also rename an existing advanced content switching policy. You can create
different policies based on the URL. URL-based policies can be of different types, as described in the
following table.

For more information, see Examples of URL-Based Policies pdf.

Note

You can configure rule-based content switching using classical policy expressions or advanced
policy expressions.

To modify, remove, or rename a policy by using the command line interface

At the command prompt, type one of the following commands:

• set cs policy <policyName> [-domain <domainValue>] [-rule <ruleValue>]

[-url <URLValue>]
• rm cs policy <policyName>
• rename cs policy <policyName> <newPolicyName>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2053

NetScaler 12.0

Example:

1 set cs policy Policy-CS-1 -domain ”www.domainxyz.com”

2
3 set cs policy Policy-CS-1 -rule ”CLIENT.IP.SRC.SUBNET(22).EQ
(10.100.148.0)”
4
5 set cs policy Policy-CS-2 -rule ”SYS.TIME.BETWEEN(GMT 2010 Jun,GMT 2010
Jul)”
6
7 set cs policy Policy-CS-1 -url /sports/*
8
9 rename cs policy Policy-CS-1 Policy-CS-11
10
11 rm cs policy Policy-CS-1

To modify, remove, or rename a policy by using the configuration utility

1. Navigate to Traffic Management > Content Switching > Policies.

2. Select the policy, and either delete it, edit it or, in the Action list, click Rename.
1.
2. Citrix ADC
3. NetScaler 12.0

Managing client connections

November 2, 2018
Contributed by:
C
To ensure efficient management of client connections, you can configure the content switching virtual
servers on the NetScaler appliance.
• Configuring the ICMP Response. You can configure the NetScaler appliance to send ICMP re-
sponses to PING requests according to your settings. On the IP address corresponding to the
virtual server, set the ICMP RESPONSE to VSVR_CNTRLD, and on the virtual server, set the ICMP
VSERVER RESPONSE.
The following settings can be made on a virtual server:
– When you set ICMP VSERVER RESPONSE to PASSIVE on all virtual servers, the NetScaler
appliance always responds.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2054

NetScaler 12.0

– When you set ICMP VSERVER RESPONSE to ACTIVE on all virtual servers, the NetScaler ap-
pliance responds even if one virtual server is UP.
– When you set ICMP VSERVER RESPONSE to ACTIVE on some and PASSIVE on others,
NetScaler appliance responds even if one virtual server set to ACTIVE is UP.

Redirecting Client Requests to a Cache

The NetScaler appliance cache redirection feature redirects HTTP requests to a cache. You can signif-
icantly reduce the burden of responding to HTTP requests and improve your Web site performance
through proper implementation of the cache redirection feature.

A cache stores frequently requested HTTP content. When you configure cache redirection on a virtual
server, the NetScaler appliance sends cacheable HTTP requests to the cache and non-cacheable HTTP
requests to the origin Web server. For more information on cache redirection, see “Cache Redirection.”

To configure cache redirection on a virtual server by using the command line interface

At the command prompt, type:

set cs vserver <name> -cacheable <Value>

Example

1 set cs vserver Vserver-CS-1 -cacheable yes

To configure cache redirection on a virtual server by using the configuration utility

1. Navigate to Traffic Management > Content Switching > Virtual Servers, and open a virtual server.
2. In Advanced Settings, select Traffic Settings, and select Cacheable.

Enabling Delayed Cleanup of Virtual Server Connections

Under certain conditions, you can configure the down state flush setting to terminate existing con-
nections when a service or a virtual server is marked DOWN. Terminating existing connections frees
resources and in certain cases speeds recovery of overloaded load balancing setups.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2055

NetScaler 12.0

To configure the down state flush setting on a virtual server by using the command line
interface

At the command prompt, type:

set cs vserver <name> -downStateFlush <Value>

Example

1 set cs vserver Vserver-CS-1 -downStateFlush enabled

To configure the down state flush setting on a virtual server by using the configuration utility

1. Navigate to Traffic Management > Content Switching > Virtual Servers, and open a virtual server.
2. In Advanced Settings, select Traffic Settings, and then select Down State Flush.

Rewriting Ports and Protocols for Redirection

Virtual servers and the services that are bound to them may use different ports. When a service re-
sponds to an HTTP connection with a redirect, you may need to configure the NetScaler appliance to
modify the port and the protocol to ensure that the redirection goes through successfully. You do this
by enabling and configuring the redirectPortRewrite setting.

To configure HTTP redirection on a virtual server by using the command line interface

At the command prompt, type:

set cs vserver <name> -redirectPortRewrite <Value>

Example

1 set cs vserver Vserver-CS-1 -redirectPortRewrite enabled

To configure HTTP redirection on a virtual server by using the configuration utility

1. Navigate to Traffic Management > Content Switching > Virtual Servers, and open a virtual server.
2. In Advanced Settings, select Traffic Settings, and select Rewrite.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2056

NetScaler 12.0

Inserting the IP Address and Port of a Virtual Server in the Request Header

If you have multiple virtual servers that communicate with different applications on the same service,
you must configure the NetScaler appliance to add the IP address and port number of the appropri-
ate virtual server to the HTTP requests that are sent to that service. This setting allows applications
running on the service to identify the virtual server that sent the request.

If the primary virtual server is down and the backup virtual server is up, the configuration settings
of the backup virtual server are added to the client requests. If you want the same header tag to be
added, regardless of whether the requests are from the primary virtual server or backup virtual server,
you must configure the required header tag on both virtual servers.

Note: This option is not supported for wildcarded virtual servers or dummy virtual servers.

To insert the IP address and port of the virtual server in the client requests by using the
command line interface

At the command prompt, type:

set cs vserver <name> -insertVserverIPPort <vServerIPPORT>

Example

1 set cs vserver Vserver-CS-1 -insertVserverIPPort 10.201.25.136:80

To insert the IP address and port of the virtual server in the client requests by using the
configuration utility

1. Navigate to Traffic Management > Content Switching > Virtual Servers, and open a virtual server.
2. In Advanced Settings, select Traffic Settings and, in the Virtual Server IP Port Insertion list, select
VIPADDR or V6TOV4MAPPING, and specify a port header in Virtual Server IP Port Insertion Value.

Setting a Time-out Value for Idle Client Connections

You can configure a virtual server to terminate any idle client connections after a configured time-out
period elapses. When you configure this setting, the NetScaler appliance waits for the time you specify
and, if the client is idle after that time, it closes the client connection.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2057

NetScaler 12.0

To set a time-out value for idle client connections by using the command line interface

At the command prompt, type:

set cs vserver <name> -cltTimeout <Value>

Example

1 set cs vserver Vserver-CS-1 -cltTimeout 100

To set a time-out value for idle client connections by using the configuration utility

1. Navigate to Traffic Management > Content Switching > Virtual Servers, and open a virtual server.
2. In Advanced Settings, select Traffic Settings, and specify a Client Idle Time-Out value.

Identifying Connections with the 4-tuple and Layer 2 Connection Parameters

You can now set the L2Conn option for a content switching virtual server. With the L2Conn option set,
connections to the content switching virtual server are identified by the combination of the 4-tuple
(<source IP>:<source port>::<destination IP>:<destination port>) and Layer 2 connection parameters.
The Layer 2 connection parameters are the MAC address, VLAN ID, and channel ID.

To set the L2Conn option for a content switching virtual server by using the command line
interface

At the command line, type the following commands to configure the L2Conn parameter for a content
switching virtual server and verify the configuration:

set cs vserver <name> -l2Conn (ON OFF)

• show cs vserver <name>

Example

1 > set cs vserver mycsvserver -l2Conn ON

2 Done
3 > show cs vserver mycsvserver

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2058

NetScaler 12.0

4 mycsvserver (192.0.2.56:80) - HTTP Type: CONTENT

5 State: UP
6 . . .
7 . . .
8 L2Conn: ON Case Sensitivity: ON
9 . . .
10 . . .
11 Done
12 >

To set the L2Conn option for a content switching virtual server by using the configuration utility

1. Navigate to Traffic Management > Content Switching > Virtual Servers, and open a virtual server.
2. In Advanced Settings, select Traffic Settings, and then select Layer 2 Parameters.

1.
2. Citrix ADC
3. NetScaler 12.0

Troubleshooting

September 19, 2018

Contributed by:
C

If the content switching feature does not work as expected after you have configured it, you can use
some common tools to access NetScaler appliance resources and diagnose the problem.

Resources for Troubleshooting Content Switching

For best results, use the following resources to troubleshoot a content switching issue on a NetScaler
appliance:

• Configuration file
• Relevant newnslog file
• Trace files
• Network topology diagram for the network setup of the customer
• Citrix documentation, such as release notes, Knowledge Center articles, and eDocs

In addition to the above resources, the following tools expedite troubleshooting:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2059

NetScaler 12.0

• The iehttpheaders or a similar utility

• The Wireshark application customized for the NetScaler appliance trace files
• An SSH utility for command line access
• A HyperTerminal utility to access the console

Troubleshooting Content Switching Issues

The most common content switching issues involve the content switching feature not working at all,
or working only intermittently, and Service Unavailable responses.
• Issue
The content switching feature is not functioning.
Resolution
Check the configuration as follows:
– Verify that the appliance is licensed for content switching.
– Verify that the feature is enabled.
– From the configuration file, verify that valid content switching policies are correctly bound
to the load balancing virtual servers.
• Issue
Client receives a 503 - Service Unavailable response.
Resolution
– Verify the URL and policy bindings. The client receives the 503 response when none of the
policies you have configured is evaluated and no default load balancing virtual server is
defined and bound to the content switching virtual server.
– From the configuration, verify the policies and URL being accessed by the client.
– Verify that for every type of request the respective policy is evaluated. If the policy is not
evaluated, check the policy expression and update it if necessary.
– Verify the URL and HTTP request and response headers. To do so, record an HTTPHeader
trace and, if necessary, record the packet traces on the appliance and the client.
• Issue
Intermittently, the content switching feature is not working as expected.
Resolution
– Study the network topology diagram, if available, of the setup to understand the various
devices installed between the client and the server(s).
– Verify the configuration and policy bindings. Make sure that the URL in the policy expres-
sion matches to the one in the client request.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2060

NetScaler 12.0

– Verify that appropriate priorities are assigned to the policies. An incorrect precedence or
priority assigned to a policy can cause a problem.

– Run the following commands to verify the bindings and the values of the policy hit coun-
ters in the output of the commands:

show cs vserver <CS VServer>

show cs policy <CS Policy>

stat cs vserver <CS VServer>

– Using iehttpheaders or a similar utility, determine whether the HTTP headers for the re-
quests or responses provide any pointers to the issue.

– Check the release notes and Knowledge Center articles.

– If the issue is still not resolved, contact Citrix Technical Support with appropriate data for
further investigation.

1.
2. Citrix ADC
3. NetScaler 12.0

DataStream

January 6, 2019

Contributed by:
C

The NetScaler DataStream feature provides an intelligent mechanism for request switching at the
database layer by distributing requests based on the SQL query being sent.

When deployed in front of database servers, a NetScaler appliance ensures optimal distribution of
traffic from the application servers and Web servers. Administrators can segment traffic according to
information in the SQL query and on the basis of database names, usernames, character sets, and
packet size.

You can either configure load balancing to switch requests based on load balancing algorithms or
elaborate the switching criteria by configuring content switching to make a decision based on an SQL
query parameters. You can further configure monitors to track the state of database servers.

Note: NetScaler DataStream is supported only for MySQL and MS SQL databases. For information
about the supported protocol version, character sets, special queries, and transactions, see DataS-
tream Reference.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2061

NetScaler 12.0

How DataStream Works

In DataStream, the ADC appliance is placed in-line between the application and/or Web servers and
the database servers. On the appliance, the database servers are represented by services.

A typical DataStream deployment consists of the entities described in the following diagram.

Figure 1. DataStream Entity Model

As shown in this figure, a DataStream configuration can consist of an optional content switching vir-
tual server (CS), a load balancing setup consisting of load balancing virtual servers (LB1 and LB2) and
services (Svc1, Svc2, Svc3, and Svc4), and content switching policies (optional).

The clients (application or Web servers) send requests to the IP address of a content switching virtual
server (CS) configured on the NetScaler appliance. The appliance, then, authenticates the clients us-
ing the database user credentials configured on the appliance. The content switching virtual server
(CS) applies the associated content switching policies to the requests. After evaluating the policies,
the content switching virtual server (CS) routes the requests to the appropriate load balancing virtual
server (LB1 or LB2), which, then, distributes the requests to the appropriate database servers (repre-
sented by services on the appliance) based on the load balancing algorithm. The NetScaler appliance
uses the same database user credentials to authenticate the connection with the database server.

If a content switching virtual server is not configured on the appliance, the clients (application or Web
servers) send their requests to the IP address of a load balancing virtual server configured on the
appliance. The NetScaler appliance authenticates the client by using the database user credentials
configured on the appliance, and then uses the same credentials to authenticate the connection with
the database server. The load balancing virtual server distributes the requests to the database servers
according to the load balancing algorithm. The most effective load balancing algorithm for database
switching is the least connection method.

DataStream uses connection multiplexing to enable multiple client-side requests to be made over the
same server-side connection. The following connection properties are considered:

• User name
• Database name
• Packet size
• Character set

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2062

NetScaler 12.0

Configuring Database Users

December 21, 2018

Contributed by:
C

In databases, a connection is always stateful, which means that as soon as a connection is established,
it must be authenticated.

You need to configure your database user name and password on the NetScaler appliance. For exam-
ple, if you have a user John configured on the database, you need to configure the user John on the
ADC too. When you add the database user names and passwords on the ADC, these are added to the
nsconfig file.
Note

Names are case sensitive.

The ADC uses these user credentials to authenticate the clients, and then authenticate the server con-
nections with the database servers.

To add a database user by using the command line interface

At the command prompt, type

add db user <username> - password <password>

Example:

1 add db user nsdbuser -password dd260427edf

To add a database user by using the configuration utility

Navigate to System > User Administration > Database Users, and configure a database user.

If you have changed the password of the database user on the database server, you must reset the
password of the corresponding user configured on the ADC appliance.

To reset the password of a database user by using the command line interface

At the command prompt, type

1 set db user <username> -password <password>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2063

NetScaler 12.0

Example:

1 set db user nsdbuser -password dd260538abs

To reset the password of database users by using the configuration utility

Navigate to System > User Administration > Database Users, select a user, and enter new values for
the password.

If a database user no longer exists on the database server, you can remove the user from the ADC
appliance. However, if the user continues to exist on the database server and you remove the user
from the ADC appliance, any request from the client with this user name does not get authenticated,
and therefore, does not get routed to the database server.

To remove a database user by using the command line interface

At the command prompt, type

1 rm db user <username>

Example:

1 rm db user nsdbuser

To remove a database user by using the configuration utility

Navigate to System > User Administration > Database Users, select a user, and click Delete.

1.
2. Citrix ADC
3. NetScaler 12.0

Configuring a Database Profile

December 21, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2064

NetScaler 12.0

A database profile is a named collection of parameters that is configured once but applied to multiple
virtual servers that require those particular parameter settings. After creating a database profile, you
bind it to load balancing or content switching virtual servers. You can create as many profiles as you
need.

To create a database profile by using the command line interface

At the command line, type the following commands to create a database profile and verify the config-
uration:

1 add db dbProfile <name> [-interpretQuery ( YES | NO )] [-stickiness (

YES | NO )] [-kcdAccount <string>]
2
3 show db dbProfile

Example:

1 > add dbProfile myDBProfile -interpretQuery YES -stickiness YES -

kcdAccount mykcdaccnt
2 Done
3 > show dbProfile myDBProfile
4 Name: myDBProfile
5 Interpret Query: YES
6 Stickyness: YES
7 KCD Account: mykcdaccnt
8 Reference count: 0
9
10 Done
11 >

To create a database profile by using the configuration utility

Navigate to System > Profiles and, on the Database Profiles tab, configure a database profile.

To bind a database profile to a load balancing or content switching virtual server by

using the command line interface

At the command line, type:

1 set (lb | cs) vserver <name> -dbProfileName <string>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2065

NetScaler 12.0

To bind a database profile to a load balancing or content switching virtual server by

using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Virtual Servers or Traffic Management
> Content Switching > Virtual Servers, and open a virtual server.
2. In Advanced Settings, select Profiles and, in the DB Profile list, select a profile to bind to the
virtual server. To create a new profile, click plus (+).

1.
2. Citrix ADC
3. NetScaler 12.0

Configuring Load Balancing for DataStream

January 14, 2019

Contributed by:
C

Before configuring a load balancing setup, you must enable the load balancing feature. Then, begin
by creating at least one service for each database server in the load balancing group. With the services
configured, you are ready to create a load balancing virtual server and bind the services to the virtual
server.
Note:

For databases, the load balancing can only occur on homogenous database servers (database
servers that contain the exact same databases). For a configuration that contains unique
databases on different servers, you must use content switching. If some of your database
servers host identical content, you can use load balancing on those servers only. You can
then use content switching policies to send requests to the load balancing virtual server that
manages load balancing for those databases.

The NetScaler appliance currently stores the database name and login information during the
database session. When a query is made to the database, it uses that information to connect to
the specific database server.

Parameter values specific to DataStream

• Protocol

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2066

NetScaler 12.0

Use the
MYSQL protocol type for MySQL databases and
MSSQL protocol type for MS SQL databases while configuring virtual servers and services. The
MySQL and TDS protocols are used by the clients to communicate with the respective database
servers by using SQL queries. For information about the MySQL protocol, see
http://dev.mysql.com/doc/internals/en/client-server-protocol.html. For information about
the TDS protocol, see
http://msdn.microsoft.com/en-us/library/dd304523(v=prot.13).aspx.

• Port

Port on which the virtual server listens for client connections. Use port 3306 for MySQL database
servers.

• Method

It is recommended that you use the Least Connection method for better load balancing and
lower server load. However, other methods, such as Round Robin, Least Response Time, Source
IP Hash, Source IP Destination IP Hash, Least Bandwidth, Least Packets, and Source IP Source
Port Hash, are also supported.
Note: URL Hash method is not supported for DataStream.

• MS SQL Server Version

If you are using the Microsoft SQL Server, and you expect some clients to not be running the
same version as your Microsoft SQL Server product, set the
Server Version parameter for the load balancing virtual server. The version setting provides
compatibility between the client-side and server-side connections by ensuring that all commu-
nication conforms to the server’s version. For more information about setting the
Server Version parameter, see
Configuring the MySQL and Microsoft SQL server version setting.

• MySQL Server Version

If you are using the MySQL Server, and you expect some clients to not be running the same
version as your MySQL Server product, set the Server Version parameter for the load balancing
virtual server. The version setting provides compatibility between the client-side and server-
side connections by ensuring that all communication conforms to the server’s version. For more
information about setting the
Server Version parameter, see
Configuring the MySQL and Microsoft SQL server version setting.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2067

NetScaler 12.0

Configuring Content Switching for DataStream

January 14, 2019

Contributed by:
C

You can segment traffic according to information in the SQL query, on the basis of database names,
user names, character sets, and packet size.

You can configure content switching policies with default syntax expressions to switch content based
on connection properties, such as user name and database name, command parameters, and the SQL
query to select the server.

The default syntax expressions evaluate traffic associated with MYSQL and MS SQL database servers.
You can use request-based expressions in default syntax policies to make request switching decisions
at the content switching virtual server bind point and response-based expressions (expressions that
begin with MYSQL.RES) to evaluate server responses to user-configured health monitors.

For information about default syntax expressions, see

Default Syntax Expressions: DataStream.

Note:

For databases, the load balancing can only occur on homogenous database servers (database
servers that contain the exact same databases). For a configuration that contains unique
databases on different servers, you must use content switching. If some of your database
servers host identical content, you can use load balancing on those servers only. You can
then use content switching policies to send requests to the load balancing virtual server that
manages load balancing for those databases.

The NetScaler appliance currently stores the database name and login information during the
database session. When a query is made to the database, it uses that information to connect to
the specific database server.

Parameter values specific to DataStream

• Protocol

Use the
MYSQL protocol type for MySQL databases and
MSSQL protocol type for MS SQL databases while configuring virtual servers and services. The
MySQL and TDS protocols are used by the clients to communicate with the respective database
servers by using SQL queries. For information about the MySQL protocol, see

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2068

NetScaler 12.0

http://dev.mysql.com/doc/internals/en/client-server-protocol.html. For information about

the TDS protocol, see
http://msdn.microsoft.com/en-us/library/dd304523(v=prot.13).aspx.
• Port
Port on which the virtual server listens for client connections. Use port 3306 for MySQL database
servers.
• MS SQL Server Version
If you are using Microsoft SQL Server, and you expect some clients to not be running the same
version as your Microsoft SQL Server product, set the
Server Version parameter for the content switching virtual server. The version setting provides
compatibility between the client-side and server-side connections by ensuring that all commu-
nication conforms to the server’s version. For more information about setting the
Server Version parameter, see
Configuring the Microsoft SQL Server Version Setting.
1.
2. Citrix ADC
3. NetScaler 12.0

Configuring Monitors for DataStream

December 21, 2018

Contributed by:
C
To track the state of each load balanced database server in real time, you need to bind a monitor to
each service. The monitor is configured to test the service by sending periodic probes to the service.
(This is sometimes referred to as performing a health check.) If the monitor receives a timely response
to its probes, it marks the service as UP. If it does not receive a timely response to the designated
number of probes, it marks the service as DOWN.
For DataStream, you need to use the built-in monitors, MYSQL-ECV and MSSQL-ECV. This monitor pro-
vides the ability to send an SQL request and parse the response for a string.
Before configuring monitors for DataStream, you must add database user credentials to your
NetScaler appliance. For information about configuring monitors, see Configure monitors in a load
balancing setup.
When you create a monitor, a TCP connection is established with the database server, and the connec-
tion is authenticated by using the user name provided while creating the monitor. You can then run

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2069

NetScaler 12.0

an SQL query to the database server and evaluate the server response to check whether it matches
the configured rule.

The following examples are for MYSQL servers.

Examples:

In the following example, the value of the error message is evaluated to determine the state of the
server.

1 add lb monitor lb_mon1 MYSQL-ECV -sqlQuery ”select * from

2 table2;” -evalrule ”mysql.res.error.message.contains(”Invalid
3 User”)”-database ”NS” -userName ”user1”

In the following example, the number of rows in the response is evaluated to determine the state of
the server.

1 add lb monitor lb_mon4 MYSQL-ECV -sqlQuery ”select * from

2 table4;” -evalrule ”mysql.res.atleast_rows_count(7)” -database ”NS” -
userName ”user2”

In the following example, the value of a particular column is evaluated to determine the state of the
server.

1 add lb monitor lb_mon3 MYSQL-ECV

2 -sqlQuery ”select * from ABC;” -evalrule ”mysql.res.row(1).double_elem
(2) == 345.12”
3 -database ”NS” -userName ”user3”

The following examples are for MSSQL servers.

Examples:

In the following example, the value of the error message is evaluated to determine the state of the
server.

1 add lb monitor lb_mon1 MSSQL-ECV -sqlQuery ”select * from

2 table2;” -evalrule ”mssql.res.error.message.contains(”Invalid
3 User”)”-database ”NS” -userName ”user1”

In the following example, the number of rows in the response is evaluated to determine the state of
the server.

1 add lb monitor lb_mon4 MSSQL-ECV -sqlQuery ”select * from

2 table4;” -evalrule ”mssql.res.atleast_rows_count(7)” -database ”NS” -
userName ”user2”

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2070

NetScaler 12.0

In the following example, the value of a particular column is evaluated to determine the state of the
server.

1 add lb monitor lb_mon3 MSSQL-ECV

2 -sqlQuery ”select * from ABC;” -evalrule ”mssql.res.row(1).double_elem
(2) == 345.12”
3 -database ”NS” -userName ”user3”

1.
2. Citrix ADC
3. NetScaler 12.0

Use Case 1: Configuring DataStream for a Master/Slave Database

Architecture

January 6, 2019
Contributed by:
C
A commonly used deployment scenario is the master/slave database architecture where the master
database replicates all information to the slave databases.
For master/slave database architecture, you may want all WRITE requests to be sent to the master
database and all READ requests to the slave databases.
The following figure shows the entities and the values of the parameters you need to configure on the
appliance.
Figure 1. DataStream Entity Model for Master/Slave Database Setup
In this example scenario, a service (Svc_mysql_1) is created to represent the master database and is
bound to a load balancing virtual server (Lb_vsr_mysql_master). Three more services (Svc_mysql_2,
Svc_mysql_3, and Svc_mysql_4) are created to represent the three slave databases, and they are
bound to another load balancing virtual server (Lb_vsr_mysql_slave).
A content switching virtual server (Cs_vsr_mysql_1) is configured with associated policies to send all
WRITE requests to the load balancing virtual server, Lb_vsr_mysql_master, and all READ requests to
the load balancing virtual server, Lb_vsr_mysql_slave.
When a request reaches the content switching virtual server, the virtual server applies the associated
content switching policies to that request. After evaluating the policies, the content switching virtual
server routes the request to the appropriate load balancing virtual server, which sends it to the appro-
priate service.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2071

NetScaler 12.0

The following table lists the names and values of the entities and the policy configured on the
NetScaler appliance.

Entity Type Name IP Address Protocol Port Expression

Services Svc_mysql_1 10.102.29.5 MYSQL 3306 NA

Svc_mysql_2 10.102.29.6 MYSQL 3306 NA
Svc_mysql_3 10.102.29.7 MYSQL 3306 NA
Svc_mysql_4 10.102.29.8 MYSQL 3306 NA
Load Lb_vsr_mysql_master
10.102.29.201 MYSQL 3306 NA
balancing
virtual
servers
Lb_vsr_mysql_slave
10.102.29.202 MYSQL 3306 NA
Content Cs_vsr_mysql_1 10.102.29.161 MYSQL 3306 NA
switching
virtual server
Content Cs_select NA NA NA “MYSQL.REQ.QUERY.COMMA
switching
policy

Table 1. Entity and Policy Names and Values

To configure DataStream for a master/slave database setup by using the command line
interface

At the command prompt, type

1 add service Svc_mysql_1 10.102.29.5 mysql 3306

2
3 add service Svc_mysql_2 10.102.29.6 mysql 3306
4
5 add service Svc_mysql_3 10.102.29.7 mysql 3306
6
7 add service Svc_mysql_4 10.102.29.8 mysql 3306
8
9 add lb vserver Lb_vsr_mysql_master mysql 10.102.29.201 3306
10
11 add lb vserver Lb_vsr_mysql_slave mysql 10.102.29.202 3306

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2072

NetScaler 12.0

12
13 bind lb vserver Lb_vsr_mysql_master svc_mysql_1
14
15 bind lb vserver Lb_vsr_mysql_slave svc_mysql_2
16
17 bind lb vserver Lb_vsr_mysql_slave svc_mysql_3
18
19 bind lb vserver Lb_vsr_mysql_slave svc_mysql_4
20
21 add cs vserver Cs_vsr_mysql_1 mysql 10.102.29.161 3306
22
23 add cs policy Cs_select ‒ rule ”MYSQL.REQ.QUERY.COMMAND.contains(”
select”)”
24
25 bind cs vserver Cs_vsr_mysql_1 Lb_vsr_mysql_master
26
27 bind cs vserver Cs_vsr_mysql_1 Lb_vsr_mysql_slave ‒ policy Cs_select ‒
priority 10

1.
2. Citrix ADC
3. NetScaler 12.0

Use Case 2: Configuring the Token Method of Load Balancing for

DataStream

January 6, 2019

Contributed by:
C

You can configure the token method of load balancing for DataStream to base the selection of
database servers on the value of the token extracted from the client (application or web server)
requests. These tokens are defined by using SQL expressions. For subsequent requests with the
same token, the Citrix ADC appliance sends the requests to the same database server that handled
the initial request. Requests with the same token are sent to the same database server until the
maximum connection limit is reached or the session entry has aged out.

You can use the following sample SQL expressions to define tokens:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2073

NetScaler 12.0

MySQL MS SQL

MYSQL.REQ.QUERY.TEXT MSSQL.REQ.QUERY.TEXT
MYSQL.REQ.QUERY.TEXT(n) MSSQL. REQ.QUERY.TEXT(n)
MYSQL.REQ.QUERY.COMMAND MSSQL.REQ.QUERY.COMMAND
MYSQL.CLIENT.USER MSSQL.CLIENT.USER
MYSQL.CLIENT.DATABASE MSSQL.CLIENT.DATABASE
MYSQL.CLIENT.CAPABILITIES

The following example shows how the Citrix ADC DataStream feature works when you configure the
token method of load balancing.

Figure 1. How DataStream Works with the Token Method of Load Balancing

In this example, the token is the name of the database. A request with token books is sent to Database
Server1 and a request with token music is sent to Database Server2. All subsequent requests with
token books are sent to Database Server1 and requests with token music are sent to Database Server2.
This configuration provides pseudo persistence with the database servers.

To configure this example by using the command line interface

At the command prompt, type:

1 add service Service1 192.0.2.9 MYSQL 3306

2
3 add service Service2 192.0.2.11 MYSQL 3306
4
5 add lb vserver token_lb_vserver MYSQL 192.0.2.15 3306 -lbmethod token -
rule MYSQL.CLIENT.DATABASE
6
7 bind lb vserver token_lb_vserver Service1
8
9 bind lb vserver token_lb_vserver Service2

To configure this example by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Virtual Servers, configure a virtual server
and specify the protocol as MYSQL.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2074

NetScaler 12.0

2. Click in the Service section, and configure two services specifying the protocol as MYSQL. Bind
these services to the virtual server.
3. In Advanced Settings, click Method and, in the Load Balancing Method list, select TOKEN and
specify the expression as MYSQL.CLIENT.DATABASE.

1.
2. Citrix ADC
3. NetScaler 12.0

Use Case 3: Logging MSSQL Transactions in Transparent Mode

December 21, 2018

Contributed by:
C

You can configure the Citrix ADC appliance to operate transparently between MSSQL clients and
servers, and to only log or analyze details of all client-server transactions. Transparent mode is de-
signed so that the Citrix ADC appliance only forwards MSSQL requests to the server, and then relays
the server’s responses to the clients. As the requests and responses pass through the appliance,
the appliance logs information gathered from them, as specified by the audit logging or AppFlow
configuration, or collects statistics, as specified by the Action Analytics configuration. You do not
have to add database users to the appliance.

When operating in transparent mode, the Citrix ADC appliance does not perform load balancing, con-
tent switching, or connection multiplexing for the requests. However, it responds to a client’s pre-
login packet on behalf of the server so that it can prevent encryption from being agreed upon during
the pre-login handshake. The login packet and subsequent packets are forwarded to the server.

Summary of Configuration Tasks

For logging or analyzing MSSQL requests in transparent mode, you have to do the following:

• Configure the Citrix ADC appliance as the default gateway for both clients and servers.
• Do one of the following on the Citrix ADC appliance:
– If you can configure the use source IP address (USIP) option globally, create a load bal-
ancing virtual server with a wildcard IP address and the port number on which the MSSQL
servers listen for requests (a port-specific wildcard virtual server). Then, enable the USIP
option globally. If you configure a port-specific wildcard virtual server, you do not have to
create MSSQL services on the appliance. The appliance discovers the services on the basis
of the destination IP address in the client requests.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2075

NetScaler 12.0

– If you do not want to configure the USIP option globally, create MSSQL services with
the USIP option enabled on each of them. If you configure services, you do not have to
create a port-specific wildcard virtual server.
• Configure audit logging, AppFlow, or Action Analytics to log or collect statistics about the re-
quests. If you configure a virtual server, you can bind your policies either to the virtual server
or to the global bind point. If you do not configure a virtual server, you can bind your policies
to only the global bind point.

Configuring Transparent Mode by Using a Wildcard Virtual Server

You can configure transparent mode by configuring a port-specific wildcard virtual server and en-
abling Use Source IP (USIP) mode globally. When a client sends its default gateway (the Citrix ADC
appliance) a request with the IP address of an MSSQL server in the destination IP address header, the
appliance checks whether the destination IP address is available. If the IP address is available, the
virtual server forwards the request to the server. Otherwise, it drops the request.

To create a wildcard virtual server by using the command line

At the command prompt, type the following commands to create a wildcard virtual server and verify
the configuration:

1 add lb vserver <name> <serviceType> <IPAddress> <port>

2
3 show lb vserver <name>

Example:

1 > add lb vserver wildcardLbVs MSSQL * 1433

2 Done
3 > show lb vserver wildcardLbVs
4 wildcardLbVs (*:1433) - MSSQL Type: ADDRESS
5 State: UP
6 . . .
7
8 Done
9 >

To create a wildcard virtual server by using the GUI

Navigate to Traffic Management > Load Balancing > Virtual Servers, and create a virtual server. Specify
MSSQL as the protocol and * as the IP address.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2076

NetScaler 12.0

To enable Use Source IP (USIP) mode globally by using the CLI

At the command prompt, type the following commands to enable USIP mode globally and verify the
configuration:

1 enable ns mode USIP

2
3 show ns mode

Example:

1 > enable ns mode USIP

2 Done
3 > show ns mode
4
5 Mode Acronym
Status
6 ------- -------
------
7 . . .
8 3) Use Source IP USIP ON
9 . . .
10 Done
11 >

To enable USIP mode globally by using the GUI

1. Navigate to System > Settings and, in Modes and Features, select Configure Modes.
2. Select Use Source IP.

Configuring Transparent Mode by Using MSSQL Services

You can configure transparent mode by configuring MSSQL services and enabling USIP on each ser-
vice. When a client sends its default gateway (the Citrix ADC appliance) a request with the IP address
of an MSSQL server in the destination IP address header, the appliance forwards the request to the
destination server.

To create an MSSQL service and enable USIP mode on the service by using the command line
interface

At the command prompt, type the following commands to create an MSSQL service, with USIP en-
abled, and verify the configuration:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2077

NetScaler 12.0

1 add service <name> (<IP> | <serverName>) <serviceType> <port> -usip YES

‘
2
3 show service <name>

Example

1 > add service myDBservice 192.0.2.0 MSSQL 1433 -usip YES

2 Done
3 > show service myDBservice
4 myDBservice (192.0.2.0:1433) - MSSQL
5 State: UP
6 . . .
7 Use Source IP: YES Use Proxy Port: YES
8 . . .
9 Done
10 >

To create an MSSQL service, with USIP enabled, by using the GUI

1. Navigate to Traffic Management > Load Balancing > Services, and configure a service.
2. Specify protocol as MSSQL and, in Settings, select Use Source IP.

1.
2. Citrix ADC
3. NetScaler 12.0

Use Case 4: Database Specific Load Balancing

January 6, 2019

Contributed by:
C

A database server farm should be load balanced not only on the basis of the states of the servers,
but also on the basis of the availability of the database on each server. A service might be up, and a
load balancing device might show it as being in the UP state, but the requested database might be
unavailable on that service. If a query is forwarded to a service on which the database is unavailable,
the request is not served. Therefore, a load balancing device must be aware of the availability of a

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2078

NetScaler 12.0

database on each service and, when making a load balancing decision, it must consider only those
services on which the database is available.
As an example, consider that database servers server1, server2, and server3 host databases my-
database1 and mydatabase2. If mydatabase1 becomes unavailable on server2, the load balancing
device must be aware of that change in state, and it must load balance requests for mydatabase1
across only server1 and server3. After mydatabase1 becomes available on server2, the load balancing
device must include server2 in load balancing decisions. Similarly, if mydatabase2 becomes unavail-
able on server3, the device must load balance requests for mydatabase2 across only server1 and
server2, and it must include server3 in its load balancing decisions only when mydatabase2 becomes
available. This load balancing behavior must be consistent across all the databases that are hosted
on the server farm.
The Citrix ADC appliance implements this behavior by retrieving a list of all the databases that are
active on a service. To retrieve the list of active databases, the appliance uses a monitor that is con-
figured with an appropriate SQL query. If the requested database is unavailable on a service, the ap-
pliance excludes the service from load balancing decisions until it becomes available. This behavior
ensures uninterrupted service to clients.
Note

Database specific load balancing is currently supported for only MSSQL and MySQL service types.
This support is also available for Microsoft SQL Server 2012 high availability deployment.

To set up database specific load balancing, you must enable the load balancing feature, configure a
load balancing virtual server of type MSSQL or MySQL, configure the services that host the database,
and bind the services to the virtual server. The monitor needs valid user credentials to log on to the
database server, so you must configure a database user account on each of the servers and then add
the user account to the Citrix ADC appliance. Then, you configure an MSSQL-ECV or MYSQL-ECV mon-
itor and bind the monitor to each service. Finally, you must test the configuration to ensure that it is
working as intended. Before you perform these configuration tasks, make sure you understand how
database specific load balancing works.

How Database Specific Load Balancing Works

For database specific load balancing, you configure a monitor that periodically queries each database
server for the names of all the active databases on it. The Citrix ADC appliance stores the results, and
regularly updates the records on the basis of the information retrieved through monitoring. When
a client queries a particular database, the appliance uses the configured load balancing method to
select a service, and then checks its records to determine whether the database is available on that
service. If the records indicate that the database is not available, it uses the configured load balancing
method to select the next available service, and then repeats the check. The appliance forwards the
query to the first available service on which the database is active.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2079

NetScaler 12.0

Enabling Load Balancing

You can configure load balancing entities such as services and virtual servers when the load balancing
feature is disabled, but they will not function until you enable the feature.

To enable load balancing by using the command line interface

At the command prompt, type the following command to enable load balancing and verify the config-
uration:

1 enable ns feature LB
2
3 show ns feature

Example:

1 > enable ns feature LoadBalancing

2 Done
3 > show ns feature
4
5 Feature Acronym Status
6 ------- ------- ------
7 1) Web Logging WL OFF
8 2) Surge Protection SP ON
9 3) Load Balancing LB ON
10 .
11 .
12 .
13 24) NetScaler Push push OFF
14 Done

To enable load balancing by using the configuration utility

Navigate to System > Settings and, in Configure Basic Features, select Load Balancing.

Configuring a Load Balancing Virtual Server for Database Specific Load Balancing

To configure a virtual server to load balance databases on the basis of availability, you enable the
database specific load balancing parameter on the virtual server. Enabling the parameter modifies
the load balancing logic so that the Citrix ADC appliance refers the results of the monitoring probe
sent to the selected service, before forwarding the query to that service.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2080

NetScaler 12.0

To configure a load balancing virtual server for database specific load balancing

At the command prompt, type the following command to configure a load balancing virtual server for
database specific load balancing and verify the configuration:

1 add lb vserver <name> <serviceType> <ipAddress> <port> -dbsLb ENABLED

2
3 show lb vserver <name>

Configuring Services

After you enable the load balancing feature, you must create at least one service for each application
server that is to be included in your load balancing setup. The services that you configure provide
the connections between the Citrix ADC appliance and the load balanced servers. Each service has a
name and specifies an IP address, a port, and the type of data that is served.

If you create a service without first creating a server object, the IP address of the service is also the
name of the server that hosts the service. If you prefer to identify servers by name rather than IP
address, you can create server objects and then specify a server’s name instead of its IP address when
you create a service.

Configuring Database Users

In databases, a connection is always stateful, which means that as soon as a connection is established,
it must be authenticated.

You need to configure your database user name and password on the Citrix ADC. For example, if you
have a user John configured on the database, you need to configure the user John on the ADC too.
When you add the database user names and passwords on the ADC, these are added to the nsconfig
file.
Note

Names are case sensitive.

The ADC uses these user credentials to authenticate the clients, and then authenticate the server con-
nections with the database servers.

To add a database user by using the command line interface

At the command prompt, type

1 add db user <username> - password <password>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2081

NetScaler 12.0

Example:

1 add db user nsdbuser -password dd260427edf

To add a database user by using the configuration utility

Navigate to System > User Administration > Database Users, and configure a database user.

If you have changed the password of the database user on the database server, you must reset the
password of the corresponding user configured on the Citrix ADC appliance.

To reset the password of a database user by using the command line interface

At the command prompt, type

1 set db user <username> -password <password>

Example:

1 set db user nsdbuser -password dd260538abs

To reset the password of database users by using the configuration utility

Navigate to System > User Administration > Database Users, select a user, and enter new values for
the password.

If a database user no longer exists on the database server, you can remove the user from the Citrix ADC
appliance. However, if the user continues to exist on the database server and you remove the user
from the ADC appliance, any request from the client with this user name does not get authenticated,
and therefore, does not get routed to the database server.

To remove a database user by using the command line interface

At the command prompt, type

1 rm db user <username>

Example:

1 rm db user nsdbuser

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2082

NetScaler 12.0

To remove a database user by using the configuration utility

Navigate to System > User Administration > Database Users, select a user, and click Delete.

Configuring a Monitor to Retrieve the Names of Active Databases

To retrieve a list of all the active databases on a database instance, you create a monitor that logs on
to the database server by using a valid user credentials and runs an appropriate SQL query. The SQL
query you need to use depends on your SQL server deployment. For example, in an MSSQL database
mirroring setup, you can use the following query to retrieve a list of active databases available on a
server instance.

1 select name from sys.databases where state=0

In a MySQL database setup you can use the following queries to retrieve a list of active databases
available on a server instance.

show databases:

You also configure the monitor to evaluate the response for an error condition, and to store the results
if there is no error. If the response contains an error, the monitor marks the service as DOWN, and the
appliance excludes the service from load balancing decisions until an error is no longer returned.

Note

The database specific load balancing feature is supported only for the MSSQL and MySQL service
types. Therefore, the monitor type must be MSSQL-ECV or MYSQL-ECV.

To configure a monitor to retrieve the names of all the active databases hosted on a service by
using the command line

At the command prompt, type the following commands to retrieve the names of all the active
databases hosted on a service and verify the configuration:

1 add lb monitor <monitorName> <type> -userName <string> -sqlQuery <text>

-evalRule <expression> -storedb ENABLED
2
3 show lb monitor <monitorName>

To configure a monitor to retrieve the names of all the active databases hosted on a service by
using the configuration utility

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2083

NetScaler 12.0

1. Navigate to Traffic Management > Load Balancing > Monitors and configure a monitor of type
MSSQL-ECV or MYSQL-ECV.
2. In Special Parameters, specify a user name, query, and a rule
For example, for MSSQL-ECV, the query should be “select name from sys.databases where
state=0”), and a rule should be MSSQL.RES.TYPE.NE(ERROR).
For MSSQL-ECV, the query should be “show databases” and a rule should be MYSQL.RES.TYPE.NE(ERROR).

Availability Groups Deployment Support for MSSQL

Consider the following scenario in which database specific load balancing is configured in a high avail-
ability group deployment. S1 through S5 are the services on the ADC appliance. DB1 through DB4 are
the databases on the servers represented by the services S1 through S5. AV1 and AV2 are the avail-
ability groups. Each availability group contains up to one primary database server instance and up
to four secondary database server instances. A service, representing the servers in the availability
group, can be primary for one availability group and secondary for another availability group. Each
availability group contains different databases and one listener, which is a service. All requests arrive
on the listener service that resides on the primary database. AVI contains databases DB1 and DB2.
AV2 contains databases DB3 and DB4. L1 and L2 are the listeners on AV1 and AV2 respectively. S1 is the
primary service for AV1 and S2 is the primary service for AV2.

Service List of Active Databases on the Service

S1 DB1, DB2, DB3, DB4

S2 DB3, DB4
S3 DB3, DB4
S4 DB1, DB2
S5 DB1, DB2

Services representing the

Availability Group Databases Servers in Availability Group

AV1 DB1, DB2 S1, S4, S5

AV2 DB3, DB4 S1, S2, S3

Queries flow as follows:

1. A READ query for AV1 is load balanced between S4 and S5. S1 is the primary for AV1.
2. A WRITE query for AV1 is directed to L1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2084

NetScaler 12.0

3. A READ query for AV2 is load balanced between S1 and S3. S2 is the primary for AV2.
4. A WRITE query for AV1 is directed to L2.

Sample Configuration

1. Configure load balancing and content switching virtual servers.

• add lb vserver lbwrite -dbslb enabled
• add lbvserver lbread MSSQL -dbslb enabled
• add csvserver csv MSSQL 1.1.1.10 1433
2. Configure two listener services, one for each availability group, and five services S1 through S5
representing databases DB1 through DB4.
• add service L1 1.1.1.11 MSSQL 1433
• add service L2 1.1.1.12 MSSQL 1433
• add service s1 1.1.1.13 MSSQL 1433
• add service s2 1.1.1.14 MSSQL 1433
• add service s3 1.1.1.15 MSSQL 1433
• add service s4 1.1.1.16 MSSQL 1433
• add service s5 1.1.1.17 MSSQL 1433
3. Bind the services to the load balancing virtual servers.
• bind lbvserver lbwrite L1
• bind lbvserver lbwrite L2
• bind lbvserver lbread s1
• bind lbvserver lbread s2
• bind lbvserver lbread s3
• bind lbvserver lbread s4
• bind lbvserver lbread s5
4. Configure database users.
• add db user nsdbuser1 -password dd260427edf
• add db user nsdbuser2 -password ccd1234xyzw
5. Configure two monitors, monitor_L1 and monitor_L2 for each listener service, to retrieve the
list of active databases in that availability group. Add a monitor, monitor1 to retrieve the list of
databases for the secondary database server instance.
• add lb monitor monitor_L1 MSSQL-ECV -userName user1 -sqlQuery “SELECT name
FROM sys.databases a INNER JOIN sys.dm_hadr_availability_replica_states b ON
a.replica_id=b.replica_id INNER JOIN sys.availability_group_listeners c on b.group_id
= c.group_id INNER JOIN sys.availability_group_listener_ip_addresses d on c.listener_id =
d.listener_id WHERE b.role = 1 and d.ip_address like ‘1.1.1.11”’ -evalRule “MSSQL.RES.TYPE.NE(ERROR)”
–storedb ENABLED
• add lb monitor monitor_L2 MSSQL-ECV -userNameuser1 -sqlQuery “SELECT name

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2085

NetScaler 12.0

FROM sys.databases a INNER JOIN sys.dm_hadr_availability_replicca_states b ON

a.replica_id=b.replica_id INNER JOIN sys.availability_group_listeners c on b.group_id
= c.group_id INNER JOIN sys.availability_group_listener_ip_addresses d on c.listener_id =
d.listener_id WHERE b.role = 1 and d.ip_address like ‘1.1.1.12”’ -evalRule “MSSQL.RES.TYPE.NE(ERROR)”
-storedb ENABLED
• add lb monitor monitor1 MSSQL-ECV -userNameuser1 -sqlQuery “SELECT name
FROM sys.databases a INNER JOIN sys.dm_hadr_availability_replica_states b ON
a.replica_id=b.replica_id WHERE b.role = 2” -evalRule “MSSQL.RES.TYPE.NE(ERROR)”
-storedb ENABLED
6. Configure read and write policies.
• add cs policy pol_write -rule “MSSQL.REQ.QUERY.TEXT.CONTAINS(“insert”)”
• add cs policy pol_read -rule “MSSQL.REQ.QUERY.TEXT.CONTAINS(“select”)”
7. Bind the policies to the content switching virtual server.
• bind csvserver csv -targetLBVserver lbwrite -policyName pol_write -priority 11
• bind csvserver csv -targetLBVserver lbread -policyName pol_read -priority 12
8. Bind monitors to the services. Bind monitors to services L1 and L2 to get the list of active
databases for the availability group for which it is the listener. Bind monitors to all the services
that are bound to the read-only virtual server.
• bind service L1 -monitorName monitor_L1
• bind service L2 -monitorName monitor_L2
• bind service s1 -monitorName monitor1
• bind service s2 -monitorName monitor1
• bind service s3 -monitorName monitor1
• bind service s4 -monitorName monitor1
• bind service s5 -monitorName monitor1

Configuration examples for MSSQL virtual server

To configure a load balancing virtual server for database specific load balancing:

1 add lb vserver DBSpecificLB1 MSSQL 192.0.2.10 1433 -dbsLb ENABLED

2
3 Done
4
5 show lb vserver DBSpecificLB1
6
7 DBSpecificLB1 (192.0.2.10:1433) - MSSQL Type: ADDRESS
8 . . .
9 DBS_LB: ENABLED
10
11 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2086

NetScaler 12.0

To configure services:

add service msservice1 5.5.5.5 MSSQL 1433

To configure a monitor to retrieve the names of all the active databases hosted on a service by
using the command line:

1 add lb monitor mssql-monitor1 MSSQL-ECV -userName user1 -sqlQuery ”

select name from sys.databases where state=0” -evalRule ”MSSQL.RES.
TYPE.NE(ERROR)” -storedb EN
2
3 Done
4
5 show lb monitor mssql-monitor1
6
7 1)   Name.......: mssql-monitor1    Type......: MSSQL-ECV
8
9 ...
10
11 Special parameters: Database.....:””
12
13 User name.....:”user1”
14
15 Query..:select name from sys.databases where state=0 EvalRule...:MSSQL.
RES.TYPE.NE(ERROR)
16
17 Version...:70 STORE_DB...:ENABLED
18
19 Done

Configuration examples for MySQL virtual server

To configure a load balancing virtual server for database specific load balancing:

1 add lb vserver DBSpecificLB1 MYSQL 192.0.2.10 3306 -dbsLb ENABLED

2
3 Done
4
5 show lb vserver DBSpecificLB1
6
7 DBSpecificLB1 (192.0.2.10:3306) - MYSQL Type: ADDRESS
8
9 . . .
10
11 DBS_LB: ENABLED

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2087

NetScaler 12.0

12
13 Done

To configure services:

1 add service msservice1 5.5.5.5 MYSQL 3306

To configure a monitor to retrieve the names of all the active databases hosted on a service by
using the command line:

1 add lb monitor mysql-monitor1 MYSQL-ECV -userName user1 -sqlQuery ”show

databases” -evalRule ”MYSQL.RES.TYPE.NE(ERROR)” -storedb ENABLED
2
3 Done
4
5 show lb monitor mysql-monitor1
6
7 1)     Name.......: mysql-monitor1  Type......: MYSQL-ECV  State....:
 ENABLED
8
9 ...
10
11 Special parameters: Database.....:””
12
13 User name.....:”user1” Query..:show databases
14
15 EvalRule...:MYSQL.RES.TYPE.NE(ERROR) STORE_DB...:ENABLED
16
17 Done

1.
2. Citrix ADC
3. NetScaler 12.0

DataStream Reference

December 21, 2018

Contributed by:
C

This reference describes the MySQL and TDS protocols, the database versions, the authentication

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2088

NetScaler 12.0

methods, and the character sets supported by the DataStream feature. It also describes how the Citrix
ADC handles transaction requests and special queries that modify the state of a connection.

You can also configure the Citrix ADC appliance to generate audit log messages for the DataStream
feature.

Supported Database Versions, Protocols, and Authentication Methods

MySQL Database MS SQL Database

Database Versions MySQL database versions 4.1, MS SQL database versions

5.0, 5.1, 5.4, 5.5, and 5.6. 2000, 2000SP1, 2005, 2008,
2008R2, and 2012.
Protocols MySQL protocol version 10. Tabular Data Stream (TDS)
For information about the protocol version 7.1 and
MySQL protocol, see MySQL higher. For information about
Client/Server Protocol the TDS protocol, see Tabular
Data Stream Protocol
Authentication Methods MySQL native authentication SQL server authentication
is supported. and Windows Authentication
(Kerberos/NTLM) are
supported.

Character Sets

The DataStream feature supports only the UTF-8 charset.

The character set used by the client while sending a request may be different from the character set
used in the database server responses. Although the charset parameter is set during the connection
establishment, it can be changed at any time by sending an SQL query. The character set is asso-
ciated with a connection, and therefore, requests on connections with one character set cannot be
multiplexed onto a connection with a different character set.

The Citrix ADC appliance parses the queries sent by the client and the responses sent by the database
server.

The character set associated with a connection can be changed after the initial handshake by using
the following two queries:

1 SET NAMES <charset> COLLATION <collation>

2

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2089

NetScaler 12.0

3 SET CHARACTER SET <charset>

Transactions

In MySQL, transactions are identified by using the connection parameter AUTOCOMMIT or the BE-
GIN:COMMIT queries. The AUTOCOMMIT parameter can be set during the initial handshake, or after
the connection is established by using the query SET AUTOCOMMIT.

The Citrix ADC appliance explicitly parses each and every query to determine the beginning and end
of a transaction.

In MySQL protocol, the response contains two flags to indicate whether the connection is a transac-
tion, the TRANSACTION and AUTOCOMMIT flags.

If the connection is a transaction, the TRANSACTION flag is set. Or, if the AutoCommit mode is OFF, the
AUTOCOMMIT flag is not set. The ADC appliance parses the response, and if either the TRANSACTION
flag is set or the AUTOCOMMIT flag is not set, it does not do connection multiplexing. When these
conditions are no longer true, the ADC appliance begins connection multiplexing.

Note

Transactions are also supported for MS SQL.

Special Queries

There are special queries, such as SET and PREPARE, that modify the state of the connection and may
break request switching, and therefore, these need to be handled differently.

On receiving a request with special queries, the Citrix ADC appliance sends an OK response to the
client and additionally, stores the request in the connection.

When a non-special query, such as INSERT and SELECT, is received along with a stored query, the Citrix
ADC appliance first, looks for the server-side connection on which the stored query has already been
sent to the database server. If no such connections exist, the ADC appliance creates a new connection,
and sends the stored query first, and then, sends the request with the non-special query.

In case of SET, USE db, and INIT_DB special queries, the appliance modifies a field in the server side
connection corresponding to the special query. This results in better reuse of the server side connec-
tion.

Only 16 queries are stored in each connection.

The following is a list of the special queries for which the ADC appliance has a modified behavior.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2090

NetScaler 12.0

• SET query

The SET SQL queries define variables that are associated with the connection. These queries
are also used to define global variables, but as of now, the ADC appliance is unable to differen-
tiate between local and global variables. For this query, the ADC appliance uses the ‘store and
forward’ mechanism.

• USE <db> query

Using this query, the user can change the database associated with a connection. In this case,
the ADC appliance parses the <db> value sent and modifies a field in the server side connection
to reflect the new database to be used.

• INIT_DB command

Using this query, the user can change the database associated with a connection. In this case,
ADC appliance parses the value sent and modifies a field in the server side connection to reflect
the new database to be used.

• COM_PREPARE

The ADC appliance stops request switching on receiving this command.

• PREPARE query

This query is used to create prepared statements that are associated with a connection. For this
query, the ADC appliance uses the ‘store and forward’ mechanism.

Audit Log Message Support

You can now configure the Citrix ADC appliance to generate audit log messages for the DataStream
feature. Audit log messages are generated when client-side and server-side connections are estab-
lished, closed, or dropped. The categories of messages that you can log and view are ERROR and
INFO. Error messages for client-side connections begin with “CS” and error messages for server-side
connections begin with “SS.” Additional information is provided where necessary. For example, log
messages for closed connections (CS_CONN_CLOSED) include only the connection ID. However, log
messages for established connections (CS_CONN_ESTD) include information such as the user name,
database name, and the client IP address in addition to the connection ID.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2091

NetScaler 12.0

Domain Name System

January 6, 2019

Contributed by:
C

You can configure the NetScaler appliance to function as an authoritative domain name server (ADNS
server) for a domain. You can add the DNS resource records that belong to the domain for which
the appliance is authoritative and configure resource record parameters. You can also configure the
NetScaler appliance as a proxy DNS server that load balances a farm of DNS name servers that are ei-
ther within your network or outside your network. You can configure the appliance as an end resolver
and forwarder. You can configure DNS suffixes that enable name resolution when fully qualified do-
main names are not configured. The appliance also supports the DNS ANY query that retrieves all the
records that belong to a domain.

You can configure the NetScaler appliance to concurrently function as an authoritative DNS server for
one domain and a DNS proxy server for another domain. When you configure the NetScaler appliance
as the authoritative DNS server or DNS proxy server for a zone, you can enable the appliance to use
the Transmission Control Protocol (TCP) for response sizes that exceed the size limit specified for the
User Datagram Protocol (UDP).

How DNS Works on the NetScaler

You can configure the NetScaler appliance to function as an ADNS server, DNS proxy server, end re-
solver, and forwarder. You can add DNS resource records on the NetScaler appliance, including ser-
vice (SRV) records, IPv6 (AAAA) records, address (A) records, mail exchange (MX) records, canonical
name (CNAME) records, pointer (PTR) records, start of authority (SOA) records, and text (TXT) records.
Also, you can configure the NetScaler to load balance external DNS name servers.

The NetScaler appliance can be configured as the authority for a domain. To do this, you add valid
SOA and NS records for the domain.

An ADNS server is a DNS server that contains complete information about a zone.

To configure the NetScaler appliance as an ADNS server for a zone, you must add an ADNS service,
and then configure the zone. To do so, you add valid SOA and NS records for the domain. When a
client sends a DNS request, the NetScaler appliance searches the configured resource records for the
domain name. You can configure the ADNS service to be used with the NetScaler Global Server Load
Balancing (GSLB) feature.

You can delegate a subdomain, by adding NS records for the subdomain to the zone of the parent do-
main. You can then make the NetScaler authoritative for the subdomain, by adding a “glue record” for

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2092

NetScaler 12.0

each of the subdomain name servers. If GSLB is configured, theNetScaler makes a GSLB load balanc-
ing decision based on its configuration and replies with the IP address of the selected virtual server.
The following figure shows the entities in an ADNS GSLB setup and a DNS proxy setup.

Figure 1. DNS Proxy Entity Model

The NetScaler appliance can function as a DNS proxy. Caching of DNS records, which is an important
function of a DNS proxy, is enabled by default on the NetScaler appliance. This enables the NetScaler
appliance to provide quick responses for repeated translations. You must also create a load balancing
DNS virtual server, and DNS services, and then bind these services to the virtual server.

The NetScaler provides two options, minimum time to live (TTL) and maximum TTL for configuring
the lifetime of the cached data. The cached data times out as specified by your settings for these
two options. The NetScaler checks the TTL of the DNS record coming from the server. If the TTL is
less than the configured minimum TTL, it is replaced with the configured minimum TTL. If the TTL is
greater than the configured maximum TTL, it is replaced with the configured maximum TTL.

The NetScaler also allows caching of negative responses for a domain. A negative response indicates
that information about a requested domain does not exist, or that the server cannot provide an answer
for the query. The storage of this information is called negative caching. Negative caching helps speed
up responses to queries on a domain, and can optionally provide the record type.

A negative response can be one of the following:

• NXDOMAIN error message - If a negative response is present in the local cache, the NetScaler
returns an error message (NXDOMAIN). If the response is not in the local cache, the query is for-
warded to the server, and the server returns an NXDOMAIN error to the NetScaler. The NetScaler
caches the response locally, then returns the error message to the client.
• NODATA error message - The NetScaler sends a NODATA error message, if the domain name in
query is valid but records of the given type are not available.

The NetScaler supports recursive resolution of DNS requests. In recursive resolution, the resolver
(DNS client) sends a recursive query to a name server for a domain name. If the queried name server is
authoritative for the domain, it responds with the requested domain name. Otherwise, the NetScaler
queries the name servers recursively until the requested domain name is found.

Before you can apply the recursive query option, you must first enable it. You can also set the number
of times the DNS resolver must send a resolution request (DNS retries) if a DNS lookup fails.

You can configure the NetScaler as a DNS forwarder. A forwarder passes DNS requests to external
name servers. The NetScaler allows you to add external name servers and provides name resolution
for domains outside the network. The NetScaler also allows you to set the name lookup priority to
DNS or Windows Internet Name Service (WINS).

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2093

NetScaler 12.0

Round Robin DNS

When a client sends a DNS request to find the DNS resource record, it receives a list of IP addresses
resolving to the name in the DNS request. The client then uses one of the IP addresses in the list,
generally, the first record or IP address. Hence, a single server is used for the total TTL of the cache
and is overloaded when a large number of requests arrive.

When the NetScaler receives a DNS request, it responds by changing the order of the list of DNS re-
source records in a round robin method. This feature is called round robin DNS. Round robin dis-
tributes the traffic equally between data centers. The NetScaler performs this function automatically.
You do not have to configure this behavior.

Functional Overview

If the NetScaler is configured as an ADNS server, it returns the DNS records in the order in which the
records are configured. If the NetScaler is configured as a DNS proxy, it returns the DNS records in the
order in which it receives the records from the server. The order of the records present in the cache
matches the order in which records are received from the server.

The NetScaler then changes the order in which records are sent in the DNS response in a round robin
method. The first response contains the first record in sequence, the second response contains the
second record in sequence, the third response contains the third record in sequence, and the order
continues in the same sequence. Thus, clients requesting the same name can connect to different IP
addresses.

Round Robin DNS Example

As an example of round robin DNS, consider DNS records that have been added as follows:

1 add dns addRec ns1 1.1.1.1 add dns addRec ns1 1.1.1.2 add dns addRec
ns1 1.1.1.3 add dns addRec ns1 1.1.1.4

The domain, abc.com is linked to an NS record as follows:

1 add dns nsrec abc.com. ns1

When the NetScaler receives a query for the A record of ns1, the Address records are served in a round
robin method as follows. In the first DNS response, 1.1.1.1 is served as the first record:

1 ns1. 1H IN A 1.1.1.1 ns1.

1H IN A 1.1.1.2 ns1.
1H IN A 1.1.1.3 ns1.
1H IN A 1.1.1.4

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2094

NetScaler 12.0

In the second DNS response, the second IP address, 1.1.1.2 is served as the first record:

1 ns1. 1H IN A 1.1.1.2 ns1.

1H IN A 1.1.1.3 ns1.
1H IN A 1.1.1.4 ns1.
1H IN A 1.1.1.1

In the third DNS response, the third IP address, 1.1.1.2 is served as the first record:

1 ns1. 1H IN A 1.1.1.3 ns1.

1H IN A 1.1.1.4 ns1.
1H IN A 1.1.1.1 ns1.
1H IN A 1.1.1.2

1.
2. Citrix ADC
3. NetScaler 12.0

Configure DNS resource records

September 14, 2018

Contributed by:
C

You configure resource records on the NetScaler ADC appliance when you configure the appliance as
an ADNS server for a zone. You can also configure resource records on the appliance if the resource
records belong to a zone for which the appliance is a DNS proxy server. On the appliance, you can
configure the following record types:

• Service records
• AAAA records
• Address records
• Mail Exchange records
• Name Server records
• Canonical records
• Pointer records
• NAPTR records
• Start of Authority records
• Text records

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2095

NetScaler 12.0

The following table lists the record types that you can configure for a domain name record on the
NetScaler appliance. For example, you can configure a maximum of 25 IP addresses for one record.

Table 1. Record Type and Number Configurable

Record Type Number of Records

Address (A) 25
IPv6 (AAAA) 5
Mail exchange (MX) 12
Name server (NS) 16
Service (SRV) 8
Pointer (PTR) 20
Canonical name (CNAME) 1
Start of Authority (SOA) 1
Text (TXT) 20
Naming Authority Pointer (NAPTR) 20

Note:

The maximum number of IP addresses for a specific hostname is 25. However, the number of
different address records can be more than 25.

1.
2. Citrix ADC
3. NetScaler 12.0

Create SRV records for a service

September 11, 2018

Contributed by:
C

The SRV record provides information about the services available on the NetScaler appliance. An SRV
record contains the following information: name of the service and the protocol, domain name, TTL,
DNS class, priority of the target, weight of records with the same priority, port of the service, and host
name of the service. The NetScaler chooses the SRV record that has the lowest priority setting first.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2096

NetScaler 12.0

If a service has multiple SRV records with the same priority, clients use the weight field to determine
which host to use.

Add an SRV record by using the CLI

At the command prompt, type the following commands to add an SRV record and verify the configu-
ration:

1 - add dns srvRec <domain> <target> -priority <positive_integer> -

weight <positive_integer> -port <positive_integer> [-TTL <secs>]
2 - sh dns srvRec <domain>

Example:

1 > add dns srvRec _http._tcp.example.com nameserver1.com -priority 1 -

weight 1 -port 80
2 Done
3 > show dns srvRec _http._tcp.example.com
4 1) Domain Name : _http._tcp.example.com
5 Target Host : nameserver1.com
6 Priority : 1 Weight : 1
7 Port : 80 TTL : 3600 secs
8 Done

Modify or remove an SRV record by using the CLI

• To modify an SRV record, type the set dns srvRec command, the name of the domain for
which the SRV record is configured, the name of the target host that hosts the associated service,
and the parameters to be changed, with their new values.
• To remove an SRV record, type the rm dns srvRec command, the name of the domain for
which the SRV record is configured, and the name of the target host that hosts the associated
service.

Configure an SRV record by using the GUI

Navigate to Traffic Management > DNS > Records > SRV Records and create an SRV record.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2097

NetScaler 12.0

Creating AAAA Records for a Domain Name

September 11, 2018

Contributed by:
C

An AAAA resource record stores a single IPv6 address.

Add an AAAA record by using the CLI

At the command prompt, type the following commands to add an AAAA record and verify the configu-
ration:

1 - add dns aaaaRec <hostName> <IPv6Address> ... [-TTL <secs>]

2 - show dns aaaaRec <hostName>

Example:

1 > add dns aaaaRec www.example.com 2001:0db8:0000:0000:0000:0000:1428:57

ab
2 Done
3 > show dns aaaaRec www.example.com
4 1) Host Name : www.example.com
5 Record Type : ADNS TTL : 5 secs
6 IPV6 Address : 2001:db8::1428:57ab
7 Done

To remove an AAAA record and all of the IPv6 addresses associated with the domain name, type the
rm dns aaaaRec command and the domain name for which the AAAA record is configured. To re-
move only a subset of the IPv6 addresses associated with the domain name in an AAAA record, type
the
rm dns aaaaRec command, the domain name for which the AAAA record is configured, and the IPv6
addresses that you want to remove.

Add an AAAA record by using the GUI

Navigate to Traffic Management > DNS > Records > AAAA Records and create an AAAA record.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2098

NetScaler 12.0

Creating address records for a Domain Name

September 11, 2018

Contributed by:
C

Address (A) records are DNS records that map a domain name to an IPv4 address.

You cannot delete Address records for a host participating in global server load balancing (GSLB). How-
ever, the NetScaler deletes Address records added for GSLB domains when you unbind the domain
from a GSLB virtual server. Only user-configured records can be deleted manually. You cannot delete
a record for a host referenced by records such as NS, MX, or CNAME.

Add an Address record by using the CLI

At the command prompt, type the following commands to add an Address record and verify the con-
figuration:

1 - add dns addRec <hostName> <IPAddress> [-TTL <secs>]

2 - show dns addRec <hostName>

Example:

1 > add dns addRec ns.example.com 192.0.2.0

2 Done
3 > show dns addRec ns.example.com
4 1) Host Name : ns.example.com
5 Record Type : ADNS TTL : 5 secs
6 IP Address : 192.0.2.0
7 Done

To remove an Address record and all of the IP addresses associated with the domain name, type the
rm dns addRec command and the domain name for which the Address record is configured. To
remove only a subset of the IP addresses associated with the domain name in an Address record, type
the
rm dns addRec command, the domain name for which the Address record is configured, and the IP
addresses that you want to remove.

Add an Address record by using the GUI

Navigate to Traffic Management > DNS > Records > Address Records and create an Address record.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2099

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0

Create MX records for a mail exchange server

September 11, 2018

Contributed by:
C

Mail Exchange (MX) records are used to direct email messages across the Internet. An MX record con-
tains an MX preference that specifies the MX server to be used. The MX preference values range from 0
through 65536. An MX record contains a unique MX preference number. You can set the MX preference
and the TTL values for an MX record.

When an email message is sent through the Internet, a mail transfer agent sends a DNS query request-
ing the MX record for the domain name. This query returns a list of host names of mail exchange
servers for the domain, along with a preference number. If there are no MX records, the request is
made for the Address record of that domain. A single domain can have multiple mail exchange servers.

Add an MX record by using the CLI

At the command prompt, type the following commands to add an MX record and verify the configura-
tion:

1 - add dns mxRec <domain> -mx <string> -pref <positive_integer> [-TTL <
secs>]
2 - show dns mxRec <domain>

Example:

1 > add dns mxRec example.com -mx mail.example.com -pref 1

2 Done
3 > show dns mxRec example.com
4 1) Domain : example.com MX Name : mail.example.com
5 Preference : 1 TTL : 5 secs
6 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2100

NetScaler 12.0

Modify or remove an MX record by using the CLI

• To modify an MX record, type the set dns mxRec command, the name of the domain for which
the MX record is configured, the name of the MX record, and the parameters to be changed, with
their new values.
• To set the TTL parameter to its default value, type the unset dns mxRec command, the name of
the domain for which the MX record is configured, the name of the MX record, and -TTL without
any TTL value. You can use the unset dns mxRec command to unset only the TTL parameter.
• To remove an MX record, type the rm dns mxRec command, the name of the domain for which
the MX record is configured, and the name of the MX record.

Add an MX record by using the GUI

Navigate to Traffic Management > DNS > Records > Mail Exchange Records and create an MX record.

1.
2. Citrix ADC
3. NetScaler 12.0

Create NS Records for an authoritative server

May 9, 2019

Contributed by:
C

Name Server (NS) records specify the authoritative server for a domain. You can configure a maximum
of 16 NS records. You can use an NS record to delegate the control of a subdomain to a DNS server.

Create an NS record by using the CLI

At the command prompt, type the following commands to create an NS record and verify the configu-
ration:

1 - add dns nsRec <domain> <nameServer> [-TTL <secs>]

2 - show dns nsRec <domain>

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2101

NetScaler 12.0

1 > add dns nsRec example.com nameserver1.example.com

2 Done
3 > show dns nsRec example.com
4 1) Domain : example.com NameServer : nameserver1.example.com
5 TTL : 5 sec
6 Done

To remove an NS record, type the

rm dns nsRec command, the name of the domain to which the NS record belongs, and the name of
the name server.

Create an NS record by using the GUI

Navigate to Traffic Management > DNS > Records > Name Server Records and create an NS record.

1.
2. Citrix ADC
3. NetScaler 12.0

Create CNAME records for a subdomain

September 11, 2018

Contributed by:
C

A canonical name record (CNAME record) is an alias for a DNS name. These records are useful when
multiple services query the DNS server. The host that has an address (A) record cannot have a CNAME
record.

In some cases, a NetScaler appliance in proxy mode requests an address record from the cache instead
of the server.

Add a CNAME record by using the CLI

At the command prompt, type the following commands to create a CNAME record and verify the con-
figuration:

1 - add dns cnameRec <aliasName> <canonicalName> [-TTL <secs>]

2 - show dns cnameRec <aliasName>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2102

NetScaler 12.0

Example:

1 > add dns cnameRec www.example.com www.examplenw.com

2 Done
3 > show dns cnameRec www.example.com
4 Alias Name Canonical Name TTL
5 1) www.example.com www.examplenw.com 5 secs
6 Done

To remove a CNAME record for a given domain, type the

rm dns cnameRec command and the alias of the domain name.

Add a CNAME record by using the GUI

Navigate to Traffic Management > DNS > Records > Canonical Records and create a CNAME record.

Cache CNAME records

NetScaler when deployed in a proxy mode does not always send the query for an address record to the
back-end server. This happens when for a answer to a query for an address record, a partial CNAME
chain is present in the cache. There are few conditions in which the ADC caches the partial CNAME
record and serves the query from the cache. Following are the conditions:

• NetScaler should be deployed in a proxy mode

• The response from the back-end server should have a CNAME chain, for which the record type
of last entry in the answer section must be a CNAME and the question type not a CNAME
• The response from the back-end server cannot be a No-data or NX-Domain
• The response from the back-end server has to be a authoritative response

1.
2. Citrix ADC
3. NetScaler 12.0

Create NAPTR records for telecommunications domain

September 11, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2103

NetScaler 12.0

NAPTR (Naming Address Pointer) is one of the most commonly used DNS record in telecommunica-
tions domain. NAPTR records map the Internet telephony address space to the Internet address space.
They therefore enable a mobile device to send a request to the correct server. The combination of
NAPTR records with Service Records (SRV) allows the chaining of multiple records to form complex
rewrite rules that produce new domain labels or uniform resource identifiers (URIs). The DNS code
for NAPTR is 35.

NetScalers support NAPTR in two modes: ADNS mode and proxy mode. In proxy mode, the ADC
caches the response from the servers and uses the cached records to server future queries. A max-
imum of 20 NAPTR records can be added for a particular domain in NetScaler. NetScaler caches the
reply to a DNS NAPTR record query. Any subsequent requests for the NAPTR record is served from the
cache.

Create a NAPTR record by using CLI

At the command prompt, type the following commands to add a NAPTR record and verify the config-
uration:

add dns naptrRec <order> <preference>[flags<string>][services<string>](

regexp<expressions>|-replacement<string>)[-TTL<secs>]

Remove a NAPTR record by using CLU

rm dns naptrRec<domain> (<order> <preference> [-flags <string>] [-services

<string>] (-regexp <expression> | -replacement <string>))| -recordId <
positive_integer>@)

Configure a NAPTR record using GUI

Navigate to Traffic Management > DNS > Records > NAPTR Records and create an NAPTR record.

1.
2. Citrix ADC
3. NetScaler 12.0

Create PTR records for IPv4 and IPv6 addresses

September 11, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2104

NetScaler 12.0

Contributed by:
C

A pointer (PTR) record translates an IP address to its domain name. IPv4 PTR records are represented
by the octets of an IP address in reverse order with the string “in-addr.arpa.” appended at the end.
For example, the PTR record for the IP address 1.2.3.4 is 4.3.2.1.in-addr.arpa.

IPv6 addresses are reverse mapped under the domain IP6.ARPA. IPv6 reverse-maps use a sequence
of nibbles separated by dots with the suffix “.IP6.ARPA” as defined in RFC 3596. For example,
the reverse lookup domain name corresponding to the address, 4321:0:1:2:3:4:567:89ab would be
b.a.9.8.7.6.5.0.4.0.0.0.3.0.0.0.2.0.0.0.1.0.0.0.0.0.0.0.1.2.3.4.IP6.ARPA.

Add a PTR record by using the CLI

At the command prompt, type the following commands to add a PTR record and verify the configura-
tion:

1 - add dns ptrRec <reverseDomain> <domain> [-TTL <secs>]

2 - show dns ptrRec <reverseDomain>

Example:

1 > add dns ptrRec 0.2.0.192.in-addr.arpa example.com

2 Done
3 > show dns ptrRec 0.2.0.192.in-addr.arpa
4 1) Reverse Domain Name : 0.2.0.192.in-addr.arpa
5 Domain Name : example.com TTL : 3600 secs
6 Done

To remove a PTR record, type the

rm dns ptrRec command and the reverse domain name associated with the PTR record

Add a PTR record by using the GUI

Navigate to Traffic Management > DNS > Records > PTR Records and create a PTR record.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2105

NetScaler 12.0

Create SOA records for authoritative information

September 11, 2018

Contributed by:
C

A Start of Authority (SOA) record is created only at the zone apex and contains information about the
zone. The record includes, among other parameters, the primary name server, contact information
(e-mail), and default (minimum) time-to-live (TTL) values for records.

Create an SOA record by using the CLI

At the command prompt, type the following commands to add an SOA record and verify the configu-
ration:

1 - add dns soaRec <domain\> -originServer \<originServerName\> -contact

\<contactName\>
2 - sh dns soaRec \<do main\>

Example:

1 > add dns soaRec example.com -originServer nameserver1.example.com -

contact admin.example.com
2 Done
3 > show dns soaRec example.com
4 1) Domain Name : example.com
5 Origin Server : nameserver1.example.com
6 Contact : admin.example.com
7 Serial No. : 100 Refresh : 3600 secs Retry : 3 secs
8 Expire : 3600 secs Minimum : 5 secs TTL : 3600 secs
9 Done

Modify or remove an SOA record by using the CLI

• To modify an SOA record, type the set dns soaRec command, the name of the domain for
which the record is configured, and the parameters to be changed, with their new values.
• To remove an SOA record, type the rm dns soaRec command and the name of the domain for
which the record is configured.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2106

NetScaler 12.0

Configure an SOA record by using the GUI

Navigate to Traffic Management > DNS > Records > SOA Records and create an SOA record.

1.
2. Citrix ADC
3. NetScaler 12.0

Create TXT records for holding descriptive text

September 11, 2018

Contributed by:
C

Domain hosts store TXT records for informative purposes. A TXT record’s RDATA component, which
consists of one or more character strings of variable length, can store practically any information that
a recipient might need to know about the domain, including information about the service provider,
contact person, email addresses, and associated details. SPF (Sender Policy Framework) protection
has been the most prominent use case for the TXT record.

All configuration types (authoritative DNS, DNS proxy, end resolver, and forwarder configurations) on
the NetScaler appliance support TXT records. You can add a maximum of 20 TXT resource records to
a domain. Each resource record is stored with a unique, internally generated record ID. You can view
the ID of a record and use it to delete the record. However, you cannot modify a TXT resource record.

Create a TXT resource record by using the CLI

At the command prompt, type the following commands to create a TXT resource record and verify the
configuration:

1 - add dns txtRec <domain> <string> ... [-TTL <secs>]

2 - show dns txtRec [<domain> | -type <type>]

Example:

1 > add dns txtRec www.example.com ”Contact: Mark” ”Email: mark@example.

com” -TTL 36000
2 Done
3 > show dns txtRec www.example.com
4 1) Domain : www.example.com Record id: 13783 TTL : 36000 secs
Record Type : ADNS

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2107

NetScaler 12.0

5 ”Contact: Mark”
6 ”Email: [email protected]”
7 Done

Remove a TXT resource record by using the CLI

At the command prompt, type the following commands to remove a TXT resource record and verify
the configuration:

1 - rm dns txtRec <domain> (<string> ... | -recordId <positive_integer>)

2 - show dns txtRec [<domain> | -type <type>]

Example:
You can use the show dns txtRec command first to view the record ID of the TXT resource record that
you want to remove, as shown:

1 > show dns txtRec www.example.com

2 1) Domain : www.example.com Record id: 36865 TTL : 36000 secs
Record Type : ADNS
3 ”Contact: Evan”
4 ”Email: [email protected]”
5 2) Domain : www.example.com Record id: 14373 TTL : 36000 secs
Record Type : ADNS
6 ”Contact: Mark”
7 ”Email: [email protected]”
8 Done

The simpler method of deleting a TXT record is to use the record ID. If you want to provide the strings,
enter them in the order in which they are stored in the record. In the following example, the TXT record
is deleted by using its record ID.

1 >rm dns txtRec www.example.com -recordID 36865

2 Done
3 > show dns txtRec www.example.com
4 1) Domain : www.example.com Record id: 14373 TTL : 36000 secs
Record Type : ADNS
5 ”Contact: Mark”
6 ”Email: [email protected]”
7 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2108

NetScaler 12.0

Configure a TXT record by using the GUI

Navigate to Traffic Management > DNS > Records > TXT Records and create a TXT record.

1.
2. Citrix ADC
3. NetScaler 12.0

Viewing DNS statistics

September 14, 2018

Contributed by:
C

You can view the DNS statistics generated by the NetScaler appliance. The DNS statistics include run-
time, configuration, and error statistics.

View DNS records statistics by using the CLI

At the command prompt, type:

stat dns

Example:

1 > stat dns

2 DNS Statistics
3
4 Runtime Statistics
5 Dns queries 21
6 NS queries 8
7 SOA queries 18
8 .
9 .
10 .
11 Configuration Statistics
12 AAAA records 17
13 A records 36
14 MX records 9
15 .
16 .
17 .

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2109

NetScaler 12.0

18 Error Statistics
19 Nonexistent domain 17
20 No AAAA records 0
21 No A records 13
22 .
23 .
24 .
25 Done

View DNS records statistics by using the GUI

1. Navigate to Traffic Management > DNS.

2. In the details pane, click Statistics.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure a DNS zone

September 14, 2018

Contributed by:
C

A DNS zone entity on the NetScaler ADC appliance facilitates the ownership of a domain on the appli-
ance. A zone on the appliance also enables you to implement DNS Security Extensions (DNSSEC) for
the zone, or to offload the zone’s DNSSEC operations from the DNS servers to the appliance. DNSSEC
sign operations are performed on all the resource records in a DNS zone. Therefore, if you want to
sign a zone, or if you want to offload DNSSEC operations for a zone, you must first create the zone on
the NetScaler appliance.

You must create a DNS zone on the appliance in the following scenarios:

• The NetScaler appliance owns all the records in a zone, that is, the appliance is operating as the
authoritative DNS server for the zone. The zone must be created with the proxyMode parameter
set to NO.
• The NetScaler appliance owns only a subset of the records in a zone, and all the other resource
records in the zone are hosted on a set of back-end name servers for which the appliance is
configured as a DNS proxy server. A typical configuration where the NetScaler appliance owns

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2110

NetScaler 12.0

only a subset of the resource records in the zone is a global server load balancing (GSLB) con-
figuration. Only the GSLB domain names are owned by the NetScaler appliance, while all the
other records are owned by the back-end name servers. The zone must be created with the
proxyMode parameter set to YES.
• You want to offload DNSSEC operations for a zone from your authoritative DNS servers to the
appliance. The zone must be created with the proxyMode parameter set to YES. You might need
to configure additional settings for the zone.

The current topic describes how to create a zone for the first two scenarios. For more information
about how to configure a zone for offloading DNSSEC operations to the appliance, see Offload DNSSEC
operations to the NetScaler appliance.

Note

If the NetScaler is operating as the authoritative DNS server for a zone, you must create Start
of Authority (SOA) and name server (NS) records for the zone before you create the zone. If
the NetScaler is operating as the DNS proxy server for a zone, SOA and NS records must not be
created on the NetScaler appliance. For more information about creating SOA and NS records,
see Configure DNS resource records.

When you create a zone, all existing domain names and resource records that end with the name of the
zone are automatically treated as a part of the zone. Additionally, any new resource records created
with a suffix that matches the name of the zone are implicitly included in the zone.

Create a DNS zone on the NetScaler appliance by using the CLI

At the command prompt, type the following command to add a DNS zone to the NetScaler appliance
and verify the configuration:

1 - add dns zone <zoneName> -proxyMode ( YES | NO )

2 - show dns zone [<zoneName> | -type <type>]

Example:

1 > add dns zone example.com -proxyMode Yes

2 Done
3 > show dns zone example.com
4 Zone Name : example.com
5 Proxy Mode : YES
6 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2111

NetScaler 12.0

Modify or remove a DNS zone by using the CLI

• To modify a DNS zone, type the set dns zone command, the name of the DNS zone, and the
parameters to be changed, with their new values.
• To remove a DNS zone, type the rm dns zone command and the name of the dns zone.

Configure a DNS zone by using the GUI

Navigate to Traffic Management > DNS > Zones and create a DNS zone.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure the NetScaler as an ADNS server

January 6, 2019

Contributed by:
C

You can configure the NetScaler appliance to function as an authoritative domain name server (ADNS)
for a domain. As an ADNS server for a domain, the NetScaler resolves DNS requests for all types of
DNS records that belong to the domain. To configure the NetScaler to function as an ADNS server for
a domain, you must create an ADNS service and configure NS and Address records for the domain on
the NetScaler. The ADNS service can be configured using the subnet IP address (SNIP) or a separate IP
address. The following topology diagram shows a sample configuration and the flow of requests and
responses.

Figure 1. NetScaler as an ADNS

The following table shows the parameters that are configured for the ADNS service illustrated in the
preceding topology diagram.

Entity type Name IP address Type Port

ADNS Service Service-ADNS-1 10.102.29.51 ADNS 53

Table 1. Example of ADNS Service Configuration

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2112

NetScaler 12.0

To configure an ADNS setup, you must configure the ADNS service. For instructions on configuring the
ADNS service, see “Load balancing”.

During DNS resolution, the ADNS server directs the DNS proxy or local DNS server to query the
NetScaler for the IP address of the domain. Because the NetScaler is authoritative for the domain,
it sends the IP address to the DNS proxy or local DNS server. The following diagram describes the
placement and role of the ADNS server in a GSLB configuration.

Figure 2. GSLB Entity Model

Note: In ADNS mode, if you remove SOA and ADNS records, the following do not function for the do-
main hosted by the NetScaler: ANY query (for more information about the ANY query, see
DNS ANY query, and negative responses, such as NODATA and NXDOMAIN.

Create an ADNS service

An ADNS service is used for global service load balancing. For more information about creating a GSLB
setup, see “Global server load balancing”. You can add, modify, enable, disable, and remove an ADNS
service. For instructions on creating an ADNS service, see Configure services.

Note: You can configure the ADNS service to use SNIP or any new IP address.

When you create an ADNS service, the NetScaler responds to DNS queries on the configured ADNS
service IP and port.

You can verify the configuration by viewing the properties of the ADNS service You can view properties
such as name, state, IP address, port, protocol, and maximum client connections.

Configure the ADNS setup to use TCP

By default, some clients use the User Datagram Protocol (UDP) for DNS, which specifies a limit of 512
bytes for the payload length of UDP packets. To handle payloads that exceed 512 bytes in size, the
client must use the Transmission Control Protocol (TCP). To enable DNS communications over TCP,
you must configure the NetScaler appliance to use the TCP protocol for DNS. The NetScaler then sets
the truncation bit in the DNS response packets. The truncation bit specifies that the response is too
large for UDP and that the client must send the request over a TCP connection. The client then uses
the TCP protocol on port 53 and opens a new connection to the NetScaler. The NetScaler listens on
port 53 with the IP address of the ADNS service to accept the new TCP connections from the client.

To configure the NetScaler to use the TCP protocol, you must configure an ADNS_TCP service. For
instructions on creating an ADNS_TCP service, see
Load balancing.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2113

NetScaler 12.0

Important

To configure the NetScaler to use UDP for DNS and use TCP only when the payload length of UDP
exceeds 512 bytes, you need to configure the ADNS and ADNS_TCP services. The IP address of
the ADNS_TCP service must be same as the IP address of the ADNS service.

Add DNS resource records

After you create an ADNS service, you can add DNS records. For instructions on adding DNS records,
see Configure DNS resource records.

Remove ADNS services

For instructions on removing services, see Load balancing

Configure domain delegation

Domain delegation is the process of assigning responsibility for a part of the domain space to another
name server. Therefore, during domain delegation, the responsibility for responding to the query is
delegated to another DNS server. Delegation uses NS records.

In the following example, sub1.abc.com is the subdomain for abc.com. The procedure describes the
steps to delegate the subdomain to the name server ns2.sub1.abc.com and add an Address record for
ns2.sub1.abc.com.

To configure domain delegation, you need to perform the following tasks, which are described in the
sections that follow:

1. Create an SOA record for a domain.

2. Create an NS record to add a name server for the domain.
3. Create an Address record for the name server.
4. Create an NS record to delegate the subdomain.
5. Create a glue record for the name server.

Create an SOA record

For instructions on configuring SOA records, see Create SOA records for authoritative information.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2114

NetScaler 12.0

Create an NS record for a name server

For instructions on configuring an NS record, see Create NS records for an authoritative server. In the
Name Server drop-down list, select the primary authoritative name server, for example, ns1.abc.com.

Create an address record

For instructions on configuring Address records, see Create address records for a domain name. In
the Host Name and IP address text boxes, type the domain name for the DNS Address record and the
IP address, for example, ns1.abc.com and 10.102.11.135, respectively.

Create an NS record for domain delegation

For instructions on configuring NS records, see Create NS records for an authoritative server.
In the Name Server drop-down list, select the primary authoritative name server, for example,
ns2.sub1.abc.com.

Create a glue record

NS records are usually defined immediately after the SOA record (but this is not a restriction.) A do-
main must have at least two NS records. If an NS record is defined within a domain, it must have a
matching Address record. This Address record is referred to as a glue record. Glue records speed up
DNS queries.

For instructions on adding glue records for a subdomain, see the procedure for adding an Address (A)
record, Configure DNS resource records.

For instructions on configuring Address records, see [Create address records for a domain name]/(/en-
us/netscaler/12/dns/configure-dns-resource-records/create-address-records.html). In Host Name
and IP address text boxes, type the domain name for the DNS Address record and the IP address, for
example, ns2.sub1.abc.com and 10.102.12.135, respectively.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure the NetScaler appliance as a DNS proxy server

January 6, 2019

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2115

NetScaler 12.0

Contributed by:
C

As a DNS proxy server, the NetScaler ADC appliance can function as a proxy for either a single DNS
server or a group of DNS servers. The flow of requests and responses is illustrated in the following
sample topology diagram.

Figure 1. NetScaler as DNS proxy

By default, the NetScaler appliance caches responses from DNS name servers. When the appliance
receives a DNS query, it checks for the queried domain in its cache. If the address for the queried do-
main is present in its cache, the NetScaler returns the corresponding address to the client. Otherwise,
it forwards the query to a DNS name server that checks for the availability of the address and returns
it to the NetScaler. The NetScaler then returns the address to the client.

For requests for a domain that has been cached earlier, the NetScaler serves the Address record of the
domain from the cache without querying the configured DNS server.

The appliance discards a record stored in its cache when the time-to-live (TTL) value of the record
reaches the configured value. A client that requests an expired record has to wait until the NetScaler
retrieves the record from the server and updates its cache. To avoid this delay, the NetScaler proac-
tively updates the cache by retrieving the record from the server before the record expires.

The following table lists sample names and the values of the entities that need to be configured on
the NetScaler.

Table 1. Example of DNS Proxy Entity Configuration

Entity type Name IP address Type Port

LB virtual server Vserver-DNS-1 10.102.29.40 DNS 53

Services Service-DNS-1 10.102.29.50 DNS 53
Services Service-DNS-2 10.102.29.51 DNS 53

The following diagram shows the entities of a DNS Proxy and the values of the parameters to be con-
figured on the NetScaler.

Figure 2. DNS Proxy Entity Model

Note

To configure DNS proxy, you need to know how to configure load balancing services and virtual
servers.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2116

NetScaler 12.0

Create a load balancing virtual server

To configure a DNS Proxy on the NetScaler, configure a load balancing virtual server of type DNS. To
configure a DNS virtual server to load balance a set of DNS servers that support recursive queries, you
must set the Recursion Available option. With this option, the RA bit is set to ON in the DNS replies
from the DNS virtual server.

For instructions on creating a load balancing virtual server, see “Load Balancing”.

Create DNS services

After creating a load balancing virtual server of type DNS, you must create DNS services. You can add,
modify, enable, disable, and remove a DNS service. For instructions on creating a DNS service, see
“Load Balancing”.

Bind a load balancing virtual server to DNS services

To complete the DNS Proxy configuration, you must bind the DNS services to the load balancing virtual
server. For instructions on binding a service to a load balancing virtual server, see “Load Balancing”.

Configure the DNS proxy setup to use TCP

Some clients use the User Datagram Protocol (UDP) for DNS communications. However, UDP specifies
a maximum packet size of 512 bytes. When payload lengths exceed 512 bytes, the client must use the
Transmission Control Protocol (TCP). When a client sends the NetScaler ADC appliance a DNS query,
the appliance forwards the query to one of the name servers. If the response is too large for a UDP
packet, the name server sets the truncation bit in its response to the NetScaler. The truncation bit
indicates that the response is too large for UDP and that the client must send the query over a TCP
connection. The NetScaler relays the response to the client with the truncation bit intact and waits for
the client to initiate a TCP connection with the IP address of the DNS load balancing virtual server, on
port 53. The client sends the request over a TCP connection. The NetScaler appliance then forwards
the request to the name server and relays the response to the client.

To configure the NetScaler to use the TCP protocol for DNS, you must configure a load balancing virtual
server and services, both of type DNS_TCP. You can configure monitors of type DNS_TCP to check the
state of the services. For instructions on creating DNS_TCP virtual servers, services, and monitors, see
“Load Balancing.”

For updating the records proactively, the NetScaler uses a TCP connection to the server to retrieve the
records.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2117

NetScaler 12.0

Important To configure the NetScaler to use UDP for DNS and use TCP only when the payload
length of UDP exceeds 512 bytes, you need to configure DNS and DNS_TCP services. The IP ad-
dress of the DNS_TCP service must be same as that of the DNS service.

Configure time-to-live values for DNS entries

The TTL is the same for all DNS records with the same domain name and record type. If the TTL value
is changed for one of the records, the new value is reflected in all records of the same domain name
and type. The default TTL value is 3600 seconds. The minimum is 0, and the maximum is 604800. If
a DNS entry has a TTL value less than the minimum or greater than the maximum, it is saved as the
minimum or maximum TTL value, respectively.

Specify the minimum and/or maximum TTL by using the CLI

At the NetScaler command prompt, type the following commands to specify the minimum and maxi-
mum TTL and verify the configuration:

1 - set dns parameter [-minTTL <secs>] [-maxTTL <secs>]

2 - show dns parameter

Example:

1 > set dns parameter -minTTL 1200 -maxTTL 1800

2 Done
3 > show dns parameter
4 DNS parameters:
5 DNS retries: 5
6 Minimum TTL: 1200 Maximum TTL: 1800
7 .
8 .
9 .
10 Done
11 >

Specify the minimum and/or maximum TTL by using the GUI

1. Navigate to Traffic Management > DNS.

2. In the details pane, under Settings, click Change DNS settings.
3. In the Configure DNS Parameters dialog box, in TTL, in the Minimum and Maximum text boxes,
type the minimum and maximum time to live (in seconds), respectively, and then click OK.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2118

NetScaler 12.0

Note: When the TTL expires, the record is deleted from the cache. The NetScaler proactively contacts
the servers and obtains the DNS record just before the DNS record expires.

Flush DNS records

You can delete all DNS records present in the cache. For example, you might want to flush DNS records
when a server is restarted after modifications are made.

Delete all proxy records by using the CLI

At the NetScaler command prompt, type:

flush dns proxyRecords

Delete all proxy records by using the GUI

1. Navigate to Traffic Management > DNS > Records.

2. In the details pane, click Flush Proxy Records.

Add DNS resource records

You can add DNS records to a domain for which the NetScaler ADC appliance is configured as a DNS
proxy server. For information about adding DNS records, see Configuring DNS Resource Records.

Remove a load balancing DNS virtual server

For information about removing a load balancing virtual server, see Load Balancing.

Limit the number of concurrent DNS requests on a client connection

You can limit the number of concurrent DNS requests on a single client connection, which is identi-
fied by the <clientip:port>-<vserver ip:port> tuple. Concurrent DNS requests are those requests that
the NetScaler appliance has forwarded to the name servers and for which the appliance is awaiting
responses. Limiting the number of concurrent requests on a client connection enables you to pro-
tect the name servers when a hostile client attempts a Distributed Denial of Service (DDoS) attack by
sending a flood of DNS requests. When the limit for a client connection is reached, subsequent DNS
requests on the connection are dropped till the outstanding request count goes below the limit. This
limit does not apply to the requests that the NetScNetScaleraler appliance serves out of its cache.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2119

NetScaler 12.0

The default value for this parameter is 255. This default value is sufficient in most scenarios. If the
name servers serve a large number of concurrent DNS requests under normal operating conditions,
you can specify either a large value or a value of zero (0). A value of 0 disables this feature and specifies
that there is no limit to the number of DNS requests that are allowed on a single client connection. This
is a global parameter and applies to all the DNS virtual servers that are configured on the NetScaler
appliance.

Specify the maximum number of concurrent DNS requests allowed on a single client
connection by using the CLI

At the command prompt, type the following commands to specify the maximum number of concur-
rent DNS requests allowed on a single client connection and verify the configuration:

1 - set dns parameter -maxPipeline <positive_integer>

2 - show dns parameter

Example:

1 > set dns parameter -maxPipeline 1000

2 Done
3 > show dns parameter
4 DNS parameters:
5 DNS retries: 5
6 .
7 .
8 .
9 Max DNS Pipeline Requests: 1000
10 Done

Specify the maximum number of concurrent DNS requests allowed on a single client
connection by using the GUI

1. Navigate to Traffic Management > DNS.

2. In the details pane, click Change DNS settings.
3. In the Configure DNS Parameters dialog box, specify a value for Max DNS Pipeline Requests.
4. Click OK.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2120

NetScaler 12.0

Configure the NetScaler as an end resolver

January 6, 2019
Contributed by:
C
A resolver is a procedure that is invoked by an application program that translates a domain/host
name to its resource record. The resolver interacts with the LDNS, which looks up the domain name
to obtain its IP address. The NetScaler can provide end-to-end resolution for DNS queries.
In recursive resolution, the NetScaler appliance queries different name servers recursively to access
the IP address of a domain. When the NetScaler receives a DNS request, it checks its cache for the DNS
record. If the record is not present in the cache, it queries the root servers configured in the ns.conf
file. The root name server reports back with the address of a DNS server that has detailed information
about the second-level domain. The process is repeated until the required record is found.
When you start the NetScaler appliance for the first time, 13 root name servers are added to the ns.conf
file. The NS and Address records for the 13 root servers are also added. You can modify the ns.conf
file, but the NetScaler does not allow you to delete all 13 records; at least one name server entry is
required for the appliance to perform name resolution. The following diagram illustrates the process
of name resolution.
Figure 1. Recursive resolution
In the process shown in the diagram, when the name server receives a query for the address of
s1.s2.s3.com, it first checks the root name servers for s1.s2.s3.com. A root name server reports back
with the address of the .com name server. If the address of s1.s2.s3.com is found in the name server,
it responds with a suitable IP address. Otherwise, it queries other name servers for s3.com, then
for s2.s3.com to retrieve the address of s1.s2.s3.com. In this way, resolution always starts from root
name servers and ends with the domain’s authoritative name server.
Note: For recursive resolution functionality, caching should be enabled.

Enable recursive resolution

To configure the NetScaler appliance to function as an end resolver, you must enable recursive reso-
lution on the appliance.

Enable recursive resolution by using the CLI

At the command prompt, type the following commands to enable recursive resolution and verify the
configuration:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2121

NetScaler 12.0

1 - set dns parameter -recursion ENABLED

2 - show dns parameter

Example:

1 > set dns parameter -recursion ENABLED

2 Done
3 > show dns parameter
4 DNS parameters:
5 .
6 .
7 .
8 Recursive Resolution : ENABLED
9 .
10 .
11 .
12 Done

Enable recursive resolution by using the GUI

1. Navigate to Traffic Management > DNS.

2. In the details pane, under Settings, click Change DNS settings.
3. In the Configure DNS Parameters dialog box, select the Enable recursion check box, and then
click OK.

Set the Number of Retries

The NetScaler appliance can be configured to make a preconfigured number of attempts (called DNS
retries) when it does not receive a response from the server to which it sends a query. By default, the
number of DNS retries is set to 5.

Set the number of DNS retries by using the CLI

At the command prompt, type the following commands to set the number of retries and verify the
configuration:

1 - set dns parameter -retries <positive_integer>

2 - show dns parameter

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2122

NetScaler 12.0

1 > set DNS parameter -retries 3

2 Done
3 > show dns parameter
4 DNS parameters:
5 DNS retries: 3
6 .
7 .
8 .
9 Done

Set the number of retries by using the GUI

1. Navigate to Traffic Management > DNS.

2. In the details pane, under Settings, click Change DNS settings.
3. In the Configure DNS Parameters dialog box, in the DNS Retries text box, type the DNS resolver
request retry count, and then click OK.
1.
2. Citrix ADC
3. NetScaler 12.0

Configure the NetScaler appliance as a forwarder

September 11, 2018

Contributed by:
C
A forwarder is a server that forwards DNS queries to DNS servers that are outside the forwarder server’s
network. Queries that cannot be resolved locally are forwarded to other DNS servers. A forwarder ac-
cumulates external DNS information in its cache as it resolves DNS queries. To configure the NetScaler
appliance as a forwarder, you must add an external name server.
The NetScaler appliance allows you to add external name servers to which it can forward the name res-
olution queries that cannot be resolved locally. To configure the NetScaler appliance as a forwarder,
you must add the name servers to which it must forward name resolution queries. You can specify the
lookup priority to specify the name service that the NetScaler appliance must use for name resolution.
1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2123

NetScaler 12.0

Add a name server

September 18, 2018

Contributed by:
C

You can create a name server by specifying its IP address or by configuring an existing virtual server
as the name server.

While adding name server, you can provide an IP address or a virtual server IP address. If you add
IP address based name servers, the NetScaler appliance load balances requests to the configured
name servers in round robin method. If you add a virtual server, you can configure any load balancing
method.

To verify the configuration, you can use the sh dns <recordtype> <domain> command. If the
queried records are not present in the cache, the resource records are fetched from the configured
external name servers.

Add a name server (when the NetScaler appliance acts as a forwarder) by using the CLI

At the command prompt, type;

1 add dns nameServer ((<IP>) | <dnsVserverName>)

Example:

1 add dns nameServer 192.0.2.10  

2
3 add dns nameServer dnsVirtualNS

Add a name server (when the NetScaler appliance acts as a resolver) by using the CLI

At the command prompt, type:

1 add dns nameServer ((<IP> [-local]) | <dnsVserverName>)

Example:

1 add dns nameServer 10.102.9.19 -local

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2124

NetScaler 12.0

Note:

• To remove a name server, at the NetScaler CLI, type the rm dns nameServer command
followed by the IP address of the name server.
• To view the details of the DNS nameserver, at the NetScaler CLI, type show dns
nameServer command followed by the IP address of the name server.

Add a name server by using the GUI

Navigate to Traffic Management > DNS > Name Servers and create a name server.

1.
2. Citrix ADC
3. NetScaler 12.0

Set DNS lookup priority

September 11, 2018

Contributed by:
C

You can set the lookup priority to either DNS or WINS. This option is used in the SSL VPN mode of
operation.

Set the lookup priority to DNS by using the CLI

At the command prompt, type the following commands to set the lookup priority to DNS and verify
the configuration:

1 - set dns parameter -nameLookupPriority (DNS | WINS)

2 - show dns parameter

Example:

1 > set dns parameter -nameLookupPriority DNS

2 Done
3 > show dns parameter
4 .
5 .
6 .

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2125

NetScaler 12.0

7 Name lookup priority : DNS

8 .
9 .
10 .
11 Done

Set lookup priority to DNS by using the GUI

1. Navigate to Traffic Management > DNS.

2. In the details pane, under Settings, click Change DNS settings.
3. In the Configure DNS Parameters dialog box, under Name Lookup Priority, select DNS or
WINS, and then click OK.
Note

If the DNS virtual server that you have configured is DOWN and if you set the
-nameLookupPriority to DNS, the NetScaler does not attempt WINS lookup. Therefore, if a DNS
virtual server is not configured or is disabled, set the
-nameLookupPriority to WINS.

1.
2. Citrix ADC
3. NetScaler 12.0

Disable and enable name servers

September 11, 2018

Contributed by:
C

The following procedure describes the steps to enable or disable an existing name server.

Enable or disable a name server by using the CLI

At the command prompt, type the following commands to enable or disable a name server and verify
the configuration:

1 - (enable | disable) dns nameServer <IPAddress>

2 - show dns nameServer <IPAddress>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2126

NetScaler 12.0

Example:

1 > disable dns nameServer 10.102.9.19

2 Done
3 > show dns nameServer 10.102.9.19
4 1) 10.102.9.19: LOCAL - State: OUT OF SERVICE
5 Done

Enable or disable a name server by using the GUI

1. Navigate to Traffic Management > DNS > Name Servers.

2. In the details pane, select the name server that you want to enable or disable.
3. Click Enable or Disable. If a name server is enabled, the Disable option is available. If a name
server is disabled, the Enable option is available.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure DNS logging

September 12, 2018

Contributed by:
C

You can configure the NetScaler appliance to log the DNS requests and responses that it handles. The
appliance logs the DNS requests and responses in SYSLOG format. You can choose to log either DNS
requests or DNS responses, or both, and send the syslog messages to a remote log server. The log
messages can be used to:

• Audit the DNS responses to the client

• Audit DNS clients
• Detect and prevent DNS attacks
• Troubleshoot

A NetScaler appliance can log the following sections in the DNS request or response, on the basis of
your configuration:

• Header Section
• Questions Section
• Answer Section

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2127

NetScaler 12.0

• Authority Section
• Additional Section

DNS profiles

You can use a DNS profile to configure various DNS parameters that you want the DNS endpoint to
apply to the DNS traffic. In the profile, you can enable logging, caching and negative caching.

Important: From NetScaler 11.0 release, enabling DNS caching using global DNS parameters has been
deprecated. You can enable or disable DNS caching using DNS profiles. You can now enable DNS
caching for an individual virtual server by enabling DNS caching in a DNS profile and setting the DNS
profile to the individual virtual server.

DNS profiles support the following types of DNS logging:

• DNS Query Logging

• DNS Answer Section Logging
• DNS Extended Logging
• DNS Error Logging

DNS query logging

You can configure a NetScaler appliance to log only the DNS queries that are received by the DNS
endpoints on the appliance.

Note: If errors occur during processing of a query, they are logged if this option is set in the DNS profile.

Following is an example of a query log message:

1 DNS DNS_QUERY 143 0 : U:10.102.27.70#61297:10.102.27.73#53/22142/Q/

2 (RD)/NO/1/0/0/0#test.com./1#

DNS answer section logging

You can configure a NetScaler appliance to log all the Answer sections in the DNS responses that ap-
pliance sends to the client. DNS Answer Section logging is very useful when NetScaler is configured
as a DNS resolver, or in GLSB use cases.

Following is an example of a DNS answer section log:

1 DNS DNS_RESPONSE 6678 0 : U:100.100.100.210#32776:100.100.100.10#

2 53/61373/Q/(RD,AA,RA,R)/NO/1/1/2/4#n1.citrix.com1./
3 28#ANS#AAAA/120/1111:2345:6789:ffab:abcd:effa:1234:3212##

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2128

NetScaler 12.0

DNS extended logging

To configure a NetScaler appliance to log Authority and Additional sections in the DNS responses,
enable Extended logging with Answer Section logging.

Note: If errors occur during processing of either queries or responses, the errors are logged if this
option is set in the DNS profile.

Following is an example of a message logged when the cache lookup is completed and the response
is embedded in the packet:

1 DNS DNS_RESPONSE 2252 0 :  T:100.100.100.118#21411:100.100.100.10

2 #53/48537/Q/(RD,AA,CD,RA,R)/NO/1/1/2/6#a1.citrix.com1./1#ANS#A/
3 120/1.1.1.1##AUTH#citrix.com1/NS/120/n2.citrix.com1#n1.citrix.com1##ADD
#n1.citrix.com1
4 /A/120/1.1.1.1#1.1.1.2##n1.citrix.com1/AAAA/120/
5 1111:2345:6789:ffab:abcd:effa:1234:3212##n2.citrix.com1/A/120/2.1.1.2
6 ##n2.citrix.com1/AAAA/120/2222:faff:3212:8976:123:1241:64:ff9b##OPT
/0/1280/DO##

DNS error logging

You can configure a NetScaler appliance to log the errors or failures that occur when it processes a
DNS query or response. For these errors, the appliance logs the DNS header, Question sections and
OPT records.

Following is an example of a message logged when an error occurs during processing of a DNS request
or response:

1 DNS DNS_ERROR 149 0 : U:10.102.27.70#27832:10.102.27.73#53/61153/Q/

2 (RD)/NO/1/0/0/0#test.com./1140#Packet Dropped

Policy based logging

You can configure custom logging based on DNS expressions by configuring the logAction on DNS
policies, Rewrite, or Responder policies. You can specify that logging occurs only when a particular
DNS policy evaluates to true. For more information, see Configure policy based logging for DNS.

Understand the NetScaler syslog log message format

NetScaler appliance log DNS requests and responses in the following Syslog format:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2129

NetScaler 12.0

1 <transport> :<client IP>#<client ephemeral port>:<DNS endpoint IP>#<

port>
2 : <query id> /opcode/header flags/rcode/question section count/answer
section count
3 / auth section count / additional section count #<queried domain name>
4 /<queried type>#...

• <transport>:
– T = TCP
– U = UDP
• <client IP>#< client ephemeral port >:
DNS client IP address and port number
• <DNS endpoint IP>#<port>:
NetScaler DNS endpoint IP address and port number
• <query id>:
Query ID
• <opcode>:
Operation code. Supported Values:
– Q : query
– I : inverse query
– S: status
– X0: unassigned
– N : notify
– U : update
– X1-10: unassigned values
• <header flags>:
Flags. Supported Values:
– RD : recursion desired
– TC : truncated
– AA : authoritative response
– CD : check disabled
– AD : authenticated data
– Z : unassigned
– RA : recursion available
– R : response
• <rcode>:
Response Code. Supported Values:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2130

NetScaler 12.0

– NO : no error
– F format error
– S : server failure
– NX : non-existent domain
– NI : not implemented
– R: query refused
– YX : Name Exists when it should not
– YXR : RR Set Exists when it should not
– NXR: RR Set that should exist does not
– NAS : Server Not Authoritative for zone
– NA : Not Authorized
– NZ : Name not contained in zone
– X1-5: unassigned

• /question section count/answer section count/auth section count/additional section

count:
Question section, Authority section count, and Additional section count in the DNS request

• <queried domain name>/<queried type>:

Queried domain and queried type in the DNS request

• #ANS#<record type>/<ttl>/.. #AUTH#<domain name>/<record type>/<ttl>.. #ADD#<domain

name>/<record type>/<ttl>…:
In case of DNS responses:

Answer Section is logged if answer section logging is enabled in the DNS profile.
Authority and Additional sections are logged if extended logging is enabled in the DNS profile.
The log format would differ depending on the type of record. For more information see Under-
standing the Record Logging Format.

– ANS: answer section

– AUTH: authority
– ADD: Additional section

• OPT/<edns version>/UDP max payload size/DO:

OPT record format in the DNS log

• OPT/<EDNS version>/<UDP payload size>/<“DO”or empty based on whether DNSSEC OK

bit is set or not>/<value of RDLEN>/ECS/<Q/R>/<option length>/<Family>/<Source Prefix-
Length>/<Scope Prefix-Length>/<ECS Address>:
If the DNS query or response includes the EDNS Client Subnet (ECS) option, then that is also
logged in the OPT record format in the DNS log file.

When a DNS query with ECS option that includes either IPv4 or IPv6 address is sent, the ECS
option is logged with either “ECS/Q” indicating that the values in the log are from the query or

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2131

NetScaler 12.0

“ECS/R” indicating that the values in the log are from the response.

The value of Scope Prefix-Length is also set appropriately. In case of the DNS Query, it is set to
zero,and for response, it is set to the calculated value.

The following table describes the logged details in various scenarios:

ECS option set in the ECS option set in the

Scenario DNS Query DNS Response Logged Details

Both query logging Yes Yes ECS option is logged

and extended logging with the string
enabled “ECS/R/” and the
Scope Prefix-Length
is set to the
calculated value.
Both query logging Yes No ECS option is logged
and extended logging with the string
enabled “ECS/Q” and the
Scope Prefix-Length
is set to zero.
Query logging is Yes Yes ECS option is logged
enabled, but with the string
extended logging is “ECS/Q/” and the
not enabled Scope Prefix-Length
is set to zero.
Query logging & Yes Yes ECS option is not
extended logging are logged.
not enabled
Query logging is Yes No ECS option is logged
enabled, but with the string
extended logging is “ECS/Q/” and the
not enabled Scope Prefix-Length
is set to zero.
Query logging is not Yes Yes ECS option is logged
enabled, but with the string
extended logging is “ECS/R/” and the
enabled Scope Prefix-Length
is set to the
calculated value.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2132

NetScaler 12.0

ECS option set in the ECS option set in the

Scenario DNS Query DNS Response Logged Details

Query logging is not Yes No ECS option is not

enabled, but logged.
extended logging is
enabled

Understand the record logging format

Following is an example of the record logging format in a Syslog message:

1 <domainname>/<record type>/ <record ttl> / <resource record data>#<

resource record data>#......##

where:

Resource Record Data /

Record Type Sample Format Format

Address (A) record A/5/1.1.1.1#1.1.1.2#1.1.1.3## IPv4 address

AAAA record AAAA/5/1::1#1::2#1::3## IPv6 address
SOA record SOA/3600/ns1.dnslogging.test./root.dnslogging.test./100/3600/3/3600/5##
Origin server, contact, and
other details. Resource record
format is :
< originServer
>/<contact>/<serial
number>/<refresh
rate>/<retry>/<expire>/<minimum>##
NS record NS/5/ns1.dnslogging.test Host name of the nameserver.
MX record #MX/5/10/host1.dnslogging.test.#11/host2.dnslogging.test.##
Preference followed by mail
exchange server host name
CNAME record logging CNAME/5/host1.dnslogging.test.##
Canonical name
SRV record SRV/5/1/2/3/host1.dnslogging.test.#4/5/6/host2.dnslogging.test.##
Resource record format:
<priority>/<weight>/<port>/<target>#
TXT record TXT/5/dns+logging## Data comprises all the texts.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2133

NetScaler 12.0

Resource Record Data /

Record Type Sample Format Format

NAPTR record NAPTR/5/10/11////dnslogging#20/21/R/SIP//sip.dnslogging.test##

Resource record format:
<order>/<preference>/<flags>/<services>/<re
expression>/<replacement
string>#
DNSKEY record DNSKEY/5/1/3/5/AwEAAanP0K+i5bfv5SU478L760EjDjnPqI2Ccx6JZgiDBZhSONP
Resource record format:
<flags>/<protocol>/<algorithm>/<public
key in base64 encoding>#
PTR record PTR/3600/test.com.#test4.com.##
Domain name

Limitations of DNS logging

DNS logging has the following limitations:

• If response logging is enabled, only the following record types are logged:

– Address (A) record

– AAAA record
– SOA record
– NS record
– MX record
– CNAME record
– SRV record
– TXT record
– NAPTR record
– DNSKEY record
– PTR record

For all other record types, only L3/L4 parameters, DNS Header, and Question section are logged.

• RRSIG records are not logged even if response logging is enabled.

• DNS64 is not supported.

• DNS proactive update requests or responses are logged according to the settings in the default
profile.

• On the virtual server, if sessionless option and response logging is enabled, L3/L4 parameters,
DNS Header, and DNS Question section are logged instead of the response.

• The maximum size of the syslog message is 1024 bytes.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2134

NetScaler 12.0

• If you have set DNS profile for a DNS policy with action type Rewrite Response, NetScaler appli-
ance does not log the query or the manipulated responses. To log the required information you
need to use audit message action in the DNS policy.

• DNS transactions that are due to DNS monitoring traffic are not logged.

Configuring DNS logging

Following is an overview of configuring DNS logging:

1. Create a Syslog action and enable DNS in the action.

2. Create a Syslog policy and specify the Syslog action in the policy.
3. Globally bind the Syslog policy to enable logging of all NetScaler system events. Or, bind the
Syslog policy to a specific load balancing virtual server.
4. Create a DNS profile and define any of the following type of logging that you want to enable:
• DNS Query Logging
• DNS Answer Section Logging
• DNS Extended Logging
• DNS Error Logging
5. Configure any of the following, based on your requirement:
• DNS service and virtual server for DNS
• ADNS service
• NetScaler as a forwarder
• NetScaler as a resolver
6. Set the created DNS profile to one of the DNS entities.

Configure DNS logging for NetScaler configured as DNS Proxy by using the CLI

1. Add a syslog action and enable DNS in the action. At the command prompt, type:

1 add audit syslogAction <name> (<serverIP> | -lbVserverName <string

>) [-serverPort <port>] -logLevel <logLevel> ... [-dateFormat <
dateFormat>] [-logFacility <logFacility>] [-tcp ( NONE | ALL )]
[-acl ( ENABLED | DISABLED )] [-timeZone ( GMT_TIME |
LOCAL_TIME )] [-userDefinedAuditlog ( YES | NO )] [-
appflowExport ( ENABLED |DISABLED )] [-lsn ( ENABLED | DISABLED
)] [-alg ( ENABLED | DISABLED )] [-transport ( TCP | UDP )] [-
tcpProfileName <string>] [-maxLogDataSizeToHold <
positive_integer>] [-dns ( ENABLED | DISABLED)]

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2135

NetScaler 12.0

add audit syslogAction nssyslogact1 10.102.151.136 -logLevel CRITICAL

ERROR WARNING NOTICE INFORMATIONAL DEBUG -logFacility LOCAL4 -timeZone
LOCAL_TIME -dns ENABLED

2. Create a syslog policy and specify the created syslog action in the policy. At the command
prompt, type:

add audit syslogPolicy <name> <rule> <action>

Example:

add audit syslogPolicy syslogpol1 ns_true nssyslogact1

3. Bind the syslog policy globally. At the command prompt, type:

bind system global [<policyName> [-priority <positive_integer>]]

Example:

bind system global syslogpol1

4. Create a DNS profile and enable any of the following type of logs that you want to configure:

• DNS Query Logging

• DNS Answer Section Logging
• DNS Extended Logging
• DNS Error Logging

At the command prompt, type:

add dns profile <dnsProfileName> [-dnsQueryLogging ( ENABLED | DISABLED

)] [-dnsAnswerSecLogging ( ENABLED | DISABLED )] [-dnsExtendedLogging
(ENABLED | DISABLED )] [-dnsErrorLogging ( ENABLED | DISABLED )] [-
cacheRecords ( ENABLED | DISABLED )] [-cacheNegativeResponses ( ENABLED
| DISABLED )]

Example:

add dns profile dnsprofile1 -dnsQueryLogging ENABLED

5. Configure service of type DNS. At the command prompt, type:

add service <name> <serverName> <serviceType> <port>

Example:

add service svc1 10.102.84.140 dns 53

6. Configure a load balancing virtual server of service type DNS.

add lb vserver <name> <serviceType> <ip> <port>

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2136

NetScaler 12.0

add lb vserver lb1 dns 100.100.100.10 53

7. Bind the service to the virtual server. At the command prompt, type:

bind lb vserver <name> <serviceName>

Example:

bind lb vserver lb1 svc1

8. Set the created DNS profile to the virtual server. At the command prompt, type:

set lb vserver <name> [ - dnsProfileName <string>]

Example:

set lb vserver lb1 ‒dnsProfileName dnsprofile1

Sample DNS logging configuration for NetScaler appliance configured as DNS proxy

1 > add audit syslogAction nssyslogact1 10.102.151.136 -logLevel

2 CRITICAL ERROR WARNING NOTICE INFORMATIONAL DEBUG -logFacility LOCAL4 -
timeZone
3 LOCAL_TIME -dns ENABLED
4 Done
5 > add audit syslogPolicy syslogpol1 ns_true nssyslogact1
6 Done
7 > bind system global syslogpol1
8 Done
9 > add dns profile dnsprofile1 -dnsqueryLogging ENABLED
10 Done
11 > add lb vserver lb1 dns 100.100.100.10 53 ‒ dnsProfileName dnsprofile1
12 Done
13 > add service svc1 10.102.84.140 dns 53
14 Done
15 > bind lb vserver lb1 svc1
16 Done

Sample DNS logging configuration for NetScaler appliance configured as ADNS

1 > add audit syslogAction nssyslogact1 10.102.151.136 -logLevel CRITICAL

2 ERROR WARNING NOTICE INFORMATIONAL DEBUG -logFacility LOCAL4 -timeZone
LOCAL_TIME
3 -dns ENABLED
4 Done
5 > add audit syslogPolicy syslogpol1 ns_true nssyslogact1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2137

NetScaler 12.0

6 Done
7 > bind system global syslogpol1
8 Done
9 > add dns profile dnsprofile1 -dnsqueryLogging ENABLED
10 Done
11 > add lb vserver lb1 dns 100.100.100.10 53 ‒ dnsProfileName dnsprofile1
12 Done
13 > add service svc1 10.102.84.140 dns 53
14 Done
15 > bind lb vserver lb1 svc1
16 Done

Sample DNS logging configuration for NetScaler appliance configured as a forwarder

1 > add audit syslogAction nssyslogact1 10.102.151.136 -logLevel CRITICAL

2 ERROR WARNING NOTICE INFORMATIONAL DEBUG -logFacility LOCAL4 -timeZone
LOCAL_TIME
3 -dns ENABLED
4 Done
5 > add audit syslogPolicy syslogpol1 ns_true nssyslogact1
6 Done
7 > bind system global syslogpol1
8 Done
9 > add dns profile dnsprofile1 -dnsqueryLogging ENABLED
10 Done
11 > add dns nameserver 8.8.8.8 ‒ dnsProfileName dnsprofile1
12 Done

Sample DNS logging configuration for NetScaler appliance configured as a sesolver

1 > add audit syslogAction nssyslogact1 10.102.151.136

2 -logLevel CRITICAL ERROR WARNING NOTICE INFORMATIONAL DEBUG -
logFacility LOCAL4
3 -timeZone LOCAL_TIME -dns ENABLED
4 Done
5 > add audit syslogPolicy syslogpol1 ns_true nssyslogact1
6 Done
7 > bind system global syslogpol1
8 Done
9 > add dns profile dnsprofile1 -dnsqueryLogging ENABLED
10 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2138

NetScaler 12.0

11 > set dns parameter -recursion enABLED

12 Done
13 > add nameserver 1.1.1.100 -local dnsProfileName dnsprofile1
14 Done

Configure policy based logging for DNS

Policy based logging enables you to specify a format for log messages. The contents of a log message
are defined by using a default syntax expression. When the message action specified in the policy is
performed, the NetScaler appliance constructs the log message from the expression and writes the
message to the log file. You can configure the appliance to log only when a particular DNS policy
evaluates to True.
Note

If you have set a DNS policy with a DNS profile for the request side, NetScaler appliance logs only
the query.

To configure policy based logging for a DNS policy, you must first configure an audit message action.
For more information about configuring an audit message action, see
Configure the NetScaler appliance for audit logging. After configuring the audit message action, spec-
ify the message action in a DNS policy.

Configure policy based logging for a DNS policy by using the CLI

At the command prompt, type the following commands to configure policy based logging for a DNS
policy and verify the configuration:

1 - add dns action <actionName> <actionType> [-IPAddress <ip_addr|

ipv6_addr> ... | -viewName <string> | -preferredLocList <string>
...] [-TTL <secs>] [-dnsProfileName <string>]
2 - set dns policy <name> [<rule>] [-actionName <string>] [-logAction <
string>]
3 - show dns policy [<name>]

Example 1:

In a GSLB deployment, if you want to respond with different IP addresses to the client requests coming
from a particular subnet, instead of responding with IP addresses used for general purposes (such as
the IP addresses of internal users), you can configure a DNS policy with the action type as DNS view. In
this case, you can configure DNS logging on the specified DNS action such that you can log the specific
responses.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2139

NetScaler 12.0

1> add dns profile dns_prof1 -dnsqueryLogging enABLED -

dnsanswerSecLogging enABLED
2 Done
3 > add dns view dns_view1
4 Done
5 > add dns action dns_act1 viewName -view dns_view1 ‒ dnsprofilename
dns_prof1
6 Done
7 > add dns policy dns_pol1 ”CLIENT.IP.SRC.APPLY_MASK(255.255.255.0).EQ
(100.100.100.0) ”
8 dns_act1
9 Done
10 > bind dns global dns_pol1 100 -gotoPriorityExpression END -type
REQ_DEFAULT
11 Done
12 > bind gslb service site_1_svc -viewName dns_view1 123.1.1.1
13 Done
14 > bind gslb service site_5_svc -view dns_view1 132.1.1.1
15 Done

Note: In the above configuration, if you query for the domain configured on a GSLB virtual server, for
example,
sampletest.com, all the internal users of subnet 100.100.100.0/24 are served with the DNS view IP ad-
dresses, and the responses are logged. Client requests for other subnets are not logged.

Example 2:

If you want to log only the queries for the domain

example.com, you can create a DNS profile with query logging enabled and set the DNS profile to a
DNS action with the action type
NOOP, and then create a DNS policy and set the DNS action. For example:

1 >add dns profile query_logging -dnsqueryLogging ENABLED

2 Done
3 >add dns action dns_act1 NOOP -dnsprofileName query_logging
4 Done
5 >add dns policy dns_pol1 DNS.REQ.QUESTION.DOMAIN.EQ(”example.com”)
dns_act1
6 Done

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2140

NetScaler 12.0

Configuring DNS suffixes

September 11, 2018

Contributed by:
C

You can configure DNS suffixes that enable the NetScaler appliance to complete non-fully qualified
domain names (non-FQDNs) during name resolution. For example, during the process of resolving
the domain name abc (which is not fully qualified), if a DNS suffix example.com is configured, the
appliance appends the suffix to the domain name (abc.example.com) and resolves it. If DNS suffixes
are not configured, the appliance appends a period to the non-FQDNs and resolves the domain name.

Create DNS suffixes

DNS suffixes have significance and are valid only when the NetScaler is configured as an end resolver
or forwarder. You can specify a suffix of up to 127 characters.

Create DNS suffixes by using the CLI

At the command prompt, type the following commands to create a DNS suffix and verify the configu-
ration:

1 - add dns suffix <dnsSuffix>

2 - show dns suffix <dnsSuffix>

Example:

1 > add dns suffix example.com

2 Done
3 > show dns suffix example.com
4 1) Suffix: example.com
5 Done

To remove a DNS suffix by using the NetScaler command line, at the NetScaler command prompt, type
the rm dns suffix command and the name of the DNS suffix.

Create DNS suffixes by using the GUI

Navigate to Traffic Management > DNS > DNS Suffix and create DNS suffixes.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2141

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0

DNS ANY query

September 11, 2018

Contributed by:
C

An ANY query is a type of DNS query that retrieves all records available for a domain name. The ANY
query must be sent to a name server that is authoritative for a domain.

Behavior in ADNS mode

In the ADNS mode, the NetScaler appliance returns the records held in its local cache. If there are no
records in the cache, the appliance returns the NXDOMAIN (negative) response.

If the NetScaler can match the domain delegation records, it returns the NS records. Otherwise, it
returns the NS records of the root domain.

Behavior in DNS proxy mode

In proxy mode, the NetScaler appliance checks its local cache. If there are no records in the cache, the
appliance passes the query to the server.

Behavior for GSLB domains

If a GSLB domain is configured on the NetScaler appliance and an ANY query is sent for the GSLB do-
main (or GSLB site domain), the appliance returns the IP address of the GSLB service that it selects
through the Load Balancing decision. If the multiple IP response (MIR) option is enabled, the IP ad-
dresses of all GSLB services are sent.

For the NetScaler to return these records when it responds to the ANY query, all records corresponding
to a GSLB domain must be configured on the NetScaler.

Note

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2142

NetScaler 12.0

If records for a domain are distributed between the NetScaler and a server, only records config-
ured on the NetScaler are returned.
The NetScaler provides the option to configure DNS views and DNS policies. These are used for per-
forming global server load balancing. For more information, see Global Server Load Balancing.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure negative caching of DNS records

September 11, 2018

Contributed by:
C

The NetScaler appliance supports caching of negative responses for a domain. A negative response
indicates that information about a requested domain does not exist, or that the server cannot provide
an answer for the query. The storage of this information is called negative caching. Negative caching
helps speed up responses to queries about a domain.

Note:

Negative caching is supported only when the back-end server is configured as an authoritative
DNS (ADNS) server for the queried domain.

A negative response can be one of the following:

• NXDOMAIN error message—If a negative response is present in the local cache, the NetScaler
returns an error message (NXDOMAIN). If the response is not in the local cache, the query is
forwarded to the server, and the server returns an NXDOMAIN error to the NetScaler appliance.
The appliance caches the response locally, then returns the error message to the client.
• NODATA error message—If the domain name in query is valid but records of the given type are
not available, the appliance sends a NODATA error message.

When negative caching is enabled, the appliance caches the negative response from the DNS server
and serves the future requests from the cache only. This helps speed up responses to queries and also
to reduce the DNS traffic. Negative caching can be used in all deployments, that is, when a NetScaler
appliance is serving as a proxy, as an end resolver, or as a forwarder.

You can enable or disable negative caching using DNS profile, for more information see, DNS profiles.
By default, negative caching is enabled in the default DNS profile (default-dns-profile) that are bound
by default to a DNS virtual server or in the newly created DNS profile.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2143

NetScaler 12.0

Enable or disable negative caching by using the CLI

At the command prompt, type the following commands to enable or disable negative caching and
verify the configuration:

1 - add dns profile <dnsProfileName> [-cacheRecords ( ENABLED | DISABLED

)] [-cacheNegativeResponses (ENABLED | DISABLED )]
2 - show dns profile [<dnsProfileName>]

Example of a default DNS profile:

1 > sh dns profile default-dns-profile

2 1) default-dns-profile
3 Query logging : DISABLED Answer section logging :
DISABLED
4 Extended logging : DISABLED Error logging : DISABLED
5 Cache Records : ENABLED Cache Negative Responses: ENABLED
6 Done

Example of a newly created DNS profile:

1 > add dnsprofile dns_profile1 -cacheRecords ENABLED -

cacheNegativeResponses ENABLED
2 Done
3 > show dns profile dns_profile1
4 1) dns_profile1
5 Query logging : DISABLED Answer section logging :
DISABLED
6 Extended logging : DISABLED Error logging : DISABLED
7 Cache Records : ENABLED Cache Negative Responses: ENABLED
8 Done

Specify service or virtual server level DNS parameters by using the CLI

At the command prompt, perform the following:

1. Configure the DNS profile.

add dns profile <dnsProfileName> [-cacheRecords ( ENABLED | DISABLED )]

[-cacheNegativeResponses (ENABLED | DISABLED )]

2. Bind the DNS profile to the service or virtual server.

To bind the DNS profile to the service:

set service <name> [-dnsProfileName <string>]

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2144

NetScaler 12.0

Example:

1 >set service service1 -dnsProfileName dns_profile1

2 Done

To bind the DNS profile to the virtual server:

set lb vserver <name> [-dnsProfileName <string>]

Example:

1 >set lb vserver lbvserver1 -dnsProfileName dns_profile1

2 Done

Specify service or virtual server level DNS parameters by using the GUI

1. Configure the HTTP profile.

Navigate to System > Profiles> DNS Profile, and create the DNS profile.

2. Bind the HTTP profile to the service or virtual server.

Navigate to Traffic Management > Load Balancing> Services/Virtual Servers, and create the
DNS profile, which should be bound to the service/virtual server.

1.
2. Citrix ADC
3. NetScaler 12.0

Cache EDNS0 client subnet data when the NetScaler appliance is in

proxy mode

January 6, 2019

Contributed by:
C

In NetScaler Proxy mode, if a back-end server that supports EDNS0 Client Subnet (ECS) sends a re-
sponse containing the ECS option, the NetScaler appliance forwards the response as-is to the client
and stores it in the cache, along with the client subnet information. Further DNS requests that are
from the same subnet of the same domain, and for which the server would send the same response,
are then served from the cache instead of being directed to the server.

Note:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2145

NetScaler 12.0

• ECS caching is disabled by default. You have to enable caching of EDNS0 client-subnet data in
the associated DNS profile.
• The number of subnets that you can cache for a domain is limited to the available subnet IDs,
that is, 1270 in the NetScaler appliance. Optionally, you can set the limit to a lower number
(minimum value: 1 ipv4/ipv6).

Enable caching of ECS responses by using the CLI

At the command prompt, type:

set dns profile <dnsProfileName> -cacheECSSubnet ( ENABLED | DISABLED )

Limit the number of subnets that can be cached per domain by using the CLI

At the command prompt, type:

set dns profile <dnsProfileName> -maxSubnetsPerDomain <positive_integer>

Example:

In the example shown in the above figure, the client at IP address 2.2.2.2 sends a query for
www.example.com to the DNS resolver, and the DNS resolver sends the following response:

www.example.com IN A, IP is 2.2.2.11, and ECS 2.2.2.0/24/24

At this point, the response and the client-subnet identifier (2.2.2.0/24) are cached. Further requests
from the same subnet and domain will be served from the cache.

For example, if the client’s IP address is 2.2.2.100 and the query is for www.example.com, the query is
served from the cache instead of being sent to the backend server.

1.
2. Citrix ADC
3. NetScaler 12.0

Domain name system security extensions

September 12, 2018

Contributed by:
C

DNS Security Extensions (DNSSEC) is an Internet Engineering Task Force (IETF) standard that aims
to provide data integrity and data origin authentication in communications between name servers

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2146

NetScaler 12.0

and clients while still transmitting User Datagram Protocol (UDP) responses in clear text. DNSSEC
specifies a mechanism that uses asymmetric key cryptography and a set of new resource records that
are specific to its implementation.

The DNSSEC specification is described in RFC 4033, “DNS Security Introduction and Requirements,”
RFC 4034, “Resource Records for the DNS Security Extensions,” and RFC 4035, “Protocol Modifications
for the DNS Security Extensions.” The operational aspects of implementing DNSSEC within DNS are
discussed in RFC 4641, “DNSSEC Operational Practices.”

You can configure DNSSEC on the NetScaler ADC. You can generate and import keys for signing DNS
zones. You can configure DNSSEC for zones for which the NetScaler is authoritative. You can configure
the ADC as a DNS proxy server for signed zones hosted on a farm of backend name servers. If the ADC
is authoritative for a subset of the records belonging to a zone for which the ADC is configured as a
DNS proxy server, you can include the subset of records in the DNSSEC implementation.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure DNSSEC

September 14, 2018

Contributed by:
C

Configuring DNSSEC involves enabling DNSSEC on the NetScaler ADC appliance, creating a Zone Sign-
ing Key and a Key Signing Key for the zone, adding the two keys to the zone, and then signing the zone
with the keys.

The NetScaler appliance does not act as a DNSSEC resolver. DNSSEC on the ADC is supported only in
the following deployment scenarios:

1. ADNS—NetScaler is the ADNS and generates the signatures itself.

2. Proxy—NetScaler acts as a DNSSEC proxy. It is assumed that the NetScaler is placed in front of
the ADNS/LDNS servers in a trusted mode. The ADC acts only as a proxy caching entity and does
not validate any signatures.

Enable and disable DNSSEC

You must enable DNSSEC on the NetScaler for the ADC to respond to DNSSEC-aware clients. By de-
fault, DNSSEC is enabled.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2147

NetScaler 12.0

You can disable the DNSSEC feature if you do not want the NetScaler to respond to clients with
DNSSEC-specific information.

Enable or disable DNSSEC by using the CLI

At the command prompt, type the following commands to enable or disable DNSSEC and verify the
configuration:

1 - set dns parameter -dnssec ( ENABLED | DISABLED )

2 - show dns parameter

Example:

1 > set dns parameter -dnssec ENABLED

2 Done
3 > show dns parameter
4 DNS parameters:
5 DNS retries: 5
6 .
7 .
8 .
9 DNSEC Extension: ENABLED
10 Max DNS Pipeline Requests: 255
11 Done

Enable or disable DNSSEC by using the GUI

1. Navigate to Traffic Management > DNS.

2. In the details pane, click Change DNS settings.
3. In the Configure DNS Parameters dialog box, select or clear the Enable DNSSEC Extension check
box.

Create DNS keys for a zone

For each DNS zone that you want to sign, you must create two pairs of asymmetric keys. One pair,
called the Zone Signing Key, is used to sign all the resource record sets in the zone. The second pair is
called the Key Signing Key and is used to sign only the DNSKEY resource records in the zone.

When the Zone Signing Key and Key Signing Key are created, the suffix .key is automatically appended
to the names of the public components of the keys and the suffix .private is automatically appended
to the names of their private components.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2148

NetScaler 12.0

Additionally, the NetScaler also creates a Delegation Signer (DS) record and appends the suffix .ds to
the name of the record. If the parent zone is a signed zone, you must publish the DS record in the
parent zone to establish the chain of trust.
When you create a key, the key is stored in the /nsconfig/dns/ directory, but it is not automatically
published in the zone. After you create a key by using the create dns key command, you must explic-
itly publish the key in the zone by using the add dns key command. The process of generating a key
has been separated from the process of publishing the key in a zone to enable you to use alternative
means to generate keys. For example, you can import keys generated by other key-generation pro-
grams (such as bind-keygen) by using Secure File Transfer Protocol (SFTP) and then publish the keys
in the zone. For more information about publishing a key in a zone, see Publish a DNS key in a zone.
Perform the steps described in this topic to create a Zone Signing Key and then repeat the steps to
create a Key Signing Key. The example that follows the command syntax first creates a Zone Signing
Key pair for the zone example.com. The example then uses the command to create a Key Signing Key
pair for the zone.

Create a DNS key by using the CLI

At the NetScaler command prompt, type the following command to create a DNS key:
create dns key -zoneName <string> -keyType <keyType> -algorithm RSASHA1 -
keySize <positive_integer> -fileNamePrefix <string>

Example:

1 > create dns key -zoneName example.com -keyType zsk -algorithm RSASHA1
-keySize 1024 -fileNamePrefix example.com.zsk.rsasha1.1024
2 File Name: /nsconfig/dns/example.com.zsk.rsasha1.1024.key (public); /
nsconfig/dns/example.com.zsk.rsasha1.1024.private (private); /
nsconfig/dns/example.com.zsk.rsasha1.1024.ds (ds)
3 This operation may take some time, Please wait...
4 Done
5 > create dns key -zoneName example.com -keyType ksk -algorithm RSASHA1
-keySize 4096 -fileNamePrefix example.com.ksk.rsasha1.4096
6 File Name: /nsconfig/dns/example.com.ksk.rsasha1.4096.key (public); /
nsconfig/dns/example.com.ksk.rsasha1.4096.private (private); /
nsconfig/dns/example.com.ksk.rsasha1.4096.ds (ds)
7 This operation may take some time, Please wait...
8 Done

Create a DNS key by using the GUI

1. Navigate to Traffic Management > DNS.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2149

NetScaler 12.0

2. In the details area, click Create DNS Key and create a DNS key.
Note: For
File Name Prefix, if you want to modify the file name prefix of an existing key, click the arrow
next to the
Browse button, click either
Local or
Appliance (depending on whether the existing key is stored on your local computer or in the
/nsconfig/dns/ directory on the appliance), browse to the location of the key, and then double-
click the key. The
File Name Prefix box is populated with only the prefix of the existing key. Modify the prefix ac-
cordingly.

Publish a DNS key in a zone

A key (Zone Signing Key or Key Signing Key) is published in a zone by adding the key to the NetScaler.
A key must be published in a zone before you sign the zone.

Before you publish a key in a zone, the key must be available in the /nsconfig/dns/ directory. There-
fore, if you used other means to generate the key—means other than the create dns key command
on the NetScaler (for example, by using the bind-keygen program on another computer)—make sure
that the key is added to the /nsconfig/dns/ directory before you publish the key in the zone.

If the key has been generated by another program, you can import the key to your local computer and
use the NetScaler configuration utility to add the key to the /nsconfig/dns/ directory. Or, you can use
other means to import the key to the directory, such as the Secure File Transfer Protocol (SFTP).

You must use the add dns key command for each public-private key pair that you want to publish in
a given zone. If you created a Zone Signing Key pair and a Key Signing Key pair for a zone, use the
add dns key command to first publish one of the key pairs in the zone and then repeat the command
to publish the other key pair. For each key that you publish in a zone, a DNSKEY resource record is
created in the zone.

The example that follows the command syntax first publishes the Zone Signing Key pair (that was
created for the example.com zone) in the zone. The example then uses the command to publish the
Key Signing Key pair in the zone.

Publish a key in a zone by using the CLI

At the command prompt, type the following command to publish a key in a zone and verify the con-
figuration:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2150

NetScaler 12.0

1 - add dns key <keyName> <publickey> <privatekey> [-expires <

positive_integer> [<units>]] [-notificationPeriod <positive_integer>
[<units>]] [-TTL <secs>]
2 - show dns zone [<zoneName> | -type <type>]

Example:

1> add dns key example.com.zsk example.com.zsk.rsasha1.1024.key example.

com.zsk.rsasha1.1024.private
2 Done
3 > add dns key example.com.ksk example.com.ksk.rsasha1.4096.key example.
com.ksk.rsasha1.4096.private
4 Done
5 > show dns zone example.com
6 Zone Name : example.com
7 Proxy Mode : NO
8 Domain Name : example.com
9 Record Types : NS SOA DNSKEY
10 Domain Name : ns1.example.com
11 Record Types : A
12 Domain Name : ns2.example.com
13 Record Types : A
14 Done

Publish a key in a DNS zone by using the GUI

Navigate to
Traffic Management > DNS > Keys.

Note: For
Public Key and
Private Key, to add a key that is stored on your local computer, click the arrow next to the
Browse button, click
Local, browse to the location of the key, and then double-click the key.

Configure a DNS key

You can configure the parameters of a key that has been published in a zone. You can modify the key’s
expiry time period, notification period, and time-to-live (TTL) parameters. If you change the expiry
time period of a key, the NetScaler automatically re-signs all the resource records in the zone with the
key, provided that the zone is currently signed with the particular key.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2151

NetScaler 12.0

Configure a key by using the CLI

At the command prompt, type the following command to configure a key and verify the configuration:

1 - set dns key <keyName> [-expires <positive_integer> [<units>]] [-

notificationPeriod <positive_integer> [<units>]] [-TTL <secs>]
2 - show dns key [<keyName>]

Example:

1 > set dns key example.com.ksk -expires 30 DAYS -notificationPeriod 3

DAYS -TTL 3600
2 Done
3 > show dns key example.com.ksk
4 1) Key Name: example.com.ksk
5 Expires: 30 DAYS Notification: 3 DAYS TTL: 3600
6 Public Key File: example.com.ksk.rsasha1.4096.key
7 Private Key File: example.com.ksk.rsasha1.4096.private
8 Done

Configure a key by using the GUI

1. Navigate to Traffic Management > DNS > Keys.

2. In the details pane, click the key that you want to configure, and then click Open.

3. In the Configure DNS Key dialog box, modify the values of the following parameters as shown:

• Expires—expires
• Notification Period—notificationPeriod
• TTL—TTL

4. Click OK.

Sign and unsign a DNS zone

To secure a DNS zone, you must sign the zone with the keys that have been published in the zone.
When you sign a zone, the NetScaler creates a Next Secure (NSEC) resource record for each owner
name. Then, it uses the Key Signing Key to sign the DNSKEY resource record set. Finally, it uses the
Zone Signing Key to sign all the resource record sets in the zone, including the DNSKEY resource record
sets and NSEC resource record sets. Each sign operation results in a signature for the resource record
sets in the zone. The signature is captured in a new resource record called the RRSIG resource record.

After you sign a zone, you must save the configuration.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2152

NetScaler 12.0

Sign a zone by using the CLI

At the command prompt, type the following command to sign a zone and verify the configuration:

1 - sign dns zone <zoneName> [-keyName <string> ...]

2 - show dns zone [<zoneName> | -type (ADNS | PROXY | ALL)]
3 - save config

Example:

1 > sign dns zone example.com -keyName example.com.zsk example.com.ksk

2 Done
3 > show dns zone example.com
4 Zone Name : example.com
5 Proxy Mode : NO
6 Domain Name : example.com
7 Record Types : NS SOA DNSKEY RRSIG NSEC
8 Domain Name : ns1.example.com
9 Record Types : A RRSIG NSEC
10 Domain Name : ns2.example.com
11 Record Types : A RRSIG
12 Domain Name : ns2.example.com
13 Record Types : RRSIG NSEC
14 Done
15 > save config
16 Done

Unsign a zone by using the CLI

At the command prompt, type the following command to unsign a zone and verify the configuration:

1 - unsign dns zone <zoneName> [-keyName <string> ...]

2 - show dns zone [<zoneName> | -type (ADNS | PROXY | ALL)]

Example:

1 > unsign dns zone example.com -keyName example.com.zsk example.com.ksk

2 Done
3 > show dns zone example.com
4 Zone Name : example.com
5 Proxy Mode : NO
6 Domain Name : example.com
7 Record Types : NS SOA DNSKEY
8 Domain Name : ns1.example.com

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2153

NetScaler 12.0

9 Record Types : A
10 Domain Name : ns2.example.com
11 Record Types : A
12 Done

Sign or unsign a zone by using the GUI

1. Navigate to Traffic Management > DNS > Zones.

2. In the details pane, click the zone that you want to sign, and then click Sign/Unsign.
3. In the Sign/Unsign DNS Zone dialog box, do one of the following:
• To sign the zone, select the check boxes for the keys (Zone Signing Key and Key Signing
Key) with which you want to sign the zone.
You can sign the zone with more than one Zone Signing Key or Key Signing Key pair.
• To unsign the zone, clear the check boxes for the keys (Zone Signing Key and Key Signing
Key) with which you want to unsign the zone.
You can unsign the zone with more than one Zone Signing Key or Key Signing Key pair.
4. Click OK.

View the NSEC records for a given record in a zone

You can view the NSEC records that the NetScaler automatically creates for each owner name in the
zone.

View the NSEC record for a given record in a zone by using the CLI

At the command prompt, type the following command to view the NSEC record for a given record in
a zone:

show dns nsecRec [<hostName> | -type (ADNS | PROXY | ALL)]

Example:

1 > show dns nsecRec example.com

2 1) Domain Name : example.com
3 Next Nsec Name: ns1.example.com
4 Record Types : NS SOA DNSKEY RRSIG NSEC
5 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2154

NetScaler 12.0

View the NSEC record for given record in a zone by using the GUI

1. Navigate to Traffic Management > DNS > Records > Next Secure Records.
2. In the details pane, click the name of the record for which you want to view the NSEC record.
The NSEC record for the record you select is displayed in the Details area.

Remove a DNS key

You remove a key from the zone in which it is published when the key has expired or if the key has been
compromised. When you remove a key from the zone, the zone is automatically unsigned with the
key. Removing the key with this command does not remove the key files present in the /nsconfig/dns/
directory. If the key files are no longer needed, they have to be explicitly removed from the directory.

Remove a key from the NetScaler by using the CLI

At the command prompt, type the following command to remove a key and verify the configuration:

1 - rm dns key <keyName>

2 - show dns key <keyName>

Example:

1 > rm dns key example.com.zsk

2 Done
3 > show dns key example.com.zsk
4 ERROR: No such resource [keyName, example.com.zsk]

Remove a key from the NetScaler by using the GUI

1. Navigate to Traffic Management > DNS > Keys.

2. In the details pane, click the name of the key that you want to remove from the ADC, and then
click Remove.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2155

NetScaler 12.0

Configure DNSSEC when the NetScaler is authoritative for a zone

September 14, 2018

Contributed by:
C

When the NetScaler ADC is authoritative for a given zone, all the resource records in the zone are con-
figured on the ADC. To sign the authoritative zone, you must create keys (the Zone Signing Key and the
Key Signing Key) for the zone, add the keys to the ADC, and then sign the zone, as described in Create
DNS keys for a zone, Publish a DNS key in a zone, and Sign and unsign a DNS zone, respectively.

If any global server load balancing (GSLB) domains configured on the ADC belong to the zone being
signed, the GSLB domain names are signed along with the other records that belong to the zone.

After you sign a zone, responses to requests from DNSSEC-aware clients include the RRSIG resource
records along with the requested resource records. DNSSEC must be enabled on the ADC. For more
information about enabling DNSSEC, see Enable and disable DNSSEC.

Finally, after you configure DNSSEC for the authoritative zone, you must save the NetScaler configu-
ration.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure DNSSEC for a zone for which the NetScaler is a DNS proxy
server

October 24, 2018

Contributed by:
C

The procedure for signing a zone for which the NetScaler ADC is configured as a DNS proxy server
depends on whether or not the ADC owns a subset of the zone information owned by the backend
name servers. If it does, the configuration is considered a partial zone ownership configuration. If the
ADC does not own a subset of the zone information, the NetScaler configuration for managing the
backend servers is considered a zone-less DNS proxy server configuration. The basic DNSSEC configu-
ration tasks for both NetScaler configurations are the same. However, signing the partial zone on the
NetScaler requires some additional configuration steps.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2156

NetScaler 12.0

Note: The terms

zone-less proxy server configuration and
partial zone are used only in the context of the NetScaler appliance.

Important: When configured in proxy mode, the ADC does not perform signature verification on
DNSSEC responses before updating the cache.

If you configure the ADC as a DNS proxy to load balance DNSSEC aware resolvers (servers), you must
set the Recursion Available option while configuring the DNS virtual server. If a DNSSEC query arrives
with Checking Disabled (CD) bit set, the query is passed on to the server with the CD bit retained, and
the response from the server is not cached. In releases prior to 10.5.e build xx.x, the ADC unset the CD
bit before passing it to the server and also cached the server response.

Configure DNSSEC for a zone-less DNS proxy server configuration

For a zone-less DNS proxy server configuration, zone signing must be performed on the backend name
servers. On the NetScaler, you configure the ADC as a DNS proxy server for the zone. You create a load
balancing virtual server of protocol type DNS, configure services on the ADC to represent the name
servers, and then bind the services to the load balancing virtual server. For more information about
these configuration tasks, see Configure the NetScaler as a DNS proxy server.

When a client sends the ADC a DNS request with the DNSSEC OK (DO) bit set, the ADC checks its cache
for the requested information. If the resource records are not available in its cache, the ADC forwards
the request to one of the DNS name servers, and then relays the response from the name server to
the client. Additionally, the ADC caches the RRSIG resource records along with the response from the
name server. Subsequent requests from DNSSEC-aware clients are served from the cache (including
the RRSIG resource records), subject to the time-to-live (TTL) parameter. If a client sends a DNS re-
quest without setting the DO bit, the ADC responds with only the requested resource records, and
does not include the RRSIG resource records that are specific to DNSSEC.

Configure DNSSEC for a partial zone ownership configuration

In some NetScaler configurations, even though the authority for a zone lies with the backend name
servers, a subset of the resource records that belong to the zone might be configured on the NetScaler.
The ADC owns (or is authoritative for) only this subset of records. Such a subset of records can be
considered to constitute a partial zone on the ADC. The ADC owns the partial zone. All other records
are owned by the backend name servers.

A typical partial zone configuration on the NetScaler is seen when global server load balancing (GSLB)
domains are configured on the ADC, and the GSLB domains are a part of a zone for which the backend
name servers are authoritative.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2157

NetScaler 12.0

Signing a zone that includes only a partial zone on the ADC involves including the partial zone infor-
mation in the backend name server zone files, signing the zone on the backend name servers, and
then signing the partial zone on the ADC. The same key set must be used to sign the zone on the name
servers and the partial zone on the ADC.

Sign the zone on the backend name servers

1. Include the resource records that are contained in the partial zone, in the zone files of the name
servers.
2. Create keys and use the keys to sign the zone on the backend name servers.

Sign the partial zone on the NetScaler

1. Create a zone with the name of the zone that is owned by the backend name servers. When
configuring the partial zone, set the proxyMode parameter to YES. This zone is the partial zone
that contains the resource records owned by the ADC.
For example, if the name of the zone that is configured on the backend name servers is exam-
ple.com, you must create a zone named example.com on the ADC, with the proxyMode param-
eter set to YES. For more information about adding a zone, see Configure a DNS zone.
Note

Do not add SOA and NS records for the zone. These records should not exist on the ADC
for a zone for which the ADC is not authoritative.
2. Import the keys (from one of the backend name servers) to the ADC and then add them to the /n-
sconfig/dns/ directory. For more information about how you can import a key and add it to the
ADC, see Publish a DNS key in a zone.
3. Sign the partial zone with the imported keys. When you sign the partial zone with the keys,
the ADC generates RRSIG and NSEC records for the resource record sets and individual resource
records in the partial zone, respectively. For more information about signing a zone, see sign
and unsign a DNS zone.
1.
2. Citrix ADC
3. NetScaler 12.0

Configure DNSSEC for GSLB domain names

September 14, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2158

NetScaler 12.0

Contributed by:
C
If global server load balancing (GSLB) is configured on the NetScaler ADC and the ADC is authoritative
for the zone to which the GSLB domain names belong, all GLSB domain names are signed when the
zone is signed. For more information about signing a zone for which the ADC is authoritative, see
Configure DNSSEC when the NetScaler appliance is authoritative for a zone.
If the GSLB domains belong to a zone for which the backend name servers are authoritative, you must
first sign the zone on the name servers, and then sign the partial zone on the ADC to complete the
DNSSEC configuration for the zone. For more information, see Configure DNSSEC for a partial zone
ownership configuration.
1.
2. Citrix ADC
3. NetScaler 12.0

Zone Maintenance

September 14, 2018

Contributed by:
C
From a DNSSEC perspective, zone maintenance involves rolling over Zone Signing Keys and Key Sign-
ing Keys when key expiry is imminent. These zone maintenance tasks have to be performed manually.
The process of re-signing a zone is performed automatically and does not require manual interven-
tion.

Re-sign an updated zone

When a zone is updated, that is, when new records are added to the zone or existing records are
changed, the process of re-signing the new (or modified) record is performed automatically by the
NetScaler ADC. If a zone contains multiple Zone Signing Keys, the ADC re-signs the new (or modified)
record with the key with which the zone is signed at the point in time when the re-signing is to be
performed.

Roll over DNSSEC keys

On the NetScaler, you can use the pre-publish and double signature methods to perform a rollover
of the Zone Signing Key and Key Signing Key. More information about these two rollover methods is

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2159

NetScaler 12.0

available in RFC 4641, “DNSSEC Operational Practices.”

The following topics map commands on the ADC to the steps in the rollover procedures discussed in
RFC 4641.

The key expiry notification is sent through an SNMP trap called dnskeyExpiry. Three MIB variables,
dnskeyName, dnskeyTimeToExpire, and dnskeyUnitsOfExpiry are sent along with the dnskeyExpiry
SNMP trap. For more information, see Citrix NetScaler SNMP OID Reference at NetScaler 12.0 SNMP
OID Reference.

Pre-publish key rollover

RFC 4641, “DNSSEC Operational Practices” defines four stages for the pre-publish key rollover method:
initial, new DNSKEY, new RRSIGs, and DNSKEY removal. Each stage is associated with a set of tasks
that you must perform on the ADC. Following are the descriptions of each stage and the tasks that you
must perform. The rollover procedure described here can be used for both Key Signing Keys and Zone
Signing Keys.

• Stage 1: Initial. The zone contains only those key sets with which the zone has currently been
signed. The state of the zone in the initial stage is the state of the zone just before you begin the
key rollover process.

Example:

Consider the key, example.com.zsk1, with which the zone example.com is currently signed. The
zone contains only those RRSIGs that were generated by the example.com.zsk1 key, which is
due for expiry. The Key Signing Key is example.com.ksk1.

• Stage 2: New DNSKEY. A new key is created and published in the zone (that is, the key is added
to the ADC), but the zone is not signed with the new key until the pre-roll phase is complete.
In this stage, the zone contains the old key, the new key, and the RRSIGs generated by the old
key. Publishing the new key for the complete duration of the pre-roll phase gives the DNSKEY
resource record (that corresponds to the new key) enough time to propagate to the secondary
name servers.

Example:

A new key example.com.zsk2 is added to the example.com zone. The zone is not signed with ex-
ample.com.zsk2 until the pre-roll phase is complete. The example.com zone contains DNSKEY
resource records for both example.com.zsk1 and example.com.zsk2.

NetScaler commands:

Perform the following tasks on the ADC:

– Create a new DNS key by using the create dns key command.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2160

NetScaler 12.0

For more information about creating a DNS key, including an example, see Create DNS keys
for a zone.

– Publish the new DNS key in the zone by using the add dns key command.

For more information about publishing the key in the zone, including an example, see Pub-
lish a DNS key in a zone.

• Stage 3: New RRSIGs. The zone is signed with the new DNS key and then unsigned with the
old DNS key. The old DNS key is not removed from the zone and remains published until the
RRSIGs that were generated by the old key expire.

Example:

The zone is signed with example.com.zsk2 and then unsigned with example.com.zsk1. The
zone continues to publish example.com.zsk1 until the RRSIGs that were generated by exam-
ple.com.zsk1 expire.

NetScaler commands:

Perform the following tasks on the ADC:

– Sign the zone with the new DNS key by using the sign dns zone command.
– Unsign the zone with the old DNS key by using the unsign dns zone command.

For more information about signing and unsigning a zone, including examples, see Sign and
unsign a DNS zone.

• Stage 4: DNSKEY Removal. When the RRSIGs that were generated by the old DNS key expire,
the old DNS key is removed from the zone.

Example:

The old DNS key example.com.zsk1 is removed from the example.com zone.

NetScaler commands

On the ADC, you remove the old DNS key by using the rm dns key command. For more informa-
tion about removing a key from a zone, including an example, see Remove a DNS key.

Double signature key rollover

RFC 4641, “DNSSEC Operational Practices” defines three stages for double signature key rollover: ini-
tial, new DNSKEY, and DNSKEY removal. Each stage is associated with a set of tasks that you must
perform on the ADC. Following are the descriptions of each stage and the tasks that you must per-
form. The rollover procedure described here can be used for both Key Signing Keys and Zone Signing
Keys.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2161

NetScaler 12.0

• Stage 1: Initial. The zone contains only those key sets with which the zone has currently been
signed. The state of the zone in the initial stage is the state of the zone just before you begin the
key rollover process.

Example:

Consider the key, example.com.zsk1, with which the zone example.com is currently signed. The
zone contains only those RRSIGs that were generated by the example.com.zsk1 key, which is
due for expiry. The Key Signing Key is example.com.ksk1.

• Stage 2: New DNSKEY. The new key is published in the zone and the zone is signed with the
new key. The zone contains the RRSIGs that are generated by the old and the new keys. The
minimum duration for which the zone must contain both sets of RRSIGs is the time required for
all the RRSIGs to expire.

Example:

A new key example.com.zsk2 is added to the example.com zone. The zone is signed with exam-
ple.com.zsk2. The example.com zone now contains the RRSIGs generated from both keys.

NetScaler commands

Perform the following tasks on the ADC:

– Create a new DNS key by using the create dns key command.

For more information about creating a DNS key, including an example, see Create DNS keys
for a zone.

– Publish the new key in the zone by using the add dns key command.

For more information about publishing the key in the zone, including an example, see Pub-
lish a DNS key in a zone.

– Sign the zone with the new key by using the sign dns zone command.

For more information about signing a zone, including examples, see Sign and unsign a DNS
zone.

• Stage 3: DNSKEY Removal. When the RRSIGs that were generated by the old DNS key expire,
the old DNS key is removed from the zone.

Example:

The old DNS key example.com.zsk1 is removed from the example.com zone.

NetScaler commands:

On the ADC, you remove the old DNS key by using the rm dns key command.

For more information about removing a key from a zone, including an example, see Remove a
DNS key.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2162

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0

Offload DNSSEC operations to the NetScaler

September 11, 2018

Contributed by:
C

For DNS zones for which your DNS servers are authoritative, you can offload DNSSEC operations to
the NetScaler. In a DNSSEC offloading deployment, a DNS server sends unsigned responses. The ADC
signs the response on the fly before relaying it to the client. The ADC also caches the signed response.
Apart from reducing the load on the DNS servers, offloading DNSSEC operations to the ADC gives you
the following benefits:

• You can sign records that the DNS servers generate programmatically. Such records cannot be
signed by routine zone signing operations performed on the DNS servers.
• You can serve signed responses to clients even if you have not implemented DNSSEC on your
servers.

For setting up DNSSEC offloading, you must configure a DNS load balancing virtual server, configure
services that represent the DNS servers, and then bind the services to the virtual server. For infor-
mation about configuring a DNS load balancing virtual server, configuring services, and binding the
services to the virtual server, see Configure a DNS zone.

You must create a zone entity on the ADC for each DNS zone whose DNSSEC operations you want to
offload. For each DNS zone, you must enable the Proxy Mode and DNSSEC Offload parameters. You
can optionally configure NSEC record generation for an offloaded zone. To create a DNS zone entity
for DNSSEC offloading, follow the instructions in this topic.

To complete the configuration, you must generate DNS keys for the zone, add the keys to the zone,
and then sign the zone with the keys. This process is the same as for normal DNSSEC. For information
about creating keys, adding keys to a zone, and signing the zone, see Domain name system security
extensions.

After you configure DNS offloading, you must flush the DNS cache on the NetScaler. Flushing the DNS
cache ensures that any unsigned records in the cache are removed and subsequently replaced by
signed records. For information about flushing the DNS cache, see Flush DNS records.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2163

NetScaler 12.0

Enable DNSSEC offloading for a zone by using the CLI

At the command line, type the following commands to enable DNSSEC offloading for a zone and verify
the configuration:

1 - add dns zone <zoneName> -proxyMode YES -dnssecOffload ENABLED [-nsec

( ENABLED | DISABLED )
2 - show dns zone

Example:

1 > add dns zone example.com -proxyMode YES -dnssecOffload ENABLED nsec
ENABLED
2 Done
3 > show dns zone example.com
4 Zone Name : example.com
5 Proxy Mode : YES
6 DNSSEC Offload: ENABLED NSEC: ENABLED
7 Done

Enable DNSSEC offloading for a zone by using the GUI

1. Navigate to Traffic Management > DNS > Zones.

2. In the details pane, do one of the following:
• To create a zone on the NetScaler, click Add.
• To configure DNSSEC offloading for an existing zone, double-click the zone.
3. In the Create DNS Zone or Configure DNS Zone dialog box, select the Proxy Mode and DNSSEC
Offload check boxes.
4. Optionally, if you want the NetScaler to generate NSEC records for the zone, select the NSEC
check box.
1.
2. Citrix ADC
3. NetScaler 12.0

Admin partition support for DNSSEC

September 11, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2164

NetScaler 12.0

In a partitioned NetScaler appliance, the DNS keys that are generated are stored in the following loca-
tions:

• Default partition: /nsconfig/dns/

• Non-default partition: /nsconfig/partitions/<partitionname>/dns/

You can now add a password to the DNS key. To add a password to the DNS key, you must first add
the password in the create dns key command and then provide the same password in the add dns
key command when adding the DNS key to the NetScaler appliance. For example:

create dns key -zoneName com -keytype ksK -algorithm rsASHA1 -keysize 4096
- fileNamePrefix com.ksk.rsasha1.4096 -password 1jsfd3Wa

add dns key com.zsk.4096 /nsconfig/dns/com.zsk.rsasha1.4096.private -

password 1jsfd3Wa

Note:

• For default partitioned environment, the keys are read from default location/nsconfig/dns/.
However, if the keys are stored in a different location, the path name has to be provided in the
add dns key –private command. Example, add dns key –private <path name>.
• For non-default partitioned environment, the keys are read from the default location/nsconfig/-
partitions/<partitionname>/dns/.

1.
2. Citrix ADC
3. NetScaler 12.0

Supporting wildcard DNS domains

September 11, 2018

Contributed by:
C

Wildcard DNS domains are used to handle requests for a nonexistent domains and subdomains. In a
zone, if you want to redirect queries for all nonexistent domains or subdomains to a particular server,
you can use wildcard domains rather than creating a separate Resource Record (RR) for each such
domain. The most common use of a wildcard DNS domain is to create a zone that can be used to
forward mail from the internet to some other mail system.

In DNS resolution, the wildcard domain is supported by wildcard RRs. The wildcard RRs are used
to synthesize the responses to queries for a nonexistent domain name. For example, if you queried

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2165

NetScaler 12.0

http://image.example.com, and the subdomain “image” did not exist, you could be redirected to ex-
ample.com.

A wildcard record has an asterisk (*) character as the leftmost label of a domain name. For example,
*.example.com. An asterisk at any other place in the domain name does signify a wildcard DNS record.
For example, new.*.example.com is not a valid wildcard DNS record.
Note

• Wildcard domain is supported only when the NetScaler appliance is authoritative for the
zone and is configured as an ADNS or a DNS proxy server.
• Wildcard domain is not supported for NS and SOA records.
• Wildcard domain cannot be applied when the query is in another zone.
• Wildcard domain cannot be applied when the QNAME or a name between the wildcard do-
main and the QNAME is known to exist.

Example configuration

1 add dns soaRec example.com -originServer n1.example.com -contact admin.

example.com
2
3 add dns nsRec example.com n1.example.com
4
5 add dns nsRec example.com n2.example.com
6
7 add dns zone example.com  -proxyMode no
8
9 add dns addrec www.example.com 2.2.2.2
10
11 add dns addrec *.example.com 10.10.10.10
12
13 add dns addrec *.example.com 10.10.10.11
14
15 add dns aaaarec *.example.com 2001::1

In the example, wildcard domain name is added for A and AAAA record.

When a query is received for a domain name that exists in the zone, say www.example.com, the
NetScaler appliance responds with the corresponding response; that is 2.2.2.2 in the example.

For a nonexistent domain name that matches with a wildcard type, a synthesized response is deliv-
ered.

In the example, the NetScaler appliance responds with 10.10.10.10 and 10.10.10.11 for domain name
nonexist.example.com or xyz.example.com.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2166

NetScaler 12.0

Wildcard synthesize is not applicable for a domain name that exists in the zone.
For example, for the query www.example.com and type AAAA, the NetScaler appliance does not syn-
thesize with wildcard, because www.example.com exists with type A. In the example, the NetScaler
appliance responds with a NODATA response.
For a query say abc.example.com and type AAAA, the NetScaler appliance responds with a synthesized
response; that is 2001::1 in the example.
1.
2. Citrix ADC
3. NetScaler 12.0

Mitigate DNS DDoS attacks

September 11, 2018

Contributed by:
C
DNS servers are one of the most critical components of a network, and they must be defended against
attacks. One of the most basic types of DNS attacks is the DDoS attack. Attacks of this type are on
the rise and can be extremely destructive. To mitigate DDoS attacks, you can flush negative records,
restrict the time to live (TTL) of negative records, preserve NetScaler memory by limiting the memory
consumed by the DNS cache, retain DNS records in the cache, and enable DNS cache bypass. You can
also limit DNS queries to a single packet and thereby prevent Slowloris attacks.

Flush negative records

A DNS attack fills the cache with negative records (NXDOMAIN and NODATA). As a result, responses to
legitimate requests are not cached, so new requests are sent to a back-end server for DNS resolution.
Responses are therefore delayed.
You can now flush the negative DNS records from the NetScaler appliance’s DNS cache.

Flush negative cache records by using the CLI

At the command prompt, type:

flush dns proxyrecords -type (dnsRecordType | negRecType)NXDOMAIN | NODATA

Example:
flush dns proxyrecords ‒negRecType NODATA

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2167

NetScaler 12.0

Flush of negative cache records by using the GUI

1. Navigate to Configuration > Traffic Management > DNS > Records.

2. In the details pane, click Flush Proxy Records.
3. In the Flush Type box, select Negative Records.
4. In the Negative Records Type box, select either NXDOMAIN or NODATA.

Protection against random subdomain and NXDOMAIN attacks

To prevent random subdomain and NXDOMAIN attacks, you can restrict the DNS cache memory, and
you can adjust the TTL values for negative records.

To limit the amount of memory consumed by the DNS cache, you can specify the maximum cache size
(in MB), and also the cache size (in MB) for storing negative responses. When either limit is reached,
no more entries are added to the cache. Also, syslog messages are logged and, if you have configured
SNMP traps, SNMP traps are generated. If these limits are not set, caching continues until the system
memory is exhausted.

A higher TTL value for negative records can result in storing records that are not valuable for a long
period of time. A lower TTL value results in sending more requests to the back-end server.

The TTL of the negative record is set to a value that can be lesser of the TTL value or the ”Expires”
value of the SOA record.

Note:

• This limitation is added per packet engine. For example, if the maxCacheSize is set to 5 MB and
the appliance has 3 packet engines, the total cache size is 15 MB.
• The cache size for the negative records must be less than or equal to the maximum cache size.
• If you reduce the DNS cache memory limit to a value lower than the amount of data already
cached, the cache size remains above the limit until data ages out (exceeds its TTL0 or is flushed
(flush dns proxyrecords command, or Flush Proxy Records in the NetScaler GUI).
• To configure SNMP traps, see Configuring the NetScaler to Generate SNMP Traps.

Limit the memory consumed by the DNS Cache by using the CLI

At the command prompt, type:

set dns parameter -maxCacheSize <MBytes> -maxNegativeCacheSize <MBytes>

Example:

set dns parameter - maxCacheSize 100 -maxNegativeCacheSize 25

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2168

NetScaler 12.0

Limit the memory consumed by the DNS Cache by using the GUI

Navigate to Configuration > Traffic Management > DNS, click Change DNS Settings, and set the
following parameters:

• Max Cache Size in MB

• Max Negative Cache Size in MB

Restrict TTL of negative records by using the CLI

At the command prompt, type:

set dns parameter -maxnegcacheTTL <secs>

Example:

set dns parameter -maxnegcacheTTL 360

Restrict TTL of negative records by using the GUI

1. Navigate to Configuration > Traffic Management > DNS.

2. Click Change DNS Settings and set the Max Negative Cache TTL in sec parameter.

Retain DNS records in the cache

An attack can flood the DNS cache with entries that are not valuable but can cause flushing of the
already cached legitimate records to make room for the new entries. To prevent attacks from filling
the cache with invalid data, you can retain the legitimate records even after they exceed their TTL
values.

If you enable the cacheNoExpire parameter, the records currently in the cache are retained until you
disable the parameter.

Note:

• This option can be used only when the maximum cache size is specified (maxCacheSize param-
eter).
• If maxnegcacheTTL is configured and cacheNoExpire is enabled, cacheNoExpire takes priority.

Retain DNS records in the cache by using the CLI

At the command prompt, type:

set dns parameter -cacheNoExpire ( ENABLED | DISABLED)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2169

NetScaler 12.0

Example:

set dns parameter -cacheNoExpire ENABLED

Retain DNS records in the cache by using the GUI

1. Navigate to Configuration > Traffic Management > DNS and click Change DNS Settings.
2. Select Cache No Expire.

Enable DNS cache bypass

For greater visibility and control of DNS requests arriving at the NetScaler appliance, you can set the
cacheHitBypass parameter to forward all requests to the back-end servers and allow cache to be built
but not used. After the cache is built, you can disable the parameter so that requests are served from
the cache.

Enable DNS cache bypass by using the CLI

At the command prompt, type:

set dns parameter -cacheHitBypass ( ENABLED | DISABLED )

Example:

set dns parameter -cacheHitBypass ENABLED

Enable DNS cache bypass by using the GUI

1. Navigate to Configuration > Traffic Management > DNS and click Change DNS Settings.
2. Select Cache Hit Bypass.

Prevent the Slowloris attack

A DNS query spanning multiple packets presents the potential threat of a Slowloris attack. The
NetScaler appliance can silently drop DNS queries that are split into multiple packets.

You can set the splitPktQueryProcessing parameter to ALLOW or DROP a DNS query if the query is split
into multiple packets.

Note: This is applicable only for DNS TCP.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2170

NetScaler 12.0

Limit the DNS queries to a single packet by using the CLI

At the command prompt, type:

set dns parameter -splitPktQueryProcessing ( ALLOW | DROP )

Example:

set dns parameter -splitPktQueryProcessing DROP

Limit DNS queries to a single packet by using the GUI

1. Navigate to Configuration > Traffic Management > DNS and click Change DNS Settings.
2. In the Split Packet Query Processing box, choose ALLOW or DROP.

Collect statistics of the DNS responses served from the cache

You can collect statistics of the DNS responses served from cache and use these statistics to create
a threshold beyond which additional DNS traffic is dropped, and enforce this threshold with a band-
width based policy. Previously, bandwidth calculation for a DNS load balancing virtual server was not
accurate, because the number of cache hits was not reported.

In proxy mode, the statistics for Request bytes, Response bytes, Total Packets rcvd, and Total Packets
sent statistics are continuously updated. Previously, these statistics were not always updated, partic-
ularly for a DNS load balancing virtual server.

Proxy mode also now enables you to determine the number of DNS responses served from the
cache. To help collect these statistics, the following options have been added to the stat lb vserver
<DNSvirtualServerName> command:

• Requests – Total number of requests received by the DNS or DNS_TCP vserver. Includes the
requests forwarded to the back end and the requests answered from the cache.
• Vserver hits –Total number of requests forwarded to the back end. The total number of cache
hits is the difference between Requests and Vserver hits.
• Responses – Total number of responses sent by this vserver. For example, if a DNS LB virtual
server received 5 DNS requests, forwarded 3 of them to the back end, and served 2 of them
from the cache, the corresponding value of each of these statistics would be as follows:
– Vserver hits: 3
– Requests: 5
– Responses: 5

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2171

NetScaler 12.0

Firewall Load Balancing

September 14, 2018

Contributed by:
C

Firewall load balancing distributes traffic across multiple firewalls, providing fault tolerance and in-
creased throughput. Firewall load balancing protects your network by:

• Dividing the load between the firewalls, which eliminates a single point of failure and allows the
network to scale.
• Increasing high availability.

Configuring a NetScaler appliance for firewall load balancing is similar to configuring load balancing,
with the exception that the recommended service type is ANY, recommended monitor type is PING,
and the load balancing virtual server mode is set to MAC.

You can set up firewall load balancing in a sandwich, an enterprise, or multiple-firewall environment
configuration. The sandwich environment is used for load balancing traffic entering the network from
outside and traffic leaving the network to the internet and involves configuring two NetScaler appli-
ances, one on each side of a set of firewalls. You configure an enterprise environment for load bal-
ancing traffic leaving the network to the internet. The enterprise environment involves configuring a
single NetScaler appliance between the internal network and the firewalls that provide access to the
Internet. The multiple-firewall environment is used for load balance traffic coming from another fire-
wall. Having firewall load balancing enabled on both the sides of NetScaler appliance improves the
traffic flow in both the egress and ingress direction and ensures faster processing of the traffic. The
multiple-firewall environment involves configuring a NetScaler appliance sandwiched between two
firewalls.

Important: If you configure static routes on the NetScaler appliance for the destination IP address and
enable L3 mode, the NetScaler appliance uses its routing table to route the traffic instead of sending
the traffic to the load balancing vserver.

Note: For FTP to work, an additional virtual server or service should be configured on the NetScaler
appliance with IP address and port as * and 21 respectively, and the service type specified as FTP. In
this case, the NetScaler appliance manages the FTP protocol by accepting the FTP control connection,
modifying the payload, and managing the data connection, all through the same firewall.

Firewall Load Balancing supports only some of the load balancing methods supported on the
NetScaler appliance. Also, you can configure only a few types of persistence and monitors.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2172

NetScaler 12.0

Firewall Load Balancing Methods

The following load balancing methods are supported for firewall load balancing.

• Least Connections
• Round Robin
• Least Packets
• Least Bandwidth
• Source IP Hash
• Destination IP Hash
• Source IP Destination IP Hash
• Source IP Source Port hash
• Least Response Time Method (LRTM)
• Custom Load

Firewall Persistence

Only SOURCEIP, DESTIP, and SOURCEIPDESTIP based persistence are supported for firewall load bal-
ancing.

Firewall Server Monitoring

Only PING and transparent monitors are supported in firewall load balancing. You can bind a PING
monitor (default) to the backend service that represents the firewall. If a firewall is configured not to
respond to ping packets, you can configure transparent monitors to monitor hosts on the trusted side
through individual firewalls.

1.
2. Citrix ADC
3. NetScaler 12.0

Sandwich Environment

January 6, 2019

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2173

NetScaler 12.0

A NetScaler deployment in a sandwich mode is capable of load balancing network traffic through fire-
walls in both directions: ingress (traffic entering the network from the outside, such as the internet)
and egress (traffic leaving the network to the internet).

In this setup, a NetScaler is located on each side of a set of firewalls. The NetScaler placed between
the firewalls and the Internet, called the external NetScaler that handles ingress traffic selects the
best firewall, based on the configured method. The NetScaler between the firewalls and the private
network, called the internal NetScaler tracks the firewall from which the initial packet for a session is
received. It then makes sure that all subsequent packets for that session are sent to the same firewall.

The internal NetScaler can be configured as a regular traffic manager to load balance traffic across the
private network servers. This configuration also allows traffic originating from the private network
(egress) to be load balanced across the firewalls.

The following diagram shows the sandwich firewall load balancing environment.

Figure 1. Firewall Load Balancing (Sandwich)

The service type ANY configures the NetScaler to accept all traffic.

To avail benefits related to HTTP and TCP, configure the service and virtual server with type HTTP or
TCP. For FTP to work, configure the service with type FTP.

Configuring the External NetScaler in a Sandwich Environment

Perform the following tasks to configure the external NetScaler in a sandwich environment

• Enable the load balancing feature.

• Configure a wildcard service for each firewall.
• Configure a monitor for each wildcard service.
• Configure a wildcard virtual server for traffic coming from the Internet.
• Configure the virtual server in MAC rewrite mode.
• Bind services to the wildcard virtual server.
• Save and Verify the Configuration.

Enable the load balancing feature

To enable load balancing by using the command line interface

At the command prompt, type the following command to enable load balancing and verify the config-
uration:

1 enable ns feature LB
2 show ns feature

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2174

NetScaler 12.0

Example:

1 > enable ns feature LoadBalancing

2 Done
3 > show ns feature
4
5 Feature Acronym Status
6 ------- ------- ------
7 1) Web Logging WL OFF
8 2) Surge Protection SP ON
9 3) Load Balancing LB ON
10 .
11 .
12 .
13 24) NetScaler Push push OFF
14 Done

To enable load balancing by using the configuration utility

Navigate to System > Settings and, in Configure Basic Features, select Load Balancing.

Configure a wildcard service for each firewall

To configure a wildcard service for each firewall by using the command line interface

At the command prompt, type:

1 add service <name> <serverName> ANY *

Example:

1 add service Service-HTTP-1 10.102.29.5 ANY *

To configure a wildcard service for each firewall by using the configuration utility

Navigate to Traffic Management > Load Balancing > Services and add a service. Specify ANY in the
Protocol field and * in the Port field.

Configure a monitor for each wildcard service

A PING monitor is bound by default to the service. You will need to configure a transparent monitor
to monitor hosts on the trusted side through individual firewalls. You can then bind the transparent

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2175

NetScaler 12.0

monitor to services. The default PING monitor monitors the connectivity only between the NetScaler
appliance and the upstream device. The transparent monitor monitors all the devices existing in the
path from the appliance to the device that owns the destination IP address specified in the monitor.
If a transparent monitor is not configured and the status of the firewall is UP but one of the next hop
devices from that firewall is down, the appliance includes the firewall while performing load balancing
and forwards the packet to the firewall. However, the packet is not delivered to the final destination
because one of the next hop devices is down. By binding a transparent monitor, if any of the devices
(including the firewall) are down, the service is marked as DOWN and the firewall is not included when
the appliance performs firewall load balancing.
Binding a transparent monitor will override the PING monitor. To configure a PING monitor in addition
to a transparent monitor, after you create and bind a transparent monitor, you need to bind a PING
monitor to the service.

To configure a transparent monitor by using the command line interface

At the command prompt, type the following commands to configure a transparent monitor and verify
the configuration:

1 add lb monitor <monitorName> <type> [-destIP <ip_addr|ipv6_addr|*>] [-

transparent (YES | NO )]
2 bind lb monitor <monitorName> <serviceName>

Example:

1 add monitor monitor-HTTP-1 HTTP -destip 10.10.10.11 -transparent YES

2 bind monitor monitor-HTTP-1 fw-svc1
3 To bind a PING monitor, type the following command:
4 bind monitor PING fw-svc1

To create and bind a transparent monitor by using the configuration utility

Navigate to
Traffic Management > Load Balancing > Monitors, and then create and bind a transparent monitor.

Configure a wildcard virtual server for traffic coming from the Internet

To configure a wildcard virtual server for traffic coming from the Internet by using the command
line interface
At the command prompt, type:

1 add lb vserver <name> ANY * *

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2176

NetScaler 12.0

Example:

1 add lb vserver Vserver-LB-1 ANY * *

To configure a wildcard virtual server for traffic coming from the Internet by using the configu-
ration utility

Navigate to Traffic Management > Load Balancing > Virtual Servers and create a wildcard virtual server.
Specify ANY in the Protocol field and * in the Port field.

Configure the virtual server in MAC rewrite mode

To configure the virtual server in MAC rewrite mode by using the command line interface

At the command prompt, type:

1 set lb vserver <name>@ -m <RedirectionMode>

Example:

1 set lb vserver Vserver-LB-1 -m MAC

To configure the virtual server in MAC rewrite mode by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Virtual Servers and select the virtual server
for which you want to configure the redirection mode (for example, Vserver-LB-1).
2. Edit the Basic Settings section and. click more.
3. From the Redirection Mode drop-down list, select MAC Based.

Bind services to the wildcard virtual server

To bind a service to the wildcard virtual server by using the command line interface

At the command prompt, type:

1 bind lb vserver <name> <serviceName>

Example:

1 bind lb vserver Vserver-LB-1 Service-HTTP-1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2177

NetScaler 12.0

To bind a service to the wildcard virtual server by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Virtual Servers and select the virtual server
for which you want to bind the service.
2. Click in the Services section and select a service to bind.

Save and Verify the Configuration

When you’ve finished the configuration tasks, be sure to save the configuration. You should also check
to make sure that the settings are correct.

To save and verify the configuration by using the command line interface

At the command prompt, type the following commands to configure a transparent monitor and verify
the configuration:

1 save ns config
2 show vserver

Example:

1 save config
2 sh lb vserver FWLBVIP1
3 FWLBVIP1 (*:*) - ANY Type: ADDRESS
4 State: UP
5 Last state change was at Mon Jun 14 06:40:14 2010
6 Time since last state change: 0 days, 00:00:11.240
7 Effective State: UP ARP:DISABLED
8 Client Idle Timeout: 120 sec
9 Down state flush: ENABLED
10 Disable Primary Vserver On Down : DISABLED
11 No. of Bound Services : 2 (Total) 2 (Active)
12 Configured Method: SRCIPDESTIPHASH
13 Mode: MAC
14 Persistence: NONE
15 Connection Failover: DISABLED
16
17 1) fw_svc_1 (10.102.29.251: *) - ANY State: UP Weight: 1
18 2) fw_svc_2 (10.102.29.18: *) - ANY State: UP Weight: 1
19 Done
20 show service fw-svc1
21 fw-svc1 (10.102.29.251:*) - ANY
22 State: DOWN
23 Last state change was at Thu Jul 8 10:04:50 2010

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2178

NetScaler 12.0

24 Time since last state change: 0 days, 00:00:38.120

25 Server Name: 10.102.29.251
26 Server ID : 0 Monitor Threshold : 0
27 Max Conn: 0 Max Req: 0 Max Bandwidth: 0 kbits
28 Use Source IP: NO
29 Client Keepalive(CKA): NO
30 Access Down Service: NO
31 TCP Buffering(TCPB): YES
32 HTTP Compression(CMP): NO
33 Idle timeout: Client: 120 sec Server: 120 sec
34 Client IP: DISABLED
35 Cacheable: NO
36 SC: OFF
37 SP: OFF
38 Down state flush: ENABLED
39
40 1) Monitor Name: monitor-HTTP-1
41 State: DOWN Weight: 1
42 Probes: 5 Failed [Total: 5 Current: 5]
43 Last response: Failure - Time out during TCP connection
establishment stage
44 Response Time: 2000.0 millisec
45 2) Monitor Name: ping
46 State: UP Weight: 1
47 Probes: 3 Failed [Total: 0 Current: 0]
48 Last response: Success - ICMP echo reply received.
49 Response Time: 1.415 millisec
50 Done

Configuring the Internal NetScaler in a Sandwich Environment

Perform the following tasks to configure the internal NetScaler in a sandwich environment
For traffic from the server (egress)
• Enable the load balancing feature.
• Configure a wildcard service for each firewall.
• Configure a monitor for each wildcard service.
• Configure a wildcard virtual server to load balance the traffic sent to the firewalls.
• Configure the virtual server in MAC rewrite mode.
• Bind firewall services to the wildcard virtual server.
For traffic across private network servers
• Configure a service for each virtual server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2179

NetScaler 12.0

• Configure a monitor for each service.

• Configure an HTTP virtual server to balance traffic sent to the servers.
• Bind HTTP services to the HTTP virtual server.
• Save and Verify the Configuration.

Enable the load balancing feature

You can configure load balancing entities such as services and virtual servers when the load balancing
feature is disabled, but they will not function until you enable the feature.

To enable load balancing by using the command line interface

At the command prompt, type the following command to enable load balancing and verify the config-
uration:

1 enable ns feature LB
2 show ns feature

Example:

1 > enable ns feature LoadBalancing

2 Done
3 > show ns feature
4
5 Feature Acronym Status
6 ------- ------- ------
7 1) Web Logging WL OFF
8 2) Surge Protection SP ON
9 3) Load Balancing LB ON
10 .
11 .
12 .
13 24) NetScaler Push push OFF
14 Done

To enable load balancing by using the configuration utility

Navigate to System > Settings and, in Configure Basic Features, select Load Balancing.

Configure a wildcard service for each firewall

To configure a wildcard service for each firewall by using the command line interface

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2180

NetScaler 12.0

At the command prompt, type:

1 add service <name> <serverName> ANY *

Example:

1 add service Service-HTTP-1 10.102.29.5 ANY *

To configure a wildcard service for each firewall by using the configuration utility

Navigate to Traffic Management > Load Balancing > Services and add a service. Specify ANY in the
Protocol field and * in the Port field.

Configure a monitor for each wildcard service

A PING monitor is bound by default to the service. You will need to configure a transparent monitor
to monitor hosts on the trusted side through individual firewalls. You can then bind the transparent
monitor to services. The default PING monitor monitors the connectivity only between the NetScaler
appliance and the upstream device. The transparent monitor monitors all the devices existing in the
path from the appliance to the device that owns the destination IP address specified in the monitor.
If a transparent monitor is not configured and the status of the firewall is UP but one of the next hop
devices from that firewall is down, the appliance includes the firewall while performing load balancing
and forwards the packet to the firewall. However, the packet is not delivered to the final destination
because one of the next hop devices is down. By binding a transparent monitor, if any of the devices
(including the firewall) are down, the service is marked as DOWN and the firewall is not included when
the appliance performs firewall load balancing.

Binding a transparent monitor will override the PING monitor. To configure a PING monitor in addition
to a transparent monitor, after you create and bind a transparent monitor, you need to bind a PING
monitor to the service.

To configure a transparent monitor by using the command line interface

At the command prompt, type the following commands to configure a transparent monitor and verify
the configuration:

1 add lb monitor <monitorName> <type> [-destIP <ip_addr|ipv6_addr|*>] [-

transparent (YES | NO )]
2 bind lb monitor <monitorName> <serviceName>

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2181

NetScaler 12.0

1 add monitor monitor-HTTP-1 HTTP -destip 10.10.10.11 -transparent YES

2 bind monitor monitor-HTTP-1 fw-svc1

To create and bind a transparent monitor by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Monitors and create a monitor.
2. In the Create Monitor dialog box, enter the required parameters and select Transparent.

Configure a wildcard virtual server to load balance the traffic sent to the firewalls

To configure a wildcard virtual server to load balance the traffic sent to the firewalls by using
the command line interface

At the command prompt, type:

1 add lb vserver <name> ANY * *

Example:

1 add lb vserver Vserver-LB-1 ANY * *

To configure a wildcard virtual server for traffic coming from the Internet by using the configu-
ration utility

Navigate to
Traffic Management > Load Balancing > Virtual Servers and create a wildcard virtual server. Specify
ANY in the Protocol field and * in the Port field.

To configure a wildcard virtual server to load balance the traffic sent to the firewalls by using
the configuration utility

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.

2. In the details pane, click Add.
3. In the Create Virtual Server (Load Balancing) dialog box, specify values for the following param-
eters as shown:
• Name—name
4. In Protocol, select ANY, and in IP Address and Port, select *.
5. Click Create, and then click Close. The virtual server you created appears in the Load Balancing
Virtual Servers pane.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2182

NetScaler 12.0

Configure the virtual server in MAC rewrite mode

To configure the virtual server in MAC rewrite mode by using the command line interface

At the command prompt, type:

1 set lb vserver <name>@ -m <RedirectionMode>

Example:

1 set lb vserver Vserver-LB-1 -m MAC

To configure the virtual server in MAC rewrite mode by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Virtual Servers and select the virtual server
for which you want to configure the redirection mode (for example, Vserver-LB-1).
2. Edit the Basic Settings section and. click more.
3. From the Redirection Mode drop-down list, select MAC Based.

To configure the virtual server in MAC rewrite mode by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.

2. In the details pane, select the virtual server for which you want to configure the redirection
mode (for example, Vserver-LB-1), and then click Open.
3. On the Advanced tab, under Redirection Mode, click MAC-Based.
4. Click OK.

Bind firewall services to the wildcard virtual server

To bind firewall services to the wildcard virtual server by using the command line interface

At the command prompt, type:

1 bind lb vserver <name> <serviceName>

Example:

1 bind lb vserver Vserver-LB-1 Service-HTTP-1

To bind firewall services to the wildcard virtual server by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Virtual Servers, and select a virtual server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2183

NetScaler 12.0

2. Click in the Service section, and select a service to bind.

Note: You can bind a service to multiple virtual servers.

Configure a service for each virtual server

To configure a service for each virtual server by using the command line interface

At the command prompt, type:

1 add service <name> <serverName> HTTP <port>

Example:

1 add service Service-HTTP-1 10.102.29.5 HTTP 80

To configure a service for each virtual server by using the configuration utility

Navigate to Traffic Management > Load Balancing > Services and configure a service for each virtual
server. Specify HTTP in the Protocol field and select HTTP under Available Monitors.

To configure a service for each virtual server by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Services.

2. In the details pane, click Add.
3. In the Create Service dialog box, specify values for the following parameters as shown:
• Service Name—name
• Server—serverName
• Port—port
4. In Protocol, specify HTTP. Under Available Monitors, select HTTP.
5. Click Create, and then click Close. The service you created appears in the Services pane.

Configure a monitor for each service

To bind a monitor to a service by using the command line interface

At the command prompt, type:

1 bind lb monitor <monitorName> <ServiceName>

Example:

1 bind mon monitor-HTTP-1 Service-HTTP-1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2184

NetScaler 12.0

To bind a monitor to a service by using the configuration utility

Navigate to
Traffic Management > Load Balancing > Services, double-click a service and add a monitor.

To bind a monitor to a service by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Services.

2. Open the service, and add a monitor.

Configure an HTTP virtual server to balance traffic sent to the servers

To configure an HTTP virtual server to balance traffic sent to the servers by using the command
line interface

At the command prompt, type:

1 add lb vserver <name> HTTP <ip> <port>

Example:

1 add lb vserver Vserver-LB-1 HTTP 10.102.29.60 80

To configure an HTTP virtual server to balance traffic sent to the servers by using the configura-
tion utility

Navigate to Traffic Management > Load Balancing > Virtual Services and configure an HTTP virtual
server. Specify HTTP in the Protocol field.

To configure an HTTP virtual server to balance traffic sent to the servers by using the configura-
tion utility

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.

2. In the details pane, click Add.
3. In the Create Virtual Server (Load Balancing) dialog box, specify values for the following param-
eters as shown:
• Name—name
• IP Address—IPAddress
Note: If the virtual server uses IPv6, select the
IPv6 check box and enter the address in IPv6 format (for example,
1000:0000:0000:0000:0005:0600:700a:888b).
• Port—port

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2185

NetScaler 12.0

4. Under Protocol, select HTTP.

5. Click Create, and then click Close. The virtual server you created appears in the Load Balancing
Virtual Servers pane.

Save and Verify the Configuration

When you’ve finished the configuration tasks, be sure to save the configuration. You should also check
to make sure that the settings are correct.

To save and verify the configuration by using the command line interface

At the command prompt, type the following commands to configure a transparent monitor and verify
the configuration:

• save ns config
• show vserver

Example:

1 save config
2 show lb vserver FWLBVIP2
3 FWLBVIP2 (*:*) - ANY Type: ADDRESS
4 State: UP
5 Last state change was at Mon Jun 14 07:22:54 2010
6 Time since last state change: 0 days, 00:00:32.760
7 Effective State: UP
8 Client Idle Timeout: 120 sec
9 Down state flush: ENABLED
10 Disable Primary Vserver On Down : DISABLED
11 No. of Bound Services : 2 (Total) 2 (Active)
12 Configured Method: LEASTCONNECTION
13 Current Method: Round Robin, Reason: A new service is bound
14 Mode: MAC
15 Persistence: NONE
16 Connection Failover: DISABLED
17
18 1) fw-int-svc1 (10.102.29.5: *) - ANY State: UP Weight: 1
19 2) fw-int-svc2 (10.102.29.9: *) - ANY State: UP Weight: 1
20 Done
21 show service fw-int-svc1
22 fw-int-svc1 (10.102.29.5:*) - ANY
23 State: DOWN
24 Last state change was at Thu Jul 8 14:44:51 2010
25 Time since last state change: 0 days, 00:01:50.240

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2186

NetScaler 12.0

26 Server Name: 10.102.29.5

27 Server ID : 0 Monitor Threshold : 0
28 Max Conn: 0 Max Req: 0 Max Bandwidth: 0 kbits
29 Use Source IP: NO
30 Client Keepalive(CKA): NO
31 Access Down Service: NO
32 TCP Buffering(TCPB): NO
33 HTTP Compression(CMP): NO
34 Idle timeout: Client: 120 sec Server: 120 sec
35 Client IP: DISABLED
36 Cacheable: NO
37 SC: OFF
38 SP: OFF
39 Down state flush: ENABLED
40
41 1) Monitor Name: monitor-HTTP-1
42 State: DOWN Weight: 1
43 Probes: 9 Failed [Total: 9 Current: 9]
44 Last response: Failure - Time out during TCP connection
establishment stage
45 Response Time: 2000.0 millisec
46 2) Monitor Name: ping
47 State: UP Weight: 1
48 Probes: 3 Failed [Total: 0 Current: 0]
49 Last response: Success - ICMP echo reply received.
50 Response Time: 1.275 millisec
51 Done

To save and verify the configuration by using the configuration utility

1. In the details pane, click Save.

2. In the Save Config dialog box, click Yes.
3. Navigate to Traffic Management > Load Balancing > Virtual Servers.
4. In the details pane, select the virtual server that you created in step 5 and verify that the settings
displayed in the Details pane are correct.
5. Navigate to Traffic Management > Load Balancing > Services.
6. In the details pane, select the service that you created in step 5 and verify that the settings dis-
played in the Details pane are correct.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2187

NetScaler 12.0

Monitoring a Firewall Load Balancing Setup in a Sandwich Environment

After the configuration is up and running, you should view the statistics for each service and virtual
server to check for possible problems.

Viewing the Statistics of a Virtual Server

To evaluate the performance of virtual servers or to troubleshoot problems, you can display details of
the virtual servers configured on the NetScaler appliance. You can display a summary of statistics for
all the virtual servers, or you can specify the name of a virtual server to display the statistics only for
that virtual server. You can display the following details:

• Name
• IP address
• Port
• Protocol
• State of the virtual server
• Rate of requests received
• Rate of hits

To display virtual server statistics by using the command line interface

To display a summary of the statistics for all the virtual servers currently configured on the NetScaler,
or for a single virtual server, at the command prompt, type:

1 stat lb vserver [-detail] [<name>]

Example:

1 >stat lb vserver -detail

2 Virtual Server(s) Summary
3 vsvrIP port Protocol State Req/s
Hits/s
4 One * 80 HTTP UP 5/s
0/s
5 Two * 0 TCP DOWN 0/s
0/s
6 Three * 2598 TCP DOWN 0/s
0/s
7 dnsVirtualNS 10.102.29.90 53 DNS DOWN 0/s
0/s
8 BRVSERV 10.10.1.1 80 HTTP DOWN 0/s
0/s

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2188

NetScaler 12.0

9 LBVIP 10.102.29.66 80 HTTP UP 0/s

0/s
10 Done

To display virtual server statistics by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Virtual Servers > Statistics.
2. If you want to display the statistics for only one virtual server, in the details pane, select the
virtual server, and click Statistics.

Viewing the Statistics of a Service

You can view the rate of requests, responses, request bytes, response bytes, current client connec-
tions, requests in surge queue, current server connections, and so forth using the service statistics.

To view the statistics of a service by using the command line interface

At the command prompt, type:

1 stat service <name>

Example:

1 stat service Service-HTTP-1

To view the statistics of a service by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Services > Statistics.
2. If you want to display the statistics for only one service, select the service, and click Statistics.

1.
2. Citrix ADC
3. NetScaler 12.0

Enterprise Environment

January 6, 2019

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2189

NetScaler 12.0

In the enterprise setup, the NetScaler is placed between the firewalls connecting to the public Internet
and the internal private network and handles egress traffic. The NetScaler selects the best firewall
based on the configured load balancing policy.

The following diagram shows the enterprise firewall load balancing environment

Figure 1. Firewall Load Balancing (Enterprise)

The service type ANY configures the NetScaler to accept all traffic.

To avail benefits related to HTTP and TCP, configure the service and vserver with type HTTP or TCP.
For FTP to work, configure the service with type FTP.

Configuring the NetScaler in an Enterprise Environment

Perform the following tasks to configure a NetScaler in an enterprise environment.

For traffic from the server (egress)

• Enable the load balancing feature.

• Configure a wildcard service for each firewall.
• Configure a monitor for each wildcard service.
• Configure a wildcard virtual server to load balance the traffic sent to the firewalls.
• Configure the virtual server in MAC rewrite mode.
• Bind firewall services to the wildcard virtual server.

For traffic across private network servers

• Configure a service for each virtual server.

• Configure a monitor for each service.
• Configure an HTTP virtual server to balance traffic sent to the servers.
• Bind HTTP services to the HTTP virtual server.
• Save and Verify the Configuration.

Enable the load balancing feature

You can configure load balancing entities such as services and virtual servers when the load balancing
feature is disabled, but they will not function until you enable the feature.

To enable load balancing by using the command line interface

At the command prompt, type the following command to enable load balancing and verify the config-
uration:

• enable ns feature LB

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2190

NetScaler 12.0

• show ns feature
Example:

1 > enable ns feature LoadBalancing

2 Done
3 > show ns feature
4
5 Feature Acronym Status
6 ------- ------- ------
7 1) Web Logging WL OFF
8 2) Surge Protection SP ON
9 3) Load Balancing LB ON
10 .
11 .
12 .
13 24) NetScaler Push push OFF
14 Done

To enable load balancing by using the configuration utility

Navigate to System > Settings and, in Configure Basic Features, select Load Balancing.

Configure a wildcard service for each firewall

To configure a wildcard service for each firewall by using the command line interface
At the command prompt, type:

1 add service <name> <serverName> ANY *

Example:

1 add service Service-HTTP-1 10.102.29.5 ANY *

To configure a wildcard service for each firewall by using the configuration utility
1. Navigate to Traffic Management > Load Balancing > Services.
2. In the details pane, click Add.
3. In the Create Service dialog box, specify values for the following parameters as shown:
• Service Name—name
• Server—serverName
4. In Protocol, select ANY, and in Port, select *.
5. Click Create, and then click Close. The service you created appears in the Services pane.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2191

NetScaler 12.0

Configure a monitor for each wildcard service

A PING monitor is bound by default to the service. You will need to configure a transparent monitor
to monitor hosts on the trusted side through individual firewalls. You can then bind the transparent
monitor to services. The default PING monitor monitors the connectivity only between the NetScaler
appliance and the upstream device. The transparent monitor monitors all the devices existing in the
path from the appliance to the device that owns the destination IP address specified in the monitor.
If a transparent monitor is not configured and the status of the firewall is UP but one of the next hop
devices from that firewall is down, the appliance includes the firewall while performing load balancing
and forwards the packet to the firewall. However, the packet is not delivered to the final destination
because one of the next hop devices is down. By binding a transparent monitor, if any of the devices
(including the firewall) are down, the service is marked as DOWN and the firewall is not included when
the appliance performs firewall load balancing.

Binding a transparent monitor will override the PING monitor. To configure a PING monitor in addition
to a transparent monitor, after you create and bind a transparent monitor, you need to bind a PING
monitor to the service.

To configure a transparent monitor by using the command line interface

At the command prompt, type the following commands to configure a transparent monitor and verify
the configuration:

1 add lb monitor <monitorName> <type> [-destIP <ip_addr|ipv6_addr|*>] [-

transparent (YES | NO )]
2 bind lb monitor <monitorName> <serviceName>

Example:

1 add monitor monitor-HTTP-1 HTTP -destip 10.10.10.11 -transparent YES

2 bind monitor monitor-HTTP-1 fw-svc1

To create and bind a transparent monitor by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Monitors.

2. In the details pane, click Add.

3. In the Create Monitor dialog box, specify values as shown:

• Name*
• Type*—type
• Destination IP
• Transparent

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2192

NetScaler 12.0

-* A required parameter

4. Click Create, and then click Close. In the Monitors pane, select the monitor that you just config-
ured and verify that the settings displayed at the bottom of the screen are correct.

Configure a wildcard virtual server to load balance the traffic sent to the firewalls

To configure a wildcard virtual server to load balance the traffic sent to the firewalls by using
the command line interface

At the command prompt, type:

1 add lb vserver <name> ANY * *

Example:

1 add lb vserver Vserver-LB-1 ANY * *

To configure a wildcard virtual server to load balance the traffic sent to the firewalls by using
the configuration utility

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.

2. In the details pane, click Add.
3. In the Create Virtual Server (Load Balancing) dialog box, specify values for the following param-
eters as shown:
• Name—name
4. In Protocol, select ANY, and in IP Address and Port, select *.
5. Click Create, and then click Close. The virtual server you created appears in the Load Balancing
Virtual Servers pane.

Configure the virtual server in MAC rewrite mode

To configure the virtual server in MAC rewrite mode by using the command line interface

At the command prompt, type:

1 set lb vserver <name>@ -m <RedirectionMode>

Example:

1 set lb vserver Vserver-LB-1 -m MAC

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2193

NetScaler 12.0

To configure the virtual server in MAC rewrite mode by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.

2. In the details pane, select the virtual server for which you want to configure the redirection
mode (for example, Vserver-LB-1), and then click Open.
3. On the Advanced tab, under Redirection Mode, click MAC-Based.
4. Click OK.

Bind firewall services to the wildcard virtual server

To bind firewall services to the wildcard virtual server by using the command line interface

At the command prompt, type:

1 bind lb vserver <name> <serviceName>

Example:

1 bind lb vserver Vserver-LB-1 Service-HTTP-1

To bind firewall services to the wildcard virtual server by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Virtual Servers, and select a virtual server.
2. Click in the Service section, and select a service to bind.

Note: You can bind a service to multiple virtual servers.

Configure a service for each virtual server

To configure a service for each virtual server by using the command line interface

At the command prompt, type:

1 add service <name> <serverName> HTTP <port>

Example:

1 add service Service-HTTP-1 10.102.29.5 HTTP 80

To configure a service for each virtual server by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Services.

2. In the details pane, click Add.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2194

NetScaler 12.0

3. In the Create Service dialog box, specify values for the following parameters as shown:
• Service Name—name
• Server—serverName
• Port—port
4. In Protocol, specify HTTP. Under Available Monitors, select HTTP.
5. Click Create, and then click Close. The service you created appears in the Services pane.

Configure a monitor for each service

To bind a monitor to a service by using the command line interface

At the command prompt, type:

1 bind lb monitor <monitorName> <ServiceName>

Example:

1 bind mon monitor-HTTP-1 Service-HTTP-1

To bind a monitor to a service by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Services.

2. Open the service, and add a monitor.

Configure an HTTP virtual server to balance traffic sent to the servers

To configure an HTTP virtual server to balance traffic sent to the servers by using the command
line interface

At the command prompt, type:

1 add lb vserver <name> HTTP <ip> <port>

Example:

1 add lb vserver Vserver-LB-1 HTTP 10.102.29.60 80

To configure an HTTP virtual server to balance traffic sent to the servers by using the configura-
tion utility

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.

2. In the details pane, click Add.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2195

NetScaler 12.0

3. In the Create Virtual Server (Load Balancing) dialog box, specify values for the following param-
eters as shown:
• Name—name
• IP Address—IPAddress
Note: If the virtual server uses IPv6, select the
IPv6 check box and enter the address in IPv6 format (for example,
1000:0000:0000:0000:0005:0600:700a:888b).
• Port—port
4. Under Protocol, select HTTP.
5. Click Create, and then click Close. The virtual server you created appears in the Load Balancing
Virtual Servers pane.

Bind HTTP services to the HTTP virtual server

To bind HTTP services to the wildcard virtual server by using the command line interface

At the command prompt, type:

1 bind lb vserver <name> <serviceName>

Example:

1 bind lb vserver Vserver-LB-1 Service-HTTP-1

To bind HTTP services to the wildcard virtual server by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Virtual Servers, and select a virtual server.
2. Click in the Service section, and select a service to bind.

Note: You can bind a service to multiple virtual servers.

Save and Verify the Configuration

When you’ve finished the configuration tasks, be sure to save the configuration. You should also check
to make sure that the settings are correct.

To save and verify the configuration by using the command line interface

At the command prompt, type the following commands to configure a transparent monitor and verify
the configuration:

• save ns config

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2196

NetScaler 12.0

• show vserver

Example:

1 save config
2 show lb vserver FWLBVIP2
3 FWLBVIP2 (*:*) - ANY Type: ADDRESS
4 State: UP
5 Last state change was at Mon Jun 14 07:22:54 2010
6 Time since last state change: 0 days, 00:00:32.760
7 Effective State: UP
8 Client Idle Timeout: 120 sec
9 Down state flush: ENABLED
10 Disable Primary Vserver On Down : DISABLED
11 No. of Bound Services : 2 (Total) 2 (Active)
12 Configured Method: LEASTCONNECTION
13 Current Method: Round Robin, Reason: A new service is bound
14 Mode: MAC
15 Persistence: NONE
16 Connection Failover: DISABLED
17
18 1) fw-int-svc1 (10.102.29.5: *) - ANY State: UP Weight: 1
19 2) fw-int-svc2 (10.102.29.9: *) - ANY State: UP Weight: 1
20 Done
21 show service fw-int-svc1
22 fw-int-svc1 (10.102.29.5:*) - ANY
23 State: DOWN
24 Last state change was at Thu Jul 8 14:44:51 2010
25 Time since last state change: 0 days, 00:01:50.240
26 Server Name: 10.102.29.5
27 Server ID : 0 Monitor Threshold : 0
28 Max Conn: 0 Max Req: 0 Max Bandwidth: 0 kbits
29 Use Source IP: NO
30 Client Keepalive(CKA): NO
31 Access Down Service: NO
32 TCP Buffering(TCPB): NO
33 HTTP Compression(CMP): NO
34 Idle timeout: Client: 120 sec Server: 120 sec
35 Client IP: DISABLED
36 Cacheable: NO
37 SC: OFF
38 SP: OFF
39 Down state flush: ENABLED
40
41 1) Monitor Name: monitor-HTTP-1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2197

NetScaler 12.0

42 State: DOWN Weight: 1

43 Probes: 9 Failed [Total: 9 Current: 9]
44 Last response: Failure - Time out during TCP connection
establishment stage
45 Response Time: 2000.0 millisec
46 2) Monitor Name: ping
47 State: UP Weight: 1
48 Probes: 3 Failed [Total: 0 Current: 0]
49 Last response: Success - ICMP echo reply received.
50 Response Time: 1.275 millisec
51 Done

To save and verify the configuration by using the configuration utility

1. In the details pane, click Save.

2. In the Save Config dialog box, click Yes.
3. Navigate to Traffic Management > Load Balancing > Virtual Servers.
4. In the details pane, select the virtual server that you created in step 5 and verify that the settings
displayed in the Details pane are correct.
5. Navigate to Traffic Management > Load Balancing > Services.
6. In the details pane, select the service that you created in step 5 and verify that the settings dis-
played in the Details pane are correct.

Monitoring a Firewall Load Balancing Setup in an Enterprise Environment

After the configuration is up and running, you should view the statistics for each service and virtual
server to check for possible problems.

Viewing the Statistics of a Virtual Server

To evaluate the performance of virtual servers or to troubleshoot problems, you can display details of
the virtual servers configured on the NetScaler appliance. You can display a summary of statistics for
all the virtual servers, or you can specify the name of a virtual server to display the statistics only for
that virtual server. You can display the following details:

• Name
• IP address
• Port
• Protocol
• State of the virtual server

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2198

NetScaler 12.0

• Rate of requests received

• Rate of hits

To display virtual server statistics by using the command line interface

To display a summary of the statistics for all the virtual servers currently configured on the NetScaler
appliance, or for a single virtual server, at the command prompt, type:

1 stat lb vserver [-detail] [<name>]

Example:

1 >stat lb vserver -detail

2 Virtual Server(s) Summary
3 vsvrIP port Protocol State Req/s
Hits/s
4 One * 80 HTTP UP 5/s
0/s
5 Two * 0 TCP DOWN 0/s
0/s
6 Three * 2598 TCP DOWN 0/s
0/s
7 dnsVirtualNS 10.102.29.90 53 DNS DOWN 0/s
0/s
8 BRVSERV 10.10.1.1 80 HTTP DOWN 0/s
0/s
9 LBVIP 10.102.29.66 80 HTTP UP 0/s
0/s
10 Done

To display virtual server statistics by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Virtual Servers > Statistics.
2. If you want to display the statistics for only one virtual server, in the details pane, select the
virtual server, and click Statistics.

Viewing the Statistics of a Service

Updated: 2013-08-28

You can view the rate of requests, responses, request bytes, response bytes, current client connec-
tions, requests in surge queue, current server connections, and so forth using the service statistics.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2199

NetScaler 12.0

To view the statistics of a service by using the command line interface

At the command prompt, type:

1 stat service <name>

Example:

1 stat service Service-HTTP-1

To view the statistics of a service by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Services > Statistics.
2. If you want to display the statistics for only one service, select the service, and click Statistics.

1.
2. Citrix ADC
3. NetScaler 12.0

Multiple-Firewall Environment

January 6, 2019

Contributed by:
C

In a multiple-firewall environment, the NetScaler appliance is placed between two sets of firewalls,
the external set connecting to the public Internet, and the internal set connecting to the internal pri-
vate network. The external set typically handles the egress traffic. These firewalls mainly implement
access control lists to allow or deny access to external resources. The internal set typically handles
the ingress traffic. These firewalls implement security to safeguard the intranet from malicious at-
tacks apart from load-balancing the ingress traffic. The multiple-firewall environment allows you to
load-balance traffic coming from another firewall. By default, the traffic coming from a firewall is not
load balanced on the other firewall across a NetScaler appliance. Having firewall load balancing en-
abled on both the sides of NetScaler improves the traffic flow in both the egress and ingress direction
and ensures faster processing of the traffic.

The following figure shows a multiple-firewall load balancing environment

Figure 1. Firewall Load Balancing (multiple-firewall)

With a configuration like the one shown in Figure 1, you can configure the NetScaler to load balance the
traffic through the an internal firewall even if it is load balanced by an external firewall. For example,

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2200

NetScaler 12.0

with this feature configured, the traffic coming from the external firewalls (firewalls 1, 2, and 3) is load
balanced on the internal firewalls (firewalls 4, 5, and 6) and vice versa.

Firewall load balancing is supported only for MAC mode LB virtual server.

The service type ANY configures the NetScaler to accept all traffic.

To avail benefits related to HTTP and TCP, configure the service and virtual server with type HTTP or
TCP. For FTP to work, configure the service with type FTP.

Configuring the NetScaler in a Multiple-Firewall Environment

To configure a NetScaler appliance in a multiple-firewall environment, you have to enable the load
balancing feature, configure a virtual server to load balance the egress traffic across the external fire-
walls, configure a virtual server to load balance the ingress traffic across the internal firewalls, and
enable firewall load balancing on the NetScaler appliance. To configure a virtual server to load bal-
ance traffic across a firewall in the multiple-firewall environment, you need to:

1. Configure a wildcard service for each firewall

2. Configure a monitor for each wildcard service
3. Configure a wildcard virtual server to load balance the traffic sent to the firewalls
4. Configure the virtual server in MAC rewrite mode
5. Bind firewall services to the wildcard virtual server

Enabling the load balancing feature

To configure and implement load balancing entities such as services and virtual servers, you need to
enable the load balancing feature on the NetScaler device.

To enable load balancing by using the CLI:

At the command prompt, type the following command to enable load balancing and verify the config-
uration:

1 enable ns feature <featureName>

2 show ns feature

Example:

1 enable ns feature LoadBalancing

2 Done
3 show ns feature
4 Feature Acronym Status
5 ------- ------- ------
6 1) Web Logging WL OFF

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2201

NetScaler 12.0

7 2) Surge Protection SP ON
8 3) Load Balancing LB ON
9 .
10 .
11 .
12 24) NetScaler Push push OFF
13 Done

To enable load balancing by using the GUI:

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

2. In the Settings pane, under Modes and Features, click Change basic features.
3. In the Configure Basic Features dialog box, select the Load Balancing check box, and then click
Ok.

Configuring a wildcard service for each firewall

To accept traffic from all the protocols, you need to configure wildcard service for each firewall by
specifying support for all the protocols and ports.

To configure a wildcard service for each firewall by using the CLI:

At the command prompt, type the following command to configure support for all the protocols and
ports:

1 add service <name>@ <serverName> <serviceType> <port_number>

Example:

1 add service fw-svc1 10.102.29.5 ANY *

To configure a wildcard service for each firewall by using the GUI:

1. Navigate to Traffic Management > Load Balancing > Services.

2. In the details pane, click Add.

3. In the Create Services dialog box, specify values for the following parameters as shown:

• Service Name—name
• Server—serverName

-* A required parameter

4. In Protocol, select Any and in Port, select *.

5. Click Create, and then click Close. The service you created appears in the Services pane.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2202

NetScaler 12.0

Configuring a monitor for each service

A PING monitor is bound by default to the service. You will need to configure a transparent monitor
to monitor hosts on the trusted side through individual firewalls. You can then bind the transparent
monitor to services. The default PING monitor monitors the connectivity only between the NetScaler
appliance and the upstream device. The transparent monitor monitors all the devices existing in the
path from the appliance to the device that owns the destination IP address specified in the monitor.
If a transparent monitor is not configured and the status of the firewall is UP but one of the next hop
devices from that firewall is down, the appliance includes the firewall while performing load balancing
and forwards the packet to the firewall. However, the packet is not delivered to the final destination
because one of the next hop devices is down. By binding a transparent monitor, if any of the devices
(including the firewall) are down, the service is marked as DOWN and the firewall is not included when
the appliance performs firewall load balancing.

Binding a transparent monitor will override the PING monitor. To configure a PING monitor in addition
to a transparent monitor, after you create and bind a transparent monitor, you need to bind a PING
monitor to the service.

To configure a transparent monitor by using the CLI:

At the command prompt, type the following commands to configure a transparent monitor and verify
the configuration:

1 add lb monitor <monitorName> <type> [-destIP <ip_addr|ipv6_addr|*>] [-

transparent (YES | NO )]
2 bind lb monitor <monitorName> <serviceName>

Example:

1 add monitor monitor-HTTP-1 HTTP -destip 10.10.10.11 -transparent YES

2 bind monitor monitor-HTTP-1 fw-svc1

To create and bind a transparent monitor by using the GUI:

1. Navigate to Traffic Management > Load Balancing > Monitors.

2. In the details pane, click Add.

3. In the Create Monitor dialog box, specify values for the following parameters as shown:

• Name*
• Type*—type
• Destination IP
• Transparent

-* A required parameter

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2203

NetScaler 12.0

4. Click Create, and then click Close. In the Monitors pane, select the monitor that you just config-
ured and verify that the settings displayed at the bottom of the screen are correct.

Configuring a virtual server to load balance the traffic sent to the firewalls

To load balance any kind of traffic, you need to configure a wildcard virtual server specifying the pro-
tocol and port as any value.

To configure a virtual server to load balance the traffic sent to the firewalls by using the CLI:

At the command prompt, type the following command:

1 add lb vserver <name>@ <serviceType> <IPAddress> <port_number>

Example:

1 add lb vserver Vserver-LB-1 ANY * *

To configure a virtual server to load balance the traffic sent to the firewalls by using the GUI:

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.

2. In the details pane, click Add.
3. In Protocol, select Any, and in IP Address and Port, select *.
4. Click Create, and then click Close. The virtual server you created appears in the Load Balancing
Virtual Servers pane.

Configuring the virtual server to MAC rewrite mode

To configure the virtual server to use MAC address for forwarding the incoming traffic, you need to
enable the MAC rewrite mode.

To configure the virtual server in MAC rewrite mode by using the CLI:

At the command prompt, type the following command:

1 set lb vserver <name>@ -m <RedirectionMode>

Example:

1 set lb vserver Vserver-LB-1 -m MAC

To configure the virtual server in MAC rewrite mode by using the GUI:

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2204

NetScaler 12.0

2. In the details pane, select the virtual server for which you want to configure the redirection
mode (for example, Vserver-LB1), and then click Open.
3. On the Advanced tab, under the Redirection Mode mode, click Open.
4. Click Ok.

Binding firewall services to the virtual server

To access a service on NetScaler appliance, you need to bind it to a wildcard virtual server.

To bind firewall services to the virtual server by using the CLI:

At the command prompt, type the following command:

1 bind lb vserver <name>@ <serviceName>

Example:

1 bind lb vserver Vserver-LB-1 Service-HTTP-1

To bind firewall services to the virtual server by using the GUI:

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.

2. In the details pane, select the virtual server for which you want to configure the redirection
mode (for example, Vserver-LB1), and then click Open.
3. In the Configure Virtual Server (Load Balancing) dialog box, on the Services tab, select the Active
check box next to the service that you want to bind to the virtual server(for example, Service-
HTTP-1 ).
4. Click Ok.

Configuring the multiple-firewall load balancing on the NetScaler appliance

To load balance traffic on both the sides of a NetScaler using firewall load balancing, you need to
enable mulitpl-firewall load balancing by using the vServerSpecificMac parameter.

To configure multiple-firewall load balancing by using the CLI:

At the command prompt, type the following command:

1 set lb parameter -vServerSpecificMac <status>

Example:

1 set lb parameter -vServerSpecificMac ENABLED

To configure multiple-firewall load balancing by using the GUI:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2205

NetScaler 12.0

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.

2. In the details pane, select the virtual server for which you want to configure the redirection
mode (for example, Configure Load Balancing parameters).
3. In the Set Load Balancing Parameters dialog box, select the Virtual Server Specific MAC check
box.
4. Click Ok.

Saving and Verifying the Configuration

When you’ve finished the configuration tasks, be sure to save the configuration. You should also check
to make sure that the settings are correct.

To save and verify the configuration by using the CLI:

At the command prompt, type the following commands to configure a transparent monitor and verify
the configuration:

• save ns config
• show vserver

Example:

1 save config
2 show lb vserver FWLBVIP2
3 FWLBVIP2 (*:*) - ANY Type: ADDRESS
4 State: UP
5 Last state change was at Mon Jun 14 07:22:54 2010
6 Time since last state change: 0 days, 00:00:32.760
7 Effective State: UP
8 Client Idle Timeout: 120 sec
9 Down state flush: ENABLED
10 Disable Primary Vserver On Down : DISABLED
11 No. of Bound Services : 2 (Total) 2 (Active)
12 Configured Method: LEASTCONNECTION
13 Current Method: Round Robin, Reason: A new service is bound
14 Mode: MAC
15 Persistence: NONE
16 Connection Failover: DISABLED
17
18 1) fw-int-svc1 (10.102.29.5: *) - ANY State: UP Weight: 1
19 2) fw-int-svc2 (10.102.29.9: *) - ANY State: UP Weight: 1
20 Done
21 show service fw-int-svc1
22 fw-int-svc1 (10.102.29.5:*) - ANY
23 State: DOWN

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2206

NetScaler 12.0

24 Last state change was at Thu Jul 8 14:44:51 2010

25 Time since last state change: 0 days, 00:01:50.240
26 Server Name: 10.102.29.5
27 Server ID : 0 Monitor Threshold : 0
28 Max Conn: 0 Max Req: 0 Max Bandwidth: 0 kbits
29 Use Source IP: NO
30 Client Keepalive(CKA): NO
31 Access Down Service: NO
32 TCP Buffering(TCPB): NO
33 HTTP Compression(CMP): NO
34 Idle timeout: Client: 120 sec Server: 120 sec
35 Client IP: DISABLED
36 Cacheable: NO
37 SC: OFF
38 SP: OFF
39 Down state flush: ENABLED
40
41 1) Monitor Name: monitor-HTTP-1
42 State: DOWN Weight: 1
43 Probes: 9 Failed [Total: 9 Current: 9]
44 Last response: Failure - Time out during TCP connection
establishment stage
45 Response Time: 2000.0 millisec
46 2) Monitor Name: ping
47 State: UP Weight: 1
48 Probes: 3 Failed [Total: 0 Current: 0]
49 Last response: Success - ICMP echo reply received.
50 Response Time: 1.275 millisec
51 Done

**To save and verify the configuration by using the GUI:

1. In the details pane, click Save.

2. In the Save Config dialog box, click Yes.
3. Navigate to Traffic Management > Load Balancing > Virtual Servers.
4. In the details pane, select the virtual server that you created in step 5 and verify that the settings
displayed in the Details pane are correct.
5. Navigate to Traffic Management > Load Balancing > Services.
6. In the details pane, select the service that you created in step 5 and verify that the settings dis-
played in the Details pane are correct.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2207

NetScaler 12.0

Monitoring a Firewall Load Balancing Setup in a Multiple-Firewall Environment

After the configuration is up and running, you should view the statistics for each service and virtual
server to check for possible problems.

Viewing the Statistics of a Virtual Server

To evaluate the performance of virtual servers or to troubleshoot problems, you can display details of
the virtual servers configured on the NetScaler appliance. You can display a summary of statistics for
all the virtual servers, or you can specify the name of a virtual server to display the statistics only for
that virtual server. You can display the following details:
• Name
• IP address
• Port
• Protocol
• State of the virtual server
• Rate of requests received
• Rate of hits
To display virtual server statistics by using the CLI:
To display a summary of the statistics for all the virtual servers currently configured on the NetScaler
appliance, or for a single virtual server, at the command prompt, type:

1 stat lb vserver [-detail] [<name>]

Example:

1 >stat lb vserver -detail

2 Virtual Server(s) Summary
3 vsvrIP port Protocol State Req/s
Hits/s
4 One * 80 HTTP UP 5/s
0/s
5 Two * 0 TCP DOWN 0/s
0/s
6 Three * 2598 TCP DOWN 0/s
0/s
7 dnsVirtualNS 10.102.29.90 53 DNS DOWN 0/s
0/s
8 BRVSERV 10.10.1.1 80 HTTP DOWN 0/s
0/s
9 LBVIP 10.102.29.66 80 HTTP UP 0/s
0/s

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2208

NetScaler 12.0

10 Done

To display virtual server statistics by using the GUI:

1. Navigate to Traffic Management > Load Balancing > Virtual Servers > Statistics.
2. If you want to display the statistics for only one virtual server, in the details pane, select the
virtual server, and click Statistics.

Viewing the Statistics of a Service

You can view the rate of requests, responses, request bytes, response bytes, current client connec-
tions, requests in surge queue, current server connections, and so forth using the service statistics.

To view the statistics of a service by using the CLI:

At the command prompt, type:

1 stat service <name>

Example:

1 stat service Service-HTTP-1

To view the statistics of a service by using the GUI:

1. Navigate to Traffic Management > Load Balancing > Services > Statistics.
2. If you want to display the statistics for only one service, select the service, and click Statistics.

1.
2. Citrix ADC
3. NetScaler 12.0

Global Server Load Balancing

September 14, 2018

Contributed by:
C
Note

This feature is available as an option with a NetScaler standard edition license, but is included
with the enterprise and platinum edition licenses.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2209

NetScaler 12.0

NetScaler appliances configured for global server load balancing (GSLB) provide for disaster recovery
and ensure continuous availability of applications by protecting against points of failure in a wide
area network (WAN). GSLB can balance the load across data centers by directing client requests to the
closest or best performing data center, or to surviving data centers in case of an outage.

In a typical configuration, a local DNS server sends client requests to a GSLB virtual server, to which are
bound GSLB services. A GSLB service identifies a load balancing or content switching virtual server,
which can be at the local site or a remote site. If the GSLB virtual server selects a load balancing or
content switching virtual server at a remote site, it sends the virtual server’s IP address to the DNS
server, which sends it to the client. The client then resends the request to the new virtual server at
the new IP.

The GSLB entities that you must configure are the GSLB sites, the GSLB services, the GSLB virtual
servers, load balancing or content switching virtual servers, and authoritative DNS (ADNS) services.
You must also configure MEP. You can also configure DNS views to expose different parts of your net-
work to clients accessing the network from different locations.

Note

To take full advantage of the NetScaler GSLB features, you should use NetScaler appliances for
load balancing or content switching at each data center, so that your GSLB configuration can use
the proprietary Metric Exchange Protocol (MEP) to exchange site metrics.

1.
2. Citrix ADC
3. NetScaler 12.0

GSLB deployment types

September 12, 2018

Contributed by:
C

NetScaler appliances configured for global server load balancing (GSLB) provide for disaster recovery
and ensure continuous availability of applications by protecting against points of failure in a wide
area network (WAN). GSLB can balance the load across data centers by directing client requests to the
closest or best performing data center, or to surviving data centers in the event of an outage.

The following are some of the typical GSLB deployment types:

• Active-active site deployment

• Active-passive site deployment

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2210

NetScaler 12.0

• Parent-child topology deployment

1.
2. Citrix ADC
3. NetScaler 12.0

Active-active site deployment

January 6, 2019

Contributed by:
C

An active-active site consists of multiple active data centers. Client requests are load balanced across
active data centers. This deployment type can be used when you have a need for global distribution
of traffic in a distributed environment.

All the sites in an active-active deployment are active, and all the services for a particular application/-
domain are bound to the same GSLB vserver. Sites exchange metrics through the Metrics Exchange
Protocol (MEP). Site metrics exchanged between the sites include the status of each load balancing
and content switching virtual server, current number of connections, current packet rate, and current
bandwidth usage. The NetScaler appliance needs this information to perform load balancing across
the sites.

An active-active deployment can include a maximum of 32 GSLB sites, because MEP cannot synchro-
nize more than 32 sites. No backup sites are configured in this deployment type.

The NetScaler appliance sends client requests to the appropriate GSLB site as determined by the GSLB
method specified in the GSLB configuration.

For an active-active deployment, you can configure the following GSLB methods.

• Round Robin
• Least Connections
• Least Response Time
• Least Bandwidth
• Least Packets
• Source IP Hash
• Custom Load
• Round Trip Time (RTT)
• Static Proximity

Note:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2211

NetScaler 12.0

• If MEP is disabled, the following algorithm methods default to Round Robin.

– RTT
– Least Connections
– Least Bandwidth
– Least Packets
– Least Response Time
• In the static proximity GLSB method, the appliance sends the request to the IP address of the
site that best matches the proximity criteria.
• In the Round Trip Time method, the dynamic round trip time (RTT) values are to select the IP
address of the best performing site. RTT is a measure of the delay in the network between the
client’s local DNS server and a data resource.

GSLB active-active datacenter topology

In the diagram, Site 1 and Site 2 are active GLSB sites.

When the client sends a DNS request, it lands in one of the active sites.

If Site 1 receives the client request, the GSLB virtual server in Site 1 selects a load balancing or content
switching virtual server and sends the virtual server’s IP address to the DNS server, which sends it to
the client. The client then resends the request to the new virtual server at the new IP address.

As both sites are active, the GSLB algorithm evaluates the services at both sites when making a selec-
tion as determined by the configured GSLB method.

1.
2. Citrix ADC
3. NetScaler 12.0

Active-passive site deployment

January 6, 2019

Contributed by:
C

An active-passive site consists of an active and a passive data center. This deployment type is ideal for
disaster recovery.

In this type of deployment, some of the sites (remote sites) are reserved only for disaster recovery.
These sites do not participate in any decision making until all the active sites are DOWN. A passive site
does not become operational unless a disaster event triggers a failover.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2212

NetScaler 12.0

Once you have configured the primary data center, replicate the configuration for the backup data
center and designate it as the passive GSLB site by designating a GSLB virtual server at that site as the
backup virtual server.

An active-passive deployment can include a maximum of 32 GSLB sites, because MEP cannot synchro-
nize more than 32 sites.

For an active-passive deployment, you can configure the following GSLB methods.

• Round Robin
• Least Connections
• Least Response Time
• Least Bandwidth
• Least Packets
• Source IP Hash
• Custom Load
• Round Trip Time (RTT)
• Static Proximity

Note:

• If MEP is disabled, the following algorithm methods default to Round Robin.

– RTT
– Least Connections
– Least Bandwidth
– Least Packets
– Least Response Time
• In the static proximity GLSB method, the appliance sends the request to the IP address of the
site that best matches the proximity criteria.
• In the Round Trip Time method, the dynamic round trip time (RTT) values are to select the IP
address of the best performing site. RTT is a measure of the delay in the network between the
client’s local DNS server and a data resource.

GSLB active-passive datacenter topology

In the diagram, Site 1 is an active site and Site 2 is a passive site, which has the same configuration as
that of Site 1.

If Site 1 goes DOWN, Site 2 becomes operational.

When the client sends a DNS request, the request can land in any of the sites. However, the services
are selected only from the active site (Site1) as long as it is UP.

Services from the passive site (Site 2) are selected only if the active site (Site 1) is DOWN.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2213

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0

Parent-child topology deployment using the MEP protocol

January 6, 2019

Contributed by:
C

NetScaler GSLB provides global server load balancing and disaster recovery by creating mesh con-
nections between all the involved sites and making intelligent load balancing decisions. Each site
communicates with the others to exchange server and network metrics through Metric Exchange Pro-
tocol (MEP), at regular intervals. However, with the increase in number of peer sites, the volume of
MEP traffic increases exponentially because of the mesh topology. To overcome this, you can use a
parent-child topology. The parent-child topology also supports larger deployments. In addition to
the 32 parent sites, you can configure 1024 child sites.

The GSLB parent-child topology is a two-level hierarchical design with the following characteristics:

• At the top level are parent sites, which have peer relationships with other parents.
• Each parent can have multiple child sites.
• Each parent site exchanges health information with its child sites and with other parent sites.
• A child site communicates only with its parent site.
• In a parent-child relationship for GSLB, only the parent site responds to ADNS queries. The child
sites act as normal load balancing sites.
• An ADNS service or DNS load balancing virtual servers should be configured only in the parent
site.
• A parent site can have a normal GSLB configuration, that is, services from local and all remote
sites, but a child site can have local services only. Also, only the parent sites have GSLB virtual
servers configured.

Note

• In a parent-child topology, the exchange of site metrics is initiated from the lower of two IP
addresses. However, from NetScaler release 11.1 build 51.x, the parent sites initiate connec-
tions to the child sites, and not vice versa, because the parent sites have information about
all the child sites in the GSLB setup.

• In a parent-parent connection, the exchange of site metrics is still initiated from the lower IP of
two IP addresses.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2214

NetScaler 12.0

• In a parent-child topology, GSLB services are not always required to be configured on a child site.
However, if you have additional configuration such as client authentication, client IP address
insertion, or other SSL-specific requirement, you must add an explicit GSLB service on the child
site and configure it accordingly.

• In a parent-child topology, the parent site and the child site can be on differentNetScaler soft-
ware versions. However, to use the GSLB automaticConfigSync option to synchronize the con-
figuration across the parent sites, all parent sites must be on the sameNetScaler software ver-
sions. If you are not using the automaticConfigSync option, then the parent site and the child
site can be on differentNetScaler software versions but make sure that you are not using any of
the new features in the latest release. This is also applicable, in general, to two NetScaler nodes
participating in GSLB.

Basic parent-child topology

In the diagram, Site P1 and Site P2 are parent sites in a peer relationship. Site P1C1 and P2C1 are the
child sites of P1 and P2 respectively.

Setting up a parent-child configuration for GSLB

If you have a firewall configured at a GSLB site, make sure that port 3011 is open.

The following diagram displays a sample parent-child configuration.

• The configuration of a child site includes the child site and its parent site, but no other parent
or child sites.
• Network metrics, such as RTT and persistence session information, are synchronized only
across the parent sites. Therefore, parameters such as nwMetricExchange and sessionEx-
change are disabled by default on all the child sites.
• To verify correct parent-child configuration, check the states of all the GSLB services bound to
the parent sites.

To set up a parent-child configuration for GSLB by using the CLI:

1. On each parent site, enter the following commands:

1 add gslb site <siteName> <siteIPAddress> [-publicIP <ip_addr|ipv6_addr

|*>]

1 add gslb site <siteName> <siteIPAddress> [-publicIP <ip_addr|ipv6_addr

|*>] [-parentSite <string>]

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2215

NetScaler 12.0

1 add gslb site GSLB_Site1 10.1.1.1 - publicIP 10.1.1.1

1 add gslb site Site1_child1 1 10.1.1.2 -publicIP 10.1.1.2 -parentSite

GSLB_Site1

2. On each child site, enter the following commands:

1 add gslb site <siteName> <siteIPAddress> [-publicIP <ip_addr|ipv6_addr

|*>]
2
3  add gslb site <siteName> <siteIPAddress> [-publicIP <ip_addr|ipv6_addr
|*>] [-parentSite <string>]

Example:

1 add gslb site GSLB_Site1 10.1.1.1 - publicIP 10.1.1.1

2
3 add gslb site Site1_child1 1 10.1.1.2 -publicIP 10.1.1.2 -parentSite
GSLB_Site1

For a complete example of a parent-child configuration, using the command line interface, see Exam-
ple of a Complete Parent-Child Configuration, Using the CLI

Note

If the load balancing virtual server IP address is a private IP address and the public IP address is
different from this IP address, you need to configure a GSLB service for the local load balancing
virtual server on the child site. This is required for statistics collection between the parent and
the child site.

On the child site, at the command prompt, type:

add gslb service <name> <private IP/lb vserver IP> http 80 ‒sitename <
childsite name> -publicip <public IP of LB vserver>

Example:

add gslb service Service-GSLB 192.168.1.3 http 80 -GSLB_Site11 site 11_lb1 172.16.1.1

Where 192.168.1.3 is a private IP address of the load balancing virtual server and 172.16.1.1 is a
public IP address of the load balancing virtual server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2216

NetScaler 12.0

Backing up a parent site

Note: This feature was introduced in NetScaler release 11.1 build 51.x. To use the backup parent site
topology, make sure that the parent site and the child sites are on NetScaler 11.1 build 51.x and later.

The backup parent site topology is useful in scenarios wherein a large number of child sites are asso-
ciated with a parent site. If this parent site goes DOWN, all of its child sites become unavailable. To
prevent this, you can now configure a backup parent site to which the child sites can connect if the
original parent site is DOWN. The parent site sends the backup parent list to the child sites through
the MEP messages.

When a parent site is DOWN, the other parent sites in the GSLB get to know that a particular parent site
is DOWN through MEP because MEP to that parent site is DOWN. The other parent sites in the GSLB
setup look up the backup chain of the peer parent. The parent site with the highest preference adopts
the child sites of the parent that went DOWN. The new parent then initiates a connection with the
child site. A child site can accept or reject the connection after evaluating its existing connections and
the information in the backup list.
When the original parent site is back UP, it tries to establish connections with its child sites that have
migrated to a different parent. When a connection attempt is successful, the child site is reassigned
to its original parent site.

Note:

• Only parent sites can be configured as backups, and this configuration can only be done at the
parent site.
• All child sites use the backup parent set.
• Synchronization is done only on the parent sites. GSLB child sites’ configuration is not affected
by synchronization. This is because the parent site and the child site configurations are not
identical. The child sites configuration consists only of its own and its parent site’s details. Also,
GSLB services are not always required to be configured in the child sites.

Consider the configuration shown in the following figure, in which:

• SiteP1, SiteP2, and SiteP3 are the parent sites.

• Child_site1, Child_site2, and Child_site3 are the child sites of SiteP1, SiteP2, and Site P3 respec-
tively.
• Backup parent sites;
– SiteP1 backup parents - SiteP2 (higher preference) and Site P3
– SiteP2 backup parents – SiteP3 (higher preference) and Site P1
– SiteP3 backup parents – SiteP1 (higher preference) and Site P2

Note: For illustration purposes, the figure shows only one backup parent for each parent site.

The following list summarizes the behavior of the parent and child sites under various scenarios:

• Scenario 1: SiteP1 goes DOWN.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2217

NetScaler 12.0

– SiteP2 and SiteP3 detect that SiteP1’s MEP connection is DOWN. SiteP2 is higher in the
preference list of backup parents for SiteP1, so it tries to initiate a connection to Child_site1.
SiteP3 assumes that Child_site1 is now the child site of parent SiteP2.
– SiteP2 sends Child_Site1 the list of SiteP1’s backup parents (SiteP2 and SiteP3) to
Child_site1. Child_site1 uses the list to decide whether to accept or reject the connection
from SiteP2. It accepts the connection and becomes a child of SiteP2.
– When SiteP1 is back UP, it sends Child_site1 a connection request. The new request takes
precedence and Child_site 1 migrates to SiteP1.
• Scenario 2: Only the MEP connection between SiteP1 and SiteP2 has gone DOWN. Child_site1
rejects SiteP2’s connection request, because its parent, SiteP1, is still UP.
• Scenario 3: SiteP3 and Child_Site1 detect that SiteP1 is DOWN, and the MEP connection between
SiteP3 and SiteP2 is also DOWN. However, Site P2 detects that SiteP1 is UP, and the MEP con-
nection between SiteP1 and SiteP2 is UP.
– SiteP2 does not take any action.
– SiteP3 checks SiteP1’s backup list and finds that SiteP2 has a higher preference than
SiteP3. But SiteP2 is DOWN, so SiteP3 tries to establish a connection with Child_site1.
Child_site1 has detected that SiteP1 is DOWN, so it accepts SiteP3’s connection request.
– Now the connection between SiteP1 and SiteP2 goes DOWN. SiteP2 checks SiteP1’s backup
list and finds itself as the most preferred backup, so it tries to connect to Child_site1.
Child_site1 evaluates the new connection request based on SiteP1’s list and finds SiteP2
as the most preferred backup, so it migrates to SiteP2 from SiteP3.

To configure a backup parent site by using the command line interface

At the command prompt type:

1 set gslb site <sitename> -backupParentlist <bkp_site1> <bkp_site2> … <

bkp_site5>

<sitename> is the current parent site.

Note:
• You cannot add a new site as a backup parent. You must first add all the sites, and then configure
the site as a backup parent.
• To remove a backup parent, you must use the unset command, which unsets all the sites that
were previously configured as backup parent sites.

To configure a backup parent site by using the GUI

1. Navigate to Configuration > Traffic Management > GSLB > Sites.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2218

NetScaler 12.0

2. Add a new site or select an existing site.

3. Choose the Backup Parent Sites option box while creating or configuring the GSLB site.

1.
2. Citrix ADC
3. NetScaler 12.0

GSLB configuration entities

September 12, 2018

Contributed by:
C

A GSLB configuration consists of a group of GSLB entities on each appliance in the configuration.
These entities include the following:

• GSLB Sites
• GSLB Services
• GSLB Virtual Servers
• Load Balancing or Content Switching Virtual Servers
• ADNS Services
• DNS VIPs

GSLB Sites

A typical GSLB setup consists of data centers, each of which has various network appliances that may
or may not be NetScaler appliances. The data centers are called GSLB sites. Each GSLB site is managed
by a NetScaler appliance that is local to that site. Each of these appliances treats its own site as the
local site and all other sites, managed by other appliances, as remote sites.

If the appliance that manages a site is the only NetScaler appliance in that data center, the GSLB site
hosted on that appliance acts as a bookkeeping placeholder for auditing purposes, because no met-
rics can be collected. Typically, this happens when the appliance is used only for GSLB, and other
products in the data center are used for load balancing or content switching.

Relationships among GSLB Sites

The concept of sites is central to NetScaler GSLB implementations. Unless otherwise specified, sites
form a peer relationship among themselves. This relationship is used first to exchange health infor-

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2219

NetScaler 12.0

mation and then to distribute load as determined by the selected algorithm. In many situations, how-
ever, a peer relationship among all GSLB sites is not desirable. Reasons for not having an all-peer
implementation could be;

• To clearly separate GSLB sites. For example, to separate sites that participate in resolving DNS
queries from the traffic management sites.
• To reduce the volume of Metric Exchange Protocol (MEP) traffic, which increases exponentially
with an increasing number of peer sites.

These goals can be achieved by using parent and child GSLB sites.

GSLB Services

A GSLB service is usually a representation of a load balancing or content switching virtual server, al-
though it can represent any type of virtual server. The GSLB service identifies the virtual server’s
IP address, port number, and service type. GSLB services are bound to GSLB virtual servers on the
NetScaler appliances managing the GSLB sites. A GSLB service bound to a GSLB virtual server in the
same data center is local to the GSLB virtual server. A GSLB service bound to a GSLB virtual server in
a different data center is remote from that GSLB virtual server.
Note

Sites and services are inherently linked to indicate proximity between the two. That is, all ser-
vices must belong to a site, and are assumed to be in the same location as the GSLB site for
proximity purposes. Likewise, services and virtual servers are linked, so that the logic is linked
to the resources that are available.

GSLB Virtual Servers

A GSLB virtual server has one or more GSLB services bound to it, and load balances traffic among those
services. It evaluates the configured GSLB methods (algorithms) to select the appropriate service to
which to send a client request. Because the GSLB services can represent either local or remote servers,
selecting the optimal GSLB service for a request has the effect of selecting the data center that should
serve the client request.

The domain for which global server load balancing is configured must be bound to the GSLB virtual
server, because one or more services bound to the virtual server will serve requests made for that
domain.

Unlike other virtual servers configured on a NetScaler appliance, a GSLB virtual server does not have
its own virtual IP address (VIP).

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2220

NetScaler 12.0

Load Balancing or Content Switching Virtual Servers

A load balancing or content switching virtual server represents one or many physical servers on the
local network. Clients send their requests to the load balancing or content switching virtual server’s
virtual IP (VIP) address, and the virtual server balances the load across the physical servers. After a
GSLB virtual server selects a GSLB service representing either a local or a remote load balancing or
content switching virtual server, the client sends the request to that virtual server’s VIP address.

For more information about load balancing or content switching virtual servers and services, see Load
Balancing or Content Switching.

ADNS Services

An ADNS service is a special kind of service that responds only to DNS requests for domains for which
the NetScaler appliance is authoritative. When an ADNS service is configured, the appliance owns
that IP address and advertises it. Upon reception of a DNS request by an ADNS service, the appliance
checks for a GSLB virtual server bound to that domain. If a GSLB virtual server is bound to the domain,
it is queried for the best IP address to which to send the DNS response.

DNS VIPs

A DNS virtual IP is a virtual IP (VIP) address that represents a load balancing DNS virtual server on the
NetScaler appliance. DNS requests for domains for which the NetScaler appliance is authoritative can
be sent to a DNS VIP.

1.
2. Citrix ADC
3. NetScaler 12.0

GSLB methods

September 12, 2018

Contributed by:
C

Unlike traditional DNS servers that simply respond with the IP addresses of the configured servers,
a NetScaler appliance configured for GSLB responds with the IP addresses of the services, as deter-
mined by the configured GSLB method. By default, the GSLB virtual server is set to the least connec-

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2221

NetScaler 12.0

tion method. If all GSLB services are down, the appliance responds with the IP addresses of all the
configured GSLB services.

GSLB methods are algorithms that the GSLB virtual server uses to select the best-performing GSLB
service. After the host name in the Web address is resolved, the client sends traffic directly to the
resolved service IP address.

The NetScaler appliance provides the following GSLB methods:

• Round Robin
• Least Connections
• Least Response Time
• Least Bandwidth
• Least Packets
• Source IP Hash
• Custom Load
• Round Trip Time (RTT)
• Static Proximity

For GSLB methods to work with a remote site, either MEP must be enabled or explicit monitors must
be bound to the remote services. If MEP is disabled, RTT, Least Connections, Least Bandwidth, Least
Packets and Least Response Time methods default to Round Robin.

The Static Proximity and RTT load balancing methods are specific to GSLB.

Specifying a GSLB method other than static proximity or dynamic RTT

For information about the Round Robin, Least Connections, Least Response Time, Least Bandwidth,
Least Packets, Source IP Hash, or Custom Load method, see “
Load Balancing.”

To change the GSLB method by using the CLI

At the command prompt, type:

1 set gslb vserver <name> -lbMethod GSLBMethod

Example:

1 set gslb vserver Vserver-GSLB-1 -lbMethod ROUNDROBIN

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2222

NetScaler 12.0

To change the GSLB method by using the GUI

1. Navigate to Traffic Management > GSLB > Virtual Servers.

2. In the details pane, select a GSLB virtual server and click Open.
3. In the Configure GSLB Virtual Server dialog box, on the Method and Persistence tab, under
Method, select a method from the Choose Method list.
4. Click OK, and verify that the method you selected appears under Details at the bottom of the
screen.

1.
2. Citrix ADC
3. NetScaler 12.0

GSLB algorithms

April 12, 2019

Contributed by:
C

The following algorithm are supported for GSLB.

• Round Robin: When a GSLB virtual server is configured to use the round robin method, it con-
tinuously rotates a list of the services that are bound to it. When the virtual server receives a
request, it assigns the connection to the first service in the list, and then moves that service to
the bottom of the list.
• Least Response Time: When the GSLB virtual server is configured to use the least response
time method, it selects the service with the fewest active connections and the lowest average
response time. You can configure this method for HTTP and Secure Sockets Layer (SSL) services
only. The response time (also called Time to First Byte, or TTFB) is the time interval between
sending a request packet to a service and receiving the first response packet from the service.
The NetScaler appliance uses response code 200 to calculate TTFB.
• Least Connections: When a GSLB virtual server is configured to use the least connection GSLB
algorithm (or method), it selects the service with the fewest active connections. This is the de-
fault method, because, in most circumstances, it provides the best performance.
• Least Bandwidth: A GSLB virtual server configured to use the least bandwidth method selects
the service that is currently serving the least amount of traffic, measured in megabits per second
(Mbps).
• Least Packets: A GSLB virtual server configured to use the least packets method selects the
service that has received the fewest packets in the last 14 seconds.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2223

NetScaler 12.0

• Source IP Hash: A GSLB virtual server configured to use the source IP hash method uses the
hashed value of the client IPv4 or IPv6 address to select a service. To direct all requests from
source IP addresses that belong to a particular network to a specific destination server, you
must mask the source IP address. For IPv4 addresses, use the netMask parameter. For IPv6
addresses, use the v6NetMaskLength parameter.
• Custom Load: Custom load balancing is performed on server parameters such as CPU usage,
memory, and response time. When using the custom load method, the NetScaler appliance
usually selects a service that is not handling any active transactions. If all of the services in the
GSLB setup are handling active transactions, the appliance selects the service with the smallest
load. A special type of monitor, known as a load monitor, calculates the load on each service in
the network. The load monitors do not mark the state of a service, but they do take services out
of the GSLB decision when those services are not UP.

For more details, see Load Balancing.

1.
2. Citrix ADC
3. NetScaler 12.0

Static proximity

September 12, 2018

Contributed by:
C

The static proximity method for GSLB uses an IP-address based static proximity database to deter-
mine the proximity between the client’s local DNS server and the GSLB sites. The NetScaler appliance
responds with the IP address of a site that best matches the proximity criteria.

If two or more GSLB sites at different geographic locations serve the same content, the NetScaler
appliance maintains a database of IP address ranges and uses the database for decisions about the
GSLB sites to which to direct incoming client requests.

For the static proximity method to work, you must either configure the NetScaler appliance to use
an existing static proximity database populated through a location file or add custom entries to the
static proximity database. After adding custom entries, you can set their location qualifiers. After
configuring the database, you are ready to specify static proximity as the GSLB method.

For details about configuring static proximity, see Configuring Static Proximity.

1.
2. Citrix ADC

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2224

NetScaler 12.0

3. NetScaler 12.0

Dynamic round trip time method

September 20, 2018

Contributed by:
C

Dynamic round trip time (RTT) is a measure of time or delay in the network between the client’s local
DNS server and a data resource. To measure dynamic RTT, the NetScaler appliance probes the client’s
local DNS server and gathers RTT metric information. The appliance then uses this metric to make its
load balancing decision. Global server load balancing monitors the real-time status of the network
and dynamically directs the client request to the data center with the lowest RTT value.

When a client’s DNS request for a domain comes to the NetScaler appliance configured as the author-
itative DNS for that domain, the appliance uses the RTT value to select the IP address of the best
performing site to send it as a response to the DNS request.

The NetScaler appliance uses different mechanisms, such as ICMP echo request / reply (PING), UDP,
and TCP to gather the RTT metrics for connections between the local DNS server and participating
sites. The appliance first sends a ping probe to determine the RTT. If the ping probe fails, a DNS UDP
probe is used. If that probe also fails, the appliance uses a DNS TCP probe.

These mechanisms are represented on the NetScaler appliance as Load Balancing Monitors and are
easily identified due to their use of the “ldns” prefix. The three monitors, in their default order, are:

• ldns-ping
• ldns-dns
• ldns-tcp

These monitors are built in to the appliance and are set to safe defaults, but may be customized just
like any other monitor on the appliance.

The default order may also be changed by setting it explicitly as a GSLB parameter. For example, to set
the order to be the DNS UDP query followed by the PING and then TCP, type the following command:

set gslb parameter -ldnsprobeOrder DNS PING TCP

Unless they have been customized, the NetScaler appliance performs UDP and TCP probing on port
53, however unlike regular load balancing monitors the probes need not be successful in order to
provide valid RTT information. ICMP port unavailable messages, TCP Resets and DNS error responses,
which would usually constitute a failure are all acceptable for calculating the RTT value.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2225

NetScaler 12.0

Once the RTT data has been compiled, the appliance uses the proprietary metrics exchange protocol
(MEP) to exchange RTT values between participating sites. After calculating RTT metrics, the appliance
sorts the RTT values to identify the data center with the best (smallest) RTT metric.”

If RTT information is not available (for example, when a client’s local DNS server accesses the site for
the first time), the NetScaler appliance selects a site by using the round robin method and directs the
client to the site.

To configure the dynamic method, you configure the site’s GSLB virtual server for dynamic RTT. You
can also set the interval at which local DNS servers are probed to a value other than the default.

Configure a GSLB virtual server for dynamic RTT

To configure a GSLB virtual server for dynamic RTT, you specify the RTT load balancing method.

The NetScaler appliance regularly validates the timing information for a given local server. If a change
in latency exceeds the configured tolerance factor, the appliance updates its database with the new
timing information and sends the new value to other GSLB sites by performing a MEP exchange. The
default tolerance factor is 5 milliseconds (ms).

The RTT tolerance factor must be the same throughout the GSLB domain. If you change it for a site,
you must configure identical RTT tolerance factors on all NetScaler appliances deployed in the GSLB
domain.

To configure a GSLB virtual server for dynamic RTT by using the command line interface

At the command prompt, type:

1 set gslb vserver <name> -lbMethod RTT -tolerance <value>

Example:

1 set gslb vserver Vserver-GSLB-1 -lbMethod RTT -tolerance 10

To configure a GSLB virtual server for dynamic RTT by using the configuration utility

Navigate to Traffic Management > GSLB > Virtual Servers and double-click the virtual server.

Set the probing interval of local DNS servers

The NetScaler appliance uses different mechanisms, such as ICMP echo request / reply (PING), TCP,
and UDP to obtain RTT metrics for connections between the local DNS server and participating GSLB

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2226

NetScaler 12.0

sites. By default, the appliance uses a ping monitor and probes the local DNS server every 5 seconds.
The appliance then waits 2 seconds for the response and, if a response is not received in that time, it
uses the TCP DNS monitor for probing.

However, you can modify the time interval for probing the local DNS server to accommodate your
configuration.

To modify the probing interval by using the command line interface

At the command prompt, type:

1 set lb monitor <monitorName> <type> -interval <integer> <units> -

resptimeout <integer> <units>

Example:

1 set lb monitor monitor-HTTP-1 HTTP -interval 10 sec -resptimeout 5 sec

To modify the probing interval by using the configuration utility

Navigate to Traffic Management > Load Balancing > Monitors, and double-click the monitor that
you want to modify (for example, PING).

1.
2. Citrix ADC
3. NetScaler 12.0

Configure static proximity

September 12, 2018

Contributed by:
C

For the static proximity method to work, you must either configure the NetScaler appliance to use
an existing static proximity database populated through a location file or add custom entries to the
static proximity database. After adding custom entries, you can set their location qualifiers. After
configuring the database, you are ready to specify static proximity as the GSLB method.

This document includes the following information:

• Adding a Location File to Create a Static Proximity Database

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2227

NetScaler 12.0

• Adding Custom Entries to a Static Proximity Database

• Setting the Location Qualifiers

• Specifying the Proximity Method

• Synchronizing GSLB Static Proximity Database

1.
2. Citrix ADC
3. NetScaler 12.0

Add a location file to create a static proximity database

September 12, 2018

Contributed by:
C

A static proximity database is a UNIX-based ASCII file. Entries added to this database from a location
file are called static entries. Only one location file can be loaded on a NetScaler appliance. Adding a
new location file overrides the existing file. The number of entries in the static proximity database is
limited by the configured memory in the NetScaler appliance.

The static proximity database can be created in the default format or in a format derived from com-
mercially configured third party databases (such as www.maxmind.com and www.ip2location.com).

The NetScaler appliance includes the following two IP geolocation database files. These are GeoLite2
files, published by MaxMind.

• Citrix_Netscaler_InBuilt_GeoIP_DB_IPv4
• Citrix_Netscaler_InBuilt_GeoIP_DB_IPv6

These database files are available in a format supported by the NetScaler appliance in the directory
/var/netscaler/inbuilt_db.

You can use these IP geolocation databases as the location file for the static proximity based GSLB
method, or in location based policies.

These databases vary in the details they provide. There is no strict enforcement of the database file
format, except that the default file has format tags. The database files are ASCII files that use a comma
as the field delimiter. There are differences in the structure of fields and the representation of IP ad-
dresses in the locations.

The format parameter describes the structure of the file to the NetScaler appliance. Specifying an
incorrect value for the format option can corrupt the internal data.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2228

NetScaler 12.0

Note

• After an upgrade, if the /var/netscaler/inbuilt_db/ directory contains the da tabase file (Cit-
rix_Netscaler_InBuilt_GeoIP_DB.csv) from the earlierNetScaler software versions, the file
is retained.
• The default location of the database file is /var/netscaler/locdb, and on a high availabil-
ity (HA) setup, an identical copy of the file must be present in the same location on both
NetScaler appliances.

The following abbreviations are used in this section:

CSHN. Short name of a country based on the country code standard of ISO-3166.

LCN. Long name of the country.

RC. Region code based on ISO-3166-2 (for US and Canada). The region code “FIPS-10-4” is used
for the other regions.

• Some databases provide short country names according to ISO-3166 and long country
names as well. The NetScaler uses short names when storing and matching qualifiers.

• To create a static proximity database, log on to the UNIX shell of the NetScaler appliance
and use an editor to create a file with the location details in one of the NetScaler-supported
formats.

To add a static location file by using the CLI

At the command prompt, type:

1 add locationFile <locationFile> [-format <format>]

2 - show locationFile

Example:

1 add locationFile /var/nsmap/locdb/nsgeo1.0 -format netscaler

2 Done
3
4 show locationFile
5 Location File: /var/nsmap/locdb/nsgeo1.0
6 Format: netscaler
7 Done
8 >

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2229

NetScaler 12.0

To add a static location file by using the GUI

1. Navigate to AppExpert > Location, click the Static Database tab.

2. Click Add to add a static location file.

You can view an imported location file database by using the View Database dialog box in the config-
uration utility. There is no CLI equivalent.

To view a static location file by using the GUI

1. Navigate to AppExpert > Location, click the Static Database tab.

2. Select a static location file, and from the Action list, click View Database.

To convert a location file into the NetScaler format

By default, when you add a location file, it is saved in the NetScaler format. You can convert a location
file of other formats into the NetScaler format.

Note: The nsmap option can be accessed only from the command line interface. The conversion is
possible only into the NetScaler format.

To convert the static database format, At the CLI prompt, type the following command:

1 nsmap -f <inputFileFormat> -o <outputFileName> <inputFileName>

Example:

1 nsmap -f ip-country-region-city -o nsfile.ns ip-country-region-city.

csv

1.
2. Citrix ADC
3. NetScaler 12.0

Add custom entries to a static proximity database

September 12, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2230

NetScaler 12.0

Custom entries take precedence over static entries in the proximity database. You can add a maximum
of 500 custom entries. For a custom entry, denote all omitted qualifiers with an asterisk (*) and, if
qualifiers have a period or space in the name, enclose the parameter in double quotation marks. The
first 31 characters are evaluated for each qualifier. You can also provide the longitude and latitude of
the geographical location of the IP address-range for selecting a service with the static proximity GSLB
method.

To add custom entries by using the command line interface

At the command prompt, type the following commands to add a custom entry to the static proximity
database and verify the configuration:

1 add location < IPfrom> < IPto> <preferredLocation> [-longitude <integer

>[-latitude <integer>]]
2 show location

Example:

1 >add location 192.168.100.1 192.168.100.100 *.us.ca.mycity

1 >show location

Parameters for adding custom entries

• IPfrom

First IP address in the range, in dotted decimal notation. This is a mandatory argument.

• IPto

Last IP address in the range, in dotted decimal notation. This is a mandatory argument.

• preferredLocation

String of qualifiers, in dotted notation, describing the geographical location of the IP

address range. Each qualifier is more specific than the one that precedes it, as in conti-
nent.country.region.city.isp.organization. For example,”NA.US.CA.San Jose.ATT.citrix”.
Note: A qualifier that includes a dot (.) or space ( ) must be enclosed in double quotation marks.
This is a mandatory argument. Maximum Length: 197

• longitude

Numerical value, in degrees, specifying the longitude of the geographical location of the IP
address-range.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2231

NetScaler 12.0

Note: Longitude and latitude parameters are used for selecting a service with the static proxim-
ity GSLB method. If they are not specified, selection is based on the qualifiers specified for the
location.
Maximum value: 180

• latitude

Numerical value, in degrees, specifying the latitude of the geographical location of the IP
address-range.
Note: Longitude and latitude parameters are used for selecting a service with the static
proximity GSLB method. If they are not specified, selection is based on the qualifiers specified
for the location.
Maximum value: 180

To add custom entries by using the configuration utility

Navigate to AppExpert > Location, click the Custom Entries tab, and add the custom entries.

1.
2. Citrix ADC
3. NetScaler 12.0

Set location qualifiers

September 12, 2018

Contributed by:
C

The database used to implement static proximity contains the location of the GSLB sites. Each location
contains an IP address range and up to six qualifiers for that range. The qualifiers are literal strings and
are compared in a prescribed order at run time. Every location must have at least one qualifier. The
meaning of the qualifiers (context) is defined by the qualifier labels, which are user defined. NetScaler
has two built-in contexts:

Geographic context, which has the following qualifier labels:

• Qualifier 1 – “Continent”
• Qualifier 2 – “Country”
• Qualifier 3 – “State”
• Qualifier 4 – “City”
• Qualifier 5 – “ISP”

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2232

NetScaler 12.0

• Qualifier 6 – “Organization”

Custom entries, which have the following qualifier labels:

• Qualifier 1 – “Qualifier 1”
• Qualifier 2 – “Qualifier 2”
• Qualifier 3 – “Qualifier 3”
• Qualifier 4 – “Qualifier 4”
• Qualifier 5 – “Qualifier 5”
• Qualifier 6 – “Qualifier 6”

If the geographic context is set with no Continent qualifier, Continent is derived from Country. Even
the built-in qualifier labels are based on the context, and the labels can be changed. These qualifier
labels specify the locations mapped with the IP addresses used to make static proximity decisions.

To perform a static proximity-based decision, the NetScaler appliance compares the location at-
tributes (qualifiers) derived from the IP address of the local DNS server resolver with the location
attributes of the participating sites. If only one site matches, the appliance returns the IP address of
that site. If there are multiple matches, the site selected is the result of a round robin on the matching
GSLB sites. If there is no match, the site selected is a result of a round robin on all configured sites. A
site that does not have any qualifiers is considered a match.

To set the location qualifiers by using the command line interface

At the command prompt, type:

1 set locationparameter -context <context> -q1label <string> [-q2label <

string>] [-q3label <string>] [-q4label <string>] [-q5label <string>]
[-q6label <string>]

Example:

1 set locationparameter -context custom -q1label asia

To set the location qualifiers by using the configuration utility

1. Navigate to AppExpert > Location.

2. From the Action list, click Location Parameters and set the location qualifiers.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2233

NetScaler 12.0

Specify proximity method

September 12, 2018

Contributed by:
C

When you have configured the static proximity database, you are ready to specify static proximity as
the GLSB method.

To specify static proximity by using the command line interface

At the command prompt, type the following commands to configure static proximity and verify the
configuration:

1 set gslb vserver <name> -lbMethod STATICPROXIMITY

2 show gslb vserver <name>

Example:

1 set gslb vserver Vserver-GSLB-1 -lbMethod STATICPROXIMITY

2 show gslb vserver

To specify static proximity by using the configuration utility

1. Navigate to Traffic Management > GSLB > Virtual Servers and double-click the virtual server.
2. Click the Method section and from the Choose Method drop-down list, select STATICPROXIM-
ITY.

1.
2. Citrix ADC
3. NetScaler 12.0

Synchronize GSLB static proximity database

September 12, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2234

NetScaler 12.0

Synchronizing a global server load balancing (GSLB) static proximity database requires that one of the
sites be identified as the master GSLB node. Any site in the topology can be designated as the master
node. The rest of the GSLB nodes are automatically designated as slave nodes.
Synchronizing GSLB static proximity databases synchronizes the files in the /var/netscaler/locdb direc-
tory across the slave nodes. During the synchronization process, the master node fetches the running
configuration from each of the slave nodes and compares it to the configuration on the master node.
The master GSLB node uses the rsync program to synchronize the static proximity database across
the slave nodes. To speed up the synchronization process, the rsync program makes only enough
changes to eliminate the differences between the two files. The synchronization process cannot be
rolled back.
The following example synchronizes Site2, which is a slave site, to master site Site1. The administrator
enters the sync gslb config command on Site1:

1 sync gslb config -nowarn

2 Sync Time: Feb 24 2014 14:56:16
3 Retrieving local site info: ok
4 Retrieving all participating gslb sites info:
5 0 bytes in 0 blocks
6 ok
7 site1[Master]:
8 Getting Config: ok
9 site2[Slave]:
10 Syncing gslb static proximity database: ok
11 Getting Config: ok
12 Comparing config: ok
13 Applying changes: ok
14 Done

1.
2. Citrix ADC
3. NetScaler 12.0

Configure site-to-site communication

May 9, 2019
Contributed by:
C
GSLB site-to-site communication is between the remote procedure call (RPC) nodes that are associ-
ated with the communicating sites. A master GSLB site establishes connections with slave sites to

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2235

NetScaler 12.0

synchronize GSLB configuration information and to exchange site metrics.

An RPC node is created automatically when a GSLB site is created, and is assigned an internally gen-
erated user name and password. The NetScaler appliance uses this user name and password to au-
thenticate itself to remote GSLB sites during connection establishment. No configuration steps are
necessary for an RPC node, but you can specify a password of your choice, enhance security by en-
crypting the information that GSLB sites exchange, and specify a source IP address for the RPC node.

The appliance needs a NetScaler owned IP address to use as the source IP address when communi-
cating with other GSLB sites. By default, the RPC nodes use a subnet IP (SNIP) address, but you might
want to specify an IP address of your choice.

The following topics describe the behavior and configuration of RPC nodes on the NetScaler appli-
ance:

Changing the password of an RPC node

You can secure the communication between sites in your GSLB setup by changing the password of
each RPC node. After you change the password for the RPC node of the local site, you must manually
propagate the change to the RPC node at each of the remote sites.

The password is stored in encrypted form. You can verify that the password has changed by using the
show rpcNode command to compare the encrypted form of the password before and after the change.

To change the password of an RPC node by using the command line interface

At the command line, type the following commands to change the password of an RPC node:

1 set ns rpcNode <IPAddress> {

2 -password }
3
4 show ns rpcNode

Example:

1 > set rpcNode 192.0.2.4 -password mypassword

2 Done
3 > show rpcNode
4 .
5 .
6 .
7 2) IPAddress: 192.0.2.4 Password: d336004164d4352ce39e
8 SrcIP: * Secure: OFF
9 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2236

NetScaler 12.0

10 >

To unset the password of an RPC node by using the command line interface

To unset the password of an RPC node by using the CLI, type the unset rpcNode command, the IP
address of the RPC node, and the password parameter, without a value.

To change the password of an RPC node by using the configuration utility

Navigate to System > Network > RPC, select the RPC node, and change the password.

Encrypt the exchange of site metrics

You can secure the information that is exchanged between GSLB sites by setting the secure option for
the RPC nodes in the GSLB setup. With the secure option set, the NetScaler appliance encrypts all
communication sent from the node to other RPC nodes.

To encrypt the exchange of site metrics by using the command line interface

At the command prompt, type the following commands to encrypt the exchange of site metrics and
verify the configuration:

1 set ns rpcNode <IPAddress> [-secure ( YES | NO )]

2 show rpcNode

Example:

1 > set rpcNode 192.0.2.4 -secure YES

2 Done
3 >
4 > show rpcNode
5 .
6 .
7 .
8 3) IPAddress: 192.0.2.4 Password: d336004164d4352ce39e SrcIP:
192.0.2.3 Secure: ON
9 Done
10 >

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2237

NetScaler 12.0

To unset the secure parameter by using the command line interface

To unset the secure parameter by using the CLI, type the unset rpcNode command, the IP address of
the RPC node, and the secure parameter, without a value.

To encrypt the exchange of site metrics by using the NetScaler configuration utility

1. Navigate to System > Network > RPC and double-click a RPC node.
2. Select the Secure option, and click OK.

Configure source IP address for an RPC node

By default, the NetScaler appliance uses a NetScaler owned subnet IP (SNIP) address as the source
IP address for an RPC node, but you can configure the appliance to use a specific SNIP address. If a
SNIP address is not available, the GSLB site cannot communicate with other sites. In such a scenario,
you must configure either the NSIP address or a virtual IP (VIP) address as the source IP address for
an RPC node. A VIP address can be used as the source IP address of an RPC node only if the RPC node
is a remote node. If you configure a VIP address as the source IP address and remove the VIP address,
the appliance uses a SNIP address.
Note

From NetScaler 11.0.64.x release onwards, you can configure the appliance to use GSLB Site IP
address as the source IP address for an RPC node.

To specify a source IP address for an RPC node by using the command line interface

At the command prompt, type the following commands to change the source IP address for an RPC
node and verify the configuration:

1 set ns rpcNode <IPAddress> [-srcIP <ip_addr|ipv6_addr|*>]

2 show ns rpcNode

Example:

1 set rpcNode 192.0.2.4 -srcIP 192.0.2.3

2 Done
3 show rpcNode

1 IPAddress: 192.0.2.4 Password: d336004164d4352ce39e SrcIP: 192.0.2.3

Secure: OFF
2 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2238

NetScaler 12.0

To unset the source IP address parameter by using the command line interface

To unset the source IP address parameter by using the CLI, type the unset rpcNodecommand, the IP
address of the RPC node, and the srcIP parameter, without a value.

To specify a source IP address for an RPC node by using the NetScaler configuration utility

1. Navigate to System > Network > RPC and double-click a RPC node.
2. In the Source IP Address field, enter the IP address that you want the RPC node to use as the
source IP address and click OK.
Important

The source IP address cannot be synchronized across the sites participating in GSLB because
the source IP address for a RPC node is specific to each NetScaler appliance. Therefore, after
you force a synchronization (using the sync gslb config –forceSync command or by selecting the
ForceSync option in the GUI), you have to manually change the source IP addresses on the other
NetScaler appliances.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure metrics exchange protocol

September 12, 2018

Contributed by:
C

The data centers in a GSLB setup exchange metrics with each other through the metrics exchange
protocol (MEP), which is a proprietary protocol for NetScaler appliance. The exchange of the metric
information begins when you create a GSLB site. These metrics comprise load, network, and persis-
tence information.

MEP is required for health checking of data centers to ensure their availability. A connection for ex-
changing network metric (round-trip time) can be initiated by either of the data centers involved in
the exchange, but a connection for exchanging site metrics is always initiated by the data center with
the lower IP address. By default, the data center uses a subnet IP address (SNIP) to establish a connec-
tion to the IP address of a different data center. However, you can configure a specific SNIP, virtual IP
(VIP) address, or the NSIP address, as the source IP address for metrics exchange. The communication

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2239

NetScaler 12.0

process between GSLB sites uses TCP port 3011 or 3009, so this port must be open on firewalls that
are between the NetScaler appliances.
Note: You cannot configure a GSLB site IP address as the source IP address for site metrics exchange.
If the source and target sites (the site that initiates a MEP connection and the site that receives the
connection request, respectively) have both private and public IP addresses configured, the sites ex-
change MEP information by using the public IP addresses.
You can also bind monitors to check the health of remote services as described in “Monitoring GSLB
Services.” When monitors are bound, metric exchange does not control the state of the remote ser-
vice. If a monitor is bound to a remote service and metric exchange is enabled, the monitor controls
the health status. Binding the monitors to the remote service enables the NetScaler appilance to inter-
act with a non NetScaler load balancing device. The NetScaler appliance can monitor non NetScaler
devices but cannot perform load balancing on them unless monitors are bound to all GSLB services
and only static load balancing methods (such as the round robin, static proximity, or hash-based meth-
ods) are used.
With NetScaler release 11.1.51.x or later, to avoid unnecessary disruption of services, you can set a time
delay for marking GSLB services as DOWN when a MEP connection goes DOWN.

Enable site metrics exchange

Site metrics exchanged between the GSLB sites include the status of each load balancing, or con-
tent switching virtual server, the current number of connections, the current packet rate, and current
bandwidth usage information.
The NetScaler appliance needs this information to perform load balancing between the sites. The site
metric exchange interval is 1 second. A remote GSLB service must be bound to a local GSLB virtual
server to enable the exchange of site metrics with the remote service.

To enable or disable site metrics exchange by using the command line interface

At a command prompt, type the following commands to enable or disable site metric exchange and
verify the configuration:

1 set gslb site <siteName> -metricExchange (ENABLED|DISABLED)

2 show gslb site** <siteName>

Example:

1 set gslb site Site-GSLB-East-Coast -metricExchange ENABLED

2 set gslb site Site-GSLB-East-Coast -metricExchange DISABLED
3 show gslb site Site-GSLB-East-Coast

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2240

NetScaler 12.0

To enable or disable site metric exchange by using the GUI

1. Navigate to Traffic Management > GSLB > Sites, and select the site.
2. In the Configure GSLB Site dialog box, select the Metric Exchange option.

Enable network metric exchange

If your GSLB sites use the round-trip time (RTT) load balancing method, you can enable or disable the
exchange of RTT information about the client’s local DNS service. This information is exchanged every
5 seconds.

For details about changing the GSLB method to a method based on RTT, see “GSLB Methods.”

To enable or disable network metric information exchange by using the command line interface

At the command prompt, type the following commands to enable or disable network metric informa-
tion exchange and verify the configuration:

1 set gslb site <siteName> -nwmetricExchange (ENABLED|DISABLED)

2 show gslb site <<siteName>

Example:

1 set gslb site Site-GSLB-East-Coast -nwmetricExchange ENABLED

2 set gslb site Site-GSLB-East-Coast -nwmetricExchange DISABLED
3 show gslb site Site-GSLB-East-Coast

To enable or disable network metric information exchange by using the GUI

1. Navigate to Traffic Management > GSLB > Sites.

2. In the Configure GSLB Site dialog box, select the Network Metric Exchange option.

Configuring a time delay for the GSLB services to be marked as DOWN when a MEP
connection goes DOWN

If the status of a MEP connection to a remote site changes to DOWN, the status of every GSLB service
on that remote site is marked as DOWN, although the site might not actually be DOWN.

You can now set a delay to allow some time for reestablishment of the MEP connection before the site
is marked as DOWN. If the MEP connection is back UP before the delay expires, the services are not
affected.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2241

NetScaler 12.0

For example, if you set the delay 10, the GSLB services are marked as DOWN until the MEP connection
has been DOWN for 10 seconds. If the MEP connection is back UP within 10 seconds, the GSLB services
remain in the UP state.

Note: This delay is applicable only to services not bound to a monitor. The delay does not affect the
trigger monitors.

To set a time delay by using the command line interface

At the command prompt, type the following command:

1 set gslb parameter** - GSLBSvcStateDelayTime <sec>

Example:

set gslb parameter - GSLBSvcStateDelayTime 10

To set a time delay by using the GUI

1. Navigate to Configuration > Traffic Management > GSLB > Change GSLB Settings.
2. In the GSLB Service State Delay Time (secs) box, type the time delay in seconds.

Enable persistence information exchange

You can configure NetScaler appliance to provide persistent connections, so that a client transmission
to any virtual server in a group can be directed to a server that has received previous transmissions
from the same client.

You can enable or disable the exchange of persistence information at each site. This information is
exchanged once every 5 seconds between NetScaler appliances participating in GSLB.

For details about configuring persistence, see Configuring Persistent Connections.

To enable or disable persistence information exchange by using the command line interface

At the command prompt, type the following commands to enable or disable persistence-information
exchange and verify the configuration:

1 set gslb site <siteName> -sessionExchange (ENABLED|DISABLED)

2 show gslb site** <siteName>

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2242

NetScaler 12.0

1 set gslb site Site-GSLB-East-Coast -sessionExchange ENABLED

2 set gslb site Site-GSLB-East-Coast -sessionExchange DISABLED
3 show gslb site Site-GSLB-East-Coast

To enable or disable persistence information exchange by using the GUI

1. Navigate to Traffic Management > GSLB > Sites, and double-click the site.
2. In the Configure GSLB Site dialog box, select or clear the Persistence Session Entry Exchange
check box.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure GSLB by using a wizard

September 12, 2018

Contributed by:
C

You can now use a wizard to configure the GSLB deployment types: active-active, active-passive, and
parent-child.

This wizard is available in the GUI. To access the wizard, navigate to Configuration > Traffic Manage-
ment > GSLB and click Get Started.

You can also access this wizard from the GSLB dashboard. Navigate to Configuration > Traffic Man-
agement > GSLB > Dashboard and click Configure GSLB.

Note: You can also configure the GSLB entities individually.

• Active-Active Site Configuration

• Active-Passive Site Configuraiton
• Parent-Child Topology Configuration

Important

This feature is supported in High Availability deployment and not in Admin Partition and Cluster
deployments.

1.
2. Citrix ADC

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2243

NetScaler 12.0

3. NetScaler 12.0

Configure active-active site

January 6, 2019

Contributed by:
C

The following figure shows the workflow involved in a GSLB active-active site configuration.

Before you begin configuring an active-active site, make sure you have configured a standard load
balancing setup for each server farm or data center.

Also, for synchronizing the GSLB configuration across the GSLB sites in the deployment, make sure
that:

• Local GLSB Sites are configured on all the appliances in the GSLB configuration.
• You have enabled management access on all the GSLB Sites in the configuration.
• You have configured the firewall to accept the auto synchronization and MEP connections.
• The master and slave NetScaler appliances are running the same NetScaler software versions.
• All the NetScaler appliances participating as sites should have the same NetScaler software ver-
sion (the sites are not in a master-slave relationship).
• The RPC node password is same across all the GSLB sites in the GSLB configuration.

To configure an active-active site by using the wizard

On the Configuration tab, do the following:

1. Navigate to Traffic Management > GSLB, and then click Get Started.
2. If you have not configured an ADNS service or a DNS virtual server for the site, you can do it now.
a) Click View and then click Add.
b) Enter the service name, IP address and select the protocol (ADNS/ADNS_TCP) through
which the data is exchanged with the service.
3. Select Active-Active Site.
4. Enter the fully qualified domain name and specify the time period for which the record must be
cached by DNS proxies.
5. Configure the GSLB sites. Each site must be configured with a local GSLB site, and each site’s
configuration must include all the other sites as remote GSLB sites. There can be only one local
site and all other sites are remote sites.
a) Enter the site details, such as the site name and site IP address.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2244

NetScaler 12.0

b) Select either REMOTE or LOCAL site type.

c) Optionally, change the RPC password and, if necessary, secure it.
d) If a monitor is to be bound to the GSLB service, select the condition under which the mon-
itor is to monitor the service. This will be effective only after a monitor is bound to the
services. The possible conditions are:
• ALWAYS. Monitor the GSLB service at all times.
• MEP Fails. Monitor the GSLB service only when the exchange of metrics through MEP
fails.
• MMEP Fails and Service ID Down. Exchange of metrics through MEP is enabled but
the status of the service, updated through metrics exchange, is DOWN.
6. Configure the GSLB services. To create an active-active site you must add at least two GSLB
services.
a) Enter the service details, such as service name, service type, and port number.
b) Associate the service with a site (local or remote) by selecting the GSLB site where the GSLB
service belongs.
c) Select the monitor that must be bound to the service when MEP fails, if required. The
service can be an existing server, or you can create a new server or a virtual server.
d) To associate an existing server, select the server name. The service IP address is automat-
ically populated.
• If the public IP address is different from the server IP, which can happen in a NAT en-
vironment, enter the public IP address and the port number of the public port.
• To associate a new server, create a server by entering the server IP details and its pub-
lic IP address and the public port number.
• To associate a virtual server, select an already existing virtual server, or click + and add
a new virtual server. This vserver is the load balancing vserver with which this GSLB
service will be associated.
7. Configure the GSLB virtual servers.
a) Enter the name of the GSLB virtual server name and select the DNS record type.
b) Click > in the Select Service box and choose the GSLB services to be bound to the GSLB
virtual server.
c) Click > in the Domain Binding box to select the domain to be bound to this GSLB virtual
server.
d) Choose the GSLB method for selecting the best-performing GSLB service. The default val-
ues for GSLB method, backup method, and dynamic weight are auto-populated, by de-
fault. You can change them if required.
• If you choose the Algorithm based method, select the primary and backup methods
and also specify the dynamic weight option.
• If you choose the Static Proximity method, select the backup method and the dy-
namic weight method. Also, provide the location of the database file by clicking the

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2245

NetScaler 12.0

> icon or add a new location by clicking + in the Select a location database box.
• If you choose the Dynamic Proximity (RTT) method, select the backup method and
specify the dynamic weight option and the round-trip time value based on which the
best-performing service is to be selected.
8. Click Done if the configuration is complete. The GSLB dashboard appears.
9. If you have modified the GSLB site configuration, click Auto Synchronize GSLB in the dash-
board to synchronize the configuration to other sites in the GSLB setup.
• Before synchronization, make sure that the local site’s configuration includes information
about the remote sites. Also, for the synchronization to be successful, the local site must
be configured on the other NetScaler appliances.
• If real-time synchronization is enabled, you do not have to click Auto Synchronize GSLB.
The synchronization happens automatically. To enable real time synchronization, do the
following:
a) Navigate to Traffic Management > GSLB > Dashboard and click Change GSLB Set-
tings.
b) Select the Automatic Config Sync check box.
10. Click Test GSLB Setup to make sure that the ADNS services or the DNS servers are responding
with the correct IP address for the domain name that is configured in the GSLB setup.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure active-passive site

January 6, 2019

Contributed by:
C

The following figure shows the workflow involved in the active-passive site configuration.

Before you begin configuring an active-passive site, make sure you have configured a standard load
balancing setup for each server farm or data center.

Also, for synchronizing the GSLB configuration across the GSLB sites in the deployment, make sure
that:

• Local GLSB Sites are configured on all the appliances in the GSLB configuration.
• You have enabled management access on all the GSLB Sites in the configuration.
• You have configured the firewall to accept the auto synchronization and MEP connections.
• The master and slave NetScaler appliances are running the same NetScaler software versions.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2246

NetScaler 12.0

• All the NetScaler appliances participating as sites should have the same NetScaler software ver-
sion (the sites are not in a master-slave relationship).
• The RPC node password is same across all the GSLB sites in the GSLB configuration.

To configure an active-passive site by using the wizard

On the Configuration tab, do the following:

1. Navigate to Traffic Management > GSLB, and then click Get Started.
2. If you have not configured an ADNS service or a DNS virtual server for the site, you can do it now.
a) Click View and then click Add.
b) Enter the service name, IP address and select the protocol (ADNS/ADNS_TCP) through
which the data is exchanged with the service.
3. Select Active-Passive Site.
4. Enter the fully qualified domain name and specify the time period for which the record must be
cached by DNS proxies.
5. Configure the GSLB sites. Each site must be configured with a local GSLB site, and each site’s
configuration must include all the other sites as remote GSLB sites. There can be only one local
site and all other sites are remote sites.
a) Enter the site details, such as the site name and site IP address.
b) Select either REMOTE or LOCAL site type.
c) Optionally, change the RPC password and, if necessary, secure it.
d) If a monitor is to be bound to the GSLB service, select the condition under which the mon-
itor is to monitor the service. This will be effective only after a monitor is bound to the
services. The possible conditions are:
• ALWAYS. Monitor the GSLB service at all times.
• MEP Fails. Monitor the GSLB service only when the exchange of metrics through MEP
fails.
• MEP Fails and Service ID Down. Exchange of metrics through MEP is enabled but the
status of the service, updated through metrics exchange, is DOWN.
6. Configure the GSLB services.
a) Enter the service details, such as service name, service type, and port number.
b) Associate the service with a site (local or remote) by selecting the GSLB site where the GSLB
service belongs.
c) Select the monitor that must be bound to the service when MEP fails, if required. The
service can be an existing server, or you can create a new server or a virtual server.
d) To associate an existing server, select the server name. The service IP address is automat-
ically populated.
• If the public IP address is different from the server IP, which can happen in a NAT en-
vironment, enter the public IP address and the port number of the public port.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2247

NetScaler 12.0

• To associate a new server, create a server by entering the server IP details and its pub-
lic IP address and the public port number.
• To associate a virtual server, select an already existing virtual server, or click + and add
a new virtual server. This vserver is the load balancing vserver with which this GSLB
service will be associated.
7. Configure the GSLB backup virtual servers. The GSLB backup virtual servers become opera-
tional only when the primary GSLB virtual servers is inaccessible or it is marked DOWN for any
reason.
a) Enter the name of the GSLB virtual server name and select the DNS record type.
b) Click > in Service Binding, and choose the GSLB services that must be bound to the GSLB
virtual server.
c) Choose the GSLB method for selecting the best-performing GSLB service. The default val-
ues for GSLB method, backup method, and dynamic weight are auto-populated, by de-
fault. You can change them if required.
• If you choose the Algorithm based method, select the primary and backup methods.
• If you choose the Static Proximity method, select the backup method and provide
the location of the database file.
• If you choose the Dynamic Proximity (RTT) method, select the backup method and
specify the service weight and the RTT value based on which the best-performing ser-
vice is to be selected.
8. Configure the GSLB virtual servers.
a) Enter the name of the GSLB virtual server name and select the DNS record type.
b) Click > in the Select Service box and choose the GSLB services to be bound to the GSLB
virtual server.
c) Click > in the Domain Binding box to select the domain to be bound to this GSLB virtual
server.
d) Choose the GSLB method for selecting the best-performing GSLB service. The default val-
ues for GSLB method, backup method, and dynamic weight are auto-populated, by de-
fault. You can change them if required.
• If you choose the Algorithm based method, select the primary and backup methods
and also specify the dynamic weight option.
• If you choose the Static Proximity method, select the backup method and the
dynamic weight method. Also, provide the location of the database file by clicking
the > icon or add a new location by clicking + in the Select a location database box.
• If you choose the Dynamic Proximity (RTT) method, select the backup method and
specify the dynamic weight option and the round-trip time value based on which the
best-performing service is to be selected.
9. Click Done if the configuration is complete. The GSLB dashboard appears.
10. If you have modified the GSLB site configuration, click Auto Synchronize GSLB in the dash-

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2248

NetScaler 12.0

board to synchronize the configuration to other sites in the GSLB setup.

• Before synchronization, make sure that the local site’s configuration includes information
about the remote sites. Also, for the synchronization to be successful, the local site must
be configured on the other NetScaler appliances.
• If real-time synchronization is enabled, you do not have to click Auto Synchronize GSLB.
The synchronization happens automatically. To enable real time synchronization, do the
following:
a) Navigate to Traffic Management > GSLB > Dashboard and click Change GSLB Set-
tings.
b) Select the Automatic Config Sync check box.
11. Click Test GSLB Setup to make sure that the ADNS services or the DNS servers are responding
with the correct IP address for the domain name that is configured in the GSLB setup.

Note

For details about configuring GSLB entities of an active-passive GSLB setup for disaster recovery,
see Configuring GSLB for Disaster Recovery.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure parent-child topology

January 6, 2019

Contributed by:
C

In a parent-child topology, at the top level are parent sites, which have peer relationships with other
parents. Each parent can have multiple child sites, and each parent site exchanges health information
with its child sites and with other parent sites. However, a child site communicates only with its parent
site.

The following figure shows the workflow involved in a GSLB parent-child topology configuration.

Before you begin configuring the parent-child topology deployment, make sure you have configured
a standard load balancing setup for each server farm or data center.

Also, for synchronizing the GSLB configuration across the GSLB sites in the deployment, make sure
that:

• Local GLSB Sites are configured on all the appliances in the GSLB configuration.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2249

NetScaler 12.0

• You have enabled management access on all the GSLB Sites in the configuration.
• You have configured the firewall to accept the auto synchronization and MEP connections.
• All the NetScaler appliances participating as sites should have the sameNetScaler software ver-
sion (the sites are not in a master-slave relationship).
• The RPC node password is same across all the GSLB sites in the GSLB configuration.

To configure a parent-child deployment by using the wizard

On the Configuration tab, do the following:

1. Navigate to Traffic Management > GSLB, and then click Get Started.
2. If you have not configured an ADNS server or a DNS virtual server for the site, you can do it now.
a) Click View and then click Add.
b) Enter the service name, IP address and select the protocol (ADNS/ADNS_TCP) through
which the data is exchanged with the service.
3. Select Parent-Child Topology.
4. In the Select the site type field, choose;
• Parent – When configuring the parent site, you must configure its associated child sites
and also configure the other parent sites in the GSLB setup.
• Child – When configuring the child site, you must configure only the child site and its par-
ent site.

To configure a parent site

1. Enter the fully qualified domain name and specify the time period for which the record must be
cached by DNS proxies.
2. Configure the GSLB sites. Each site must be configured with a local GSLB site, and each site’s
configuration must include all the other sites as remote GSLB sites. There can be only one local
site. All other sites are remote sites. If the specified site IP address is owned by the appliance
(for example, a MIP address or SNIP address), the site is a local site. Otherwise, it is a remote
site.
3. Enter the site details, such as the site name and site IP address.
a) Select the site type.
b) Optionally, change the RPC password and, if necessary, secure it.
c) If a monitor is to be bound to the GSLB service, select the condition under which the mon-
itor is to monitor the service. This will be effective only after a monitor is bound to the
services. The possible conditions are:
• Always. Monitor the GSLB service at all times.
• MEP Fails. Monitor the GSLB service only when the exchange of metrics through MEP
fails.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2250

NetScaler 12.0

• MEP Fails and Service is DOWN. Exchange of metrics through MEP is enabled but the
status of the service, updated through metrics exchange, is DOWN.
4. Configure the GSLB services.
a) Enter the service details such as service name, service type, and port number.
b) Associate the service with a site (local or remote) by selecting the GSLB site to which the
GSLB service belongs.
c) Select the monitor that must be bound to the service when MEP fails, if required. The
service can be an existing server, or you can create a new server or a virtual server.
• To associate an existing server, select the server name. The service IP address is auto-
populated.
• To associate a new server, create a server by entering the server IP details and its pub-
lic IP address and the public port number.
• To associate a virtual server, select an already existing virtual server or click + and
add a new virtual server. This vserver is the load balancing vserver to which this GSLB
service will be associated. If the public IP address is different from the server IP, which
can happen in a NAT environment, enter the public IP address and the public port
number.
5. Configure the GSLB virtual servers.
a) Enter the name of the GSLB virtual server name and select the DNS record type.
b) Click > in the Select Service box and choose the GSLB services to be bound to the GSLB
virtual server.
c) Click > in the Domain Binding box to view the domain name that is bound to the GSLB
virtual server.
d) Choose the GSLB method for selecting the best-performing GSLB service. The default val-
ues for GSLB method, backup method, and dynamic weight are automatically populated
by default. You can change them if required.
• If you choose the Algorithm based method, select the primary and backup methods
and also specify the dynamic weight option.
• If you choose the Static Proximity method, select the backup method and the
dynamic weight method. Also, provide the location of the database file by clicking
the > icon or add a new location by clicking + in the Select a location database box.
• If you choose the Dynamic Proximity (RTT) method, select the backup method and
specify the service weight and the RTT value based on which the best-performing ser-
vice is to be selected.
6. Click Done if the configuration is complete. The GSLB dashboard appears.
7. If you have modified the GSLB parent-site configuration, click Auto Synchronize GSLB to syn-
chronize the configuration to the other parent sites in the GSLB setup. In a parent-child topol-
ogy, synchronization for the child sites is skipped.
• Before synchronization, make sure that the local site’s configuration includes information

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2251

NetScaler 12.0

about the remote sites.

• If real-time synchronization is enabled, you do not have to click Auto Synchronize GSLB.
The synchronization happens automatically. To enable real time synchronization, do the
following:
a) Navigate to Traffic Management > GSLB > Dashboard and click Change GSLB Set-
tings.
b) Select the Automatic Config Sync check box.
8. Click Test GSLB Setup to make sure that the ADNS services or the DNS servers are responding
with the correct IP address for the domain name that is configured in the GSLB setup.

To configure a child site

1. Configure the GSLB sites.

a) Enter the site details, such as the site name and site IP address.
b) Select the site type.
c) Optionally, change the RPC password and, if necessary, secure it. 4. If a monitor is bound
to the GSLB service, select the condition under which the monitor is to monitor the service.
The possible conditions are:
• Always. Monitor the GSLB service at all times.
• MEP Fails. Monitor the GSLB service only when the exchange of metrics through MEP
fails.
• MEP Fails and Service is DOWN. Exchange of metrics through MEP is enabled but the
status of the service, updated through metrics exchange, is DOWN.
2. Click Done if the configuration is complete. The GSLB dashboard appears.
3. Click Test GSLB Setup to make sure that the ADNS services or the DNS servers are responding
with the correct IP address for the domain name that is configured in the GSLB setup.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure GSLB entities individually

January 6, 2019

Contributed by:
C

Global server load balancing is used to manage traffic flow to a web site hosted on two separate
server farms that ideally are in different geographic locations. For example, consider a Web site,

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2252

NetScaler 12.0

www.mycompany.com, which is hosted on two geographically separated server farms or data cen-
ters. Both server farms use NetScaler appliances. The NetScaler appliances in these server farms are
set up in one-arm mode and function as authoritative DNS servers for the www.mycompany.com do-
main. The following figure illustrates this configuration.

Figure 1. Basic GSLB Topology

To configure such a GSLB setup, you must first configure a standard load balancing setup for each
server farm or data center. This enables you to balance load across the different servers in each
server farm. Then, configure both NetScaler appliances as authoritative DNS (ADNS) servers. Next,
create a GSLB site for each server farm, configure GSLB virtual servers for each site, create GLSB ser-
vices, and bind the GSLB services to the GSLB virtual servers. Finally, bind the domain to the GSLB
virtual servers. The GSLB configurations on the two appliances at the two different sites are identical,
although the load-balancing configurations for each site is specific to that site.

Note: To configure a GSLB site in aNetScaler cluster setup, see

Setting Up GSLB in a Cluster.

Configuring a Standard Load Balancing Setup

A load balancing virtual server balances the load across different physical servers in the data center.
These servers are represented as services on the NetScaler appliance, and the services are bound to
the load balancing virtual server.

For details on configuring a basic load balancing setup, see Load Balancing.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure an authoritative DNS service

September 12, 2018

Contributed by:
C

When you configure the NetScaler appliance as an authoritative DNS server, it accepts DNS requests
from the client and responds with the IP address of the data center to which the client should send
requests.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2253

NetScaler 12.0

Note: For the NetScaler appliance to be authoritative, you must also create SOA and NS records. For
more information about SOA and NS records, see
Domain Name System.

To create an ADNS service by using the command line interface

At the command prompt, type the following commands to create an ADNS service and verify the con-
figuration:

1 add service <name> <IP>@ ADNS <port>

2
3 show service <name>

Example:

1 add service Service-ADNS-1 10.14.39.21 ADNS 53

2
3 show service Service-ADNS-1

To modify an ADNS service by using the command line interface

At the command prompt, type the following command:

1 set service <name> <IPAddress> ADNS <port>

Example:

1 set service Service-ADNS-1 10.14.39.21 ADNS 53

To remove an ADNS service by using the command line interface

At the command prompt, type the following command:

1 rm service <name>

Example:

1 rm service Service-ADNS-1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2254

NetScaler 12.0

To configure an ADNS service by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Services.

2. Add a new ADNS service, or select an existing service and edit its settings.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure a basic GSLB site

September 12, 2018

Contributed by:
C

A GSLB site is a representation of a data center in your network and is a logical grouping of GSLB virtual
servers, services, and other network entities. Typically, in a GSLB set up, there are many GSLB sites
that are equipped to serve the same content to a client. These are usually geographically separated
to ensure that the domain is active even if one site goes down completely. All of the sites in the GSLB
configuration must be configured on every NetScaler appliance hosting a GSLB site. In other words,
at each site, you configure the local GSLB site and each remote GSLB site.

Once GSLB sites are created for a domain, the NetScaler appliance sends client requests to the appro-
priate GSLB site as determined by the GSLB algorithms configured.

To create a GSLB site by using the command line interface

At the command prompt, type the following commands to create a GSLB site and verify the configura-
tion:

1 add gslb site <siteName> <siteIPAddress>

2 show gslb site <siteName>

Example:

1 add gslb site Site-GSLB-East-Coast 10.14.39.21

2 show glsb site Site-GSLB-East-Coast

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2255

NetScaler 12.0

To modify or remove a GSLB Site by using the command line interface

• To modify a GSLB site, use the set gslb site command, which is just like using the add gslb site
command, except that you enter the name of an existing GSLB Site.
• To unset a site parameter, use the unset gslb site command, followed by the siteName value
and the name of the parameter to be reset to its default value.
• To remove a GSLB site, use the rm gslb site command, which accepts only the <name> argument.

To configure a basic GSLB site by using the configuration utility

1. Navigate to Traffic Management > GSLB > Sites.

2. Add a new GSLB site, or select an existing GSLB site and edit its settings.

To view the statistics of a GSLB site by using the command line interface

At the command prompt, type:

1 stat gslb site <siteName>

Example:

1 stat gslb site Site-GSLB-East-Coast

To view the statistics of a GSLB site by using the configuration utility

1. Navigate to Traffic Management > GSLB > Sites.

2. Select the GSLB site and click Statistics.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure a GSLB service

November 9, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2256

NetScaler 12.0

A GSLB service is a representation of a load balancing or content switching virtual server. A local GSLB
service represents a local load balancing or content switching virtual server. A remote GSLB service
represents a load balancing or content switching virtual server configured at one of the other sites in
the GSLB setup. At each site in the GSLB setup, you can create one local GSLB service and any number
of remote GSLB services.
Important

If the load balancing virtual server is either in a GSLB node itself or is in a child node (in parent-
child deployment) and no monitors are bound to the GSLB service, then make sure the following:

The GLSB service IP address, port number, and protocol match the virtual server that the service
is representing. Else, the service state is marked as DOWN.

To create a GSLB service by using the command line interface

At the command prompt, type the following commands to create a GSLB service and verify the config-
uration:

1 add gslb service <serviceName> <serverName | IP> <serviceType> <port>-

siteName <string>
2 show gslb service <serviceName>

Example:

1 add gslb service Service-GSLB-1 10.14.39.14 HTTP 80 ‒ siteName Site-

GSLB-East-Coast
2 show gslb service Service-GSLB-1

To modify or remove a GSLB service by using the command line interface

• To modify a GSLB service, use the set gslb service <serviceName> command. For this com-
mand, specify the name of the GSLB service whose configuration you want to modify. You can
change the existing values of the parameters either specified by you or set by default. You can
change the value of more than one parameter in the same command. Refer to the add gslb
service command for details about the parameters. Example

1 > set gslb service SKP_GSLB_NOTCNAME_SVC2 -maxBandWidth 25 -

maxClient 8
2 Done
3 > sh gslb service SKP_GSLB_NOTCNAME_SVC2
4 SKP_GSLB_NOTCNAME_SVC2 (21.211.21.21: 80)- HTTP
5 ...

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2257

NetScaler 12.0

6 Max Conn: 8 Max Bandwidth: 25 kbits

• To reset a parameter to its default value, you can use the unset gslb service <serviceName>
command and the parameters to be unset. Example

1 > unset gslb service SKP_GSLB_NOTCNAME_SVC2 maxBandWidth

2 Done
3 > sh gslb service SKP_GSLB_NOTCNAME_SVC2
4 SKP_GSLB_NOTCNAME_SVC2 (21.211.21.21: 80)- HTTP
5 ...
6 Max Conn: 8 Max Bandwidth: 0 kbits

• To remove a GSLB service, use the rm gslb service <serviceName> command.

To create a GSLB service by using the configuration utility

1. Navigate to Traffic Management > GSLB > Services.

2. Add a new GSLB service, or select an existing service and edit its settings.

To view the statistics of a GSLB service by using the command line interface

At the command prompt, type:

1 stat gslb service <serviceName>

Example:

1 stat gslb service Service-GSLB-1

To view the statistics of a GSLB service by using the configuration utility

1. Navigate to Traffic Management > GSLB > Services.

2. Select the GSLB Service and click Statistics.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2258

NetScaler 12.0

Configure a GSLB service group

November 9, 2018

Contributed by:
C

Service group enables you to manage a group of services as easily as a single service. For example, if
you enable or disable an option, such as compression, health monitoring, or graceful shutdown, for a
service group, the option gets enabled or disabled for all the members of the service group.

After creating a service group, you can bind it to a virtual server, and you can add services to the group.
You can also bind monitors to the service groups.

Important

If the load balancing virtual server is either in a GSLB node itself or is in a child node (in parent-
child deployment) and no monitors are bound to the GSLB service, then make sure the following:

The GLSB service group IP address, port number, and protocol match the virtual server that the
service is representing. Else, the service state is marked as DOWN.

The NetScaler supports the following types of GSLB service groups.

• IP address based service groups

• Domain name based service groups
• Domain name based autoscale service groups

GSLB domain name based autoscale service groups

The NetScaler hybrid and multi-cloud global server load balancing (GSLB) solution enables customers
to distribute application traffic across multiple data centers in hybrid clouds, multiple clouds, and
on premises. The NetScaler GSLB solution supports various load balancing solutions, such as the
NetScaler load balancer, Elastic Load Balancing (ELB) for Amazon Web Services (AWS), and other third-
party load balancers. Also, the GSLB solution performs global load balancing even if the GSLB and
load balancing layers are independently managed.

In cloud deployments, users are given a domain name as a reference when accessing the load bal-
ancing solution for management purposes. It is recommended that external entities do not use the
IP addresses that these domain names resolve to. Also, the load balancing layers scale up or down
based on the load, and the IP addresses are not guaranteed to be static. Therefore, it is recommended
to use the domain name to refer to the load balancing endpoints instead of IP addresses. This requires
the GSLB services to be referred using the domain name instead of IP addresses and it must consume

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2259

NetScaler 12.0

all the IP addresses returned for the load balancing layer domain name and have a representation for
the same in GSLB.

To use domain names instead of IP addresses when referring to the load balancing endpoints, you can
use the domain name based service groups for GSLB.

Monitor GSLB domain name based service groups

The NetScaler appliance has two built-in monitors that monitor TCP-based applications; tcp-
default and ping-default. The tcp-default monitor is bound to all TCP services and the ping-default
monitor is bound to all non-TCP services. The built-in monitors are bound by default to the GSLB
service groups. However, it is recommended to bind an application specific monitor to the GSLB
service groups.

Recommendation for setting the trigger monitors option to MEPDOWN

The Trigger Monitors option can be used to indicate if the GSLB site must use the monitors always, or
use monitors when metrics exchange protocol (MEP) is DOWN.

The Trigger Monitors option is set to ALWAYS by default.

When the Trigger Monitors option is set to ALWAYS, each GSLB node triggers the monitors indepen-
dently. If each GSLB node triggers the monitors independently, then each GSLB node might operate
on different set of GSLB services. This might result in discrepancies in the DNS responses for the DNS
requests landing on these GSLB nodes. Also, if each GSLB node is monitoring independently, then the
number of monitor probes reaching the load balancer entity increases. The persistence entries also
become incompatible across the GSLB nodes.

Therefore, it is recommended that the Trigger Monitors option on GSLB site entity is set to MEPDOWN.
When the Trigger Monitors option is set to MEPDOWN, the load balancing domain resolution and mon-
itoring ownership lies with the local GSLB node. When Trigger Monitors option is set to MEPDOWN,
the load balancing domain resolution and subsequent monitoring is done by the local GSLB node of a
GSLB service group. The results are then propagated to all other nodes participating in GSLB by using
the metrics exchange protocol (MEP).

Also, whenever the set of IP addresses associated with a load balancing domain are updated, it is
notified through MEP.

Limitations of GSLB service groups

• For a load balancing domain, the IP address that is returned in the DNS response is generally
the public IP address. The private IP address cannot be applied dynamically when the load
balancing domain is resolved. Therefore, public IP port and private IP port for the GSLB domain

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2260

NetScaler 12.0

name based autoscale service groups IP port bindings are the same. These parameters cannot
be set explicitly for the domain name based autoscale service groups.
• Site persistence, DNS views, and clustering are not supported for GSLB service groups.

Configure and manage GSLB service groups by using the CLI

Operation CLI Command

To add a GSLB service group add gslb serviceGroup <

serviceGroupName>@ <serviceType> [-
autoScale ( DISABLED | DNS )] -
siteName <string>
Example: add gslb serviceGroup
Service-Group-1 http -siteName Site1
-autoScale DNS
To bind a GSLB service group to a virtual server bind gslb serviceGroup <
serviceGroupName> ((<IP>@ <port>)|
<serverName>@ | ((-monitorName <
string>@
Example: bind gslb serviceGroup
Service-Group-1 203.0.113.2; bind gslb
serviceGroup Service-Group-1 S1 80; bind gslb
serviceGroup Service-Group-1 -monitorName
Mon1
To unbind a GSLB service group to a virtual unbind gslb serviceGroup <
server serviceGroupName> ((<IP>@ <port>)|
<serverName>@ | -monitorName <
string>@)
Example:unbind gslb serviceGroup
Service-Group-1 -monitorName Mon1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2261

NetScaler 12.0

Operation CLI Command

To set parameters for a GSLB service group set gslb serviceGroup <
serviceGroupName>@ [(<serverName>@
<port> [-weight <positive_integer>]
[-hashId <positive_integer>] [-
publicIP <ip_addr|ipv6_addr|*>] [-
publicPort <port>])| -maxClient <
positive_integer> | -cip ( ENABLED
| DISABLED )| <cipHeader> | -
cltTimeout <secs> | -svrTimeout <
secs> | -maxBandwidth <
positive_integer> | -monThreshold <
positive_integer> | -downStateFlush
( ENABLED | DISABLED )] [-
monitorName <string> -weight <
positive_integer>] [-healthMonitor
( YES | NO )] [-comment <string>]
[-appflowLog ( ENABLED | DISABLED )
]
To unset parameters from a GSLB service group unset gslb serviceGroup <
serviceGroupName>@ [<serverName>@ <
port> [-weight] [-hashId] [-
publicIP] [-publicPort]] [-
maxClient] [-cip] [-cltTimeout] [-
svrTimeout] [-maxBandwidth] [-
monThreshold] [-appflowLog] [-
monitorName] [-weight] [-
healthMonitor] [-cipHeader] [-
downStateFlush] [-comment]
To enable a GSLB service group enable gslb serviceGroup <
serviceGroupName>@ [<serverName>@ <
port>]
Example:enable gslb serviceGroup SG1 S1 80
To disable a GSLB service group disable gslb serviceGroup <
serviceGroupName>@ [<serverName>@ <
port>] [-delay <secs>] [-graceFul (
YES /| NO )]

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2262

NetScaler 12.0

Operation CLI Command

Example:disable gslb serviceGroup SRG2 S1

80
Note: The service group that has to be
disabled must be a DBS service group and not
an autoscale service group.
To remove a GSLB service group rm gslb serviceGroup <
serviceGroupName>
Example:rm gslb serviceGroup
Service-Group-1
To view the statistics of a GSLB service group stat gslb serviceGroup [<
serviceGroupName>]
Example:stat gslb serviceGroup
Service-Group-1
To view the properties of a GSLB service group show gslb serviceGroup [<
serviceGroupName> -includeMembers]
Example: show gslb serviceGroup SG1; show
gslb serviceGroup -includeMembers

Changes to the existing GSLB CLI commands

The following table lists some of the changes that are done to the existing GSLBs commands after the
introduction of the GSLB service groups.

CLI Command Change

bind gslb vserver The service group name is added to the bind
command.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2263

NetScaler 12.0

CLI Command Change

Example:bind gslb vserver <name> ((-

serviceName <string> [-weight <
positive_integer>] )| <
serviceGroupName>@ | | (-domainName
<string> [-TTL <secs>] [-backupIP<
ip_addr|ipv6_addr|*>] [-
cookieDomain <string>] [-
cookieTimeout <mins>][-
sitedomainTTL <secs>])| (-
policyName <string>@ [-priority<
positive_integer>] [-
gotoPriorityExpression <expression
>] [-type REQUEST | RESPONSE )]))
unbind gslb vserver The service group is added to the unbind
command.
Example: unbind gslb vserver <name> (-
serviceName <string> <
serviceGroupName> @ /(-domainName <
string> [-backupIP] [-cookieDomain
])| -policyName <string>@)
show gslb site When this command is executed, the GSLB
service groups are also displayed.
show gslb vs When this command is executed, the GSLB
service groups are be displayed.
stat gslb vs When this command is executed, the GSLB
service groups statistics are also displayed.
show lb monitor bindings When this command is executed the GSLB
service group bindings are also displayed.

Configure GSLB service groups by using the GUI

1. Navigate to Traffic Management > GSLB > Service Groups.

2. Create a service group and set the AutoScale Mode to DNS.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2264

NetScaler 12.0

Tip

For deployment scenario and example configuration of GSLB service groups, see the following
topics:

• Use Case: Deployment of Domain Name Based Autoscale Service Group

• Use Case: Deployment of IP Address Based Autoscale Service Group

1.
2. Citrix ADC
3. NetScaler 12.0

Configure a GSLB virtual server

September 12, 2018

Contributed by:
C

A GSLB virtual server is an entity that represents one or more GSLB services and balances traffic be-
tween them. It evaluates the configured GSLB methods or algorithms to select a GSLB service to which
to send the client request.

Note

A GSLB virtual server protocol requirement is mainly to create a relation between the virtual
server and the services that are bound to the virtual server. This also keeps CLI/APIs consistent
with respect to other types of virtual servers. The Service Type parameter on a service or a vir-
tual server is not leveraged while serving the DNS requests. It is instead referenced during site
persistence, monitoring, and for the purpose of doing lookups via MEP.

To create a GSLB virtual server by using the command line interface

At the command prompt, type the following commands to add a GSLB virtual server and verify the
configuration:

1 - add gslb vserver <name> <serviceType> -ipType (IPv4 | IPv6)

2 - show gslb vserver <name>

Example:

1 add gslb vserver Vserver-GSLB-1 HTTP -ipType IPv4

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2265

NetScaler 12.0

2 add gslb vserver Vserver-GSLB-2 HTTP -ipType IPv6

3 show gslb vserver Vserver-GSLB-1
4 show gslb vserver Vserver-GSLB-2

To modify or remove a GSLB virtual server by using the command line interface

• To modify a GSLB virtual server, use the set gslb vserver command, which is just like using the
add gslb vserver command, except that you enter the name of an existing GSLB virtual server.
• To reset a parameter to is default value, you can use the unset gslb vserver command followed
by the vserverName value and the name of the parameter to be unset.
• To remove a GSLB virtual server, use the rm gslb vserver command, which accepts only the name
argument.

To configure a GSLB virtual server by using the configuration utility

1. Navigate to Traffic Management > GSLB > Virtual Servers.

2. Add a new GSLB virtual server, or select an existing GSLB virtual server and edit its settings.

To view the statistics of a GSLB virtual server by using the command line interface

At the command prompt, type:

1 stat gslb vserver <name>

Example:

1 stat gslb vserver Vserver-GSLB-1

To view the statistics of a GSLB virtual server by using the configuration utility

Navigate to Traffic Management > GSLB > Virtual Servers, select the virtual server and click Statis-
tics.

Statistics of a GSLB service

When you run the stat gslb service command from the command line or click on the Statistics link from
the configuration utility, the following details of the service will be displayed:

• Request bytes. Total number of request bytes received on this service or virtual server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2266

NetScaler 12.0

• Response bytes. Number of response bytes received by this service or virtual server.
• Current client established connections. Number of client connections in ESTABLISHED state.
• Current load on the service. Load on the service (Calculated from the load monitor bound to
the service).

The data of number of requests and responses, and the number of current client and server connec-
tions may not be displayed or may not be synchronized with the data of the corresponding load bal-
ancing virtual server.

Clearing the GSLB virtual server or service statistics

Note: This feature is available in NetScaler release 10.5.e.

You can now clear the statistics of a GSLB virtual server and service. NetScaler provides the following
two options to clear the statistics:

• Basic: Clears the statistics that are specific to the virtual server but retains the statistics that are
contributed by the bound GLSB service.
• Full: Clears both the virtual server and the bound GSLB service statistics.

To clear the statistics of a GSLB virtual server by using the command line interface

At the command prompt, type:

1 stat gslb vserver <name> -clearstats <basic | full>

Example:

1 stat gslb vserver Vserver-GSLB-1 ‒ clearstats basic

To clear the statistics of a GSLB service by using the command line interface

At the command prompt, type:

1 stat gslb service <name> -clearstats <basic | full>

Example:

1 stat gslb service service-GSLB-1 ‒ clearstats basic

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2267

NetScaler 12.0

To clear the statistics of a GSLB virtual server by using the configuration utility

1. Navigate to Traffic Management > GSLB > Virtual Servers.

2. Select the GSLB virtual server and, click Statistics, and then click Clear.
3. From the Clear drop-down list, select Basic or Full, and then click OK.

To clear the statistics of a GSLB service by using the configuration utility

1. Navigate to Traffic Management > GSLB > Services.

2. Select the GSLB service and, click Statistics, and then click Clear.
3. From the Clear drop-down list, select Basic or Full, and then click OK.

Enabling and Disabling GSLB Virtual Servers

When you create a GSLB virtual server, it is enabled by default. If you disable it, it cannot process
traffic. A disabled GSLB virtual server is not included in GSLB configuration but is not removed from
the NetScaler appliance.

To enable or disable a GSLB virtual server by using the command line interface

At the command prompt, type one of the following commands:

1 enable gslb vserver <name>@

2
3 disable gslb vserver <name>@

Example:

1 enable gslb vserver Vserver-GSLB-1

2 disable gslb vserver Vserver-GSLB-1

To enable or disable a GSLB virtual server by using the configuration utility

1. Navigate to Traffic Management > GSLB > Virtual Servers.

2. Select a virtual server and, from the Action list, select enable or disable.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2268

NetScaler 12.0

Bind GSLB services to a GSLB virtual server

September 12, 2018

Contributed by:
C

Once the GSLB services and virtual server are configured, relevant GSLB services must be bound to
the GSLB virtual server to activate the configuration.

To bind a GSLB service to a GSLB virtual server by using the command line interface

At the command prompt, type the following commands to bind a GSLB service to a GSLB virtual server
and verify the configuration:

1 bind gslb vserver <name> -serviceName <string>

2
3 show gslb vserver <name>

Example:

1 bind gslb vserver Vserver-GSLB-1 -serviceName Service-GSLB-1

2 show gslb vserver Vserver-GSLB-1

To unbind a GSLB service from a GSLB virtual server by using the command line
interface

At the command prompt, type:

1 unbind gslb vserver <name> -serviceName <string>

To bind GSLB services by using the configuration utility

1. Navigate to Traffic Management > GSLB > Virtual Servers and double-click a virtual server.
2. Click in the Domains section, and configure a domain and bind the domain.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2269

NetScaler 12.0

Bind a domain to a GSLB virtual server

September 12, 2018

Contributed by:
C

To make a NetScaler appliance the authoritative DNS server for a domain, you must bind the domain
to the GSLB virtual server. When you bind a domain to a GSLB virtual server, the NetScaler appliance
adds an address record for the domain, containing the name of the GSLB virtual server. The start of
authority (SOA) and name server (NS) records for the GSLB domain must be added manually.

For details on configuring SOA and NS records, see Domain Name System.

To bind a domain to a GSLB virtual server by using the command line interface

At the command prompt, type the following commands to bind a domain to a GSLB virtual server and
verify the configuration:

1 bind gslb vserver <name> -domainName <string>

2 show gslb vserver <name>

Example:

1 bind gslb vserver Vserver-GSLB-1 -domainName www.mycompany.com

2 show gslb vserver Vserver-GSLB-1

To unbind a GSLB domain from a GSLB virtual server by using the command line
interface

At the command prompt, type:

1 unbind gslb vserver <name> -domainName <string>

To bind a domain to a GSLB virtual server by using the configuration utility

1. Navigate to Traffic Management > GSLB > Virtual Servers.

2. In GSLB Virtual Servers pane, select the GSLB Virtual Server to which you want to bind the do-
main (for example, Vserver-GSLB-1) and click Open.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2270

NetScaler 12.0

3. In the Configure GSLB Virtual Server dialog box, on the Domains tab, do one of the following:

• To create a new Domain, click Add.

• To modify an existing Domain, select the domain, and then click Open.

4. In the Create GSLB Domain or Configure GSLB Domain dialog box, specify values for the follow-
ing parameters as shown:

• Domain Name*—domainName (for example, www.mycompany.com)

/* A required parameter

5. Click Create.

6. Click OK.

To view the statistics of a domain by using the command line interface

At the command prompt, type:

1 stat gslb domain <name>

Example:

1 stat gslb domain www.mycompany.com

Note: To view statistics for a particular GSLB domain, enter the name of the domain exactly as it was
added to the NetScaler appliance. If you do not specify the domain name, or if you specify an incorrect
domain name, statistics for all configured GSLB domains are displayed.

To view the statistics of a domain by using the configuration utility

1. Navigate to Traffic Management > GSLB > Virtual Servers.

2. In GSLB Virtual Servers pane, select the GSLB Virtual Server (for example, Vserver-GSLB-1) and
click Open.
3. In the Configure GSLB Virtual Server dialog box, on the Domains tab, select the domain, and
then click Statistics.

To view the configuration details of the entities bound to a GSLB domain using the
command line

Note: This feature is available in NetScaler release 10.5.e.

At the command prompt, type:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2271

NetScaler 12.0

1 show gslb domain <name>

Example:

1 show gslb domain gslb1.com

2 gslb1.com
3 gvs1 - HTTP state: DOWN
4 DNS Record Type: A
5 Configured Method: LEASTCONNECTION
6 Backup Method: ROUNDROBIN
7 Persistence Type: NONE
8 Empty Down Response: DISABLED
9 Multi IP Response: DISABLED
10 Dynamic Weights: DISABLED
11
12 gsvc1 (10.102.239.165: 80)- HTTP State: DOWN Weight: 1
13 Dynamic Weight: 0 Cumulative Weight: 1
14 Effective State: DOWN
15 Threshold : BELOW
16
17 Monitor Name : http
18 State: DOWN Weight: 1
19 Probes: 144 Failed [Total: 144 Current: 144]
20 Last response: Failure - TCP syn sent, reset
received.
21 Response Time: 2000 millisec
22
23 gsvc2 (10.102.239.179: 80)- HTTP State: DOWN Weight: 1
24 Dynamic Weight: 0 Cumulative Weight: 1
25 Effective State: DOWN
26 Threshold : BELOW
27
28 Monitor Name : http-ecv
29 State: DOWN Weight: 1
30 Probes: 141 Failed [Total: 141 Current: 141]
31 Last response: Failure - TCP syn sent, reset
received.
32 Response Time: 2000 millisec
33 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2272

NetScaler 12.0

To view the configuration details of the entities bound to a GSLB domain by using the
configuration utility

Note: This feature is available in NetScaler release 10.5.e.

1. Navigate to Traffic Management > GSLB > Virtual Servers and double-click a virtual server.
2. Click the field below the Domains pane.
3. In the GSLB Virtual Server Domain Binding dialog box, select a domain, and then click Show
Bindings.

1.
2. Citrix ADC
3. NetScaler 12.0

Example of a GSLB setup and configuration

January 14, 2019

Contributed by:
C

An organization has a geographically dispersed network and has three data centers located in the
United States, Mexico, and Colombia. In the configuration related to these locations, these are re-
ferred to as US, MX, and CO respectively. At each location, the company has a server farm, which
provides the same content and the setup is working as expected. The NetScaler appliance at each
location is configured through a virtual server with the HTTP protocol on port 80.

The organization has implemented the GSLB setup by adding a site identifier at each site. The site
identifier includes a site name and an IP address that is owned by the NetScaler appliance and is used
for the GSLB communications.
Each site has a site local to the appliance. Also, each site has two sites remote to the local appliance.
On each site, a GSLB virtual server is created with the same name. This virtual server identifies the
website of the organization globally and does not have any IP address associated with it.
The setup also has GSLB services configured that point to the load balancing virtual servers configured
on each GSLB site by specifying the IP address, protocol, and port number of the respective virtual
server. These services are bound to the GSLB virtual server.

Note: In the procedure below, the commands use private IP addresses for the GSLB sites. For public
sites and GSLB services, ensure that you use public IP addresses for these sites.

The following table lists the IP addresses and locations used in the example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2273

NetScaler 12.0

IP Address Location

10.3.1.101 Site IP of local NetScaler.

172.16.1.101 Site IP of remote location site-MX.
192.168.1.101 Site IP of remote location site-CO.
172.16.1.100 Service IP of remote location site-MX.
10.3.1.100 Service IP of local NetScaler.
192.168.1.100 Service IP of remote location site-CO.

When adding a GSLB site, if the site communicates over the internet only then use the “Public IP” field.
For example, when there is no site to site VPN connectivity between the GSLB sites.

To configure the GSLB setup with NetScaler appliances by using the CLI commands

1. Enable the GSLB feature, if not already done.

1 enable ns feature gslb

2. Identify a SNIP that for adding local GSLB site.

3. Add the GSLB site for the local NetScaler appliance.

1 add gslb site site-US 10.3.1.101

4. Add the GSLB sites for the remote NetScaler appliances.

1 add gslb site site-MX 172.16.1.101

2 add gslb site site-CO 192.168.1.101

5. Add the GSLB virtual server that references a service being used in the GSLB setup:

1 add gslb vserver gslb-lb HTTP

6. Add the GSLB services for each site participating in the GSLB setup:

1 add gslb service gslb_SVC30 172.16.1.100 HTTP 80 -siteName site-MX

2 add gslb service gslb_SVC10 10.3.1.100 HTTP 80 -siteName site-US
3 add gslb service gslb_SVC20 192.168.1.100 HTTP 80 -siteName site-
CO

7. Bind the GSLB services to the GSLB virtual server:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2274

NetScaler 12.0

1 bind gslb vserver gslb-lb -serviceName gslb_SVC10

2 bind gslb vserver gslb-lb -serviceName gslb_SVC20
3 bind gslb vserver gslb-lb -serviceName gslb_SVC30

8. Bind the domain to the GSLB virtual server.

1 bind gslb vserver gslb-lb -domainName www.mycompany.com -TTL 30

9. Add an ADNS service that listens to the DNS queries.

1 set service Service-ADNS-1 10.14.39.21 ADNS 53

1.
2. Citrix ADC
3. NetScaler 12.0

Synchronize the configuration in a GSLB setup

January 14, 2019

Contributed by:
C

Typically, a GSLB setup has a few data centers with a GSLB site configured for each data center. In
each NetScaler, participating in GSLB, configure one GSLB site as a local site and the others as remote
sites. When you add another GSLB site at a later point, you must ensure that the configuration across
all GSLB sites is identical. You can use the NetScaler’s GSLB configuration synchronization option to
synchronize the configuration across the GSLB sites.

The NetScaler appliance from which you use the synchronization option is referred to as the ‘master
node’ and the GSLB sites on which the configuration is copied as ‘slave nodes.’ When you synchronize
a GSLB configuration, the configurations on all the GSLB sites participating in the GSLB setup are made
similar to that on the master node.

Synchronization (may also be referred to as ‘auto sync’) is carried out in the following manner:

• The master node finds the differences between the configuration of the master node and slave
node, and changes the configuration of the slave node to make it similar to the master node.
If you force a synchronization (use the ‘force sync’ option), the appliance deletes the GSLB con-
figuration from the slave node and then configures the slave to make it similar to the master
node.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2275

NetScaler 12.0

• During synchronization, if a command fails, synchronization is not aborted and the error mes-
sage are logged into a .err file in the /var/netscaler/gslb directory.
• Synchronization is done only on the parent sites. GSLB child sites’ configuration is not affected
by synchronization. This is because the parent site and the child site configurations are not
identical. The child sites configuration consists only of its own and its parent site’s details. Also,
GSLB services are not always required to be configured in the child sites.
• If you disable the internal user login, the GSLB auto sync uses the SSH keys to synchronize the
configuration. But, to use GSLB auto sync in partition environment, you need to enable the
internal user login and make sure that the partition username in the local and remote GSLB
sites is same.
Note

• On the remote GSLB site RPC node, configure the firewall to accept auto-sync connections
by specifying the remote site IP (cluster IP address for cluster setup) and port (3010 for RPC
and 3008 for secure RPC). If the default route to reach the remote sites is in management
subnet, as in most cases, then NSIP is used as the source IP address.

To configure a different source IP address, you must have the GSLB site IP address and the
SNIP in a different subnet. Also, you must have an explicit route defined to the remote site
IP address through GSLB site IP subnet.

• The source IP address cannot be synchronized across the sites participating in GSLB be-
cause the source IP address for a RPC node is specific to each NetScaler appliance. There-
fore, after you force a synchronization (using the sync gslb config -forceSync command or
by selecting the ForceSync option in the GUI), you have to manually change the source IP
addressess on the other NetScaler appliances.

• Port 22 is also required for synchronizing the database files to the remote site.

If you use the saveconfig option, the sites that participate in the synchronization process auto-
matically save their configuration, in the following way:

1. The master node saves its configuration immediately before it initiates the process of synchro-
nization.
2. After the process of synchronization is complete, the slave nodes save their configuration. A
slave node saves its configuration only if the configuration difference was applied successfully
on it. If synchronization fails on a slave node, you must manually investigate the cause of the
failure and take corrective action.

Limitations of synchronization:

• On the master node, the names of the remote GSLB sites must be identical to the names of sites
configured on the NetScaler appliances hosting those sites.
• During the synchronization, traffic disruptions may occur.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2276

NetScaler 12.0

• NetScaler can synchronize only up to 80000 lines of the configuration.

• Synchronization may fail:
– If the spill over method is changed from CONNECTION to DYNAMIC CONNECTION.
– If you interchange the site prefix of the GSLB services bound to a GSLB virtual server on
the master node and then try to synchronize.
– If the RPC node passwords are different for NSIP and loopback IP address.
• If you have configured the GSLB sites as High Availability (HA) pairs, the RPC node passwords of
primary and secondary nodes should be same.
• If you rename any GLSB entity that are part of your GSLB configuration (use “show gslb running-
Config” command to display the GSLB configuration). You need to use the force sync option to
synchronize the configuration to other GSLB sites.

Note: To overcome the limitations due to some settings in the GSLB configuration, you can use
the force sync option. But, if you use the force sync option the GSLB entities are removed and
re-added to the configuration and the GSLB statistics are reset to zero. Hence the traffic is disrupted
during the configuration change.

Before you start the synchronization of a GSLB setup, make sure that:

• On all the GSLB sites including the master node, management access and SSH should be en-
abled for the IP address of the corresponding GSLB site. The IP address of a GSLB site must be
an IP address owned by the NetScaler appliance. For more information about adding the GSLB
site IP addresses and enabling Management Access, see “Configuring a Basic GSLB Site”.
• The GSLB configuration on the NetScaler appliance that is considered as the master node is
complete and appropriate to be copied on all the sites.
• If you are synchronizing the GSLB configuration for the first time, all the sites participating in
GSLB need to have the GSLB site entity of their respective local sites.
• You are not synchronizing sites that, by design, do not have the same configuration.

Important

The following directories are synchronized as part of the GSLB configuration synchronization.

• /var/netscaler/locdb/
• /var/netscaler/ssl/

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2277

NetScaler 12.0

Manual synchronization between sites participating in GSLB

September 12, 2018

Contributed by:
C

Important: After a GSLB configuration is synchronized, the configuration cannot be rolled back on any
of the GSLB sites. Perform the synchronization only if you are sure that the synchronization process
will not overwrite the configuration on the remote site. Site synchronization is undesirable when the
local and remote sites have different configurations by design, and can lead to site outage. If some
commands fail and some commands succeed, the successful commands cannot be rolled back.

To synchronize a GSLB configuration by using the CLI:

At the command prompt, type the following commands to synchronize GSLB sites and verify the con-
figuration:

1 sync gslb config [-preview | -forceSync <string> | -nowarn | -

saveconfig] [-debug]
2 show gslb syncStatus

Example:

1 sync gslb config

2
3 [WARNING]: Syncing config may cause configuration loss on other site.
4
5 Please confirm whether you want to sync-config (Y/N)? [N]:y
6
7 Sync Time: Dec 9 2011 10:56:9
8
9 Retrieving local site info: ok
10
11 Retrieving all participating gslb sites info: ok
12
13 Gslb_site1[Master]:
14
15 Getting Config: ok
16
17 Gslb_site2[Slave]:
18
19 Getting Config: ok
20
21 Comparing config: ok

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2278

NetScaler 12.0

22
23 Applying changes: ok
24
25 Done

To synchronize a GSLB configuration by using the GUI:

1. Navigate to Traffic Management > GSLB > Dashboard.

2. Click Auto Synchronization GSLB and select ForceSyn.
3. In GSLB Site Name, select the GSLB sites that are to be synchronized with the master node
configuration.

Previewing GSLB synchronization

By previewing the GSLB synchronization operation, you can see the differences between the master
node and each slave node. If there are any discrepancies, you can troubleshoot before synchronizing
the GSLB configuration.

To preview the GSLB synchronization output by using the CLI:

At the command prompt, type the following command:

1 sync gslb config -preview

To preview the GSLB synchronization output by using the GUI:

1. Navigate to Configuration > Traffic Management > GSLB > Dashboard.

2. Click Auto Synchronization GSLB and select Preview.
3. Click Run.
A progress window displays any discrepancies in the configuration.

Debugging the commands triggered during synchronization process

You can view the status (success or failure) of each command triggered during the synchronization
process and troubleshoot accordingly.

To debug the GSLB synchronization commands by using the CLI:

At the command prompt, type the following command:

1 sync gslb config -debug

To debug the GSLB synchronization commands by using the GUI:

1. Navigate to Configuration >Traffic Management> GSLB > Dashboard.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2279

NetScaler 12.0

2. Click Auto Synchronization GSLB and select Debug.

3. Click Run.
A progress window displays the status of each command triggered during synchronization.
1.
2. Citrix ADC
3. NetScaler 12.0

Real-time synchronization between sites participating in GSLB

September 12, 2018

Contributed by:
C
If you want to synchronize GSLB configuration across slave sites automatically when the commands
are executed on master sites, you can now use the AutomaticConfigSync option to automatically syn-
chronize the real-time GSLB configuration. You do not have to manually trigger the AutoSync option
to synchornize the configuration.
If you attempt to manually synchronize (with the sync gslb config command) a site while it is being
autosynchronized, a “Sync in progress” error message appears. Autosynchronization cannot be trig-
gered for a site that is in the process of being synchronized manually.

Attention:

Starting with NetScaler 12.1 build xx.xx, SNMP traps are generated when you synchronize the
GSLB configuration. Note that in real-time synchronization, the synchronization status in the
first SNMP trap is captured as failure. You can ignore this status because a second SNMP trap is
automatically generated immediately after the first trap with the actual synchronization status.
However, if the synchronization failed in the second attempt also, SNMP trap is not generated
because the synchronization status has not changed from the previous synchronization status.

For details on configuring NetScaler appliance to generate traps, see Configuring the NetScaler to
generate SNMP traps.
Notes:
• All logs related to real-time sync are stored in the /var/netscaler/gslb/periodic_sync.log file.
• The sync status file and default configuration file are stored in the location /var/netscaler/gslb_sync.
• Enabling AutomaticConfigSync from default partition of a partitioned appliance is not
supported. However, it can be enabled from all other partitions. The sync status file and
default configuration file are stored in the location /var/partitions/<partition name>
/netscaler/gslb_sync.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2280

NetScaler 12.0

Best practices for using the real-time synchronization feature

• It is recommended that all the NetScaler appliances participating as sites have the
sameNetScaler software version.
• To change the RPC node password, first change the password on the slave site and then on the
master site.
• Configure local GSLB sites on each site participating in GSLB.
• Enable automaticConfigSync on one of the sites where the configuration is performed. This site
eventually gets synchronized to other GSLB sites.
• If there is a new configuration or changes are made to the existing configuration, make sure
to check the status using the “show gslb syncStatus” command to confirm if the changes are
synchronized across all sites or if there was any error.

To enable real-time synchronization by using the CLI

At the command prompt, type:

1 set gslb parameter  ‒ automaticConfigSync (ENABLED | DISABLED)

Example:

1 set gslb parameter  ‒ automaticConfigSync ENABLED

To enable real-time synchronization by using the GUI

1. Navigate to Configuration > Traffic Management > GSLB > Change GSLB Settings.
2. Select Automatic ConfigSync.

Note: This option must be enabled only in the site where the configuration is performed.

Tip

For information on the following topics, see Manual synchronization between sites participating
in GSLB.

• Previewing GSLB synchronization

• Debugging the commands triggered during synchronization process

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2281

NetScaler 12.0

GSLB dashboard

September 12, 2018

Contributed by:
C
You can view the overall status of the GSLB sites participating in GSLB on the GSLB dashboard.
You can access the GSLB settings from the dashboard. You can also start the GSLB configuration wizard
from the dashboard. Additionally, you can perform the synchronization and test the GSLB setup from
the dashboard.
To access the GSLB dashboard, navigate to Configuration > Traffic Management > GSLB > Dash-
board.
1.
2. Citrix ADC
3. NetScaler 12.0

Monitor GSLB services

September 12, 2018

Contributed by:
C
When you bind a remote service to a GSLB virtual server, the GSLB sites exchange metric information,
including network metric Information, which is the round-trip-time and persistence Information.
If a metric exchange connection is momentarily lost between any of the participating sites, the remote
site is marked as DOWN and load balancing is performed on the remaining sites that are UP. When
metric exchange for a site is DOWN, the remote services belonging to the site are marked DOWN as
well.
The NetScaler appliance periodically evaluates the state of the remote GSLB services by using either
MEP or monitors that are explicitly bound to the remote services. Binding explicit monitors to local
services is not required, because the state of the local GSLB service is updated by default using the
MEP. However, you can bind explicit monitors to a remote service. When monitors are explicitly bound,
the state of the remote service is not controlled by the metric exchange.
By default, when you bind a monitor to a remote GSLB service, the NetScaler appliance uses the state
of the service reported by the monitor. However, you can configure the NetScaler appliance to use
monitors to evaluate services in the following situations:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2282

NetScaler 12.0

• Always use monitors (default setting).

• Use monitors when MEP is DOWN.
• Use monitors when remote services and MEP are DOWN.

The second and third of the above settings enable the appliance to stop monitoring when MEP is UP.
For example, in a hierarchical GSLB setup, a GSLB site provides the MEP information about its child
sites to its parent site. Such an intermediate site may evaluate the state of the child site as DOWN
because of network issues, though the actual state of the site is UP. In this case, you can bind mon-
itors to the services of the parent site and disable MEP to determine the actual state of the remote
service. This option enables you to control the manner in which the states of the remote services are
determined.

To use monitors, first create them, and then bind them to GSLB services.

Configure monitor trigger

You can configure a GSLB site to always use monitors (the default), use monitors when MEP is down, or
use monitors when both the remote service and MEP are down. In the latter two cases, the NetScaler
appliance stops monitoring when MEP returns to the UP state.

To configure monitor triggering by using the command line interface

At the command prompt, type:

1 set gslb site <siteName>  ‒ triggerMonitor (ALWAYS | MEPDOWN |

MEPDOWN_SVCDOWN)

Example:

1 set gslb site Site-GSLB-North-America ‒ triggerMonitor Always

To configure monitor triggering by using the configuration utility

1. Navigate to Traffic Management > GSLB > Sites, and double-click the site.
2. In the Trigger Monitors drop-down list, select an option for when to trigger monitoring.

Add or remove monitors

To add a monitor, you specify the type and the port. You cannot remove a monitor that is bound to a
service. You must first unbind the monitor from the service.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2283

NetScaler 12.0

To add a monitor by using the command line interface

At the command prompt, type the following commands to create a monitor and verify the configura-
tion:

1 add lb monitor <monitorName> -type <monitorType> -destPort <portNumber>

2
3 show lb monitor <monitorName>

Example:

1 add lb monitor monitor-HTTP-1 -type HTTP -destPort 80

2 show lb monitor monitor-HTTP-1

To remove a monitor by using the command line interface

At the command prompt, type:

1 rm lb monitor <monitorName>

To add a monitor by using the configuration utility

Navigate to
Traffic Management > Load Balancing > Monitors, and add or delete a monitor.

Bind monitors to a GSLB service

Once you create monitors, you must bind them to GSLB services. When binding monitors to the ser-
vices, you can specify a weight for the monitor. After binding one or more weighted monitors, you can
configure a monitor threshold for the service. This threshold takes the service down if the sum of the
bound monitor weights falls below the threshold value.

Note: In the configuration utility, you can set both the weight and the monitoring threshold at the
same time that you bind the monitor. When using the command line, you must issue a separate com-
mand to set the service’s monitoring threshold.

To bind the monitor to the GSLB service by using the command line interface

At the command prompt, type:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2284

NetScaler 12.0

1 bind monitor <name> <serviceName> [ -state (Enabled | Disabled) ] -

weight <positiveInteger>

Example:

1 bind monitor monitor-HTTP-1 service-GSLB-1 -state enabled -weight 2

To set the monitoring threshold for a GSLB service by using the command line interface

At the command prompt, type:

1 set gslb service <ServiceName> -monThreshold <PositiveInteger>

Example:

1 set gslb service service-GSLB-1 -monThreshold 9

To bind the monitor to the GSLB service by using the configuration utility

1. Navigate to Traffic Management > GSLB > Services.

2. Click the Monitor section and bind the monitor to the GSLB service.

To set the monitoring threshold for a GSLB service by using the configuration utility

1. Navigate to Traffic Management > GSLB > Services.

2. Click the Monitor Threshold section and enter a threshold value.

1.
2. Citrix ADC
3. NetScaler 12.0

Use case: Deployment of domain name based autoscale service group

September 12, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2285

NetScaler 12.0

Tip

For information about the GSLB service groups, see Configuring a GSLB Service Group

Deployment scenario

Two datacenters are deployed in two AWS regions, one in Sydney and one in North Virginia. Another
datacenter is deployed in Azure. An AWS ELB in each AWS region is used to load balance the applica-
tion servers. ALB is used for Azure to load balancing the application server. The NetScaler appliances
are configured for GSLB for the ELBs and ALB using GSLB domain name based autoscale service group.

Important

You must configure the required security groups in AWS and attach it to the GSLB instance. Port
53 must be allowed in the security group inbound and outbound rules. Also, ports (3009 or 3011
depending on secure MEP configuration) for MEP communication must be open. For application
monitoring, the corresponding ports must be allowed in the security group outbound rules.

The configuration steps for the above deployment scenario and the corresponding CLI commands are
as follows:

1. Create datacenters (represented by GSLB sites).

1 add gslb site aws-sydney 192.0.2.2

2
3 add gslb site aws-nvirginia 198.51.100.111
4
5 add gslb site alb-southindia 203.0.113.6

2. Add a name server with the DNS gateway IP address where the GSLB node is added. This must be
done in all datacenters.

1 add dns nameServer 8.8.8.8

3. Add servers for ELB and ALB.

1 add server aws-sydney_server lb-sydney-1052691850.ap-southeast-2.elb.

amazonaws.com
2
3 add server aws-nvirginia_server LB-nvirginia-860559595.us-east-1.elb.
amazonaws.com
4
5 add server alb-southindia_server alb.southindia.cloudapp.azure.com

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2286

NetScaler 12.0

4. Add GSLB autoscale service groups for each ELB and ALB and bind each server to the respective
service group.

1 add gslb serviceGroup aws-nvirginia_sg HTTP -autoScale DNS -siteName

aws-nvirginia
2
3 add gslb serviceGroup aws-sydney_sg HTTP  -autoScale DNS -siteName aws-
sydney
4
5 add gslb serviceGroup alb-southindia_sg HTTP  -autoScale DNS -siteName
alb-southindia
6
7 bind gslb serviceGroup aws-nvirginia_sg aws-nvirginia_server 80
8
9 bind gslb serviceGroup aws-sydney_sg aws-sydney_server 80
10
11 bind gslb serviceGroup alb-southindia_sg alb-southindia_server 80

5. Add a GSLB virtual server and bind the application domain and the service groups to this virtual
server.

1 add gslb vserver gv1 HTTP

2
3 bind gslb vserver gv1 -serviceGroupName aws-nvirginia_sg
4
5 bind gslb vserver gv1 -serviceGroupName aws-sydney_sg
6
7 bind gslb vserver gv1 -serviceGroupName alb-southindia_sg

1.
2. Citrix ADC
3. NetScaler 12.0

Use case: Deployment of IP address based autoscale service group

September 12, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2287

NetScaler 12.0

Tip

For information about the GSLB service groups, see Configuring a GSLB Service Group.

Deployment scenario

If there are multiple applications hosted on the same application server, the GSLB should probe these
applications to see if the applications are responding or not. If an application is not responding, the
user must be directed to the server on which the application is UP. Also, if one of the applications is
DOWN, then the server should not be marked DOWN, because the other applications are UP.

In the following example, multiple applications (HTTPS) are hosted on one server in each GSLB site
and hence all these applications resolve to one IP address of the respective site.

Using the GSLB service groups, you can have the same server with an IP address and port bound to
multiple service groups where each service group represents a different application.

An application specific monitor is bound to the service groups that marks the service group as DOWN
if the application is DOWN. Thus, whenever an application is DOWN, only that application is taken out
from the setup and not the server.

1 add gslb serviceGroup app1_site1 HTTP -maxClient 0 -cip DISABLED -

cltTimeout 180 -svrTimeout 360 -siteName s1
2
3 add gslb serviceGroup app2_site1 HTTP -maxClient 0 -cip DISABLED -
cltTimeout 180 -svrTimeout 360 -siteName s1
4
5 add gslb serviceGroup app1_site2 HTTP -maxClient 0 -cip DISABLED -
cltTimeout 180 -svrTimeout 360 -siteName s2
6
7 add gslb serviceGroup app2_site2 HTTP -maxClient 0 -cip DISABLED -
cltTimeout 180 -svrTimeout 360 -siteName s2
8
9 add lb monitor http_app2 HTTP -respCode 200 -httpRequest ”GET /testsite
/app2.html”
10
11 add lb monitor http_app1 HTTP -respCode 200 -httpRequest ”GET /testsite
/app1.html”
12
13 bind gslb serviceGroup app1_site1 192.0.2.140 80
14
15 bind gslb serviceGroup app1_site1 -monitorName http_app1
16
17 bind gslb serviceGroup app2_site1 192.0.2.140 80
18

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2288

NetScaler 12.0

19 bind gslb serviceGroup app2_site1 -monitorName http_app2

20
21 bind gslb serviceGroup app1_site2 192.0.2.142 80
22
23 bind gslb serviceGroup app1_site2 -monitorName http_app1
24
25 bind gslb serviceGroup app2_site2 192.0.2.142 80
26
27 bind gslb serviceGroup app2_site2 -monitorName http_app2

1.
2. Citrix ADC
3. NetScaler 12.0

How-to articles

September 12, 2018

Contributed by:
C

The GSLB how-to articles contain information about some of the important GSLB configurations such
as customizing GSLB configuration, configuring persistent connections, disaster recovery, and so on.

Customizing Your GSLB Configuration

Configuring Persistent Connections

Managing Client Connections

Configuring GSLB for Proximity

Protecting the GSLB Setup Against Failure

Configuring GSLB for Disaster Recovery

Overriding Static Proximity Behavior by Configuring Preferred Locations

Configuring GSLB Service Selection Using Content Switching

Configuring Global Server Load Balancing for DNS Queries with NAPTR records

Using the EDNS0 Client Subnet Option for Global Server Load Balancing

Example of a Complete Parent-Child Configuration Using the Metrics Exchange Protocol

1.
2. Citrix ADC

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2289

NetScaler 12.0

3. NetScaler 12.0

Customize your GSLB configuration

September 12, 2018

Contributed by:
C

Once your basic GSLB configuration is operational, you can customize it by modifying the bandwidth
of a GSLB service, configuring CNAME based GSLB services, static proximity, dynamic RTT, persistent
connections, or dynamic weights for services, or changing the GSLB Method.

You can also configure monitoring for GSLB services to determine their states.

These settings depend on your network deployment and the types of clients you expect to connect to
your servers.

Modify maximum connections or maximum bandwidth for a GSLB service

You can restrict the number of new clients that can simultaneously connect to a load balancing or
content switching virtual server by configuring the maximum number of clients and/or the maximum
bandwidth for the GSLB service that represents the virtual server.

To modify the maximum clients or bandwidth of a GSLB service by using the command line
interface

At the command prompt, type the following command to modify the maximum number of client con-
nections or the maximum bandwidth of a GSLB service and verify the configuration:

1 set gslb service <serviceName> [-maxClients <positive_integer>] [-

maxBandwidth <positive_integer>]
2 show gslb service <serviceName>

Example:

1 set glsb service Service-GSLB-1 ‒ maxBandwidth 100 ‒ maxClients 100

2 show gslb service Service-GSLB-1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2290

NetScaler 12.0

To modify the maximum clients or bandwidth of a GSLB service by using the configuration
utility

1. Navigate to Traffic Management > GSLB > Services, and double-click a service.
2. Click in the Other Settings section and set the following parameters:
• Max Clients—maxClients
• Max Bandwidth—maxBandwidth

Create CNAME-based GSLB services

To configure a GSLB service, you can use the IP address of the server or a canonical name of the server.
If you want to run multiple services (like an FTP and a Web server, each running on different ports) from
a single IP address or run multiple HTTP services on the same port, with different names, on the same
physical host, you can use canonical names (CNAMES) for the services.

For example, you can have two entries in DNS as ftp.example.com and www.example.com for FTP ser-
vices and HTTP services on the same domain, example.com. CNAME-based GSLB services are useful
in a multilevel domain resolver configuration or in multilevel domain load balancing. Configuring a
CNAME-based GSLB service can also help if the IP address of the physical server is likely to change.

If you configure CNAME-based GSLB services for a GSLB domain, when a query is sent for the GSLB
domain, the NetScaler appliance provides a CNAME instead of an IP address. If the A record for this
CNAME record is not configured, the client must query the CNAME domain for the IP address. If the
A record for this CNAME record is configured, the NetScaler appliance provides the CNAME with the
corresponding A record (IP address). The NetScaler appliance handles the final resolution of the DNS
query, as determined by the GSLB method. The CNAME records can be maintained on a different
NetScaler appliance or on a third-party system.

In an IP-address-based GSLB service, the state of a service is determined by the state of the server
that it represents. However, a CNAME-based GSLB service has its state set to UP by default; the virtual
server IP (VIP) address or metric exchange protocol (MEP) are not used for determining its state. If
a desktop-based monitor is bound to a CNAME-based GSLB service, the state of the service is deter-
mined according to the result of the monitor probes.

You can bind a CNAME-based GSLB service only to a GSLB virtual server that has the DNS Record Type
as CNAME. Also, a NetScaler appliance can contain at most one GSLB service with a given CNAME entry.

The following are some of the features supported for a CNAME-based GSLB service:

• GSLB-policy based site affinity is supported, with the CNAME as the preferred location.
• Source IP persistence is supported. The persistency entry contains the CNAME information in-
stead of the IP address and port of the selected service.

The following are the limitations of CNAME-based GSLB services:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2291

NetScaler 12.0

• Site persistence is not supported, because the service referenced by a CNAME can be present at
any third-party location.
• Multiple-IP-address response is not supported because one domain cannot have multiple
CNAME entries.
• Source IP Hash and Round Robin are the only load balancing methods supported. The Static
Proximity method is not supported because a CNAME is not associated with an IP address and
static proximity can be maintained only according to the IP addresses.

Note: The
Empty-Down-Response feature should be enabled on the GSLB virtual server to which you bind the
CNAME-based GSLB service. If you enable the
Empty-Down-Response feature, when a GSLB virtual server is DOWN or disabled, the response to a
DNS query, for the domains bound to this virtual server, contains an empty record without any IP
addresses, instead of an error code.

To create a CNAME-based GSLB service by using the command line interface

At the command prompt, type:

1 add gslb service <serviceName> -cnameEntry <string> -siteName <string>

Example:

1 add gslb service Service-GSLB-1 -cnameEntry transport.mycompany.com -

siteName Site-GSLB-East-Coast
2 add gslb service Service-GSLB-2 -cnameEntry finance.mycompany.com -
siteName Site-GSLB-West-Coast

To create a CNAME-based GSLB service by using the configuration utility

1. Navigate to Traffic Management > GSLB > Services.

2. Create a service, and set the Type to Canonical Name Based.

Configure transition Out-Of-Service State (TROFS) in GSLB

When you configure persistence on a GSLB virtual server to which a service is bound, the service contin-
ues to serve requests from the client even after it is disabled, accepting new requests or connections
only to honor persistence. After a configured period of time, known as the graceful shutdown period,
no new requests or connections are directed to the service, and all of the existing connections are
closed.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2292

NetScaler 12.0

When disabling a service, you can specify a graceful shutdown period, in seconds, by using the delay
argument. During the graceful shutdown period, if the service is bound to a virtual server, its state
appears as Out of Service.

Configure dynamic weights for services

In a typical network, there are servers that have a higher capacity for traffic than others. However, with
a regular load balancing configuration, the load is evenly distributed across all services even though
different services represent servers with different capacities.

To optimize your GSLB resources, you can configure dynamic weights on a GSLB virtual server. The
dynamic weights can be based on either the total number of services bound to the virtual server or the
sum of the weights of the individual services bound to the virtual server. Traffic distribution is then
based on the weights configured for the services.

When dynamic weights are configured on the GSLB virtual server, requests are distributed according
to the load balancing method, the weight of the GSLB service, and the dynamic weight. The product of
the weight of the GSLB service and the dynamic weight is known as the cumulative weight. Therefore,
when dynamic weight is configured on the GSLB virtual server, requests are distributed on the basis
of the load balancing method and the cumulative weight.

When dynamic weight for a virtual server is disabled, the numerical value is set to 1. This ensures that
the cumulative weight is a non-zero integer at all times.

Dynamic weight can be based on the total number of active services bound to load balancing virtual
servers or on the weights assigned to the services.

Consider a configuration with two GSLB sites configured for a domain and each site has two services
that can serve the client. If a service at either site goes down, the other server in that site has to handle
twice as much traffic as a service at the other site. If dynamic weight is based on the number of active
services, the site with both services active has twice the weight of the site with one service down and
therefore receives twice as much traffic.

Alternatively, consider a configuration in which the services at the first site represent servers that are
twice as powerful as servers at the second site. If dynamic weight is based on the weights assigned to
the services, twice as much traffic can be sent to the first site as to the second.

Note: For details on assigning weights to load balancing services, see “

Assigning Weights to Services”.

As an illustration of how dynamic weight is calculated, consider a GSLB virtual server that has a GSLB
service bound to it. The GSLB service represents a load balancing virtual server that in turn has two
services bound to it. The weight assigned to the GSLB service is 3. The weights assigned to the two
services are 1 and 2 respectively. In this example, when dynamic weight is set to:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2293

NetScaler 12.0

• Disabled:The cumulative weight of the GSLB virtual server is the product of the dynamic weight
(disabled = 1) and the weight of the GSLB service (3), so the cumulative weight is 3.
• SERVICECOUNT: The count is the sum of the number of services bound to the load balancing
virtual servers corresponding to the GSLB service (2), and the cumulative weight is the product
of the dynamic weight (2) and the weight of the GSLB service (3), which is 6.
• SERVICEWEIGHT: The dynamic weight is the sum of the number of services bound to the GSLB
service (2), and the cumulative weight is the product of the dynamic weight (2) and the weight
of the GSLB service (3), which is 6.
Note: Dynamic weights are not applicable when content switching virtual servers are configured.

To configure a GSLB virtual server to use dynamic weights by using the command line interface

At the command prompt, type:

1 set gslb vserver <name> -dynamicWeight SERVICECOUNT | SERVICEWEIGHT

Example:

1 set gslb vserver vserver-GSLB-1 -dynamicWeight SERVICECOUNT

To set GSLB virtual server to use dynamic weights by using the configuration utility

1. Navigate to Traffic Management > GSLB > Virtual Servers, double-click the GSLB virtual server
whose method you want to change (for example, vserver-GSLB-1).
2. Click the Method section and, from the Dynamic Weight drop-down list, select SERVICECOUNT
or SERVICEWEIGHT.
1.
2. Citrix ADC
3. NetScaler 12.0

Configure persistent connections

September 12, 2018

Contributed by:
C
Persistence ensures that a series of client requests for a particular domain name is sent to the same
data center instead of being load balanced. If persistence is configured for a particular domain, it takes

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2294

NetScaler 12.0

precedence over the configured GSLB method. Persistence is useful for deployments that deal with
e-commerce, such as shopping card usage, where the server needs to maintain the state of the con-
nection to track the transaction. To maintain the state of connection, you must configure persistence
on a virtual server. With persistence configured, the NetScaler appliance selects a data center to pro-
cess a client request and forwards the IP address of the selected data center for all subsequent DNS
requests. If the configured persistence applies to a site that is down, the NetScaler appliance uses a
GSLB method to select a new site, and the new site becomes persistent for subsequent requests from
the client.

The GSLB virtual server is responsible for DNS-based site persistence, and it controls the site persis-
tence for a remote GSLB service. The NetScaler appliance supports persistence based on the source
IP address or on HTTP cookies.

When you bring a physical service DOWN with a delay time, the physical service goes into the transition
out of service (TROFS) state. Site persistence is supported as long as the service is in the TROFS state.
That is, if the same client sends a request for the same service within the specified delay time after a
service is marked TROFS, the same GSLB site (data center) services the request.

Note: If connection proxy is specified as the site persistence method and if you also want to configure
persistence of the physical servers, do not configure SOURCEIP persistence. When the connection
is proxied, an IP address owned by the appliance is used, and not the actual IP address of the client.
Configure methods such as cookie persistence or rule-based persistence on the load balancing virtual
server.

Configure persistence based on source IP address

With source-IP persistence, when a DNS request is received at a data center, the NetScaler appliance
first looks for an entry in the persistence table and, if an entry for the local DNS server exists and the
server mentioned in the entry is configured, the IP address of that server is sent as the DNS response.

For the first request from a particular client, the NetScaler appliance selects the best GSLB site for the
request and sends its IP address to the client. Since persistence is configured for the source IP address
of the client, all subsequent requests by that client or another local DNS server in the same IP subnet
are sent the IP address of the GSLB site that was selected for the first request.

For source-IP address based persistence, the same set of persistence identifiers must be configured
on the GSLB virtual servers in all data centers. A persistence identifier is a number used by the data
centers to identify a particular GSLB virtual server. A cookie transmits the persistence identifier, en-
abling the NetScaler appliance to identify the domain so that it can forward all appropriate requests
to the same domain. When persistence is enabled, the persistence information is also exchanged as
part of metrics exchange.

For the NetScaler appliance to support persistence across sites, persistence must be enabled on the

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2295

NetScaler 12.0

GSLB virtual servers of all participating sites. When you use source IP address persistence on the net-
work identifier, you must configure a subnet mask. For any domain, persistence takes precedence
over any other configured GSLB method.

To configure persistence based on source IP address by using the command line interface

At the command prompt, type:

1 set gslb vserver <name> -persistenceType (SOURCEIP|NONE) -persistenceId

<positive_integer> [-persistMask <netmask>] ‒ [timeout <mins>]

Example:

1 set gslb vserver vserver-GSLB-1 -persistenceType SOURCEIP -

persistenceId 23 -persistMask 255.255.255.255 ‒ timeout 2

To configure persistence based on source IP address by using the configuration utility

1. Navigate to Traffic Management > GSLB > Virtual Servers and double-click the GSLB virtual
server whose method you want to change (for example, vserver-GSLB-1).
2. Click the Persistence section and, from the Persistence drop-down list, select SOURCEIP and
set the following parameters:
• Persistence Id—persistenceID
• Time-out—timeout
• IPv4 Netmask or IPv6 Mask length—persistMask

Configure persistence based on HTTP cookies

The NetScaler appliance provides persistence at the HTTP-request level by using connection proxy
and HTTP redirect. With these persistence methods, the appliance uses an HTTP cookie (known as a
“site cookie”) to reconnect the client to the same server. The appliance inserts the site cookie in the
first HTTP response.

The site cookie contains information about the selected GSLB service on which the client has a persis-
tent connection. The cookie expiration is based on the cookie timeout configured on the NetScaler
appliance. If the virtual server names are not identical on all the sites, you must use the persistence
identifier. Cookies inserted are compliant with RFC 2109.

When the NetScaler appliance responds to a client DNS request by sending the IP address of the se-
lected GSLB site, the client sends an HTTP request to that GSLB site. The physical server in that GSLB
site adds a site cookie to the HTTP header, and connection persistence is in effect.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2296

NetScaler 12.0

If the DNS entry in the client cache expires, and then the client sends another DNS query and is di-
rected to a different GSLB site, the new GSLB site uses the site cookie present in the client request
header to implement persistence. If the GSLB configuration at the new site uses connection-proxy
persistence, the new site creates a connection to the GSLB site that inserted the site cookie, proxies
the client request to the original site, receives a response from the original GSLB site, relays that re-
sponse back to the client, and closes the connection. If the GSLB configuration uses HTTP redirect
persistence, the new site redirects the request to the site that originally inserted the cookie.

Note: Connection proxy persistence can be configured only for local services. However, connection
proxy persistence must be enabled on both local and remote GSLB services that are configured for the
GSLB virtual server.

Connection proxy occurs when the following conditions are satisfied:

• Requests are sent from a domain participating in GSLB. The domain is obtained from the
URL/Host header.
• Requests are sent from a local GSLB service whose public IP address matches the public IP ad-
dress of an active service bound to the GSLB virtual server.
• The local GSLB service has connection proxy enabled.
• The request includes a valid cookie that contains the IP address of an active remote GSLB ser-
vice.

If one of the conditions is not met, connection proxy does not occur, but a site cookie is added if the
local GSLB service has connection proxy enabled AND:

• No site cookie is supplied; OR,

• The site cookie refers to an IP address that is not an active GSLB remote service; OR,
• The cookie refers to the IP address of the virtual server on which the request is received.

The following are the limitations of using connection proxy site cookies:

• Site cookies do not work for non-HTTP(S) protocols.

• If an HTTP request is sent to a back-up virtual server, the virtual server does not add a cookie.
• Site cookies do not work if SSL client authentication is required.
• At the local site, the statistics for a GSLB service on a remote site are not the same as the statistics
recorded for that service at the remote site. At the local site, the statistics for a remote GSLB
service are slightly higher than the statistics that the remote site records for that same service.

Redirect persistence can be used only:

• For HTTP or HTTPS protocols.

• If the domain name is present in the request (either in the URL or in the HOST header), and the
domain is a GSLB domain.
• When the request is received on a backup VIP or a GSLB local service that is in the down state.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2297

NetScaler 12.0

Note

In a GSLB parent-child configuration, connection proxy works as intended even when a GSLB
service is not configured on a child site. However, if you have additional configuration such as
client authentication, client IP address insertion, or other SSL-specific requirement, you must
add an explicit GSLB service on the site and configure it accordingly.

For more information about parent-child topology, see Parent-Child Topology Deployment Using
the MEP Protocol.

To set persistence based on HTTP cookies by using the command line interface

At the command prompt, type:

1 set gslb service <serviceName> -sitePersistence (ConnectionProxy [-

sitePrefix <prefix>] | HTTPredirect -sitePrefix <prefix>)

Example:

1 set gslb service service-GSLB-1 -sitePersistence ConnectionProxy

2 set gslb service service-GSLB-1 -sitePersistence HTTPRedirect -
sitePrefix vserver-GSLB-1

To set persistence based on cookies by using the configuration utility

1. Navigate to Traffic Management > GSLB > Services and select the service that you want to
configure for site persistence (for example, service-GSLB-1).
2. Click the Site Persistence section and set persistence based on cookies.
1.
2. Citrix ADC
3. NetScaler 12.0

Manage client connections

October 26, 2018

Contributed by:
C
To facilitate management of client connections, you can enable delayed cleanup of connections to
the virtual server. You can then manage local DNS traffic by configuring DNS policies.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2298

NetScaler 12.0

Enable delayed cleanup of virtual server connections

The state of a virtual server depends on the states of the services bound to it, and the state of each
service depends on the monitors bound to it. If a server is slow or down, the monitoring probes time
out and the service that represents the server is marked as DOWN. A virtual server is marked as DOWN
only when all services bound to it are marked as DOWN. You can configure services and virtual servers
to either terminate all connections when they go down, or allow the connections to go through. The
latter setting is for situations in which a service is marked as DOWN because of a slow server.

When you configure the down state flush option, the NetScaler appliance performs a delayed cleanup
of connections to a GSLB service that is down.

To enable delayed cleanup of virtual server connections by using the command line interface

At the command prompt, type the following commands to configure delayed connection cleanup and
verify the configuration:

1 set gslb service <name> -downStateFlush (ENABLED | DISABLED)

2 show gslb service <name>

Example:

1 set gslb service Service-GSLB-1 -downStateFlush ENABLED

2 Done
3
4 show gslb service Service-GSLB-1
5 Done

To enable delayed cleanup of virtual server connections by using the configuration utility

1. Navigate to Traffic Management > GSLB > Services and double-click the service.
2. Click the Other Settings section and select the Down State Flush option.

Manage local DNS traffic by using DNS policies

You can use DNS policies to implement site affinity by directing traffic from the IP address of a local
DNS resolver or network to a predefined target GSLB site. This is configured by creating DNS policies
with DNS expressions and binding the policies globally on the NetScaler appliance.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2299

NetScaler 12.0

DNS expressions

The NetScaler appliance provides certain predefined DNS expressions that can be used for configuring
actions specific to a domain. Such actions can, for example, drop certain requests, select a specific
view for a specific domain, or redirect certain requests to a specific location.

These DNS expressions (also called rules) are combined to create DNS policies that are then bound
globally on the NetScaler appliance.

Following is the list of predefined DNS qualifiers available on the NetScaler appliance:

• CLIENT.UDP.DNS.DOMAIN.EQ(“domainname”)
• CLIENT.UDP.DNS.IS_AREC
• CLIENT.UDP.DNS.IS_AAAAREC
• CLIENT.UDP.DNS.IS_SRVREC
• CLIENT.UDP.DNS.IS_MXREC
• CLIENT.UDP.DNS.IS_SOAREC
• CLIENT.UDP.DNS.IS_PTRREC
• CLIENT.UDP.DNS.IS_CNAME
• CLIENT.UDP.DNS.IS_NSREC
• CLIENT.UDP.DNS.IS_ANYREC

The CLIENT.UDP.DNS.DOMAIN DNS expression can be used with string expressions. If you are
using domain names as part of the expression, they must end with a period (.). For example,
CLIENT.UDP.DNS.DOMAIN.ENDSWITH(“abc.com.”)

To create an expression by using the configuration utility

1. Click the icon next to the Expression text box. Click Add. (Leave the Flow Type and Protocol
drop-down list boxes empty.) Follow these steps to create a rule.
2. In the Qualifier box, select a qualifier (for example, LOCATION).
3. In the Operator box, select an operator (for example, ==).
4. In the Value box, type a value (for example, Asia, Japan….).
5. Click OK. Click Create and click Close. The rule is created.
6. Click OK.

Configure DNS actions

A DNS policy includes the name of a DNS action to be performed when the policy rule evaluates to
TRUE. A DNS action can do one of the following:

• Send the client an IP address for which you have configured a DNS view. For more information
about DNS views, see Adding DNS Views.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2300

NetScaler 12.0

• Send the client the IP address of a GSLB service after referring to a list of preferred locations
that overrides static proximity behavior. For more information about preferred locations, see
Overriding Static Proximity Behavior by Configuring Preferred Locations.
• Send the client a specific IP address as determined by the evaluation of the DNS query or re-
sponse (DNS response rewrite).
• Forward a request to the name server without performing a lookup in the appliance’s DNS
cache.
• Drop a request.

You cannot create a DNS action for dropping a DNS request or for bypassing the DNS cache on the
appliance. If you want to drop a DNS request, use the built-in action, dns_default_act_Drop. If you
want to bypass the DNS cache, use the built-in action, dns_default_act_Cachebypass. Both actions
are available along with custom actions in the Create DNS Policy and the Configure DNS Policy dialog
boxes. These built-in actions cannot be modified or removed.

To configure a DNS action by using the command line interface

At the command prompt, type the following commands to configure a DNS action and verify the con-
figuration:

1 add dns action <actionName> <actionType> (-IPAddress <ip_addr |

ipv6_addr> ... | -viewName <string> | -preferredLocList <string>
...) [-TTL <secs>]
2
3 show dns action [<actionName>]

Examples

Example 1: Configuring DNS Response Rewrite. The following DNS action sends the client a precon-
figured IP address when the policy to which the action is bound evaluates to true:

1 add dns action dns_act_response_rewrite Rewrite_Response -IPAddress

192.0.2.20 192.0.2.56 198.51.100.10
2 Done
3
4 show dns action dns_act_response_rewrite
5 1) ActionName: dns_act_response_rewrite ActionType: Rewrite_Response
TTL: 3600 IPAddress: 192.0.2.20 192.0.2.56
198.51.100.10
6 Done

Example 2: Configuring a DNS-View Based Response. The following DNS action sends the client an
IP address for which you have configured a DNS view:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2301

NetScaler 12.0

1 add dns action send_ip_from_view_internal_ip ViewName -viewName

view_internal_ip
2 Done
3
4 show dns action send_ip_from_view_internal_ip
5 1) ActionName: send_ip_from_view_internal_ip ActionType: ViewName
ViewName: view_internal_ip
6 Done

Example 3: Configuring a Response Based on a Preferred Location List. The following DNS ac-
tion sends the client the IP address that corresponds to the preferred location that it selects from the
specified list of locations:

1 add dns action send_preferred_location GslbPrefLoc -preferredLocList NA

.tx.ns1.*.*.* NA.tx.ns2.*.*.* NA.tx.ns3.*.*.*
2 Done
3
4 show dns action send_preferred_location
5 1) ActionName: send_preferred_location ActionType: GslbPrefLoc
PreferredLocList: ”NA.tx.ns1.*.*.*” ”NA.tx.ns2.*.*.*” ”NA.tx.ns3
.*.*.*”
6 Done

To configure a DNS action by using the NetScaler configuration utility

1. Navigate to Traffic Management > DNS > Actions, create or edit a DNS action.
2. In the Create DNS Action or Configure DNS Action dialog box, set the following parameters:
• Action Name (cannot be changed for an existing DNS action)
• Type (cannot be changed for an existing DNS action)
To set the
Type parameter, do one of the following:
– To create a DNS action that is associated with a DNS view, select View Name. Then,
from the View Name list, select the DNS view that you want to use in the action.
– To create a DNS action with a preferred location list, select Preferred Location List. In
Preferred Location, enter a location, and then click Add. Add as many DNS locations
as you want.
– To configure a DNS action for rewriting a DNS response on the basis of policy evalua-
tion, select Rewrite Response. In IP Address, enter an IP address, and then click Add.
Add as many IP addresses as you want.
• TTL (applicable only to the Rewrite Response action type)

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2302

NetScaler 12.0

Configure DNS policies

DNS policies operate on a location database that uses static and custom IP addresses. The attributes
of the incoming local DNS request are defined as part of an expression, and the target site is defined
as part of a DNS policy. While defining actions and expressions, you can use a pair of single quotation
marks (‘’) as a wildcard qualifier to specify more than one location. When a DNS policy is configured
and a GSLB request is received, the custom IP address database is first queried for an entry that defines
the location attributes for the source:

• When a DNS query comes from an LDNS, the characteristics of the LDNS are evaluated against
the configured policies. If they match, an appropriate action (site affinity) is executed. If the
LDNS characteristics match more than one site, the request is load balanced between the sites
that match the LDNS characteristics.
• If the entry is not found in the custom database, the static IP address database is queried for an
entry, and if there is a match, the above policy evaluation is repeated.
• If the entry is not found in either the custom or static databases, the best site is selected and
sent in the DNS response on the basis of the configured load balancing method.

The following restrictions apply to DNS policies created on the NetScaler appliance.

• A maximum of 64 policies are supported.

• DNS policies are global to the NetScaler appliance and cannot be applied to a specific virtual
server or domain.

• Domain or virtual server specific binding of policy is not supported.

You can use DNS policies to direct clients that match a certain IP address range to a specific site. For
example, if you have a GSLB setup with multiple GSLB sites that are separated geographically, you can
direct all clients whose IP address is within a specific range to a particular data center.

Both TCP-based and UDP-based DNS traffic can be evaluated. Policy expressions are available for
UDP-based DNS traffic on the server and for both UDP-based DNS traffic and TCP-based DNS traffic
on the client side. Additionally, you can configure expressions to evaluate queries and responses that
involve only the following DNS question types (or QTYPE values):

• A
• AAAA
• NS
• SRV
• PTR
• CNAME
• SOA
• MX
• ANY

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2303

NetScaler 12.0

The following response codes (RCODE values) are also supported:

• NOERROR - No error
• FORMERR - Format error
• SERVFAIL - Server failure
• NXDOMAIN - Non-existent domain
• NOTIMP - Query type not implemented
• REFUSED - Query refused

You can configure expressions to evaluate DNS traffic. A DNS expression begins with the DNS.REQ or
DNS.RES prefixes. Functions are available for evaluating the queried domain, the query type, and the
carrier protocol. For more information about DNS expressions, see “Expressions for Evaluating a DNS
Message and Identifying Its Carrier Protocol” in “Policy Configuration and Reference”.

To add a DNS policy by using the command line interface

At the command prompt, type the following commands to create a DNS policy and verify the configu-
ration:

1 add dns policy <name> <rule> <actionName>

2 show dns policy <name>

Example:

1 > add dns policy policy-GSLB-1 ’CLIENT.UDP.DNS.DOMAIN.EQ(”domainname”)’

my_dns_action
2 Done
3 > show dns policy policy-GSLB-1
4 Name: policy-GSLB-1
5 Rule: CLIENT.UDP.DNS.DOMAIN.EQ(”domainname”)
6 Action Name: my_dns_action
7 Hits: 0
8 Undef Hits: 0
9
10 Done

To remove a configured DNS policy by using the command line interface

At the command prompt, type:

1 rm dns policy <name>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2304

NetScaler 12.0

To configure a DNS policy by using the NetScaler configuration utility

1. Navigate to Traffic Management > DNS > Policies and create a DNS policy.
2. In the Create DNS Policy or Configure DNS Policy dialog box, set the following parameters:
• Policy Name (cannot be changed for an existing policy)
• Action
• Expression
To specify an expression, do the following:
a) Click Add, and then, in the drop-down box that appears, select the expression element
with which you want to begin the expression. A second list appears. The list contains
a set of expression elements that you can use immediately after the firs expression
element.
b) In the second list, select the expression element that you want, and then enter a pe-
riod.
c) After each selection, if you enter a period, the next set of valid expression elements
appear in a list. Select expression elements and fill in arguments to functions until
you have the expression you want.
3. Click Create or OK, and then click Close.

Bind DNS policies

DNS policies are bound globally on the NetScaler appliance and are available for all configured GSLB
virtual servers. Even though DNS policies are globally bound, policy execution can be limited to a
specific GSLB virtual server by specifying the domain in the expression.

Note: Even though the bind dns global command accepts

REQ_OVERRIDE and
RES_OVERRIDE as valid bind points, those bind points are redundant, because DNS policies can be
bound only globally. Bind your DNS policies only to the
REQ_DEFAULT and
RES_DEFAULT bind points.

To bind a DNS policy globally by using the command line interface

At the command prompt, type the following commands to bind a DNS policy globally and verify the
configuration:

1 bind dns global <policyName> <priority> [-gotoPriorityExpression <

string>] [-type <type>]
2 show dns global -type <type>

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2305

NetScaler 12.0

1 bind dns global policy-GSLB-1 10 -gotoPriorityExpression END

2 Done
3 show dns global -type REQ_DEFAULT
4 1) Policy Name: policy-GSLB-1
5 Priority: 10
6 GotoPriorityExpression: END
7 Done

To bind a DNS policy globally by using the configuration utility

1. Navigate to Traffic Management > DNS > Policies.

2. In the details pane, click Global Bindings.
3. In the Bind/Unbind DNS Policy(s) to Global dialog box, click Insert Policy.
4. In the Policy Name column, select, from the list, the policy that you want to bind. Alternatively,
in the list, click New Policy, and then create a DNS policy by setting parameters in the Create
DNS Policy dialog box.
5. To modify a policy that is already bound globally, click the name of the policy, and then click
Modify Policy. Then, in the Configure DNS Policy dialog box, modify the policy, and then click
OK.
6. To unbind a policy, click the name of the policy, and then click Unbind Policy.
7. To modify the priority assigned to a policy, double-click the priority value, and then enter a new
value.
8. To regenerate assigned priorities, click Regenerate Priorities. The priority values are modified
to begin at 100, with increments of 10, without affecting the order of evaluation.
9. Click OK.

To view the global bindings of a DNS policy by using the command line interface

At the command prompt, type:

show dns global

To view the global bindings of a DNS policy by using the configuration utility

1. Navigate to Traffic Management > DNS > Policies.

2. In the details pane, click Global Bindings. The global bindings of all DNS policies appear in this
dialog box.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2306

NetScaler 12.0

Adding DNS Views

You can configure DNS views to identify various types of clients and provide an appropriate IP address
to a group of clients who query for the same GSLB domain. DNS views are configured by using DNS
policies that select the IP addresses sent back to the client.

For example, if you have configured GSLB for your company’s domain and have the server hosted in
your company’s network, clients querying for the domain from within your company’s internal net-
work can be provided with the server’s internal IP address instead of the public IP address. Clients
that query DNS for the domain from the Internet, on the other hand, can be provided the domain’s
public IP address.

To add a DNS view, you assign it a name of up to 31 characters. The leading character must be a number
or letter. The following characters are also allowed: @ _ - . (period) : (colon) # and space ( ). After
adding the view, you configure a policy to associate it with clients and a part of the network, and you
bind the policy globally. To configure and bind a DNS policy, see Managing Local DNS Traffic by
Using DNS Policies.

To add a DNS view by using the command line interface

At the command prompt, type the following commands to create a DNS view and verify the configura-
tion:

1 add dns view <viewName>

2 show dns view <viewName>

Example:

1 add dns view PrivateSubnet

2 show dns view PrivateSubnet

To remove a DNS view by using the command line interface

At the command prompt, type:

1 rm dns view <viewName>

To add a DNS view by using the configuration utility

Navigate to Traffic Management > DNS > Views and add a DNS view.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2307

NetScaler 12.0

For details on how to create a DNS policy and how to bind DNS policies globally, see Managing Local
DNS Traffic by Using DNS Policies.
1.
2. Citrix ADC
3. NetScaler 12.0

Configure GSLB for proximity

September 12, 2018

Contributed by:
C
When you configure GSLB for proximity, client requests are forwarded to the closest data center. The
main benefit of the proximity-based GSLB method is faster response times resulting from the selection
of the closest available data center. Such a deployment is critical for applications that require fast
access to large volumes of data.
You can configure GSLB for proximity based on the round trip time (RTT), static proximity, or a combi-
nation of the two.

Configure dynamic round trip time (RTT) method

Dynamic round trip time (RTT) is a measure of time or delay in the network between the client’s local
DNS server and a data resource. To measure dynamic RTT, the NetScaler appliance probes the client’s
local DNS server and gathers RTT metric information. The appliance then uses this metric to make its
load balancing decision. Global server load balancing monitors the real-time status of the network
and dynamically directs the client request to the data center with the lowest RTT value
To configure GSLB for proximity with dynamic method, you must first configure the basic GSLB set up
and then configure dynamic RTT.
First create two GSLB sites, local and remote. Then, for the local site, create a GSLB virtual server
and GSLB services and bind the services to the virtual server. Then create ADNS services and bind the
domain for which you are configuring GSLB to the GSLB virtual server at the local site. Finally, create
a load balancing virtual server with the same virtual server IP address as the GSLB service.
For details on how to configure a basic GSLB setup, see Configuring GSLB Entities Individually.
Once you have configured a basic GSLB setup, configure the dynamic RTT method.
For details on how to configure the GSLB virtual server to use the dynamic RTT method for load bal-
ancing, see Configuring Dynamic RTT.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2308

NetScaler 12.0

Configure static proximity

The static proximity method for GSLB uses an IP address-based static proximity database to deter-
mine the proximity between the client’s local DNS server and the GSLB sites. The NetScaler appliance
responds with the IP address of a site that best matches the proximity criteria.

If two or more GSLB sites at different geographic locations serve the same content, the NetScaler
appliance maintains a database of IP address ranges and uses the database for decisions about the
GSLB sites to which to direct incoming client requests.

To configure GSLB for proximity with static proximity, you must first configure the basic GSLB set up
and then configure static proximity.

First create two GSLB sites, local and remote. Then, for the local site, create a GSLB virtual server
and GSLB services and bind the services to the virtual server. Then create ADNS services and bind the
domain for which you are configuring GSLB to the GSLB virtual server at the local site. Finally, create
a load balancing virtual server with the same virtual server IP address as the GSLB service.

For details on how to configure a basic GSLB setup, see Configuring GSLB Entities Individually.

Once you have configured a basic GSLB setup, configure static proximity.

For details on how to configure the GSLB virtual server to use static proximity for load balancing, see
Configuring Static Proximity.

Configure static proximity and dynamic RTT

You can configure the GSLB virtual server to use a combination of static proximity and dynamic RTT
when you have some clients coming from an internal network like a branch office. You can configure
GSLB such that the clients coming from the branch office or any other internal network are directed
to a particular GSLB site that is geographically close to the client network. For all other requests, you
can use dynamic RTT.

First create two GSLB sites, local and remote. Then, for the local site, create a GSLB virtual server
and GSLB services and bind the services to the virtual server. Then create ADNS services and bind the
domain for which you are configuring GSLB to the GSLB virtual server at the local site. Finally, create
a load balancing virtual server with the same virtual server IP address as the GSLB service.

For details on how to configure a basic GSLB setup, see Configuring GSLB Entities Individually.

Once you have configured a basic GSLB setup, configure the GSLB virtual server to use static proximity
for all traffic originating from an internal network and then use dynamic RTT for all other traffic.

For details on how to configure static proximity, see Configuring Static Proximity and for details on
how to configure dynamic RTT, see Configuring Dynamic RTT.

1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2309

NetScaler 12.0

2. Citrix ADC
3. NetScaler 12.0

Protect the GSLB setup against failure

September 12, 2018

Contributed by:
C

You can protect your GSLB setup against failure of a GSLB site or a GSLB virtual server by configur-
ing a backup GSLB virtual server, configuring the NetScaler appliance to respond with multiple IP
addresses, or configuring a Backup IP address for a GSLB domain. You can also divert excess traffic to
a backup virtual server by using spillover.

Configure a backup GSLB virtual server

Configuring a backup entity for a GSLB virtual server ensures that DNS traffic to a site is not interrupted
if the GSLB virtual server goes down. The backup entity can be another GSLB virtual server, or it can be
a backup IP address. With a backup entity configured, if the primary GSLB virtual server goes down,
the backup entity handles DNS requests. To specify what should happen when the primary GSLB
virtual server comes back up again, you can configure the backup entity to continue handling traffic
until you manually enable the primary virtual server to take over (using the disablePrimaryOnDown
option), or you can configure a timeout period after which the primary takes over.

Note: You can configure a single backup entity as a backup for multiple GSLB virtual server.

If you configure both the timeout and the disablePrimaryOnDown option for the backup entity, the
backup session time-out takes precedence over the disablePrimaryOnDown setting.

To configure a backup GSLB virtual server by using the command line interface

At the command prompt, type the following commands to configure a GSLB virtual server as a backup
virtual server and verify the configuration:

1 set gslb vserver <name> -backupVServer <name> [-backupSessionTimeout <

timeoutValue>] [-disablePrimaryOnDown (ENABLED | DISABLED)]
2
3 show gslb vserver <name>

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2310

NetScaler 12.0

1 set gslb vserver vserver-GSLB-1 -backupVServer vserver-GSLB-2 -

backupSessionTimeout 3 -disablePrimaryOnDown ENABLED
2 show gslb vserver vserver-GSLB-1

To set GSLB virtual server as a backup virtual server by using the configuration utility

1. Navigate to Traffic Management > GSLB > Virtual Servers, and double-click the GSLB virtual
server.
2. Click the Backup Virtual Server section and select the backup virtual server.

Configure a GSLB setup to respond with multiple IP addresses

A typical DNS response contains the IP address of the best performing GSLB service. However, if you
enable multiple IP response (MIR), the NetScaler appliance sends the best GSLB service as the first
record in the response and adds the remaining active services as additional records. If MIR is disabled
(the default), the NetScaler appliance sends the best service as the only record in the response.

To configure a GSLB virtual server for multiple IP responses by using the command line
interface

At the command prompt, type the following commands to configure a GSLB virtual server for multiple
IP responses and verify the configuration:

1 set gslb vserver<name> -MIR (ENABLED | DISABLED)

2 - show gslb vserver <name>

Example:

1 set gslb vserver vserver-GSLB-1 -MIR ENABLED

2 show gslb vserver <vserverName>

To set a GSLB virtual server for multiple IP responses by using the configuration utility

1. Navigate to Traffic Management > GSLB > Virtual Servers and double-click the GSLB virtual
server for which you want to configure a backup virtual server (for example, vserver-GSLB-1).
2. On the Advanced tab, under When this VServer is “UP,” select the Send all “active” service IP in
response (MIR) check box, and click OK.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2311

NetScaler 12.0

Configuring a GSLB Virtual Server to Respond with an Empty Address Record When
DOWN

A DNS response can contain either the IP address of the requested domain or an answer stating that
the IP address for the domain is not known by the DNS server, in which case the query is forwarded
to another name server. These are the only possible responses to a DNS query.

When a GSLB virtual server is disabled or in a DOWN state, the response to a DNS query for the GSLB
domain bound to that virtual server contains the IP addresses of all the services bound to the virtual
server. However, you can configure the GSLB virtual server to in this case send an empty down re-
sponse (EDR). When this option is set, a DNS response from a GSLB virtual server that is in a DOWN
state does not contain IP address records, but the response code is successful. This prevents clients
from attempting to connect to GSLB sites that are down.

Note: You must configure this setting for each virtual server to which you want it to apply.

To configure a GSLB virtual server for empty down responses by using the command line
interface

At the command prompt, type:

1 set gslb vserver<name> -EDR (ENABLED | DISABLED)

Example:

1 > set gslb vserver vserver-GSLB-1 -EDR ENABLED

2 Done

To set a GSLB virtual server for empty down responses by using the configuration utility

1. Navigate to Traffic Management > GSLB > Virtual Servers and double-click the GSLB virtual
server for which you want to configure a backup virtual server (for example, vserver-GSLB-1).
2. On the Advanced tab, under When this VServer is “Down,” select the Do not send any service’s
IP address in response (EDR) check box.
3. Click OK.

Configure a backup IP address for a GSLB domain

You can configure a backup site for your GSLB configuration. With this configuration in place, if all of
the primary sites go DOWN, the IP address of the backup site is provided in the DNS response.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2312

NetScaler 12.0

Typically, if a GSLB virtual server is active, that virtual server sends a DNS response with one of the
active site IP addresses as selected by the configured GSLB method. If all the configured primary sites
in the GSLB virtual server are inactive (in the DOWN state), the authoritative domain name system
(ADNS) server or DNS server sends a DNS response with the backup site’s IP address.

Note: When a backup IP address is sent, persistence is not honored.

To set a backup IP address for a domain by using the command line interface

At the command prompt, type the following commands to set a backup IP address and verify the con-
figuration:

1 set gslb vserver <name> -domainName <string> -backupIP <IPAddress>

2 show gslb vserver <name>

Example:

1 set gslb vserver vserver-GSLB-1 -domainName www.abc.com -backupIP

10.102.29.66
2 show gslb vserver vserver-GSLB-1

To set a backup IP address for a domain by using the configuration utility

1. Navigate to Traffic Management > GSLB > Virtual Servers and double-click the GSLB virtual
server to which you want to bind the backup domain (for example, vserver-GSLB-1).
2. Click the Domains section, configure the GSLB domain and specify the IP address of the backup
domain in the Backup IP field.

Divert excess traffic to a backup virtual server

Once the number of connections to a primary GSLB virtual server exceeds the configured threshold
value, you can use the spillover option to divert new connections to a backup GSLB virtual server. This
threshold value can be calculated dynamically or set manually. Once the number of connections to
the primary virtual server drops below the threshold, the primary GSLB virtual server resumes serving
client requests.

You can configure persistence with spillover. When persistence is configured, new clients are diverted
to the backup virtual server if that client is not already connected to a primary virtual server. When
persistence is configured, connections that were diverted to the backup virtual server are not moved
back to the primary virtual server after the number of connections to the primary virtual server drops

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2313

NetScaler 12.0

below the threshold. Instead, the backup virtual server continues to process those connections until
they are terminated by the user. Meanwhile, the primary virtual server accepts new clients.

The threshold can be measured either by the number of connections or by the bandwidth.

If the backup virtual server reaches the configured threshold and is unable to take any additional load,
the primary virtual server diverts all requests to the designated redirect URL. If a redirect URL is not
configured on the primary virtual server, subsequent requests are dropped.

The spillover feature prevents the remote backup GSLB service (backup GSLB site) from getting
flooded with client requests when the primary GSLB virtual server fails. This occurs when a monitor
is bound to a remote GSLB service, and the service experiences a failure that causes its state to go
DOWN. The monitor continues to keep the state of the remote GSLB service UP, however, because of
the spillover feature.

As part of the resolution to this problem, two states are maintained for a GSLB service, the primary
state and effective state. The primary state is the state of the primary virtual server and the effective
state is the cumulative state of the virtual servers (primary and backup chain). The effective state is
set to UP if any of the virtual servers in the chain of virtual servers is UP. A flag that indicates that the
primary VIP has reached the threshold is also provided. The threshold can be measured by either the
number of connections or the bandwidth.

A service is considered for GSLB only if its primary state is UP. Traffic is directed to the backup GSLB
service only when all the primary virtual servers are DOWN. Typically, such deployments will have
only one backup GSLB service.

Adding primary and effective states to a GSLB service has the following effects:

• When source IP persistence is configured, the local DNS is directed to the previously selected site
only if the primary virtual server on the selected site is UP and below threshold. Persistence can
be ignored in the round robin mode.
• If cookie-based persistence is configured, client requests are redirected only when the primary
virtual server on the selected site is UP.
• If the primary virtual server has reached its saturation and the backup VIP(s) is absent or down,
the effective state is set to DOWN.
• If external monitors are bound to an HTTP-HTTPS virtual server, the monitor decides the pri-
mary state.
• If there is no backup virtual server to the primary virtual server and the primary virtual server
has reached its threshold, the effective state is set to DOWN.

To configure a backup GSLB virtual server by using the command line interface

At the command prompt, type the following commands to configure a backup GSLB virtual server and
verify the configuration:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2314

NetScaler 12.0

1 set gslb vserver <name> -soMethod <method> -soThreshold <threshold> -

soPersistence ( **ENABLED** | **DISABLED** ) -soPersistenceTimeout <
timeout>
2 show gslb vserver <name>

Example:

1 set gslb vserver Vserver-GSLB-1 -soMethod CONNECTION -soThreshold 1000

-soPersistence ENABLED -soPersistenceTimeout 2
2 show gslb vserver Vserver-GSLB-1

To configure a backup GSLB virtual server by using the configuration utility

1. Navigate to Traffic Management > GSLB > Virtual Servers and double-click the virtual server
that you want to configure as a backup (for example, Vserver-LB-1).
2. Click the SpillOver section and set the following parameters:
• Method— soMethod
• Threshold— soThreshold
• Persistence Time-out (min) — soPersistenceTimeout
3. Select the Persistence option and click OK.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure GSLB for disaster recovery

September 12, 2018

Contributed by:
C

Disaster recovery capability is critical, because downtime is costly. A NetScaler appliance configured
for GSLB forwards traffic to the least-loaded or the best-performing data center. This configuration,
referred to as an active-active setup, not only improves performance, but also provides immediate
disaster recovery by routing traffic to other data centers if a data center that is part of the setup goes
down. Alternatively, you can configure an active-standby GSLB setup for disaster recovery only.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2315

NetScaler 12.0

Configure GSLB for disaster recovery in an active-standby data center setup

A conventional disaster recovery setup includes an active data center and a standby data center. The
standby data center is a remote site. When a failover occurs as a result of a disaster event that causes
the primary active data center to be inactive, the standby data center becomes operational.

Configuring disaster recovery in an active-standby data-center setup consists of the following tasks.

• Create the active data center.

– Add a local GSLB site.
– Add a GSLB vserver, which represents the active data center.
– Bind the domain to the GSLB virtual server.
– Add gslb services and bind the services to active GSLB virtual server.
• Create the standby data center.
– Add a remote gslb site.
– Add a gslb vserver, which represents standby data center.
– Add gslb services which represents standby data center and bind the services to the
standby gslb vserver.
– Designate the standby data center by configuring the standby GSLB virtual server as the
backup virtual server for the active GSLB virtual server.

Once you have configured the primary data center, replicate the configuration for the backup data
center and designate it as the standby GSLB site by designating a GSLB virtual server at that site as
the backup virtual server.

For details on how to configure a basic GSLB setup, see Configuring GSLB Entities Individually.

To designate the standby GSLB site by using the command line interface

At both the active site and the remote site, at the command prompt, type:

1 set gslb vserver <name> -backupVserver <string>

Example:

1 set gslb vserver vserver-GSLB-1 -backupVServer vserver-GSLB-2

To configure the standby site by using the configuration utility

1. Navigate to Traffic Management > GSLB > Virtual Servers and double-click the GSLB virtual
server for the primary site.
2. Click the Backup Virtual Server section and select a backup virtual server.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2316

NetScaler 12.0

By default, once the primary virtual server becomes active, it starts receiving traffic. However, if you
want the traffic to be directed to the backup virtual server even after the primary virtual server be-
comes active, use the
‘disable primary on down’ option.

Configure for disaster recovery in an active-active data center setup

An active-active GSLB deployment, in which both GSLB sites are active, removes any risk that may
arise in having a standby data center. With such a setup, web or application content can be mirrored in
geographically separate locations. This ensures that data is consistently available at each distributed
data center.

To configure GSLB for disaster recovery in an active-active data center set up, you must first configure
the basic GSLB setup on the first data center and then configure all other data centers.

First create at least two GSLB sites. Then, for the local site, create a GSLB virtual server and GSLB
services and bind the services to the virtual server. Then create ADNS services and bind the domain
for which you are configuring GSLB to the GSLB virtual server in the local site. Finally, at the local site,
create a load balancing virtual server with the same virtual server IP address as the GSLB service.

Once you have configured the first data center, replicate the configuration for other data centers part
of the setup.

For details on how to configure a basic GSLB setup, see Configuring GSLB Entities Individually.

Configuring for Disaster Recovery with Weighted Round Robin

When you configure GSLB to use the weighted round robin method, weights are added to the GSLB
services and the configured percentage of incoming traffic is sent to each GSLB site. For example, you
can configure your GSLB setup to forward 80 percent of the traffic to one site and 20 percent of the
traffic to another. After you do this, the NetScaler appliance will send four requests to the first site for
each request that it sends to the second.

To set up the weighted round robin method, first create two GSLB sites, local and remote. Next, for the
local site create a GSLB virtual server and GSLB services, and bind the services to the virtual server.
Configure the GSLB method as round robin. Next, create ADNS services and bind the domain for which
you are configuring GSLB to the GSLB virtual server. Finally, create a load balancing virtual server with
the same virtual server IP address as the GSLB service.

Each service that represents a physical server in the network has weights associated with it. Therefore
the GSLB service is assigned a dynamic weight that is the sum of weights of all services bound to
it. Traffic is then split between the GSLB services based on the ratio of the dynamic weight of the

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2317

NetScaler 12.0

particular service to the total weight. You can also configure individual weights for each GSLB service
instead of the dynamic weight.

If the services do not have weights associated with them, you can configure the GSLB virtual server to
use the number of services bound to it to calculate the weight dynamically.

For details on how to configure a basic GSLB setup, see Configuring GSLB Entities Individually.

Once you configure a basic GSLB setup, you must configure the weighted round robin method such
that the traffic is split between the configured GSLB sites according to the weights configured for the
individual services.

To configure a virtual server to assign weights to services by using the command line interface

At the command prompt, type one of the following commands, depending upon whether you want to
create a new load balancing virtual server or configure an existing one:

1 add lb vserver <name>@ -weight <WeightValue> <ServiceName>

2 set lb vserver <name>@ -weight <WeightValue> <ServiceName>

Example:

1 add lb vserver Vserver-LB-1 -weight 4 Service-HTTP-1

2 set lb vserver Vserver-LB-1 -weight 4 Service-HTTP-1

To set dynamic weight by using the command line interface

At the command prompt, type:

1 set gslb vserver <name> -dynamicWeight DynamicWeightType

Example:

1 set gslb vserver Vserver-GSLB-1 -dynamicWeight ServiceWeight

To add weights to the GSLB services by using the command line interface

At the command prompt, type:

1 set gslb vserver <name> -serviceName GSLBServiceName -weight

WeightValue

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2318

NetScaler 12.0

1 set gslb vserver Vserver-GSLB-1 -serviceName Service-GSLB-1 -weight 1

To configure a virtual server to assign weights to services by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Virtual Servers and double-click the virtual
server (for example, Vserver-LB-1).
2. Click the Services section and set the weight of a service.

To add weights to the GSLB services by using the configuration utility

1. Navigate to Traffic Management > GSLB > Virtual Servers and double-click the virtual server (for
example, vserver-GSLB-1)
2. Click the Services section and set the weight of the service in the Weight field.

To set dynamic weight by using the configuration utility

1. Navigate to Traffic Management > GSLB > Virtual Servers and double-click the virtual server (for
example, vserver-GSLB-1).
2. Click the Method section and, from the Dynamic Weight drop-down list select SER-
VICEWEIGHT.

Configuring for Disaster Recovery with Data Center Persistence

Data center persistence is required for web applications that require maintaining a connection with
the same server instead of having the requests load balanced. For example, in an e-commerce portal,
maintaining a connection between the client and the same server is critical. For such applications,
HTTP redirect persistence can be configured in an active-active setup.

To configure GSLB for disaster recovery with data center persistence, you must first configure the basic
GSLB set up and then configure HTTP redirect persistence.

First create two GSLB sites, local and remote. Next, for the local site, create a GSLB virtual server and
GSLB services and bind the services to the virtual server. Next, create ADNS services and bind the
domain for which you are configuring GSLB to the GSLB virtual server at the local site. Next, create
a load balancing virtual server with the same virtual server IP address as the GSLB service. Finally,
duplicate the previous steps for the remote configuration, or configure the NetScaler appliance to
autosynchronize your GSLB configuration.

For details on how to configure a basic GSLB setup, see Configuring GSLB Entities Individually.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2319

NetScaler 12.0

Once you have configured a basic GSLB setup, configure HTTP redirect precedence to enable data
center persistence.

To configure HTTP redirect by using the command line interface

At the command prompt, type the following commands to configure HTTP redirect and verify the con-
figuration:

1 set gslb service <serviceName> -sitePersistence <sitePersistence> -

sitePrefix <string>
2 show gslb service <serviceName>

Example:

1 set gslb service Service-GSLB-1 -sitePersistence HTTPRedirect -

sitePrefix vserver-GSLB-1
2 show gslb service Service-GSLB-1

To configure HTTP redirect by using the configuration utility

1. Navigate to Traffic Management > GSLB > Services and double-click the GSLB service to be con-
figured.
2. Click the Site Persistence section, select the HTTPRedirect option, and in the Site Prefix text
box, enter the site prefix (for example, vserver-GSLB-1).
Note

When site persistence is not configured and if a load balancing virtual server that is configured as
a local GSLB service is DOWN, the HTTP requests are redirected to other healthy GSLB sites using
a 302 redirect.

1.
2. Citrix ADC
3. NetScaler 12.0

Override static proximity behavior by configuring preferred locations

September 12, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2320

NetScaler 12.0

You might want to direct traffic from a local DNS (LDNS) server or network to a GSLB service other than
the GSLB service that the static proximity method selects for that traffic. That is, you have a
preferred location for that traffic. To override the static proximity method with preferred locations,
you can do the following:

1. Configure a DNS action that consists of a list of preferred locations. For more information about
configuring a DNS action, see Configuring a DNS Action.
2. Configure a DNS policy to identify the traffic arriving from the LDNS server or network for which
you want to override static proximity, and apply the action in the policy.
3. Bind the policy to the global request bind point.

In the DNS action, you can configure a list of up to 8 preferred locations. The locations must be pro-
vided in the dotted qualifier notation, which is the notation in which you add custom locations to the
static proximity database. The locations can include wildcards for qualifiers that you want to omit. For
information about the dotted qualifier notation for locations, see Adding Custom Entries to a Static
Proximity Database. When entering the preferred locations, you must enter them in the descending
order of priority.

When a policy evaluates to

TRUE, the NetScaler appliance matches the preferred locations, in priority order, with the locations of
GSLB services. Matches are of the following two types:

• If all the non-wildcard qualifiers in a preferred location match the corresponding qualifiers in
the location of a GSLB service, the match is considered a perfect match. For example, a GSLB
service location of .UK..* or Europe.UK.. is a perfect match for the preferred location .UK..*.
• If only a subset of the non-wildcard qualifiers match, the match is considered a partial match.
For example, a GSLB service location of Europe.EG is a partial match for the preferred location
Europe.UK.

When a DNS policy evaluates to

TRUE, the following algorithm is used to select a GSLB service:

1. The appliance evaluates the preferred location that has the highest priority and moves down
the priority order until a perfect match is found between a preferred location and the location
of a GSLB service.

If a perfect match is found, the appliance checks whether the corresponding GSLB service is
up. If it is up, it returns the IP address of the GSLB service in the DNS response. If multiple per-
fect matches are found (which can happen when one or more wildcards are used in a preferred
location), the appliance checks the state of each of the corresponding GSLB services and load
balances the GSLB services that are up.

2. If a perfect match is not found for any of the preferred locations, the appliance returns to the
preferred location that has the highest priority and moves down the priority order until a partial
match is found between a preferred location and the location of a GSLB service.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2321

NetScaler 12.0

If a partial match is found, the appliance checks whether the corresponding GSLB service is up.
If it is up, it returns the IP address of the GSLB service in the DNS response. If multiple partial
matches are found, the appliance checks the state of each of the corresponding GSLB services
and load balances the GSLB services that are up.

3. If none of the perfect and partial matches are up, the appliance load balances all other available
GSLB services.

In this way, the appliance implements a type of site affinity for traffic that matches the DNS
policy.

Example

Consider a GSLB configuration that consists of the following eight GSLB services:

• Asia.IN
• Asia.JPN
• Asia.HK
• Europe.UK
• Europe.RU
• Europe.EG
• Africa.SD
• Africa.ZMB

Further consider the following DNS action and policy configuration:

1 > add dns action prefLoc11 GslbPrefLoc -preferredLocList ”Asia.HK” ”

Europe.UK”
2 Done
3 > add dns policy dnsPolPrefLoc ”CLIENT.IP.SRC.MATCHES_LOCATION(”*.ZMB
.*.*”)” prefLoc11
4 Done

When the appliance receives a request from the location

.ZMB..*, the preferred locations are evaluated as follows:

1. The appliance attempts to find a GSLB service whose location is a perfect match for Asia.HK,
which is the preferred location that has the highest priority. It finds that the GSLB service at
Asia.HK is a perfect match. If the GSLB service is up, it sends the client the IP address of the
GSLB service.
2. If the GSLB service at Asia.HK is down, the appliance attempts to find a perfect match for the
second preferred location, Europe.UK. It finds that the GSLB service at Europe.UK is a perfect
match. If the GSLB service is up, it sends the client the IP address of the service.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2322

NetScaler 12.0

3. If the GSLB service at Europe.UK is down, it returns to the preferred location that has the highest
priority, Asia.HK, and looks for partial matches. For Asia.HK, it finds that Asia.IN and Asia.JPN
are partial matches. If only one of the corresponding GSLB services is up, it sends the client the
IP address of the service. If both locations are up, it load balances the two services.
4. If all partial matches for Asia.HK are down, the appliance looks for partial matches for Eu-
rope.UK. It finds that Europe.RU and Europe.EG are partial matches for the preferred location.
If only one of the corresponding GSLB services is up, it sends the client the IP address of the
service. If both locations are up, it load balances the two services.
5. If all partial matches for Europe.UK are down, the appliance load balances all other available
GSLB services. In the current example, the appliance load balances Africa.SD and Africa.ZMB
because the remaining six GSLB services have been found to be down.

1.
2. Citrix ADC
3. NetScaler 12.0

Configure GSLB service selection using content switching

September 12, 2018

Contributed by:
C

In a typical GSLB deployment, you can prioritize the selection of a set of GSLB services bound to a
GSLB virtual server, but you cannot do the following:

• Restrict the selection of a GSLB service from a subset of GSLB services bound to a GSLB virtual
server for the given domain.
• Apply different load balancing methods on the different subsets of GSLB services in the deploy-
ment.
• Apply spillover policies on a subset of GSLB services, and you cannot have a backup for a subset
of GSLB services.
• Configure a subset of GSLB services to serve different content. That is, you cannot content
switch between servers in different GSLB sites. The GSLB configuration assumes that the
servers contain the same content.
• Define a subset GSLB services with different priorities and specify an order in which the services
in the subset are applied to a request.

You can now configure a content switching (CS) policy to customize the GSLB deployment. First con-
figure a set of GSLB services and bind it to a GSLB virtual server. Then, configure a CS virtual server

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2323

NetScaler 12.0

of target type GSLB, define a CS policy and action with the GSLB virtual server as target virtual server,
and bind the CS policy to CS virtual server.
Important

• Only CS policies with DNS based expressions can be bound to a CS virtual server of target
type GSLB.
• If a GLSB service is bound to a CS virtual server through a GSLB virtual server, you cannot
bind another GSLB virtual server bound with the same GSLB service to the CS virtual server.

Example
Consider a GLSB deployment that includes two GSLB sites. At each site, four GSLB services (S-1, S-2,
S-3, and S-4) are bound to GSLB virtual server VS-1. You can configure a content switching (CS) virtual
server of target type GSLB and define a CS policy and action with VS-1 as the target virtual server, so
that requests for content in English are served only by S-1 and S-2, and requests for content in the
local language are served only by S-3 and S-4.

You could give S-1 priority by configuring a backup virtual server to VS-1 and binding S-2 to the backup
virtual server. Client requests would then be served by S-1 unless the server it represents went down,
in which case the requests would be served by S-2. If both S-1 and S-2 were down, clients would receive
an empty response.

To configure GSLB Service Selection using Content Switching:

1. Configure GSLB. For instructions, see Configuring Global Server Load Balancing.
2. Configure a Content Switching (CS) virtual server of target type GSLB. For more information, see
Creating Content Switching Virtual Servers..
3. Configure Content Switching (CS) policies. For more information, see Configuring Content
Switching Policies.
4. Configure CS actions that designate a GSLB virtual server as the target virtual server. For more
information, see Configuring a Content Switching Action.
5. Bind the CS policies to the CS virtual server. For more information, see Binding Policies to a
Content Switching Virtual Server.
6. Bind the domain to the CS virtual server instead of the GSLB virtual server.

Sample Configuration

The following sample configuration sends requests from the client with IP address 5.5.5.5 to SER-
VICE_GSLB1 and SERVICE_GSLB2. SERVICE_GSLB1 has a higher priority than SERVICE_GSLB2, and
SERVICE_GSLB2 serves the client requests only when SERVICE_GSLB1 is down. If both SERVICE_GSLB1
and SERVICE_GSLB2 are down, SERVICE_GSLB3 and service-GSLB4 are not considered, and a blank
response is sent to the client.

1 add cs vs CSVSERVER_GSLB http ‒ targettype GSLB

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2324

NetScaler 12.0

2 Done
3 add gslb vs VSERVER_GSLB1 http
4 Done
5 add gslb vs VSERVER_GSLB2 http
6 Done
7 add gslb vs VSERVER_GSLB_BACKUP1 http
8 Done
9 set gslb vs VSERVER_GSLB1 -backupvserver VSERVER_GSLB_BACKUP1
10 Done
11 add gslb service SERVICE_GSLB1 1.1.1.1 HTTP 80 -sitename site1
12 Done
13 add gslb service SERVICE_GSLB2 1.1.1.2 HTTP 80 -sitename site1
14 Done
15 add gslb service SERVICE_GSLB3 1.1.1.3 HTTP 80 -sitename site2
16 Done
17 add gslb service SERVICE_GSLB4 1.1.1.4 HTTP 80 -sitename site2
18 Done
19 bind gslb vs VSERVER_GSLB1 -servicename SERVICE_GSLB1
20 Done
21 bind gslb vs VSERVER_GSLB_BACKUP1 -servicename SERVICE_GSLB2
22 Done
23 bind gslb vs VSERVER_GSLB2 -servicename SERVICE_GSLB3
24 Done
25 bind gslb vs VSERVER_GSLB2 -servicename SERVICE_GSLB4
26 Done
27 add cs action a1 -targetvserver VSERVER_GSLB1
28 Done
29 add cs policy p1 -rule ”CLIENT.IP.SRC.EQ(5.5.5.5)” -action a1
30 Done
31 bind cs vs CSVSERVER_GSLB -domainName www.abc.com
32 Done
33 bind cs vs CSVSERVER_GSLB -policyname p1 -priority 1
34 Done
35 add cs action a2 -targetvserver VSERVER_GSLB2
36 Done
37 add cs policy p2 -rule ”CLIENT.IP.SRC.EQ(6.6.6.6)” -action a2
38 Done
39 bind cs vs CSVSERVER_GSLB -policyname p2 -priority 2
40 Done

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2325

NetScaler 12.0

Configure GSLB for DNS queries with NAPTR records

September 12, 2018

Contributed by:
C

In a typical Global Server Load Balancing (GSLB) deployment, the NetScaler appliance receives DNS
queries for A/AAAA records, selects the most appropriate GSLB service according to the configured
load balancing method, and returns the service’s IP address as a reply to the DNS query. You can now
configure the appliance to receive DNS queries for NAPTR records and respond with the list of services
configured for a domain. The appliance also monitors the health of the services, and in the response
it provides a list of only the services that are up.

Example:

In Telco deployments, you can configure a NetScaler appliance to receive DNS queries with NAPTR
records from clients such as mobile management entities (MMEs), which play the role of a DNS resolver
to discover all the services that are offered by the domain name. The appliance responds to the query
with NAPTR records for all the services that are up. The MME can use this NAPTR response to run the
S-NAPTR procedure to select the nodes on the basis of the service offered, colocation, topological
closeness, and so on.

If multiple nodes qualify for selection, the MME can use the preference field in the NAPTR record from
the NetScaler appliance to determine the node.

NAPTR Record Format

While responding to a DNS query with NAPTR record, a NetScaler appliance constructs a response
NAPTR record for each GSLB service.

The following table lists the files in the NAPTR record:

Field

Domain The GSLB domain

TTL The amount of time for which the NAPTR
record can be cached.
Class The class of the record. By default, this value is
set to IN.
Type The DNS record type.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2326

NetScaler 12.0

Field

Order Specifies the order in which the NAPTR record

MUST be processed. You can specify the order
in the GSLB service. Otherwise, it is set to 1.
Preference Specifies the order in which NAPTR records
with equal “order” values SHOULD be
processed, low numbers being processed
before high numbers. If the order is not
specified in the GSLB service, it is set to 1.
Flags Controls the aspects of the rewriting and
interpretation of the fields in the record. The
NetScaler appliance sets this value to A.
Service Specifies the available service(s).
Regular Expression Regular expressions are not supported, so this
value is set to NULL.
Replacement The domain name of the node that hosts the
services.

Configuration procedure

For detailed GSLB configuration instructions, see Configuring Global Server Load Balancing (GSLB).
Make sure that you do the following:

• Set the following parameters while adding the GSLB virtual server:
– serviceType: ANY
– dnsRecordType: NAPTR
– lbMethod: CUSTOMLOAD

Example:

1 add gslb vserver gslb_vs ANY -dnsRecordType NAPTR -lbMethod CUSTOMLOAD

• While adding a GSLB site, set the naptrReplacementSuffix parameter to the domain name that
you want to embed in the NAPTR records.

Example:

1 add gslb site site1 10.102.218.200  -naptrReplacementSuffix example.com

• Set the following parameters while adding the GSLB service:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2327

NetScaler 12.0

– naptrreplacement
– naptrOrder
– naptrServices
– naptrDomainTTL
– naptrPreference

Sample configuration

1 add gslb vserver gslb_vs ANY -dnsRecordType NAPTR -lbMethod CUSTOMLOAD

2
3 Done
4
5 add gslb site site1 10.102.218.200 -naptrReplacementSuffix example.com
6
7 Done
8
9 add gslb service sgw1 3.3.3.13 ANY * -siteName site1 -naptrreplacement
sgw1.site1. -naptrOrder 2 -naptrServices x-3gpp-sgw:x-s5-gtp -
naptrDomainTTL 20 -naptrPreference 200
10
11 Done
12
13 add gslb service sgw2 3.3.3.11 ANY * -siteName site1 -naptrreplacement
sgw2.site1. -naptrOrder 5 -naptrServices x-3gpp-sgw:x-s5-gtp -
naptrDomainTTL 20 naptrPreference 100
14
15 Done
16
17 add gslb service sgw3 3.3.3.12 ANY * -siteName site2 -naptrreplacement
sgw3.site1. -naptrOrder 10 -naptrServices x-3gpp-sgw:x-s5-gtp -
naptrDomainTTL 20 naptrPreference 300
18
19 bind gslb vserver gslb_vs -serviceName sgw1
20
21 Done
22
23 bind gslb vserver gslb_vs -serviceName sgw2
24
25 Done
26
27 bind gslb vserver gslb_vs -serviceName sgw3
28
29 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2328

NetScaler 12.0

30
31 bind gslb service sgw1 -monitorName ping
32
33 Done
34
35 bind gslb service sgw2 -monitorName ping
36
37 Done
38
39 bind gslb service sgw3 -monitorName ping
40
41 Done
42
43 bind gslb vserver gslb_vs -domainName gslb.com -TTL 5
44
45 Done

Note

DNS queries with NAPTR records are not supported in parent-child configuration.

1.
2. Citrix ADC
3. NetScaler 12.0

Use the EDNS0 client subnet option for GSLB

January 6, 2019

Contributed by:
C

EDNS Client Subnet (ECS) is a DNS header extension that provides the client subnet details. You can
use these details to improve the accuracy of NetScaler Global Server Load Balancing (GSLB) by using
the client network location rather than the DNS resolver location to determine the topological close-
ness of the client.
Note

NetScaler supports only EDNS0.

Important:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2329

NetScaler 12.0

Make sure that the LDNS in your deployment supports EDNS0 Client Subnet so that the incoming
DNS queries contains the EDNS0 Client Subnet option and the NetScaler appliance uses the ECS
address while processing the DNS query.

In a typical GSLB deployment, when you use proximity-based load balancing methods like static prox-
imity or dynamic round-trip time (RTT), the NetScaler appliance uses the local DNS (LDNS) IP ad-
dress for determining the topological closeness of the client and performs GSLB accordingly. But
when a centralized DNS resolver, such as Google DNS or OpenDNS, is involved in the deployment,
the NetScaler appliance sends the DNS request to a datacenter close to the centralized DNS resolver,
which might not be close to the client. For example, in a typical NetScaler GSLB deployment using
the static proximity load balancing method, an end-user request from Japan is sent to a datacenter in
Japan and an end user request from California is sent to a datacenter in California. But if a centralized
DNS resolver is involved, the NetScaler appliance might send a request from Japan to a datacenter in
California.

You can use the ECS option in deployments that include the NetScaler appliance configured as Au-
thoritative DNS (ADNS) server for a GSLB domain. If you use static proximity as the load balancing
method, you can use the IP subnet in the EDNS header instead of the LDNS IP address to determine
the geographical proximity of the client. In the case of proxy mode deployment, the NetScaler appli-
ance forwards an ECS-enabled DNS query as-is to the back-end servers, and the appliance does not
cache ECS-enabled DNS responses.

Note

The ECS option is not applicable for all other deployment modes, such as ADNS mode for non-
GSLB domains, resolver mode, and forwarder mode. In all these modes, the ECS option is ig-
nored by the NetScaler appliance. Also, by default, ECS is disabled for GSLB deployment.

To enable EDNS0 Client Subnet option by using the command line interface:

At the command prompt, type:

1 set gslb vserver <vserver_name> **-ECS ENABLED

2
3 set gslb vserver vserver-GSLB-1 -ECS ENABLED

Address validation

You can configure a GSLB virtual server to verify that the address returned by the EDNS0 Client Subnet
(ECS) option of the DNS query is not a private or an unroutable IP address. With address validation
enabled, the NetScaler appliance ignores the ECS address in the DNS query if it is listed in the following
table, and instead uses the LDNS IP address for global server load balancing.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2330

NetScaler 12.0

Note

By default, address validation is disabled.

Address Type Address Description

IPV4 10.0.0.0/8 For private use
172.16.0.0/12 For private use
192.168.0.0/16 For private use
0.0.0.0/8 Refers to the host on the
network
100.64.0.0/10 Shared address space
127.0.0.0/8 Loopback address
169.254.0.0/16 Link Local IPv4 address as
defined in RFC 3927
192.0.0.0/24 Used for IETF protocol
assignments, includes the
private space 192.168.0.0/16
192.0.2.0/24 Used for documentation
purposes
192.88.99.0/24 Used for 6to4 Relay Anycast
198.18.0.0/15 Used in Device benchmark
testing
198.51.100.0/24 Used for documentation
purposes
203.0.113.0/24 Used for documentation
purposes
240.0.0.0/4 Used as reserved
255.255.255.255/32 Used for broadcast

IPv6 ::1/128 loopback address

::/128 unspecified address
::ffff:0:0/96 IPv4-mapped address
100::/64 discard-only address block

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2331

NetScaler 12.0

2001::/23 Used for IETF protocol

assignments
2001::/32 TEREDO
2001:2::/48 Used for benchmarking
2001:db8::/32 Used for documentation
purposes
2001:10::/28 ORCHID
2002::/16 Used for 6to4 Relay Anycast
fc00::/7 Unique-local
fe80::/10 Link-local Unicast addresses

To enable address validation by using the command line interface

At the command prompt, type:

1 set gslb vserver <vserver_name> -ecsAddressValidation ENABLED

2
3 set gslb vserver vserver-GSLB-1 -ecsAddressValidation ENABLED

1.
2. Citrix ADC
3. NetScaler 12.0

Example of a complete parent-child configuration using the metrics

exchange protocol

January 6, 2019

Contributed by:
C

Consider the following parent-child topology in which the GSLB sites are distributed globally.

• Site1 and Site2 are the parent sites.

• Site1_child1 and Site1_child2 are the child sites of Site1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2332

NetScaler 12.0

• Site2_child1 and Site2_child2 are the child sites of Site2.

The following commands illustrate the complete configuration of the parent-child topology.

site1

1 add gslb site site1 10.102.82.164 -publicIP 10.102.82.164

2
3 add gslb site site2 10.106.24.164 -publicIP 10.106.24.164
4
5 add gslb site site1_child1 10.102.82.131 -publicIP 10.102.82.131 -
nwMetricExchange DISABLED -sessionExchange DISABLED -parentSite
site1
6
7 add gslb site site1_child2 10.102.82.67 -publicIP 10.102.82.67 -
nwMetricExchange DISABLED -sessionExchange DISABLED -parentSite
site1
8
9 add gslb site site2_child1 10.106.24.132 -publicIP 10.106.24.132 -
nwMetricExchange DISABLED -sessionExchange DISABLED -parentSite
site2
10
11 add gslb site site2_child2 10.106.24.67 -publicIP 10.106.24.67 -
nwMetricExchange DISABLED -sessionExchange DISABLED -parentSite
site2
12
13 add gslb service site1_child1_http_gsvc1 10.102.82.132 HTTP 80 -
publicIP 10.102.82.132 -publicPort 80 -maxClient 0 -siteName
site1_child1 -cltTimeout 180 -svrTimeout 360 -downStateFlush ENABLED
14
15 add gslb service site1_child2_http_gsvc1 10.102.82.68 HTTP 80 -publicIP
10.102.82.68 -publicPort 80 -maxClient 0 -siteName site1_child2 -
cltTimeout 180 -svrTimeout 360 -downStateFlush ENABLED
16
17 add gslb service site2_child1_http_gsvc1 10.106.24.134 HTTP 80 -
publicIP 10.106.24.134 -publicPort 80 -maxClient 0 -siteName
site2_child1 -cltTimeout 180 -svrTimeout 360 -downStateFlush ENABLED
18
19 add gslb service site2_child2_http_gsvc1 10.106.24.68 HTTP 80 -publicIP
10.106.24.68 -publicPort 80 -maxClient 0 -siteName site2_child2 -
cltTimeout 180 -svrTimeout 360 -downStateFlush ENABLED
20
21 add gslb vserver gv1 HTTP -backupLBMethod ROUNDROBIN -tolerance 0 -
appflowLog DISABLED

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2333

NetScaler 12.0

22
23 bind gslb vserver gv1 -serviceName site1_child1_http_gsvc1
24
25 bind gslb vserver gv1 -serviceName site1_child2_http_gsvc1
26
27 bind gslb vserver gv1 -serviceName site2_child2_http_gsvc1
28
29 bind gslb vserver gv1 -serviceName site2_child1_http_gsvc1
30
31 bind gslb vserver gv1 -domainName www.gslb.com -TTL 5

site1_child1

1 add gslb site site1 10.102.82.164 -publicIP 10.102.82.164

2
3 add gslb site site1_child1 10.102.82.131 -publicIP 10.102.82.131 -
nwMetricExchange DISABLED -sessionExchange DISABLED -parentSite
site1

You can add the following commands for load balancing configuration:

1 add service svc1 10.102.82.25 HTTP 80 -gslb NONE -maxClient 0 -maxReq 0

-cip DISABLED -usip NO -useproxyport YES -sp ON -cltTimeout 180 -
svrTimeout 360 -CKA NO -TCPB NO -CMP NO
2
3 add lb vserver lb1 HTTP 10.102.82.132 80 -persistenceType NONE -
cltTimeout 180
4
5 bind lb vserver lb1 svc1

site1_child2

1 add gslb site site1 10.102.82.164 -publicIP 10.102.82.164

2
3 add gslb site site1_child2 10.102.82.67 -publicIP 10.102.82.67 -
nwMetricExchange DISABLED -sessionExchange DISABLED -parentSite
site1
4
5 You can add the following commands for load balancing configuration:
6

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2334

NetScaler 12.0

7 add service svc1 10.102.82.25 HTTP 80 -gslb NONE -maxClient 0 -maxReq 0

-cip DISABLED -usip NO -useproxyport YES -sp OFF -cltTimeout 180 -
svrTimeout 360 -CKA NO -TCPB NO -CMP NO
8
9 add lb vserver lb1 HTTP 10.102.82.68 80 -persistenceType NONE -
cltTimeout 180
10
11 bind lb vserver lb1 svc1

site2

1 add gslb site site1 10.102.82.164 -publicIP 10.102.82.164

2
3 add gslb site site2 10.106.24.164 -publicIP 10.106.24.164
4
5 add gslb site site1_child1 10.102.82.131 -publicIP 10.102.82.131 -
nwMetricExchange DISABLED -sessionExchange DISABLED -parentSite
site1
6
7 add gslb site site1_child2 10.102.82.67 -publicIP 10.102.82.67 -
nwMetricExchange DISABLED -sessionExchange DISABLED -parentSite
site1
8
9 add gslb site site2_child1 10.106.24.132 -publicIP 10.106.24.132 -
nwMetricExchange DISABLED -sessionExchange DISABLED -parentSite
site2
10
11 add gslb site site2_child2 10.106.24.67 -publicIP 10.106.24.67 -
nwMetricExchange DISABLED -sessionExchange DISABLED -parentSite
site2
12
13 add gslb service site1_child1_http_gsvc1 10.102.82.132 HTTP 80 -
publicIP 10.102.82.132 -publicPort 80 -maxClient 0 -siteName
site1_child1 -cltTimeout 180 -svrTimeout 360 -downStateFlush ENABLED
14
15 add gslb service site1_child2_http_gsvc1 10.102.82.68 HTTP 80 -publicIP
10.102.82.68 -publicPort 80 -maxClient 0 -siteName site1_child2 -
cltTimeout 180 -svrTimeout 360 -downStateFlush ENABLED
16
17 add gslb service site2_child1_http_gsvc1 10.106.24.134 HTTP 80 -
publicIP 10.106.24.134 -publicPort 80 -maxClient 0 -siteName
site2_child1 -cltTimeout 180 -svrTimeout 360 -downStateFlush ENABLED
18

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2335

NetScaler 12.0

19 add gslb service site2_child2_http_gsvc1 10.106.24.68 HTTP 80 -publicIP

10.106.24.68 -publicPort 80 -maxClient 0 -siteName site2_child2 -
cltTimeout 180 -svrTimeout 360 -downStateFlush ENABLED
20
21 add gslb vserver gv1 HTTP -backupLBMethod ROUNDROBIN -tolerance 0 -
appflowLog DISABLED
22
23 bind gslb vserver gv1 -serviceName site1_child1_http_gsvc1
24
25 bind gslb vserver gv1 -serviceName site1_child2_http_gsvc1
26
27 bind gslb vserver gv1 -serviceName site2_child2_http_gsvc1
28
29 bind gslb vserver gv1 -serviceName site2_child1_http_gsvc1
30
31 bind gslb vserver gv1 -domainName www.gslb.com -TTL 5

site2_child1

1 add gslb site site2 10.106.24.164 -publicIP 10.106.24.164

2
3 add gslb site site2_child1 10.106.24.132 -publicIP 10.106.24.132 -
nwMetricExchange DISABLED -sessionExchange DISABLED -parentSite
site2

You can add the following commands for load balancing configuration:

1 add service svc1 10.102.82.25 HTTP 80 -gslb NONE -maxClient 0 -maxReq 0

-cip DISABLED -usip NO -useproxyport YES -sp ON -cltTimeout 180 -
svrTimeout 360 -CKA NO -TCPB NO -CMP NO
2
3 add lb vserver lb1 HTTP 10.106.24.134 80 -persistenceType NONE -
cltTimeout 180
4
5 bind lb vserver lb1 svc1

site2_child2

1 add gslb site site2 10.106.24.164 -publicIP 10.106.24.164

2

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2336

NetScaler 12.0

3 add gslb site site2_child2 10.106.24.67 -publicIP 10.106.24.67 -

nwMetricExchange DISABLED -sessionExchange DISABLED -parentSite
site2

You can add the following commands for load balancing configuration:

1 add service svc1 10.102.82.25 HTTP 80 -gslb NONE -maxClient 0 -maxReq 0

-cip DISABLED -usip NO -useproxyport YES -sp ON -cltTimeout 180 -
svrTimeout 360 -CKA NO -TCPB NO -CMP NO
2
3 add lb vserver lb1 HTTP 10.106.24.68 80 -persistenceType NONE -
cltTimeout 180
4
5 bind lb vserver lb1 svc1

1.
2. Citrix ADC
3. NetScaler 12.0

Link load balancing

September 17, 2018

Contributed by:
C

Link load balancing (LLB) balances outbound traffic across multiple Internet connections provided by
different service providers. LLB enables the NetScaler applianace appliance to monitor and control
traffic so that packets are transmitted seamlessly over the best possible link. Unlike with server load
balancing, where a service represents a server, with LLB, a service represents a router or the next hop.
A link is a connection between the NetScaler applianace and the router.

To configure link load balancing, many users begin by configuring a basic setup with default set-
tings. Configuring a basic setup involves configuring services, virtual servers, monitors, routes, an
LLB method, and, optionally, configuring persistence. Once a basic setup is operational, you can
customize it for your environment.

Load balancing methods that are applicable to LLB are round robin, destination IP hash, least band-
width, and least packets. You can optionally configure persistence for connections to be sustained on
a specific link. The available persistence types are source IP address-based, destination IP address-
based, and source IP and destination IP address-based. PING is the default monitor but configuring a
transparent monitor is recommended.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2337

NetScaler 12.0

You can customize your setup by configuring reverse NAT (RNAT) and backup links.

1.
2. Citrix ADC
3. NetScaler 12.0

Configuring a Basic LLB Setup

January 6, 2019

Contributed by:
C

To configure LLB, you first create services representing each router to the Internet Service Providers
(ISPs). A PING monitor is bound by default to each service. Binding a transparent monitor is optional
but recommended. Then, you create a virtual server, bind the services to the virtual server, and config-
ure a route for the virtual server. The route identifies the virtual server as the gateway to the physical
routers represented by the services. The virtual server selects a router by using the load balancing
method that you specify. Optionally, you can configure persistence to make sure that all traffic for a
particular session is sent over a specific link.

To configure a basic LLB setup, do the following:

• Configure services

• Configure an LLB virtual server and binding a service

• Configure the LLB method and persistence

• Configure an LLB route

• Create and bind a transparent monitor

Configure services

A default monitor (PING) is automatically bound to a service type of ANY when the service is created,
but you can replace the default monitor with a transparent monitor, as described in “
Creating and Binding a Transparent Monitor.”

To create a service by using the command line interface

At the command prompt, type:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2338

NetScaler 12.0

1 add service <name> <IP> <serviceType> <port>

2
3 show service <name>

Example:

1 add service ISP1R_svc_any 10.10.10.254 any *

2 show service ISP1R_svc_any
3 ISP1R_svc_any (10.10.10.254:*) - ANY
4 State: DOWN
5 Last state change was at Tue Aug 31 04:31:13 2010
6 Time since last state change: 2 days, 05:34:18.600
7 Server Name: 10.10.10.254
8 Server ID : 0 Monitor Threshold : 0
9 Max Conn: 0 Max Req: 0 Max Bandwidth: 0 kbits
10 Use Source IP: NO
11 Client Keepalive(CKA): NO
12 Access Down Service: NO
13 TCP Buffering(TCPB): YES
14 HTTP Compression(CMP): NO
15 Idle timeout: Client: 120 sec Server: 120 sec
16 Client IP: DISABLED
17 Cacheable: NO
18 SC: OFF
19 SP: OFF
20 Down state flush: ENABLED
21
22 1) Monitor Name: ping
23 State: UP Weight: 1
24 Probes: 244705 Failed [Total: 0 Current: 0]
25 Last response: Success - ICMP echo reply received.
26 Response Time: 1.322 millisec
27 Done

To create services by using the configuration utility

Navigate to Traffic Management > Load Balancing > Services, and create a service.

To create services by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Services.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2339

NetScaler 12.0

2. In the details pane, click Add.

3. In the Create Service dialog box, specify values for the following parameters:

• Service Name*—name
• Server—IP
• Protocol*—serviceType (Select ANY from the drop-down list.)
• Port*—port

A required parameter

1. Click Create.

2. Repeat Steps 2-4 to create another service.

3. Click Close.

4. In the Services pane, select the services that you just configured and verify that the settings
displayed at the bottom of the screen are correct.

Configure an LLB virtual server and bind a service

After you create a service, create a virtual server and bind services to the virtual server. The default LB
method of least connections is not supported in LLB. For information about changing the LB method,
see “
Configuring the LLB Method and Persistence.”

To create a link load balancing virtual server and bind a service by using the command line
interface

At the command prompt, type:

1 add lb vserver <name> <serviceType>

2
3 bind lb vserver < name> <serviceName>
4
5 show lb vserver < name>

Example:

1 add lb vserver LLB-vip any

2 bind lb vserver LLB-vip ISP1R_svc_any
3 sh lb vserver LLB-vip
4 LLB-vip (0.0.0.0:0) - ANY Type: ADDRESS
5 State: DOWN
6 Last state change was at Thu Sep 2 10:51:32 2010

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2340

NetScaler 12.0

7 Time since last state change: 0 days, 17:51:46.770

8 Effective State: DOWN
9 Client Idle Timeout: 120 sec
10 Down state flush: ENABLED
11 Disable Primary Vserver On Down : DISABLED
12 No. of Bound Services : 1 (Total) 0 (Active)
13 Configured Method: ROUNDROBIN
14 Mode: IP
15 Persistence: NONE
16 Connection Failover: DISABLED
17
18 1) ISP1R_svc_any (10.10.10.254: *) - ANY State: DOWN Weight: 1
19 Done

To create a link load balancing virtual server and bind a service by using the configuration
utility

1. Navigate to Traffic Management > Load Balancing > Virtual Servers, and create a virtual server
for link load balancing. Specify ANY in the Protocol field.
Note: Make sure that
Directly Addressable is unchecked.
2. Under the Services tab, in the Active column, select the check box for the service that you want
to bind to the virtual server.

Configure the LLB method and persistence

By default, the Citrix ADC appliance uses the least connections method to select the service for redi-
recting each client request, but you should set the LLB method to one of the supported methods. You
can also configure persistence, so that different transmissions from the same client are directed to
the same server.

To configure the LLB method and/or persistence by using the command line interface

At the command prompt, type the following command:

1 set lb vserver <name> -lbMethod <lbMethod> -persistenceType <

persistenceType>
2
3 show lb vserver <name>

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2341

NetScaler 12.0

1 set lb vserver LLB-vip -lbmethod ROUNDROBIN -persistencetype SOURCEIP

2
3 show lb vserver LLB-vip
4 LLB-vip (0.0.0.0:0) - ANY Type: ADDRESS
5 State: DOWN
6 Last state change was at Fri Sep 3 04:46:48 2010
7 Time since last state change: 0 days, 00:52:21.200
8 Effective State: DOWN
9 Client Idle Timeout: 120 sec
10 Down state flush: ENABLED
11 Disable Primary Vserver On Down : DISABLED
12 No. of Bound Services : 0 (Total) 0 (Active)
13 Configured Method: ROUNDROBIN
14 Mode: IP
15 Persistence: SOURCEIP
16 Persistence Mask: 255.255.255.255 Persistence v6MaskLength:
128 Persistence Timeout: 2 min
17 Connection Failover: DISABLED

To configure the link load balancing method and/or persistence by using the configuration
utility

1. Navigate to Traffic Management > Load Balancing > Virtual Servers and select the virtual server
for which you want to configure the load balancing method and/or persistence settings.
2. In the Advanced Settings section, select Method and configure the load balancing method.
3. In the Advanced Settings section, select Persistence and configure the persistence parameters.

Configure an LLB route

After configuring the

IPv4 or IPv6 services, virtual servers, LLB methods, and persistence, you configure an
IPv4 or IPv6 LLB route for the network specifying the LLB virtual server as the gateway. A route is a
collection of links that are load balanced. Requests are sent to the LLB virtual server IP address that
acts as the gateway for all outbound traffic and selects the router based on the LLB method configured.

To configure an IPv4 LLB route by using the command line interface

At the command prompt, type:

1 add lb route <network> <netmask> <gatewayName>

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2342

NetScaler 12.0

2
3 show lb route [<network> <netmask>]

Example:

1 add lb route 0.0.0.0 0.0.0.0 LLB-vip

2 show lb route 0.0.0.0 0.0.0.0
3 Network Netmask Gateway/VIP Flags
4 ----------- ------------- -------------- --------
5 1) 0.0.0.0 0.0.0.0 LLB-vip UP

To configure an IPv6 LLB route by using the command line interface

At the command prompt, type:

1 add lb route6 <network> <gatewayName>

2
3 show lb route6

Example:

1 add lb route6 ::/0 llb6_vs show lb route6 Network VIP Flags -----------
--------- -------- 1) ::/0 llb6_vs UP

To configure an LLB route by using the configuration utility

Navigate to System > Network > Routes, and select LLB, and configure the LLB route.

Note: Select LLBV6 to configure an IPV6 route.

To configure an LLB route by using the configuration utility

1. Navigate to System > Network > Routes.

2. In the details pane, select one of the following:

• Click LLB to configure an IPv4 route.

• Click LLBV6 to configure an IPv4 route.

3. In the Create LB Route or Create LB IPV6 Routedialog box, set the following parameters:

• Network*
• Netmask*—Required for IPV4 routes.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2343

NetScaler 12.0

• Gateway Name*—gatewayName

A required parameter

1. Click Create, and then click Close. The route that you just created appears on the LLB or the
LLB6 tab in the Routes pane.

The following diagram shows a basic LLB setup. A service is configured for each of the two links (ISPs)
and PING monitors are bound by default to these services. A link is selected based on the LLB method
configured.

Figure 1. Basic LLB Setup

Note

If your Internet service provider has provided an IPv6 address, replace the IPv4 service with an
IPv6 service in the above figure.

Create and bind a transparent monitor

You create a transparent monitor to monitor the health of upstream devices, such as routers. You can
then bind the transparent monitor to services. The default PING monitor monitors the connectivity
only between the Citrix ADC appliance and the upstream device. The transparent monitor monitors all
the devices existing in the path from the appliance to the device that owns the destination IP address
specified in the monitor. If a transparent monitor is not configured and the status of the router is
UP but one of the next hop devices from that router is down, the appliance includes the router while
performing load balancing and forwards the packet to the router. However, the packet is not delivered
to the final destination because one of the next hop devices is down. By binding a transparent monitor,
if any of the devices (including the router) are down, the service is marked as DOWN and the router is
not included when the appliance performs link load balancing.

To create a transparent monitor by using the command line interface

At the command prompt, type:

1 add lb monitor <monitorName> <type> -destIP <ip_addr|*> -transparent

YES
2
3 show lb monitor [<monitorName>]

Example:

1 add lb monitor monitor-1 PING -destIP 10.10.10.11 -transparent YES

2 > show lb monitor monitor-1

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2344

NetScaler 12.0

3 1) Name.......: monitor-1 Type......: PING State....:

ENABLED
4 Standard parameters:
5 Interval.........: 5 sec Retries...........:
3
6 Response timeout.: 2 sec Down time.........:
30 sec
7 Reverse..........: NO Transparent.......:
YES
8 Secure...........: NO LRTM..............:
ENABLED
9 Action...........: Not applicable Deviation.........:
0 sec
10 Destination IP...: 10.10.10.11
11 Destination port.: Bound service
12 Iptunnel.........: NO
13 TOS..............: NO TOS ID............:
0
14 SNMP Alert Retries: 0 Success Retries..:
1
15 Failure Retries..: 0

To create a transparent monitor by using the configuration utility

Navigate to Traffic Management > Load Balancing > Monitors and configure a transparent monitor.

To create a transparent monitor by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Monitors.

2. In the Monitors pane, click Add.

3. In the Create Monitor dialog box, set the following parameters:

• Name*
• Type*
• Destination IP
• Transparent

A required parameter

1. Click Create, and then click Close.

2. In the Monitors pane, select the monitor that you just configured and verify that the settings
displayed in the Details pane are correct.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2345

NetScaler 12.0

To bind a monitor to a service by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Services.

2. On the Monitors tab, under Available, select the monitor that you want to bind to the service,
and then click Add.

To bind a monitor to a service by using the command line interface

At the command prompt, type:

1 bind lb monitor <monitorName> <serviceName>

2
3 show service <name>

Example:

1 bind lb monitor monitor-HTTP-1 ISP1R_svc_any

2 Done
3 > show service ISP1R_svc_any
4 ISP1R_svc_any (10.10.10.254:*) - ANY
5 State: UP
6 Last state change was at Thu Sep 2 10:51:07 2010
7 Time since last state change: 0 days, 18:41:55.130
8 Server Name: 10.10.10.254
9 Server ID : 0 Monitor Threshold : 0
10 Max Conn: 0 Max Req: 0 Max Bandwidth: 0 kbits
11 Use Source IP: NO
12 Client Keepalive(CKA): NO
13 Access Down Service: NO
14 TCP Buffering(TCPB): YES
15 HTTP Compression(CMP): NO
16 Idle timeout: Client: 120 sec Server: 120 sec
17 Client IP: DISABLED
18 Cacheable: NO
19 SC: OFF
20 SP: OFF
21 Down state flush: ENABLED
22
23 1) Monitor Name: monitor-HTTP-1
24 State: UP Weight: 1
25 Probes: 1256 Failed [Total: 0 Current: 0]
26 Last response: Success - ICMP echo reply received.
27 Response Time: 1.322 millisec
28 Done

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2346

NetScaler 12.0

To bind a monitor to a service by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Services.

2. In the details pane, select a service to which you want to bind a monitor, and then click Open.
3. In the Configure Service dialog box, on the Monitors tab, under Available, select the monitor
that you want to bind to the service, and then click Add.
4. Click OK.
5. In the Services pane, select the service that you just configured and verify that the settings dis-
played in the Details pane are correct.

1.
2. Citrix ADC
3. NetScaler 12.0

Configuring RNAT with LLB

November 22, 2018

Contributed by:
C

You can configure an LLB setup for reverse network address translation (RNAT) for outbound traffic.
This ensures that the return network traffic for a specific flow is routed through the same path. First
configure basic LLB, as described in
“Configuring a Basic LLB Setup”, and then configure RNAT. You must then enable use subnet IP (USNIP)
mode.

To add SNIPs for ISP routers by using the command line interface

At the command prompt, type:

1 add IP NS <network><subnet of first ISP in the IP router> <subnet mask>

 -type SNIP
2
3 add IP NS <in the IP subnet of second ISP router> <subnet mask> -type
SNIP

Example:

1 add ns ip 10.140.23.1 255.255.255.0 -type snip

2

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2347

NetScaler 12.0

3 add ns ip 10.141.23.1 255.255.255.0 -type snip

To configure RNAT by using the command line interface

At the command prompt, type:

1 set rnat <network> <netmask>

2
3 show rnat

Example:

1 set rnat 10.102.29.0 255.255.255.0 -natIP 10.140.23.1

2 set rnat 10.102.29.0 255.255.255.0 -natIP 10.141.23.1
3 show rnat
4 1) Network: 10.102.29.0      Netmask: 255.255.255.0
5  NatIP: 10.140.23.1
6  2) Network: 10.102.29.0      Netmask: 255.255.255.0
7  NatIP: 10.141.23.1

To configure RNAT by using the configuration utility

1. Navigate to System > Network > NATs.

2. On the RNAT tab, click Configure RNAT.
3. Specify the network on which to perform RNAT.

Note

You can also configure RNAT by using Access Control Lists (ACLs). Refer Configuring RNAT for
details.

To enable Use Subnet IP mode by using the command line interface

At the command prompt, type:

1 enable ns mode USNIP

2
3 show ns mode

Example:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2348

NetScaler 12.0

1 enable ns mode USNIP

2
3 show ns mode
4 Mode Acronym Status
5 ------- ------- ------
6 1) Fast Ramp FR ON
7 2) ….
8 8) Use Subnet IP USNIP ON
9 9) …

To enable Use Subnet IP mode by using the configuration utility

1. Navigate to System > Settings and, under Modes and Features, click Configure Modes.
2. In the Configure Modes dialog box, select Use Subnet IP, and then click OK.

1.
2. Citrix ADC
3. NetScaler 12.0

Configuring a Backup Route

January 6, 2019

Contributed by:
C

To prevent disruption in services when the primary route is down, you can configure a backup route.
Once the backup route is configured, the NetScaler appliance automatically uses it when the primary
route fails. First create a primary virtual server as described in “Configuring an LLB Virtual Server and
Binding a Service.” To configure a backup route, create a secondary virtual server similar to a primary
virtual server and then designate this virtual server as a backup virtual server (route).

In the following diagram, Router-vip is the primary virtual server, and Backup_Router-vip is the sec-
ondary virtual server designated as the backup virtual server.

Figure 1. Backup Route Setup

Note: If your Internet service provider has provided an IPv6 address, replace the IPv4 service with an
IPv6 service in the above figure.

By default, all traffic is sent through the primary route. However, when the primary route fails, all
traffic is diverted to the backup route as shown in the following diagram.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2349

NetScaler 12.0

Figure 2. Backup Routing in Operation

Note: If your Internet service provider has provided an IPv6 address, replace the IPv4 service with an
IPv6 service in the above figure.

To set the secondary virtual server as the backup virtual server by using the command
line interface

At the command prompt, type:

1 set lb vserver <name> -backupVserver <string>

Example:

1 set lb vserver Router-vip -backupVServer Backup_Router-vip

2 > show lb vserver Router-vip
3 Router-vip (0.0.0.0:0) - ANY Type: ADDRESS
4 State: UP
5 Last state change was at Fri Sep 3 04:46:48 2010
6 Time since last state change: 0 days, 03:09:45.600
7 Effective State: UP
8 Client Idle Timeout: 120 sec
9 Down state flush: ENABLED
10 Disable Primary Vserver On Down : DISABLED
11 No. of Bound Services : 1 (Total) 1 (Active)
12 Configured Method: ROUNDROBIN
13 Mode: IP
14 Persistence: DESTIP Persistence Mask: 255.255.255.255
Persistence v6MaskLength: 128 Persistence Timeout: 2
min
15 Backup: Router2-vip
16 Connection Failover: DISABLED
17 Done

To set the secondary virtual server as the backup virtual server by using the
configuration utility

1. Navigate to Traffic Management > Load Balancing > Virtual Servers and select the secondary
virtual server for which you want to configure the backup virtual server.
2. In the Load Balancing Virtual Server dialog box, under Advanced, select Protection.
3. In the Backup Virtual Server drop-down list, select the secondary backup virtual server, and
then click OK.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2350

NetScaler 12.0

1.
2. Citrix ADC
3. NetScaler 12.0

Resilient LLB Deployment Scenario

January 6, 2019

Contributed by:
C

In the following diagram, there are two networks: 30.30.30.0 and 30.30.31.0. Link load balancing is
configured based on the destination IP address. Two routes are configured with gateways Router1-vip
and Router2-vip, respectively. Router1-vip is configured as a backup to Router2-vip and vice versa.
All traffic with the destination IP specified as 30.30.30.30 is sent through Router1-vip and traffic with
the destination IP specified as 30.30.31.31 is sent through Router2-vip.

Figure 1. Resilient LLB Deployment Setup

Note: If your Internet service provider has provided an IPv6 address, replace the IPv4 service with an
IPv6 service in the above figure.

However, if any one of the gateways (Router1-vip or Router2-vip) is DOWN, traffic is routed through
the backup router. In the following diagram, Router1-vip for ISP1 is DOWN, so all traffic with the des-
tination IP specified as 30.30.30.30 is also sent through ISP2.

Figure 2. Resilient LLB Deployment Scenario

Note: If your Internet service provider has provided an IPv6 address, replace the IPv4 service with an
IPv6 service in the above figure.

1.
2. Citrix ADC
3. NetScaler 12.0

Monitoring an LLB Setup

January 10, 2019

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2351

NetScaler 12.0

After the configuration is up and running, you should view the statistics for each service and virtual
server to check for possible problems.

Viewing the Statistics of a Virtual Server

To evaluate the performance of virtual servers or to troubleshoot problems, you can display details of
the virtual servers configured on the NetScaler appliance. You can display a summary of statistics for
all the virtual servers, or you can specify the name of a virtual server to display the statistics only for
that virtual server. You can display the following details:

• Name
• IP address
• Port
• Protocol
• State of the virtual server
• Rate of requests received
• Rate of hits

To display virtual server statistics by using the command line interface

To display a summary of the statistics for all the virtual servers currently configured on the NetScaler,
or for a single virtual server, at the command prompt, type:

1 stat lb vserver -detail] [<name>]

Example:

1 >stat lb vserver -detail

2 Virtual Server(s) Summary
3 vsvrIP port Protocol State Req/s
Hits/s
4 One * 80 HTTP UP 5/s
0/s
5 Two * 0 TCP DOWN 0/s
0/s
6 Three * 2598 TCP DOWN 0/s
0/s
7 dnsVirtualNS 10.102.29.90 53 DNS DOWN 0/s
0/s
8 BRVSERV 10.10.1.1 80 HTTP DOWN 0/s
0/s
9 LBVIP 10.102.29.66 80 HTTP UP 0/s
0/s

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2352

NetScaler 12.0

10 Done

To display virtual server statistics by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Virtual Servers > Statistics.
2. If you want to display the statistics for only one virtual server, in the details pane, select the
virtual server, and click Statistics.

Viewing the Statistics of a Service

You can view the rate of requests, responses, request bytes, response bytes, current client connec-
tions, requests in surge queue, current server connections, and so forth using the service statistics.

To view the statistics of a service by using the command line interface

At the command prompt, type:

stat service <name>

Example:

1 stat service Service-HTTP-1

To view the statistics of a service by using the configuration utility

1. Navigate to Traffic Management > Load Balancing > Services > Statistics.
2. If you want to display the statistics for only one service, select the service, and click Statistics.

1.
2. Citrix ADC
3. NetScaler 12.0

Load Balancing

September 17, 2018

Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2353

NetScaler 12.0

The load balancing feature distributes user requests for web pages and other protected applications
across multiple servers that all host (or mirror) the same content. You use load balancing primarily
to manage user requests to heavily used applications, preventing poor performance and outages and
ensuring that users can access your protected applications. Load balancing also provides fault toler-
ance; when one server that hosts a protected application becomes unavailable, the feature distributes
user requests to the other servers that host the same application.

You can configure the load balancing feature to:

• Distribute all requests for a specific protected website, application, or resource between two or
more identically configured servers.
• Use any of several different algorithms to determine which server should receive each incom-
ing user request, basing the decision on different factors, such as which server has the fewest
current user connections or which server has the lightest load.

The load balancing feature is a core feature of the NetScaler appliance. Most users first set up a work-
ing basic configuration and then customize various settings, including persistence for connections. In
addition, you can configure features for protecting the configuration against failure, managing client
traffic, managing and monitoring servers, and managing a large scale deployment.

1.
2. Citrix ADC
3. NetScaler 12.0

How load balancing works

January 6, 2019

Contributed by:
C

In a basic load balancing setup, clients send their requests to the IP address of a virtual server config-
ured on the NetScaler appliance. The virtual server distributes them to the load-balanced application
servers according to a preset pattern, called the load balancing algorithm. In some cases, you might
want to assign the load balancing virtual server a wildcard address instead of a specific IP address.
For instructions about specifying a global HTTP port on the appliance, see Global HTTP Ports.

Load balancing basics

A load balancing setup includes a load-balancing virtual server and multiple load-balanced applica-
tion servers. The virtual server receives incoming client requests, uses the load balancing algorithm to

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2354

NetScaler 12.0

select an application server, and forwards the requests to the selected application server. The follow-
ing conceptual drawing illustrates a typical load balancing deployment. Another variation involves
assigning a global HTTP port.

Figure 1. Load Balancing Architecture

The load balancing virtual server can use any of a number of algorithms (or methods) to determine
how to distribute load among the load-balanced servers that it manages. The default load balancing
method is the least connection method, in which the NetScaler appliance forwards each incoming
client connection to whichever load-balanced application server currently has the fewest active user
connections.

The entities that you configure in a typical NetScaler load balancing setup are:

• Load balancing virtual server. The IP address, port, and protocol combination to which a
client sends connection requests for a particular load-balanced website or application. If the
application is accessible from the Internet, the virtual server IP (VIP) address is a public IP ad-
dress. If the application is accessible only from the local area network (LAN) or wide area net-
work (WAN), the VIP is usually a private (ICANN non-routable) IP address.
• Service. The IP address, port, and protocol combination used to route requests to a specific
load-balanced application server. A service can be a logical representation of the application
server itself, or of an application running on a server that hosts multiple applications. After
creating a service, you bind it to a load balancing virtual server.
• Server object. A virtual entity that enables you to assign a name to a physical server instead of
identifying the server by its IP address. If you create a server object, you can specify its name
instead of the server’s IP address when you create a service. Otherwise, you must specify the
server’s IP address when you create a service, and the IP address becomes the name of the
server.
• Monitor. An entity on the NetScaler appliance that tracks a service and ensures that it is oper-
ating correctly. The monitor periodically probes (or performs a health check on) each service to
which you assign it. If the service does not respond within the time specified by the time-out,
and a specified number of health checks fail, that service is marked DOWN. The NetScaler appli-
ance then skips that service when performing load balancing, until the issues that caused the
service to quit responding are fixed.

The virtual server, services, and load balanced application servers in a load balancing setup can use
either Internet Protocol version 4 (IPv4) or Internet Protocol version 6 (IPv6) IP addresses. You can mix
IPv4 and IPv6 addresses in a single load balancing setup.

For variations in the load balancing setup, see the following use cases:

• Configuring Load Balancing in Direct Server Return Mode

• Configuring LINUX Servers in DSR Mode
• Configuring DSR Mode When Using TOS

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2355

NetScaler 12.0

• Configuring Load Balancing in DSR Mode by Using IP Over IP

• Configuring Load Balancing in One-arm Mode
• Configuring Load Balancing in the Inline Mode
• Load Balancing of Intrusion Detection System Servers
• Load balance remote desktop protocol servers

Understanding the topology

In a load balancing setup, the load balancing server is logically located between the client and the
server farm, and manages traffic flow to the servers in the server farm. On the NetScaler appliance, the
application servers are represented by virtual entities called services. The following diagram shows
the topology of a basic load balancing configuration.

Figure 2. Basic Load Balancing Topology

In the diagram, load balancing is used to manage traffic flow to the servers. The virtual server selects
the service and assigns it to serve client requests. Consider a scenario where the services Service-
HTTP-1 and Service-HTTP-2 are created and bound to the virtual server named Vserver-LB-1. Vserver-
LB-1 forwards the client request to either Service-HTTP-1 or Service-HTTP-2. The NetScaler appliance
uses the least connection load balancing method to select the service for each request. The following
table lists the names and values of the basic entities that must be configured on the appliance.

Entity Name IPAddress Port Protocol

Virtual server Vserver-LB-1 10.102.29.60 80 HTTP

Services Service-HTTP-1 10.102.29.5 80 HTTP
Service-HTTP-2 10.102.29.6 80 HTTP
Monitors Default None None None

The following diagram shows the load balancing sample values and mandatory parameters that are
described in the preceding table.
Figure 3. Load Balancing Entity Model

Use of wildcards instead of IP addresses and ports

In some cases you might need to use a wildcard for the IP address or the port of a virtual server or for
the port of a service. The following cases may require using a wildcard:
• If the NetScaler appliance is configured as a transparent pass through, which must accept all
traffic that is sent to it regardless of the IP or port to which it is sent.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2356

NetScaler 12.0

• If one or more services listen on ports that are not well known.
• If one or more services, over time, change the ports that they listen on.
• If you reach the limit for the number of IP addresses and ports that you can configure on a single
NetScaler appliance.
• If you want to create virtual servers that listen for all traffic on a specific virtual LAN.

When a wildcard-configured virtual server or service receives traffic, the NetScaler appliance deter-
mines the actual IP address or port and creates new records for the service and associated load bal-
anced application server. These dynamically created records are called dynamically learned server
and service records.

For example, a firewall load balancing configuration can use wildcards for both the IP address and
port. If you bind a wildcard TCP service to this type of load balancing virtual server, the virtual server
receives and processes all TCP traffic that does not match any other service or virtual server.

The following table describes some of the different types of wildcard configurations and when each
should be used.

IP Port Protocol Description

* * TCP A general wildcard

virtual server that
accepts traffic sent to
any IP address and
port on the NetScaler
appliance. When
using a wildcarded
virtual server, the
appliance
dynamically learns
the IP and port of
each service and
creates the necessary
records as it
processes traffic.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2357

NetScaler 12.0

IP Port Protocol Description

* * TCP A firewall load

balancing virtual
server. You can bind
firewall services to
this virtual server,
and the NetScaler
appliance passes
traffic through the
firewall to the
destination.
IP Address * TCP,UDP, and ANY A virtual server that
accepts all traffic that
is sent to the
specified IP address,
regardless of the port.
You must explicitly
bind to this type of
virtual server the
services to which it
will redirect traffic. It
will not dynamically
learn them.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2358

NetScaler 12.0

IP Port Protocol Description

Note: You do not

configure services or
virtual servers for a
global HTTP port. In
this case, you
configure a specific
port as a global HTTP
port (for example, set
ns param -httpPort
80). The appliance
then accepts all traffic
that matches the port
number, and
processes it as HTTP
traffic. The appliance
dynamically learns
and creates services
for this traffic.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2359

NetScaler 12.0

IP Port Protocol Description

* port SSL, SSL_TCP A virtual server that

accepts all traffic sent
to any IP address on a
specific port. Used for
global transparent
SSL offloading. All
SSL, HTTP, and TCP
processing that
usually is performed
for a service of the
same protocol type is
applied to traffic that
is directed to this
specific port. The
appliance uses the
port to dynamically
learn the IP of the
service it should use.
If –cleartext is not
specified, the
NetScaler appliance
uses end-to-end SSL.
* port Not applicable All other virtual
servers that can
accept traffic to the
port. You do not bind
services to these
virtual servers; the
NetScaler appliance
learns them
dynamically.

Note: If you have configured your NetScaler appliance as a transparent pass through that makes use
of global (wildcard) ports, you may want to turn on Edge mode.
For more information, see “Configuring Edge Mode.”

The NetScaler appliance attempts to locate virtual servers and services by first attempting an exact

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2360

NetScaler 12.0

match. If none is found, it continues to search for a match based on wildcards, in the following order:

1. Specific IP address and specific port number

2. Specific IP address and a * (wildcard) port

3. • (wildcard) IP address and a specific port

4. • (wildcard) IP address and a * (wildcard) port

If the appliance is unable to select a virtual server by IP address or port number, it searches for a virtual
server on the basis of the protocol used in the request, in the following order:

1. HTTP
2. TCP
3. ANY

Configuring global HTTP ports

You do not configure services or virtual servers for a global HTTP port. Instead, you configure a specific
port by using the set ns param command. After configuring this port, the NetScaler appliance accepts
all traffic that matches the port number, and processes it as HTTP traffic, dynamically learning and
creating services for that traffic.

You can configure more than one port number as a global HTTP port. If you are specifying more than
one port number in a single set ns param command, separate the port numbers by a single white
space. If one or more ports have already been specified as global HTTP ports, and you want to add
one or more ports without removing the ports that are currently configured, you must specify all the
port numbers, current and new, in the command. Before you add port numbers, use the show ns
param command to view the ports that are currently configured.

To configure a global HTTP port by using the command line interface

At the command prompt, type the following commands to configure a global HTTP port and verify the
configuration:

1 set ns param ‒ httpPort <port>

2
3 show ns param

Example 1: Configuring a port as a global HTTP port

In this example, port 80 is configured as a global HTTP port.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2361

NetScaler 12.0

1 set ns param -httpPort 80

2 Done
3 show ns param
4 Global configuration settings:
5 HTTP port(s): 80
6 Max connections: 0
7 Max requests per connection: 0
8 Client IP insertion: DISABLED
9 Cookie version: 0
10 Persistence Cookie Secure Flag: ENABLED
11 ...
12 ...

Example 2: Adding ports when one or more global HTTP ports are already configured**

In this example, port 8888 is added to the global HTTP port list. Port 80 is already configured as a
global HTTP port.

1 > show ns param

2 Global configuration settings:
3 HTTP port(s): 80
4 Max connections: 0
5 Max requests per connection: 0
6 Client IP insertion: DISABLED
7 Cookie version: 0
8 Persistence Cookie Secure Flag: ENABLED
9 Min Path MTU: 576
10 ...
11 ...
12 Done
13 > set ns param -httpPort 80 8888
14 Done
15 > show ns param
16
17 Global configuration settings:
18 HTTP port(s): 80,8888
19 Max connections: 0
20 Max requests per connection: 0
21 Client IP insertion: DISABLED
22 Cookie version: 0
23 Persistence Cookie Secure Flag: ENABLED
24 Min Path MTU: 576
25

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2362

NetScaler 12.0

26 ...
27 ...
28 Done
29 >

To configure a global HTTP port by using the configuration utility

1. Navigate to System > Settings > Change HTTP Parameters, and then add an HTTP port number.

1.
2. Citrix ADC
3. NetScaler 12.0

Set up basic load balancing

June 7, 2019

Contributed by:
C

Before configuring your initial load balancing setup, enable the load balancing feature. Then begin by
creating at least one service for each server in the load balancing group. With the services configured,
you are ready to create a load balancing virtual server, and bind each service to the virtual server. That
completes the initial setup. Before proceeding with further configuration, verify your configuration to
make sure that each element was configured properly and is operating as expected.

Enabling Load Balancing

You can configure load balancing entities such as services and virtual servers when the load balancing
feature is disabled, but they will not function until you enable the feature.

To enable load balancing by using the CLI

At the command prompt, type the following command to enable load balancing and verify the config-
uration:

• enable ns feature LB
• show ns feature

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2363

NetScaler 12.0

Example

1 > enable ns feature LoadBalancing

2
3 Done
4
5 > show ns feature
6
7
8
9 Feature Acronym Status
10
11 ------- ------- ------
12
13 1) Web Logging WL OFF
14
15 2) Surge Protection SP ON
16
17 3) Load Balancing LB ON
18
19 .
20
21 .
22
23 .
24
25 24) NetScaler Push push OFF
26
27 Done

To enable load balancing by using the GUI

Navigate to System > Settings and, in Configure Basic Features, select Load Balancing.

Configuring a Server Object

Create an entry for your server on the NetScaler appliance. THe NetScaler appliance supports IP ad-
dress based servers and domain-based servers. If you create an IP address based server, you can
specify the name of the server instead of its IP address when you create a service. For information
about setting up DNS for a domain-based server, see Domain Name System.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2364

NetScaler 12.0

To create a server object by using the CLI

At the command prompt, type:

1 add server <name>@ <IPAddress>@ | <domain>

Example:

1 add server web_serv 10.102.27.150

To create a server object by using the GUI

Navigate to Traffic Management > Load Balancing > Servers, and add a server object.

Configuring Services

After you enable the load balancing feature, you must create at least one service for each application
server that is to be included in your load balancing setup. The services that you configure provide
the connections between the NetScaler appliance and the load balanced servers. Each service has a
name and specifies an IP address, a port, and the type of data that is served.

If you create a service without first creating a server object, the IP address of the service is also the
name of the server that hosts the service. If you prefer to identify servers by name rather than IP
address, you can create server objects and then specify a server’s name instead of its IP address when
you create a service.

When you create a service that uses UDP as the transport layer protocol, a ping monitor is automati-
cally bound to the service. A ping monitor is the most basic of the built-in monitors. When you create a
service that uses TCP as the transport layer protocol, a TCP_default monitor is automatically bound to
the service. When you develop a strategy for managing your load balancing setup, you might decide
to bind a different type of monitor, or multiple monitors, to the service.

Creating a Service

Before you create a service, you need to understand the different service types and how each is used.
The following list describes the types of services supported on the NetScaler appliance.

HTTP

Used for load-balanced servers that accept HTTP traffic, such as standard websites and web appli-
cations. The HTTP service type enables the NetScaler appliance to provide compression, content fil-

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2365

NetScaler 12.0

tering, caching, and client keep-alive support for your Layer 7 web servers. This service type also
supports virtual server IP port insertion, redirect port rewriting, Web 2.0 Push, and URL redirection
support.

Because HTTP is a TCP-based application protocol, you can also use the TCP service type for web
servers. If you do so, however, the NetScaler appliance is able to perform only Layer 4 load balancing.
It cannot provide any of the Layer 7 supports described earlier.

SSL

Used for servers that accept HTTPS traffic, such as ecommerce websites and shopping cart applica-
tions. The SSL service type enables the NetScaler appliance to encrypt and decrypt SSL traffic (per-
form SSL offloading) for your secure web applications. It also supports HTTP persistence, content
switching, rewrite, virtual server IP port insertion, Web 2.0 Push, and URL redirection.

You can also use the SSL_BRIDGE, SSL_TCP, or TCP service types. If you do so, however, the appliance
performs only Layer 4 load balancing. It cannot provide SSL offloading or any of the Layer 7 supports
described above.

FTP

Used for servers that accept FTP traffic. The FTP service type enables the NetScaler appliance to sup-
port specific details of the FTP protocol.

You can also use TCP or ANY service types for FTP servers.

TCP

Used for servers that accept many different types of TCP traffic, or that accept a type of TCP traffic for
which a more specific type of service is not available.

You can also use the ANY service type for these servers.

SSL_TCP

Used for servers that accept non-HTTP-based SSL traffic, to support SSL offloading.

You can also use the TCP service type for these services. If you do so, the NetScaler appliance performs
both the Layer 4 load balancing and SSL offloading.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2366

NetScaler 12.0

UDP

Used for servers that accept UDP traffic. You can also use the ANY service type.

SSL_BRIDGE

Used for servers that accept SSL traffic when you do not want the NetScaler appliance to perform SSL
offloading. Alternatively, you can use the SSL_TCP service type.

NNTP

Used for servers that accept Network News Transfer Protocol (NNTP) traffic, typically Usenet sites.

DNS

Used for servers that accept DNS traffic, typically nameservers. With the DNS service type, the
NetScaler appliance validates the packet format of each DNS request and response. It can also cache
DNS responses. You can apply DNS policies to DNS services.

You can also use the UDP service type for these services. If you do, however, the NetScaler appliance
can only perform Layer 4 load balancing. It cannot provide support for DNS-specific features.

ANY

Used for servers that accept any type of TCP, UDP, or ICMP traffic. The ANY parameter is used primarily
with firewall load balancing and link load balancing.

SIP-UDP

Used for servers that accept UDP-based Session Initiation Protocol (SIP) traffic. SIP initiates, manages,
and terminates multimedia communications sessions, and has emerged as the standard for Internet
telephony (VoIP).

You can also use the UDP service type for these services. If you do, however, the NetScaler appliance
performs only Layer 4 load balancing. It cannot provide support for SIP-specific features.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2367

NetScaler 12.0

DNS-TCP

Used for servers that accept DNS traffic, where the NetScaler appliance acts as a proxy for TCP traffic
sent to DNS servers. With services of the DNS-TCP service type, the NetScaler appliance validates
the packet format of each DNS request and response and can cache DNS responses, as with the DNS
service type.

You can also use the TCP service type for these services. If you do, however, the NetScaler appliance
only performs Layer 4 load balancing of external DNS name servers. It cannot provide support for any
DNS-specific features.

RTSP

Used for servers that accept Real Time Streaming Protocol (RTSP) traffic. RTSP provides delivery of
multimedia and other streaming data. Select this type to support audio, video, and other types of
streamed media.

You can also use the TCP service type for these services. If you do, however, the NetScaler appliance
performs only Layer 4 load balancing. It cannot parse the RTSP stream or provide support for RTSPID
persistence or RTSP NATting.

DHCPRA

Used for servers that accept DHCP traffic. The DHCPRA service type can be used to relay DHCP requests
and responses between VLANs.

DIAMETER

Used for load balancing Diameter traffic among multiple Diameter servers. Diameter uses message-
based load balancing.

SSL_DIAMETER

Used for load balancing Diameter traffic over SSL.

Services are designated as DISABLED until the NetScaler appliance connects to the associated load-
balanced server and verifies that it is operational. At that point, the service is designated as ENABLED.
Thereafter, the NetScaler appliance periodically monitors the status of the servers, and places any
that fail to respond to monitoring probes (called health checks) back in the DISABLED state until they
respond.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2368

NetScaler 12.0

Note: You can create a range of services from a single CLI command or the same dialog box. The names
in the range vary by a number used as a suffix/prefix. For example, service1, service2, and so on. From
the configuration utility, you can specify a range only in the last octet of the IP address, which is the
fourth in case of an IPv4 address and the eighth in case of an IPv6 address. From the command line,
you can specify the range in any octet of the IP address.

QUIC

Used by load balancing servers that accept UDP based QUIC video traffic. The service enables the
NetScaler appliance to optimize encrypted ABR video traffic over UDP protocol.

To create a service by using the CLI

At the command prompt, type:

1 add service <name> <serverName> <serviceType> <port>

2
3 add service Service-HTTP-1 192.0.2.5 HTTP 80

To create a service by using the GUI

1. Navigate to Traffic Management> Load Balancing > Services.

2. In the details pane, click Add.

3. In the Create Service dialog box, specify values for the following parameters:

• Service Name—name
• Server—serverName
• Protocol—serviceType
• Port—port

4. Click Create, and then click Close. The service you created appears in the Services pane.

Creating a Virtual Server

After you create your services, you must create a virtual server to accept traffic for the load bal-
anced websites, applications, or servers. Once load balancing is configured, users connect to the
load-balanced website, application, or server through the virtual server’s IP address or FQDN.

Note:

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2369

NetScaler 12.0

• Virtual server names prefixed with “app” do not appear in the GUI though they are present in
the ns.conf file and are displayed when you run the show command. However, virtual server
names prefixed with “app” are displayed in the GUI.

• The virtual server is designated as DOWN until you bind the services that you created to it, and
until the Citrix ADC appliance connects to those services and verifies that they are operational.
Only then is the virtual server designated as UP.

To create a virtual server by using the CLI

At the command prompt, type:

1 add lb vserver <name> <serviceType> <ip> <port>

2
3 add lb vserver Vserver-LB-1 HTTP 10.102.29.60 80

To create a virtual server by using the GUI

Navigate to Traffic Management > Load Balancing > Virtual Servers, and then create a virtual server.

Binding Services to the Virtual Server

Note: A service can be bound to a maximum of 500 virtual servers.

After you have created services and a virtual server, you must bind the services to the virtual server.
Usually, services are bound to virtual servers of the same type, but you can bind certain types of ser-
vices to certain different types of virtual servers, as shown below.

Virtual Server Type Service Type Comment

HTTP SSL You would normally bind an

SSL service to an HTTP virtual
server to do encryption.
SSL HTTP You would normally bind an
HTTP service to an SSL virtual
server to do SSL offloading.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2370

NetScaler 12.0

Virtual Server Type Service Type Comment

SSL_TCP TCP You would normally bind a

TCP service to an SSL_TCP
virtual server to do SSL
offloading for other TCP (SSL
decryption without content
awareness).

The state of the services bound to a virtual server determines the state of the virtual server: if all of
the bound services are DOWN, the virtual server is marked DOWN, and if any of the bound services is
UP or OUT OF SERVICE, the state of the virtual server is UP.

To bind a service to a load balancing virtual server by using the CLI

At the command prompt, type:

1 bind lb vserver <name> <serviceName>

2
3 bind lb vserver Vserver-LB-1 Service-HTTP-1

To bind a service to a load balancing virtual server by using the GUI

1. Navigate to Traffic Management> Load Balancing > Virtual Servers, and select a virtual server.
2. Click in the Service section, and select a service to bind.

Note: You can bind a service to multiple virtual servers.

Verifying the Configuration

After finishing your basic configuration, you should view the properties of each service and load bal-
ancing virtual server in your load balancing setup to verify that each is configured correctly. After the
configuration is up and running, you should view the statistics for each service and load balancing
virtual server to check for possible problems.

Viewing the Properties of a Server Object

You can view properties such as the name, state, and IP address of any server object in your NetScaler
appliance configuration.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2371

NetScaler 12.0

To view the properties of server objects by using the CLI

At the command prompt, type:

1 show server <serverName>

2
3 show server server-1

To view the properties of server objects by using the GUI

Navigate to Traffic Management > Load Balancing > Servers. The parameter values of the available
servers appear in the details pane.

Viewing the Properties of a Virtual Server

You can view properties such as the name, state, effective state, IP address, port, protocol, method,
and number of bound services for your virtual servers. If you have configured more than the basic
load balancing settings, you can view the persistence settings for your virtual servers, any policies
that are bound to them, and any cache redirection and content switching virtual servers that have
been bound to the virtual servers.

To view the properties of a load balancing virtual server by using the CLI

At the command prompt, type:

1 show lb vserver <name>

2
3 show lb vserver Vserver-LB-1

To view the properties of a load balancing virtual server by using the GUI

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.

2. In the details pane, click a virtual server to display its properties at the bottom of the details
pane.

3. To view cache redirection and content switching virtual servers that are bound to this virtual
server, click Show CS/CR Bindings.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2372

NetScaler 12.0

Viewing the Properties of a Service

You can view the name, state, IP address, port, protocol, maximum client connection, maximum re-
quests per connection, and server type of the configured services, and use this information to trou-
bleshoot any mistake in the service configuration.

To view the properties of services by using the CLI

At the command prompt, type:

1 show service <name>

2
3 show service Service-HTTP-1

To view the properties of services by using the GUI

Navigate to Traffic Management > Load Balancing > Services. The details of the available services
appear on the Services pane.

Viewing the Bindings of a Service

You can view the list of virtual servers to which the service is bound. The binding information also
provides the name, IP address, port, and state of the virtual servers to which the services are bound.
You can use the binding information to troubleshoot any problem with binding the services to virtual
servers.

To view the bindings of a service by using the command line

At the command prompt, type:

1 show service bindings <name>

2
3 show service bindings Service-HTTP-1

To view the bindings of a service by using the GUI

1. Navigate to Traffic Management > Load Balancing > Services.

2. In the details pane, select the service whose binding information you want to view.

3. In the Action tab, click Show Bindings.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2373

NetScaler 12.0

Viewing the Statistics of a Virtual Server

To evaluate the performance of virtual servers or to troubleshoot problems, you can display details of
the virtual servers configured on the NetScaler appliance. You can display a summary of statistics for
all the virtual servers, or you can specify the name of a virtual server to display the statistics only for
that virtual server. You can display the following details:

• Name
• IP address
• Port
• Protocol
• State of the virtual server
• Rate of requests received
• Rate of hits

To display virtual server statistics by using the CLI

To display a summary of the statistics for all the virtual servers currently configured on the appliance,
or for a single virtual server, at the command prompt, type:

1 stat lb vserver [‘<name>‘]

Example:

1 stat lb vserver server-1

The following figure displays a sample statistic page.

To display virtual server statistics by using the GUI

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.

2. If you want to display the statistics for only one virtual server, in the details pane, select the
virtual server whose statistics you want to display.

3. In the details pane, click Statistics.

Viewing the Statistics of a Service

You can view the rate of requests, responses, request bytes, response bytes, current client connec-
tions, requests in surge queue, current server connections, and so forth using the service statistics.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2374

NetScaler 12.0

To view the statistics of a service by using the CLI

At the command prompt, type:

1 stat service ‘<name>‘

Example:

1 stat service Service-HTTP-1

To view the statistics of a service by using the GUI

1. Navigate to Traffic Management > Load Balancing > Services.

2. In the details pane, select the service whose statistics you want to view (for example, Service-
HTTP-1).

3. Click Statistics. The statistics appear in a new window.

1.
2. Citrix ADC
3. NetScaler 12.0

Load balance virtual server and service states

January 6, 2019

Contributed by:
C

A load balancing virtual server that does not have a backup virtual server can take the following states,
depending on the states of the service(s) bound to it and whether it is administratively disabled:

• UP: At least one of the services bound to the virtual server is UP.
• DOWN: All the services bound to the virtual server are DOWN, or the load balancing feature is
not enabled.
• Out of Service (OFS): If you administratively disable the virtual server, it enters the OFS state
but its effective state is DOWN. Transitioning to the OFS state from the DOWN or UP state, or to
the DOWN or UP state from the OFS state, is controlled by the administrator.

The state and effective state of a virtual server are the same if a backup virtual server is not configured.
However, if a backup virtual server or a chain of backup virtual servers is configured, the effective state
is derived from the states of the services that are bound to the primary virtual server and the backup

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2375

NetScaler 12.0

virtual server(s). If any of the backup virtual servers in the chain is UP, the effective state of the primary
virtual server is UP, even if all the services bound to the primary virtual server are DOWN.

The following diagrams show the conditions under which a virtual server transitions from one state
to another.

A service can take the following states:

• UP: If probes from all the monitors bound to the service are successful.
• DOWN: If monitoring probes to the service are not answered within the configured time limit.
• OUT OF SERVICE: If you administratively disable the service, or if you gracefully shut down the
service and there are no active transactions to the service
• GOING OUT OF SERVICE (TROFS): If you administratively disable the service with delay, or
gracefully shut down the service and there are active transactions to the service. For more in-
formation, see Graceful Shut down of Services.
• DOWN WHEN GOING OUT OF SERVICE (TROFS_DOWN)[] A monitoring probe fails while the
service is in the GOING OUT OF SERVICE state.

A service in the process of transitioning from UP to OFS is in the GOING OUT OF SERVICE state. A service
transitioning from DOWN to OFS is in the DOWN WHEN GOING OUT OF SERVICE state. For example, if
a service is DOWN and you disable it with delay, the service transitions to DOWN WHEN GOING OUT
OF SERVICE and then to the OUT OF SERVICE state. If a service is UP and you disable it with delay, the
service transitions to GOING OUT OF SERVICE. During this time, if a monitoring probe to the server
fails, the service transitions to DOWN WHEN GOING OUT OF SERVICE and, after the delay time expires,
enters the OFS state.
Note

You can configure spillover to a backup virtual server by setting the “healthThreshold” param-
eter to a non-zero positive value. Then, if a single service bound to the primary virtual server
transitions to the DOWN WHEN GOING OUT OF SERVICE state and the health threshold is not
reached, the primary virtual server is marked DOWN and new connections are directed to the
backup virtual server.

The following diagrams show the conditions under which a service transitions from one state to an-
other.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2376

NetScaler 12.0

Support for load balancing profile

September 14, 2018

Contributed by:
C

A load balancing configuration has a large number of parameters, so setting the same parameters on
a number of virtual servers can become tedious. From release 11.1, a load balancing (LB) profile makes
this task easier. You can now set load balancing parameters in a profile and associate this profile with
virtual servers, instead of setting these parameters on each virtual server.

The following parameters are presently supported in an LB profile:

• HTTPonlyflag—Include the HttpOnly attribute in persistence cookies. The HttpOnly attribute

limits the scope of a cookie to HTTP requests and helps mitigate the risk of cross-site scripting
attacks.
• UseSecuredPersistenceCookie—Encrypt the persistence cookie values by using a SHA2 hash al-
gorithm.
• Cookiepassphrase—Specify the passphrase used to generate a secured persistence cookie
value.
• DBS_LB—Enable database specific load balancing for MySQL and MSSQL service types.
• Cl_process_local—Packets destined to a virtual server in a cluster are not steered. Enable option
for single packet request response mode or when the upstream device is performing a proper
RSS for connection based distribution.
Note

You can set DBS_LB and Cl_process_local parameters on a virtual server and in the profile. If
you enable these parameters on a virtual server and then set a profile to this virtual server, the
parameters appear as disabled in the output of the “show lb vserver” command for that virtual
server. Check the profile to see the actual status of these parameters. In addition, if you set and
then unset a profile to a virtual server, the parameters will be set with default values for that
virtual server.

To create an LB profile by using the CLI

At the command prompt, type:

1 add lb profile <lbprofilename> -dbsLb ( ENABLED | DISABLED ) -

processLocal ( ENABLED | DISABLED ) -httpOnlyCookieFlag ( ENABLED |
DISABLED ) -cookiePassphrase -useSecuredPersistenceCookie ( ENABLED
| DISABLED )

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2377

NetScaler 12.0

Example:

1 add lb profile p1
2
3 Done
4
5 show lb profile p1
6
7 LB Profile name:                 p1
8
9 DBS LB : DISABLED        Process Local: DISABLED
10
11 Persistence Cookie HttpOnly Flag: ENABLED
12
13 Use Secured Persistence Cookie Flag: DISABLED
14
15 No of vservers bound: 0
16
17 Done

To create an LB profile by using the GUI

Navigate to System > Profiles > LB Profile, and add a profile.

To associate an LB profile with an LB virtual server by using the CLI

At the command prompt, type:

1 set lb vserver <name> -lbprofilename <string>

Example

1 set lbvserver lbvip1 -lbprofile p1

2
3 Done
4
5 sh lb vserver lbvip1
6
7 lbvip1 (203.0.113.1:80) - HTTP       Type: ADDRESS
8 State: UP
9 Last state change was at Wed May 25 12:36:20 2016
10 Time since last state change: 0 days, 00:01:26.140
11 Effective State: UP  ARP:DISABLED

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2378

NetScaler 12.0

12 Client Idle Timeout: 180 sec

13 Down state flush: ENABLED
14 Disable Primary Vserver On Down : DISABLED
15 Appflow logging: ENABLED
16 Port Rewrite : DISABLED
17 No. of Bound Services :  2 (Total)       2 (Active)
18 Configured Method: LEASTCONNECTION      BackupMethod: ROUNDROBIN
19 Mode: IP
20 Persistence: NONE
21 Vserver IP and Port insertion: OFF
22 Push: DISABLED  Push VServer:
23 Push Multi Clients: NO
24 Push Label Rule: none
25 L2Conn: OFF
26 Skip Persistency: None
27 Listen Policy: NONE
28 IcmpResponse: PASSIVE
29 RHIstate: PASSIVE
30 New Service Startup Request Rate: 0 PER_SECOND, Increment Interval: 0
31 Mac mode Retain Vlan: DISABLED
32 DBS_LB: DISABLED
33 Process Local: DISABLED
34 Traffic Domain: 0
35 LB Profile: p1
36 Done

To associate an LB profile with an LB virtual server by using the GUI

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.

2. Select a virtual server, and click Edit.
3. In Advanced Settings, click Profiles.
4. In the LB Profile list, select the profile to associate with this virtual server.

1.
2. Citrix ADC
3. NetScaler 12.0

Load balancing algorithms

September 14, 2018

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2379

NetScaler 12.0

Contributed by:
C

The load balancing algorithm defines the criteria that the NetScaler appliance uses to select the ser-
vice to which to redirect each client request. Different load balancing algorithms use different criteria.
For example, the least connection algorithm selects the service with the fewest active connections,
while the round robin algorithm maintains a running queue of active services, distributes each con-
nection to the next service in the queue, and then sends that service to the end of the queue.

Some load balancing algorithms are best suited to handling traffic on websites, others to managing
traffic to DNS servers, and others to handling complex web applications used in e-commerce or on
company LANs or WANs. The following table lists each load balancing algorithm that the NetScaler
appliance supports, with a brief description of how each operates.

Name Server selection based on

LEASTCONNECTION Which service currently has the fewest client

connections. This is the default load balancing
algorithm.
ROUNDROBIN Which service is at the top of a list of services.
After that service is selected for a connection, it
moves to the bottom of the list.
LEASTRESPONSETIME Which load balanced server currently has the
quickest response time.
URLHASH A hash of the destination URL.
DOMAINHASH A hash of the destination domain.
DESTINATIONIPHASH A hash of the destination IP address.
SOURCEIPHASH A hash of the source IP address.
SRCIPDESTIPHASH A hash of the source and destination IP
addresses.
CALLIDHASH A hash of the call ID in the SIP header.
SRCIPSRCPORTHASH A hash of the client’s IP address and port.
LEASTBANDWIDTH Which service currently has the fewest
bandwidth constraints.
LEASTPACKETS Which service currently is receiving the fewest
packets.
CUSTOMLOAD Data from a load monitor.
TOKEN The configured token.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2380

NetScaler 12.0

Name Server selection based on

LRTM Fewest active connections and the lowest

average response time.

Depending on the protocol of the service that it is load balancing, the NetScaler appliance sets up each
connection between client and server to last for a different time interval. This is called load balancing
granularity, of which are three types: request-based, connection-based, and time-based granularity.
The following table describes each type of granularity and when each is used.

Types of Load Balanced

Granularity Service Specifies

Request -based HTTP or HTTPS A new service is chosen for

each HTTP request,
independent of TCP
connections. As with all HTTP
requests, after the Web server
fulfills the request, the
connection is closed.
Connection-based TCP and TCP-based protocols A service is chosen for every
other than HTTP new TCP connection. The
connection persists until
terminated by either the
service or the client.
Time-based UDP and other IP protocols A new service is chosen for
each UDP packet. Upon
selection of a service, a
session is created between
the service and a client for a
specified period of time.
When the time expires, the
session is deleted and a new
service is chosen for any
additional packets, even if
those packets come from the
same client.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2381

NetScaler 12.0

During startup of a virtual server, or whenever the state of a virtual server changes, the virtual server
can initially use the round robin method to distribute the client requests among the physical servers.
This type of distribution, referred to as startup round robin, helps prevent unnecessary load on a single
server as the initial requests are served. After using the round robin method at the startup, the virtual
server switches to the load balancing method specified on the virtual server.
The Startup RR Factor works in the following manner:
• If the Startup RR Factor is set to zero, the appliance switches to the specified load balancing
method depending on the request rate.
• If the Startup RR Factor is any number other than zero, the appliance uses the round robin
method for the specified number of requests before switching to the specified load balancing
method.
• By default, the Startup RR Factor is set to zero.
Note: You cannot set the startup RR Factor for an individual virtual server. The value you specify ap-
plies to all the virtual servers on the NetScaler appliance.

To set the startup round-robin factor by using the CLI

At the command prompt, type:

set lb parameter -startupRRFactor
Example
set lb parameter -startupRRFactor 25000

To set the startup round-robin factor by using the GUI

1. Navigate to Traffic Management > Load Balancing > Configure Load Balancing Parameters, and
set the Startup RR Factor.
1.
2. Citrix ADC
3. NetScaler 12.0

Least connection method

January 6, 2019
Contributed by:
C

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2382

NetScaler 12.0

When a virtual server is configured to use the least connection load balancing algorithm (or method),
it selects the service with the fewest active connections. This is the default method, because, in most
circumstances, it provides the best performance.

For TCP, HTTP, HTTPS, and SSL_TCP services, the NetScaler appliance includes the following connec-
tion types in its list of existing connections:

• Active connections to a service. Connections representing requests that a client has sent to
the virtual server and that the virtual server has forwarded to a service. For HTTP and HTTPS
services, active connections represent only those HTTP or HTTPS requests that have not yet
received a response.
• Waiting connections in the surge queue. Any connections to the virtual server that are waiting
in a surge queue and have not yet been forwarded to a service. Connections can build up in the
surge queue at any time, for any of the following reasons:
– Your services have connection limits, and all services in your load balancing configuration
are at that limit.
– The surge protection feature is configured and has been activated by a surge in requests
to the virtual server.
– The load-balanced server has reached an internal limit and therefore does not open any
new connections. (For example, an Apache server’s connection limit is reached.)

When a virtual server uses the least connection method, it considers the waiting connections as be-
longing to the specific service. Therefore, it does not open new connections to those services.

For UDP services, the connections that the least connection algorithm considers include all sessions
between the client and a service. These sessions are logical, time-based entities. When the first UDP
packet in a session arrives, the NetScaler appliance creates a session between the source IP address
and port and the destination IP address and port.

For Real-Time Streaming Protocol (RTSP) connections, the NetScaler appliance uses the number of
active control connections to determine the lowest number of connections to an RTSP service.

The following example shows how a virtual server selects a service for load balancing by using the
least connection method. Consider the following three services:

• Service-HTTP-1 is handling 3 active transactions.

• Service-HTTP-2 is handling 15 active transactions.
• Service-HTTP-3 is not handling any active transactions.

The following diagram illustrates how the NetScaler appliance forwards incoming requests when us-
ing the least connection method.

Figure 1. Mechanism of the Least Connections Load Balancing Method

In this diagram, the virtual server selects the service for each incoming connection by choosing the
server with the fewest active transactions.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2383

NetScaler 12.0

Connections are forwarded as follows:

• Service-HTTP-3 receives the first request, because it is not handling any active transactions.

Note: The service with no active transaction is selected first.

• Service-HTTP-3 receives the second and third requests because the service has the next least
number of active transactions.

• Service-HTTP-1 receives the fourth request Because Service-HTTP-1 and Service-HTTP-3 have
same number of active transactions, the virtual server uses the round robin method to choose
between them.

• Service-HTTP-3 receives the fifth request.

• Service-HTTP-1 receives the sixth request, and so on, until both Service-HTTP-1 and Service-
HTTP-3 are handling the same number of requests as Service-HTTP-2. At that time, the
NetScaler appliance starts forwarding requests to Service-HTTP-2 when it is the least loaded
service or its turn comes up in the round robin queue.

Note: If connections to Service-HTTP-2 close, it might get new connections before each of the
other two services has 15 active transactions.

The following table explains how connections are distributed in the three-service load balancing setup
described above.

Current Number of
Incoming Connection Service Selected Active Connections Remarks

Request-1 Service-HTTP-3; (N = 1 Service-HTTP-3 has

0) the fewest active
connections.
Request-2 Service-HTTP-3; (N = 2 Service-HTTP-3 has
1) the fewest active
connections.
Request-3 Service-HTTP-3; (N = 3 -
2)
Request-4 Service-HTTP-1; (N = 4 Service-HTTP-1 and
3) Service-HTTP-3 have
the same number of
active connections.
Request-5 Service-HTTP-3; (N = 4 Service-HTTP-1 and
3) Service-HTTP-3 have
the same number of
active connections.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2384

NetScaler 12.0

Current Number of
Incoming Connection Service Selected Active Connections Remarks

Request-6 Service-HTTP-1;(N = 5 -
4)
Request-7 Service-HTTP-3; (N = 5 -
4)
Request-8 Service-HTTP-1; (N = 6 -
5)

Service-HTTP-2 is selected for load balancing when it completes its active transactions and the current
connections to it close, or when the other services (Service-HTTP-1 and Service-HTTP-3) have 15 or
more connections each.

The NetScaler appliance can also use the least connection method when weights are assigned to ser-
vices. It selects a service by using the value (Nw) of the following expression:

Nw = (Number of active transactions) * (10000 / weight)

The following example shows how the NetScaler appliance selects a service for load balancing by
using the least connection method when weights are assigned to services. In the preceding exam-
ple, suppose Service-HTTP-1 is assigned a weight of 2, Service-HTTP-2 is assigned a weight of 3, and
Service-HTTP-3 is assigned a weight of 4. Connections are forwarded as follows:

• Service-HTTP-3 receives the first because the service is not handling any active transactions.

Note: If services are not handling any active transactions, the NetScaler appliance uses the
round robin method regardless of the weights assigned to each of the services.

• Service-HTTP-3 receives the second, third, fourth, fifth, sixth, and seventh requests because the
service has lowest Nw value.

• Service-HTTP-1 receives the eighth request. Because Service-HTTP-1 and Service-HTTP-3 now
have same Nw value, the appliance performs load balancing in a round robin manner. There-
fore, Service-HTTP-3 receives the ninth request.

The following table explains how connections are distributed on the three-service load balancing
setup that is described above.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2385

NetScaler 12.0

Current Nw (Number
of active
transactions) * (10000
Request Received Service Selected / weight) value Remarks

Request-1 Service-HTTP-3; (Nw Nw = 2500 Service-HTTP-3 has

= 0) the lowest Nw value.
Request-2 Service-HTTP-3; (Nw Nw = 5000
= 2500)
Request-3 Service-HTTP-3; (Nw Nw = 7500
= 5000)
Request-4 Service-HTTP-3; (Nw Nw = 10000
= 7500)
Request-5 Service-HTTP-3; (Nw Nw = 12500
= 10000)
Request-6 Service-HTTP-3; (Nw Nw = 15000
= 12500)
Request-7 Service-HTTP-1; (Nw = Nw = 20000 Service-HTTP-1 and
15000) Service-HTTP-3 have
the same Nw values
Request-8 Service-HTTP-3; (Nw Nw = 17500
= 15000)

Service-HTTP-2 is selected for load balancing when it completes its active transactions or when the
Nw value of other services (Service-HTTP-1 and Service-HTTP-3) is equal to 50000.

The following diagram illustrates how the NetScaler appliance uses the least connection method when
weights are assigned to the services.

Figure 2. Mechanism of the Least Connections Load Balancing Method when Weights are Assigned

To configure the least connection method, see Configuring a Load Balancing Method that Does Not
Include a Policy.

1.
2. Citrix ADC
3. NetScaler 12.0

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2386

NetScaler 12.0

Round robin method

January 6, 2019

Contributed by:
C

When a load balancing virtual server is configured to use the round robin method, it continuously
rotates a list of the services that are bound to it. When the virtual server receives a request, it assigns
the connection to the first service in the list, and then moves that service to the bottom of the list.

The following diagram illustrates how the NetScaler appliance uses the round robin method with a
load balancing setup that contains three load-balanced servers and their associated services.

Figure 1. How the Round Robin Load Balancing Method Works

If you assign a different weight to each service, the NetScaler appliance performs weighted round
robin distribution of incoming connections. It does this by skipping the lower-weighted services at
appropriate intervals.

For example, assume that you have a load balancing setup with three services. You set Service-HTTP-1
to a weight of 2, Service-HTTP-2 to a weight of 3, and Service-HTTP-3 to a weight of 4. The services are
bound to Vserver-LB-1, which is configured to use the round robin method. With this setup, incoming
requests are delivered as follows:

• Service-HTTP-1 receives the first request.

• Service-HTTP-2 receives the second request.
• Service-HTTP-3 receives the third request.
• Service-HTTP-1 receives the fourth request.
• Service-HTTP-2 receives the fifth request.
• Service-HTTP-3 receives the sixth request.
• Service-HTTP-2 receives the seventh request.
• Service-HTTP-3 receives both the eighth and the ninth requests.

Note: You can also configure weights on services to prevent multiple services from using the same
server and overloading the server.

A new cycle then begins, using the same pattern.

The following diagram illustrates the weighted round robin method.

Figure 2. How the Round Robin Load Balancing Method Works with Weighted Services

To configure the round robin method, see Configuring a Load Balancing Method that Does Not Include
a Policy.

1.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2387

NetScaler 12.0

2. Citrix ADC
3. NetScaler 12.0

Least response time method

January 6, 2019

Contributed by:
C

When the load balancing virtual server is configured to use the least response time method, it selects
the service with the fewest active connections and the lowest average response time. You can con-
figure this method for HTTP and Secure Sockets Layer (SSL) load balancing virtual servers only. The
response time (also called Time to First Byte, or TTFB) is the time interval between sending a request
packet to a service and receiving the first response packet from the service. The NetScaler appliance
uses response code 200 to calculate TTFB.

The following example shows how a virtual server selects a service for load balancing by using the
least response time method. Consider the following three services:

• Service-HTTP-1 is handling three active transactions and TTFB is two seconds.

• Service-HTTP-2 is handling seven active transactions and TTFB is one second.
• Service-HTTP-3 is not handling any active transactions and TTFB is two seconds.

The following diagram illustrates how the NetScaler appliance uses the least response time method
to forward the connections.

Figure 1. How the Least Response Time Load Balancing Method Works

The virtual server selects a service by multiplying the number of active transactions by the TTFB for
each service and then selecting the service with the lowest result. For the example shown above, the
virtual server forwards requests as follows:

• Service-HTTP-3 receives the first request, because the service is not handling any active trans-
actions.
• Service-HTTP-3 also receives the second and third requests, because the result is lowest of the
three services.
• Service-HTTP-1 receives the fourth request. Since Service-HTTP-1 and Service-HTTP-3 have
the same result, the NetScaler appliance chooses between them by applying the Round Robin
method.
• Service-HTTP-3 receives the fifth request.
• Service-HTTP-2 receives the sixth request, because at this point it has the lowest result.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2388

NetScaler 12.0

• Because Service-HTTP-1, Service-HTTP-2, and Service-HTTP-3 all have the same result at this
point, the appliance switches to the round robin method, and continues to distribute connec-
tions using that method.

The following table explains how connections are distributed in the three-service load balancing setup
described above.

Current N Value
(Number of Active
Request Received Service Selected Transactions * TTFB) Remarks

Request-1 Service-HTTP-3;(N = N=2 Service-HTTP-3 has

0) the lowest N value.
Request-2 Service-HTTP-3; (N = N=4 Service-HTTP-3 has
2) the lowest N value.
Request-3 Service-HTTP-3; (N = N=6 Service-HTTP-3 has
4) the lowest N value.
Request-4 Service-HTTP-1; (N = N=8 Service-HTTP-1 and
6) Service-HTTP-3 have
the same N values.
The appliance uses
the round robin
method to distribute
the requests.
Request-5 Service-HTTP-3; (N = N=8 Service-HTTP-1 and
6) Service-HTTP-3 have
the same N values.
Request-6 Service-HTTP-2; (N = N=8 Service-HTTP-2 has
7) the lowest N value.
Request-7 Service-HTTP-3; (N = N = 10 Service-HTTP-
8) 1,Service-HTTP-2 and
Service-HTTP-3 have
the same N values.
The NetScaler
appliance uses the
round robin method
to distribute the
requests.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2389

NetScaler 12.0

Current N Value
(Number of Active
Request Received Service Selected Transactions * TTFB) Remarks

Request-8 Service-HTTP-1; (N = N = 10 Service-HTTP-1 and

8) Service-HTTP-2 have
the same N values,
the appliance uses
the round robin
method to distribute
the requests.

Service-HTTP-1 is again selected for load balancing when it completes its active transactions or when
its N value is less than the other services (Service-HTTP-2 and Service-HTTP-3).

Selection of services when weights are assigned

The following diagram illustrates how the NetScaler appliance uses the least response time method
when weights are assigned.

Figure 2. How the Least Response Time Load Balancing Method Works When Weights Are Assigned

The virtual server selects a service by using the value (Nw) in the following expression:

Nw = (N) * (10000 / weight)

Where N = (number of active transactions * TTFB)

Suppose Service-HTTP-1 is assigned a weight of 2, Service-HTTP-2 is assigned weight of 3, and Service-

HTTP-3 is assigned weight of 4.

The NetScaler appliance distributes requests as follows:

• Service-HTTP-3 receives the first request, because it is not handling any active transactions.

If services are not handling any active transactions, the appliance selects them regardless of the
weights assigned to them.

• Service-HTTP-3 receives the second, third, fourth, and fifth requests, because this service has
the lowest Nw value.

• Service-HTTP-2 receives the sixth request, because this service has the lowest Nw value.

• Service-HTTP-3 receives the seventh request, because this service has the lowest Nw value.

• Service-HTTP-2 receives the eighth request, because this service has the lowest Nw value.

© 1999-2018 Citrix Systems, Inc. All rights reserved. 2390

NetScaler 12.0

Service-HTTP-1 has the lowest weight and therefore the highest Nw value, so the virtual server does
not select it for load balancing.

The following table explains how connections are distributed in the three-service load balancing setup
described above.

Current Nw Value =
Request Received Service Selected (N) * (10000 / Weight) Remarks

Request-1 Service-HTTP-3; (Nw Nw = 5000 Service-HTTP-3 has

= 0) the lowest Nw value.
Request-2 Service-HTTP-3; (Nw Nw = 10000 Service-HTTP-3 has
= 5000 the lowest Nw value.
Request-3 Service-HTTP-3; (Nw Nw = 15000 Service-HTTP-3 has
= 10000) the lowest Nw value.
Request-4 Service-HTTP-3; (Nw Nw = 20000 Service-HTTP-3 has
= 15000) the lowest Nw value.
Request-5 Service-HTTP-3; (Nw Nw = 25000 Service-HTTP-3 has
= 20000) the lowest Nw value.
Request-6 Service-HTTP-2; (Nw Nw = 26666.67 Service-HTTP-2 has
= 23333.34) the lowest Nw value.
Request-7 Service-HTTP-3; (Nw Nw= 30000 Service-HTTP-3 has