NAME
USAGE
DESCRIPTION
PARAMETERS
OPTIONS
EXAMPLES
IMPLEMENTATION DETAILS
SEE ALSO
KNOWN BUGS
DIAGNOSTICS
COPYRIGHT

NAME

kasykcqd - start a Kasyk caching query server

USAGE

kasykcqd [options] configfile

DESCRIPTION

The 'kasykcqd' executable reads the specified Kasyk caching query server configuration XML and starts listening for search queries on the indicated location. Instead of performing queries itself, the 'kasykcqd' executable uses one or more "providers" that handle query requests for it. A provider can either be a "true" Kasyk server (kasykd) (that can either be running locally or can be running on a remote host), another Kasyk caching query server (kasykcqd) running on a remote host (which is in fact indistinguishable from a Kasyk server (kasykd)) or a locally running Kasyk searcher (kasyk) that act as an "ad hoc" server for a specific (local) index.

Which providers provide what to the Kasyk caching query server 'kasykcqd', is determined by the contents of the Kasyk caching query server configuration XML in the specified configuration file. Only some aspects of the configuration can be overriden by options: some of these must be specified if there is no appropiate setting available in the configuration file.

Like the Kasyk server (kasykd) executable, the 'kasykcqd' executable will continue to run until it is told to stop, either by killing the process, or by using the --shutdown option.

Unlike the Kasyk server (kasykd) executable, the Kasyk caching query server 'kasykcqd' keeps the result of queries (Kasyk hitlist XML) in memory until more recent queries cause them to be removed, or until the Kasyk caching query server is restarted. This makes paging operations, where the same query is posted over and over again, but where the "window" of interesting hits is moved (e.g. first time 1..10, second time 11..20, third time 21..30, etc. etc.), very efficient as the query does not actually has to be redone, but instead is extracted from the Kasyk hitlist XML that is stored in memory by the Kasyk caching query server.

PARAMETERS

The only parameter is not optional. It indicates the name of the configuration file that contains the Kasyk caching query server configuration XML.

Unlike the Kasyk searcher (kasyk) executable, no direct queries are possible to 'kasykcqd'. It is however possible to use the Kasyk searcher (kasyk) executable to perform queries on the Kasyk caching query server. In that sense, 'kasykcqd' is indistinguishable from Kasyk server (kasykd) to the outside world.

No messages are sent to standard output (STDOUT) or standard error output (STDERR) if the caching query server has started without any problems. If there are any problems, they are sent to the message log file (if any directly or indirectly specified) and to standard error output.

OPTIONS

--location [host:port] or -L [host:]port: Override the "location" attribute of the <searching> container in the Kasyk caching query server configuration XML. Can be either specified as just a port number (in which case "localhost" will be assumed as the IP-number) or as a combination of a hostname (or IP-number) and a port number.
--server or -s: Output the Kasyk server info XML of the Kasyk caching query server running for the specified configuration file.
--restart or -R: Cause the Kasyk caching query server running for the specified configuration file to be restarted (re-read its configuration and clear its cache). Does not output any message if correctly restarted.
--shutdown or -S: Cause the Kasyk caching query server running for the specified configuration file to be shut down. Does not output any message if correctly shut down.
--messagelog filename or -M filename: Set filename to be used for logging messages. Overrides the name of the logfile that is specified in the Kasyk caching query server configuration XML or with the KASYK_MESSAGELOG environment variable.
--user user or -u user: User id with which to execute . This is only applicable when running as root on Unix(like) systems.
--group group or -g group: Group id with which to execute . This is only applicable when running as root on Unix(like) systems.
--pending connections or -p connections: Specify the number of connections that can be pending before being accepted by the server. Only needed for very heavily visited servers. Defaults to the pending attribute of the <clients> container in the Kasyk caching query server configuration XML or 128 if not specified in there.
--version or -V: Print version information of . This includes the software version, the index version it is compatible with, and whether or not it is a threaded version.
--verbose [level] or -v [level]: Set verbosity level of . Verbosity level of 1 is assumed if no value is specified. Can be used in conjunction with --copyright and --help.
--copyright or -C: Print copyright information of . This basically gives the standard GPL copyright statement. Use --verbose or -v also to get the complete copyright information including references to all internal and external libraries used.
--help or -h or -?: Print valid usage options of . Basically this information in a more condensed format.

EXAMPLES

If there are no error messages, startup was successful. To be sure of success, call 'kasykcqd" again with the same configuration file using the --server option.

starting using configuration only

 $ kasykcqd configfile <ENTER>
 $

Start serving query requests according to the configuration in "configfile" on whatever host and port are specified in the Kasyk caching query server configuration XML.

starting on specific IP-number and port

 $ kasykcqd --location=myserver.domain.com:3334 configfile <ENTER>
 $

Start serving query requests according to the configuration in "configfile" on host "myserver.domain.com" and port "3334". Ignore any settings for host in the Kasyk caching query server configuration XML.

starting on local machine on specific port, check success

 $ kasykcqd -L 3334 configfile <ENTER>
 $ kasykcqd -s configfile <ENTER>
 <kasyk:server xmlns:kasyk="http://www.kasyk.org/1.0" location="127.0.0.1:3334" pid="29604"/>
 $

Start serving query requests for the configuration file "configfile" on host "localhost" (127.0.0.1) and port "3334". Ignore any settings for host in the Kasyk caching query server configuration XML. Show the resulting Kasyk server info XML.

shut a running server down

 $ kasykcqd --shutdown configfile <ENTER>
 $

Shut the server down that is running for the configuration file "configfile".

IMPLEMENTATION DETAILS

The 'kasykcqd' executable creates a server info file containing Kasyk server info XML in the same directory as the specified configuration file. The 'kasykcqd' executable (running with any additional --user and --group option settings) must therefore be able to create the necessary file in the same directory as where the configuration file is residing. The server info file is automatically removed when the server is shut down.

KNOWN BUGS

See http://www.kasyk.nl/bugs/kasykcqd.html for the most up-to-date information about known bugs for 'kasykcqd'.

DIAGNOSTICS

Exit status is normally 0. Exit status 1 indicates a problem of some sort with an error message sent to STDERR and any active logfile.

COPYRIGHT

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Kasyk Program Information: Kasyk version 1.0.0, generated on Tue Nov 25 12:09:47 2003.