Perlbal::Manual::Configuration(3pm)			User Contributed Perl Documentation		       Perlbal::Manual::Configuration(3pm)

NAME

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

   VERSION
       Perlbal 1.78.

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

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

   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.

       Pools

       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.

       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

       Configuring a pool in a separate file

       You can create a pool in a separate file by using the "nodefile" parameter:

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

       Services

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

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

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

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

       Expansions

       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

       Comments in Perlbal's configuration files start with a "#":

	   # this is a comment
	   ENABLE myservice # this is also a comment

   Environment variables
       DANGABUILD_DAEMONONLY

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

       DANGABUILD_MODULESONLY

       Used in "Makefile.PL". If set to a true value only the modules will be built, not the "perlbal" executable.

       PERLBAL_DEBUG

       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.

       PERLBAL_DEBUG_BUFFERED_UPLOADS

       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.

       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.

       PERLBAL_DEBUG_OBJ

       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.

       PERLBAL_REMOVE_FIELDS

       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.

       PERLBAL_TEST_ALPHA

       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;
	   }

       PERLBAL_TRACK_STATES

       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.

       PERLBAL_XS_HEADERS

       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.

       TEST_PERLBAL_FOREGROUND

       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.

       TEST_PERLBAL_USE_EXISTING

       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.

   SEE ALSO
       Perlbal::Manual::Management.

perl v5.14.2							    2012-02-20				       Perlbal::Manual::Configuration(3pm)