Gentoo Apache + PHP4 + PEAR Install and Tweak Guide

Contents

Introduction
Choose Your Setup
Installing Apache
PHP Configuration Options
Installing PHP4
Installing PEAR

Introduction

I had a previous guide on how to setup Apache 1.3.x + PHP4 + mod_ssl
from source files, but I found a few bugs in it, and it didn't use any
of the packages in Portage.  I decided to rewrite it using (modified)
Gentoo ebuilds to make things easier.

Choose your setup

The first thing to do is decide: do you want Apache 1.3.x or 2.x?
There are advantages and disadvantages to both, and I'm not going to
go into them.  For some, it's simply a matter of personal preference.
I've been having trouble of late getting Apache 1.3.31 and PHP 4.3.7
to work together, but with all my tweaks, that comes as no surprise.
For this installation, I'm going to start with Apache 2.

Also, this doesn't cover how to install/setup/use PHP5 (yet).  This guide
uses PHP 4.3.6 which is the latest stable ebuild of PHP4 in portage.

Note: Don't use any version of PHP < 4.3.6 for all the recent bugfixes
it has.

Install Apache 1 or 2

The first step is to install (emerge) apache.

The USE flags are a bit tricky when it comes to setting which version of
Apache to use.  As of this version of Portage that I'm using (2.0.50-r8),
emerging apache can be a little flakey because it ALWAYS defaults to
installing Apache 2.  This can be made even more confusing since possible
USE flags include apache1 and apache2.  Even with apache1 set, running
"emerge apache" will still emerge Apache 2.  It can be a bit confusing. :)

To work around this is to tell portage specifically which apache ebuild
to emerge.

If you want to install Apache 1.3.31, run this:

emerge =net-www/apache-1.3.31[-r(x)]

The = before net-www tells it to install that exact version.  I use []
to indicate a possible new ebuild version for that package, and x is the
ebuild number (you wouldn't actually type in the brackets or parentheses
on the command line).  In this case, if you wanted to install the r1
ebuild of apache 1.3.31, this would be the code:

emerge =net-www/apache-1.3.31-r1

Note: Another trick I like to use to install apache1 (and instead of
doing =net-www/etc..) is just to run this:

emerge mod_gzip

which will automatically include apache1 as a dependency.  Plus you get
mod_gzip installed too. :D

Note: Even though there is no "ssl" USE flag for apache1, it will install
mod_ssl by default (I think -- I know it downloads it.  Don't ask me
why mod_ssl is a separate package).

Installing Apache 2 is much simpler:

emerge apache

If you want to use SSL with apache2 (so you can run https://), have your
use flags set to include "ssl" or just run this:

USE="ssl" emerge apache

Once apache is installed, we don't need to make any changes to it -- YET.
In fact, go ahead and run:

# rc-update add apache default

to have it start on bootup.  If you installed apache2, the code is:

# rc-update add apache2 default

If you want to start it now, run:

# /etc/init.d/apache(2) start

and you can browse to http://localhost/ just to make sure it's working.

When you start apache, you'll see this warning:
 * Starting apache2...
apache2: Could not determine the server's fully qualified domain name,
using 127.0.0.1 for ServerName

Don't worry about it for now -- we'll fix it later.  Everything will
run fine even if you don't fix it.

Final notes:
This is optional, but something I do on every install to make things a
little simpler, since I tweak my apache settings all the time -- make a
softlink to the main apache config in your /etc directory so it's easier
to find/edit.

# ln -s /etc/apache2/conf/apache2.conf /etc/httpd2.conf

I know it's possible to have both instances of Apache installed (1 and
2), but I'm not sure about the feasibility of having mod_php work for
both of them.

Apache /etc/conf.d/ settings:

By default, Apache's restart style is graceful (see
http://httpd.apache.org/docs-2.0/stopping.html#graceful ), which is
perfect for production environments.  If for some reason you don't
want that though, edit /etc/init.d/apache(2) with your favorite editor,
and change the RESTARTSTYLE variable.

PHP Configuration Options

Note: This section will grow as I do more research.  Right now it covers
the areas I use regularly, and that's about it.

Note: See PHP's Miscellaneous configuration options --
http://www.php.net/manual/en/install.configure.php

Note: By default, mod_php comes with these notable options ENABLED:

bz2
calendar
ftp
pcre
session
zlib

See phpinfo() for complete current default configuration settings in
mod_php or run "$ php -i | less" for the php cli ebuild.

Note: Since mod_php and php are separate ebuilds (mod_php for apache,
and php for CLI), any configuration options you want to change will have
to be done separately to each ebuild.

Here's some common PHP configuration options you may want to use, and
how to enable them:

MySQL [USE flag] - Database
Docs: http://www.php.net/manual/en/ref.mysql.php
Set your use flag to include "mysql"

PostgreSQL [USE flag] - Database
Docs: http://www.php.net/manual/en/ref.pgsql.php
Set your use flag to include "postgres"

mhash [USE flag] - Hashing
"Mhash can be used to create checksums, message digests, message
authentication codes, and more."
Docs: http://www.php.net/manual/en/ref.mhash.php
Set your use flag to include "crypt"

mcrypt [USE flag] - Encryption
" This is an interface to the mcrypt library, which supports a wide
variety of block algorithms such as DES, TripleDES, Blowfish (default),
3-WAY, SAFER-SK64, SAFER-SK128, TWOFISH, TEA, RC2 and GOST in CBC, OFB,
CFB and ECB cipher modes. Additionally, it supports RC6 and IDEA which
are considered "non-free"."
Docs: http://www.php.net/manual/en/ref.mcrypt.php
Set your use flag to include "crypt"

crack [USE flag] - Password testing
"These functions allow you to use the CrackLib library to test the
'strength' of a password. The 'strength' of a password is tested by
that checks length, use of upper and lower case and checked against the
specified CrackLib dictionary. CrackLib will also give helpful diagnostic
messages that will help 'strengthen' the password."
Docs: http://www.php.net/manual/en/ref.crack.php
Set your use flag to include "crypt" (not verified -- it may be default)
Note: for PHP5 it's in PECL now - http://pecl.php.net/package/crack


Tweaking and emerging the php ebuilds


This is the fun part, where you get to tweak the PHP4 ebuilds to pass
your own configuration options.

Note: There is probably an easier way to do this, since your changes
will be wiped out with a new ebuild, but I don't know how to do it --
if someone does, please let me know. :)

First of all, create, if you haven't already, a PORTDIR_OVERLAY directory.
The overlay directory basically says: use the ebuilds in this location
instead of the ones in Portage.  To set it up do this:

Edit /etc/make.conf with your favorite editor
Uncomment the PORTDIR_OVERLAY variable, and set it to something.  (I can't
remember what the default is, but I changed mine to /etc/portage since
I always backup my /etc/ directory).

Once you have the overlay setup, copy over the old ebuilds:

# cd /etc/portage
# mkdir dev-php
# mkdir dev-php/mod_php
# mkdir dev-php/php
# cp /usr/portage/dev-php/mod-php/* -Rv /etc/portage/dev-php/mod_php
# cp /usr/portage/dev-php/php/* -Rv /etc/portage/dev-php/php

Now that they are copied over, you can start to tweak them a bit.
Change directories to the ebuild, and edit it.  In my case, php-4.3.6
is the latest (stable) php package, with a 3rd ebuild:

# cd /etc/portage/dev-php/mod_php
# vim|nano|whatever mod_php-4.3.6-r2.ebuild

The variable you are looking to tweak (in both the mod_php and php
ebuilds) is $myconf.

Look for this line in the ebuild: php-sapi_src_compile

Insert _above that line_ any configuration options that you know you want
(and that will work) when compiling PHP4.  Note: See the next section
for PHP configuration options/USE flags and their descriptions.

Here's an example though -- I _added_ this line to enable zip support:

myconf="${myconf} --with-zip"

Note: For those of you who are bash noobs like me, what that line does is
says: set the myconf variable to the existing myconf variable ( ${myconf}
) and append "--with-zip".

If you know what other weird configuration options you want to pass in
there, go ahead and include those as well.  Fortunately, the USE flags
cover the major areas, and PEAR covers a few more, so as a general rule,
you probably won't have to hack the ebuild.

Once you have your $myconf variable correctly setup, you can emerge
the ebuild.  Do it manually by running emerge and pointing directly to
that ebuild.  In this case, the code would be this:

# emerge /etc/portage/dev-php/mod_php/php-4.3.6-r2.ebuild

One thing to note before emerging the actual mod_php ebuild is to know
WHICH version of Apache you are installing it for.  If you haven't
already installed apache, do it now, since it will default to Apache2
if you don't make a choice.

If you have BOTH Apache1 and 2 installed and want mod_php installed for
Apache1, then run this:

For apache1
# USE="apache1 -apache2" emerge
/etc/portage/dev-php/mod_php/php-4.3.6-r2.ebuild

For apache2, just emerge the ebuild.  It will default to Apache2, no
matter what your USE flags are (again, don't ask me why).