Apache2::ServerUtil(3pm)

1docs::api::Apache2::SerUvseerrUtCioln(t3r)ibuted Perl Dodcoucmse:n:taaptii:o:nApache2::ServerUtil(3)
2
3
4

NAME

6       Apache2::ServerUtil - Perl API for Apache server record utils
7

Synopsis

9         use Apache2::ServerUtil ();
10         $s = Apache2::ServerUtil->server;
11
12         # push config
13         $s->add_config(['ServerTokens off']);
14
15         # add components to the Server signature
16         $s->add_version_component("MyModule/1.234");
17
18         # access PerlSetVar/PerlAddVar values
19         my $srv_cfg = $s->dir_config;
20
21         # check command line defines
22         print "this is mp2"
23             if Apache2::ServerUtil::exists_config_define('MODPERL2');
24
25         # get PerlChildExitHandler configured handlers
26         @handlers = @{ $s->get_handlers('PerlChildExitHandler') || []};
27
28         # server build and version info:
29         $when_built = Apache2::ServerUtil::get_server_built();
30         $description = Apache2::ServerUtil::get_server_description();
31         $version = Apache2::ServerUtil::get_server_version();
32         $banner = Apache2::ServerUtil::get_server_banner();
33
34         # ServerRoot value
35         $server_root = Apache2::ServerUtil::server_root();
36
37         # get 'conf/' dir path (avoid using this function!)
38         my $dir = Apache2::ServerUtil::server_root_relative($r->pool, 'conf');
39
40         # set child_exit handlers
41         $r->set_handlers(PerlChildExitHandler => \&handler);
42
43         # server level PerlOptions flags lookup
44         $s->push_handlers(ChildExit => \&child_exit)
45             if $s->is_perl_option_enabled('ChildExit');
46
47         # extend HTTP to support a new method
48         $s->method_register('NEWGET');
49
50         # register server shutdown callback
51         Apache2::ServerUtil::server_shutdown_register_cleanup(sub { Apache2::Const::OK });
52
53         # do something only when the server restarts
54         my $cnt = Apache2::ServerUtil::restart_count();
55         do_something_once() if $cnt > 1;
56
57         # get the resolved ids from Group and User entries
58         my $user_id  = Apache2::ServerUtil->user_id;
59         my $group_id = Apache2::ServerUtil->group_id;
60

Description

62       "Apache2::ServerUtil" provides the Apache server object utilities API.
63

Methods API

65       "Apache2::ServerUtil" provides the following functions and/or methods:
66
67   "add_config"
68       Dynamically add Apache configuration:
69
70         $s->add_config($lines);
71
72       obj: $s ( "Apache2::ServerRec object" )
73       arg1: $lines ( ARRAY ref )
74           An ARRAY reference containing configuration lines per element,
75           without the new line terminators.
76
77       ret: no return value
78       since: 2.0.00
79
80       See also: "$r->add_config"
81
82       For example:
83
84       Add a configuration section at the server startup (e.g. from
85       startup.pl):
86
87         use Apache2::ServerUtil ();
88         my $conf = <<'EOC';
89         PerlModule Apache2::MyExample
90         <Location /perl>
91           SetHandler perl-script
92           PerlResponseHandler Apache2::MyExample
93         </Location>
94         EOC
95         Apache2::ServerUtil->server->add_config([split /\n/, $conf]);
96
97   "add_version_component"
98       Add a component to the version string
99
100         $s->add_version_component($component);
101
102       obj: $s ( "Apache2::ServerRec object" )
103       arg1: $component ( string )
104           The string component to add
105
106       ret: no return value
107       since: 2.0.00
108
109       This function is usually used by modules to advertise themselves to the
110       world. It's picked up by such statistics collectors, like netcraft.com,
111       which accomplish that by connecting to various servers and grabbing the
112       server version response header ("Server"). Some servers choose to fully
113       or partially conceal that header.
114
115       This method should be invoked in the "PerlPostConfigHandler" phase,
116       which will ensure that the Apache core version number will appear
117       first.
118
119       For example let's add a component "Hikers, Inc/0.99999" to the server
120       string at the server startup:
121
122         use Apache2::ServerUtil ();
123         use Apache2::Const -compile => 'OK';
124
125         Apache2::ServerUtil->server->push_handlers(
126             PerlPostConfigHandler => \&add_my_version);
127
128         sub add_my_version {
129             my ($conf_pool, $log_pool, $temp_pool, $s) = @_;
130             $s->add_version_component("Hikers, Inc/0.99999");
131             return Apache2::Const::OK;
132         }
133
134       or of course you could register the "PerlPostConfigHandler" handler
135       directly in httpd.conf
136
137       Now when the server starts, you will something like:
138
139         [Thu Jul 15 12:15:28 2004] [notice] Apache/2.0.51-dev (Unix)
140         mod_perl/1.99_15-dev Perl/v5.8.5 Hikers, Inc/0.99999
141         configured -- resuming normal operations
142
143       Also remember that the "ServerTokens" directive value controls whether
144       the component information is displayed or not.
145
146   "dir_config"
147       "$s->dir_config()" provides an interface for the per-server variables
148       specified by the "PerlSetVar" and "PerlAddVar" directives, and also can
149       be manipulated via the "APR::Table" methods.
150
151         $table  = $s->dir_config();
152         $value  = $s->dir_config($key);
153         @values = $s->dir_config->get($key);
154         $s->dir_config($key, $val);
155
156       obj: $s ( "Apache2::ServerRec object" )
157       opt arg2: $key ( string )
158           Key string
159
160       opt arg3: $val ( string )
161           Value string
162
163       ret: ...
164           Depends on the passed arguments, see further discussion
165
166       since: 2.0.00
167
168       The keys are case-insensitive.
169
170         $t = $s->dir_config();
171
172       dir_config() called in a scalar context without the $key argument
173       returns a HASH reference blessed into the APR::Table class. This object
174       can be manipulated via the APR::Table methods. For available methods
175       see APR::Table.
176
177         @values = $s->dir_config->get($key);
178
179       To receive a list of values you must use "get()" method from the
180       "APR::Table" class.
181
182         $value = $s->dir_config($key);
183
184       If the $key argument is passed in the scalar context only a single
185       value will be returned. Since the table preserves the insertion order,
186       if there is more than one value for the same key, the oldest value
187       assosiated with the desired key is returned. Calling in the scalar
188       context is also much faster, as it'll stop searching the table as soon
189       as the first match happens.
190
191         $s->dir_config($key => $val);
192
193       If the $key and the $val arguments are used, the set() operation will
194       happen: all existing values associated with the key $key (and the key
195       itself) will be deleted and $value will be placed instead.
196
197         $s->dir_config($key => undef);
198
199       If $val is undef the unset() operation will happen: all existing values
200       associated with the key $key (and the key itself) will be deleted.
201
202   "exists_config_define"
203       Check for a definition from the server startup command line (e.g.
204       "-DMODPERL2")
205
206         $result = Apache2::ServerUtil::exists_config_define($name);
207
208       arg1: $name ( string )
209           The define string to check for
210
211       ret: $result ( boolean )
212           true if defined, false otherwise
213
214       since: 2.0.00
215
216       For example:
217
218         print "this is mp2"
219             if Apache2::ServerUtil::exists_config_define('MODPERL2');
220
221   "get_handlers"
222       Returns a reference to a list of handlers enabled for a given phase.
223
224         $handlers_list = $s->get_handlers($hook_name);
225
226       obj: $s ( "Apache2::ServerRec object" )
227       arg1: $hook_name ( string )
228           a string representing the phase to handle.
229
230       ret: $handlers_list (ref to an ARRAY of CODE refs)
231           a list of references to the handler subroutines
232
233       since: 2.0.00
234
235       See also: "$r->add_config"
236
237       For example:
238
239       A list of handlers configured to run at the child_exit phase:
240
241         @handlers = @{ $s->get_handlers('PerlChildExitHandler') || []};
242
243   "get_server_built"
244       Get the date and time that the server was built
245
246         $when_built = Apache2::ServerUtil::get_server_built();
247
248       ret: $when_built ( string )
249           The server build time string
250
251       since: 2.0.00
252
253   "get_server_version"
254       Get the server version string
255
256         $version = Apache2::ServerUtil::get_server_version();
257
258       ret: $version ( string )
259           The server version string
260
261       since: 2.0.00
262
263   "get_server_banner"
264       Get the server banner
265
266        $banner = Apache2::ServerUtil::get_server_banner();
267
268       ret: $banner ( string )
269           The server banner
270
271       since: 2.0.4
272
273   "get_server_description"
274       Get the server description
275
276        $description = Apache2::ServerUtil::get_server_description();
277
278       ret: $description ( string )
279           The server description
280
281       since: 2.0.4
282
283   "group_id"
284       Get the group id corresponding to the "Group" directive in httpd.conf:
285
286         $gid = Apache2::ServerUtil->group_id;
287
288       obj: "Apache2::ServerUtil" (class name)
289       ret: $gid ( integer )
290           On Unix platforms returns the gid corresponding to the value used
291           in the "Group" directive in httpd.conf. On other platforms returns
292           0.
293
294       since: 2.0.03
295
296   "is_perl_option_enabled"
297       check whether a server level "PerlOptions" flag is enabled or not.
298
299         $result = $s->is_perl_option_enabled($flag);
300
301       obj: $s ( "Apache2::ServerRec object" )
302       arg1: $flag ( string )
303       ret: $result ( boolean )
304       since: 2.0.00
305
306       For example to check whether the "ChildExit" hook is enabled (which can
307       be disabled with "PerlOptions -ChildExit") and configure some handlers
308       to run if enabled:
309
310         $s->push_handlers(ChildExit => \&child_exit)
311             if $s->is_perl_option_enabled('ChildExit');
312
313       See also: PerlOptions and the equivalent function for directory level
314       PerlOptions flags.
315
316   "method_register"
317       Register a new request method, and return the offset that will be
318       associated with that method.
319
320         $offset = $s->method_register($methname);
321
322       obj: $s ( "Apache2::ServerRec object" )
323       arg1: $methname ( string )
324           The name of the new method to register (in addition to the already
325           supported "GET", "HEAD", etc.)
326
327       ret: $offset ( integer )
328           An int value representing an offset into a bitmask. You can
329           probably ignore it.
330
331       since: 2.0.00
332
333       This method allows you to extend the HTTP protocol to support new
334       methods, which fit the HTTP paradigm.  Of course you will need to write
335       a client that understands that protocol extension.  For a good example,
336       refer to the "MyApache2::SendEmail" example presented in "the
337       PerlHeaderParserHandler section", which demonstrates how a new method
338       "EMAIL" is registered and used.
339
340   "push_handlers"
341       Add one or more handlers to a list of handlers to be called for a given
342       phase.
343
344         $ok = $s->push_handlers($hook_name => \&handler);
345         $ok = $s->push_handlers($hook_name => [\&handler, \&handler2]);
346
347       obj: $s ( "Apache2::ServerRec object" )
348       arg1: $hook_name ( string )
349           the phase to add the handlers to
350
351       arg2: $handlers ( CODE ref or SUB name or an ARRAY ref )
352           a single handler CODE reference or just a name of the subroutine
353           (fully qualified unless defined in the current package).
354
355           if more than one passed, use a reference to an array of CODE refs
356           and/or subroutine names.
357
358       ret: $ok ( boolean )
359           returns a true value on success, otherwise a false value
360
361       since: 2.0.00
362
363       See also: "$r->add_config"
364
365       Examples:
366
367       A single handler:
368
369         $s->push_handlers(PerlChildExitHandler => \&handler);
370
371       Multiple handlers:
372
373         $s->push_handlers(PerlChildExitHandler => ['Foo::Bar::handler', \&handler2]);
374
375       Anonymous functions:
376
377         $s->push_handlers(PerlLogHandler => sub { return Apache2::Const::OK });
378
379   "restart_count"
380       How many times the server was restarted.
381
382         $restart_count = Apache2::ServerUtil::restart_count();
383
384       ret: "restart_count" ( number )
385       since: 2.0.00
386
387       The following demonstration should make it clear what values to expect
388       from this function. Let's add the following code to startup.pl, so it's
389       run every time httpd.conf is parsed:
390
391         use Apache2::ServerUtil ();
392         my $cnt = Apache2::ServerUtil::restart_count();
393         open my $fh, ">>/tmp/out" or die "$!";
394         print $fh "cnt: $cnt\n";
395         close $fh;
396
397       Now let's run a series of server starts and restarts and look at what
398       is logged into /tmp/out:
399
400         % httpd -k start
401         cnt: 1
402         cnt: 2
403
404         % httpd -k graceful
405         cnt: 1
406         cnt: 3
407
408         % httpd -k graceful
409         cnt: 1
410         cnt: 4
411
412         % httpd -k stop
413         cnt: 1
414
415       Remembering that Apache restarts itself immediately after starting, we
416       can see that the "restart_count" goes from 1 to 2 during the server
417       start. Moreover we can see that every operation forces the parsing of
418       httpd.conf and therefore reinitialization of mod_perl (and running all
419       the code found in httpd.conf). This happens even when the server is
420       shutdown via "httpd -k stop".
421
422       What conclusions can be drawn from this demonstration:
423
424       ·   "Apache2::ServerUtil::restart_count()" returns 1 every time some
425           "-k" command is passed to Apache (or "kill -USR1" or some
426           alternative signal is received).
427
428       ·   At all other times the count will be 2 or higher. So for example on
429           graceful restart the count will be 3 or higher.
430
431       For example if you want to run something every time "httpd -k" is run
432       you just need to check whether "restart_count()" returns 1:
433
434         my $cnt = Apache2::ServerUtil::restart_count();
435         do_something() if $cnt == 1;
436
437       To do something only when server restarts ("httpd -k start" or "httpd
438       -k graceful)", check whether "restart_count()" is bigger than 1:
439
440         my $cnt = Apache2::ServerUtil::restart_count();
441         do_something() if $cnt > 1;
442
443   "server"
444       Get the main server's object
445
446         $main_s = Apache2::ServerUtil->server();
447
448       obj: "Apache2::ServerUtil" (class name)
449       ret: $main_s ( "Apache2::ServerRec object" )
450       since: 2.0.00
451
452   "server_root"
453       returns the value set by the top-level "ServerRoot" directive.
454
455         $server_root = Apache2::ServerUtil::server_root();
456
457       ret: $server_root ( string )
458       since: 2.0.00
459
460   "server_root_relative"
461       Returns the canonical form of the filename made absolute to
462       "ServerRoot":
463
464         $path = Apache2::ServerUtil::server_root_relative($pool, $fname);
465
466       arg1: $pool ( "APR::Pool object" )
467           Make sure that you read the following explanation and understand
468           well which pool object you need to pass before using this function.
469
470       opt arg2: $fname ( string )
471       ret: $path ( string )
472           The concatenation of "ServerRoot" and the $fname.
473
474           If $fname is not specified, the value of "ServerRoot" is returned
475           with a trailing "/". (it's the same as using '' as $fname's value).
476
477       since: 2.0.00
478
479       $fname is appended to the value of "ServerRoot" and returned. For
480       example:
481
482         my $dir = Apache2::ServerUtil::server_root_relative($r->pool, 'logs');
483
484       You must be extra-careful when using this function. If you aren't sure
485       what you are doing don't use it.
486
487       It's much safer to build the path by yourself using use
488       "Apache2::ServerUtil::server_root()", For example:
489
490         use File::Spec::Functions qw(catfile);
491         my $path = catfile Apache2::ServerUtil::server_root, qw(t logs);
492
493       In this example, no memory allocation happens on the Apache-side and
494       you aren't risking to get a memory leak.
495
496       The problem with "server_root_relative" is that Apache allocates memory
497       to concatenate the path string. The memory is allocated from the pool
498       object. If you call this method on the server pool object it'll
499       allocate the memory from it.  If you do that at the server startup,
500       it's perfectly right, since you will do that only once. However if you
501       do that from within a request or a connection handler, you create a
502       memory leak every time it is called -- as the memory gets allocated
503       from the server pool, it will be freed only when the server is
504       shutdown. Therefore if you need to build a relative to the root server
505       path for the duration of the request, use the request pool:
506
507         use Apache2::RequestRec ();
508         Apache2::ServerUtil::server_root_relative($r->pool, $fname);
509
510       If you need to have the path for the duration of a connection (e.g.
511       inside a protocol handler), you should use:
512
513         use Apache2::Connection ();
514         Apache2::ServerUtil::server_root_relative($c->pool, $fname);
515
516       And if you want it for the scope of the server file:
517
518         use Apache2::Process ();
519         use Apache2::ServerUtil ();
520         Apache2::ServerUtil::server_root_relative($s->process->pool, $fname);
521
522       Moreover, you could have encountered the opposite problem, where you
523       have used a short-lived pool object to construct the path, but tried to
524       use the resulting path variable, when that pool has been destructed
525       already. In order to avoid mysterious segmentation faults, mod_perl
526       does a wasteful copy of the path string when returning it to you --
527       another reason to avoid using this function.
528
529   "server_shutdown_cleanup_register"
530       Register server shutdown cleanup callback:
531
532         Apache2::ServerUtil::server_shutdown_cleanup_register($sub);
533
534       arg1: $sub ( CODE ref or SUB name )
535       ret: no return value
536       since: 2.0.00
537
538       This function can be used to register a callback to be run once at the
539       server shutdown (compared to "PerlChildExitHandler" which will execute
540       the callback for each exiting child process).
541
542       For example in order to arrange the function "do_my_cleanups()" to be
543       run every time the server shuts down (or restarts), run the following
544       code at the server startup:
545
546         Apache2::ServerUtil::server_shutdown_cleanup_register(\&do_my_cleanups);
547
548       It's necessary to run this code at the server startup (normally
549       startup.pl). The function will croak if run after the
550       "PerlPostConfigHandler" phase.
551
552       Values returned from cleanup functions are ignored. If a cleanup dies
553       the exception is stringified and passed to "warn()". Usually, this
554       results in printing it to the error_log.
555
556   "set_handlers"
557       Set a list of handlers to be called for a given phase. Any previously
558       set handlers are forgotten.
559
560         $ok = $s->set_handlers($hook_name => \&handler);
561         $ok = $s->set_handlers($hook_name => [\&handler, \&handler2]);
562         $ok = $s->set_handlers($hook_name => []);
563         $ok = $s->set_handlers($hook_name => undef);
564
565       obj: $s ( "Apache2::ServerRec object" )
566       arg1: $hook_name ( string )
567           the phase to set the handlers in
568
569       arg2: $handlers ( CODE ref or SUB name or an ARRAY ref )
570           a reference to a single handler CODE reference or just a name of
571           the subroutine (fully qualified unless defined in the current
572           package).
573
574           if more than one passed, use a reference to an array of CODE refs
575           and/or subroutine names.
576
577           if the argument is "undef" or "[]" the list of handlers is reset to
578           zero.
579
580       ret: $ok ( boolean )
581           returns a true value on success, otherwise a false value
582
583       since: 2.0.00
584
585       See also: "$r->add_config"
586
587       Examples:
588
589       A single handler:
590
591         $r->set_handlers(PerlChildExitHandler => \&handler);
592
593       Multiple handlers:
594
595         $r->set_handlers(PerlFixupHandler => ['Foo::Bar::handler', \&handler2]);
596
597       Anonymous functions:
598
599         $r->set_handlers(PerlLogHandler => sub { return Apache2::Const::OK });
600
601       Reset any previously set handlers:
602
603         $r->set_handlers(PerlCleanupHandler => []);
604
605       or
606
607         $r->set_handlers(PerlCleanupHandler => undef);
608
609   "user_id"
610       Get the user id corresponding to the "User" directive in httpd.conf:
611
612         $uid = Apache2::ServerUtil->user_id;
613
614       obj: "Apache2::ServerUtil" (class name)
615       ret: $uid ( integer )
616           On Unix platforms returns the uid corresponding to the value used
617           in the "User" directive in httpd.conf. On other platforms returns
618           0.
619
620       since: 2.0.03
621

Unsupported API

623       "Apache2::ServerUtil" also provides auto-generated Perl interface for a
624       few other methods which aren't tested at the moment and therefore their
625       API is a subject to change. These methods will be finalized later as a
626       need arises. If you want to rely on any of the following methods please
627       contact the the mod_perl development mailing list so we can help each
628       other take the steps necessary to shift the method to an officially
629       supported API.
630
631   "error_log2stderr"
632       Start sending STDERR to the error_log file
633
634         $s->error_log2stderr();
635
636       obj: $s ( "Apache2::ServerRec object" )
637           The current server
638
639       ret: no return value
640       since: 2.0.00
641
642       This method may prove useful if you want to start redirecting STDERR to
643       the error_log file before Apache does that on the startup.
644

Copyright

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

Authors

653       The mod_perl development team and numerous contributors.
654
655
656
657perl v5.28.0                      2016-10-27 docs::api::Apache2::ServerUtil(3)