Application Invocation

The finished application has the following invocation syntax (by way of statserv_main()):

application [-install] [-installa] [-remove] [-a file] [-v level] [-l file] [-u uid] [-c config] [-f vconfig] [-C fname] [-t minutes] [-k kilobytes] [-d daemon] [-w dir] [-p pidfile] [-r kilobytes] [-ziDST1] [listener-spec...]

The options are:

-a file: Specify a file for dumping PDUs (for diagnostic purposes). The special name - (dash) sends output to stderr.
-S: Don't 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.
-1: Like -S but after one session the server exits. This mode is for debugging only .
-T: 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.
-s: Use the SR protocol (obsolete).
-z: 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.
-l file: The logfile.
-c config: A user option that serves as a specifier for some sort of configuration, usually a filename. The argument to this option is transferred to member configname of the statserv_options_block.
-f vconfig: This specifies an XML file that describes one or more YAZ frontend virtual servers.
-C fname: Sets SSL certificate file name for server (PEM).
-v level: The log level. Use a comma-separated list of members of the set {fatal,debug,warn,log,malloc,all,none}.
-u uid: Set user ID. Sets the real UID of the server process to that of the given user. It's useful if you aren't comfortable with having the server run as root, but you need to start it as such to bind a privileged port.
-w dir: The server changes to this directory during before listening on incoming connections. This option is useful when the server is operating from the inetd daemon (see -i).
-p pidfile: Specifies that the server should write its Process ID to file given by pidfile . A typical location would be /var/run/yaz-ztest.pid.
-i: Use this to make the the server run from the inetd server (UNIX only).
-D: 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.
-install: 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.
-installa: 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.
-remove: Use this to remove the server from the NT services (Windows NT/2000/XP only).
-t minutes: Idle session timeout, in minutes.
-k size: Maximum record size/message size, in kilobytes.
-r size: Maximum size of log file before rotation occurs, in kilobytes. Default size is 1048576 k (=1 GB).
-d daemon: Set name of daemon to be used in hosts access file. See hosts_access(5) and tcpd(8).
-m time-format: Sets the format of time-stamps in the log-file. Specify a string in the input format to strftime().

A listener specification consists of a transport mode followed by a colon (:) followed by a listener address. The transport mode is either tcp, unix: or ssl.

For TCP and SSL, an address has the form

    hostname | IP-number [: portnumber]

The port number defaults to 210 (standard Z39.50 port).

For UNIX, the address is the filename of socket.

For TCP/IP and SSL, the special hostname @ (at sign) is mapped to the address INADDR_ANY, which causes the server to listen on any local interface.

Example 4.1. Running the GFS on Unix

Assuming the server application appname is started as root, the following will make it listen on port 210. The server will change identity to nobody and write its log to /var/log/app.log.

      
                    appname
                   -l /var/log/app.log -u nobody tcp:@:210

The server will accept Z39.50 requests and offer SRU service on port 210.

Example 4.2. Setting up Apache as SRU Frontend

If you use Apache as your public web server and want to offer HTTP port 80 access to the YAZ server on 210, you can use the ProxyPass directive. If you have virtual host srw.mydomain you can use the following directives in Apache's httpd.conf:

      <VirtualHost *>
       ErrorLog /home/srw/logs/error_log
       TransferLog /home/srw/logs/access_log
       ProxyPass / http://srw.mydomain:210/
      </VirtualHost>

The above for the Apache 1.3 series.

Example 4.3. Running a server with local access only

Servers that is only being accessed from the local host should listen on UNIX file socket rather than a Internet socket. To listen on /tmp/mysocket start the server as follows:

      
                    appname
                   tcp:/tmp/mysocket