Quick Reference for Administrators, Release 2.0

General Information

The Neokernel Web Server executable is neokernel.exe; by default, it is installed to the folder c:\program files\cometway\neokernel\. The server can be started using the shortcut in the Start menu, by double-clicking the executable, or by running the application from a command prompt.

If you start neokernel.exe without changing any configuration parameters, you can connect to the server by browsing to the URL http://localhost/. The file index.htm and other static files are in the \html subdirectory of the application directory. The console will display server status information, and NCSA-Extended format HTTP log files are output to the \logs subdirectory of the application directory.

The nkservice.exe executable in the application directory is used to run the Neokernel as a Windows Service. It can be started from the Services control panel. When running as a service, significant events and errors appear in the Neokernel Events event log, which is accessible from the Event Viewer in the Windows Management Console.

Both the neokernel.exe executable and the nkservice.exe service application support the following command line syntax:

neokernel [-hide_println] [-hide_debug] [-hide_warning] [-startup_dir <dir>] [-startup_file <.xml startup file>]

-startup_dir <dir>	Where <dir> is the path to the directory that neokernel.exe should use as a startup directory.
-startup_file <file>	Where <file> is the path to an xml props file that neokernel.exe should use as the startup file. If no file is specified, the server looks in the application directory for a file called neokernel_props.xml to use as the startup file.
hide_println	If this prop is set to true, all println() output from this kernel is hidden. The default value is false.
hide_debug	If this prop is set to true, all debug output from this kernel is hidden. The default value is false.
hide_warning	If this prop is set to true, all warning output for this kernel is hidden. The default value is false.

Table 1: Command Line Parameters

Server Logs

The server generates log files that record server processes and client requests. By default, HTTP log files are generated in a subdirectory of the startup directory called /logs. This directory will be created if it doesn’t exist. The http log files conform to the NCSA Common Log File formatting conventions.

By default, all other program output gets routed to the console. If you need to store the console output in log files, look in the neokernel_props.xml file for the FileReporterAgent section and set the startup prop of this agent to true. This agent will log all console output to files in the /logs subdirectory of the server’s working directory, or if the Neokernel can’t write to the directory, the logs will appear in the CommonAppDataPath (on Windows 2003 and earlier, this will be c:\Documents and Settings\Application Data\Comet Way, Inc.\Neokernel\

Running the Neokernel as a Windows Service

The nkservice.exe is for running the Neokernel as a Windows Service. The installer registers this executable as a windows service so it can be controlled using the Services control panel. When running as a windows service, the Neokernel writes console output to sequentially numbered files in the /logs directory. Errors and other significant events appear in the event log, viewable using the Event Viewer[1]. The Neokernel service supports the same command line arguments as the Neokernel console executable.

Configuring Server Properties (Props)

Most server behavior is configurable by editing the neokernel_props.xml file. This file is divided into sections corresponding to the components that the server will load at startup. Each section defines a set of properties (Props[2]) used to configure that component. Neokernel components are called agents, and include agents for authenticating users with HTTP-Basic authentication, serving HTML or other static files, proxy services, and redirection.

If you define a value for a prop in the neokernel_props.xml file, the agent will use that value. Default values are used if the prop isn’t specified. The /demos directory has examples of different server configurations with neokernel_props.xml files that can be used as templates for your own configurations.

Other files are also used for configuring server behavior. The following table describes each of these files[3].

File Name	Purpose
neokernel_props.xml	The file with configuration parameters for the agents that the server will load. Here is an example of a very simple neokernel_props.xml file: <?xml version="1.0"?> <props_list> <props> <agent_id>100</agent_id> <classname>AgentOne</classname> <startup>true</startup> </props> <props> <agent_id>101</agent_id> <classname>AgentTwo</classname> <startup>true</startup> </props> </props_list> </xml>
authmap	If the HTTPAuthenticationAgent is running, it uses this file to determine what directories on the server require authentication. The file must contain the names of each secured directory, or realm, and the username / password combinations that are allowed to access that realm. The authentication map file must be in this format: default PATH0 REALM0 username0 password0 PATH1 REALM2 username0 password0 username1 password1 Here is an example of an authentication file: default /private/mine/ My Realm john johnpassword santos halper /private/ Main Realm john mainpassword If the above example is used as the authentication map file, attempts to access http://hostname/private/mine/ will be prompted for a username and password (the prompt will ask for the password to My Realm). If you want to password protect an agent-generated page, set the agent’s service_name so it includes the protected realm (directory) in it’s URL. The default keyword at the start of the example means that the realms apply to ALL domains that this server handles. If you want a realm to apply only to a certain domain, replace the default keyword with the hostname of the domain you want. Multiple domains may be listed in a single authentication map file, as in the following example: www.myserver.com /private/mine/ My Realm john johnpassword santos halper www.myotherserver.com /private/ Main Realm john mainpassword
redirect	If the HTTPRedirectAgent is running, it uses this file to determine what requests should be redirected and where they should be redirected to. Here is an example of a redirect file: http://myserver/redir1/file.htm=http://yahoo.com/ http://myserver/redir2/=http://redirect1:9000/ http://myserver/redir2/==http://redirect2:9000/ http://myserver/redir2/==http://redirect3:9000/ When a browser requests /redir1/file.html, it is redirected to http://yahoo.com. When it requests /redir2, it is redirected to http://redirect1:9000/. The next request for /redir2 is redirected to http://redirect2:9000/. The third incoming request is redirected to http://redirect3:9000/. The fourth request is redirected to http://redirect1:9000/, and the cycle is started again. In this way, the HTTPRedirectAgent can be used for round-robin style load balancing. Complete URLs must be used to specify redirected URLs and the redirect targets.
proxy_hosts	If the HTTPProxyAgent is in use, this file provides the list of URLs that will be proxied instead of being handled normally by the Web Server. Here is an example of a proxy file: http://myserver/proxy_me=http://proxy:1099 http://myserver/proxy_me2=http://proxy1:9000 http://myserver/proxy_me2=http://proxy2:9000 http://myserver/proxy_me2=http://proxy3:9000 When a browser requests /proxy_me, the WebServer gives the request to the HTTPProxyAgent to handle. The HTTPProxyAgent contacts the web server at proxy on port 1099 and proxies the request to that server. When a browser requests /proxy_me_too, the HTTPProxyAgent will cycle through the 3 web servers indicated, so that the first time the URL is accessed, the connection is proxied to proxy1, port 9000. The second time, the request is proxied to proxy2, the third request goes to proxy3, the fourth request goes to proxy1, and so on. The HTTPProxyAgent also supports listeners, which can proxy all HTTP or HTTPS traffic instead of specific URLs. Listeners are used when you want to provide a proxy for HTTP browsers like Internet Explorer; they are configured to listen on a specific port and IP number, and are specified using the listener prop of the HTTPProxyAgent. For more information, see page 15.
mime_types	This file describes what MIME types the server should use when sending browsers a file with a specific file extension. If a mime_types file isn’t found, a default set of common MIME types is used.
log_maps	The LogViewerPage provides a web interface for viewing summary information from the web server’s log files. If it is running, the log_maps file defines the reports that the LogViewerPage generates. This file should contain names mapped to text patterns. For example, a map file might look like this: Total requests=GET LogViewer requests=GET /logviewer.agent In the above example, LogViewerPage will let the user select from 2 fields, Total requests and LogViewer requests. If the user chooses the report called Total requests, all log entries that match the pattern ‘GET’ will be counted and included in the report. If the user chooses to view the report called LogViewer requests, a smaller set of entries (that match the pattern ‘GET /logviewer.agent’) will be included in the second report. The search patterns used to filter the reports can be regular expressions.

Table 1 – Server configuration files.

[1] The Event Viewer is in the System Tools section of the Computer Management console, accessible by right-clicking on My Computer and selecting Manage.

[2] The properties of Neokernel agents are referred to as props because the object com.neokernel.props.Props is used to represent them in the API and to differentiate them from other properties.

[3] The table shows the default filenames; you can change these filenames by editing the neokernel_props.xml file to change the path where the corresponding agents look for their configuration file.