admin-install - NaviServer Installation Guide
NaviServer is distributed in source form.
NaviServer is reasonably portable and known to compile and run on the following platforms:
Linux 2.2 and better (x86 and others)
FreeBSD 3.4 and better (x86 and others)
OpenBSD 2.5 and better (x86 and others)
Solaris 2.x and better (SPARC and x86)
OpenSolaris (OmniOS, OpenIndiana)
IRIX 6.x (mips)
HP/UX 10 and 11 (hppa)
DEC Tru64 & OSF/1 4.0 and better (alpha)
UnixWare 7.x and better (x86)
Apple OS/X "Darwin"
It's likely NaviServer can compile on other systems and/or higher or lower numbered versions but this has not been extensively tested. The primary development platforms for NaviServer is Linux.
You will need a C compiler. The best one to use is GNU GCC from http://www.gnu.org and its mirrors or clang. NaviServer (and the included Tcl libraries) are written entirely in ANSI standard C.
GNU make is also required. It is also available from the GNU web site.
Released versions are available from SourceForge Download area
Latest development version is available from Mercurial repository
hg clone http://bitbucket.org/naviserver/naviserver cd naviserver ./autogen.sh make install
We've tried to make building NaviServer as simple as possible. On the supported platforms, simply type:
./configure make
Some modules use third-party libraries. If the library is missing, the NaviServer build will continue without error -- it just will not build the offending module.
Note: If you have any problems building, the two files include/Makefile.global and include/Makefile.module have all the information you need to change settings throughout the NaviServer environment.
Two options to configure.sh script worth noting:
--enable-symbols to enable debugging information to be compiled in for easy debugging, otherwise it will be compiled with optimization enabled and that will prevent from effective troubleshooting in case of server crash
Type "make install" to make a production server. This will create an installation directory at /usr/local/ns/, populate the directories with various startup files and configuration files, copy the binaries to the /usr/local/ns/bin directory, and finish. To install confidence tests, type "make install-tests" and they will appear in the tests/ directory of your server's pageroot. The default location for installations can be overridden by typing "gmake install PREFIX=/your/directory/".
To download and install additional modules:
hg clone http://bitbucket.org/naviserver/modulename cd modulename make install
The steps above assume, that NaviServer is installed at the standard place at /usr/local/ns/. If this is not the case in your installation, please provide the location to make via parameter NAVISERVER.
make NAVISERVER=PATH_TO_LOCATION install
At this moment the following modules are available:
nsaccess nsclamav nsdbi nsdbmysql nsdhcpd nsicmp nsmemcache nssip nsstats nsvfs nsaspell nsconf nsdbilite nsdbpg nsdns nsimap nsphp nssmtpd nssyslogd nszlib nsauthpam nsconfigrw nsdbimy nsdbsqlite nsexpat nsldapd nsradiusd nssnmp nstftpd nschartdir nsdbbdb nsdbipg nsdbtds nsgdchart nsloopctl nsrtsp nsssl nsoracle nsudp
To check what modules are available go to http://bitbucket.org/naviserver/.
Some of the modules have external dependencies such as include directories or paths to libraries, so please look into module's README file for any additional information.
The installation directory contains several configuration files under /usr/local/ns/conf installation directory. A simple configuration to start with is nsd-config.tcl, which is used below. A more complete reference of the available parameter is sample-config, a very short configuration file is simple-config.tcl. The most basic configuration parameters are the port and listening addresses, which are set in nsd-config.tcl as follows:
Listen for HTTP connections on your computer's primary interface at port 8080. To use another port and/or select interfaces, you can set the port and address parameters. For details how to configure the networking setup of NaviServer, see nssock (for HTTP) and nsssl (for HTTPS).
Check security settings for nscp (Control Port module) and listen on localhost:4080 if they are set.
Note: Some modules can be disabled in the sample nsd.tcl for security reasons. They are nscp and nsperm. These modules can be disables by e.g. commenting out the respective lines in the "ns/server/default/modules" section. These modules are not required to run a server unless you want to use the Control Port and/or the Permissions module, respectively. Before using them in a production environment, change the passwords and default permissions by following the instructions in the NaviServer documentation.
Although you must be root to start NaviServer on port 80, the server itself must change to a regular user shortly after initialization. You either need to start the server as a non-root user (in which case you will not be able to listen for connections on privileged ports such as port 80) or you must include a -u user command line flag to which the server will setuid(2) after startup. We assume in the following sections that a user nsadmin and a group nsadmin were already created on the system, where NaviServer is installed.
If NaviServer was installed with default nsd.tcl config file, just type
/usr/local/ns/bin/nsd
and it will be started in the background listening on port 8080.
You may either specify a Unix username or numeric uid, e.g.:
bin/nsd -t conf/nsd-config.tcl -u nsadmin
For the mode of operation, there are four choices: Foreground, Background, Background with watchdog and Inittab.
Foreground mode:
bin/nsd -f -t conf/nsd-config.tcl -u nsadmin-g nsadmin
In Foreground mode , the server starts and emits diagnostic log messages directly to the terminal window. This is useful for testing, configuration or debugging a server. To start the server in foreground mode use:
To stop a server running the foreground simply press interrupt on your keyboard (e.g., ctrl-c or the DEL key) which will send a SIGINT to the server and initiate shutdown.
Background mode:
bin/nsd -t conf/nsd-config.tcl -u nsadmin-g nsadmin
In Background mode, the server forks and disassociates from the terminal. Diagnostic messages are appended to log/server.log. This is a typical daemon-style mode of operation. To start the server in background mode use:
To stop a server running the background you may either use the kill(2) command to send a SIGTERM to the background process id(*) or the special -K flag of the nsd binary. This flag will determine the process id from a special marker file, send the signal and wait for shutdown, e.g.:
Background mode with built-in watchdog:
/usr/local/ns/bin/nsd -w -t /usr/local/ns/nsd-config.tcl -u nsadmin -g nsadmin
In Watchdog mode, the server is restarted automatically when it crashes independent from the respawn support from the operating system.
Inittab mode (non-forking mode):
w1:23:respawn:/usr/local/ns/bin/nsd -i -t /usr/local/ns/nsd-config.tcl -u nsadmin -g nsadmin
In Inittab mode, the server runs in the foreground but opens the log file as with background mode. This mode is used when the server is started from an entry in the "/etc/inittab" file. The benefit of this mode is that init will restart the server automatically.
Furthermore, the inittab mode is needed as well on macOS when NaviServer is started via launchd (controlled via launchctl).
Note: While running NaviServer on some Unix platforms (e.g., Linux, SGI), you'll notice multiple nsd processes. This is normal and represents the individual threads. The main process id can be determined by checking the log/nsd.pid file or looking at the last few entries of the server log (per default "logs/error.log", each of which will include the process id and thread id in the form [pid.tid]. You can also telnet to the control port and type "ns_info pid".