1Perlbal::Manual::ConfigUusreartiCoonn(t3r)ibuted Perl DoPceurmlebnatla:t:iMoannual::Configuration(3)
2
3
4

NAME

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.36.0                      2023-01-18 Perlbal::Manual::Configuration(3)