==================================== Readme for the OpenHPI Client/Daemon ==================================== This file documents the OpenHPI daemon and client libraries for the current release. The OpenHPI daemon runs as a background process and accepts connections from remote clients to perform OpenHPI library function calls. The daemon wraps the standard OpenHPI function library with a sockets-based API that is archicture neutral for all types of clients. The OpenHPI client library provides all the connection functionality needed by the client application to connect to the OpenHPI daemon running on the local or remote server. Three ways of starting the OpenHPI daemon: ========================================= There are three methods for starting the daemon at this point; manually calling the installed init.d script, manually starting the daemon in the foreground, or automatically by installing the init script in one of the system run levels. 1. Manually Calling Init Script: ----------------------------------- You can START and STOP the daemon with the 'openhpid' init script. This script can be found in $sysconfdir/init.d/openhpid (where the default sysconfdir value expands to /usr/local/etc). You can change sysconfdir's value when you run configure using the --sysconfdir= argument. We recommend setting it to /etc. Example To Start: $sudo /usr/local/etc/init.d/openhpid start Starting openhpid: [ OK ] $ Example To Stop: $sudo /usr/local/etc/init.d/openhpid stop Stopping openhpid: [ OK ] $ 2. Installing Daemon into a Run Level: -------------------------------------------- How you get the daemon to start automatically when the system boots depends on your Linux distribution: - Fedora/Mandriva: chkconfig --add openhpid; chkconfig openhpid on - SuSE: yast - Gentoo: rc-update -a openhpid default - Debian: update-rc.d openhpid defaults Manually Starting The Daemon: --------------------------------------------- After performing 'make install' the init.d script will reside at $sysconfdir/init.d/openhpid and the executable itself at $prefix/sbin/openhpid. Usage of the openhpid executable: openhpid [options] [-c ] To start the daemon in the foreground use the '-n' option. For more info 'openhpid -h'. Example: 'openhpid -n -c /etc/openhpi/openhpi.conf' More information on daemon parameters and evironment variables is given below. The OpenHPI Daemon ================== The daemon is compiled as a standalone application and can be run as either a foreground or background application. The daemon application and client libraries will be located in the openhpid subdirectory. When you run the daemon the standard method for locating the OpenHPI configuration file is used. However, the daemon will accept a configuration file as a command line option to override the default file. An option in the configuration file determines the port number the daemon will listen on for client connections. If a configuration file is not found the the daemon will listen on port 4743 by default. Currently, if you are not running as the root user, you must override the default PID file location. Normally the PID file is created in the /var/run subdirectory. This directory is not writable by normal users and only the root user can write to this location. Thus the daemon will fail when run as a normal user if the PID file location is not overridden. To override the PID file location you can use the command line option. ./openhpid -f ./openhpid.pid The OpenHPI Client Library ========================== The easiect method to use to link to the client library is to first run the OpenHPI installation script. make install This will install the client library in the standard system locations. You can now use the following link flags to link the client library to your application. -lopenhpi When you run your application the client library uses two environment variables to locate the daemon service. OPENHPI_DAEMON_HOST - URL for the host running the daemon. This can be "localhost" if the daemon is running on the local host or an ip address. OPENHPI_DAEMON_PORT - The port number the host is listening on for clent connections. If the OPENHPI_DAEMON_HOST variable is not found the client library uses localhost as the default. If the OPENHPI_DAEMON_PORT variable is not found then the client library uses port 4743 as the default. General Information ------------------- The client and the daemon do not have to be on the same hardware architecture. The daemon could be running on a P-series processor and the client running on an x86-series processor. The client library and daemon use a marshaling technique to resolve architecture and structure padding conflicts. The user does not need to concern themselves with architectureal differences between the client and daemon. The one exception to this rule is 64-bit architectures. The client and daemon currently cannot resolve differences between 32-bit and 64-bit architectures. DO NOT MIX THESE TYPES OF ARCHITECTURES! It is important that data passed to the client library OpenHPI functions is correct. Passing incorrect data could cause the client library or the daemon to crash. The client library performs an extensive set of data validation functions for each OpenHPI function, but it is still possible for bad data to be missed by those functions. BE CAREFUL!.