Webserver(3)

💖 Webserver(3) 💖

okay bestie, so this is Webserver(3) from the User Contributed Perl Documentation section, and it's literally one of my faves because it's so chill. it's the manpage for Pod::Webserver, and no cap, it's a whole vibe. 🦋

---

✨ NAME ✨

Pod::Webserver — a minimal web server that serves up your local Perl documentation. that's it, that's the girl. 💅

---

🌸 SYNOPSIS 🌸

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

boom. run it, point your browser at that URL, done. main character energy fr. 👑

---

🎀 DESCRIPTION 🎀

so this module can be run as an application, and that application works as a minimal web server serving your local Perl documentation. it's like perldoc except the way it works is through your browser. it's giving glow-up. ✨

run podwebserver -h for a list of runtime options. iykyk. 🫶

---

🔥 SECURITY (AND @INC) 🔥

okay so let's be real here. Pod::Webserver is not what you'd call a gaping security hole — like, all it does, and all it 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. she's well-behaved. periodt. 💅

but bestie, 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. that's the part where we go 😭

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" — important!! 🙈) 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. slay, do it your way. 🌈

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.) either one, we support the girlies. 💜

💀 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. iconic of it honestly.

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. so like, the docs stay serving, bestie. 🍓

---

🌟 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/>. obsessed with them fr fr. 🧚

---

📜 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. (translation: she's free, she's hopeful, she promises nothing 💀)

---

👑 AUTHOR 👑

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

Maintained by: Allison Randal allison@perl.org

---

and that's the whole page, bestie!! this one's from perl v5.8.8, dated 2006-12-20 — yeah she's vintage, she's an elder icon, and she still slays. go serve some docs 💖✨🎀