File:  [NetBSD Developer Wiki] / wikisrc / tutorials / how_to_setup_a_webserver.mdwn
Revision 1.2: download - view: text, annotated - select for diffs
Thu Mar 14 23:44:47 2013 UTC (13 months, 1 week ago) by jdf
Branches: MAIN
CVS tags: HEAD
Add more levels to the TOC.

**Contents**

[[!toc levels=4]]

# How to run a webserver on NetBSD

First of all, logging as `root` is required thus you can install packages and 
edit system configuration files.

If you want to install packages to NetBSD, you can do this in several different 
ways, using pkgsrc, pkgin or pkg\_add. Please see the
[[chapter about installing additional software|guide/boot]] in the guide.

There are several HTTP daemons. The following text will introduce
[bozotic HTTP server](http://www.eterna.com.au/bozohttpd/) and
[Apache HTTP server](http://httpd.apache.org/).

## bozotic HTTP server

`bozohttpd` is a small and secure HTTP 1.1 server shipped with NetBSD 
(`/usr/libexec/httpd`) by default. It's very simple and there isn't even a 
configuration file. But it only provides the most basic features.

### Register the daemon

#### Run with inetd

`bozohttpd` can be run with `inetd`, and you need to register it to `inetd`. 
Daemons hosted by `inetd` is registered at `/etc/inetd.conf`. `inetd.conf` is an 
ascii file containing one service per line, and several fields per line. The 
basic layout is:

    service-name socket-type protocol wait/nowait user:group server-program arguments

In this case(handling HTTP requests), the basic format is:

    http	stream	tcp	nowait:600	nobody	FULL_PATH_OF_DAEMON DAEMON_NAME_AND_ARGUMENTS

Append this to `/etc/inetd.conf` (assuming that your files are located in 
`/var/www`):

    http	stream	tcp	nowait:600	nobody	/usr/libexec/httpd httpd /var/www

Telling `inetd` to reload the file makes `httpd` work immediately. You may run 
the following command:
     
    # /etc/rc.d/inetd reload
    Reloading inetd config files.

Here are the frequently used options:

 * `-X`: Enables directory indexing. 
 * `-c CGI_BIN_PATH`: Enables the CGI/1.1 interface.

To get more information about options, see `bozohttpd(8)`.

#### Run in standalone mode

`bozohttpd` can be run without `inetd`. You have to add `-b` to the parameters 
to enable daemon mode.

    /usr/libexec/httpd -b /var/www

Because listening ports under 1024 requires root privilege, and running a 
webserver with root privilege is unsafe, you may want to change the user to 
`nobody` after initializing sockets. The command argument for this is
`-U USERNAME`.

Now the command line looks like this:

    /usr/libexec/httpd -b -U nobody /var/www

To make `bozohttpd` run when the system boots, you have to activate it in your 
rc.local(5) by setting `httpd=YES`. Arguments you want to pass can be set with 
the `httpd_flags` variable, e.g. acitvating bozohttpd with directory indexing 
would result in:

    httpd=YES
    httpd_flags="-X"

### Examples

 * Use PHP parser(`/usr/pkg/bin/php`) to parse `.php` files in `/var/www`: 
   `httpd -C .php /usr/pkg/bin/php /var/www` (you need php installed)

 * Enable directory listing to share files via HTTP: `httpd -x PATH_TO_SHARE`

 * Run CGI programs(`/var/cgi`): `httpd -c /var/cgi /var/www`

## Apache HTTP server

The [Apache HTTP server](http://httpd.apache.org/) is a widely-used open source 
HTTP server. Apache is a powerful HTTP server, which can be extended by loading 
dynamic shared object (DSO).

### Install

You have to install Apache, it is not shipped with NetBSD. You can do this by 
executing `pkgin install apache`, `cd /usr/pkgsrc/www/apache; make install` or 
by using pkg\_add:

    # pkg_add apache-2.4.3
    pkg_add: Warning: package `apache-2.4.3' was built for a platform:
    pkg_add: NetBSD/i386 6.0 (pkg) vs. NetBSD/i386 6.0.1 (this host)
    apache-2.4.3: copying /usr/pkg/share/examples/httpd/extra/httpd-autoindex.conf to /usr/pkg/etc/httpd/httpd-autoindex.conf
    apache-2.4.3: copying /usr/pkg/share/examples/httpd/extra/httpd-dav.conf to /usr/pkg/etc/httpd/httpd-dav.conf
    apache-2.4.3: copying /usr/pkg/share/examples/httpd/extra/httpd-default.conf to /usr/pkg/etc/httpd/httpd-default.conf
    apache-2.4.3: copying /usr/pkg/share/examples/httpd/extra/httpd-info.conf to /usr/pkg/etc/httpd/httpd-info.conf
    apache-2.4.3: copying /usr/pkg/share/examples/httpd/extra/httpd-languages.conf to /usr/pkg/etc/httpd/httpd-languages.conf
    apache-2.4.3: copying /usr/pkg/share/examples/httpd/extra/httpd-manual.conf to /usr/pkg/etc/httpd/httpd-manual.conf
    apache-2.4.3: copying /usr/pkg/share/examples/httpd/extra/httpd-mpm.conf to /usr/pkg/etc/httpd/httpd-mpm.conf
    apache-2.4.3: copying /usr/pkg/share/examples/httpd/extra/httpd-multilang-errordoc.conf to /usr/pkg/etc/httpd/httpd-multilang-errordoc.conf
    apache-2.4.3: copying /usr/pkg/share/examples/httpd/extra/httpd-ssl.conf to /usr/pkg/etc/httpd/httpd-ssl.conf
    apache-2.4.3: copying /usr/pkg/share/examples/httpd/extra/httpd-userdir.conf to /usr/pkg/etc/httpd/httpd-userdir.conf
    apache-2.4.3: copying /usr/pkg/share/examples/httpd/extra/httpd-vhosts.conf to /usr/pkg/etc/httpd/httpd-vhosts.conf
    apache-2.4.3: copying /usr/pkg/share/examples/httpd/httpd.conf to /usr/pkg/etc/httpd/httpd.conf
    apache-2.4.3: copying /usr/pkg/share/examples/httpd/magic to /usr/pkg/etc/httpd/magic
    apache-2.4.3: copying /usr/pkg/share/examples/httpd/mime.types to /usr/pkg/etc/httpd/mime.types
    ===========================================================================
    The following files should be created for apache-2.4.3:

    	/etc/rc.d/apache (m=0755)
    	    [/usr/pkg/share/examples/rc.d/apache]

    ===========================================================================
    ===========================================================================
    $NetBSD: how_to_setup_a_webserver.mdwn,v 1.2 2013/03/14 23:44:47 jdf Exp $

    After apache-2.4.3, --enable-mpms-shared='event prefork worker' is
    passed to configure script, then three multi-process model is built
    and you can select the model in configuraton file.

    The mod_cgi.so module conflicts with non-prefork multi-process model,
    and mod_cgi.so module is not built anymore.
    You can use mod_cgid.so module instead.
    ===========================================================================

### Register the daemon

The main tool to control the service of Apache is `apachectl`. To make it work 
like normal services, supporting commands such as `/etc/rc.d/apache stop`, you 
need to copy the script provided by Apache to `/etc/rc.d/apache`:

    # cp /usr/pkg/share/examples/rc.d/apache /etc/rc.d

To make Apache run when system boots, you may set the rc variable `apache` to 
`yes`. This can be done by creating `/etc/rc.conf.d/apache` and insert the 
following text to the file:

    apache=yes

or writing this line into your rc.conf(5) directly.

You can also run this to start Apache immediately:

    # /etc/rc.d/apache start
    Starting apache.

or:

    # apachectl start

To see whether the server is started successfully, you can visit 
`http://127.0.0.1`. The dafault page is:

    <html><body><h1>It works!</h1></body></html>

Another way to check the daemon status:

    # /etc/rc.d/apache status
    apache is running as pid 1574.

Note: Since version 2.0, Apache doesn't support `inetd` operation mode anymore. 
Running Apache with `inetd` is not supported.

### Configuration

Apache has lots of features, so it uses a configuration 
file(`/usr/pkg/etc/httpd/httpd.conf`). The general structure of this document 
is:

    KEY VALUES
    <DIRECTORY VALUES>
    	KEY VALUES
    </DIRECTORY>

Here are the frequently used options:

 * `DocumentRoot "WEB_ROOT"` The directory out of which you will serve your 
   documents. By default, all requests are taken from this directory.

 * `ErrorDocument ERROR_CODE RESULT` Customizable error responses: the 
   `ERROR_CODE` can be 404 / 403 / etc, the `RESULT` can be a URL or a plain 
   text message.

 * `ServerAdmin MAIL_ADDRESS` The address to which problems with the server 
   should be emailed. This address appears on some server-generated pages, such 
   as error documents.

To check the syntax, you may run:

    NetBSD# apachectl configtest
    Syntax OK

#### DSO

Apache is a modular program where the administrator can choose the functionality 
to include in the server by selecting a set of modules (DSO). Apache's DSOs are 
located in `/usr/pkg/lib/httpd`. 

    # cd /usr/pkg/lib/httpd
    # ls
    httpd.exp                   mod_authz_owner.so          mod_ext_filter.so           mod_mpm_worker.so           mod_session_cookie.so
    mod_access_compat.so        mod_authz_user.so           mod_file_cache.so           mod_negotiation.so          mod_session_dbd.so
    mod_actions.so              mod_autoindex.so            mod_filter.so               mod_proxy.so                mod_setenvif.so
    mod_alias.so                mod_buffer.so               mod_headers.so              mod_proxy_ajp.so            mod_slotmem_plain.so
    mod_allowmethods.so         mod_cache.so                mod_heartbeat.so            mod_proxy_balancer.so       mod_slotmem_shm.so
    mod_asis.so                 mod_cache_disk.so           mod_heartmonitor.so         mod_proxy_connect.so        mod_socache_dbm.so
    mod_auth_basic.so           mod_cgid.so                 mod_include.so              mod_proxy_express.so        mod_socache_memcache.so
    mod_auth_digest.so          mod_charset_lite.so         mod_info.so                 mod_proxy_fcgi.so           mod_socache_shmcb.so
    mod_auth_form.so            mod_data.so                 mod_lbmethod_bybusyness.so  mod_proxy_fdpass.so         mod_speling.so
    mod_authn_anon.so           mod_dav.so                  mod_lbmethod_byrequests.so  mod_proxy_ftp.so            mod_ssl.so
    mod_authn_core.so           mod_dav_fs.so               mod_lbmethod_bytraffic.so   mod_proxy_http.so           mod_status.so
    mod_authn_dbd.so            mod_dav_lock.so             mod_lbmethod_heartbeat.so   mod_proxy_scgi.so           mod_substitute.so
    mod_authn_dbm.so            mod_dbd.so                  mod_log_config.so           mod_ratelimit.so            mod_unique_id.so
    mod_authn_file.so           mod_deflate.so              mod_log_debug.so            mod_reflector.so            mod_unixd.so
    mod_authn_socache.so        mod_dialup.so               mod_log_forensic.so         mod_remoteip.so             mod_userdir.so
    mod_authz_core.so           mod_dir.so                  mod_logio.so                mod_reqtimeout.so           mod_usertrack.so
    mod_authz_dbd.so            mod_dumpio.so               mod_mime.so                 mod_request.so              mod_version.so
    mod_authz_dbm.so            mod_echo.so                 mod_mime_magic.so           mod_rewrite.so              mod_vhost_alias.so
    mod_authz_groupfile.so      mod_env.so                  mod_mpm_event.so            mod_sed.so                  mod_watchdog.so
    mod_authz_host.so           mod_expires.so              mod_mpm_prefork.so          mod_session.so

Write `LoadModule MODULE FILENAME` in the configuration file, and the specific 
module will be loaded when Apache starts. You can also configure the module in 
this way:

    <IfModule MODULE>
    	KEY VALUES
    </IfModule>

Run the following commands to apply the configuration:

    NetBSD# /etc/rc.d/apache reload

or:

    NetBSD# apachectl graceful

To get full manual, visit `/usr/pkg/share/httpd/manual`.

#### Run CGI

For security ressons, Apache doesn't permit executing CGI programs by default. 
Uncomment the following line to `httpd.conf` to permit Apache executing CGI:

    LoadModule cgid_module lib/httpd/mod_cgid.so

The next step is telling Apache which directory is set aside for CGI programs. 
Apache will assume that every file in this directory is a CGI program, and will 
attempt to execute it, when that particular resource is requested by a client.

The syntax is:

    ScriptAlias URL_PATH FILE_PATH_OR_DIRECTORY_PATH

For example:

    ScriptAlias /cgi-bin/ /usr/local/apache2/cgi-bin/

The CGI programs should be given executing permission. Modify the permission in 
this way:

    chmod a+x CGI_FILE_PATH

#### Run PHP

The PHP module is not included by default. Run the following command to obtain 
the Apache module (or its pkgin and pkgsrc equivalents).

    # pkg_add -v "ap24-php5*"

You should load the PHP module in `httpd.conf`. Append the following lines to 
`httpd.conf`:

    LoadModule php5_module lib/httpd/mod_php5.so
    AddHandler application/x-httpd-php .php

Maybe you want `.php` instead of `.html` to be your default page. You may append 
the following line:

    DirectoryIndex index.php index.html

You can write the following lines as a php file and visit it to check whether 
PHP works correctly. Don't forget to reload the configuration before testing.

    <?php phpinfo(); ?>

If you want to configure PHP, use the following syntax:

    <IfModule mod_php5.c>
    	php_value NAME VALUE
    	php_flag NAME on|off
    	php_admin_value NAME VALUE
    	php_admin_flag NAME on|off
    </IfModule>

#### Further reading

You should also have a look at the excellent online documentation of Apache: 
<http://httpd.apache.org/docs/>

CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb