County/Town Fusion as Windows Service

Service provides support for automatic execution of background activities such as compute-intensive tasks referred to as "daemons". Using Windows Service has the advantage of automatic start/stop as well as known, familiar mechanism for service control. For County/Town Fusion running as Windows Service you must consider the following:

When running service under a System account, the process environment is incomplete, for example having limited access to network drives, printers etc.
When running service under an explicit user account, network mounted drives require using network enabled account or service scripts mounting necessary drives.

County Service Operation

Windows service starts executable CountyServiceNN.exe, which executes a small Java application - service controller. This controller reads the CountyService.properties and launches (and monitors) CountyFusion instances using the GetDown mechanism (checking and updating application when needed). Each launched CountyFusion instance then executes specified ServiceCtrlTaskManual listening (responding) on a (local) socket specified by a port number. Failure to respond is interpreted as instance failure, and the launcher may re-start that particular instance. Upon service stop, the controller sends a 'stop' request to each monitored instance and then exits.

CountyFusion Service generates multiple log files:

CountyFusion/launcher.log - getdown log of the last instance started
logs/CountyServiceController.log - controller activities (instance start/status/stop)
logs/service_nn.log{.n} - main County/TownFusion log(s) written by CountyFusion instance
logs/countyfusion-stderr.YYYY-MM-DD.log - standard error written by Windows Service
logs/countyfusion-stdout.YYYY-MM-DD.log - standard output written by Windows Service
logs/CountyFusion.YYYY-MM-DD.log - standard output written by controller start

The main application operation log is file service_nn.log{.n}, remaining logs are used for service startup/exit troubleshooting.

County Service Configuration and Installation

County Service installation requires editing of (sample) CountyService.properties located in the launch (top, fusion) directory. It must contain site-specific parameters (see below).

Installation

Prior to service installation, please make sure that County/TownFusion and prescribed tasks can be started interactively. After updating fusion\CountyService.properties, use script below to install or remove the service. Depending upon context, installed service name will be either CountyFusion or TownFusion.

fusion\installWinService install {username} {password}
fusion\installWinService remove

Optional arguments {username} {password} may be used to make service log on as a specific users (such as an account with network drives access). Once installed, first time you must start service (CountyFusion or TownFusion) manually, using Windows Service Control panel.

CountyService.properties

This file defines parameters common to all launched CountyFusion instances.

Required Parameters:

domains={URL or path to the domains.xml file}
domain={domain name}
tasks={task}{,task}

Once started, each CountyFusion instance launched by the service controller executes one of system.ServiceCtrlTaskManual specified by the list of task={task}{,task}. Each such task (defined in table 'menus') monitors the daemon schedule (managed by Daemon Schedule Administration) and launches (or stops if necessary) daemons as specified for a given workstation (host name) and controller.
To see the task names, use the following query, where 'MenuText' is the task name, and AddlData shows the service identifier used to specify daemons in 'daemoninfo' (using Daemon Schedule Administration).

select MenuText, AddlData from menus where Classname like '%ServiceCtrlTaskManual%'

Alternatively, instead of specifying tasks={task}{,task} you may specify property services=N, where N presribes number of system.ServiceCtrlTask launched using identifier service_{nn} where nn=0,1...N.

Optional Parameters:

port=nnnn - starting service port, default=18004 (used to be 80004)
user={username} - CountyFusion user, default='service'
password={pwd} - required unless user=service
logdir=logs/ - log directory (relative to top 'fusion' directory)
script={filename or URL} - script to execute on instance start
getdownWait=300 - maximum time (sec) to wait for Getdown directory lock
launchTimeout=120 - max duration (sec) to wait for launched CountyFusion to respond
pingTimeout=120 - duration (sec) to wait for 'ping' response before assuming launched CountyFusion failed
stopTimeout=30 - duration (sec) to wait for 'stop' request response

The port=nnnn (default=18004) specifies port number used to communicate/control the first CountyFusion instance. When starting multiple instances, subsequent instances use subsequent port numbers (nnnn+1...).

BEWARE:The default port range may be in use by other Windows products. Before port allocation, please make sure that such port(s) are NOT in use, for example using command

$ netstat -n

Scripts

As a work-around the service mount and other problems, both CountyFusion main excutable and/or specific daemon(s) accept an argument -script={filename or URL} indicating a DOS batch script to execute. Such script may be used to mount network drives (for example see ServiceScript.bat).

County Fusion Instance Configuration

Once started, each CountyFusion instance launched by the service executes one of the tasks prescribed by property tasks={task}{,task}. Such tasks must be instances of system.ServiceCtrlTaskManual defined by table 'menus'. Each task watches the daemon schedule (managed by Daemon Schedule Administration), and launches (or stops if necessary) daemons specified for a given workstation (host name) and service instance dentifier (specified as task AddlData service=xxxx).
In case of not using tasks={task}{,task}, service instances will use system.ServiceCtrlTask and controller name service=service_{nn} up to number of services prescribed by property services=N.

Daemon Schedule Administration

The daemon schedule task provides for interactive schedule editing. You may add, delete or edit daemons. When using property tasks={task}{,task}, for each task (in 'menus') you must specify controller identifier as AddlData service=xxxx (for example -service=ocr_1).

Starting and stopping individual daemon instances is best accomplished by changing the number of scheduled daemon instances between 1 and 0. Please note that the service control task checks the schedule at about 10 seconds interval, so the response to schedule change may be delayed. Also note that some daemons (OcrDaemon) only allow one instance Java process.

Daemon Monitor

Monitor (where enabled in menus) shows all running daemons, on all hosts. Display may be adjusted using monitor menus. Note that in case of 'dead', unresponsive daemon, the time since status refresh will keep growing - a high value suggest a dead (or deadlocked) daemon.

Service Monitor

Monitor (where enabled in menus) shows all running workstations (and where database also serves the CountyWeb app, all HTTP sessions). For the CountyService hosts (workstations), it will show each service instance with identifier composed of controller/service ID and process id (i.e. 'ocr_1 pid=1234'). The PID may be useful in case of 'hang' process, allowing to identify corresponding java process in the Task Manager to kill it.

Troubleshooting

The simplest check of CountyService uses Windows Task Manager, which should show a CountySeviceNN.exe controller process with a small memory utilization (~50k). In addition, there should be a "javaw" process for each County/TownFusion instance, using a "normal" memory between 200k and 900k (high value for running multiple daemons). Note that OCR daemon, when processing, uses 100% of (single) CPU time.
In case CountySeviceNN.exe is not visible, look for stray "javaw" processes. This would indicate a severe service failure. Normally, it should NOT fork off another "javaw" process.

Home Page