Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
NHTTPD(8)		FreeBSD	System Manager's Manual		     NHTTPD(8)

     nhttpd -- Nostromo	webserver

     nhttpd [-dhvr46] [-c configfile]

     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.

     -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, nostromo/conf/nhttpd.conf will be used by default.

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


     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	cre-
     dentials 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.

     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 un-
     der 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.

     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 frame-
     work.  To do that,	set the	+bsdauth keyword in the	htpasswd option	in-
     stead of a	filename.  You are then	able to	authenticate via your operat-
     ing system	users.	Be aware that +bsdauth requires	a SSL connection to
     work, because you normally	don't want to send your	operating system pass-
     word 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 op-
     tion.  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.

     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 se-
     cure HTTPS	connections.

     If	an error response occurs the server will normally send a default an-
     swer 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 re-
     sponse is defined but the corresponding html file is not found, the de-
     fault response will be send.  Supported custom responses are:

	   401 Unauthorized
	   403 Forbidden
	   404 Not Found

     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 nostromo/icons

     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:	    nostromo/htdocs/ nostromo/htdocs/

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

     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:

     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

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

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

     First version of nhttpd appeared in 2004.

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

     Marcus Glocker <>

FreeBSD	13.0			 Apr 10, 2016			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help