Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Perlbal::Manual::ConfiUsertContributed Perl DPerlbal::Manual::Configuration(3)

       Perlbal::Manual::Configuration -	How to configure Perlbal

       Perlbal 1.78.

       By default, Perlbal looks for a configuration file at

       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.

   Setting up Perlbal as a daemon
       You can run "perlbal" as	a daemon:

	   $ perlbal --daemon -c /home/user/perlbal.conf

       --daemon	has the	alias -d.

       A common	practice is to create a	"" 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

   Configuration file
       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
	       POOL mywebsite ADD

       The first line creates a	pool called "mywebsite". The second and	third
       lines add two different servers to that pool.

       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
	       POOL ADD

       Configuring a pool in a separate	file

       You can create a	pool in	a separate file	by using the "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).

       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.

       Pool balance method

       You can set the pool balance method:

	   SET pool balance_method = 'random'

       At the present time, "random" is	the only load balancing	method


       Here's a	sample service:

	   CREATE SERVICE service_mywebsite
	       SET role		   = reverse_proxy
	       SET pool		   = mywebsite
	       SET listen	   =

       The first line creates a	service	called "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.

       Setting parameters

       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.

       Note on types:

       '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.

       Setting parameter defaults

       Outside the scope of a service you can set parameter defaults for all
       following created services:

	   SET <param> = <value>

       This takes the same parameters as the section above ""Setting

       Enabling/Disabling services

       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).

       Including configuration files

       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 = /usr/local/etc/perlbal/my.conf
	   INCLUDE = /usr/local/etc/perlbal/other.conf /usr/local/etc/perlbal/*.conf

       See Perlbal::Plugin::Include for	further	examples and more information.


       The following things expand/interpolate in config files/commands:

	   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

   Environment variables

       Used in "Makefile.PL". If set to	a true value the modules will not be


       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


       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

       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


       This is the variable you'll have	to set to a true value in order	to
       properly	use the	commands "obj" or "track".

       See Perlbal::Manual::Management for more	information.


       Setting this variable true will give perlbal an extra speed boost on
       perl 5.10+ by removing run-time locking of field	names on internal
       objects.	As a tradeoff this will	make code such as plugins or patch
       sets that incorrectly handling fields in	perlbal	to silently fail
       rather than giving warnings and errors.

       Use with	caution	until you trust	your combination of perlbal version,
       plugins and versions and	other patches you may have applied. Once you
       trust you perlbal instance to have no problems this option should
       simply make perlbal faster.


       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:


       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".

       See Perlbal::Manual::Management for more	information.


       By setting to a true value you can enable Perlbal::XS::HTTPHeaders, if

       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.

       See Perlbal::Test for more information.


       This variable is	used by	Perlbal::Test to test Perlbal.

       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.

       See Perlbal::Test for more information.


perl v5.32.0			  2020-08-23 Perlbal::Manual::Configuration(3)


Want to link to this manual page? Use this URL:

home | help