Netscaler

---
name: netscaler
description: "Expert coverage of Citrix NetScaler ADC across all form factors and versions: MPX/VPX/CPX/SDX/BLX platforms, AppExpert policy engine, content switching, GSLB, SSL offload, compression/caching, NetScaler Console (ADM), Kubernetes CPX Ingress, NITRO API, and licensing migration. Use for \"NetScaler\", \"Citrix ADC\", \"NetScaler ADC\", \"MPX\", \"VPX\", \"CPX\", \"SDX\", \"AppExpert\", \"GSLB NetScaler\", \"NITRO API\", \"NetScaler Ingress\". Do NOT use for cross-vendor comparison, platform selection, or category-wide architecture -- use the `load-balancing` skill."
license: MIT
---

# Citrix NetScaler ADC

This skill covers Citrix NetScaler ADC (formerly Citrix ADC) across all form factors and current versions (14.1+). Areas of expertise include:

- Form factors: MPX (hardware), VPX (virtual), CPX (container), SDX (multi-tenant), BLX (bare-metal)
- AppExpert policy engine: PI expressions, rewrite, responder, content switching, rate limiting
- Content Switching: vServer-based L7 routing, priority-based policy evaluation
- GSLB: DNS-based geographic load balancing, MEP, GSLB sites, topology records
- SSL/TLS: Hardware-accelerated SSL offload (MPX), cipher management, mTLS, OCSP stapling
- Compression and Integrated Caching: HTTP compression, in-memory content caching
- NetScaler Console (ADM): Centralized management, StyleBooks, analytics, config audit
- Kubernetes: CPX as Ingress Controller, Citrix Ingress Controller (CIC), K8s annotations
- NITRO API: RESTful automation interface for all NetScaler configuration
- Licensing: File-based licensing EOL (April 15, 2026), pooled/subscription migration

## How to Approach Tasks

1. **Classify** the request:
   - **Architecture** -- Load `references/architecture.md` for platform internals, form factor selection
   - **Traffic management** -- Virtual servers, pools, services, monitors, load balancing methods
   - **Policy / AppExpert** -- Rewrite, responder, content switching policies, PI expressions
   - **GSLB** -- Multi-site DNS load balancing, MEP, site configuration
   - **SSL/TLS** -- Certificate management, cipher suites, offload/bridging, mTLS
   - **Kubernetes** -- CPX deployment, CIC, Ingress annotations, service mesh
   - **Automation** -- NITRO API, StyleBooks, Terraform, Ansible
   - **Migration** -- Licensing migration, F5-to-NetScaler, version upgrades

2. **Identify form factor** -- MPX, VPX, CPX, SDX, or BLX. Configuration is mostly identical but performance characteristics and deployment models differ.

3. **Load context** -- Read `references/architecture.md` for deep platform knowledge.

4. **Analyze** -- Apply NetScaler-specific reasoning. Consider AppExpert policy evaluation order, content switching precedence, and platform-specific limitations.

5. **Recommend** -- Provide actionable guidance with NetScaler CLI commands, NITRO API calls, or policy configurations.

6. **Verify** -- Suggest validation steps (show commands, stat commands, nsconmsg traces).

## Form Factors

| Form Factor | Description | Use Case |
|---|---|---|
| **MPX** | Physical hardware with SSL ASICs | High-performance enterprise DC; hardware SSL offload |
| **VPX** | Virtual appliance (VMware, Hyper-V, KVM, XenServer) | Cloud and virtualized DCs; licensed by throughput tier |
| **CPX** | Container-based (Docker/Kubernetes) | Microservices ingress, sidecar proxy, CI/CD |
| **SDX** | Multi-tenant hardware; isolated VPX instances on single chassis | Service providers, shared infrastructure |
| **BLX** | Bare-metal software on standard Linux servers | High performance without hypervisor overhead |

## AppExpert Policy Engine

### Policy Language

- **Default Syntax Policies (PI)** -- Legacy policy engine; limited expressions
- **Advanced Policies (AppExpert)** -- Full-featured expression language for traffic inspection
- **PI Expressions** -- Access request attributes: `HTTP.REQ.URL`, `HTTP.REQ.HEADER("X-Forwarded-For")`, `CLIENT.IP.SRC`, `HTTP.REQ.BODY(2048)`

### Policy Types

| Policy Type | Purpose | Example |
|---|---|---|
| **Rewrite** | Modify request/response headers, URL, body | Inject `X-Forwarded-Proto`, URL normalization |
| **Responder** | Generate synthetic responses | Maintenance pages, IP blocking, redirects |
| **Content Switching** | Route to different backend vServers | Path-based routing (/api, /static, /legacy) |
| **Rate Limiting** | Per-client or per-expression rate control | API rate limiting by token or IP |

### Policy Binding

Policies are bound to virtual servers at specific bind points:

```
add rewrite action ACT_ADD_XFF insert_http_header X-Forwarded-For CLIENT.IP.SRC
add rewrite policy POL_ADD_XFF true ACT_ADD_XFF
bind lb vserver VS_APP -policyName POL_ADD_XFF -priority 100 -type REQUEST
```

### Content Switching

```
# Create content switching vServer
add cs vserver CS_MAIN HTTP 10.0.0.100 80

# Create backend LB vServers
add lb vserver VS_API HTTP 0.0.0.0 0
add lb vserver VS_WEB HTTP 0.0.0.0 0

# Create CS policies
add cs policy POL_API -rule "HTTP.REQ.URL.STARTSWITH(\"/api\")"
add cs policy POL_WEB -rule "HTTP.REQ.URL.STARTSWITH(\"/web\")"

# Bind CS policies to CS vServer
bind cs vserver CS_MAIN -policyName POL_API -targetLBVserver VS_API -priority 100
bind cs vserver CS_MAIN -policyName POL_WEB -targetLBVserver VS_WEB -priority 200

# Default backend
bind cs vserver CS_MAIN -lbvserver VS_WEB
```

## GSLB (Global Server Load Balancing)

- DNS-based geographic load balancing across multiple data centers
- **GSLB Sites** -- Each DC has a NetScaler; sites exchange metrics via MEP
- **MEP (Metric Exchange Protocol)** -- Proprietary protocol for real-time metrics sharing between sites
- **GSLB Virtual Servers** -- Respond to DNS queries with "best" site IP

### GSLB Algorithms

| Algorithm | Description |
|---|---|
| Round Robin | DNS round-robin across sites |
| Least Connections | Prefer site with fewest active connections |
| RTT | Measured round-trip time via LDNS probes |
| Static Proximity | Geolocation database for client-to-site mapping |
| Persistence | Cookie or IP-based persistence to a site |

### GSLB Configuration

```
# Add GSLB sites
add gslb site SITE_NYC 203.0.113.10
add gslb site SITE_LON 198.51.100.10

# Add GSLB services
add gslb service SVC_NYC_APP SITE_NYC 203.0.113.10 HTTP 80
add gslb service SVC_LON_APP SITE_LON 198.51.100.10 HTTP 80

# Add GSLB vServer
add gslb vserver GSLB_APP HTTP
bind gslb vserver GSLB_APP -serviceName SVC_NYC_APP
bind gslb vserver GSLB_APP -serviceName SVC_LON_APP
set gslb vserver GSLB_APP -lbMethod ROUNDROBIN

# Bind domain
bind gslb vserver GSLB_APP -domainName app.example.com -TTL 30
```

## SSL Offload

- **Hardware acceleration** -- MPX appliances include dedicated SSL ASICs for TLS processing
- **TLS 1.0 through 1.3** -- Configurable per vServer; cipher suite management
- **SSL Bridging** -- Re-encrypt to backend (end-to-end TLS)
- **mTLS** -- Client certificate validation; extract cert fields into headers
- **Session Multiplexing** -- Reuse backend SSL sessions across client requests

```
# Add SSL certificate and key
add ssl certKey CERT_APP -cert /nsconfig/ssl/app.crt -key /nsconfig/ssl/app.key

# Bind certificate to vServer
bind ssl vserver VS_APP -certkeyName CERT_APP

# Configure cipher group
add ssl cipher CIPHER_MODERN
bind ssl cipher CIPHER_MODERN -cipherName TLS1.3-AES256-GCM-SHA384
bind ssl cipher CIPHER_MODERN -cipherName TLS1.2-ECDHE-RSA-AES256-GCM-SHA384

# Bind cipher group to vServer
set ssl vserver VS_APP -ssl3 DISABLED -tls1 DISABLED -tls11 DISABLED -tls12 ENABLED -tls13 ENABLED
bind ssl vserver VS_APP -cipherName CIPHER_MODERN
```

## NetScaler Console (ADM)

- **Centralized management** for multiple NetScaler instances
- **StyleBooks** -- Declarative configuration templates; deploy consistent config across fleet
- **Analytics** -- Web Insight, HDX Insight (Citrix VDI), Gateway Insight
- **Config Audit** -- Compliance checking against baseline configurations
- **Application Dashboard** -- End-to-end transaction monitoring; latency breakdown

## Kubernetes Integration

### CPX as Ingress Controller

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: netscaler-cpx
spec:
  template:
    spec:
      containers:
      - name: cpx
        image: quay.io/netscaler/netscaler-cpx:14.1
        ports:
        - containerPort: 80
        - containerPort: 443
```

### Citrix Ingress Controller (CIC)

- Reads Kubernetes Ingress resources and annotations
- Programs CPX (in-cluster) or MPX/VPX (external) accordingly
- NetScaler-specific annotations extend Ingress API: SSL redirect, rate limiting, rewrite, persistence

### Key Annotations

```yaml
metadata:
  annotations:
    ingress.citrix.com/insecure-termination: "redirect"
    ingress.citrix.com/secure-port: "443"
    ingress.citrix.com/lbmethod: "ROUNDROBIN"
    ingress.citrix.com/persistence: "COOKIEINSERT"
```

## NITRO API

### Basics

- **Base URL**: `https://<netscaler>/nitro/v1/`
- **Authentication**: HTTP Basic Auth or session-based (NITRO session token)
- **Format**: JSON

### Common Operations

```bash
# Get all LB vServers
curl -u nsroot:password "https://ns.example.com/nitro/v1/config/lbvserver"

# Create LB vServer
curl -u nsroot:password -X POST \
  "https://ns.example.com/nitro/v1/config/lbvserver" \
  -H "Content-Type: application/json" \
  -d '{"lbvserver":{"name":"VS_APP","servicetype":"HTTP","ipv46":"10.0.0.100","port":"80"}}'

# Add service
curl -u nsroot:password -X POST \
  "https://ns.example.com/nitro/v1/config/service" \
  -d '{"service":{"name":"SVC_APP1","ip":"192.168.1.10","servicetype":"HTTP","port":"8080"}}'

# Bind service to vServer
curl -u nsroot:password -X POST \
  "https://ns.example.com/nitro/v1/config/lbvserver_service_binding" \
  -d '{"lbvserver_service_binding":{"name":"VS_APP","servicename":"SVC_APP1"}}'

# Save config
curl -u nsroot:password -X POST \
  "https://ns.example.com/nitro/v1/config/nsconfig?action=save" \
  -d '{"nsconfig":{}}'
```

## Licensing Alert

**File-based licensing EOL: April 15, 2026.** Customers must migrate to pooled licensing or subscription before this date. Key migration steps:

1. Audit current license type (file-based vs pooled)
2. Contact Citrix/Cloud Software Group for license conversion
3. Apply new pooled/subscription license
4. Verify feature entitlements post-migration

## Common Pitfalls

1. **Content switching priority confusion** -- CS policies evaluate by priority number (lowest first). First match wins, with default vServer as fallback. Incorrect priority ordering causes misrouted traffic.

2. **Forgetting to save config** -- NetScaler configuration is in-memory until saved. A reboot without `save config` loses all changes since last save.

3. **SSL cipher mismatch** -- Binding a cipher group to a vServer replaces the default ciphers. Verify the cipher group includes ciphers supported by all clients.

4. **GSLB MEP connectivity** -- MEP requires TCP 3011 between GSLB sites. Firewall rules must allow this traffic for metrics exchange and health status sharing.

5. **CPX resource limits** -- CPX containers have lower throughput than VPX/MPX. Do not use CPX for high-throughput production traffic without understanding the performance ceiling.

6. **Rewrite policy ordering** -- Multiple rewrite policies on a vServer execute in priority order. Conflicting rewrites at different priorities cause unexpected behavior.

7. **Not monitoring license expiry** -- Subscription and pooled licenses have expiration dates. Expired licenses can disable features or reduce throughput.

8. **Ignoring file-based licensing EOL** -- After April 15, 2026, file-based licenses will not be supported. Plan migration well in advance.

## Reference Files

Load these when you need deep knowledge:

- `references/architecture.md` -- MPX/VPX/CPX/SDX/BLX internals, AppExpert deep dive, GSLB architecture, Kubernetes integration, ADM. Read for "how does X work" questions.