Perlbal::Manual::Configuration - How to configure Perlbal
Perlbal 1.76.
By default, Perlbal looks for a configuration file at /etc/perlbal/perlbal.conf.
You can also point perlbal at a different configuration file with the -c flag.
$ perlbal -c /home/user/perlbal.conf
-c has the alias --conf.
You can run perlbal as a daemon:
perlbal
$ perlbal --daemon -c /home/user/perlbal.conf
--daemon has the alias -d.
A common practice is to create a perlbal.sh file that supports the common operations you'll require (start, stop, restart) and place it under /etc/init.d. You can find a sample file in debian/perlbal.init.
perlbal.sh
/etc/init.d
debian/perlbal.init
A Perlbal's configuration file is a text file where you create pools and services, add servers to pools, set services' parameters and enable/disable services.
Indentation is not mandatory, but it's considered a good practice for readability issues.
Configuration is case insensitive, but it's also a good practice to uppercase all directives.
Here's a sample configuration of a pool:
CREATE POOL mywebsite POOL mywebsite ADD 10.0.0.1:80 POOL mywebsite ADD 10.0.0.2:80
The first line creates a pool called mywebsite. The second and third lines add two different servers to that pool.
mywebsite
From here on you'll be able to use this pool in a service.
Also, note that right after creating the pool, you don't need to specify which pool you're adding servers to, as it is considered to be the active pool:
CREATE POOL mywebsite POOL ADD 10.0.0.1:80 POOL ADD 10.0.0.2:80
You can create a pool in a separate file by using the nodefile parameter:
nodefile
CREATE POOL dynamic SET nodefile = conf/nodelist.dat
This separate file should contain addresses in the form of ip:port, one per line (empty lines are ignored, as well as comments started by the # sign).
ip:port
#
Perlbal will check the file periodically for updates.
The path to the file is relative to where perlbal was started.
Note that:
SET pool nodefile = none (also undef, null, "", '')
...unsets the nodefile, but does not remove current members.
Also note: If you set a nodefile, then modify the pool via POOL ADD or POOL REMOVE, Perlbal will stop checking the nodefile for updates!
Check conf/load-balancer.conf and conf/nodelist.dat for an example.
You can set the pool balance method:
SET pool balance_method = 'random'
At the present time, random is the only load balancing method available.
random
Here's a sample service:
CREATE SERVICE service_mywebsite SET role = reverse_proxy SET pool = mywebsite SET listen = 10.0.0.3:80
The first line creates a service called service_mywebsite.
service_mywebsite
On the three following lines we are setting up three parameters for that service (you can see this same example in Perlbal::Manual::LoadBalancer in more detail).
It is good practice to always start a service with the definition of its role; this way you'll avoid error messages caused by attempting to set parameters that are only acceptable for certain roles while Perlbal doesn't know which role the service is supposed to be yet.
You can set parameters via commands of either forms:
SET <service-name> <param> = <value> SET <param> = <value>
For a full list of parameters see Perlbal::Manual::LoadBalancer, Perlbal::Manual::ReverseProxy or Perlbal::Manual::WebServer.
'bool' values can be set using one of 1, true, yes, on, 0, false, off, or no.
'size' values are in integer bytes, or an integer followed by 'b', 'k', or 'm' (case-insensitive) for bytes, KiB, or MiB.
To enable a service:
ENABLE service_mywebsite
To disable a service:
DISABLE service_mywebsite
These lines is what allows you to have several services configured in a file even if they are not currently active (a common scenario is to configure everything on the file and then enable/disable services on-the-fly as required; see Perlbal::Manual::Management for more information on this process).
While Perlbal doesn't natively let you include a configuration file within another, one of its core Plugins does.
By using Perlbal::Plugin::Include you can use this feature:
LOAD include INCLUDE = /etc/perlbal/my.conf INCLUDE = /etc/perlbal/other.conf /etc/perlbal/*.conf
See Perlbal::Plugin::Include for further examples and more information.
The following things expand/interpolate in config files/commands:
${ip:eth0}
Expands to the configured IP for interface "eth0". Probably only works on Linux.
Comments in Perlbal's configuration files start with a #:
# this is a comment ENABLE myservice # this is also a comment
Used in Makefile.PL. If set to a true value the modules will not be built.
Makefile.PL
Used in Makefile.PL. If set to a true value only the modules will be built, not the perlbal executable.
There are four levels of debugging in Perlbal.
By setting this variable to a value between 0 and 4 (included) you will activate Perbal's debug.
PERLBAL_DEBUG = 0 # no debug PERLBAL_DEBUG = 4 # debug everything
These four levels are described in more detail in Perlbal::Manual::Debugging.
By setting this variable to 1 you can tell Perlbal to add a X-PERLBAL-BUFFERED-UPLOAD-REASON header to requests that have to be buffered.
X-PERLBAL-BUFFERED-UPLOAD-REASON
This can be useful to let your backend machine know that Perlbal is buffering the request.
The value of the header contains the reason why the request was buffered.
This is the variable you'll have to set to a true value in order to properly use the commands obj or track.
obj
track
See Perlbal::Manual::Management for more information.
This is a variable used to test Perlbal's alpha features.
If you're a developer working on one of these features, first set the variable to a true value:
PERLBAL_TEST_ALPHA = 1
And then, on your test file, use something like:
unless ($ENV{PERLBAL_TEST_ALPHA}) { plan skip_all => 'Alpha feature; test skipped without $ENV{PERLBAL_TEST_ALPHA}'; exit 0; } else { plan tests => 4; }
This is the variable you'll have to set to a true value in order to properly use the command state changes.
state changes
By setting to a true value you can enable Perlbal::XS::HTTPHeaders, if installed.
Note that if you enable Perlbal::XS::HTTPHeaders you won't have access to the fields of Perlbal::HTTPHeaders.
This variable is used by Perlbal::Test to test Perlbal.
TEST_PERLBAL_FOREGROUND with a true value tells Perlbal::Test that it should run a server in the foreground.
TEST_PERLBAL_FOREGROUND
See Perlbal::Test for more information.
If TEST_PERLBAL_USE_EXISTING is set to a true value then Perlbal::Test::start_server will be return a socket which is connected to an existing server's management port.
TEST_PERLBAL_USE_EXISTING
Perlbal::Test::start_server
Perlbal::Manual::Management.
To install Perlbal, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Perlbal
CPAN shell
perl -MCPAN -e shell install Perlbal
For more information on module installation, please visit the detailed CPAN module installation guide.