Installing HTTPi

If you are upgrading from a previous version of HTTPi, you may not need to install totally from scratch. See the special upgrading section to see what you need to do to keep any changes you've made to HTTPi and still benefit from the latest revisions.

HTTPi offers six "flavours" for you to choose from. Not all flavours are available in earlier versions.

• Demonic: This is a daemon version of HTTPi that is started up from the command line or an rc script. Most people will want to try the Demonic version first, as you don't need access to your (x)inetd's configuration files (read: don't need to be root) to successfully install and run it. Demonic HTTPi was first introduced in 0.7.

• inetd and xinetd: This is the original style of HTTPi, used to run HTTPi "on demand" from either network process manager. xinetd is usually faster. This is preferred if you don't want HTTPi to run as a daemon. inetd HTTPi has been supported since the original 0.1 version; xinetd HTTPi was first introduced in 0.4.

• stunnel: This is intended for running HTTPi in SSL mode to allow it to act as a secure host, and is the only supported way to enable SSL. You will need a working, running stunnel installation with your certificates and stunnel.conf already set up before running this installation option. stunnel HTTPi was first introduced in 1.6.

• launchd: This is intended for users of Apple's launchd, typically Darwin, Mac OS X 10.4 and higher, or other users who may have it installed, and who don't want to use Demonic HTTPi. launchd HTTPi was first introduced in 1.6.

• Generic: This configuration option simply builds an executable and does no installation. This is for people who wish to use the inetd version but do not have a compatible inetd, and is included really only for backwards compatibility. The Generic option was first introduced in 0.4.

To report bugs in the installation procedure, please send a complete report, including system configuration and error messages, to httpi@floodgap.com.

inetd/xinetd Instructions | Demonic Installation Instructions | stunnel Installation Instructions | launchd Installation Instructions | Generic Installation Instructions

1. gunzip and un-tar the installation archive to a convenient directory. Do not delete this directory -- you will need it if you intend to make later configuration changes. Keep the directory in a safe place.

2. Run the Demonic HTTPi configure script:

   % perl configure.demonic
   

3. The Demonic HTTPi system will ask you some standard questions, such as the mount point of the directory HTTPi will serve, where you want the access log, where you want the final executable, and so on. You will also be asked whether you wish to enable any of the various server extensions, such as the restriction matrix and the HTTPerl hack. If you intend to run multiple instances of HTTPi with different configurations, such as for IP-based virtual servers, you must specify a different path for each final executable -- the configure script hardcodes configuration settings in each build.

4. Next, you will need to supply the IP number and TCP port Demonic HTTPi will bind to. You can implement IP-based virtual servers by specifying different IP addresses for each executable, and running individual processes per IP address. If you just want to run it, use the default 0.0.0.0 for the IP address, which will cause HTTPi to bind to any available interface on your machine (i.e., INADDR_ANY).

   For the TCP port, the default is 80, but you will need to run Demonic HTTPi as root to bind this port (or any port number under 1024). If you are merely testing the server, enter a high port number (8080 is popular), which will allow you to run it without superuser privileges for testing.

5. Once this information is entered, HTTPi will next autoconfigure itself for socket operations. Therefore, it needs the standard constants, such as SOMAXCONN AF_INET PF_INET etc. HTTPi will try your C compiler first (gcc, or if unavailable/unsuitable your native cc -- the sockcons.c file so far works on HP/UX cc and anywhere gcc is supported) to get as complete a set as possible. If it can't get them that way, HTTPi can attempt to extract them from your Perl's Socket.pm (it does not need Socket.pm to execute). Otherwise, you can supply them yourself (HTTPi knows the standard values for them).

   Bug: Socket.pm does not define IPPROTO_TCP. configure.demonic has a kludge to assume six if it is getting its constants from Socket.pm. This should be okay in almost all cases.

6. configure.demonic will build your executable, which you can simply run from the command line. You do not need to background the process; it will do so automatically. You should be able to access your server almost immediately.

   Now, read the manual.

As both require modification to configuration files with similar function, both configure.xinetd and configure.inetd operate very similarly. However, you will almost certainly need superuser access to make any changes to your (x)inetd's configuration files. If you do not run the configure scripts as root, questions pertaining to installing HTTPi in (x)inetd's configuration files will not be asked, and HTTPi will not be connected to (x)inetd until you make the changes manually, or re-run the configure script as root.

Please note that configure.xinetd assumes that your xinetd's configuration file is in /etc/xinetd.conf, the default location.

1. gunzip and un-tar the installation archive to a convenient directory. Do not delete this directory -- you will need it if you intend to make later configuration changes. Keep the directory in a safe place.

2. Run the inetd or xinetd HTTPi configure script:

   % perl configure.inetd
   

   or

   % perl configure.xinetd
   

3. The configure system will ask you some standard questions, such as the mount point of the directory HTTPi will serve, where you want the access log, where you want the final executable, and so on. You will also be asked whether you wish to enable any of the various server extensions, such as the restriction matrix and the HTTPerl hack. If you intend to run multiple instances of HTTPi with different configurations, such as for xinetd IP-based virtual servers, you must specify a different path for each final executable -- the configure script hardcodes configuration settings in each build. You may also need to know one of your socket constants for portability, but fortunately the value really is constant between most OSes.

4. After these questions are answered, (x)inetd-specific installation questions will be asked. First, enter the username you want the server to run as. root ensures that the server can access all resources, and allows the server to change uid for running user-created executables; however, nobody is much less of a security hole in some respects.

   The user you choose to run HTTPi as also may affect logging and the New Security Model, both described in the user manual.

5. Next, you can alter the way (x)inetd manages HTTPi by autothrottling the number of processes spawned. With inetd, you can only specify one or infinite, but xinetd will allow you to specify a maximum. Answer the question based on your chosen installation. The default for both is infinite. Some inetds may not properly drive HTTPi with this option set to anything other than infinite (i.e., wait instead of nowait).

6. Finally, network specific questions. xinetd installations only: You can specify a particular IP address that HTTPi will "bind" to (via xinetd), allowing IP-based virtual servers by specifying different IP addresses for each executable, and running individual processes per IP address. If you just want to run it, use default for the IP address, which will cause HTTPi to bind to any available interface to xinetd (usually INADDR_ANY). This option is not available for standard inetd installations.

7. Next, select a TCP port to run HTTPi on. For the TCP port, the default is 80, but if you are merely testing the server, we suggest a high port number like 8080 that will allow you to run it without disturbing any other processes on port 80.

8. Finally, a service name must be generated (either for /etc/services [inetd] or for /etc/xinetd.conf [xinetd]). The configure script will figure out a default, usually www for port 80, and www# for other port numbers (like www9696). Be careful that it doesn't choose an already existing service, though it will attempt to check for this, and utilise the existing service name if it can.

9. The configure script will check the sanity of your configuration files (and alert you to any possible problems, though you should really check them for yourself, just in case!), build the executable, and if allowed, make the changes to (x)inetd's configuration files for you. You will need to send your (x)inetd process a SIGHUP signal as superuser, and your server should then come on line immediately. Note that you will see no HTTPi processes when the server is not being accessed.

   Now, read the manual.

configure.stunnel will modify your stunnel configuration file to enable HTTPi, but your stunnel configuration file must be pre-configured with your desired cryptographic settings and global options, along with your certificates. HTTPi does not contain any cryptographic code itself, and relies on stunnel to do SSL negotiation. If stunnel is not already working, HTTPi won't work either.

HTTPi only operates when stunnel is running as a daemon. In this configuration, it acts essentially as another inetd-like environment. Although you could use stunnel to act as a tunnel to a Demonic HTTPi installation, this application is not supported by configure.stunnel, and HTTPi also does not support operation when stunnel itself is being run from within inetd.

You will almost certainly need superuser access to make any changes to your stunnel's configuration files. If you do not run the configure scripts as root, questions pertaining to installing HTTPi in stunnel's configuration file will not be asked, and HTTPi will not be connected to stunnel until you make the changes manually, or re-run the configure script as root.

1. gunzip and un-tar the installation archive to a convenient directory. Do not delete this directory -- you will need it if you intend to make later configuration changes. Keep the directory in a safe place.

2. Run the stunnel HTTPi configure script:

   % perl configure.stunnel
   

3. To confirm that your stunnel.conf already exists, you will first be asked to provide the path to it before the installation can continue. It is not checked for veracity, only that it is present, so be sure it works.

4. The configure system will next ask you some standard questions, such as the mount point of the directory HTTPi will serve, where you want the access log, where you want the final executable, and so on. You will also be asked whether you wish to enable any of the various server extensions, such as the restriction matrix and the HTTPerl hack. If you intend to run multiple instances of HTTPi with different configurations, such as for IP-based virtual servers, you must specify a different path for each final executable -- the configure script hardcodes configuration settings in each build. You may also need to know one of your socket constants for portability, but fortunately the value really is constant between most OSes.

5. After these questions are answered, stunnel-specific installation questions will be asked. You can specify a particular IP address that HTTPi will "bind" to (via stunnel), allowing IP-based virtual servers by specifying different IP addresses for each executable, and running individual processes per IP address. If you just want to run it, use the default default for the IP address, which will cause HTTPi to bind to any available interface on your machine (INADDR_ANY).

6. Next, select a TCP port to run HTTPi on. For the TCP port, the default is 443 (for SSL), but if you are merely testing the server, we suggest a high port number like 4443 that will allow you to run it without disturbing any other processes on port 443.

7. Finally, a service name must be generated. The configure script will figure out a default, usually httpi# for most port numbers (like httpi9696), but you may override it. Be careful that it doesn't choose an already existing service, though it will attempt to check for this.

8. The configure script will then build the executable, and if allowed, make the changes to stunnel.conf for you. You will need to restart your stunnel daemon as superuser, and your server should then come on line immediately. Note that you will see no HTTPi processes when the server is not being accessed.

   Now, read the manual.

configure.launchd installs HTTPi as if launchd were inetd itself, running HTTPi "on demand" when accessed just like inetd/xinetd. Although launchd could be used in an rc-like capacity for automatically starting Demonic HTTPi upon system boot, this very simple usage is not directly supported by configure.launchd; for a very useful general purpose tool that will do this and more, look at Lingon for 10.5+, or Launchd Editor for 10.4+.

You will almost certainly need superuser access to create a property list (or plist) for launchd's configuration. If you do not run the configure scripts as root, questions pertaining to creating a .plist will not be asked, and HTTPi will not be connected to launchd until you make the property list manually, or re-run the configure script as root.

1. gunzip and un-tar the installation archive to a convenient directory. Do not delete this directory -- you will need it if you intend to make later configuration changes. Keep the directory in a safe place.

2. Run the launchd HTTPi configure script:

   % perl configure.launchd
   

3. The configure system will ask you some standard questions, such as the mount point of the directory HTTPi will serve, where you want the access log, where you want the final executable, and so on. You will also be asked whether you wish to enable any of the various server extensions, such as the restriction matrix and the HTTPerl hack. If you intend to run multiple instances of HTTPi with different configurations, such as for IP-based virtual servers, you must specify a different path for each final executable -- the configure script hardcodes configuration settings in each build. You may also need to know one of your socket constants for portability, but fortunately the value really is constant between most OSes.

4. After these questions are answered, launchd-specific installation questions will be asked. First, enter where you want the property list file to be created (the default location for Mac OS X is given for you), and the label for the service which launchd and launchctl will use to unambiguously identify it. Since it is an identification string, it should be unique.

5. Next, the configure script will ask you what username you want the server to run as. root ensures that the server can access all resources, and allows the server to change uid for running user-created executables; however, nobody is much less of a security hole in some respects. You will be also asked to specify the group name, such as wheel, admin or nobody.

   The user you choose to run HTTPi as also may affect logging and the New Security Model, both described in the user manual.

6. Finally, network specific questions. You can specify a particular IP address that HTTPi will "bind to" (via launchd), allowing IP-based virtual servers by specifying different IP addresses for each executable, and running individual processes per IP address. If you just want to run it, use the default default for the IP address, which will cause HTTPi to bind to any available interface to launchd (usually INADDR_ANY).

7. Next, select a TCP port to run HTTPi on. For the TCP port, the default is 80, but if you are merely testing the server, we suggest a high port number like 8080 that will allow you to run it without disturbing any other processes on port 80 (such as Personal Web Sharing [i.e., Apache]).

8. The configure script will then build the executable, and if allowed, generate the property list file in the location you specified. You will then have to unload any previous service with the specified identifier, if any, and then load this new one using launchctl (the configure script will give you a suggested command to use). Your new server should come on-line immediately. Note that you will see no HTTPi processes when the server is not being accessed.

   Now, read the manual.

1. gunzip and un-tar the installation archive to a convenient directory. Do not delete this directory -- you will need it if you intend to make later configuration changes. Keep the directory in a safe place.

2. Run the generic HTTPi configure script:

   % perl configure.generic
   

3. The generic HTTPi system will ask you some standard questions, such as the mount point of the directory HTTPi will serve, where you want the access log, where you want the final executable, and so on. You will also be asked whether you wish to enable any of the various server extensions, such as the restriction matrix and the HTTPerl hack. If you intend to run multiple instances of HTTPi with different configurations, you must specify a different path for each final executable -- the configure script hardcodes configuration settings in each build.

4. The executable will then be built. At this point, you should attempt to connect it to your network process manager and see if it will function correctly.

   Then, read the manual.