config.yo (5053B)
1 The configuration that crossroads uses is normally stored in the file 2 tt(/etc/crossroads.conf). This location can be overruled using the 3 command line flag tt(-c). 4 5 This section explains the syntax of the configuration file, and what 6 all settings do. 7 8 subsect(General language elements) 9 10 This section describes the general elements of the crossroads 11 configuration language. 12 13 14 subsubsect(Empty lines and comments) 15 16 Empty lines are of course allowed in the 17 configuration. Crossroads recognizes three formats of comment: 18 19 itemization( 20 it() C-style, between tt(/*) and tt(*/), 21 it() C++-style, starting with tt(//) and ending with the end 22 of the text line; 23 it() Shell-style, starting with tt(#) and ending with the end 24 of the text line.) 25 26 Simply choose your favorite editor and use the comment that 'looks 27 best'.footnote(I favor C or C++ comment. My favorite editor em(emacs) 28 can be put in tt(cmode) and nicely highlight what's comment and what's 29 not. And as a bonus it will auto-indent the configuration!) 30 31 32 subsubsect(Keywords, numbers, identifiers, generic strings) 33 34 In a configuration file, statements are identified by em(keywords), 35 such as tt(service), tt(verbosity). These are reserved words. 36 37 Many keywords require an em(identifier) as the argument. E.g, a 38 service has a unique name, which must start with a letter or 39 underscore, followed by zero or more letters, underscores, or 40 digits. Therefore, in the statement tt(service myservice), the keyword is 41 tt(service) and the identifier is tt(myservice). 42 43 Other keywords require a numeric argument. Crossroads knows only 44 non-negative integer numbers, as in tt(port 8000). Here, tt(port) is 45 the keyword and tt(8000) is the number. 46 47 Yet other keywords require 'generic strings', such as hostname 48 specifications or system commands. Such generic strings contain any 49 characters (including white space) up to the terminating statement 50 character tt(;). If a string must contain a semicolon, then it must 51 be enclosed in single or double quotes: 52 53 itemization( 54 it() tt(This is a string;) is a string that starts at tt(T) 55 and ends with tt(g) 56 it() tt("This is a string";) is the same, the double quotes 57 are not necessary 58 it() tt("This is ; a string";) has double quotes to protect 59 the inner ;) 60 61 Finally, an argument can be a 'boolean' value. Crossroads knows 62 tt(true), tt(false), tt(yes), tt(no), tt(on), tt(off). The keywords 63 tt(true), tt(yes) and tt(on) all mean the same and can be used 64 interchangeably; as can the keywords tt(false), tt(no) and tt(off). 65 66 67 subsect(Service definitions) label(servicedef) 68 69 Service definitions are blocks in the configuration file that 70 state what is for each service. A service definition starts with 71 tt(service), followed by a unique identifier, and by statements in 72 tt({) and tt(}). For example: 73 74 verb(\ 75 // Definition of service 'www': 76 service www { 77 ... 78 ... // statements that define the 79 ... // service named 'www' 80 ... 81 }) 82 83 The configuration file can contain many service blocks, as long as the 84 identifying names differ. The following list shows possible 85 statements. Each statement must end with a semicolon, except for the 86 tt(backend) statement, which has is own block (more on this later). 87 88 redef(conf)(4)(\ 89 subsubsect(ARG1) label(confARG1) 90 startdit() 91 dit(Description:) ARG2 92 dit(Syntax:) ARG3 93 dit(Default:) ARG4 94 enddit()) 95 96 97 includefile(conf/type) 98 includefile(conf/port) 99 includefile(conf/bindto) 100 includefile(conf/verbose) 101 includefile(conf/dispatchmode) 102 includefile(conf/revivinginterval) 103 includefile(conf/maxconnections) 104 includefile(conf/backlog) 105 includefile(conf/shmkey) 106 includefile(conf/allow) 107 includefile(conf/useraccount) 108 109 110 subsect(Backend definitions) 111 112 Inside the service definitions as are described in the previous 113 section, em(backend definitions) must also occur. Backend definitions 114 are started by the keyword tt(backend), followed by an identifier 115 (the back end name) , and statements inside tt({) and tt(}): 116 117 verb(\ 118 service myservice { 119 ... 120 ... // statements that define the 121 ... // service named 'myservice' 122 ... 123 124 backend mybackend { 125 ... 126 ... // statements that define the 127 ... // backend named 'mybackend' 128 ... 129 } 130 }) 131 132 Each service definition must have at least one backend 133 definition. There may be more (and probably will, if you want 134 balancing and fail over) as long as the backend names differ. 135 The statements in the backend definition blocks are described in the 136 following sections. 137 138 Some directives (tt(stickycookie) etc.) only have effect when 139 Crossroads treats the network traffic as a stream of HTTP messages; 140 i.e., when the service is declared with tt(type http). Incase of 141 tt(type any), the HTTP-specific directives have no effect. 142 143 includefile(conf/server.yo) 144 includefile(conf/verbose-backend.yo) 145 includefile(conf/weight) 146 includefile(conf/decay) 147 includefile(conf/onhooks) 148 includefile(conf/trafficlog) 149 includefile(conf/stickycookie) 150 includefile(conf/addclientheader)