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

1.1     ! jdf         1: **Contents**
        !             2: 
        !             3: [[!toc]]
        !             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:     ===========================================================================
        !           127:     $NetBSD: MESSAGE,v 1.1 2012/08/26 12:37:34 ryoon Exp $
        !           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