1Perlbal::Manual::ConfigUusreartiCoonn(t3r)ibuted Perl DoPceurmlebnatla:t:iMoannual::Configuration(3)
2
3
4
6 Perlbal::Manual::Configuration - How to configure Perlbal
7
8 VERSION
9 Perlbal 1.78.
10
11 DESCRIPTION
12 By default, Perlbal looks for a configuration file at
13 /etc/perlbal/perlbal.conf.
14
15 You can also point perlbal at a different configuration file with the
16 -c flag.
17
18 $ perlbal -c /home/user/perlbal.conf
19
20 -c has the alias --conf.
21
22 Setting up Perlbal as a daemon
23 You can run "perlbal" as a daemon:
24
25 $ perlbal --daemon -c /home/user/perlbal.conf
26
27 --daemon has the alias -d.
28
29 A common practice is to create a "perlbal.sh" file that supports the
30 common operations you'll require (start, stop, restart) and place it
31 under "/etc/init.d". You can find a sample file in
32 "debian/perlbal.init".
33
34 Configuration file
35 A Perlbal's configuration file is a text file where you create pools
36 and services, add servers to pools, set services' parameters and
37 enable/disable services.
38
39 Indentation is not mandatory, but it's considered a good practice for
40 readability issues.
41
42 Configuration is case insensitive, but it's also a good practice to
43 uppercase all directives.
44
45 Pools
46
47 Here's a sample configuration of a pool:
48
49 CREATE POOL mywebsite
50 POOL mywebsite ADD 10.0.0.1:80
51 POOL mywebsite ADD 10.0.0.2:80
52
53 The first line creates a pool called "mywebsite". The second and third
54 lines add two different servers to that pool.
55
56 From here on you'll be able to use this pool in a service.
57
58 Also, note that right after creating the pool, you don't need to
59 specify which pool you're adding servers to, as it is considered to be
60 the active pool:
61
62 CREATE POOL mywebsite
63 POOL ADD 10.0.0.1:80
64 POOL ADD 10.0.0.2:80
65
66 Configuring a pool in a separate file
67
68 You can create a pool in a separate file by using the "nodefile"
69 parameter:
70
71 CREATE POOL dynamic
72 SET nodefile = conf/nodelist.dat
73
74 This separate file should contain addresses in the form of "ip:port",
75 one per line (empty lines are ignored, as well as comments started by
76 the "#" sign).
77
78 Perlbal will check the file periodically for updates.
79
80 The path to the file is relative to where perlbal was started.
81
82 Note that:
83
84 SET pool nodefile = none
85 (also undef, null, "", '')
86
87 ...unsets the nodefile, but does not remove current members.
88
89 Also note: If you set a nodefile, then modify the pool via POOL ADD or
90 POOL REMOVE, Perlbal will stop checking the nodefile for updates!
91
92 Check conf/load-balancer.conf and conf/nodelist.dat for an example.
93
94 Pool balance method
95
96 You can set the pool balance method:
97
98 SET pool balance_method = 'random'
99
100 At the present time, "random" is the only load balancing method
101 available.
102
103 Services
104
105 Here's a sample service:
106
107 CREATE SERVICE service_mywebsite
108 SET role = reverse_proxy
109 SET pool = mywebsite
110 SET listen = 10.0.0.3:80
111
112 The first line creates a service called "service_mywebsite".
113
114 On the three following lines we are setting up three parameters for
115 that service (you can see this same example in
116 Perlbal::Manual::LoadBalancer in more detail).
117
118 It is good practice to always start a service with the definition of
119 its role; this way you'll avoid error messages caused by attempting to
120 set parameters that are only acceptable for certain roles while Perlbal
121 doesn't know which role the service is supposed to be yet.
122
123 Setting parameters
124
125 You can set parameters via commands of either forms:
126
127 SET <service-name> <param> = <value>
128 SET <param> = <value>
129
130 For a full list of parameters see Perlbal::Manual::LoadBalancer,
131 Perlbal::Manual::ReverseProxy or Perlbal::Manual::WebServer.
132
133 Note on types:
134
135 'bool' values can be set using one of 1, true, yes, on, 0, false, off,
136 or no.
137
138 'size' values are in integer bytes, or an integer followed by 'b', 'k',
139 or 'm' (case-insensitive) for bytes, KiB, or MiB.
140
141 Setting parameter defaults
142
143 Outside the scope of a service you can set parameter defaults for all
144 following created services:
145
146 SET <param> = <value>
147
148 This takes the same parameters as the section above ""Setting
149 parameters"
150
151 Enabling/Disabling services
152
153 To enable a service:
154
155 ENABLE service_mywebsite
156
157 To disable a service:
158
159 DISABLE service_mywebsite
160
161 These lines is what allows you to have several services configured in a
162 file even if they are not currently active (a common scenario is to
163 configure everything on the file and then enable/disable services on-
164 the-fly as required; see Perlbal::Manual::Management for more
165 information on this process).
166
167 Including configuration files
168
169 While Perlbal doesn't natively let you include a configuration file
170 within another, one of its core Plugins does.
171
172 By using Perlbal::Plugin::Include you can use this feature:
173
174 LOAD include
175 INCLUDE = /etc/perlbal/my.conf
176 INCLUDE = /etc/perlbal/other.conf /etc/perlbal/*.conf
177
178 See Perlbal::Plugin::Include for further examples and more information.
179
180 Expansions
181
182 The following things expand/interpolate in config files/commands:
183
184 "${ip:eth0}"
185 Expands to the configured IP for interface "eth0". Probably only
186 works on Linux.
187
188 Comments
189
190 Comments in Perlbal's configuration files start with a "#":
191
192 # this is a comment
193 ENABLE myservice # this is also a comment
194
195 Environment variables
196 DANGABUILD_DAEMONONLY
197
198 Used in "Makefile.PL". If set to a true value the modules will not be
199 built.
200
201 DANGABUILD_MODULESONLY
202
203 Used in "Makefile.PL". If set to a true value only the modules will be
204 built, not the "perlbal" executable.
205
206 PERLBAL_DEBUG
207
208 There are four levels of debugging in Perlbal.
209
210 By setting this variable to a value between 0 and 4 (included) you will
211 activate Perbal's debug.
212
213 PERLBAL_DEBUG = 0 # no debug
214
215 PERLBAL_DEBUG = 4 # debug everything
216
217 These four levels are described in more detail in
218 Perlbal::Manual::Debugging.
219
220 PERLBAL_DEBUG_BUFFERED_UPLOADS
221
222 By setting this variable to 1 you can tell Perlbal to add a
223 "X-PERLBAL-BUFFERED-UPLOAD-REASON" header to requests that have to be
224 buffered.
225
226 This can be useful to let your backend machine know that Perlbal is
227 buffering the request.
228
229 The value of the header contains the reason why the request was
230 buffered.
231
232 PERLBAL_DEBUG_OBJ
233
234 This is the variable you'll have to set to a true value in order to
235 properly use the commands "obj" or "track".
236
237 See Perlbal::Manual::Management for more information.
238
239 PERLBAL_REMOVE_FIELDS
240
241 Setting this variable true will give perlbal an extra speed boost on
242 perl 5.10+ by removing run-time locking of field names on internal
243 objects. As a tradeoff this will make code such as plugins or patch
244 sets that incorrectly handling fields in perlbal to silently fail
245 rather than giving warnings and errors.
246
247 Use with caution until you trust your combination of perlbal version,
248 plugins and versions and other patches you may have applied. Once you
249 trust you perlbal instance to have no problems this option should
250 simply make perlbal faster.
251
252 PERLBAL_TEST_ALPHA
253
254 This is a variable used to test Perlbal's alpha features.
255
256 If you're a developer working on one of these features, first set the
257 variable to a true value:
258
259 PERLBAL_TEST_ALPHA = 1
260
261 And then, on your test file, use something like:
262
263 unless ($ENV{PERLBAL_TEST_ALPHA}) {
264 plan skip_all => 'Alpha feature; test skipped without $ENV{PERLBAL_TEST_ALPHA}';
265 exit 0;
266 } else {
267 plan tests => 4;
268 }
269
270 PERLBAL_TRACK_STATES
271
272 This is the variable you'll have to set to a true value in order to
273 properly use the command "state changes".
274
275 See Perlbal::Manual::Management for more information.
276
277 PERLBAL_XS_HEADERS
278
279 By setting to a true value you can enable Perlbal::XS::HTTPHeaders, if
280 installed.
281
282 Note that if you enable Perlbal::XS::HTTPHeaders you won't have access
283 to the fields of Perlbal::HTTPHeaders.
284
285 TEST_PERLBAL_FOREGROUND
286
287 This variable is used by Perlbal::Test to test Perlbal.
288
289 "TEST_PERLBAL_FOREGROUND" with a true value tells Perlbal::Test that it
290 should run a server in the foreground.
291
292 See Perlbal::Test for more information.
293
294 TEST_PERLBAL_USE_EXISTING
295
296 This variable is used by Perlbal::Test to test Perlbal.
297
298 If "TEST_PERLBAL_USE_EXISTING" is set to a true value then
299 "Perlbal::Test::start_server" will be return a socket which is
300 connected to an existing server's management port.
301
302 See Perlbal::Test for more information.
303
304 SEE ALSO
305 Perlbal::Manual::Management.
306
307
308
309perl v5.30.0 2019-07-24 Perlbal::Manual::Configuration(3)