Citrix ADC rewrite rules help with modifying client HTTP requests based on multiple configurable conditions. These rewrite rules enable you to process and modify HTTP requests at the ADC level, reducing the load on web servers and enhancing their performance.
The rewrite rules are applicable on any Citrix ADC form factor and change part of the client requests for reasons including:
- To inform clients that the resources they’re requesting reside in a different location. Example use cases are when your website’s domain names has changed, when you want clients to use a canonical URL format (either with or without the www prefix), and when you want to catch common misspellings of your domain name.
- The backend service URL requests needs to be mapped to a more intuitive URL. For example, for a user, http://mysite.com/listings/123 will be much more intuitive than http://mysite.com/listing.html?listing=123. But if the backend services cannot be modified to understand the intuitive URLs, we can define a rewrite policy rule to convert the URL http://mysite.com/listings/123 to http://mysite.com/listing.html?listing=123.
In this blog post, we’ll use the responder policies and rewrite policies of Citrix ADC Rewrite Policy CRD on Kubernetes for rewriting the client HTTP requests. We’ll assume you’re familiar with HTTP and HTTP response codes and regular expressions. The approach we cover here requires Citrix Ingress Controller (CIC) for configuring responder policies and rewrite policies on MPX/VPX/CPX using Rewrite Policy CRD.
For installation of CIC and Citrix ADC, please check out our documentation on deploying Citrix Ingress Controller with MPX/VPX/CPX.
Comparing Citrix ADC’s Responder and Rewrite Policies
The responder and rewrite policies provide an extraordinarily comprehensive list of options to the administrator to manipulate data on HTTP requests and responses. This list gives administrators with freedom and flexibility to adjust the existing infrastructure using Citrix ADC responder and rewrite policies, without modifying back-end services. Let’s take a look at few of them:
Responder Policies
Responder policies enable Citrix ADC to send a direct response for the client requests without sending the requests to the back-end services.
Here’s a simple responder policy within the Rewrite Policy CRD that redirects clients to a new domain name:
apiVersion: citrix.com/v1
kind: rewritepolicy
metadata:
name: domainnamechange
spec:
responder-policies:
- servicenames:
- example-service
responder-policy:
redirect:
url: '"www.new-domain-name.com" + http.req.url'
redirect-status-code: 301
respond-criteria: 'HTTP.REQ.HOSTNAME.CONTAINS("old-domain-name.com")'
comment: 'Redirect to New Domain Name'This responder policy will respond to all the client requests intended for the particular Kubernetes service named example-service; if the hostname contains old-domain-name.com, the request will be redirected to www.new-domain-name.com with the provided response status code 301.
The servicenames field is a list of Kubernetes service names on which the current responder policy will be applied. The respond-criteria field is a Boolean value, which gets evaluated for every client request, and the responder policy will be applied, if the respond-criteria field evaluates to true. The redirect field has a child that specifies to which url the client request is redirected. The redirect-status-code specifies the http redirect status code. The responder policy attributes are directly mapped to Citrix ADC configuration attributes. Check out the Citrix ADC-Rewrite Policy CRD Mapping to learn more about configuration mapping.
Please note, the responder policy is defined under the Kubernetes crd kind “rewritepolicy.” In the above yaml example, the Kubernetes kind is rewritepolicy, and the spec is responder-policies.
Citrix ADC has a plethora of options/expressions to evaluate an incoming request. These expressions include everything from direct-string matching to advanced REGEX matching on any field within the requests. To learn more about expressions, check out our Policies And Expressions documentation.
We can return the above responder policy with any status code of value 3xx by replacing the values of redirect-status-code, as long as they are valid redirect codes
In some cases, you might want to define a text string that appears in the body of the response. The text can contain the following Citrix ADC variables:
apiVersion: citrix.com/v1
kind: rewritepolicy
metadata:
name: blacklisturls
spec:
responder-policies:
- servicenames:
- backend-service
responder-policy:
respondwith:
http-payload-string: '"HTTP/1.1 403 Forbidden\r\n\r\n" + "URL containing test is forbidden:" + HTTP.REQ.URL.HTTP_URL_SAFE'
respond-criteria: 'http.req.url.contains("test")'
comment: 'Blacklist test Urls'The http-payload-string attribute is used to return HTTP-return-status-code and the text string that appears in the body of the response. The text string can also be a HTML page.
In some cases, you might want to return an error page as a response in html format. The below example accomplishes that:
apiVersion: citrix.com/v1
kind: rewritepolicy
metadata:
name: blacklisturls
spec:
responder-policies:
- servicenames:
- backend-service
responder-policy:
respondwith:
http-payload-string: '"HTTP/1.1 403 Forbidden\r\n\r\n" + "<html><body text=blue bgcolor=orange>URL containing test is forbidden:" + HTTP.REQ.URL.HTTP_URL_SAFE + "</body></html>"'
respond-criteria: 'http.req.url.contains("test")'
comment: 'Blacklist test Urls'As you can see, the responder policies are simple to use. With all the available options within responder policies, Citrix ADC can be used as a powerful tool to reduce the load on web servers.
To see all the available options for responder policies, check out our Use Rewrite and Responder policies in Kubernetes documentation.
Rewrite Policies
But what if you need to test more complicated distinctions between URLs, capture elements in the original URL that don’t have corresponding Citrix ADC expressions, or change or add elements in the path? You can use the rewrite policies.
Rewrite policies are used for modifying the client request at the Citrix ADC, before the requests are punted to the back-end services.
Here’s a simple use case for rewrite-policies. It matches URLs that begin with the string /download and include the /media or /audio directory somewhere in the path. It replaces those elements with /mp3/ and adds the appropriate file extension, .mp3 or .ra. For example /download/india-east/media/file1 becomes /download/india-east/mp3/file1.mp3 when the request is sent to the back end.
apiVersion: citrix.com/v1
kind: rewritepolicy
metadata:
name: urlrewrite
spec:
rewrite-policies:
- servicenames:
- backend-service
rewrite-policy:
operation: replace
target: 'http.req.url'
modify-expression: 'HTTP.REQ.URL.REGEX_SELECT(re:\/download\/(.*?)\/:) + "mp3/" + HTTP.REQ.URL.AFTER_REGEX(re:\/download\/(.*?)\/media\/:) + ".mp3"'
comment: 'Rewriting URL usecases media to mp3'
direction: REQUEST
rewrite-criteria: 'HTTP.REQ.URL.REGEX_MATCH(re:\/download\/(.*?)\/media\/(.*):)'
- servicenames:
- backend-service
rewrite-policy:
operation: replace
target: 'http.req.url'
modify-expression: 'HTTP.REQ.URL.REGEX_SELECT(re:\/download\/(.*?)\/:) + "ra/" + HTTP.REQ.URL.AFTER_REGEX(re:\/download\/(.*?)\/audio\/:) + ".ra"'
comment: 'Rewriting URL usecases audio to ra'
direction: REQUEST
rewrite-criteria: 'HTTP.REQ.URL.REGEX_MATCH(re:\/download\/(.*?)\/audio\/(.*):)'The rewrite policies above will be applied on the Kubernetes service with the name backend-service. The first rewrite policy uses a regex match on the url that contains the regular expression /download/<anything>/media for the rewrite-criteria. The modify-expression field modifies the complete url and sends the modified request to the back-end service. Similarly, the second rewrite policy matches /download/<anything>/audio for the rewrite-criteria
The above policies modify the requests as below and sends the modified requests to the backend services: /download/india-east/media/file1 to /download/india-east/mp3/file1.mp3 and /download/india-west/audio/bieberjukebox to /download/india-west/ra/bieberjukebox.ra
The rewrite-criteria is similar to the respond-criteria, which is a Boolean value and gets evaluated against every client request. If the rewrite criteria evaluates to true, the corresponding rewrite-policy will be applied on the client request. The operation attribute specifies one of the operations allowed by the Citrix ADC on the client request. The target attribute specifies which field within the client request should be operated using the operation attribute. The modify-expression modifies the target accordingly. Similar to responder policies, the attributes of rewrite policies CRD are mapped one-to-one with Citrix ADC attributes. Please check out the Citrix ADC-Rewrite Policy mapping documentation to learn more about rewrite policies and Citrix ADC configuration mappings
The expressions for both rewrite and responder are exactly the same. Learn more in our Policies And Expressions documentation. To view all the available options for rewrite policies, see our Use Rewrite and Responder policies in Kubernetes documentation documentation.
Citrix ADC, along with Citrix Ingress Controller, can help to solve common challenges in the microservices app deployment environment. Please check out our blog post on how Citrix supercharges microservices-based app delivery for more details.
Common Examples
Let’s look at some common examples of rewrite rules, an administrator would frequently deploy in production. These will give you an overview of Citrix ADC rewrite rules that can be leveraged for advanced policy configuration use cases.
Standardizing the Domain Name
One of the most common uses of Citrix ADC responder policy rules is to redirect the old domain name to the homepage of the new domain.
apiVersion: citrix.com/v1
kind: rewritepolicy
metadata:
name: homepageredirect
spec:
responder-policies:
- servicenames:
- backend-service
responder-policy:
redirect:
url: '"www.new-domain-name.com"'
redirect-status-code: 301
respond-criteria: 'HTTP.REQ.HOSTNAME.CONTAINS("old-domain-name.com")'
comment: 'Redirect to New Domain Name'If the client request contains old-domain-name.com within its hostname, the same request will be redirected to the new-domain-name homepage, irrespective of the url.
If the url has to be mapped with the new-domain-name, the only change on the url attribute will be as follows:
url: '"www.new-domain-name.com" + http.req.url'
Adding and Removing the www Prefix
The below example redirects the requests after adding the www prefix.
apiVersion: citrix.com/v1
kind: rewritepolicy
metadata:
name: addingwww
spec:
responder-policies:
- servicenames:
- backend-service
responder-policy:
redirect:
url: '"www.domain-name.com" + http.req.url'
redirect-status-code: 301
respond-criteria: 'HTTP.REQ.HOSTNAME.EQ("domain-name.com")'
comment: 'Adding www to Domain Name'The below example redirects the requests removing the www prefix.
apiVersion: citrix.com/v1
kind: rewritepolicy
metadata:
name: removingwww
spec:
responder-policies:
- servicenames:
- backend-service
responder-policy:
redirect:
url: '"domain-name.com" + http.req.url'
redirect-status-code: 301
respond-criteria: 'HTTP.REQ.HOSTNAME.EQ("www.domain-name.com")'
comment: 'Removing www from Domain Name'Redirecting All Traffic to the Correct Domain Name
Here’s a special case that redirects incoming traffic to the website’s URL when the requested hostname doesn’t match any current website domain (it could be misspelled, for example). This works by matching the hostname that doesn’t match with the current domain name, then redirecting the request to the correct domain name.
apiVersion: citrix.com/v1
kind: rewritepolicy
metadata:
name: correctingdomainname
spec:
responder-policies:
- servicenames:
- backend-service
responder-policy:
redirect:
url: '"www.domain-name.com" + http.req.url'
redirect-status-code: 301
respond-criteria: 'HTTP.REQ.HOSTNAME.EQ("www.domain-name.com").NOT'
comment: 'Correcting domain name when requests come to misspelt domain name'Forcing all Requests to Use SSL/TLS
This responder policy forces all visitors to use a secured (SSL/TLS) connection to your site.
apiVersion: citrix.com/v1
kind: rewritepolicy
metadata:
name: httptohttps
spec:
responder-policies:
- servicenames:
- backend-service
responder-policy:
redirect:
url: '"https://" +http.req.HOSTNAME.SERVER+":"+"443"+http.req.url'
respond-criteria: 'http.req.is_valid'
comment: 'http to https'Dropping Requests for Unsupported File Extensions
For various reasons, your site might receive request URLs that end in a file extension corresponding to an application server you’re not running. In this example, the requests with file types handled by other application servers (active server pages, PHP, CGI, and so on) cannot be serviced and need to be rejected. We match on all the filetype requests using respond criteria. If the respond criteria evaluates to True, we respond with a http-payload-string that the request for corresponding file type is forbidden.
apiVersion: citrix.com/v1
kind: rewritepolicy
metadata:
name: filetyperejection
spec:
responder-policies:
- servicenames:
- backend-service
responder-policy:
respondwith:
http-payload-string: '"HTTP/1.1 403 Forbidden\r\n\r\n" + "<html><body text=blue bgcolor=orange>File type is forbidden:" + HTTP.REQ.URL.HTTP_URL_SAFE + "</body></html>"'
respond-criteria: 'HTTP.REQ.URL.ENDSWITH(".aspx").OR(HTTP.REQ.URL.ENDSWITH(".php")).OR(HTTP.REQ.URL.ENDSWITH(".cgi")).OR(HTTP.REQ.URL.ENDSWITH(".jsp"))'
comment: 'File Type Rejection'Configuring Custom Rerouting
In this example, you have a resource that functions as a controller for a set of URLs. Your users can use a more readable name for a resource, and you rewrite (not respond) so that it is handled by the controller at listing.html.
apiVersion: citrix.com/v1
kind: rewritepolicy
metadata:
name: customurlrerouting
spec:
rewrite-policies:
- servicenames:
- backend-service
rewrite-policy:
operation: replace
target: 'http.req.url'
modify-expression: '"/listing.html?listing=" + http.req.url.after_str("/listings/")'
comment: 'Changing the url for custom re-routing cases'
direction: REQUEST
rewrite-criteria: 'HTTP.REQ.URL.STARTSWITH("/listings/")'As an example, the user‑friendly URL http://mysite.com/listings/123 is rewritten to a URL handled by the listing.html controller, http://mysite.com/listing.html?listing=123.
The examples we’ve provided in this blog post cover some of the more common use cases for Citrix ADC rewrite rules. But these rules aren’t just for simple uses cases. You can also leverage them for complex use cases like inserting/modifying the HTTP header, blocking set of IPs to mitigate DDOS attacks, blocking certain URLs requests, applying regex matches and substitutions on the requests, logging the requests based on configurations, and much more.
To learn more about the advanced capabilities of Citrix ADC rewrite and responder policies, check out our Use Rewrite and Responder policies in Kubernetes documentation.
