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 (6 years, 11 months ago) by jdf
Branches: MAIN
CVS tags: HEAD
Add more levels to the TOC.

    1: **Contents**
    2: 
    3: [[!toc levels=4]]
    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: how_to_setup_a_webserver.mdwn,v 1.2 2013/03/14 23:44:47 jdf 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