File: //usr/local/share/man/man3/HTTP::Daemon::App.3
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. | will give a
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.\"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "HTTP::Daemon::App 3"
.TH HTTP::Daemon::App 3 "2006-11-17" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
HTTP::Daemon::App \- Create 2 or 3 line, fully functional (SSL) HTTP server(s)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& use HTTP::Daemon::App;
\& use MyServers::Foo;
\& HTTP::Daemon::App::run($MyServers::Foo::daemons, $MyServers::Foo::config);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
You can describe one or more \s-1HTTP\s0 daemons in a simple hash and *instantly*
have a [\-\-start|\-\-stop|\-\-restart] capable daemon that can optionally be \s-1SSL\s0 aware.
.PP
Its also easy to add command line options and has integrated help.
.Sh "\s-1EXPORT\s0"
.IX Subsection "EXPORT"
Each function can be exported but nothing is by default.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.Sh "run"
.IX Subsection "run"
Takes 2 arguments, both hashrefs. The first describes tha daemons to run, the second is for config.
.PP
\fIdaemon hashref\fR
.IX Subsection "daemon hashref"
.PP
Hopefully these are self descriptive, this example does two daemons \s-1SSL\s0 and non\-SSL:
.PP
.Vb 26
\& {
\& 'thingy-ssl' => {
\& 'label' => 'HTTPS Thingy',
\& 'ssl' => 1, # true: HTTP::Daemon::SSL, false: HTTP::Daemon
\& 'daemon' => {
\& # arguments HTTP::Daemon[::SSL]->new()
\& 'LocalPort' => 4279,
\& },
\& 'handler' => sub {
\& my($d, $c, $r, $conf_hr) = @_; # $d, $c, $r from HTTP::Daemon
\& # handle request
\& },
\& },
\& 'thingy' => {
\& 'label' => 'HTTP Thingy',
\& 'ssl' => 0, # true: HTTP::Daemon::SSL, false: HTTP::Daemon
\& 'daemon' => {
\& # arguments HTTP::Daemon[::SSL]->new()
\& 'LocalPort' => 4278,
\& },
\& 'handler' => sub {
\& my($d, $c, $r, $conf_hr) = @_; # $d, $c, $r from HTTP::Daemon
\& # handle request
\& },
\& },
\& },
.Ve
.PP
\fIconfig hashref\fR
.IX Subsection "config hashref"
.PP
.Vb 15
\& {
\& 'pre_fork' => '', # set to a code ref it gets called before it forks the child process, its args are ($handler, $d, $name, $pidfile, $conf)
\& 'pst_fork' => '', # same as pre_fork but run after the fork is done
\& 'pid_dir' => '/var/run/', # default shown
\& 'pid_ext' => '.pid', # default shown
\& 'verbose' => 0, # example of your custom option that can be used by your handlers and set via 'opts' like below
\& # 'lang' => 'Locale::Maketext::Utils handle', not used yet
\& 'help' => '', # default shown, this is added to the useage output.
\& 'opts' => {
\& # default {}, cannot use --stop, --start, or --restart, automagically added to useage line
\& '--version' => sub { print "$0 v1.0\en" },
\& '--verbose' => sub { my($daemons_hashref, $conf) = @_;$conf->{'verbose'} = 1; },
\& },
\& 'self' => "perl $0", # default shown, command used to call --stop & --start on --restart
\& }
.Ve
.Sh "decode_basic_auth"
.IX Subsection "decode_basic_auth"
Given the encoded basic auth passed by the browser
(or given the \*(L"$r\*(R" object from HTTP::Daemon, the 'Authorization' header's value)
this will return the username an password.
.PP
.Vb 2
\& my ($auth_user, $auth_pass) = decode_basic_auth( $encoded_basic_auth_from_browser );
\& my($user, $encpass, $uid, $gid, $homedir) = (getpwnam($auth_user))[0, 1, 2, 3, 7];
.Ve
.PP
.Vb 2
\& if($auth_user && $encpass eq crypt($auth_pass, $encpass) && $user eq $auth_user) {
\& ... # continue on as authenticated user
.Ve
.Sh "send_basic_auth_request"
.IX Subsection "send_basic_auth_request"
Takes two arguments: the \*(L"$c\*(R" object from HTTP::Request, the realm's name (has lame default if not specified)
.PP
It does a 401 that incites the client's authentication challenge (E.g. a browser's drop down login box)
.PP
.Vb 5
\& ... # continue on as authenticated user
\& }
\& else {
\& HTTP::Daemon::App::send_basic_auth_request($c, 'Vault of secrets');
\& }
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
HTTP::Daemon
.SH "AUTHOR"
.IX Header "AUTHOR"
Daniel Muey, <http://drmuey.com/cpan_contact.pl>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2006 by Daniel Muey
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.6 or,
at your option, any later version of Perl 5 you may have available.