====================================
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=<mysysconfdir> 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 <path to openhpi.conf>]
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!.