addclientheader.yo (5475B)
1 conf(HTTP Header Modification Directives) 2 (Crossroads understands the following 3 header modification directives: tt(addclientheader), 4 tt(appendclientheader), tt(setclientheader), tt(addserverheader), 5 tt(appendserverheader), tt(setserverheader). 6 7 The directive names always consist of 8 em(Action)em(Destination)tt(header), where: 9 10 itemization( 11 it() The action is tt(add), tt(append) or tt(insert). 12 13 itemization( 14 it() Action tt(add) adds a header, even when headers with 15 the same name already are present in an HTTP 16 message. Adding headers is useful for e.g. tt(Set-Cookie) 17 headers; a message may contain several of such headers. 18 19 it() Action tt(append) adds a header if it isn't present 20 yet in an HTTP message. If such a header is already 21 present, then the value is appended to the pre-existing 22 header. This is useful for e.g. tt(Via) headers. Imagine 23 an HTTP message with a header tt(Via: someproxy). Then the 24 directive tt(appendclientheader "Via: crossroads") will 25 rewrite the header to tt(Via: someproxy; crossroads). 26 27 it() Action tt(set) overwrites headers with the same 28 name; or adds a new header if no pre-existing is found. 29 This is useful for e.g. tt(Host) headers.) 30 31 it() The destination is one of tt(client) or tt(server). When 32 the destination is tt(server), then Crossroads will apply such 33 directives to HTTP messages that originate from the browser 34 and are being forwarded to back ends. When the destination is 35 tt(client), then Crossroads will apply such directives to 36 backend responses that are shuttled to the browser.) 37 38 The format of the directives is e.g. tt(addclientheader 39 "X-Processed-By: Crossroads"). The directives expect one 40 argument; a string, consisting of a header name, a colon, and a 41 header value. As usual, the directive must end with a semicolon. 42 43 The header value may contain one of the following formatting 44 directives: 45 46 INCLUDEFILE(formattable.yo) 47 48 The following examples show common uses of header modifications. 49 50 description( 51 dit(Enforcing session stickiness:) By combining 52 tt(stickycookie) and tt(addclientheader), HTTP session 53 stickiness is enforced. Consider the following configuration: 54 55 verb(\ 56 service ... { 57 ... 58 backend one { 59 ... 60 addclientheader "Set-Cookie: BalancerID=first; path=/"; 61 stickycookie "BalancerID=first"; 62 } 63 backend two { 64 ... 65 addclientheader "Set-Cookie: BalancerID=second; path=/"; 66 stickycookie "BalancerID=second"; 67 } 68 }) 69 70 The first request of an HTTP session is balanced to either 71 backend tt(one) or tt(two). The server response is enriched 72 using tt(addclientheader) with an appropriate cookie. A 73 subsequent request from the same browser now has that cookie 74 in place; and is therefore sent to the same back end where the 75 its predecessors went. 76 77 dit(Hiding the server software version:) Many servers 78 (e.g. Apache) advertize their version, as in tt(Server: Apache 79 1.27). This potentially provides information to attackers. The 80 following configuration hides such information: 81 82 verb(\ 83 service ... { 84 ... 85 backend one { 86 ... 87 setclientheader "Server: WWW-Server"; 88 } 89 }) 90 91 dit(Informing the server of the clients' IP address:) Since 92 Crossroads sits 'in the middle' between a client and a back 93 end, the back end perceives Crossroads as its client. The 94 following sends the true clients' IP address to the server, in 95 a header tt(X-Real-IP): 96 97 verb(\ 98 service ... { 99 ... 100 backend one { 101 ... 102 setserverheader "X-Real-IP: %r"; 103 } 104 }) 105 106 dit(Keep-Alive Downgrading:) The directives 107 tt(setclientheader) and tt(setserverheader) also play a key 108 role in downgrading Keep-Alive connections to 109 'single-shot'. E.g., the following configuration makes sure 110 that no Keep-Alive connections occur. 111 112 verb(\ 113 service ... { 114 ... 115 backend one { 116 ... 117 setserverheader "Connection: close"; 118 setclientheader "Connection: close"; 119 } 120 }))) 121 (itemization( 122 it() tt(addclientheader) em(Headername: headervalue) to add a 123 header in the traffic towards the client, even when another 124 header em(Headername) exists; 125 it() tt(appendclientheader) em(Headername: headervalue) to 126 append em(headervalue) to an existing header em(Headername) 127 in the traffic towards the client, 128 or to add the whole header alltogether; 129 it() tt(setclientheader) em(Headername: headervalue) to 130 overwrite an existing header in the traffic towards the 131 client, or to add such a header; 132 it() tt(addserverheader) em(Headername: headervalue) to add a 133 header in the traffic towards the server, even when another 134 header em(Headername) exists; 135 it() tt(appendserverheader) em(Headername: headervalue) to 136 append em(headervalue) to an existing header em(Headername) 137 in the traffic towards the server, 138 or to add the whole header alltogether; 139 it() tt(setserverheader) em(Headername: headervalue) to 140 overwrite an existing header in the traffic towards the 141 server, or to add such a header.)) 142 (There is no default.)