1docs::api::Apache2::PerUlsSeerctCioonntsr(i3b)uted PerldDooccsu:m:eanptia:t:iAopnache2::PerlSections(3)
2
3
4
6 Apache2::PerlSections - write Apache configuration files in Perl
7
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
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
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
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
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
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
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
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
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
369 mod_perl 2.0 documentation.
370
372 mod_perl 2.0 and its core modules are copyrighted under The Apache
373 Software License, Version 2.0.
374
376 The mod_perl development team and numerous contributors.
377
378
379
380perl v5.28.1 2016-10-27docs::api::Apache2::PerlSections(3)