'\" t
.\"     Title: zebrasrv
.\"    Author: Index Data
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 01/29/2026
.\"    Manual: Commands
.\"    Source: zebra 2.2.10
.\"  Language: English
.\"
.TH "ZEBRASRV" "8" "01/29/2026" "zebra 2.2.10" "Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
zebrasrv \- Zebra Server
.SH "SYNOPSIS"
.HP \w'\fBzebrasrv\fR\ 'u
\fBzebrasrv\fR [\fB\-install\fR] [\fB\-installa\fR] [\fB\-remove\fR] [\fB\-a\ \fR\fB\fIfile\fR\fR] [\fB\-v\ \fR\fB\fIlevel\fR\fR] [\fB\-l\ \fR\fB\fIfile\fR\fR] [\fB\-u\ \fR\fB\fIuid\fR\fR] [\fB\-c\ \fR\fB\fIconfig\fR\fR] [\fB\-f\ \fR\fB\fIvconfig\fR\fR] [\fB\-C\ \fR\fB\fIfname\fR\fR] [\fB\-t\ \fR\fB\fIminutes\fR\fR] [\fB\-k\ \fR\fB\fIkilobytes\fR\fR] [\fB\-d\ \fR\fB\fIdaemon\fR\fR] [\fB\-w\ \fR\fB\fIdir\fR\fR] [\fB\-p\ \fR\fB\fIpidfile\fR\fR] [\fB\-ziDST1\fR] [listener\-spec...]
.SH "DESCRIPTION"
.PP
Zebra is a high\-performance, general\-purpose structured text indexing and retrieval engine\&. It reads structured records in a variety of input formats (e\&.g\&. email,
XML,
MARC) and allows access to them through exact boolean search expressions and relevance\-ranked free\-text queries\&.
.PP
\fBzebrasrv\fR
is the
Z39\&.50
and
SRU
frontend server for the
\fBZebra\fR
search engine and indexer\&.
.PP
On Unix you can run the
\fBzebrasrv\fR
server from the command line \- and put it in the background\&. It may also operate under the inet daemon\&. On WIN32 you can run the server as a console application or as a WIN32 Service\&.
.SH "OPTIONS"
.PP
The options for
\fBzebrasrv\fR
are the same as those for
YAZ\*(Aq
\fByaz\-ztest\fR\&. Option
\-c
specifies a Zebra configuration file \- if omitted
zebra\&.cfg
is read\&.
.PP
\-a \fIfile\fR
.RS 4
Specify a file for dumping PDUs (for diagnostic purposes)\&. The special name
\-
(dash) sends output to
stderr\&.
.RE
.PP
\-S
.RS 4
Don\*(Aqt fork or make threads on connection requests\&. This is good for debugging, but not recommended for real operation: Although the server is asynchronous and non\-blocking, it can be nice to keep a software malfunction (okay then, a crash) from affecting all current users\&. The server can only accept a single connection in this mode\&.
.RE
.PP
\-1
.RS 4
Like
\-S
but after one session the server exits\&. This mode is for debugging
\fIonly\fR\&.
.RE
.PP
\-T
.RS 4
Operate the server in threaded mode\&. The server creates a thread for each connection rather than a fork a process\&. Only available on UNIX systems that offers POSIX threads\&.
.RE
.PP
\-s
.RS 4
Use the SR protocol (obsolete)\&.
.RE
.PP
\-z
.RS 4
Use the
Z39\&.50
protocol (default)\&. This option and
\-s
complement each other\&. You can use both multiple times on the same command line, between listener\-specifications (see below)\&. This way, you can set up the server to listen for connections in both protocols concurrently, on different local ports\&.
.RE
.PP
\-l \fIfile\fR
.RS 4
Specify an output file for the diagnostic messages\&. The default is to write this information to
stderr
.RE
.PP
\-c \fIconfig\-file\fR
.RS 4
Read configuration information from
\fIconfig\-file\fR\&. The default configuration is
\&./zebra\&.cfg
.RE
.PP
\-f \fIvconfig\fR
.RS 4
This specifies an
XML
file that describes one or more
YAZ
frontend virtual servers\&. See section VIRTUAL HOSTS for details\&.
.RE
.PP
\-C \fIfname\fR
.RS 4
Sets SSL certificate file name for server (PEM)\&.
.RE
.PP
\-v \fIlevel\fR
.RS 4
The log level\&. Use a comma\-separated list of members of the set {fatal,debug,warn,log,malloc,all,none}\&.
.RE
.PP
\-u \fIuid\fR
.RS 4
Set user ID\&. Sets the real UID of the server process to that of the given user\&. It\*(Aqs useful if you aren\*(Aqt comfortable with having the server run as root, but you need to start it as such to bind a privileged port\&.
.RE
.PP
\-w \fIworking\-directory\fR
.RS 4
The server changes to this working directory during before listening on incoming connections\&. This option is useful when the server is operating from the
inetd
daemon (see
\-i)\&.
.RE
.PP
\-p \fIpidfile\fR
.RS 4
Specifies that the server should write its Process ID to file given by
\fIpidfile\fR\&. A typical location would be
/var/run/zebrasrv\&.pid\&.
.RE
.PP
\-i
.RS 4
Use this to make the the server run from the
inetd
server (UNIX only)\&. Make sure you use the logfile option
\-l
in conjunction with this mode and specify the
\-l
option before any other options\&.
.RE
.PP
\-D
.RS 4
Use this to make the server put itself in the background and run as a daemon\&. If neither
\-i
nor
\-D
is given, the server starts in the foreground\&.
.RE
.PP
\-install
.RS 4
Use this to install the server as an NT service (Windows NT/2000/XP only)\&. Control the server by going to the Services in the Control Panel\&.
.RE
.PP
\-installa
.RS 4
Use this to install and activate the server as an NT service (Windows NT/2000/XP only)\&. Control the server by going to the Services in the Control Panel\&.
.RE
.PP
\-remove
.RS 4
Use this to remove the server from the NT services (Windows NT/2000/XP only)\&.
.RE
.PP
\-t \fIminutes\fR
.RS 4
Idle session timeout, in minutes\&. Default is 60 minutes\&.
.RE
.PP
\-k \fIsize\fR
.RS 4
Maximum record size/message size, in kilobytes\&. Default is 1024 KB (1 MB)\&.
.RE
.PP
\-d \fIdaemon\fR
.RS 4
Set name of daemon to be used in hosts access file\&. See
\fBhosts_access\fR(5)
and
\fBtcpd\fR(8)\&.
.RE
.PP
A
\fIlistener\-address\fR
consists of an optional transport mode followed by a colon (:) followed by a listener address\&. The transport mode is either a file system socket
unix, a SSL TCP/IP socket
ssl, or a plain TCP/IP socket
tcp
(default)\&.
.PP
For TCP, an address has the form
.sp
.if n \{\
.RS 4
.\}
.nf
    hostname | IP\-number [: portnumber]
   
.fi
.if n \{\
.RE
.\}
.sp
The port number defaults to 210 (standard
Z39\&.50
port) for privileged users (root), and 9999 for normal users\&. The special hostname "@" is mapped to the address INADDR_ANY, which causes the server to listen on any local interface\&.
.PP
The default behavior for
zebrasrv
\- if started as non\-privileged user \- is to establish a single TCP/IP listener, for the
Z39\&.50
protocol, on port 9999\&.
.sp
.if n \{\
.RS 4
.\}
.nf
    zebrasrv @
    zebrasrv tcp:some\&.server\&.name\&.org:1234
    zebrasrv ssl:@:3000
   
.fi
.if n \{\
.RE
.\}
.PP
To start the server listening on the registered port for
Z39\&.50, or on a filesystem socket, and to drop root privileges once the ports are bound, execute the server like this from a root shell:
.sp
.if n \{\
.RS 4
.\}
.nf
    zebrasrv \-u daemon @
    zebrasrv \-u daemon tcp:@:210
    zebrasrv \-u daemon unix:/some/file/system/socket
   
.fi
.if n \{\
.RE
.\}
.sp
Here
daemon
is an existing user account, and the unix socket
/some/file/system/socket
is readable and writable for the
daemon
account\&.
.SH "Z39\&.50 PROTOCOL SUPPORT AND BEHAVIOR"
.SS "Z39\&.50 Initialization"
.PP
During initialization, the server will negotiate to version 3 of the
Z39\&.50
protocol, and the option bits for Search, Present, Scan, NamedResultSets, and concurrentOperations will be set, if requested by the client\&. The maximum PDU size is negotiated down to a maximum of 1 MB by default\&.
.SS "Z39\&.50 Search"
.PP
The supported query type are 1 and 101\&. All operators are currently supported with the restriction that only proximity units of type "word" are supported for the proximity operator\&. Queries can be arbitrarily complex\&. Named result sets are supported, and result sets can be used as operands without limitations\&. Searches may span multiple databases\&.
.PP
The server has full support for piggy\-backed retrieval (see also the following section)\&.
.SS "Z39\&.50 Present"
.PP
The present facility is supported in a standard fashion\&. The requested record syntax is matched against the ones supported by the profile of each record retrieved\&. If no record syntax is given,
SUTRS
is the default\&. The requested element set name, again, is matched against any provided by the relevant record profiles\&.
.SS "Z39\&.50 Scan"
.PP
The attribute combinations provided with the termListAndStartPoint are processed in the same way as operands in a query (see above)\&. Currently, only the term and the globalOccurrences are returned with the termInfo structure\&.
.SS "Z39\&.50 Sort"
.PP
Z39\&.50
specifies three different types of sort criteria\&. Of these Zebra supports the attribute specification type in which case the use attribute specifies the "Sort register"\&. Sort registers are created for those fields that are of type "sort" in the default\&.idx file\&. The corresponding character mapping file in default\&.idx specifies the ordinal of each character used in the actual sort\&.
.PP
Z39\&.50
allows the client to specify sorting on one or more input result sets and one output result set\&. Zebra supports sorting on one result set only which may or may not be the same as the output result set\&.
.SS "Z39\&.50 Close"
.PP
If a Close PDU is received, the server will respond with a Close PDU with reason=FINISHED, no matter which protocol version was negotiated during initialization\&. If the protocol version is 3 or more, the server will generate a Close PDU under certain circumstances, including a session timeout (60 minutes by default), and certain kinds of protocol errors\&. Once a Close PDU has been sent, the protocol association is considered broken, and the transport connection will be closed immediately upon receipt of further data, or following a short timeout\&.
.SS "Z39\&.50 Explain"
.PP
Zebra maintains a "classic"
\m[blue]\fBZ39\&.50 Explain\fR\m[]\&\s-2\u[1]\d\s+2
database on the side\&. This database is called
IR\-Explain\-1
and can be searched using the attribute set
exp\-1\&.
.PP
The records in the explain database are of type
grs\&.sgml\&. The root element for the Explain grs\&.sgml records is
explain, thus
explain\&.abs
is used for indexing\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
Zebra
\fImust\fR
be able to locate
explain\&.abs
in order to index the Explain records properly\&. Zebra will work without it but the information will not be searchable\&.
.sp .5v
.RE
.SH "THE SRU SERVER"
.PP
In addition to
Z39\&.50, Zebra supports the more recent and web\-friendly IR protocol
\m[blue]\fBSRU\fR\m[]\&\s-2\u[2]\d\s+2\&.
SRU
can be carried over
SOAP
or a
REST\-like protocol that uses HTTP
GET
or
POST
to request search responses\&. The request itself is made of parameters such as
query,
startRecord,
maximumRecords
and
recordSchema; the response is an
XML
document containing hit\-count, result\-set records, diagnostics, etc\&.
SRU
can be thought of as a re\-casting of
Z39\&.50
semantics in web\-friendly terms; or as a standardisation of the ad\-hoc query parameters used by search engines such as Google and AltaVista; or as a superset of A9\*(Aqs OpenSearch (which it predates)\&.
.PP
Zebra supports
Z39\&.50,
SRU
GET, SRU
POST, SRU
SOAP
(SRW) \- on the same port, recognising what protocol is used by each incoming requests and handling them accordingly\&. This is a achieved through the use of Deep Magic; civilians are warned not to stand too close\&.
.SS "Running zebrasrv as an SRU Server"
.PP
Because Zebra supports all protocols on one port, it would seem to follow that the
SRU
server is run in the same way as the
Z39\&.50
server, as described above\&. This is true, but only in an uninterestingly vacuous way: a Zebra server run in this manner will indeed recognise and accept
SRU
requests; but since it doesn\*(Aqt know how to handle the
CQL
queries that these protocols use, all it can do is send failure responses\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
It is possible to cheat, by having
SRU
search Zebra with a
PQF
query instead of
CQL, using the
x\-pquery
parameter instead of
query\&. This is a
\fBnon\-standard extension\fR
of
CQL, and a
\fBvery naughty\fR
thing to do, but it does give you a way to see Zebra serving
SRU
``right out of the box\*(Aq\*(Aq\&. If you start your favourite Zebra server in the usual way, on port 9999, then you can send your web browser to:
.sp
.if n \{\
.RS 4
.\}
.nf
     http://localhost:9999/Default?version=1\&.1
     &operation=searchRetrieve
     &x\-pquery=mineral
     &startRecord=1
     &maximumRecords=1
    
.fi
.if n \{\
.RE
.\}
.PP
This will display the
XML\-formatted
SRU
response that includes the first record in the result\-set found by the query
mineral\&. (For clarity, the
SRU
URL is shown here broken across lines, but the lines should be joined together to make single\-line URL for the browser to submit\&.)
.sp .5v
.RE
.PP
In order to turn on Zebra\*(Aqs support for
CQL
queries, it\*(Aqs necessary to have the
YAZ
generic front\-end (which Zebra uses) translate them into the
Z39\&.50
Type\-1 query format that is used internally\&. And to do this, the generic front\-end\*(Aqs own configuration file must be used\&. See
the section called \(lqYAZ SERVER VIRTUAL HOSTS\(rq; the salient point for
SRU
support is that
\fBzebrasrv\fR
must be started with the
\-f\ \&frontendConfigFile
option rather than the
\-c\ \&zebraConfigFile
option, and that the front\-end configuration file must include both a reference to the Zebra configuration file and the
CQL\-to\-PQF
translator configuration file\&.
.PP
A minimal front\-end configuration file that does this would read as follows:
.sp
.if n \{\
.RS 4
.\}
.nf
    
    <yazgfs>
    <server>
    <config>zebra\&.cfg</config>
    <cql2rpn>\&.\&./\&.\&./tab/pqf\&.properties</cql2rpn>
   </server>
   </yazgfs>
    
.fi
.if n \{\
.RE
.\}
.PP
The
<config>
element contains the name of the Zebra configuration file that was previously specified by the
\-c
command\-line argument, and the
<cql2rpn>
element contains the name of the
CQL
properties file specifying how various
CQL
indexes, relations, etc\&. are translated into Type\-1 queries\&.
.PP
A zebra server running with such a configuration can then be queried using proper, conformant
SRU
URLs with
CQL
queries:
.sp
.if n \{\
.RS 4
.\}
.nf
    http://localhost:9999/Default?version=1\&.1
    &operation=searchRetrieve
    &query=title=utah and description=epicent*
    &startRecord=1
    &maximumRecords=1
   
.fi
.if n \{\
.RE
.\}
.SH "SRU PROTOCOL SUPPORT AND BEHAVIOR"
.PP
Zebra running as an
SRU
server supports SRU version 1\&.1, including
CQL
version 1\&.1\&. In particular, it provides support for the following elements of the protocol\&.
.SS "SRU Search and Retrieval"
.PP
Zebra supports the searchRetrieve operation\&.
.PP
One of the great strengths of
SRU
is that it mandates a standard query language,
CQL, and that all conforming implementations can therefore be trusted to correctly interpret the same queries\&. It is with some shame, then, that we admit that Zebra also supports an additional query language, our own Prefix Query Format (\m[blue]\fBPQF\fR\m[]\&\s-2\u[3]\d\s+2)\&. A
PQF
query is submitted by using the extension parameter
x\-pquery, in which case the
query
parameter must be omitted, which makes the request not valid
SRU\&. Please feel free to use this facility within your own applications; but be aware that it is not only non\-standard
SRU
but not even syntactically valid, since it omits the mandatory
query
parameter\&.
.SS "SRU Scan"
.PP
Zebra supports scan operation\&. Scanning using
CQL
syntax is the default, where the standard
scanClause
parameter is used\&.
.PP
In addition, a mutant form of
SRU
scan is supported, using the non\-standard
x\-pScanClause
parameter in place of the standard
scanClause
to scan on a
PQF
query clause\&.
.SS "SRU Explain"
.PP
Zebra supports explain\&.
.PP
The ZeeRex record explaining a database may be requested either with a fully fledged
SRU
request (with
operation=explain
and version\-number specified) or with a simple HTTP
GET
at the server\*(Aqs basename\&. The ZeeRex record returned in response is the one embedded in the
YAZ
Frontend Server configuration file that is described in the
the section called \(lqYAZ SERVER VIRTUAL HOSTS\(rq\&.
.PP
Unfortunately, the data found in the
CQL\-to\-PQF
text file must be added by hand\-craft into the explain section of the
YAZ
Frontend Server configuration file to be able to provide a suitable explain record\&. Too bad, but this is all extreme new alpha stuff, and a lot of work has yet to be done \&.\&.
.PP
There is no linkage whatsoever between the
Z39\&.50
explain model and the
SRU
explain response (well, at least not implemented in Zebra, that is \&.\&.)\&. Zebra does not provide a means using
Z39\&.50
to obtain the ZeeRex record\&.
.SS "Other SRU operations"
.PP
In the
Z39\&.50
protocol, Initialization, Present, Sort and Close are separate operations\&. In
SRU, however, these operations do not exist\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
SRU
has no explicit initialization handshake phase, but commences immediately with searching, scanning and explain operations\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Neither does
SRU
have a close operation, since the protocol is stateless and each request is self\-contained\&. (It is true that multiple
SRU
request/response pairs may be implemented as multiple HTTP request/response pairs over a single persistent TCP/IP connection; but the closure of that connection is not a protocol\-level operation\&.)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Retrieval in
SRU
is part of the
searchRetrieve
operation, in which a search is submitted and the response includes a subset of the records in the result set\&. There is no direct analogue of
Z39\&.50\*(Aqs Present operation which requests records from an established result set\&. In
SRU, this is achieved by sending a subsequent
searchRetrieve
request with the query
cql\&.resultSetId=\fIid\fR
where
\fIid\fR
is the identifier of the previously generated result\-set\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Sorting in
CQL
is done within the
searchRetrieve
operation \- in v1\&.1, by an explicit
sort
parameter, but the forthcoming v1\&.2 or v2\&.0 will most likely use an extension of the query language,
\m[blue]\fBCQL sorting\fR\m[]\&\s-2\u[4]\d\s+2\&.
.RE
.PP
It can be seen, then, that while Zebra operating as an
SRU
server does not provide the same set of operations as when operating as a
Z39\&.50
server, it does provide equivalent functionality\&.
.SH "SRU EXAMPLES"
.PP
Surf into
http://localhost:9999
to get an explain response, or use
.sp
.if n \{\
.RS 4
.\}
.nf
    http://localhost:9999/?version=1\&.1&operation=explain
    
.fi
.if n \{\
.RE
.\}
.PP
See number of hits for a query
.sp
.if n \{\
.RS 4
.\}
.nf
    http://localhost:9999/?version=1\&.1&operation=searchRetrieve
    &query=text=(plant%20and%20soil)
    
.fi
.if n \{\
.RE
.\}
.PP
Fetch record 5\-7 in Dublin Core format
.sp
.if n \{\
.RS 4
.\}
.nf
    http://localhost:9999/?version=1\&.1&operation=searchRetrieve
    &query=text=(plant%20and%20soil)
    &startRecord=5&maximumRecords=2&recordSchema=dc
    
.fi
.if n \{\
.RE
.\}
.PP
Even search using
PQF
queries using the
\fIextended naughty parameter\fR
x\-pquery
.sp
.if n \{\
.RS 4
.\}
.nf
    http://localhost:9999/?version=1\&.1&operation=searchRetrieve
    &x\-pquery=@attr%201=text%20@and%20plant%20soil
    
.fi
.if n \{\
.RE
.\}
.PP
Or scan indexes using the
\fIextended extremely naughty parameter\fR
x\-pScanClause
.sp
.if n \{\
.RS 4
.\}
.nf
    http://localhost:9999/?version=1\&.1&operation=scan
    &x\-pScanClause=@attr%201=text%20something
    
.fi
.if n \{\
.RE
.\}
.sp

\fIDon\*(Aqt do this in production code!\fR
But it\*(Aqs a great fast debugging aid\&.
.SH "YAZ SERVER VIRTUAL HOSTS"
.PP
The Virtual hosts mechanism allows a
YAZ
frontend server to support multiple backends\&. A backend is selected on the basis of the TCP/IP binding (port+listening address) and/or the virtual host\&.
.PP
A backend can be configured to execute in a particular working directory\&. Or the
YAZ
frontend may perform
\m[blue]\fBCQL\fR\m[]\&\s-2\u[5]\d\s+2
to
RPN
conversion, thus allowing traditional
Z39\&.50
backends to be offered as a
\m[blue]\fBSRU\fR\m[]\&\s-2\u[2]\d\s+2
service\&.
SRU
Explain information for a particular backend may also be specified\&.
.PP
For the HTTP protocol, the virtual host is specified in the Host header\&. For the
Z39\&.50
protocol, the virtual host is specified as in the Initialize Request in the OtherInfo, OID 1\&.2\&.840\&.10003\&.10\&.1000\&.81\&.1\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
Not all
Z39\&.50
clients allows the VHOST information to be set\&. For those the selection of the backend must rely on the TCP/IP information alone (port and address)\&.
.sp .5v
.RE
.PP
The
YAZ
frontend server uses
XML
to describe the backend configurations\&. Command\-line option
\-f
specifies filename of the
XML
configuration\&.
.PP
The configuration uses the root element
yazgfs\&. This element includes a list of
listen
elements, followed by one or more
server
elements\&.
.PP
The
listen
describes listener (transport end point), such as TCP/IP, Unix file socket or SSL server\&. Content for a listener:
.PP
CDATA (required)
.RS 4
The CDATA for the
listen
element holds the listener string, such as
tcp:@:210,
tcp:server1:2100, etc\&.
.RE
.PP
attribute id (optional)
.RS 4
identifier for this listener\&. This may be referred to from server sections\&.
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
We expect more information to be added for the listen section in a future version, such as CERT file for SSL servers\&.
.sp .5v
.RE
.PP
The
server
describes a server and the parameters for this server type\&. Content for a server:
.PP
attribute id (optional)
.RS 4
Identifier for this server\&. Currently not used for anything, but it might be for logging purposes\&.
.RE
.PP
attribute listenref (optional)
.RS 4
Specifies listener for this server\&. If this attribute is not given, the server is accessible from all listener\&. In order for the server to be used for real, however, the virtual host must match (if specified in the configuration)\&.
.RE
.PP
element config (optional)
.RS 4
Specifies the server configuration\&. This is equivalent to the config specified using command line option
\-c\&.
.RE
.PP
element directory (optional)
.RS 4
Specifies a working directory for this backend server\&. If specified, the
YAZ
frontend changes current working directory to this directory whenever a backend of this type is started (backend handler bend_start), stopped (backend handler hand_stop) and initialized (bend_init)\&.
.RE
.PP
element host (optional)
.RS 4
Specifies the virtual host for this server\&. If this is specified a client
\fImust\fR
specify this host string in order to use this backend\&.
.RE
.PP
element cql2rpn (optional)
.RS 4
Specifies a filename that includes
\m[blue]\fBCQL\fR\m[]\&\s-2\u[5]\d\s+2
to
RPN
conversion for this backend server\&. See
\m[blue]\fBCQL\fR\m[]\&\s-2\u[5]\d\s+2
section in
YAZ
manual\&. If given, the backend server will only "see" a Type\-1/RPN
query\&.
.RE
.PP
element explain (optional)
.RS 4
Specifies
\m[blue]\fBSRU\fR\m[]\&\s-2\u[2]\d\s+2
ZeeRex content for this server \- copied verbatim to the client\&. As things are now, some of the Explain content seems redundant because host information, etc\&. is also stored elsewhere\&.
.sp
The format of the Explain record is described in detail, with examples, on the file at the
\m[blue]\fBZeeRex\fR\m[]\&\s-2\u[6]\d\s+2
web\-site\&.
.RE
.PP
The
XML
below configures a server that accepts connections from two ports, TCP/IP port 9900 and a local UNIX file socket\&. We name the TCP/IP server
public
and the other server
internal\&.
.sp
.if n \{\
.RS 4
.\}
.nf
  
 <yazgfs>
  <listen id="public">tcp:@:9900</listen>
  <listen id="internal">unix:/var/tmp/socket</listen>
  <server id="server1">
    <host>server1\&.mydomain</host>
    <directory>/var/www/s1</directory>
    <config>config\&.cfg</config>
  </server>
  <server id="server2">
    <host>server2\&.mydomain</host>
    <directory>/var/www/s2</directory>
    <config>config\&.cfg</config>
    <cql2rpn>\&.\&./etc/pqf\&.properties</cql2rpn>
    <explain xmlns="http://explain\&.z3950\&.org/dtd/2\&.0/">
      <serverInfo>
        <host>server2\&.mydomain</host>
        <port>9900</port>
        <database>a</database>
      </serverInfo>
    </explain>
  </server>
  <server id="server3" listenref="internal">
    <directory>/var/www/s3</directory>
    <config>config\&.cfg</config>
  </server>
 </yazgfs>

 
.fi
.if n \{\
.RE
.\}
.PP
There are three configured backend servers\&. The first two servers,
"server1"
and
"server2", can be reached by both listener addresses \- since no
listenref
attribute is specified\&. In order to distinguish between the two a virtual host has been specified for each of server in the
host
elements\&.
.PP
For
"server2"
elements for
\m[blue]\fBCQL\fR\m[]\&\s-2\u[5]\d\s+2
to
RPN
conversion is supported and explain information has been added (a short one here to keep the example small)\&.
.PP
The third server,
"server3"
can only be reached via listener
"internal"\&.
.SH "SEE ALSO"
.PP
\fBzebraidx\fR(1)
.SH "AUTHORS"
.PP
\fBIndex Data\fR
.SH "NOTES"
.IP " 1." 4
Z39.50 Explain
.RS 4
\%https://www.loc.gov/z3950/agency/markup/07.html
.RE
.IP " 2." 4
SRU
.RS 4
\%https://www.loc.gov/standards/sru/
.RE
.IP " 3." 4
PQF
.RS 4
\%https://www.indexdata.com/yaz/doc/tools.html#PQF
.RE
.IP " 4." 4
CQL sorting
.RS 4
\%https://zing.z3950.org/cql/sorting.html
.RE
.IP " 5." 4
CQL
.RS 4
\%https://www.loc.gov/standards/sru/cql/
.RE
.IP " 6." 4
ZeeRex
.RS 4
\%https://zeerex.z3950.org/
.RE
