Perlba...ration(3pm)

💖 Perlba...ration(3pm) 💖

ok so bestie, this is the Perlbal::Manual::Configuration page — literally the "how do I configure Perlbal" bible, straight out of the User Contributed Perl Documentation. it's giving setup-guide realness and i'm obsessed. let's go 🫶

---

✨ VERSION ✨

Perlbal 1.78. that's the one, no cap.

---

🌸 DESCRIPTION 🌸

okay so by default, Perlbal goes looking for its config file at /etc/perlbal/perlbal.conf. like, that's home base. periodt.

but bestie, you can absolutely point perlbal at a different config file with the -c flag:

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

and -c has an alias — --conf. two names, one icon 👑

💅 Setting up Perlbal as a daemon 💅

you can run perlbal as a daemon, and honestly? main character energy:

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

--daemon has the alias -d.

a common practice (very common, very slay) is to create a perlbal.sh file that supports the common operations you'll require (start, stop, restart) and drop it under /etc/init.d. you can find a sample file in debian/perlbal.init — go look, it's right there 💖

🎀 Configuration file 🎀

a Perlbal config file is a text file where you:

• create pools and services
• add servers to pools
• set services' parameters
• enable/disable services

indentation is not mandatory, but it's considered a good practice for readability issues. so like, indent for the aesthetic, bestie ✨

configuration is case insensitive, but it's also a good practice to uppercase all directives. yes you can write it lowercase, no you should not — uppercase is the vibe.

🌈 Pools 🌈

here's a sample config 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. easy. ate.

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, because it's 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. so clean your file up however you want, it's fine 💅

Perlbal will check the file periodically for updates. like a little check-in, love that for it.

the path to the file is relative to where perlbal was started. important!! relative, not absolute.

note that:

SET pool nodefile = none
(also undef, null, "", '')

…unsets the nodefile, but does not remove current members. so the members stay, they're just no longer being refreshed from a file. not me being dramatic about it 😭

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! like, it just gives up on the file entirely. so pick a lane, bestie.

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. one option, but she's serving 💅

👑 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, go peek).

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. basically: tell her who she is before you start asking for things 🙈

💜 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". so like, pre-game those defaults, bestie ✨

🧚 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. yes, the typo "these lines is" is in the original and yes, i'm keeping it, facts don't change 💖

🌸 Including configuration files 🌸

while Perlbal doesn't natively let you include a configuration file within another, one of its core Plugins does. teamwork!

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. glob patterns and everything, we love a range 👑

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

that's the whole list, btw. one (1) expansion. she's niche and she's valid 🦋

🎀 Comments 🎀

comments in Perlbal's configuration files start with a #:

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

inline comments? yes. full-line comments? also yes. comment your config, bestie, future you will thank you 💅

🔥 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. go read it, it's a whole thing 📚

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. receipts, basically 🧾

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.

so like — free speed, but the safety net is gone. do not be reckless with this one, bestie 😭

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

copy that pattern exactly, it's the whole point 👑

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. pick one, she's exclusive 💅

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. (yes, "will be return" — original wording, preserving it fr fr)

see Perlbal::Test for more information.

---

🌟 SEE ALSO 🌟

• Perlbal::Manual::Management.

---

and that's the whole page, bestie!! this was perl v5.34.0, dated 2022-06-28, from the User Contributed Perl Documentation collection. go forth and configure, you absolute icon 💖✨🎀