Apache 2.0 on AIX

Warning! This document hasn't been maintained in a long time!

Related documents

A sister document is Status of Apache 2.0 on AIX. You must be familiar with the information there to make good use of Apache 2.0 on AIX. Also, check out some common build problems in another doc.

Introduction and disclaimers

This is not part of the Apache 2.0 documentation. This is not a statement of Apache Software Foundation or Apache HTTP Server Project or even anybody really important.

Support

Who is closely tracking Apache 2.0 on AIX and can try to help you?

not me, anymore

Please use the httpd user's mailing list for help with Apache 2.0 on AIX.

Bug reports

Go to http://issues.apache.org/bugzilla/ and enter a bug report. Make sure to provide appropriate detail. Don't expect a response immediately. It is useful information to people who follow the reports, even if none of the handful of such people are able to do anything about it right away.

Mailing lists

If you suspect a problem or want to discuss a design issue with Apache 2.0 and you want more interaction than entering a bug report, feel free to subscribe to dev@httpd.apache.org by sending a blank message to dev-subscribe@httpd.apache.org, then post your question there. Please note that this is not a support forum for admin questions. (User (admin) mailing lists are listead at http://httpd.apache.org/lists.html#http-users.)

If you have a patch to resolve the problem in your e-mail, that is great.

Note that issues with code in srclib/apr and srclib/apr-util are discussed at dev@apr.apache.org. You can subscribe to that list by sending a blank message to dev-subscribe@apr.apache.org.

Information about all Apache Software Foundation mailing lists can be found at http://www.apache.org/foundation/mailinglists.html. There are pointers from that page to archives for many of the lists.

Minimal prereqs

Note: some standard Apache modules have additional prereqs and are covered later in this document.

  1. AIX programming-related filesets 
    bos.adt.base
bos.adt.include
bos.adt.lib
bos.adt.libm
    Run lslpp -L fileset to see if you have the fileset installed.

  2. compiler: gcc or xlc_r (all examples here use xlc_r; we like to keep it compiling cleanly with gcc -Wall because the warnings are usually spot-on, though I normally test with an xlc_r build)

    Word to the wise: Any information in the sister document describing breakage overrides any general principles described here.

  3. apache source: It is best to always use the latest official release from http://www.apache.org/dist/httpd/ so that if you encounter problems somebody can actually help.

Building and configuring...

Note: Prior to Apache 2.0.45, the libtool distributed with the Apache source distribution did not work on AIX, and you needed to build your own libtool. If you're using an older level of Apache, or if you want to use a specific version of libtool, or you're modifying the Apache configure scripts, please see Running buildconf.

Goal for the configuration

Build Apache with the standard modules, including mod_so so that you can load your own modules into the server. Use the worker MPM because that is the strategic multi-process, multi-threaded MPM for Unix-like systems, and it works fine on AIX.

Details of the build

Unpack the sources then cd into the root source directory.
buildconf

You probably do not need to do this (see Running buildconf). But if you do, it is as simple as

$ ./buildconf
configure
$ CC=xlc_r ./configure \
--with-mpm=worker --enable-so --enable-layout=Apache \
--enable-mods-shared=most --enable-maintainer-mode   \
--with-expat=`pwd`/srclib/apr-util/xml/expat         \
--enable-static-support

If you want to use gcc instead of IBM's C for AIX, use CC=gcc instead of CC=xlc_r

If you want to build 64-bit Apache using the IBM tools, set OBJECT_MODE=64. (I don't know what to do with gcc. I suspect you need to set OBJECT_MODE and add -m64 to FLAGS.)

If you want to be able to debug your Apache build, add --enable-maintainer-mode to the configure options listed above.

If you want to install it somewhere besides /usr/local/apache2, then add --prefix=/my/favorite/directory to the configure options listed above.

Note to the curious: Explicitly specifying --enable-so works around a bug in 2.0.45. It doesn't hurt to specify it for other releases.

This first step, configure, will take a while while it detects what capabilities are available on your system. With recent levels of Apache, it can take seemingly forever to run. A huge amount of time can be saved by avoiding the checks for a number of different versions of the Berkeley DB libraries. If you don't need to use Berkeley DB libraries, skip this portion of configure processing by adding --without-berkeley-db to the configure invocation. If Berkeley DB is pre-installed on your system and the Apache configure script finds it, then user and group databases maintained by dbmmanage and htdbm can use the Berkeley DB format instead of the default SDBM (Perl-compatible) format.

make

After the configure step is done, run make. 

$ make

Please note: There is some non-standard naming of libraries, and IBM's native C compiler for AIX will display a plethora of warnings at the end of the build because of those names. Ignore them. They look like this:

xlc_r: 1501-218 file modules/aaa/.libs/mod_access.al contains an incorrect file suffix
xlc_r: 1501-218 file modules/aaa/.libs/mod_auth.al contains an incorrect file suffix
xlc_r: 1501-218 file modules/filters/.libs/mod_include.al contains an incorrect file suffix
xlc_r: 1501-218 file modules/loggers/.libs/mod_log_config.al contains an incorrect file suffix
xlc_r: 1501-218 file modules/metadata/.libs/mod_env.al contains an incorrect file suffix
xlc_r: 1501-218 file modules/metadata/.libs/mod_headers.al contains an incorrect file suffix
xlc_r: 1501-218 file modules/metadata/.libs/mod_setenvif.al contains an incorrect file suffix
xlc_r: 1501-218 file modules/http/.libs/mod_http.al contains an incorrect file suffix
xlc_r: 1501-218 file modules/http/.libs/mod_mime.al contains an incorrect file suffix
xlc_r: 1501-218 file modules/generators/.libs/mod_status.al contains an incorrect file suffix
xlc_r: 1501-218 file modules/generators/.libs/mod_autoindex.al contains an incorrect file suffix
xlc_r: 1501-218 file modules/generators/.libs/mod_asis.al contains an incorrect file suffix
xlc_r: 1501-218 file modules/generators/.libs/mod_info.al contains an incorrect file suffix
xlc_r: 1501-218 file modules/generators/.libs/mod_cgid.al contains an incorrect file suffix
xlc_r: 1501-218 file modules/mappers/.libs/mod_negotiation.al contains an incorrect file suffix
xlc_r: 1501-218 file modules/mappers/.libs/mod_dir.al contains an incorrect file suffix
xlc_r: 1501-218 file modules/mappers/.libs/mod_imap.al contains an incorrect file suffix
xlc_r: 1501-218 file modules/mappers/.libs/mod_actions.al contains an incorrect file suffix
xlc_r: 1501-218 file modules/mappers/.libs/mod_userdir.al contains an incorrect file suffix
xlc_r: 1501-218 file modules/mappers/.libs/mod_alias.al contains an incorrect file suffix
xlc_r: 1501-218 file modules/mappers/.libs/mod_rewrite.al contains an incorrect file suffix
xlc_r: 1501-218 file modules/mappers/.libs/mod_so.al contains an incorrect file suffix
xlc_r: 1501-218 file server/mpm/worker/.libs/libworker.al contains an incorrect file suffix
xlc_r: 1501-218 file server/.libs/libmain.al contains an incorrect file suffix
xlc_r: 1501-218 file os/unix/.libs/libos.al contains an incorrect file suffix
xlc_r: 1501-218 file /build/httpd/httpd-2.0.44/srclib/pcre/.libs/libpcre.al contains an incorrect file suffix

If you see warnings like this specifying _Errno as the missing prototype, please ignore these. It is due to a problem in a system header file. The problem is fixed as of AIX 5, and it has no negative side effects on older releases of AIX.

 1506-304 (I) No function prototype given for "_Errno"

make install

You may need to perform make install as root, depending on where it is installed (specified via --prefix parameter passed to configure).

# make install

If you get an install failure like the following, run slibclean as root and then run make install again. If you aren't able to run slibclean as root, the alternative is to delete all the files in Apache's lib directory then run make install again.

cp .libs/libapr-0.so.0.9.5 /home/trawick/2048gcc/lib/libapr-0.so.0.9.5
cp: /home/trawick/2048gcc/lib/libapr-0.so.0.9.5: Text file busy
make: 1254-004 The error code from the last command is 1.


Stop.
make: 1254-004 The error code from the last command is 1.


Stop.
make: 1254-004 The error code from the last command is 1.


Stop.

Verifying that modules can load

Run apachectl configtest to make sure all the Apache modules can load.

If you built with gcc and you get an error similar to the following, see item B14 in this document for a solution.

Cannot load /home/trawick/apacheinst/modules/mod_actions.so into
server:        0509-130 Symbol resolution failed for
/home/trawick/apacheinst/modules/mod_actions.so because:
        0509-136   Symbol __ashldi3 (number 15) is not exported from
                   dependent module lt-httpd.
        0509-192 Examine .loader section symbols with the
                 'dump -Tv' command.

Tuning the configuration file

Some changes may be necessary in /usr/local/apache2/conf/httpd.conf.
fixing User and Group

If you intend for Apache to listen on a low port (e.g., 80) or you need to start Apache as root for some other reason, you'll need to fix the User and Group directives.

Find this section:

User nobody
Group #-1

This won't work on AIX. On most systems, you can use nobody for both user and group, as shown below:

User nobody
Group nobody

If you neglect to do this, you'll see a confusing error message like the following in error_log:

(22)Invalid argument: setgid: unable to set group id to Group 4294967295
single-child-process server

If you want to have a single-process/multi-threaded server, find this section:

<IfModule worker.c>
StartServers         2
MaxClients         150
MinSpareThreads     25
MaxSpareThreads     75
ThreadsPerChild     25
MaxRequestsPerChild  0
</IfModule>

Add the following directives to the start of the worker.c container:

ServerLimit 1
ThreadLimit 1024

and change StartServers to 1, MaxClients to 1024, MinSpareThreads to 1, MaxSpareThreads to 1024, and ThreadsPerChild to 1024.

mod_status

If you want to enable mod_status, find this section:

#<Location /server-status>
#    SetHandler server-status
#    Order deny,allow
#    Deny from all
#    Allow from .your_domain.com
#</Location>
and uncomment all but the Order, Deny, and Allow lines. Also, find #ExtendedStatus On and uncomment that too.

Important: See the documentation for mod_access for what to do with the Order, Deny, and Allow lines in case you want to restrict who can see your server-status page.

Running buildconf

You need to run buildconf if one of the following conditions is true:

  • you're using an older Apache 2 distribution, such as 2.0.42, that has an included libtool older than 1.4.2
  • you need to make modifications to the Apache configure script
    •

    Most users of Apache 2 on AIX do not need to run buildconf and don't need the prerequisites listed in this section.

  • GNU libtool, autoconf, and m4

    Warning: The version of libtool which is available from the AIX toolbox is not compatible with Apache 2.0 because a later version of libtool is needed. Installing the toolbox version of libtool will create symbolic links for aclocal and libtool in /bin which may cause the libtool installed in /usr/local/bin to be ignored. I do not know whether or not toolbox versions of m4 and autoconf can be used in place of the packages mentioned below. If you have such information, please let me know.

    Download the following packages: m4, autoconf, libtool

    Explode the packages: 
    gzip -dc autoconf-2.13.tar.gz          | tar -xvf-
gzip -dc m4-1.4.tar.gz                 | tar -xvf-
gzip -dc libtool-1.4.2.tar.gz          | tar -xvf-
    If you don't have makeinfo on your system, the build of m4 will fail. This is an easy work-around: 
    ln -s /usr/bin/true mydir/makeinfo
    where mydir is some directory in your PATH. You can erase the symbolic link mydir/makeinfo after building these tools.

    Build them in this order. If using gcc, omit the "CC=xlc_r" on several of the commands. 

    cd m4-1.4
CC=xlc_r ./configure
make
make install

cd ../autoconf-2.13
CC=xlc_r ./configure
make
make install

cd ../libtool-1.4.2
CC=xlc_r CFLAGS=-bexpall ./configure
make
make install
    The reason CFLAGS=-bexpall is needed in libtool is so that dlopen(self,....) will work correctly on AIX.

    gcc note:Use -Wl,-bexpall instead of simply -bexpall with gcc. gcc doesn't understand -bexpall, but prefixing it with -Wl tells gcc to pass it on to the loader.

    Other build notes

    Running it

    Start it just like 1.3 except for the directory. Put /usr/local/apache2/bin in your PATH and use apachectl start.

    Note: Prior to 20011217 you would need to set the LDR_CNTRL environment variable. That is no longer needed.

    If you're running a single-child-process server, you'll see 3 httpd processes after Apache starts: 

    25680 26372        *    00:00:00  trawick httpd    /home/trawick/2.0.28/bin/httpd
26372     1        -    00:00:00  trawick httpd    /home/trawick/2.0.28/bin/httpd
29778 26372    EVENT    00:00:00  trawick httpd    /home/trawick/2.0.28/bin/httpd
    The one with parent pid 1 is the parent (just like 1.3). The one in EVENT state is the process full of worker threads. The remaining process is mod_cgid.

    Information on upgrading from Apache 1.3 can be found at http://httpd.apache.org/docs-2.0/upgrading.html .

    Enabling some interesting additional modules

    mod_ssl

    random number availability
    mod_ssl needs a source of random numbers. AIX prior to 5.2 doesn't have a kernel entropy source (/dev/*random). The solution for these older levels of AIX is to install prngd from the AIX toolbox and then add the following to your mod_ssl configuration section: 
    <IfModule mod_ssl>
SSLRandomSeed startup egd:/dev/egd-pool
SSLRandomSeed connect egd:/dev/egd-pool
other stuff
</IfModule<
    silly doc problem: the mod_auth_digest hints below tell you to use a different random number source :)
    static vs. dynamic
    Make sure that your OpenSSL build matches your mod_ssl build with respect to static vs. dynamic linking.

    If OpenSSL is built for dynamic linking but you wish to link mod_ssl directly into Apache (--enable-ssl=static), you can get link-edit errors like this: 

    ld: 0711-317 ERROR: Undefined symbol: .sk_new_null
ld: 0711-317 ERROR: Undefined symbol: .X509_STORE_CTX_set_verify_cb
ld: 0711-317 ERROR: Undefined symbol: .BIO_snprintf
ld: 0711-345 Use the -bloadmap or -bnoquiet option to obtain more
information.
    To make this work, do a special build of OpenSSL like this: 
    ./config threads no-shared no-dso no-asm
    Then point Apache to that OpenSSL build like this: 
    ./configure --enable-ssl=static --with-ssl=/path-to-openssl_dir --other-opts

    mod_auth_digest

    mod_auth_digest requires APR random number support, but APR doesn't automatically have that on AIX prior to AIX 5.2 due to the lack of support in the kernel. The fix for older levels of AIX is to install egd (Entropy Gathering Daemon) and add the "--with-egd[[=]]" parameter to configure. Then, --enable-auth-digest will work. Note: egd has to be running when you start Apache.

    mod_deflate

    You need to install the zlib compression library if you want to use mod_deflate

    Don't get it from the AIX Toolbox download page. The RPM there doesn't include header files. Instead, grab the lastest zlib tarball from the home of zlib, www.zlib.org.

    Build a static library. It is small; there is no reason to complicate matters. 

    CC=xlc_r CFLAGS="-O -qmaxmem=8192" ./configure
make
    I recommend NOT doing make install. The first time I did this, I broke an old installation of cvs because I overwrote the version of zlib that cvs expected to use.

    Another reason to segregate out of the standard install location (/usr/local/lib, /usr/local/include): there may be files in /usr/local/include which you do not want to consider for the Apache compilation.

    consider doing something like this after running make: 

    mkdir /home/george/zlib-for-apache
mkdir /home/george/zlib-for-apache/lib
mkdir /home/george/zlib-for-apache/include
cp -p zlib.h zconf.h zutil.h /home/george/zlib-for-apache/include
cp -p libz.a /home/george/zlib-for-apache/lib
    To enable mod_deflate, add these options to your existing configure options later: 
    --enable-deflate --with-z=/home/george/zlib-for-apache

    special operational considerations on AIX

    slow startup

    This can be due to DNS calls at initialization. To confirm this, try starting Apache like this:

    NSORDER=local bin/apachectl start

    If that resolves the slow startup, then the problem was caused by a DNS lookup.

    problems unmounting filesystems containing web site files (affects HACMP environments)

    Apache 2.0 on AIX normally serves files using the send_file() API. This results in the files being stored in the AIX Network Buffer Cache. This leaves the files open as long as they are in the cache, preventing the underlying filesystem from being cleanly unmounted.

    To clear files from the cache and unmount the filesystem:

  • set the size of the network buffer cache to zero temporarily to clear the cache

    The old cache size can be displayed by no -o nbc_limit. The cache size can be set to zero by no -o nbc_limit=0.

  • unmount the filesystem

  • restore the previous cache size 
    no -o nbc_limit=old_value