The OpenHPI Daemon v2.1.0
The OpenHPI Daemon is provided in the distribution so that it is possible to run a program on a machine that does not have the OpenHPI libraries installed on it. This is accomplished by providing a daemon to run on a machine which does have the OpenHPI libraries installed on it and a client library to which you link your application.
The Daemon Functional Description
The daemon is designed as a standard Linux daemon. It can be set up to start automatically using the standard Linux methodology for daemons.
Although the daemon is designed to run under the root user security settings, it can also be run by a standard user as long as the proper command line options are provided. This mainly has to do with the placement of the daemon's pid file.
The daemon listens on a TCP/IP network port for incoming connections. When a client connects to the daemon a thread is spawned to handle that connection and the daemon then waits for new connections on the main thread. This architecture limits the number of useful connections that can be handled simultaneously, but it is unlikely that the number of clients will be high enough to seriously impair the performance of the daemon or the machine it is running on. The default listening port for the daemon is 4743, but this can be overridden via a command line option. Currently the daemon only supports TCP connections.
The network protocol the daemon uses is embedded in the marshaling library. The marshaling library forms a platform and hardware architecture independent protocol for passing the HPI API parameters to the daemon from the client and returning arguments. The client library also embeds the marshaling library and this forms a code/decode mechanism for the client and the daemon to use to pass parameter API information.
The marshal library encodes binary information in a hardware independent format for transmission over the connection. This means that the client can be running on an x86 architecture and be able to successfully connect and communicate with a daemon that is running on a p-series or other hardware architecture. The only limitation to the successful communication between a client and a daemon is that the marshal library does not yet support any 64-bit architecture on either the client or the daemon.
Compiling and Linking the Daemon
The daemon code is compiled and linked by default. It does not need to be enabled via the configure script.
The daemon can be installed using the standard
make install
command. This includes adding the daemon executable (openhpid) to the machine's PATH.
Running the Daemon
The daemon is built with the expectation that it will be run by the root user. However, it can be run by a standard user if the user overrides the pid file location via the command line. There are also additional command line options to modify the behavior of the daemon. Here is the complete list.
-c conf_file
- Specifies the name and path of the HPI configuration file. This option is required when the OPENHPI_CONF environment variable is not defined. The configuration file can be used to supply some standard options. NOTE: This may or may not be the standard configuration file used by the OpenHPI library for configuration information. When openhpid is started via an init script this option is always required.
-v
- Enables the output of verbose information about HPI API invocations. The information is sent to stdout. This argument is optional.
-p port
- Overrides the default listening port the daemon uses. The default port is 4743. This argument is optional.
-f pidfile
- Overrides the default name and path to the daemon's pid file. The default name and path is /var/run/openhpid.pid. This argument is optional but is always necessary when a standard user runs the daemon.
-n
- Runs the application as a foreground process. Usually used for debugging. This option is optional.
-s secs
- Overrides the default read socket timeout of 30 minutes (1800 seconds). This option is optional.
-t threads
- Overrides the maximum number of connection threads. The default is an unlimited number of threads. this option is optional.
The daemon can also be run using the standard init.d init script mechanism. The shell script openhpid.sh is provided to help you enabled this capability.
The Client Library Functional Description
The client library should be used in place of the standard OpenHPI library for linking your application. It supplies all of the HPI APIs plus some oHpi APIs to provide for dynamic configuration of OpenHPI.
Compiling and Linking Your Application
The client library is compiled and linked by default.
The client library can be installed using the standard
make install
command. This includes adding the client library (openhpiclient) to the machine's PATH.
Running Your Application
Your application may require two environment variables in order to work correctly.
OPENHPI_DAEMON_HOST
- This environment variable specifies either the host name or the ip address of the host running the OpenHPI daemon. If the environment variable is not found the then localhost will be used.
OPENHPI_DAEMON_PORT
- This environment variable specifies the port on which the daemon is listening. If the environment variable is not found the port 4743 will be used.
All HPI APIs used in the client library return the standard HPI error codes.