Linux Certif

Toute la documentation sur la certification Linux LPI

Pod::Webserver.3pm

NAME

Pod::Webserver -- minimal web server to serve local Perl documentation

SYNOPSIS

   % podwebserver
   You can now point your browser at http://localhost:8020/
 
 

DESCRIPTION

This module can be run as an application that works as a minimal web server to serve local Perl documentation. It's like perldoc except it works through your browser.

Run podwebserver -h for a list of runtime options.

SECURITY (AND @INC)

Pod::Webserver is not what you'd call a gaping security hole --- after all, all it does and could possibly do is serve HTML versions of anything you could get by typing ``perldoc SomeModuleName''. Pod::Webserver won't serve files at arbitrary paths or anything.

But do consider whether you're revealing anything by basically showing off what versions of modules you've got installed; and also consider whether you could be revealing any proprietary or in-house module documentation.

And also consider that this exposes the documentation of modules (i.e., any Perl files that at all look like modules) in your @INC dirs --- and your @INC probably contains ``.''! If your current working directory could contain modules whose Pod you don't want anyone to see, then you could do two things: The cheap and easy way is to just chdir to an uninteresting directory:

   mkdir ~/.empty; cd ~/.empty; podwebserver
 
 

The more careful approach is to run podwebserver under perl in -T (taint) mode (as explained in perlsec), and to explicitly specify what extra directories you want in @INC, like so:

   perl -T -Isomepath -Imaybesomeotherpath -S podwebserver
 
 

You can also use the -I trick (that's a capital ``igh'', not a lowercase ``ell'') to add dirs to @INC even if you're not using -T. For example:

   perl -I/that/thar/Module-Stuff-0.12/lib -S podwebserver
 
 

An alternate approach is to use your shell's environment-setting commands to alter PERL5LIB or PERLLIB before starting podwebserver.

These -T and -I switches are explained in perlrun. But I'll note in passing that you'll likely need to do this to get your PERLLIB environment variable to be in @INC...

   perl -T -I$PERLLIB -S podwebserver
 
 

(Or replacing that with PERL5LIB, if that's what you use.)

ON INDEXING '.' IN @INC

Pod::Webserver uses the module Pod::Simple::Search to build the index page you see at http://yourservername:8020/ (or whatever port you choose instead of 8020). That module's indexer has one notable DWIM feature: it reads over @INC, except that it skips the ``.'' in @INC. But you can work around this by expressing the current directory in some other way than as just the single literal period --- either as some more roundabout way, like so:

   perl -I./. -S podwebserver
 
 

Or by just expressing the current directory absolutely:

   perl -I`pwd` -S podwebserver
 
 

Note that even when ``.'' isn't indexed, the Pod in files under it are still accessible --- just as if you'd typed ``perldoc whatever'' and got the Pod in ./whatever.pl

SEE ALSO

This module is implemented using many CPAN modules, including: Pod::Simple::HTMLBatch Pod::Simple::HTML Pod::Simple::Search Pod::Simple

See also Pod::Perldoc and <http://search.cpan.org/>

COPYRIGHT AND DISCLAIMERS

Copyright (c) 2004-2006 Sean M. Burke. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

AUTHOR

Original author: Sean M. Burke "sburke@cpan.org"

Maintained by: Allison Randal "allison@perl.org"