1YAZ-ZTEST(8) System management commands YAZ-ZTEST(8)
2
6 yaz-ztest - Z39.50/SRU 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] [-K] [-d daemon] [-w dir]
12 [-p pidfile] [-r kilobytes] [-ziDSTV1] [listener-spec...]
13
15 yaz-ztest is a Z39.50/SRU test server that uses the YAZ generic
16 front-end server (GFS) API. The server acts as a real Z39.50/SRU server
17 but does not use a database. It returns a random hit count and returns
18 a subset of a few 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.
30
32 -a file
33 Specify a file for dumping PDUs (for diagnostic purposes). The
34 special name - (dash) sends output to stderr.
35 -S
37 Don't fork or make threads on connection requests. This is good for
38 debugging, but not recommended for real operation: Although the
39 server is asynchronous and non-blocking, it can be nice to keep a
40 software malfunction (okay then, a crash) from affecting all
41 current users.
42 -1
44 Like -S but after one session the server exits. This mode is for
45 debugging only.
46 -T
48 Operate the server in threaded mode. The server creates a thread
49 for each connection rather than fork a process. Only available on
50 UNIX systems that offer POSIX threads.
51 -s
53 Use the SR protocol (obsolete).
54 -z
56 Use the Z39.50 protocol (default). This option and -s complement
57 each other. You can use both multiple times on the same command
58 line, between listener-specifications (see below). This way, you
59 can set up the server to listen for connections in both protocols
60 concurrently, on different local ports.
61 -l file
63 The logfile.
64 -c config
66 A user option that serves as a specifier for some sort of
67 configuration, usually a filename. The argument to this option is
68 transferred to member configname of the statserv_options_block.
69 -f vconfig
71 This specifies an XML file that describes one or more YAZ frontend
72 virtual servers.
73 -C fname
75 Sets SSL certificate file name for server (PEM).
76 -v level
78 The log level. Use a comma-separated list of members of the set
79 {fatal,debug,warn,log,malloc,all,none}.
80 -u uid
82 Set user ID. Sets the real UID of the server process to that of the
83 given user. It's useful if you aren't comfortable with having the
84 server run as root, but you need to start it as such to bind a
85 privileged port.
86 -w dir
88 The server changes to this directory before listening to incoming
89 connections. This option is useful when the server is operating
90 from the inetd daemon (see -i).
91 -p pidfile
93 Specifies that the server should write its Process ID to the file
94 given by pidfile. A typical location would be
95 /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 the server as an NT service and mark it as
113 "auto-start. Control the server by going to the Services in the
114 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 -K
127 Forces no-keepalive for HTTP sessions. By default GFS will keep
128 sessions alive for HTTP 1.1 sessions (as defined by the standard).
129 Using this option will force GFS to close the connection for each
130 operation.
131 -r size
133 Maximum size of log file before rotation occurs, in kilobytes.
134 Default size is 1048576 k (=1 GB).
135 -d daemon
137 Set name of daemon to be used in hosts access file. See
138 hosts_access(5) and tcpd(8).
139 -m time-format
141 Sets the format of time-stamps in the log-file. Specify a string in
142 the input format to strftime().
143 -V
145 Display YAZ version and exit.
146
148 yaz-ztest normally returns a random hit count between 0 and 24.
149 However, if a query term includes leading digits, then the integer
150 value of that term is used as hit count. This allows testers to return
151 any number of hits. yaz-ztest includes 24 MARC records for testing.
152 Hit counts exceeding 24 will make yaz-ztest return the same record
153 batch over and over. So record at position 1, 25, 49, etc. are
154 equivalent.
155 For XML, if no element set is given or element has value "marcxml",
157 MARCXML is returned (each of the 24 dummy records converted from
158 ISO2709 to XML). For element set OP, then OPAC XML is returned.
159 yaz-ztest may also return predefined XML records (for testing). This is
161 enabled if YAZ_ZTEST_XML_FETCH environment variable is defined. A
162 record is fetched from a file (one record per file). The path for the
163 filename is FE.d.xml where F is the YAZ_ZTEST_XML_FETCH value (possibly
164 empty), E is element-set, d is record position (starting from 1).
165 The following databases are honored by yaz-ztest: Default, slow and
167 db.* (all databases with prefix "db"). Any other database will make
168 yaz-ztest return diagnostic 109: "Database unavailable".
169 Options for search may be included in the form or URL get arguments
171 included as part of the Z39.50 database name. The following database
172 options are present: search-delay, present-delay, fetch-delay and seed.
173 The former, delay type options, specify a fake delay (sleep) that
175 yaz-ztest will perform when searching, presenting, fetching records
176 respectively. The value of the delay may either be a fixed floating
177 point value which specifies the delay in seconds. Alternatively the
178 value may be given as two floating point numbers separated by colon,
179 which will make yaz-ztest perform a random sleep between the first and
180 second number.
181 The database parameter seed takes an integer as value. This will call
183 srand with this integer to ensure that the random behavior can be
184 re-played.
185 Suppose we want searches to take between 0.1 and 0.5 seconds and a
187 fetch to take 0.2 second. To access test database Default we'd use:
188 Default?search-delay=0.1:0.5&fetch-delay=0.2.
189
191 The Virtual hosts mechanism allows a YAZ front-end server to support
192 multiple back-ends. A back-end is selected on the basis of the TCP/IP
193 binding (port+listening address) and/or the virtual host.
194 A back-end can be configured to execute in a particular working
196 directory. Or the YAZ front-end may perform CQL to RPN conversion, thus
197 allowing traditional Z39.50 back-ends to be offered as a SRW/SRU
198 service. SRW/SRU Explain information for a particular back-end may also
199 be specified.
200 For the HTTP protocol, the virtual host is specified in the Host
202 header. For the Z39.50 protocol, the virtual host is specified as in
203 the Initialize Request in the OtherInfo, OID
204 1.2.840.10003.10.1000.81.1.
205 Note
207 Not all Z39.50 clients allow the VHOST information to be set. For
208 those, the selection of the back-end must rely on the TCP/IP
209 information alone (port and address).
210 The YAZ front-end server uses XML to describe the back-end
212 configurations. Command-line option -f specifies filename of the XML
213 configuration.
214 The configuration uses the root element yazgfs. This element includes a
216 list of listen elements, followed by one or more server elements.
217 The listen describes listener (transport end point), such as TCP/IP,
219 Unix file socket or SSL server. Content for a listener:
220 CDATA (required)
222 The CDATA for the listen element holds the listener string, such as
223 tcp:@:210, tcp:server1:2100, etc.
224 attribute id (optional)
226 Identifier for this listener. This may be referred to from server
227 sections.
228 Note
230 We expect more information to be added for the listen section in a
231 future version, such as CERT file for SSL servers.
232 The server describes a server and the parameters for this server type.
234 Content for a server:
235 attribute id (optional)
237 Identifier for this server. Currently not used for anything, but it
238 might be for logging purposes.
239 attribute listenref (optional)
241 Specifies one or more listeners for this server. Each server ID is
242 separated by a comma. If this attribute is not given, the server is
243 accessible from all listeners. In order for the server to be used
244 for real, however, the virtual host must match if specified in the
245 configuration.
246 element config (optional)
248 Specifies the server configuration. This is equivalent to the
249 config specified using command line option -c.
250 element directory (optional)
252 Specifies a working directory for this backend server. If
253 specified, the YAZ frontend changes current working directory to
254 this directory whenever a backend of this type is started (backend
255 handler bend_start), stopped (backend handler hand_stop) and
256 initialized (bend_init).
257 element host (optional)
259 Specifies the virtual host for this server. If this is specified a
260 client must specify this host string in order to use this backend.
261 element cql2rpn (optional)
263 Specifies a filename that includes CQL to RPN conversion for this
264 backend server. See ???. If given, the backend server will only
265 "see" a Type-1/RPN query.
266 element ccl2rpn (optional)
268 Specifies a filename that includes CCL to RPN conversion for this
269 backend server. See ???. If given, the backend server will only
270 "see" a Type-1/RPN query.
271 element stylesheet (optional)
273 Specifies the stylesheet reference to be part of SRU HTTP responses
274 when the client does not specify one. If none is given, then if the
275 client does not specify one, then no stylesheet reference is part
276 of the SRU HTTP response.
277 element client_query_charset (optional)
279 If specified, a conversion from the character set given to UTF-8 is
280 performed by the generic frontend server. It is only executed for
281 Z39.50 search requests (SRU/Solr are assumed to be UTF-8 encoded
282 already).
283 element docpath (optional)
285 Specifies a path for local file access using HTTP. All URLs with a
286 leading prefix (/ excluded) that matches the value of docpath are
287 used for file access. For example, if the server is to offer access
288 in directory xsl, the docpath would be xsl and all URLs of the form
289 http://host/xsl will result in a local file access.
290 element explain (optional)
292 Specifies SRW/SRU ZeeRex content for this server. Copied verbatim
293 to the client. As things are now, some of the Explain content seem
294 redundant because host information, etc. is also stored elsewhere.
295 element maximumrecordsize (optional)
297 Specifies maximum record size/message size, in bytes. This value
298 also serves as the maximum size of incoming packages (for Record
299 Updates etc). It's the same value as that given by the -k option.
300 element retrievalinfo (optional)
302 Enables the retrieval facility to support conversions and
303 specifications of record formats/types. See ??? for more
304 information.
305 The XML below configures a server that accepts connections from two
307 ports, TCP/IP port 9900 and a local UNIX file socket. We name the
308 TCP/IP server public and the other server internal.
309 <yazgfs>
312 <listen id="public">tcp:@:9900</listen>
313 <listen id="internal">unix:/var/tmp/socket</listen>
314 <server id="server1">
315 <host>server1.mydomain</host>
316 <directory>/var/www/s1</directory>
317 <config>config.cfg</config>
318 </server>
319 <server id="server2" listenref="public,internal">
320 <host>server2.mydomain</host>
321 <directory>/var/www/s2</directory>
322 <config>config.cfg</config>
323 <cql2rpn>../etc/pqf.properties</cql2rpn>
324 <explain xmlns="http://explain.z3950.org/dtd/2.0/">
325 <serverInfo>
326 <host>server2.mydomain</host>
327 <port>9900</port>
328 <database>a</database>
329 </serverInfo>
330 </explain>
331 </server>
332 <server id="server3" listenref="internal">
333 <directory>/var/www/s3</directory>
334 <config>config.cfg</config>
335 </server>
336 </yazgfs>
337 There are three configured backend servers. The first two servers,
341 "server1" and "server2", can be reached by both listener addresses.
342 "server1" is reached by all (two) since no listenref attribute is
343 specified. "server2" is reached by the two listeners specified. In
344 order to distinguish between the two, a virtual host has been specified
345 for each server in the host elements.
346 For "server2" elements for CQL to RPN conversion is supported and
348 explain information has been added (a short one here to keep the
349 example small).
350 The third server, "server3" can only be reached via listener
352 "internal".
353
355 yaz-<version>/ztest/yaz-ztest.c
356 yaz-<version>/include/yaz/backend.h
358
360 yaz(7) yaz-log(7)
361
363 Index Data
364YAZ 5.34.0 01/12/2023 YAZ-ZTEST(8)