Apache2::PerlSections(3pm)

1docs::api::Apache2::PerUlsSeerctCioonntsr(i3b)uted PerldDooccsu:m:eanptia:t:iAopnache2::PerlSections(3)
2
3
4

NAME

6       Apache2::PerlSections - write Apache configuration files in Perl
7

Synopsis

9         <Perl>
10         @PerlModule = qw(Mail::Send Devel::Peek);
11
12         #run the server as whoever starts it
13         $User  = getpwuid(>) || >;
14         $Group = getgrgid()) || );
15
16         $ServerAdmin = $User;
17
18         </Perl>
19

Description

21       With "<Perl>"..."</Perl>" sections, it is possible to configure your
22       server entirely in Perl.
23
24       "<Perl>" sections can contain any and as much Perl code as you wish.
25       These sections are compiled into a special package whose symbol table
26       mod_perl can then walk and grind the names and values of Perl
27       variables/structures through the Apache core configuration gears.
28
29       Block sections such as "<Location>".."</Location>" are represented in a
30       %Location hash, e.g.:
31
32         <Perl>
33         $Location{"/~dougm/"} = {
34           AuthUserFile   => '/tmp/htpasswd',
35           AuthType       => 'Basic',
36           AuthName       => 'test',
37           DirectoryIndex => [qw(index.html index.htm)],
38           Limit          => {
39               "GET POST"    => {
40                   require => 'user dougm',
41               }
42           },
43         };
44         </Perl>
45
46       If an Apache directive can take two or three arguments you may push
47       strings (the lowest number of arguments will be shifted off the @list)
48       or use an array reference to handle any number greater than the minimum
49       for that directive:
50
51         push @Redirect, "/foo", "http://www.foo.com/";
52
53         push @Redirect, "/imdb", "http://www.imdb.com/";
54
55         push @Redirect, [qw(temp "/here" "http://www.there.com")];
56
57       Other section counterparts include %VirtualHost, %Directory and %Files.
58
59       To pass all environment variables to the children with a single
60       configuration directive, rather than listing each one via "PassEnv" or
61       "PerlPassEnv", a "<Perl>" section could read in a file and:
62
63         push @PerlPassEnv, [$key => $val];
64
65       or
66
67         Apache2->httpd_conf("PerlPassEnv $key $val");
68
69       These are somewhat simple examples, but they should give you the basic
70       idea. You can mix in any Perl code you desire. See eg/httpd.conf.pl and
71       eg/perl_sections.txt in the mod_perl distribution for more examples.
72
73       Assume that you have a cluster of machines with similar configurations
74       and only small distinctions between them: ideally you would want to
75       maintain a single configuration file, but because the configurations
76       aren't exactly the same (e.g. the "ServerName" directive) it's not
77       quite that simple.
78
79       "<Perl>" sections come to rescue. Now you have a single configuration
80       file and the full power of Perl to tweak the local configuration. For
81       example to solve the problem of the "ServerName" directive you might
82       have this "<Perl>" section:
83
84         <Perl>
85         $ServerName = `hostname`;
86         </Perl>
87
88       For example if you want to allow personal directories on all machines
89       except the ones whose names start with secure:
90
91         <Perl>
92         $ServerName = `hostname`;
93         if ($ServerName !~ /^secure/) {
94             $UserDir = "public.html";
95         }
96         else {
97             $UserDir = "DISABLED";
98         }
99         </Perl>
100

API

102       "Apache2::PerlSections" provides the following functions and/or
103       methods:
104
105   "server"
106       Get the current server's object for the <Perl> section
107
108         <Perl>
109           $s = Apache2::PerlSections->server();
110         </Perl>
111
112       obj: "Apache2::PerlSections" (class name)
113       ret: $s ( "Apache2::ServerRec object" )
114       since: 2.0.03
115

@PerlConfig and $PerlConfig

117       This array and scalar can be used to introduce literal configuration
118       into the apache configuration. For example:
119
120         push @PerlConfig, 'Alias /foo /bar';
121
122       Or:
123         $PerlConfig .= "Alias /foo /bar\n";
124
125       See also "$r->add_config"
126

Configuration Variables

128       There are a few variables that can be set to change the default
129       behaviour of "<Perl>" sections.
130
131   $Apache2::PerlSections::Save
132       Each "<Perl>" section is evaluated in its unique namespace, by default
133       residing in a sub-namespace of "Apache2::ReadConfig::", therefore any
134       local variables will end up in that namespace. For example if a
135       "<Perl>" section happened to be in file /tmp/httpd.conf starting on
136       line 20, the namespace: "Apache2::ReadConfig::tmp::httpd_conf::line_20"
137       will be used. Now if it had:
138
139         <Perl>
140           $foo     = 5;
141           my $bar  = 6;
142           $My::tar = 7;
143         </Perl>
144
145       The local global variable $foo becomes
146       $Apache2::ReadConfig::tmp::httpd_conf::line_20::foo, the other variable
147       remain where they are.
148
149       By default, the namespace in which "<Perl>" sections are evaluated is
150       cleared after each block closes. In our example nuking
151       $Apache2::ReadConfig::tmp::httpd_conf::line_20::foo, leaving the rest
152       untouched.
153
154       By setting $Apache2::PerlSections::Save to a true value, the content of
155       those namespaces will be preserved and will be available for inspection
156       by "Apache2::Status" and "Apache2::PerlSections->dump" In our example
157       $Apache2::ReadConfig::tmp::httpd_conf::line_20::foo will still be
158       accessible from other perl code, after the "<Perl>" section was parsed.
159

PerlSections Dumping

161   "Apache2::PerlSections->dump"
162       This method will dump out all the configuration variables mod_perl will
163       be feeding to the apache config gears. The output is suitable to read
164       back in via "eval".
165
166         my $dump = Apache2::PerlSections->dump;
167
168       ret: $dump ( string / "undef" )
169           A string dump of all the Perl code encountered in <Perl> blocks,
170           suitable to be read back via "eval"
171
172       For example:
173
174         <Perl>
175
176         $Apache2::PerlSections::Save = 1;
177
178         $Listen = 8529;
179
180         $Location{"/perl"} = {
181            SetHandler => "perl-script",
182            PerlHandler => "ModPerl::Registry",
183            Options => "ExecCGI",
184         };
185
186         @DirectoryIndex = qw(index.htm index.html);
187
188         $VirtualHost{"www.foo.com"} = {
189            DocumentRoot => "/tmp/docs",
190            ErrorLog => "/dev/null",
191            Location => {
192              "/" => {
193                Allowoverride => 'All',
194                Order => 'deny,allow',
195                Deny  => 'from all',
196                Allow => 'from foo.com',
197              },
198            },
199         };
200         </Perl>
201
202         <Perl>
203         print Apache2::PerlSections->dump;
204         </Perl>
205
206       This will print something like this:
207
208         $Listen = 8529;
209
210         @DirectoryIndex = (
211           'index.htm',
212           'index.html'
213         );
214
215         $Location{'/perl'} = (
216             PerlHandler => 'Apache2::Registry',
217             SetHandler => 'perl-script',
218             Options => 'ExecCGI'
219         );
220
221         $VirtualHost{'www.foo.com'} = (
222             Location => {
223               '/' => {
224                 Deny => 'from all',
225                 Order => 'deny,allow',
226                 Allow => 'from foo.com',
227                 Allowoverride => 'All'
228               }
229             },
230             DocumentRoot => '/tmp/docs',
231             ErrorLog => '/dev/null'
232         );
233
234         1;
235         __END__
236
237       It is important to put the call to "dump" in it's own "<Perl>" section,
238       otherwise the content of the current "<Perl>" section will not be
239       dumped.
240
241   "Apache2::PerlSections->store"
242       This method will call the "dump" method, writing the output to a file,
243       suitable to be pulled in via "require" or "do".
244
245         Apache2::PerlSections->store($filename);
246
247       arg1: $filename (string)
248           The filename to save the dump output to
249
250       ret: no return value
251

Advanced API

253       mod_perl 2.0 now introduces the same general concept of handlers to
254       "<Perl>" sections.  Apache2::PerlSections simply being the default
255       handler for them.
256
257       To specify a different handler for a given perl section, an extra
258       handler argument must be given to the section:
259
260         <Perl handler="My::PerlSection::Handler" somearg="test1">
261           $foo = 1;
262           $bar = 2;
263         </Perl>
264
265       And in My/PerlSection/Handler.pm:
266
267         sub My::Handler::handler : handler {
268             my ($self, $parms, $args) = @_;
269             #do your thing!
270         }
271
272       So, when that given "<Perl>" block in encountered, the code within will
273       first be evaluated, then the handler routine will be invoked with 3
274       arguments:
275
276       arg1: $self
277           self-explanatory
278
279       arg2: $parms ( "Apache2::CmdParms" )
280           $parms is specific for the current Container, for example, you
281           might want to call "$parms->server()" to get the current server.
282
283       arg3: $args ( "APR::Table object")
284           the table object of the section arguments. The 2 guaranteed ones
285           will be:
286
287             $args->{'handler'} = 'My::PerlSection::Handler';
288             $args->{'package'} = 'Apache2::ReadConfig';
289
290           Other "name="value"" pairs given on the "<Perl>" line will also be
291           included.
292
293       At this point, it's up to the handler routing to inspect the namespace
294       of the $args->{'package'} and chooses what to do.
295
296       The most likely thing to do is to feed configuration data back into
297       apache. To do that, use Apache2::Server->add_config("directive"), for
298       example:
299
300         $parms->server->add_config("Alias /foo /bar");
301
302       Would create a new alias. The source code of "Apache2::PerlSections" is
303       a good place to look for a practical example.
304

Verifying "<Perl>" Sections

306       If the "<Perl>" sections include no code requiring a running mod_perl,
307       it is possible to check those from the command line. But the following
308       trick should be used:
309
310         # file: httpd.conf
311         <Perl>
312         #!perl
313
314         # ... code here ...
315
316         __END__
317         </Perl>
318
319       Now you can run:
320
321         % perl -c httpd.conf
322

Bugs

324   <Perl> directive missing closing '>'
325       httpd-2.0.47 had a bug in the configuration parser which caused the
326       startup failure with the following error:
327
328         Starting httpd:
329         Syntax error on line ... of /etc/httpd/conf/httpd.conf:
330         <Perl> directive missing closing '>'     [FAILED]
331
332       This has been fixed in httpd-2.0.48. If you can't upgrade to this or a
333       higher version, please add a space before the closing '>' of the
334       opening tag as a workaround. So if you had:
335
336         <Perl>
337         # some code
338         </Perl>
339
340       change it to be:
341
342         <Perl >
343         # some code
344         </Perl>
345
346   <Perl>[...]> was not closed.
347       On encountering a one-line <Perl> block, httpd's configuration parser
348       will cause a startup failure with an error similar to this one:
349
350         Starting httpd:
351         Syntax error on line ... of /etc/httpd/conf/httpd.conf:
352         <Perl>use> was not closed.
353
354       If you have written a simple one-line <Perl> section like this one :
355
356         <Perl>use Apache::DBI;</Perl>
357
358       change it to be:
359
360          <Perl>
361          use Apache::DBI;
362          </Perl>
363
364       This is caused by a limitation of httpd's configuration parser and is
365       not likely to be changed to allow one-line block like the example
366       above. Use multi-line blocks instead.
367

Copyright

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

Authors

376       The mod_perl development team and numerous contributors.
377
378
379
380perl v5.38.0                      2023-07-20docs::api::Apache2::PerlSections(3)