Annotation of wikisrc/tutorials/how_to_setup_a_webserver.mdwn, revision 1.2

1.1       jdf         1: **Contents**
                      2: 
1.2     ! jdf         3: [[!toc levels=4]]
1.1       jdf         4: 
                      5: # How to run a webserver on NetBSD
                      6: 
                      7: First of all, logging as `root` is required thus you can install packages and 
                      8: edit system configuration files.
                      9: 
                     10: If you want to install packages to NetBSD, you can do this in several different 
                     11: ways, using pkgsrc, pkgin or pkg\_add. Please see the
                     12: [[chapter about installing additional software|guide/boot]] in the guide.
                     13: 
                     14: There are several HTTP daemons. The following text will introduce
                     15: [bozotic HTTP server](http://www.eterna.com.au/bozohttpd/) and
                     16: [Apache HTTP server](http://httpd.apache.org/).
                     17: 
                     18: ## bozotic HTTP server
                     19: 
                     20: `bozohttpd` is a small and secure HTTP 1.1 server shipped with NetBSD 
                     21: (`/usr/libexec/httpd`) by default. It's very simple and there isn't even a 
                     22: configuration file. But it only provides the most basic features.
                     23: 
                     24: ### Register the daemon
                     25: 
                     26: #### Run with inetd
                     27: 
                     28: `bozohttpd` can be run with `inetd`, and you need to register it to `inetd`. 
                     29: Daemons hosted by `inetd` is registered at `/etc/inetd.conf`. `inetd.conf` is an 
                     30: ascii file containing one service per line, and several fields per line. The 
                     31: basic layout is:
                     32: 
                     33:     service-name socket-type protocol wait/nowait user:group server-program arguments
                     34: 
                     35: In this case(handling HTTP requests), the basic format is:
                     36: 
                     37:     http       stream  tcp     nowait:600      nobody  FULL_PATH_OF_DAEMON DAEMON_NAME_AND_ARGUMENTS
                     38: 
                     39: Append this to `/etc/inetd.conf` (assuming that your files are located in 
                     40: `/var/www`):
                     41: 
                     42:     http       stream  tcp     nowait:600      nobody  /usr/libexec/httpd httpd /var/www
                     43: 
                     44: Telling `inetd` to reload the file makes `httpd` work immediately. You may run 
                     45: the following command:
                     46:      
                     47:     # /etc/rc.d/inetd reload
                     48:     Reloading inetd config files.
                     49: 
                     50: Here are the frequently used options:
                     51: 
                     52:  * `-X`: Enables directory indexing. 
                     53:  * `-c CGI_BIN_PATH`: Enables the CGI/1.1 interface.
                     54: 
                     55: To get more information about options, see `bozohttpd(8)`.
                     56: 
                     57: #### Run in standalone mode
                     58: 
                     59: `bozohttpd` can be run without `inetd`. You have to add `-b` to the parameters 
                     60: to enable daemon mode.
                     61: 
                     62:     /usr/libexec/httpd -b /var/www
                     63: 
                     64: Because listening ports under 1024 requires root privilege, and running a 
                     65: webserver with root privilege is unsafe, you may want to change the user to 
                     66: `nobody` after initializing sockets. The command argument for this is
                     67: `-U USERNAME`.
                     68: 
                     69: Now the command line looks like this:
                     70: 
                     71:     /usr/libexec/httpd -b -U nobody /var/www
                     72: 
                     73: To make `bozohttpd` run when the system boots, you have to activate it in your 
                     74: rc.local(5) by setting `httpd=YES`. Arguments you want to pass can be set with 
                     75: the `httpd_flags` variable, e.g. acitvating bozohttpd with directory indexing 
                     76: would result in:
                     77: 
                     78:     httpd=YES
                     79:     httpd_flags="-X"
                     80: 
                     81: ### Examples
                     82: 
                     83:  * Use PHP parser(`/usr/pkg/bin/php`) to parse `.php` files in `/var/www`: 
                     84:    `httpd -C .php /usr/pkg/bin/php /var/www` (you need php installed)
                     85: 
                     86:  * Enable directory listing to share files via HTTP: `httpd -x PATH_TO_SHARE`
                     87: 
                     88:  * Run CGI programs(`/var/cgi`): `httpd -c /var/cgi /var/www`
                     89: 
                     90: ## Apache HTTP server
                     91: 
                     92: The [Apache HTTP server](http://httpd.apache.org/) is a widely-used open source 
                     93: HTTP server. Apache is a powerful HTTP server, which can be extended by loading 
                     94: dynamic shared object (DSO).
                     95: 
                     96: ### Install
                     97: 
                     98: You have to install Apache, it is not shipped with NetBSD. You can do this by 
                     99: executing `pkgin install apache`, `cd /usr/pkgsrc/www/apache; make install` or 
                    100: by using pkg\_add:
                    101: 
                    102:     # pkg_add apache-2.4.3
                    103:     pkg_add: Warning: package `apache-2.4.3' was built for a platform:
                    104:     pkg_add: NetBSD/i386 6.0 (pkg) vs. NetBSD/i386 6.0.1 (this host)
                    105:     apache-2.4.3: copying /usr/pkg/share/examples/httpd/extra/httpd-autoindex.conf to /usr/pkg/etc/httpd/httpd-autoindex.conf
                    106:     apache-2.4.3: copying /usr/pkg/share/examples/httpd/extra/httpd-dav.conf to /usr/pkg/etc/httpd/httpd-dav.conf
                    107:     apache-2.4.3: copying /usr/pkg/share/examples/httpd/extra/httpd-default.conf to /usr/pkg/etc/httpd/httpd-default.conf
                    108:     apache-2.4.3: copying /usr/pkg/share/examples/httpd/extra/httpd-info.conf to /usr/pkg/etc/httpd/httpd-info.conf
                    109:     apache-2.4.3: copying /usr/pkg/share/examples/httpd/extra/httpd-languages.conf to /usr/pkg/etc/httpd/httpd-languages.conf
                    110:     apache-2.4.3: copying /usr/pkg/share/examples/httpd/extra/httpd-manual.conf to /usr/pkg/etc/httpd/httpd-manual.conf
                    111:     apache-2.4.3: copying /usr/pkg/share/examples/httpd/extra/httpd-mpm.conf to /usr/pkg/etc/httpd/httpd-mpm.conf
                    112:     apache-2.4.3: copying /usr/pkg/share/examples/httpd/extra/httpd-multilang-errordoc.conf to /usr/pkg/etc/httpd/httpd-multilang-errordoc.conf
                    113:     apache-2.4.3: copying /usr/pkg/share/examples/httpd/extra/httpd-ssl.conf to /usr/pkg/etc/httpd/httpd-ssl.conf
                    114:     apache-2.4.3: copying /usr/pkg/share/examples/httpd/extra/httpd-userdir.conf to /usr/pkg/etc/httpd/httpd-userdir.conf
                    115:     apache-2.4.3: copying /usr/pkg/share/examples/httpd/extra/httpd-vhosts.conf to /usr/pkg/etc/httpd/httpd-vhosts.conf
                    116:     apache-2.4.3: copying /usr/pkg/share/examples/httpd/httpd.conf to /usr/pkg/etc/httpd/httpd.conf
                    117:     apache-2.4.3: copying /usr/pkg/share/examples/httpd/magic to /usr/pkg/etc/httpd/magic
                    118:     apache-2.4.3: copying /usr/pkg/share/examples/httpd/mime.types to /usr/pkg/etc/httpd/mime.types
                    119:     ===========================================================================
                    120:     The following files should be created for apache-2.4.3:
                    121: 
                    122:        /etc/rc.d/apache (m=0755)
                    123:            [/usr/pkg/share/examples/rc.d/apache]
                    124: 
                    125:     ===========================================================================
                    126:     ===========================================================================
1.2     ! jdf       127:     $NetBSD: how_to_setup_a_webserver.mdwn,v 1.1 2013/03/14 23:43:53 jdf Exp $
1.1       jdf       128: 
                    129:     After apache-2.4.3, --enable-mpms-shared='event prefork worker' is
                    130:     passed to configure script, then three multi-process model is built
                    131:     and you can select the model in configuraton file.
                    132: 
                    133:     The mod_cgi.so module conflicts with non-prefork multi-process model,
                    134:     and mod_cgi.so module is not built anymore.
                    135:     You can use mod_cgid.so module instead.
                    136:     ===========================================================================
                    137: 
                    138: ### Register the daemon
                    139: 
                    140: The main tool to control the service of Apache is `apachectl`. To make it work 
                    141: like normal services, supporting commands such as `/etc/rc.d/apache stop`, you 
                    142: need to copy the script provided by Apache to `/etc/rc.d/apache`:
                    143: 
                    144:     # cp /usr/pkg/share/examples/rc.d/apache /etc/rc.d
                    145: 
                    146: To make Apache run when system boots, you may set the rc variable `apache` to 
                    147: `yes`. This can be done by creating `/etc/rc.conf.d/apache` and insert the 
                    148: following text to the file:
                    149: 
                    150:     apache=yes
                    151: 
                    152: or writing this line into your rc.conf(5) directly.
                    153: 
                    154: You can also run this to start Apache immediately:
                    155: 
                    156:     # /etc/rc.d/apache start
                    157:     Starting apache.
                    158: 
                    159: or:
                    160: 
                    161:     # apachectl start
                    162: 
                    163: To see whether the server is started successfully, you can visit 
                    164: `http://127.0.0.1`. The dafault page is:
                    165: 
                    166:     <html><body><h1>It works!</h1></body></html>
                    167: 
                    168: Another way to check the daemon status:
                    169: 
                    170:     # /etc/rc.d/apache status
                    171:     apache is running as pid 1574.
                    172: 
                    173: Note: Since version 2.0, Apache doesn't support `inetd` operation mode anymore. 
                    174: Running Apache with `inetd` is not supported.
                    175: 
                    176: ### Configuration
                    177: 
                    178: Apache has lots of features, so it uses a configuration 
                    179: file(`/usr/pkg/etc/httpd/httpd.conf`). The general structure of this document 
                    180: is:
                    181: 
                    182:     KEY VALUES
                    183:     <DIRECTORY VALUES>
                    184:        KEY VALUES
                    185:     </DIRECTORY>
                    186: 
                    187: Here are the frequently used options:
                    188: 
                    189:  * `DocumentRoot "WEB_ROOT"` The directory out of which you will serve your 
                    190:    documents. By default, all requests are taken from this directory.
                    191: 
                    192:  * `ErrorDocument ERROR_CODE RESULT` Customizable error responses: the 
                    193:    `ERROR_CODE` can be 404 / 403 / etc, the `RESULT` can be a URL or a plain 
                    194:    text message.
                    195: 
                    196:  * `ServerAdmin MAIL_ADDRESS` The address to which problems with the server 
                    197:    should be emailed. This address appears on some server-generated pages, such 
                    198:    as error documents.
                    199: 
                    200: To check the syntax, you may run:
                    201: 
                    202:     NetBSD# apachectl configtest
                    203:     Syntax OK
                    204: 
                    205: #### DSO
                    206: 
                    207: Apache is a modular program where the administrator can choose the functionality 
                    208: to include in the server by selecting a set of modules (DSO). Apache's DSOs are 
                    209: located in `/usr/pkg/lib/httpd`. 
                    210: 
                    211:     # cd /usr/pkg/lib/httpd
                    212:     # ls
                    213:     httpd.exp                   mod_authz_owner.so          mod_ext_filter.so           mod_mpm_worker.so           mod_session_cookie.so
                    214:     mod_access_compat.so        mod_authz_user.so           mod_file_cache.so           mod_negotiation.so          mod_session_dbd.so
                    215:     mod_actions.so              mod_autoindex.so            mod_filter.so               mod_proxy.so                mod_setenvif.so
                    216:     mod_alias.so                mod_buffer.so               mod_headers.so              mod_proxy_ajp.so            mod_slotmem_plain.so
                    217:     mod_allowmethods.so         mod_cache.so                mod_heartbeat.so            mod_proxy_balancer.so       mod_slotmem_shm.so
                    218:     mod_asis.so                 mod_cache_disk.so           mod_heartmonitor.so         mod_proxy_connect.so        mod_socache_dbm.so
                    219:     mod_auth_basic.so           mod_cgid.so                 mod_include.so              mod_proxy_express.so        mod_socache_memcache.so
                    220:     mod_auth_digest.so          mod_charset_lite.so         mod_info.so                 mod_proxy_fcgi.so           mod_socache_shmcb.so
                    221:     mod_auth_form.so            mod_data.so                 mod_lbmethod_bybusyness.so  mod_proxy_fdpass.so         mod_speling.so
                    222:     mod_authn_anon.so           mod_dav.so                  mod_lbmethod_byrequests.so  mod_proxy_ftp.so            mod_ssl.so
                    223:     mod_authn_core.so           mod_dav_fs.so               mod_lbmethod_bytraffic.so   mod_proxy_http.so           mod_status.so
                    224:     mod_authn_dbd.so            mod_dav_lock.so             mod_lbmethod_heartbeat.so   mod_proxy_scgi.so           mod_substitute.so
                    225:     mod_authn_dbm.so            mod_dbd.so                  mod_log_config.so           mod_ratelimit.so            mod_unique_id.so
                    226:     mod_authn_file.so           mod_deflate.so              mod_log_debug.so            mod_reflector.so            mod_unixd.so
                    227:     mod_authn_socache.so        mod_dialup.so               mod_log_forensic.so         mod_remoteip.so             mod_userdir.so
                    228:     mod_authz_core.so           mod_dir.so                  mod_logio.so                mod_reqtimeout.so           mod_usertrack.so
                    229:     mod_authz_dbd.so            mod_dumpio.so               mod_mime.so                 mod_request.so              mod_version.so
                    230:     mod_authz_dbm.so            mod_echo.so                 mod_mime_magic.so           mod_rewrite.so              mod_vhost_alias.so
                    231:     mod_authz_groupfile.so      mod_env.so                  mod_mpm_event.so            mod_sed.so                  mod_watchdog.so
                    232:     mod_authz_host.so           mod_expires.so              mod_mpm_prefork.so          mod_session.so
                    233: 
                    234: Write `LoadModule MODULE FILENAME` in the configuration file, and the specific 
                    235: module will be loaded when Apache starts. You can also configure the module in 
                    236: this way:
                    237: 
                    238:     <IfModule MODULE>
                    239:        KEY VALUES
                    240:     </IfModule>
                    241: 
                    242: Run the following commands to apply the configuration:
                    243: 
                    244:     NetBSD# /etc/rc.d/apache reload
                    245: 
                    246: or:
                    247: 
                    248:     NetBSD# apachectl graceful
                    249: 
                    250: To get full manual, visit `/usr/pkg/share/httpd/manual`.
                    251: 
                    252: #### Run CGI
                    253: 
                    254: For security ressons, Apache doesn't permit executing CGI programs by default. 
                    255: Uncomment the following line to `httpd.conf` to permit Apache executing CGI:
                    256: 
                    257:     LoadModule cgid_module lib/httpd/mod_cgid.so
                    258: 
                    259: The next step is telling Apache which directory is set aside for CGI programs. 
                    260: Apache will assume that every file in this directory is a CGI program, and will 
                    261: attempt to execute it, when that particular resource is requested by a client.
                    262: 
                    263: The syntax is:
                    264: 
                    265:     ScriptAlias URL_PATH FILE_PATH_OR_DIRECTORY_PATH
                    266: 
                    267: For example:
                    268: 
                    269:     ScriptAlias /cgi-bin/ /usr/local/apache2/cgi-bin/
                    270: 
                    271: The CGI programs should be given executing permission. Modify the permission in 
                    272: this way:
                    273: 
                    274:     chmod a+x CGI_FILE_PATH
                    275: 
                    276: #### Run PHP
                    277: 
                    278: The PHP module is not included by default. Run the following command to obtain 
                    279: the Apache module (or its pkgin and pkgsrc equivalents).
                    280: 
                    281:     # pkg_add -v "ap24-php5*"
                    282: 
                    283: You should load the PHP module in `httpd.conf`. Append the following lines to 
                    284: `httpd.conf`:
                    285: 
                    286:     LoadModule php5_module lib/httpd/mod_php5.so
                    287:     AddHandler application/x-httpd-php .php
                    288: 
                    289: Maybe you want `.php` instead of `.html` to be your default page. You may append 
                    290: the following line:
                    291: 
                    292:     DirectoryIndex index.php index.html
                    293: 
                    294: You can write the following lines as a php file and visit it to check whether 
                    295: PHP works correctly. Don't forget to reload the configuration before testing.
                    296: 
                    297:     <?php phpinfo(); ?>
                    298: 
                    299: If you want to configure PHP, use the following syntax:
                    300: 
                    301:     <IfModule mod_php5.c>
                    302:        php_value NAME VALUE
                    303:        php_flag NAME on|off
                    304:        php_admin_value NAME VALUE
                    305:        php_admin_flag NAME on|off
                    306:     </IfModule>
                    307: 
                    308: #### Further reading
                    309: 
                    310: You should also have a look at the excellent online documentation of Apache: 
                    311: <http://httpd.apache.org/docs/>

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