Deploying a NetScaler CPX Instance in Docker

Last published : Sep 02, 2026
NetScaler CPX instances are available as a Docker image file in the Quay container registry. To deploy an instance, download the NetScaler CPX image from the Quay container registry and then deploy the instance by using the docker run command or the Docker compose tool.

Prerequisites

Make sure that:
  • Docker host system has at least:
    • 1 CPU
    • 2 GB RAM
      Note:
      For better NetScaler CPX performance, you can define the number of processing engines that you want the NetScaler CPX instance to start. For every additional processing engine, you add, make sure that the Docker host contains the equivalent number of vCPUs and amount of memory in GB. For example, if you want to add 4 processing engines, the Docker host must contain 4 vCPUs and 4 GB of memory.
  • Docker host system is running Linux Ubuntu version 14.04 or later.
  • Docker version 1.12 is installed on the host system. For information about Docker installation on Linux, see the Docker Documentation.
  • Docker host has Internet connectivity.
    Note: NetScaler CPX has issues while running on ubuntu version 16.04.5, kernel version 4.4.0-131-generic. So, it is not recommended to run NetScaler CPX on ubuntu version 16.04.5 kernel version 4.4.0-131-generic.
    Note: The following kubelet and kube-proxy versions have some security vulnerabilities and it is not recommended to use NetScaler CPX with these versions:
    • kubelet/kube-proxy v1.18.0-1.18.3
    • kubelet/kube-proxy v1.17.0-1.17.6
    • kubelet/kube-proxy <=1.16.10
    For information on how to mitigate this vulnerability, see Mitigate this vulnerability.

Downloading NetScaler CPX Image from Quay

You can download the NetScaler CPX image from the Quay container registry using the docker pull command and deploy it on your environment. Use the following command to download the NetScaler CPX image from the Quay container registry:
docker pull quay.io/citrix/citrix-k8s-cpx-ingress:13.0-xx.xx
For example, if you want to download the version 13.0-64.35, then use the following command:
docker pull quay.io/citrix/citrix-k8s-cpx-ingress:13.0-64.35
Use the following command to verify if the NetScaler CPX image is installed in docker images:
root@ubuntu:~# docker images | grep 'citrix-k8s-cpx-ingress'
quay.io/citrix/citrix-k8s-cpx-ingress                  13.0-64.35          952a04e73101        2 months ago        469 MB
You can deploy the latest NetScaler CPX image from the Quay container registry.

Deploying the NetScaler CPX Instance Using the docker run Command

On the host, you can install a NetScaler CPX instance in the Docker container by using the NetScaler CPX Docker image that you loaded onto the host. Using the docker run command, install the NetScaler CPX instance with the default NetScaler CPX configuration.
Install the NetScaler CPX instance on the Docker container by using the following docker run command:
docker run -dt -P --privileged=true --net=host –e NS_NETMODE=”HOST” -e CPX_CORES=<number of cores> --name <container_name> --ulimit core=-1 -e CPX_NW_DEV='<INTERFACES>' -e CPX_CONFIG=’{“YIELD”:”NO”}’ -e LS_IP=<LS_IP_ADDRESS> -e LS_PORT=<LS_PORT> e PLATFORM=CP1000 -v <host_dir>:/cpx --name <cpx_container_name> <REPOSITORY>:<CPX-IMAGE_TAG_IN_QUAY>docker run -dt --privileged=true --net=host -e NS_NETMODE="HOST" -e CPX_NW_DEV='eth1 eth2' -e CPX_CORES=5 –e CPX_CONFIG='{"YIELD":"No"}' -e LS_IP=10.102.38.134 -e PLATFORM=CP1000 -v /var/cpx:/cpx --name cpx_host quay.io/citrix/citrix-k8s-cpx-ingress:14.1-x.x
This example creates a container named mycpx based on the NetScaler CPX Docker image.
The -P parameter is mandatory. It tells Docker to map the ports exposed in the container by the NetScaler CPX Docker image. That means mapping ports 9080, 22, 9443, and 161/UDP, to the ports on the Docker host that are randomly selected from the user-defined range. This mapping is done to avoid conflicts. If you later create multiple NetScaler CPX containers on the same Docker host. The port mappings are dynamic and are set each time the container is started or restarted. The ports are used as follows:
  • 9080 is used for HTTP
  • 9443 is used for HTTPs
  • 22 used for SSH
  • 161/UDP is used for SNMP.
If you want static port mappings, use the -p parameter to set them manually.
The --privileged=true option is used to run the container in privileged mode. If you are running the NetScaler CPX in Host mode of deployment then you need to provide all the system privileges to the NetScaler CPX.
To run the NetScaler CPX in bridge mode with a single or multiple cores, you can use the --cap-add=NET_ADMIN option instead of the privileged mode. The --cap-add=NET_ADMIN option enables you to run the NetScaler CPX container with full network privileges. With the --cap-add=NET_ADMIN option, use the --sysctl kernel.shmmax=1073741824 --sysctl net.ipv6.conf.default.accept_dad=0 --sysctl kernel.core_pattern=/var/crash/core.%e.%p.%s option in the docker run command to do the additional system control settings manually. These additional system control settings aren't done automatically under any non-privileged modes.
The**--net=host is a standard docker run command option that specifies that the container is running in the host network stack and has access to all the network devices.
Note
Ignore this option, if you are running NetScaler CPX in bridge or none network.
The -e NS_NETMODE="HOST" is a NetScaler CPX specific environment variable that allows you to specify that the NetScaler CPX is started in host mode. Once NetScaler CPX starts in host mode it configures 4 default iptables rules on a host machine for management access to the NetScaler CPX. It uses the following ports:
  • 9995 for HTTP
  • 9996 for HTTPS
  • 9997 for SSH
  • 9998 for SNMP
If you want to specify different ports, you can use the following environment variables:
  • -e NS_HTTP_PORT=
  • -e NS_HTTPS_PORT=
  • -e NS_SSH_PORT=
  • -e NS_SNMP_PORT=
Note
Ignore this environment variable, if you are running NetScaler CPX in bridge or none network.
The -e CPX_CORES is an optional NetScaler CPX specific environment variable. You can use it to improve the performance of the NetScaler CPX instance by defining the number of processing engines that you want the NetScaler CPX container to start.
Notes:
  • For every additional processing engine you add, make sure that the Docker host contains the equivalent number of vCPUs and amount of memory in GB. For example, if you want to add 4 processing engines, then the Docker host must contain 4 vCPUs and 4 GB of memory.
  • NetScaler CPX can support from 1 to 16 cores.
The -e EULA = yes is a mandatory NetScaler CPX specific environment variable, which is required to verify that you have read and understand the End User License Agreement (EULA) available at: The Citrix licensing system components.
The -e PLATFORM=CP1000 parameter specifies the NetScaler CPX license type.
If you are running Docker in a host network, you can assign dedicated network interfaces to the NetScaler CPX container using the -e CPX_NW_DEV environment variable. You need to define the network interfaces separated by a whitespace. The network interfaces that you define are held by the NetScaler CPX container until you uninstall the NetScaler CPX container. When the NetScaler CPX container is provisioned all the assigned network interfaces are added to the NetScaler networking namespace.
Note
If you are running NetScaler CPX in bridge network you may change the container network, such as, configure another network connection to the container or remove an existing network. Then make sure that you restart the NetScaler CPX container to use the updated network.
docker run -dt --privileged=true --net=host -e NS_NETMODE="HOST" -e EULA=yes -e CPX_NW_DEV='eth1 eth2' -e CPX_CORES=5 -e PLATFORM=CP1000 --name cpx_host cpx:13.0-x.x
The -e CPX_CONFIG is a NetScaler CPX specific environment variable that enables you to control the throughput performance of the NetScaler CPX container. When the NetScaler CPX does not receive any incoming traffic to process, it yields the CPU during this idle time, hence resulting in low throughput performance. You can use the CPX_CONFIG environment variable to control the throughput performance of the NetScaler CPX container in such scenarios. You need to provide following values to the CPX_CONFIG environment variable in JSON format:
  • If you want the NetScaler CPX container to yield CPU in idle scenarios, define {"YIELD” : “Yes”}
  • If you want the NetScaler CPX container to avoid yielding the CPU in idle scenarios so that you can get high throughput performance, define {“YIELD” : “No”}
docker run -dt --privileged=true --net=host -e NS_NETMODE="HOST" -e EULA=yes -e CPX_CORES=5 –e CPX_CONFIG='{"YIELD":"No"}' -e PLATFORM=CP1000 --name cpx_host cpx:13.0-x.xdocker run -dt --privileged=true --net=host -e NS_NETMODE="HOST" -e EULA=yes -e CPX_CORES=5 –e CPX_CONFIG='{"YIELD":"Yes"}' -e PLATFORM=CP1000 --name cpx_host cpx:13.0-x.x
The –v parameter is an optional parameter that specifies the mount point of the NetScaler CPX mount directory, /cpx. A mount point is a directory on the host, in which you mount the /cpx directory. The /cpx directory stores the logs, configuration files, SSL certificates, and core dump files. In the example, the mount point is /var/cpx and the NetScaler CPX mount directory is /cpx.
If you purchased a license or have an evaluation license, you can upload the license to a license server and specify the license server location with the docker run command, by using the -e LS_IP=<LS_IP_ADDRESS> -e LS_PORT=<LS_PORT> parameter. In this case, you do not need to accept the EULA.
docker run -dt --privileged=true --net=host -e NS_NETMODE="HOST" -e CPX_CORES=5 –e CPX_CONFIG='{"YIELD":"No"}' -e LS_IP=10.102.38.134 -e PLATFORM=CP1000 --name cpx_host cpx:13.0-x.x
Where:
  • LS_IP_ADDRESS is the IP address of the license server.
  • LS_PORT is the port of the license server.
You can view the images running on your system and the ports mapped to the standard ports by using the command: docker ps

Deploying a Lighter Version of NetScaler CPX Using the docker run Command

NetScaler provides a lighter version of NetScaler CPX which consumes lesser runtime memory. The lighter version of NetScaler CPX can be deployed as a sidecar in service-mesh deployments.
The lighter version of NetScaler CPX supports the following features:
  • Application availability
    • L4 load balancing and L7 content switching
    • SSL Offloading
    • IPv6 protocol translation
  • Application security
    • L7 rewrite and responder
  • Simple manageability
    • Web logging
    • AppFlow®
To instantiate the lighter version of NetScaler CPX, set the NS_CPX_LITE environment variable while executing the Docker run command.
docker run -dt -P --privileged=true -e NS_CPX_LITE=1 -e EULA=yes --name <container_name> --ulimit core=-1 <REPOSITORY>:<TAG>
The following example creates a lightweight container based on the NetScaler CPX image.
docker run –dt -P --privileged=true -e NS_CPX_LITE=1 -e EULA=yes -–name lightweight --ulimit core=-1 cpx:latest
By default, logging using newnslog is disabled on the lighter version of NetScaler CPX. To enable it, you must set the NS_ENABLE_NEWNSLOG environment variable to 1 while bringing up the lighter version of NetScaler CPX.
The following example shows how to enable logging using newnslog while deploying the lighter version of NetScaler CPX.
docker run -dt --privileged=true --ulimit core=-1 -e EULA=yes -e NS_CPX_LITE=1 -e NS_ENABLE_NEWNSLOG=1 cpx:<tag>
Note: The lighter version of CPX supports only single core (CPX_CORES=1).

Deploying NetScaler CPX Instances by Using Docker Compose

You can use the Compose tool of Docker to provision a single NetScaler CPX instance or multiple NetScaler CPX instances. To provision NetScaler CPX instances by using Docker Compose, you must first write a compose file. This file specifies the NetScaler CPX image, the ports that you want to open for the NetScaler CPX instance, and the privileges for your NetScaler CPX instance.
Important
Make sure that you have installed Docker Compose tool on the host.
To provision multiple NetScaler CPX instances:
  1. Write a compose file, where:
  • \&lt;service-name> is the name of the service you want to provision.
  • image:\&lt;repository>:\&lt;tag> denotes the repository and the versions of the NetScaler CPX image.
  • privileged: true provides all root privileges to the NetScaler CPX instance.
  • cap_add provides network privileges to the NetScaler CPX instance.
  • \&lt;host_directory_path> denotes the directory on the docker host that you want to mount for the NetScaler CPX instance.
  • \&lt;number_processing_engine> is the number of processing engines that you want the NetScaler CPX instance to start. For every additional processing engine, make sure that the Docker host contains the equivalent number of vCPUs and amount of memory in GB. For example, if you want to add 4 processing engines, then the Docker host must contain 4 vCPUs and 4 GB of memory.
The compose file generally follows a format similar to:
<container_name>:
    image: <repository>:<tag>
    ports:
        -  9443
        -  22
        -  9080
        -  161/udp
    tty: true
    cap_add:
        - NET_ADMIN
    ulimits:
        core: -1
    volumes:
        - <host_directory_path>:/cpx
    environment:
        - EULA=yes
        - CPX_CORES=<number_processing_engine>
        - CPX_CONFIG='{"YIELD":"Yes"}'CPX_0:
    image: quay.io/citrix/citrix-k8s-cpx-ingress:13.1-37.38
    ports:
        -  9443
        -  22
        -  9080
        -  161/udp
    tty: true
    cap_add:
        - NET_ADMIN
    ulimits:
        core: -1
    volumes:
        - /root/test:/cpx
    environment:
        -  CPX_CORES=2
        -  EULA=yes