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"