FAQ

Download

Client Install

Server Install

Help Docs

Neolectric

DataView Server Setup

The DataView Client can connect to the demo server listed in the client download. If you want to connect to your own server there are 4 components required.

  1. Webserver - example below will use Apache
  2. Servlet Runner - example below will use Apache Tomcat
  3. DataView servlet and supporting classes - dataview-version-server.jar
  4. MySQL or similar database with JDBC connectors

The Tomcat servlet runner can act as a standalone webserver but I prefer to use Apache as the webserver and use an Apache module to connect to Tomcat. This allows Apache to do what it's really good at: deliver static files; encode/decode ssl; run other web frameworks like php; listen on port 80 (the standard http port) while running as a non-privileged user with no login privilege.

When you set up a Virtual Host directory structure you should think about who owns the files and what the file and directory permissions are should be. There are 3 user accounts and 1 group to consider:

  1. User nobody to run Apache - this account is probably on your system by default
  2. User tomcat to run Tomcat - or some other admin account that is not root
  3. A user account for the webmaster of each virtual host - I'll use host in this example
  4. A group that contains nobody and tomcat. I'll call the group webuser

These user accounts must exist on your system and are normally stored in /etc/password and /etc/group. Some systems use an ldap or nis server instead.

Apache is started by user root but switches to user nobody when running. Starting as root allows it to listen on port 80, the standard http port. Don't run Tomcat on port 80 as root because it does now switch to a safe user.

The user and group Apache runs under is specified in the file httpd.conf. If you installed apache from rpm this will probably be in /etc/httpd/conf and your web docs may be in /var/www. If you compiled from src and used the traditional apache layout it will be in /usr/local/apache/conf with docs in /home/username/public_html or /home/username/htdocs.

You may want to restrict the type of shell that the host account can login with. A common practice is to use /sbin/nologin which allows the user to upload via ftp but not get a shell. A better method is to create a chroot "jail" directory and use the rssh shell and restrict the webmaster to using sftp for uploads. Do a google search on rssh and filezilla (an sftp client) for details.

Now we'll setup a directory that contains web files for hostname.com and set permissions to restrict certain directories to the desired users. You can copy this section to create your own setup script. Just change the name of the host and run it as root. 

#!/bin/bash

# create a dir structure for a website that the host webmaster can update
mkdir /home/host
mkdir /home/host/htdocs
mkdir /home/host/htdocs/error
mkdir /home/host/htdocs/WEB-INF
mkdir /home/host/prop
mkdir /home/host/logs

# restrict /home/host to host and webuser (group for apache and tomcat)
chown host:webuser /home/host
chmod o-wrx /home/host

# restrict prop to tomcat
chown tomcat:tomcat /home/host/prop
chmod o-wrx /home/host/prop

# give ownership of htdocs and error to host so the webmaster can update
chown host:webuser /home/host/htdocs
chown host:webuser /home/host/htdocs/error

# restrict WEB-INF to tomcat
chown tomcat:tomcat /home/host/htdocs/WEB-INF
chmod o-wrx /home/host/htdocs/WEB-INF

Next, we'll modify the main Apache config file httpd.conf to set up a Virtual Host for hostname.com that tells apache which IP address this host belongs to, it's names and where to look for web files and error pages. You may want to tweak the Options inside htdocs for your setup. 

file: /usr/local/apache/conf/httd.conf 
(perhaps /etc/httpd/conf/httpd.conf if you installed from rpm)

# put in the IP address here
NameVirtualHost xxx.xxx.xxx.xxx.

<VirtualHost xxx.xxx.xxx.xxx>
 ServerName hostname.com
 ServerAlias www.hostname.com
 ServerAdmin admin@hostname.com
 DocumentRoot /home/host/htdocs
 ErrorLog /home/host/log/error_log
 ErrorDocument 401 /error/notauthorized.html
 ErrorDocument 403 /error/forbidden.html
 ErrorDocument 404 /error/notfound.html
 ErrorDocument 500 /error/internalerr.html
 ErrorDocument 503 /error/unavailable.html
 CustomLog /home/host/log/access_log common
 <Directory "/home/host/htdocs">
    Options FollowSymLinks
    AllowOverride AuthConfig
 </Directory>
 <Location /WEB-INF/ >
    AllowOverride None
    deny from all
 </Location>
</VirtualHost>

When Apache starts up it loads various modules. You can tell Apache to pass requests for certain file types and file paths to Tomcat using the jk2 module. First you need to download and compile it. See the download page for location. Then you need to modify the main apache config file httpd.conf to load it. 

LoadModule jk2_module modules/mod_jk2.so
The jk2_module will look for the file workers2.properties in the same directory as httd.conf. Here is a sample that is set to pass requests for /dataview to Tomcat.

file: /usr/local/apache/conf/workers2.properties
(perhaps /etc/httpd/conf/workers2.properties if you installed apache from rpm)

# A minimal JK2 connector configuration file to pass .dxp requests to Tomcat
[logger]
info=Native logger
level=ERROR

[config:]
file=${serverRoot}/conf/workers2.properties
debug=0
debugEnv=0

[uriMap:]
info=Maps the requests.
debug=0

[shm:]
info=Scoreboard. Required for reconfiguration and status with multiprocess servers
file=anonymous
debug=0

[workerEnv:]
info=Global server options
timing=0
debug=0

[lb:lb]
info=Default load balancer.
debug=0

[channel.socket:localhost:8009]
info=Ajp13 forwarding over socket
debug=0
tomcatId=localhost:8009

# pass requests for /dataview to Tomcat
[uri:/dataview]
info=dataview servlet
debug=0

# ucomment if you run .jsp pages
# [uri:/*.jsp]
# info=jsp servlet
# debug=0

This document was written for Tomcat version 5 which was downloaded as jakarta-tomcat-5.x.tar.gz where x denotes minor version numbers. I extract this to /usr/local and created a symlink called tomcat.

cd /usr/local
ln -s jakarta-tomcat-5.x tomcat

These jar files contain classes required by the DataView servlet.

mysql-connector-java-3.x.x-production-bin.jar
xercesImpl.jar
datview-version-server.jar

See the download page to get them. Put them in /usr/local/tomcat/shared so tomcat can find them. Make sure you have MySQL installed with the required tables and user accounts before you start Tomcat or you will get errors when the ContextServlet tries to create a database pool. The Help file docs/advanced-localdb.html has information on creating MySQL user accounts in MySQL.

When Tomcat starts up it reads the file /usr/local/tomcat/conf/server.xml to find out what you want it to do. Here is an example that loads an application zone for the Virtual Host: hostname.com. It tells Tomcat to listen for connections from an Apache module on port 8009 and pass all requests to hostname.com. All the tomcat example apps have been removed for clarity.

file: $TOMCAT_HOME/conf/server.xml

<Server port="8005" shutdown="SHUTDOWN">
  <Service name="Catalina">
  	
  <!-- Define a Coyote/JK2 AJP 1.3 Connector (for apache) on port 8009 -->
  <Connector port="8009" enableLookups="false"
   redirectPort="8443" debug="0" protocol="AJP/1.3" />
			   
  <Engine name="Catalina" defaultHost="hostname.com" debug="4">
   <Logger className="org.apache.catalina.logger.FileLogger" />

   <!-- hostname.com host -->
   <Host name="hostname.com" debug="4" appBase="/home/host/htdocs"
    autoDeploy="false" xmlValidation="false" xmlNamespaceAware="true">
    <Alias>www.hostname.com</Alias>
    <Context path="" docBase="/home/host/htdocs" debug="0" reloadable="false"/>
   </Host>
	  
  </Engine>
 </Service>
</Server>

Based on the path you specified for appBase and docBase in server.xml above, Tomcat will look for a a file called web.xml in each Virtual Host that tells it which servlets to load for each host. For hostname.com the config files will be /home/host/htdocs/WEB-INF/web.xml.

For safety we told Apache to stay out of this directory in httpd.conf.

<Location /WEB-INF/ >
  AllowOverride None
  deny from all
</Location>

We also made this directory readable only by the tomcat user so a webmaster can't change it. Here's a sample web.xml file for hostname.com. It tells Tomcat to load a ContextServlet and a DvServlet (aka DataView server).

file: /home/host/htdocs/WEB-INF/web.xml
<?xml version="1.0" encoding="ISO-8859-1"?>

<!-- Servlet config file ready by Tomcat for hostname.com.
 Tomcat expects this file to be stored in the filepath docBase/WEB-INF/web.xml
 where docBase is defined for each hostname in $TOMCAT_HOME/conf/server.xml.
 Look in my server.xml file for each Host tag and it's nested Context tag
 that defines the docBase. I normally use a docBase /home/hostname/htdocs
 to match the DocumentRoot I set for the corresponding Apache VirtualHost. -->

<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
    version="2.4">

 <servlet> <!-- ContextServlet loads service classes into this host's ServletContext -->
  <servlet-name>ctxtservlet</servlet-name>
  <servlet-class>com.neolectric.servlet.ContextServlet</servlet-class>
  <init-param> <!-- file that describes service classes -->
   <param-name>contextFile</param-name>
   <param-value>/home/host/prop/context.xml</param-value>
  </init-param>
  <init-param> <!-- xml parser that reads config values -->
   <param-name>parser</param-name>
   <param-value>org.apache.xerces.parsers.SAXParser</param-value>
  </init-param>
  <load-on-startup>1</load-on-startup> <!-- load this servlet first --> 
 </servlet>
	
 <servlet> <!-- Servlet responds to DataView client -->
  <servlet-name>dvservlet</servlet-name>
  <servlet-class>com.neolectric.servlet.DvServlet</servlet-class>
  <init-param>
   <param-name>maxRead</param-name>
   <param-value>1048576</param-value> <!-- 1MB tranlated to bytes -->
  </init-param>
  <init-param>
   <param-name>docRoot</param-name>
   <param-value>/home/host/htdocs/</param-value>
  </init-param>
  <init-param>
   <param-name>userTable</param-name>
   <param-value>dvusers</param-value>
  </init-param>
  <init-param>
   <param-name>excludeDb</param-name> <!-- comma delim list of db pools to exclude -->
   <param-value>secretdb,stuffdb</param-value>
  </init-param>
  <init-param>
   <param-name>debug</param-name>
   <param-value>true</param-value>
  </init-param>
  <init-param>
   <param-name>saxParser</param-name>
   <param-value>org.apache.xerces.parsers.SAXParser</param-value>
  </init-param>
 </servlet>
 <servlet-mapping> <!-- map urls passed by mod_jk2 -->
  <servlet-name>dvservlet</servlet-name> 
  <url-pattern>/dataview</url-pattern> 
 </servlet-mapping>
 
 <!-- docs (relative to host docroot) returned by servlet runner for various http errors -->
 <error-page>
  <error-code>401</error-code>
  <location>/error/notauthorized.html</location>
 </error-page>
 <error-page>
  <error-code>403</error-code>
  <location>/error/forbidden.html</location>
 </error-page>
 <error-page>
  <error-code>404</error-code>
  <location>/error/notfound.html</location>
 </error-page>
 <error-page>
  <error-code>500</error-code>
  <location>/error/internalerr.html</location>
 </error-page>
 <error-page>
  <error-code>503</error-code>
  <location>/error/unavailable.html</location>
 </error-page>
	
</web-app>

Note that the <load-on-startup> parameter for the ContextServlet is set to 1 while the value for the DxpServlet is 2. This tells Tomcat to load the ContextServlet first so it can create and store service classes required by the DxpServlet and similar servlets.

The ContexServlet is a custom servlet and has an <init-param> called contextFile, normally called context.xml, that lists the services to load and their parameters. IMPORTANT: this file contains sensitive information and should only be readable by tomcat. At the beginning of this document we created a directory called /home/host/prop and set the permission so that only tomcat could get in. This is outside the docBase that tomcat uses and is a good place to store context.xml. For additional security you can make this file read-only.

file: /home/host/prop/context.xml

<?xml version='1.0' encoding='utf-8'?>

 <!-- This file is read by the ContextServlet to load service 
 classes that are used in this Virtual Host. It contains sensitive
 information and should be stored outside the directory path that
 Apache or Tomcat serve pages from.
 -->
<context name="hostname.com"> 
 
 <!-- Load pools of database connections in this host zone.
  Do this before other services that depend on connections.
  You can load multiple pools but each must have a unique name.
 -->
 <DbService class="com.neolectric.dbutil.DbService">
  <pool>
   <name>host</name>            <!-- named used by DbService to store this connection pool -->
   <driver>org.gjt.mm.mysql.Driver</driver>
   <connections>4</connections> <!-- how many active connections to open -->
   <queue>4</queue>             <!-- how many request can wait for a free connection -->
   <ping>select 1</ping>        <!-- sql stmt used to see if a connection is live -->
   <user>bozo</user>	        <!-- user stored in database permission table -->
   <password>xxxxxxxx</password><!-- 8 char password -->
   <url>jdbc:mysql://host_or_ipaddr:3306/dbname</url> <!-- connection to database server -->
  </pool>
 </DbService>
 
</context>

The context file may contain other services. Only the DbService is shown in this example.