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         $banner = Apache2::ServerUtil::get_server_banner();
32
33         # ServerRoot value
34         $server_root = Apache2::ServerUtil::server_root();
35
36         # get 'conf/' dir path (avoid using this function!)
37         my $dir = Apache2::ServerUtil::server_root_relative($r->pool, 'conf');
38
39         # set child_exit handlers
40         $r->set_handlers(PerlChildExitHandler => \&handler);
41
42         # server level PerlOptions flags lookup
43         $s->push_handlers(ChildExit => \&child_exit)
44             if $s->is_perl_option_enabled('ChildExit');
45
46         # extend HTTP to support a new method
47         $s->method_register('NEWGET');
48
49         # register server shutdown callback
50         Apache2::ServerUtil::server_shutdown_register_cleanup(sub { Apache2::Const::OK });
51
52         # do something only when the server restarts
53         my $cnt = Apache2::ServerUtil::restart_count();
54         do_something_once() if $cnt > 1;
55
56         # get the resolved ids from Group and User entries
57         my $user_id  = Apache2::ServerUtil->user_id;
58         my $group_id = Apache2::ServerUtil->group_id;
59

Description

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

Methods API

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

Unsupported API

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

Copyright

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

Authors

654       The mod_perl development team and numerous contributors.
655
656
657
658perl v5.38.0                      2023-07-20 docs::api::Apache2::ServerUtil(3)