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 vari‐
27       ables/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 config‐
60       uration directive, rather than listing each one via "PassEnv" or "Perl‐
61       PassEnv", 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 meth‐
103       ods:
104
105       "server"
106
107       Get the current server's object for the <Perl> section
108
109         <Perl>
110           $s = Apache2::PerlSections->server();
111         </Perl>
112
113       obj: "Apache2::PerlSections" (class name)
114       ret: $s ( "Apache2::ServerRec object" )
115       since: 2.0.03
116

@PerlConfig and $PerlConfig

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

Configuration Variables

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

PerlSections Dumping

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

Advanced API

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

Verifying "<Perl>" Sections

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

Bugs

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

Copyright

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

Authors

381       The mod_perl development team and numerous contributors.
382
383
384
385perl v5.8.8                       2006-11-19docs::api::Apache2::PerlSections(3)