1YAZ-ZTEST(8)              System management commands              YAZ-ZTEST(8)
2
3
4

NAME

6       yaz-ztest - Z39.50/SRU Test Server
7

SYNOPSIS

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

DESCRIPTION

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
20       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
24       For TCP and SSL, an address has the form:
25
26               hostname | IP-number [ : portnumber ]
27
28
29       For UNIX local socket, the address is the filename of the local socket.
30

OPTIONS

32       -a file
33           Specify a file for dumping PDUs (for diagnostic purposes). The
34           special name - (dash) sends output to stderr.
35
36       -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
43       -1
44           Like -S but after one session the server exits. This mode is for
45           debugging only.
46
47       -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
52       -s
53           Use the SR protocol (obsolete).
54
55       -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
62       -l file
63           The logfile.
64
65       -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
70       -f vconfig
71           This specifies an XML file that describes one or more YAZ frontend
72           virtual servers.
73
74       -C fname
75           Sets SSL certificate file name for server (PEM).
76
77       -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
81       -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
87       -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
92       -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
97       -i
98           Use this to make the the server run from the inetd server (UNIX
99           only).
100
101       -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
106       -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
111       -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
116       -remove
117           Use this to remove the server from the NT services (Windows
118           NT/2000/XP only).
119
120       -t minutes
121           Idle session timeout, in minutes.
122
123       -k size
124           Maximum record size/message size, in kilobytes.
125
126       -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
132       -r size
133           Maximum size of log file before rotation occurs, in kilobytes.
134           Default size is 1048576 k (=1 GB).
135
136       -d daemon
137           Set name of daemon to be used in hosts access file. See
138           hosts_access(5) and tcpd(8).
139
140       -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
144       -V
145           Display YAZ version and exit.
146

TESTING

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
156       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
160       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
166       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
170       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
174       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
182       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
186       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

GFS CONFIGURATION AND VIRTUAL HOSTS

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
195       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
201       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
206           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
211       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
215       The configuration uses the root element yazgfs. This element includes a
216       list of listen elements, followed by one or more server elements.
217
218       The listen describes listener (transport end point), such as TCP/IP,
219       Unix file socket or SSL server. Content for a listener:
220
221       CDATA (required)
222           The CDATA for the listen element holds the listener string, such as
223           tcp:@:210, tcp:server1:2100, etc.
224
225       attribute id (optional)
226           Identifier for this listener. This may be referred to from server
227           sections.
228
229           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
233       The server describes a server and the parameters for this server type.
234       Content for a server:
235
236       attribute id (optional)
237           Identifier for this server. Currently not used for anything, but it
238           might be for logging purposes.
239
240       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
247       element config (optional)
248           Specifies the server configuration. This is equivalent to the
249           config specified using command line option -c.
250
251       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
258       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
262       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
267       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
272       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
278       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
284       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
291       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
296       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
301       element retrievalinfo (optional)
302           Enables the retrieval facility to support conversions and
303           specifications of record formats/types. See ???  for more
304           information.
305
306       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
310
311            <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
338
339
340       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
347       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
351       The third server, "server3" can only be reached via listener
352       "internal".
353

FILES

355       yaz-<version>/ztest/yaz-ztest.c
356
357       yaz-<version>/include/yaz/backend.h
358

SEE ALSO

360       yaz(7) yaz-log(7)
361

AUTHORS

363       Index Data
364
365
366
367YAZ 5.34.0                        01/12/2023                      YAZ-ZTEST(8)
Impressum