libapa...ections(3pm)

🎀 libapa...ections(3pm) 🎀

okay bestie, welcome to libapa...ections(3pm) from the User Contributed Perl Documentation section 💅 this is the page that teaches you how to write your whole Apache config in Perl, and honestly? it ate.

🌸 NAME 🌸

Apache2::PerlSections — write Apache configuration files in Perl ✨

---

🦋 Synopsis 🦋

<Perl>
@PerlModule = qw(Mail::Send Devel::Peek);

#run the server as whoever starts it
$User  = getpwuid(>) || >;
$Group = getgrgid()) || );

$ServerAdmin = $User;

</Perl>

like. look at that. config file but make it Perl 🫶

---

💜 Description 💜

so the whole vibe: with <Perl>...</Perl> sections, you can configure your server entirely in Perl. no cap.

A <Perl> section can hold any and as much Perl code as you want, fr fr. These sections get compiled into a special package whose symbol table mod_perl then walks and grinds — taking the names and values of your Perl variables/structures and shoving them through the Apache core configuration gears 🔥

Block sections like <Location>..</Location> show up as a %Location hash, like this:

<Perl>
$Location{"/~dougm/"} = {
  AuthUserFile   => '/tmp/htpasswd',
  AuthType       => 'Basic',
  AuthName       => 'test',
  DirectoryIndex => [qw(index.html index.htm)],
  Limit          => {
      "GET POST"    => {
          require => 'user dougm',
      }
  },
};
</Perl>

If an Apache directive can take two or three arguments, you have options bestie ✨ you can push strings (the lowest number of arguments will be shifted off the @list) or use an array reference when you need to handle any number greater than the minimum for that directive:

push @Redirect, "/foo", "http://www.foo.com/";

push @Redirect, "/imdb", "http://www.imdb.com/";

push @Redirect, [qw(temp "/here" "http://www.there.com")];

Other section counterparts include %VirtualHost, %Directory and %Files 👑

Wanna pass all the environment variables to the children with a single configuration directive instead of listing each one via PassEnv or PerlPassEnv? A <Perl> section could read in a file and:

push @PerlPassEnv, [$key => $val];

or

Apache2->httpd_conf("PerlPassEnv $key $val");

These are somewhat simple examples, but they should give you the basic idea. You can mix in any Perl code you desire. See eg/httpd.conf.pl and eg/perl_sections.txt in the mod_perl distribution for more examples 🌈

okay now imagine this: you have a cluster of machines with similar configurations and only small distinctions between them. Ideal world? you'd maintain a single configuration file. But the configurations aren't exactly the same (e.g. the ServerName directive) so it's not quite that simple 😭

enter <Perl> sections to the rescue 🦋 Now you have a single configuration file and the full power of Perl to tweak the local configuration. For example, to solve the problem of the ServerName directive you might have this <Perl> section:

<Perl>
$ServerName = `hostname`;
</Perl>

And say you want to allow personal directories on all machines except the ones whose names start with secure:

<Perl>
$ServerName = `hostname`;
if ($ServerName !~ /^secure/) {
    $UserDir = "public.html";
}
else {
    $UserDir = "DISABLED";
}
</Perl>

main character energy tbh 💅

---

✨ API ✨

Apache2::PerlSections provides the following functions and/or methods:

🌟 server

Get the current server's object for the <Perl> section.

<Perl>
  $s = Apache2::PerlSections->server();
</Perl>

• obj: Apache2::PerlSections (class name)
• ret: $s ( Apache2::ServerRec object )
• since: 2.0.03

💜 @PerlConfig and $PerlConfig

This array and scalar can be used to introduce literal configuration into the apache configuration. For example:

push @PerlConfig, 'Alias /foo /bar';

Or:

$PerlConfig .= "Alias /foo /bar\n";

See also $r->add_config 🫶

---

🌈 Configuration Variables 🌈

There are a few variables that can be set to change the default behaviour of <Perl> sections.

🍓 $Apache2::PerlSections::Save

Each <Perl> section is evaluated in its unique namespace, by default residing in a sub-namespace of Apache2::ReadConfig::, therefore any local variables will end up in that namespace. For example, if a <Perl> section happened to be in file tmp/httpd.conf starting on line 20, the namespace Apache2::ReadConfig::tmp::httpd_conf::line_20 will be used. Now if it had:

<Perl>
  $foo     = 5;
  my $bar  = 6;
  $My::tar = 7;
</Perl>

The local global variable $foo becomes $Apache2::ReadConfig::tmp::httpd_conf::line_20::foo, the other variable remain where they are.

By default, the namespace in which <Perl> sections are evaluated is cleared after each block closes. In our example, nuking $Apache2::ReadConfig::tmp::httpd_conf::line_20::foo, leaving the rest untouched 💀

By setting $Apache2::PerlSections::Save to a true value, the content of those namespaces will be preserved and will be available for inspection by Apache2::Status and Apache2::PerlSections->dump. In our example $Apache2::ReadConfig::tmp::httpd_conf::line_20::foo will still be accessible from other perl code, after the <Perl> section was parsed ✨

---

💖 PerlSections Dumping 💖

🎀 Apache2::PerlSections->dump

This method will dump out all the configuration variables mod_perl will be feeding to the apache config gears. The output is suitable to read back in via eval.

my $dump = Apache2::PerlSections->dump;

• ret: $dump ( string / undef ) — a string dump of all the Perl code encountered in <Perl> blocks, suitable to be read back via eval

For example:

<Perl>

$Apache2::PerlSections::Save = 1;

$Listen = 8529;

$Location{"/perl"} = {
   SetHandler => "perl-script",
   PerlHandler => "ModPerl::Registry",
   Options => "ExecCGI",
};

@DirectoryIndex = qw(index.htm index.html);

$VirtualHost{"www.foo.com"} = {
   DocumentRoot => "/tmp/docs",
   ErrorLog => "/dev/null",
   Location => {
     "/" => {
       Allowoverride => 'All',
       Order => 'deny,allow',
       Deny  => 'from all',
       Allow => 'from foo.com',
     },
   },
};
</Perl>

<Perl>
print Apache2::PerlSections->dump;
</Perl>

This will print something like this:

$Listen = 8529;

@DirectoryIndex = (
  'index.htm',
  'index.html'
);

$Location{'/perl'} = (
    PerlHandler => 'Apache2::Registry',
    SetHandler => 'perl-script',
    Options => 'ExecCGI'
);

$VirtualHost{'www.foo.com'} = (
    Location => {
      '/' => {
        Deny => 'from all',
        Order => 'deny,allow',
        Allow => 'from foo.com',
        Allowoverride => 'All'
      }
    },
    DocumentRoot => '/tmp/docs',
    ErrorLog => '/dev/null'
);

1;
__END__

⚠️ it is important to put the call to dump in its own <Perl> section, otherwise the content of the current <Perl> section will not be dumped. no cap, this one gets people every time 😭

🦋 Apache2::PerlSections->store

This method will call the dump method, writing the output to a file, suitable to be pulled in via require or do.

Apache2::PerlSections->store($filename);

• arg1: $filename (string) — the filename to save the dump output to
• ret: no return value

---

👑 Advanced API 👑

mod_perl 2.0 now introduces the same general concept of handlers to <Perl> sections. Apache2::PerlSections simply being the default handler for them 🌟

To specify a different handler for a given perl section, an extra handler argument must be given to the section:

<Perl handler="My::PerlSection::Handler" somearg="test1">
  $foo = 1;
  $bar = 2;
</Perl>

And in My/PerlSection/Handler.pm:

sub My::Handler::handler : handler {
    my ($self, $parms, $args) = @_;
    #do your thing!
}

So, when that given <Perl> block is encountered, the code within will first be evaluated, then the handler routine will be invoked with 3 arguments:

• arg1: $self — self-explanatory 💅
• arg2: $parms ( Apache2::CmdParms ) — $parms is specific for the current Container, for example, you might want to call $parms->server() to get the current server.
• arg3: $args ( APR::Table object ) — the table object of the section arguments. The 2 guaranteed ones will be:

$args->{'handler'} = 'My::PerlSection::Handler';
$args->{'package'} = 'Apache2::ReadConfig';

Other name="value" pairs given on the <Perl> line will also be included ✨

At this point, it's up to the handler routing to inspect the namespace of the $args->{'package'} and choose what to do.

The most likely thing to do is to feed configuration data back into apache. To do that, use Apache2::Server->add_config("directive"), for example:

$parms->server->add_config("Alias /foo /bar");

Would create a new alias. The source code of Apache2::PerlSections is a good place to look for a practical example 👑

---

🌸 Verifying <Perl> Sections 🌸

If the <Perl> sections include no code requiring a running mod_perl, it is possible to check those from the command line. But the following trick should be used:

# file: httpd.conf
<Perl>
#!perl

# ... code here ...

__END__
</Perl>

Now you can run:

% perl -c httpd.conf

vibe check: passed ✅

---

💀 Bugs 💀

😭 <Perl> directive missing closing '>'

httpd-2.0.47 had a bug in the configuration parser which caused the startup failure with the following error:

Starting httpd:
Syntax error on line ... of /etc/httpd/conf/httpd.conf:
<Perl> directive missing closing '>'     [FAILED]

This has been fixed in httpd-2.0.48. If you can't upgrade to this or a higher version, please add a space before the closing > of the opening tag as a workaround. So if you had:

<Perl>
# some code
</Perl>

change it to be:

<Perl >
# some code
</Perl>

one space. that's it. that's the fix 🙈

🫶 <Perl>[...]> was not closed.

On encountering a one-line <Perl> block, httpd's configuration parser will cause a startup failure with an error similar to this one:

Starting httpd:
Syntax error on line ... of /etc/httpd/conf/httpd.conf:
<Perl>use> was not closed.

If you have written a simple one-line <Perl> section like this one:

<Perl>use Apache::DBI;</Perl>

change it to be:

 <Perl>
 use Apache::DBI;
 </Perl>

This is caused by a limitation of httpd's configuration parser and is not likely to be changed to allow one-line block like the example above. Use multi-line blocks instead 💅

---

🔥 See Also 🔥

mod_perl 2.0 documentation.

---

⭐ Copyright ⭐

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

---

👑 AUTHORS 👑

Okay so who do we have to thank for this whole thing? Bestie, it's a group project that actually worked:

• The mod_perl development team 💖
• and numerous contributors 🌈

That's it, that's the roster — no solo main character here, just a whole squad of legends who showed up, wrote code, and gave us <Perl> sections to play with. Absolute icons, every single one. 👑

---

and that's a wrap on libapa...ections(3pm), bestie 🎀 you just read the perl v5.42.3 version, dated 2026-08-20 — so if your copy says something different, you're reading a whole other timeline fr fr. go configure something iconic, drink some water, and remember: the mod_perl dev team ate and left no crumbs 💅✨🦋