NHTTPD(8)                   System Manager's Manual                  NHTTPD(8)

NAME
     nhttpd - Nostromo webserver

SYNOPSIS
     nhttpd [-dhvr46] [-c configfile]

DESCRIPTION
     nhttpd is a simple, fast and secure HTTP server.  It runs as a single
     process, handling connections with select(2).  For CGIs and directory
     listing it does fork(2).  nhttpd has the minimum of HTTP/1.1 and CGI/1.1
     implemented.  Also supported are; chroot, setuid, basic authentication,
     SSL, IPv6, custom responses, aliases, and virtual hosts.  To stop the
     server send a SIGTERM signal to the PID.  The access log is written in
     standard CLF format.

     After changes in the configfile, nhttpd needs to be restarted, except for
     changes of the parameters described in the CONFIGURATION RELOAD section.

     CGIs are recognized by the file world executable flag.  If it is set, the
     file is handled as CGI and will be executed.  Therefore it is possible to
     use a CGI as index naming it like defined by the docindex option.
     Whether a file or directory is accessible by nhttpd is decided by its
     world readable flag.  If it is not set on a file or directory, it can't
     be accessed and a 403 Forbidden response will be sent.

OPTIONS
     -d      Enable debug mode.  More informations about ongoing processes are
             written to the syslog(3) LOG_DAEMON facility.  Be careful, the
             logs will grow very quickly in debug mode.

     -h      Prints short listing of nhttpd options.

     -v      Prints version.

     -r      nhttpd will chroot(2) to serverroot.  If you use this option, you
             have to change docroot, virtual hosts, and aliases in configfile
             to paths within your serverroot.

     -4      Enable IPv4 and IPv6.

     -6      Enable IPv6 only.

     -c configfile
             Uses configfile as configuration file.  If this option is not
             set, /var/nostromo/conf/nhttpd.conf will be used by default.

CONFIGURATION RELOAD
     Parts of the configuration can be reloaded by sending a SIGHUP signal to
     the PID.  Those are the following configfile parameters for which
     configuration reload works:

           logaccess
           htaccess
           custom_401
           custom_403
           custom_404
           homedirs
           homedirs_public

     For changes in the configfile sections ALIASES and VIRTUAL HOSTS no
     reload is required at all.  All other parameter changes require a full
     restart of the nhttpd process to get effective.

     What also happens during a SIGHUP is that the basic authentication
     credentials cache gets cleared.  This can be useful if you have set a new
     user password and want to have it effective immediately instead of giving
     a user the ability to still login with the old, cached password.

SETUID
     For security reasons it is recommended to run nhttpd under an extra user.
     To do that create a new user on your system which has a valid entry in
     the /etc/passwd file.  Then set the user option in your configfile to
     that user.  It is necessary to start nhttpd as root, so it can switch to
     that user afterwards.  If the user option is not set, nhttpd will run
     under the user who started it, except root!

     Be sure that the permissions on your docroot are set correct, as nhttpd
     needs write permissions at least on the logs directory.

BASIC AUTHENTICATION
     To ask for basic authentication on certain directories within your
     docroot you have to create a file in that directory named like set by the
     htaccess option in your configfile.  The htaccess file should contain one
     line including the realm option like in this example:

           realm Unix Developers Realm

     If the realm option can not be parsed from the htaccess file, it will be
     set to a default value saying 'unknown realm'.

     The list of authorized users and their passwords (DES encrypted) are
     stored in the file set by the htpasswd option in configfile.  To create a
     new user entry in this file, use the crypt tool.

     On BSD systems it is also possible to use the BSD authentication
     framework.  To do that, set the +bsdauth keyword in the htpasswd option
     instead of a filename.  You are then able to authenticate via your
     operating system users.  Be aware that +bsdauth requires a SSL connection
     to work, because you normally don't want to send your operating system
     password unencrypted over the network.  If this condition is not met, the
     caller receives a 403 Forbidden response directly.  You can allow none
     SSL connections to do BSD authentication by setting the +bsdauthnossl
     option.  Be sure that you really want that!

     Note: BSD authentication works just on OpenBSD for now.

     All subdirectories below the htaccess file are protected automatically.
     The client will be prompted for basic authentication if accessing such a
     protected directory.

SSL
     nhttpd uses the OpenSSL library, so be sure you have it installed on your
     system if you want to use SSL.  To activate SSL uncomment sslport which
     is the port where we will listen for SSL connections, sslcert which is
     the certificate file, and sslcertkey which is the certificate key file.
     If the certificate and the key are correct nhttpd will startup with a log
     entry for SSL activation in the log, otherwise it will complain and the
     startup is aborted.  After a successful startup we are able to handle
     secure HTTPS connections.

CUSTOM RESPONSES
     If an error response occurs the server will normally send a default
     answer saying for example 404 Not Found.  Instead of this default
     response, you can define your personal responses, using the custom
     response options in the configfile.  There you define an html file which
     will be displayed instead of the default response.

     The custom response html file will be searched in every defined docroot,
     what means in your default docroot and every virtual host.  So you can
     define different custom responses for each virtual host.  If a custom
     response is defined but the corresponding html file is not found, the
     default response will be send.  Supported custom responses are:

           401 Unauthorized
           403 Forbidden
           404 Not Found

ALIASES
     With aliases you can create a fake path which will point to a real path.
     For example, to let all links starting with /icons point to another path,
     just add the following line in your configfile:

           /icons /var/nostromo/icons

VIRTUAL HOSTS
     To serve virtual hosts, just add a line for each virtual host in
     configfile with the domain name as option and port if not 80, and the
     docroot of that virtual host, as in this example:

           www.rahel.ch     /var/nostromo/htdocs/www.rahel.ch
           www.nazgul.ch:81 /var/nostromo/htdocs/www.nazgul.ch

     For each virtual host a separate access_log is written automatically with
     the following syntax as example:

           access_log-www.rahel.ch
           access_log_www.nazgul.ch:81

HOMEDIRS
     To serve the home directories of your users via HTTP, enable the homedirs
     option by defining the path in where the home directories are stored,
     normally /home.  To access a users home directory enter a ~ in the URL
     followed by the home directory name like in this example:

           http://www.nazgul.ch/~hacki/

     The content of the home directory is handled exactly the same way as a
     directory in your document root.  If some users don't want that their
     home directory can be accessed via HTTP, they shall remove the world
     readable flag on their home directory and a caller will receive a 403
     Forbidden response.  Also, if basic authentication is enabled, a user can
     create an .htaccess file in his home directory and a caller will need to
     authenticate.

     You can restrict the access within the home directories to a single sub
     directory by defining it via the homedirs_public option.

FILES
     /var/nostromo/conf/nhttpd.conf  server configuration
     /var/nostromo/conf/mimes        mime types
     /var/nostromo/logs/nhttpd.pid   pid file
     /var/nostromo/logs/access_log   http log
     /usr/local/sbin/crypt           create user with DES password
     /usr/local/sbin/nhttpd          http daemon

HISTORY
     First version of nhttpd appeared in 2004.

THANKS
     Thanks to Marc Balmer, Daniel Hartmeier, Boris Meyer, and Wouter Schoot
     for their support.

AUTHORS
     Marcus Glocker 

OpenBSD 5.9                     April 10, 2016                     OpenBSD 5.9