FAQ: Startup and Shutdown

Note: This is an FAQ document. A mustgather for start/stop problem also exists here.

Do I have to start IBM HTTP Server as root?

Port access on Unix and Linux

Applications running as users other than root are normally prevented from binding to (listening on) low-numbered ports on Unix and Linux systems. Low-numbered ports are those ports below 1024. The standard ports for most popular Internet protocols, including http and https, are low-numbered ports.

On Solaris 10, IBM HTTP Server must be started as root to bind to a low-numbered port unless the user which starts the web server has been granted the net_privaddr privilege.

On AIX, HP-UX, and Linux, and other versions of Solaris, IBM HTTP Server must be started as root to bind to a low-numbered port. A possible work-around is to utilize a firewall to redirect requests to port 80 to a high port. The web server will listen on the high-numbered port, thus avoiding the root requirement.

Solutions using setcap on Linux or setsecattr on AIX, each which allow port binding to be delegated to non-root users, block the use of LD_LIBRARY_PATH/LIBPATH required to run IHS and cannot be used.

Port access on z/OS

z/OS can restrict low ports to UID(0) users or authorized programs, allow reservation of particular ports to specified users or jobs, or allow unrestricted access. We recommend that IBM HTTP Server be started as a non-UID(0) user and z/OS configuration used to allow access to the required ports. Refer to Performing required z/OS system configurations in the IBM HTTP Server InfoCenter for more information.

Log and configuration file access

The user id starting the web server must have read access to the configuration files and write access to the directory containing log files and other run-time files. This may require starting as root, or changing the ownership or permission of existing log files, depending on the configuration.

What happens if I stop IBM HTTP Server using SIGKILL?

Stopping the server by sending SIGTERM to the parent process

  • no new connections will be accepted, starting almost immediately

  • existing requests will have a short time to finish and log their results

  • for most child processes:

    • the active request will finish normally

    • the active request will be logged

  • for child processes that don't finish their request in a reasonable amount of time:

    • the request will be abruptly terminated

    • the active request won't be logged

Stopping the server by sending SIGKILL to all of the processes

  • no new connections will be accepted, starting almost immediately

  • all active requests will be abruptly terminated

  • no active requests will be logged

  • the pid file won't be removed, so a warning will be logged when the server is started again

  • no permanent problems expected

  • Note: Third-party modules could require manual intervention before restart if they have resources that they must release at termination.

How can I start IHS during AIX startup?

Here are AIX inittab entries to start IHS 1.3 or IHS 2.0:

: ihshttpd:2:wait:/usr/HTTPServer/bin/httpd > /dev/console 2>&1     
ihshttpd:2:wait:/usr/IBMIHS/bin/apachectl start > /dev/console 2>&1

The first entry is commented out (leading ":") and starts IHS 1.3. The second entry is active and starts IHS 2. For either 1.3 or 2.0, replace the path to httpd or apachectl with the chosen installation directory. The "apachectl start" command is a valid way to start IHS 1.3 or IHS 2.0. The "httpd" command is only valid for IHS 1.3.

Why are httpd processes still active when apachectl stop completes?

apachectl stop sends a signal to the parent process, and then exits. As soon as the parent process receives the signal, it starts terminating the child processes. In many cases, by the time you can look for child processes after the completion of apachectl stop they will have already exited. Some of the following are reasons why they will linger for some time:

  • high system load (perhaps caused by many httpd child processes having to wake up and exit

  • active requests being handled by one or more httpd child processes

If a shutdown problem is suspected with IBM HTTP Server 2.0 or above, make sure that you are using one of the following software levels:

  • 6.1 or later
    GA

  • 6.0.x
    6.0.0.2 or later

  • 2.0.42.x, 2.0.47.x
    PK01070 or later

How does IBM HTTP Server determine when a child process should end? Does it have a timeout?

There is no timeout. Beyond normal web server termination or restart, here are the situations where a child process will exit:

All releases of IBM HTTP Server on Windows

A child process will only end if MaxRequestsPerChild is set to non-zero, and the process has handled at least that many client connections.

IBM HTTP Server 1.3.x on Linux and Unix

If MaxRequestsPerChild is set to non-zero, a child process will exit once it has handled that many client connections.

While there are more idle processes than the value of MaxSpareServers, one child process will exit per second.*

*On AIX, if AcceptMutex is set to pthread, idle child process termination often does not work. Code AcceptMutex fcntl to work around this problem.

IBM HTTP Server 2.0 and higher on Linux and Unix

If MaxRequestsPerChild is set to non-zero, a child process will exit once it has handled that many client connections.

While there are more idle threads than the value of MaxSpareThreads, one child process will exit per second.

Linux and Unix: How do I keep IHS from terminating child processes prior to web server shutdown?

Occasionally, problems with IHS or third-party modules can be attributed to issues which occur when IHS child processes terminate. In this case, it is helpful to disable child process termination until the problem can be fully resolved.

IHS 2.0 and above

Set MaxRequestsPerChild to 0 and set MaxSpareThreads to the same value as MaxClients.

IHS 1.3

Set MaxRequestsPerChild to 0 and set MaxSpareServers to the same value as MaxClients.

How do you gracefully shut down IHS?

In IHS 7.0 and later on Unix, apachectl -k graceful-stop will stop listening for new requests but allow active requests to finish, waiting forever by default, or until GracefulShutdownTimeout seconds have elapsed.

Otherwise, there is no mechanism to shut down the web server yet allow active requests to gracefully finish. Active requests must finish within about 7 seconds, or they may be forcefully terminated when the child process is killed.

How do I start IHS during the Linux boot process?

The first step here is determine which initialization system your Linux distribution is using. This can be determined by using the following command file /sbin/init.

Systems using systemd will have output similar to the following:

# file /sbin/init
/sbin/init: symbolic link to /lib/systemd/systemd

Using systemd

Many Linux distributions now use systemd as their initialization system. A few notable distributions that now use systemd are:

  • RHEL 7 and above

  • SLES 12 and above

  • Ubuntu 15.04 and above

Although SysV Init scripts are mostly compatiable with systemd, users may want to switch to a systemd unit file as they are simpler. However, you cannot mix and match starting/stopping/querying services with systemd and directly (apachectl) as systemd will not know the correct status.

Example Unit File

[Unit]
Description=IBM HTTP Server
After=network-online.target remote-fs.target nss-lookup.target

[Service]
Type=forking
PIDFile=/opt/IHS/logs/httpd.pid
ExecStart=/opt/IHS/bin/apachectl start -d /opt/IHS
ExecStop=/opt/IHS/bin/apachectl graceful-stop
ExecReload=/opt/IHS/bin/apachectl graceful
PrivateTmp=true
LimitNOFILE=infinity

[Install]
WantedBy=multi-user.target

NOTE: The example unit file above is provided AS-IS with no support.

Steps to Enable the IHS Service (all commands require root privilege)

  1. Create the file ihs.service under /etc/systemd/system.

  2. Copy the contents of the example above into the file. Update the IHS root paths as neccessary.

  3. Start the service using systemctl start ihs.

  4. Enable the service to be started during start up using systemctl enable ihs.

Other Notes

  • To see the status of the IHS service, systemctl status ihs can be used.

  • To setup the IHS Admin Server using systemd, replace apachectl with adminctl and httpd.pid with admin.pid in a new service.

Using SysVInit

The only IHS specific information required for this task is that the full path to <ihsinst>bin/apachectl should be used to stop and start IHS version 2.0.x and later. Further apachectl information is available here

Basic example of starting IHS during Linux startup:

  1. Determine the default runlevel for your system by running the following command: grep default /etc/inittab

  2. As root, create a new file in /etc/init.d/ using a name of your choosing, e.g. /etc/init.d/IHS_6.1)

  3. Contents of an example/etc/init.d/IHS_6.1 script, consult your linux manual for information on details for creating your own that declares proper dependencies or interoperates with chkconfig/inssrv. This script is provided AS-IS with no support.

    #!/bin/bash
    # SERVICENAME should match this filename
    SERVICENAME=$(basename $0)
    LOCKFILE="/var/lock/subsys/${SERVICENAME}"
    APACHECTL=/opt/IHS61/bin/apachectl

    # The next lines are for chkconfig on RedHat systems.
    # chkconfig: 2345 98 02
    # description: Starts and stops IHS

    # The next lines are for chkconfig on SuSE systems.
    ### BEGIN INIT INFO
    # Provides: IHS_61.1
    # Required-Start: $network $syslog
    # Required-Stop:
    # Default-Start: 2 3 4 5
    # Default-Stop: 0 6
    # Short-Description: Starts and stops IHS
    # Description: Starts and stops IHS
    ### END INIT INFO


    case "$1" in
      start)
        touch $LOCKFILE
        ;;

      stop)
        rm -f $LOCKFILE
        ;;

      *)
        echo "Usage: $0 {start|stop|status|restart}"
        exit 1
        ;;
    esac

    $APACHECTL "$@"

  1. Mark the file from the previous step as executable by owner: chmod u+x /etc/init.d/IHS_6.1

  2. Run chkconfig --add IHS_61 and verify proper symlinks are created. If the symlinks are not created by chkconfig, create them manually in the desired runlevel directories (choose high-numbered startup links).

  3. Beginning with the next full reboot, the OS will call this script with the parameter "start" towards the end of system initialization

  4. The LOCKFILE manipulation is required on RHEL5 and later, otherwise the service is not stopped at shutdown.

More elaborate interaction with system facilities is possible as long as the interface to IHS is apachectl.

apachectl reports "Argument list too long" on RHEL 7 after upgrading kernel to 3.10.0-514.21.2.el7

This issue has been documented in the startup mustgather document here.