intro.yo (10397B)
1 Crossroads is a daemon that basically accepts TCP connections 2 at preconfigured ports, and given a list of 'back ends' 3 distributes each incoming connection to one of the back ends, 4 so that a client request is 5 served. Additionally, crossroads maintains an internal 6 administration of the back end connectivity: if a back end isn't 7 usable, then the client request is handled using another back 8 end. Crossroads will then periodically check whether a previously not 9 usable back end has come to life yet. Also, crossroads can select 10 back ends by estimating the load, so that balancing is achieved. 11 12 Using this approach, crossroads serves as load balancer and fail over 13 utility. Crossroads will very likely not be as reliable as 14 hardware based balancers, since it always will require a server to 15 run on. This server, in turn, may become a new Single Point of 16 Failure (SPOS). However, in situations where cost efficiency is an issue, 17 crossroads may be a good choice. Furthermore, crossroads can be 18 deployed in situations where a hardware based balancing already 19 exists and augmenting service reliability is needed. Or, crossroads may be 20 run off a diskless system, which again improves reliability of the 21 underlying hardware. 22 23 This document describes how to use crossroads, how to configure it 24 in order to increase the reliability of your systems, and how to 25 compile the program from its sources. whenhtml(This document is 26 also available in url(PDF)(crossroads.pdf) format.) 27 28 subsect(Obtaining Crossroads) 29 30 As quick reference, here are some important URL's for Crossroads: 31 32 itemization( 33 it() lurl(http:/crossroads.e-tunity.com) is the site that serves 34 Crossroads. You can browse this at leisure 35 for documentation, sources, and so on. 36 37 it() lurl(http://freshmeat.net/projects/crossr) is the 38 Freshmeat announcement page. 39 40 it() lurl(svn://svn.e-tunity.com/crossroads) is the SVN 41 repository; anonymous reading (fetching) is allowed. In order 42 to commit changes, url(mail me)(mailto:karel@e-tunity.com) for 43 credentials.) 44 45 46 subsect(Copyright and Disclaimer) 47 48 Crossroads is distributed as-is, without assumptions of fitness 49 or usability. You are free to use crossroads to your 50 liking. It's free, and as with everything that's free: there's 51 also no warranty. 52 53 You are allowed to make modifications to the source code of 54 crossroads, and you are allowed to (re)distribute crossroads, as 55 long as you include this text, all sources, and if applicable: all 56 your modifications, with each distribution. 57 58 While you are allowed to make any and all changes to the sources, 59 I would appreciate hearing about them. If the changes concern new 60 functionality or bugfixes, then I'll include them in a next 61 release, stating full credits. If you want to seriously contribute (to 62 which you are heartily encouraged), then mail me and I'll get you 63 access to the Crossroads SVN repository, so that you can update and 64 commit as you like. 65 66 subsect(Terminology) 67 68 Throughout this document, the following terms are used: footnote(Many 69 more meanings of the terms will exist -- yes, I am aware of that. I'm 70 using the terms here in a very strict sense.) 71 72 description( 73 dit(A client) is a process that initiates a network connection 74 to get contact with some service. 75 dit(A service) or bf(server process) or bf(listener) 76 is a central application 77 that accepts network connections from clients and sevices 78 them. 79 dit(Back ends) are locations where crossroads looks in 80 order to service its clients. Crossroads sits 'in between' 81 and does its tricks. Therefore, as far as the back ends 82 are concerned, crossroads behaves like a client. As far as 83 the true client is concerned, crossroads behaves like the 84 service. The communication is however transparent: neither 85 client nor back end are aware of the middle position of 86 crossroads. 87 dit(A connection) is a network conversation between client and service, 88 where data are transferred to and fro. As 89 far as crossroads is concerned, success means that a 90 connection can be established without errors on 91 the network level. Crossroads isn't aware of service 92 pecularities. E.g., when a webserver answers tt(HTTP/1.0 93 500 Server Error) then crossroads will see this as a 94 succesful connection, though the user behind a browser may 95 think otherwise. 96 dit(Back end selection algorithms) are methods by which 97 crossroads determines which back end it will talk to 98 next. Crossroads has a number of built-in algorithms, 99 which may be configured per service. 100 dit(Back end states) are the statusses of each back end that 101 is known to crossroads. A back end may be available, 102 (temporarily) unavailble or truly down. When a back end is 103 temporarily unavailable, then crossroads will periodically 104 check whether the back end has come to life yet (that is, 105 if configured so). 106 dit(A spike) is a sudden increase in activity, leading to 107 extra load on a given service. When crossroads is in 108 effect and when the spike occurs in one connection, 109 then obviously the spike will also appear at one 110 of the back ends. However, crossroads will see the spike 111 and will make sure that a subsequent request goes to an 112 other back end. In contrast, when several connections 113 arrive simultaneously and cause a spike, then crossroads 114 will be able to distribute the connections over several 115 back ends, thereby 'flattening out' the increase. 116 dit(Load balancing) means that incoming client requests are 117 distributed over more than just one back end (which wouldn't be the 118 case if you wouldn't be running crossroads). Enabling load 119 balancing is nothing more than duplicating services over 120 more than one back end, and having something (in this 121 case: crossroads) distribute the requests, so that per 122 back end the load doesn't get too high. 123 dit(An HTTP session) is a series of separate network connections 124 that originate from one browser. E.g., to fill the display 125 with text and images, the browser hits a website several times. 126 An HTTP session may even span several 127 screens. E.g., a website registration dialog may involve 3 128 screens that when called from the same browser, 129 form a logical group of some sort. 130 dit(Headers) or bf(header lines) are specific parts of an HTTP 131 message. Crossroads has directives to add or modify 132 headers that are part of the request that a browser sends 133 to server, or those that are part of the server. 134 dit(Session stickiness) means that when a browser starts an 135 HTTP dialog, the balancer makes sure that it 'sticks' to 136 the same back end (i.e., subsequent requests from the 137 browser are forced to go to the same back end, instead of 138 being balanced to other ones). 139 dit(Back end usage) is measured by crossroads in order to be 140 able to determine back end selection. Crossroads stores 141 information about the number of active connections, the 142 transferred bytes and 143 about the connection duration. These numbers can be used to 144 estimate which back end is the least used -- and 145 therefore, presumably, the best candidate for a new 146 request. 147 dit(Fail over) is almost always used when load balancing is in 148 effect. The distributor of client requests (crossroads of 149 course) can also monitor back ends, so that incase a back 150 end is 'down', it is no longer accessed. 151 dit(Service downtime) normally occurs when a service is 152 switched off. Downtime is obviously avoided when fail over 153 is in effect: a back end can be taken out of service in a 154 controlled manner, without any client noticing it. 155 ) 156 157 subsect(Porting issues for pre-1.21 installations) 158 159 As of version 1.21, the event-hook directives tt(onsuccess) and 160 tt(onfailure) no longer exists. 161 162 itemization( 163 it() Please replace tt(onsuccess) by tt(onstart); 164 it() Please replace tt(onfailure) bu tt(onfail); 165 it() Note that there is a new hook tt(onend).) 166 167 The commands that are run via tt(onstart), tt(onend) or tt(onfail) 168 are subject to format expansion; e.g., tt(%1w) is expanded to the 169 weight of the first back end, etc.. See section ref(config) for details. 170 171 subsect(Porting issues for pre-0.26 installations) 172 173 As of version 0.26 the syntax of the configuration file has 174 changed. In particular: 175 176 itemization( 177 it() The keyword tt(maxconnections) is now used instead of 178 tt(maxclients); 179 it() The keyword tt(connectiontimeout) is now used instead of 180 tt(sessiontimeout).) 181 182 Therefore when converting configuration files to the new syntax, 183 the above keywords must be changed. (The reason for these changes 184 is that 0.26 introduces em(sticky HTTP sessions) that span 185 multiple TCP connections, and the term 186 em(session) is used strictly in that sense -- and no longer for a 187 TCP connection.) 188 189 subsect(Porting issues for pre-1.08 installations) 190 191 As of version 1.08, the following directives no longer are 192 supported: 193 194 itemization( 195 it() tt(insertstickycookie) was replaced by the more generic 196 directive tt(addclientheader). E.g., instead of nl() 197 tt(insertstickycookie "XRID=100; Path=/";) nl() 198 the syntax is now nl() 199 tt(addclientheader "Set-Cookie: XRID=100; Path=/";) 200 201 it() tt(insertrealip) was replaced by the more generic 202 directive tt(setserverheader). E.g., instead of nl() 203 tt(insertrealip on;) nl() 204 the syntax is now nl() 205 tt(setserverheader "XR-Real-IP: %r";) nl() 206 This incidentally also makes it possible to change the header 207 name (here: tt(XR-Real-IP)).) 208