.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.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.  \*(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-
.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" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Perlbal::Manual::Install 3pm"
.TH Perlbal::Manual::Install 3pm "2022-06-28" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Perlbal::Manual::Install \- Steps, dependencies and requirements to install Perlbal
.SS "\s-1VERSION\s0"
.IX Subsection "VERSION"
Perlbal 1.78.
.SS "\s-1DESCRIPTION\s0"
.IX Subsection "DESCRIPTION"
How to install Perlbal.
.SS "Installing Perlbal for the impatient"
.IX Subsection "Installing Perlbal for the impatient"
.Vb 1
\&    $ perl \-MCPAN \-e shell
\&
\&    cpan> install Perlbal
.Ve
.PP
App::cpanminus is also good at quickly installing Perlbal and all of its dependencies
.PP
.Vb 1
\&    $ cpanm Perlbal IO::AIO Perlbal::XS::HTTPHeaders
.Ve
.PP
\&... will give you an ideal Perlbal environment.
.SS "Installing Perlbal (with a little more detail)"
.IX Subsection "Installing Perlbal (with a little more detail)"
You need to have perl on the machine. If you don't have it yet, you can grab it from http://www.perl.org/.
.PP
Having perl on the machine should give you access to the \s-1CPAN\s0 shell, one of several possible ways to install and upgrade Perl modules.
.PP
Start your \s-1CPAN\s0 shell:
.PP
.Vb 1
\&    $ perl \-MCPAN \-e shell
.Ve
.PP
And now tell it to install Perlbal:
.PP
.Vb 1
\&    cpan> install Perlbal
.Ve
.PP
In the end you should see a message stating \*(L"make install  \*(-- \s-1OK\*(R"\s0 (if that's not the case, please refer to section Troubleshooting later in this document).
.SS "Installing Perlbal by hand (without using the \s-1CPAN\s0 shell)"
.IX Subsection "Installing Perlbal by hand (without using the CPAN shell)"
Head to <http://search.cpan.org/dist/Perlbal/> and find the download link. Download the file and untar it:
.PP
.Vb 1
\&    $ tar zxvf Perlbal\-X.XX.tar.gz
.Ve
.PP
Note that X.XX stands for the version number. Replace that with the latest version you got.
.PP
Now you need to create the Makefile and run it; we're also going to run the tests before installing Perlbal:
.PP
.Vb 1
\&    $ cd Perlbal\-X.XX.tar.gz
\&
\&    $ perl Makefile.PL
\&
\&    $ make
\&
\&    $ make test
\&
\&    $ sudo make install
.Ve
.SS "Installing the latest development version"
.IX Subsection "Installing the latest development version"
You can clone Perlbal's repository from github and install it by hand by following the next steps:
.PP
.Vb 1
\&    $ git clone http://github.com/perlbal/Perlbal.git
\&
\&    $ cd Perlbal
\&
\&    $ perl Makefile.PL
\&
\&    $ make
\&
\&    $ make test
\&
\&    $ sudo make install
.Ve
.SS "Optional Dependencies and Asynchronous \s-1IO\s0"
.IX Subsection "Optional Dependencies and Asynchronous IO"
It is very highly recommended that Perlbal::XS::HTTPHeaders is installed and enabled. If you have poor performance, the first thing to do is install Perlbal::XS::HTTPHeaders.
.PP
.Vb 1
\&    $ perl \-MCPAN \-e shell
\&
\&    cpan> install Perlbal::XS::HTTPHeaders
.Ve
.PP
Enable it in your configuration:
.PP
.Vb 1
\&    XS enable headers
.Ve
.PP
Perlbal checks for \s-1IO::AIO\s0 availability and uses it to perform asynchronous \s-1IO\s0 operations. If you're performing disk operations (e.g., using Perlbal as a web server), having \s-1IO::AIO\s0 will improve your response times.
.PP
The only thing required in order to benefit from this feature is to install \s-1IO::AIO\s0:
.PP
.Vb 1
\&    $ perl \-MCPAN \-e shell
\&
\&    cpan> install IO::AIO
.Ve
.PP
If you don't have \s-1IO::AIO\s0 installed a warning message will be displayed when you start perlbal:
.PP
.Vb 4
\&    WARNING:  AIO mode disabled or not available.
\&              Perlbal will run slowly under load if you\*(Aqre doing any
\&              disk operations. (e.g. web_server mode).
\&              Install IO::AIO for better performance.
.Ve
.SS "Checking that Perlbal is successfully installed"
.IX Subsection "Checking that Perlbal is successfully installed"
Perlbal is shipped with some sample configuration files that reside in the \fIconf\fR directory (of the source).
.PP
You can give Perlbal a try by heading to the directory where the source is and using the following command:
.PP
.Vb 1
\&    $ sudo perlbal \-c conf/webserver.conf
.Ve
.PP
By pointing your browser at \f(CW\*(C`localhost:80\*(C'\fR you should now see Perlbal responding (showing you the contents of \f(CW\*(C`/usr/share/doc\*(C'\fR).
.PP
Note that the \fIwebserver.conf\fR file sets up a Perlbal web server that listens on port 80. If you already have something listening on port 80 you need to either stop that service or change the port number on \fIwebserver.conf\fR.
.PP
Also note that if your machine doesn't have a \f(CW\*(C`/usr/share/docs\*(C'\fR directory you'll see an \f(CW\*(C`ERROR: Directory not found for service docs\*(C'\fR error message. Change the directory in the configuration file to something that exists.
.SS "Troubleshooting"
.IX Subsection "Troubleshooting"
\fIPrerequisites not found\fR
.IX Subsection "Prerequisites not found"
.PP
If you're installing Perlbal by hand you may encounter some error messages describing how some prerequisites are not available:
.PP
.Vb 9
\&    user@machine:~/Perlbal\-X.XX$ perl Makefile.PL
\&    Checking if your kit is complete...
\&    Looks good
\&    Warning: prerequisite BSD::Resource 0 not found.
\&    Warning: prerequisite Danga::Socket 1.44 not found.
\&    Warning: prerequisite HTTP::Date 0 not found.
\&    Warning: prerequisite HTTP::Response 0 not found.
\&    Warning: prerequisite Sys::Syscall 0 not found.
\&    Writing Makefile for Perlbal
.Ve
.PP
This is perl's way of telling you that since you're installing Perlbal by hand you'll also need to install its prerequisites by hand. Your first choice is to download each of them separately and perform the same installation procedure for each. Unfortunately, they are all likely to have additional prerequisites. Recursively.
.PP
Alternately, see the following Troubleshooting item: \f(CW\*(C`No connection to the internet\*(C'\fR.
.PP
\fINo connection to the internet\fR
.IX Subsection "No connection to the internet"
.PP
If you don't have a connection to the internet you can still install Perlbal, but you'll have to tranfer the source somehow to the machine.
.PP
Given that Perlbal has other module dependencies from \s-1CPAN\s0 (and those have their own dependencies too), here's a solution for this problem:
.PP
Step 1: On a machine with connection to the internet, install CPAN::Mini:
.PP
.Vb 1
\&    $ perl \-MCPAN \-e shell
\&
\&    cpan> install CPAN::Mini
.Ve
.PP
Run \f(CW\*(C`minicpan\*(C'\fR to create a minimal \s-1CPAN\s0 mirror (it contains only the latest version of each module):
.PP
.Vb 1
\&    $ minicpan \-l /home/user/minicpan/ \-r http://cpan.org/
.Ve
.PP
Now grab that directory and record it to something you can read on the other machine (e.g., a \s-1DVD,\s0 a hard drive).
.PP
Once you're on that machine, you can run the \s-1CPAN\s0 shell and tell it to look for distributions on the local directory where you now have your own \s-1CPAN\s0 mirror:
.PP
.Vb 1
\&    $ perl \-MCPAN \-e shell
\&
\&    cpan> o conf urllist push file:///home/user/path/to/minicpan
\&
\&    cpan> install Perlbal
.Ve
.PP
If you want \f(CW\*(C`cpan\*(C'\fR to record this change don't forget to commit:
.PP
.Vb 1
\&    cpan> o conf commit
.Ve
.PP
\fINo compiler available\fR
.IX Subsection "No compiler available"
.PP
If there's no compiler available on the machine you will probably see an error ending in something like:
.PP
.Vb 2
\&    Failed during this command:
\&     DORMANDO/Perlbal\-X.XX.tar.gz : writemakefile NO \*(Aq/usr/bin/perl Makefile.PL INSTALLDIRS=site\*(Aq returned status \-1
.Ve
.PP
You need to install something like \f(CW\*(C`gcc\*(C'\fR (check <http://gcc.gnu.org/>).
.PP
After installing \f(CW\*(C`gcc\*(C'\fR, when trying to install Perlbal again you may get another error message:
.PP
.Vb 9
\&    cpan> install Perlbal
\&    Running install for module \*(AqPerlbal\*(Aq
\&    Running make for D/DO/DORMANDO/Perlbal\-X.XX.tar.gz
\&      Has already been unwrapped into directory /home/myself/.cpan/build/Perlbal\-X.XX\-GFko0J
\&      \*(Aq/usr/bin/perl Makefile.PL INSTALLDIRS=site\*(Aq returned status \-1, won\*(Aqt make
\&    Running make test
\&      Make had some problems, won\*(Aqt test
\&    Running make install
\&      Make had some problems, won\*(Aqt install
.Ve
.PP
This is the cpan shell assuming nothing changed in the system and skipping a few steps. You need to let it know you're willing to forget the past:
.PP
.Vb 1
\&    cpan> look Perlbal
\&
\&    $ rm \-rf *
\&
\&    $ exit
.Ve
.PP
And now you can try installation again:
.PP
.Vb 1
\&    cpan> install Perlbal
.Ve
.SS "\s-1SEE ALSO\s0"
.IX Subsection "SEE ALSO"
Perlbal::Manual.