AAA-TM and NetScaler Gateway (NSG) subsystems of NetScaler do complex tasks which are not limited to processing request and swerving/modifying it before sending it to the protected resource. These modules act as authentication gateways consuming many protocol requests and protecting the backend resources from unauthorized access. In the process these subsystems generate a variety of error codes and messages to be consumed by the user/device.

For example, when a user accesses a protected resource the first time, NetScaler AAA-Traffic Management/ NetScaler Gateway subsystems redirects the user to a login page and presents them forms for user credentials. Note: This request is served by the NetScaler AAA-Traffic Management/ NetScaler Gateway subsystems themselves.

Apart from simple use cases such as a login redirect, there could be complex workflows before a user is granted access. The user can be denied access for a variety of reasons such as denied authorization, misconfiguration or internal errors such as memory allocation failures, invalid requests or some kind of invalid access.

There is a growing requirement of being able to make these error string customizable so that the user is presented with a rich experience.

This document describes a mechanism to be able to achieve that requirement. In the proposed solution, various error codes that are generated by NetScaler Gateway are categorized into a broad section of errors. These categories not only include the error conditions but also the derived errors such as authorization failures. Once the NetScaler Gateway handler returns an error, responder policies are evaluated to check for the error code returned. If there is a matching policy that checks for a particular error category, response to the user is generated by the responder action. Responder action is customizable; so the user can be presented with the appropriate error string.

• ERR_AAA_GENERIC: generic or unclassified errors
• ERR_AAA_ALLOC: alloc failures
• ERR_AAA_C2C: C2C issues
• ERR_AAA_POLICY: policy engine issues (mostly PE policies)
• ERR_AAA_CONFIG: missing config found at runtime
• ERR_AAA_IIP: issues while handling IIP connections or IIP allocations or transfer login
• ERR_AAA_AUTHN: authentication errors
• ERR_AAA_REASSEMBLY: reassembly issues
• ERR_AAA_NOSERVICE: general server down issues, server not reachable and so on
• ERR_AAA_UNAUTHORIZED: authorization fail or authenticated requests without cookie
• ERR_AAA_BAD_REQUEST: bad request (mostly in CVPN)
• ERR_AAA_PAGE_NOT_FOUND: invalid requests (mostly in CVPN)
• ERR_UNKNOWN: unknown category (mostly a place holder)

1. “ERR_AAA_UNAUTHORIZED”
   This error is seen when a user is not authorized to access the resource or there are authenticated requests without cookie and the user sees a HTTP 403 forbidden message.
   CLI Usage:
   add expression e3 "SYS.ERROR.CATEGORY.EQ(ERR_AAA_UNAUTHORIZED)"
   add responder action respondwith respondwith “user is unauthorized to access this resource”
   add responder policy respondwith e3 respondwith
   bind responder global respondwith 1 

2. "ERR_AAA_NOSERVICE"
   In many situations, NetScaler Gateway will try to talk to external servers during and after login. For example, if ICAProxy was chosen, NetScaler Gateway will try to evaluate if the WebInterface server is up and responding. If a homepage is configured for NetScaler Gateway, then after login NetScaler Gateway will try to check if that server is up. In such cases when the servers are down, this error code is returned.
   CLI Usage:
   add expression e3 "SYS.ERROR.CATEGORY.EQ(ERR_AAA_NOSERVICE)"
   add responder action respwith respondwith '" Back end Server is DOWN/unreachable""'
   add responder policy respolicy e3 respwith
   bind responder global respolicy 1

3. "ERR_AAA_CONFIG"
   This category suggests that the user access is denied because of a misconfiguration on the NetScaler This error is seen when there are runtime configuration issues for which HTTP 500 error code is seen. One example is to configure Traffic Management vserver for 401 authentication for which the authentication server does not exist.
   CLI Usage:
   add expression e3 "SYS.ERROR.CATEGORY.EQ(ERR_AAA_CONFIG)"
   add responder action respwith respondwith '" Configuration issue,kindly chk your Config and try again""'
   add responder policy respolicy e3 respwith
   bind responder global respolicy 1

4. "ERR_AAA_AUTHN"
   NetScaler Gateway uses a userspace daemon called aaad for talking to external servers for authentication. If there are some internal errors that are encountered while communicating to that daemon then this set of errors are returned. Note: Login failure is not a part of this list because it is not a system error.
   CLI Usage:
   add expression e3 "SYS.ERROR.CATEGORY.EQ(ERR_AAA_AUTHN)"
   add responder action respwith respondwith '" NSG aaad daemon issue""'
   add responder policy respolicy e3 respwith
   bind responder global respolicy 1

5. "ERR_AAA_ALLOC"
   This error code is used to specify that the NetScaler Gateway is running low on memory and that it has encountered issues with the allocated memory for processing the current request. This error code is useful to manage heavy load cases.
   CLI Usage:
   add expression e3 "SYS.ERROR.CATEGORY.EQ(ERR_AAA_ALLOC)"
   add responder action respwith respondwith '" Allocation failure /Issue on the Netscaler device""'
   add responder policy respolicy e3 respwithbind
   bind responder global respolicy 1

6. "ERR_AAA_C2C"
   This error code denotes any issue in the Multi-Core messaging system of Netscaler. This category also holds any logic errors that happen when two cores communicate for processing a request.The issue could be due to timing, configuration modification, configuration distribution and so on.
   CLI Usage:
   add expression e3 "SYS.ERROR.CATEGORY.EQ(ERR_AAA_C2C)"
   add responder action respwith respondwith '" c2c issues with the Device""'
   add responder policy respolicy e3 respwith
   bind responder global respolicy 1
   Done

7. “ERR_AAA_REASSEMBLY”
   In many cases NetScaler Gateway expects a POST request from client/browser. For example, when authentication enters dialogue mode, user is prompted for credentials which come in POST body. Similarly, when server initiated connection information is sent to a plugin, it responds with a POST request. In those case, NetScaler Gateway will buffer all the POST data. If that fails due to large POST from a rogue server or invalid data from a faulty client, then reassembly error is returned.
   CLI Usage:
   add expression e3 "SYS.ERROR.CATEGORY.EQ(ERR_AAA_REASSEMBLY)"
   add responder action respwith respondwith '" NSG reassembly issues""'
   add responder policy respolicy e3 respwith
   bind responder global respolicy 1

8. "ERR_AAA_POLICY"
   This error will be seen when there are issues related to PE authentication policies. This category holds the errors that might occur when policy subsystem tries to initialize or evaluate policies during runtime traffic. Note: This does not hold on to any configuration errors.
   CLI Usage:
   add expression e3 "SYS.ERROR.CATEGORY.EQ(ERR_AAA_POLICY)"
   add responder action respwith respondwith '" Authentication Policy issue""'
   add responder policy respolicy e3 respwith
   bind responder global respolicy 1

9. "ERR_AAA_GENERIC"
   This error code is used to act upon any legacy error codes that NetScaler Gateway returns. In practice, this error category is not used as this will also intercept any protocol messages that the NetScaler Gateway returns. These protocol errors are non-zero values, but are not errors. Care should be taken when using this category. For all practical purposes, this error category can be avoided.
   CLI Usage:
   add expression e3 "SYS.ERROR.CATEGORY.EQ(ERR_AAA_GENERIC)"
   add responder action respwith respondwith '" Generic issue/s""'
   add responder policy respolicy e3 respwith
   bind responder global respolicy 1

10. “ERR_AAA_BAD_REQUEST”
    This error will be returned mostly for CVPN module of NetScaler Gateway where cvpnized URL is not well formed or have malformed syntax hence NetScaler Gateway is unable to decvpnize the incoming data.
    CLI Usage:
    add expression e3 "SYS.ERROR.CATEGORY.EQ(ERR_AAA_BAD_REQUEST)"
    add responder action respwith respondwith '" Bad Request.kindly modify the request to proceed""'
    add responder policy respolicy e3 respwith
    bind responder global respolicy 1

11. "ERR_AAA_PAGE_NOT_FOUND"
    This error will be returned if an invalid request is sent to the NetScaler Gateway, for example GET something.html.
    CLI Usage:
    add expression e3 "SYS.ERROR.CATEGORY.EQ(ERR_AAA_PAGE_NOT_FOUND)"
    add responder action respwith respondwith '" Resource /webpage you requested doesn’t exist”’
    add responder policy respolicy e3 respwith
    bind responder global respolicy 1

12.  "ERR_UNKNOWN"
    Unknown is a place holder for unclassified errors. This error code is a catch all error code when responder policy is unable to categorize error code that was generated by NetScaler Gateway.
    CLI Usage:
    add expression e3 "SYS.ERROR.CATEGORY.EQ(ERR_UNKNOWN)"
    add responder action respwith respondwith '" Unknown Issue""'
    add responder policy respolicy e3 respwith
    bind responder global respolicy 1

13. "ERR_AAA_IIP"
    This category of errors are used to classify any errors that NetScaler Gateway would have run into while trying to allocate intranet IP address or while trying to process server initiated connections and so forth.
    CLI Usage:
    add expression e3 "SYS.ERROR.CATEGORY.EQ(ERR_AAA_IIP")
    add responder action respwith respondwith '" Issue with IIP allocation/IIP transfer issues""'
    add responder policy respolicy e3 respwith
    bind responder global respolicy 1