1YAZ-ZTEST(8) YAZ-ZTEST(8)
2
6 yaz-ztest - Z39.50 Test Server
7
9 application [-install] [-installa] [-remove] [-a file] [-v level]
10 [-l file] [-u uid] [-c config] [-f vconfig] [-C fname]
11 [-t minutes] [-k kilobytes] [-d daemon] [-w dir]
12 [-p pidfile] [-r kilobytes] [-ziDST1] [listener-spec...]
13
15 yaz-ztest is a Z39.50 test server that uses the YAZ generic frontend
16 server API. The server acts as a real Z39.50 server but does not use a
17 database. It returns a random hit count and returns a subset of a few
18 built-in records.
19 The listener-spec consists of a transport mode followed by a colon,
21 followed by a listener address. The transport mode is either tcp, unix,
22 or ssl.
23 For TCP and SSL, an address has the form:
25 hostname | IP-number [ : portnumber ]
27 For UNIX local socket the address is the filename of the local socket.
31
33 -a file
34 Specify a file for dumping PDUs (for diagnostic purposes). The
35 special name - (dash) sends output to stderr.
36 -S
38 Don't fork or make threads on connection requests. This is good for
39 debugging, but not recommended for real operation: Although the
40 server is asynchronous and non-blocking, it can be nice to keep a
41 software malfunction (okay then, a crash) from affecting all current
42 users.
43 -1
45 Like -S but after one session the server exits. This mode is for
46 debugging only.
47 -T
49 Operate the server in threaded mode. The server creates a thread for
50 each connection rather than a fork a process. Only available on UNIX
51 systems that offers POSIX threads.
52 -s
54 Use the SR protocol (obsolete).
55 -z
57 Use the Z39.50 protocol (default). This option and -s complement
58 each other. You can use both multiple times on the same command
59 line, between listener-specifications (see below). This way, you can
60 set up the server to listen for connections in both protocols
61 concurrently, on different local ports.
62 -l file
64 The logfile.
65 -c config
67 A user option that serves as a specifier for some sort of
68 configuration, usually a filename. The argument to this option is
69 transferred to member configname of the statserv_options_block.
70 -f vconfig
72 This specifies an XML file that describes one or more YAZ frontend
73 virtual servers.
74 -C fname
76 Sets SSL certificate file name for server (PEM).
77 -v level
79 The log level. Use a comma-separated list of members of the set
80 {fatal,debug,warn,log,malloc,all,none}.
81 -u uid
83 Set user ID. Sets the real UID of the server process to that of the
84 given user. It's useful if you aren't comfortable with having the
85 server run as root, but you need to start it as such to bind a
86 privileged port.
87 -w dir
89 The server changes to this directory during before listening on
90 incoming connections. This option is useful when the server is
91 operating from the inetd daemon (see -i).
92 -p pidfile
94 Specifies that the server should write its Process ID to file given
95 by pidfile. A typical location would be /var/run/yaz-ztest.pid.
96 -i
98 Use this to make the the server run from the inetd server (UNIX
99 only).
100 -D
102 Use this to make the server put itself in the background and run as
103 a daemon. If neither -i nor -D is given, the server starts in the
104 foreground.
105 -install
107 Use this to install the server as an NT service (Windows NT/2000/XP
108 only). Control the server by going to the Services in the Control
109 Panel.
110 -installa
112 Use this to install and activate the server as an NT service
113 (Windows NT/2000/XP only). Control the server by going to the
114 Services in the Control Panel.
115 -remove
117 Use this to remove the server from the NT services (Windows
118 NT/2000/XP only).
119 -t minutes
121 Idle session timeout, in minutes.
122 -k size
124 Maximum record size/message size, in kilobytes.
125 -r size
127 Maximum size of log file before rotation occurs, in kilobytes.
128 Default size is 1048576 k (=1 GB).
129 -d daemon
131 Set name of daemon to be used in hosts access file. See
132 hosts_access(5) and tcpd(8).
133 -m time-format
135 Sets the format of time-stamps in the log-file. Specify a string in
136 the input format to strftime().
137
139 The Virtual hosts mechanism allows a YAZ frontend server to support
140 multiple backends. A backend is selected on the basis of the TCP/IP
141 binding (port+listening adddress) and/or the virtual host.
142 A backend can be configured to execute in a particular working
144 directory. Or the YAZ frontend may perform CQL to RPN conversion, thus
145 allowing traditional Z39.50 backends to be offered as a SRW/SRU
146 service. SRW/SRU Explain information for a particular backend may also
147 be specified.
148 For the HTTP protocol, the virtual host is specified in the Host
150 header. For the Z39.50 protocol, the virtual host is specified as in
151 the Initialize Request in the OtherInfo, OID
152 1.2.840.10003.10.1000.81.1.
153 Note
155 Not all Z39.50 clients allows the VHOST information to be set. For
156 those the selection of the backend must rely on the TCP/IP information
157 alone (port and address).
158 The YAZ frontend server uses XML to describe the backend
160 configurations. Command-line option -f specifies filename of the XML
161 configuration.
162 The configuration uses the root element yazgfs. This element includes a
164 list of listen elements, followed by one or more server elements.
165 The listen describes listener (transport end point), such as TCP/IP,
167 Unix file socket or SSL server. Content for a listener:
168 CDATA (required)
170 The CDATA for the listen element holds the listener string, such as
171 tcp:@:210, tcp:server1:2100, etc.
172 attribute id (optional)
174 identifier for this listener. This may be referred to from server
175 sections.
176 Note
178 We expect more information to be added for the listen section in a
179 future version, such as CERT file for SSL servers.
180 The server describes a server and the parameters for this server type.
182 Content for a server:
183 attribute id (optional)
185 Identifier for this server. Currently not used for anything, but it
186 might be for logging purposes.
187 attribute listenref (optional)
189 Specifies listener for this server. If this attribute is not given,
190 the server is accessible from all listener. In order for the server
191 to be used for real, howeever, the virtual host must match (if
192 specified in the configuration).
193 element config (optional)
195 Specifies the server configuration. This is equivalent to the config
196 specified using command line option -c.
197 element directory (optional)
199 Specifies a working directory for this backend server. If specifid,
200 the YAZ fronend changes current working directory to this directory
201 whenever a backend of this type is started (backend handler
202 bend_start), stopped (backend handler hand_stop) and initialized
203 (bend_init).
204 element host (optional)
206 Specifies the virtual host for this server. If this is specified a
207 client must specify this host string in order to use this backend.
208 element cql2rpn (optional)
210 Specifies a filename that includes CQL to RPN conversion for this
211 backend server. See the section called “CQL TO RPN CONVERSIONS” If
212 given, the backend server will only "see" a Type-1/RPN query.
213 element stylesheet (optional)
215 Specifies the stylesheet reference to be part of SRU HTTP responses
216 when the client does not specify one. If neither this is given, nor
217 the client specifies one, no stylesheet reference is part of the SRU
218 HTTP response.
219 element docpath (optional)
221 Specifies a path for local file access using HTTP. All URLs with a
222 leading prefix (/ exluded) that matches the value of docpath are
223 used for file access. For example, if the server is to offer access
224 in directory xsl, the docpath would be xsl and all URLs of the form
225 http://host/exl will result in a local file access.
226 element explain (optional)
228 Specifies SRW/SRU ZeeRex content for this server. Copied verbatim to
229 the client. As things are now, some of the Explain content seeem
230 redundant because host information, etc. is also stored elsewhere.
231 element maximumrecordsize (optional)
233 Specifies maximum record size/message size, in bytes. This value
234 also servers as maximum size of incoming packages (for Record
235 Updates etc). It's the same value as that given by the -k option.
236 element retrievalinfo (optional)
238 Enables the retrieval facility supporting conversions and
239 specifications of record formats/types. See the section called
240 “RETRIEVAL FACILITY” for more information.
241 The XML below configures a server that accepts connections from two
243 ports, TCP/IP port 9900 and a local UNIX file socket. We name the
244 TCP/IP server public and the other server internal.
245 <yazgfs>
248 <listen id="public">tcp:@:9900</listen>
249 <listen id="internal">unix:/var/tmp/socket</listen>
250 <server id="server1">
251 <host>server1.mydomain</host>
252 <directory>/var/www/s1</directory>
253 <config>config.cfg</config>
254 </server>
255 <server id="server2">
256 <host>server2.mydomain</host>
257 <directory>/var/www/s2</directory>
258 <config>config.cfg</config>
259 <cql2rpn>../etc/pqf.properties</cql2rpn>
260 <explain xmlns="http://explain.z3950.org/dtd/2.0/">
261 <serverInfo>
262 <host>server2.mydomain</host>
263 <port>9900</port>
264 <database>a</database>
265 </serverInfo>
266 </explain>
267 </server>
268 <server id="server3" listenref="internal">
269 <directory>/var/www/s3</directory>
270 <config>config.cfg</config>
271 </server>
272 </yazgfs>
273 There are three configured backend servers. The first two servers,
277 "server1" and "server2", can be reached by both listener addresses -
278 since no listenref attribute is specified. In order to distinguish
279 between the two a virtual host has been specified for each of server in
280 the host elements.
281 For "server2" elements for CQL to RPN conversion is supported and
283 explain information has been added (a short one here to keep the
284 example small).
285 The third server, "server3" can only be reached via listener
287 "internal".
288
290 yaz-<version>/ztest/yaz-ztest.c
291 yaz-<version>/include/yaz/backend.h
293
295 Refer to the "Retrieval Facility" in the YAZ manual
296
298 Refer to the "Specification of CQL to RPN mappings" in YAZ manual.
299
301 yaz(7) yaz-log(7)
302YAZ 2.1.54 03/16/2007 YAZ-ZTEST(8)