Commands Reference, Volume 3

invscoutd Command

Purpose

Launches a permanent Inventory Scout server daemon.

Syntax

invscoutd [ -o] [ -pPortno] [ -bBufsize] [ -dMaxdbsize] [ -tTimeout] [ -vVerblev] Logfile

Description

The invscoutd command implements a permanent Inventory Scout server daemon on one machine in a user's local network. The usual client is a Java applet running in the user's Web browser, which was downloaded from a central Inventory Scout CGI application.

Daemon initialization involves reading command line options and several local inventory scout companion files. Once in operation, each client-server transaction involves reading from a well-known socket for a text string and returning a text report over the same socket.

Protocols

Client connections to the daemon's socket use the Internet TCP/IP protocol. In a transaction, the invoking client applet sends an "action" request, as a URL-encoded text string, to the server daemon. The request is by any ASCII control character (x00 to x1F), which triggers the processing of the request.

Some requests require the client to pass additional arbitrary data. In these cases, the additional data immediately follow the termination byte for a length specified in the action request.

With one exception (ACTION=PING), the server daemon always returns a pseudo MIME format text report written back over the same socket connection. The pseudo MIME format is used even for error results. The daemon terminates the returned text and the transaction itself by closing the socket, resulting in an end-of-file (EOF) indication to the invoking client. The client should close the socket at its end of the connection as soon as the EOF is received.

Action Requests

The action request string is a standard URL-encoded string. For example:

"ACTION=actionword&NAME1=value1&NAME2&NAME3=word%xx+word+word\0"

.

• Field names and their values are separated by equal signs (=).
• Name=Value pairs are separated by ampersands (&).
• The Name field is always case insensitive.
• The Value field is case insensitive, unless documented otherwise.
• The ACTION=keyword pair must always be present.
• The MRDM=clearpwd pair must be present if passwords are required for the action. The clearpwd value is case sensitive.
• The DATALEN=n pair must be present if additional binary data immediately follows the action string termination byte, and must be absent if no additional data follows the termination byte. The integer n specifies the number of additional data bytes. If the client attempts to write more data than the n bytes, if the action does not accept the DATALEN parameter and discards any additional data, or if the action processor detects an early error, the daemon may prematurely close the client-to-server socket pipe. A transaction with n greater than a specific maximum value will immediately return an error code (see -d flag).
• A string between ampersands without an equal sign is parsed as a Name with an Empty value.
• Spaces can be represented by plus signs (+).
• Binary characters may be coded as the escape sequence of a percent sign followed by exactly two hexadecimal chars (%xx). This escape sequence must also be used to code URL metacharacters like the equal sign, ampersand, and plus sign within a Value.
• The control character termination byte must alway be sent by the client.

Results

The daemon returns a text result in a pseudo MIME format. Specifically, it returns a header consisting of one or more Name=Value pairs, each on a line by itself. The first Name=Value pair always is the "result" code in the form RESULT=number. The result code always is returned for every action, except the PING action.

Internal scout result codes applicable only to the Java applet client are not documented below.

An optional free-form text report may follow the header lines depending on the result code. If there is a free-form text report, the header is first terminated by an empty line, such as two adjacent linefeeds.

In any event, the result report is terminated by an EOF indicator after reading the last of the report text from the socket. The EOF also signifies the end of the transaction itself.

Table 1-1.

"action=ping\0"
 
<EOF>

"action=ECHO&MRDM=yadayada&datalen=9\0Hi There!"
 
"RESULT=0\n"
"\n"
"action=ECHO&MRDM=yadayada&datalen=9\n"
"Hi There!"<EOF>

"action=UrlDecode&subaction=yadayada\0"
 
"RESULT=0\n"
"\n"
"  0: ACTION       UrlDecode\n"
"  1: SUBACTION    yadayada\n"
<EOF>

"ACTION=TESTPWD&MRDM=thepassword\0"
 
"RESULT=0\n"
"\n"
<EOF>

"ACTION=VERSIONS\0"
 
"RESULT=0\n"
"\n"
"1.2.3.4\n"
"5.6.7.8\n"
<EOF>

"ACTION=LOGICDB&MRDM=yadayada&DATALEN=17042\0"
"...17042 bytes of binary data..."
 
"RESULT=0\n"
"\n"
"1.2.3.4\n"
<EOF>

"ACTION=MCODES&MRDM=xyz\0"
 
"RESULT=0\n"
"\n"
"Report Line 1\n"
"Report Line 2\n"
    :
    :
"Report Line N\n"
<EOF>

"ACTION=VPDS&MRDM=xyz\0"
 
"RESULT=0\n"
"\n"
"Report Line 1\n"
"Report Line 2\n"
    :
    :
"Report Line N\n"
<EOF>

Table 1-2.

Implementation Specifics

The invscoutd command only applies to the POWER-based platform. Currently, the server does not provide host-to-network data conversions, so it will communicate incorrect data to little-endian and byte-swap clients.

Flags

Specify any arguments, beginning with a hyphen (-), before the required logfile argument. Space is not allowed between a flag and its value.

-bBufsize

Inventory Scout commands are specified as URL-encoded strings read from a TCP/IP socket into a 1024 byte fixed length buffer. This flag can change the buffer size to Bufsize bytes if future protocol changes require a larger read buffer.

-dMaxdbsize

This flag changes the maximum size of a downloaded logic database file from the default 50000 to Maxdbsize. The daemon will abort an ACTION=LOGICDB transaction if the client applet specifies a DATALEN value greater than the maximum permitted size.

Logfile

The only required command line argument is the Logfile name. Depending on the specified verbosity level, the log lines may contain startup and shutdown banners, traces of each call, detailed internal program traces, and error statements. Depending on specified verbosity level, startup banners may also be written to stderr. The Logfile should be a fully qualified path name starting at the root directory; relative file names are presumed relative from the system's root directory, not the working directory.

-o

This flag overwrites an existing logfile. If this flag is not specified, new logfile lines are appended to any existing logfile.

-pPortno

This flag changes this server's port number from the default 808 to Port.

-tTimeout

The client applet writes a control character termination byte at the end of the URL-encoded request string to indicate the end of the request. If the invscoutd daemon does not receive the termination byte within a timeout period, it aborts the transaction and closes the socket. Similarly the client must send all bytes of the additional data specified in the DATALEN parameter with sufficient speed to prevent timeout between read blocks. This option changes the default timeout period from 30 seconds to Timeout seconds.

-vVerblev

The amount of detail written to the logfile and stderr depends on the verbosity level of the daemon. Each level incorporates the messages in the lower levels; increasing the verbosity level increases the number and types of messages that are written. The verbosity level is an integer ranging from 0 to 25. This flag changes the verbosity level from the default 18 to Verblev.

Table 1-3.

Exit Status

This command returns the following exit values:

Security

The daemon must execute as effective user ID 0 (root). However service children of the daemon reset their user ID to the authentication user ID "invscout". The daemon will not execute unless the user "invscout" has been created on the host system.

By default, an accompanying cleartext password is required from the client for most operations. If the client's password does not match the system password for the authentication user ID "invscout", the action exits with a return code. The authentication user ID cannot be changed.

The LOGICDB action will fail if the data passed from the client can not be authenticated with the IBM inventory scout public key on the local host.

Files

Related Information

The invscout command.