invscoutd Command

Purpose

Launches a permanent Inventory Scout server daemon.

Syntax

invscoutd [ -o] [ -p Portno ] [ -b Bufsize ] [ -d maxcatsize ] [ -t Timeout ] [ -v Verblev ]

Description

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

Daemon initialization involves reading command line options and several local Inventory Scout companion files. When 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.

The daemon maintains a record of its actions in a log file. 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 the specified verbosity level, startup banners may also be written to stderr.

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 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.

URL-encoded message

The action request string is a standard URL-encoded string. For example:
"ACTION=actionword&NAME1=value1&NAME2&NAME3=word%xx+word+word\0"
Supported Field Names and Values
Name Meaning/Use Supported Values
ACTION See the action request table that follows. The left-hand column of the action request table constitutes a list of supported Values.
MRDM Allows the client to provide a (cleartext) password for any ACTION that uses/requires this information. The value is case sensitive. Any ASCII string (case sensitive).
DATALEN This name must be present if additional binary data immediately follow an ACTION string termination byte, and must be absent if no additional data follow the termination byte. The integer value provided specifies the number of additional data bytes. If the client attempts to write more data than this, 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 the -d command line option). Any integer up to the value implied by the presence or absence of the -d command line option
CLIENT Allows the client to identify itself for any ACTION that uses/requires this information. The HSC value instructs Inventory Scout to allow certain actions that are only allowed when under the control of an HMC Inventory Scout master.
MODEL Allows the client to inform the server of the server's model number for VPD surveys that use/require this information. Any ASCII string of up to 25 characters (restrictions apply with some machines)
SERIAL Allows the client to inform the server of the server's serial number for VPD surveys that use/require this information. Any ASCII string of up to 25 characters (restrictions apply with some machines)
Note:
  1. Field names and their values are separated by equal signs (=).
  2. Name=Value pairs are separated by an & character.
  3. The Name field is always case insensitive.
  4. The Value field is case insensitive, unless documented otherwise.
  5. The ACTION=keyword pair must always be present.
  6. A string between ampersands without an equal sign is parsed as a Name with an Empty value.
  7. Spaces can be represented by + (plus signs).
  8. 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), and + (plus sign) within a Value.
  9. The control character termination byte must always be sent by the client.
Action Requests
Action MRDM Description
PING not required The daemon immediately closes the socket, causing an immediate EOF in the client. This is the only action that does not return a result code or text of any kind. Example:
"action=ping\0"

<EOF>
ECHO not required The daemon returns a text report consisting of the original unparsed request string followed by a linefeed. A password (MRDM) is not required but is echoed if provided, along with everything else. Additional data (DATALEN) is not required but is echoed if present, as is, after the request string. For the ECHO request, DATALEN is silently truncated to a maximum of 2000. Example:
"action=ECHO&MRDM=xyz&datalen=5\0abcde"

"RESULT=0\n"
"\n"
"action=ECHO&MRDM=xyz&datalen=5\n"
"abcde"<EOF>
URLDECODE not required The daemon returns a text report of the request string after parsing, and an exact copy of any subsequent data. A password (MRDM) is not required but is parsed and returned if provided. Additional data (DATALEN) is not required but is parsed and returned if provided; however, any actual additional data beyond the request string is discarded. Each numbered line of the report exhibits one parsed Name=Value pair from the original string. Example:
"action=UrlDecode&subaction=xyz\0"
 

"RESULT=0\n"
"\n"
"  0: ACTION       UrlDecode\n"
"  1: SUBACTION    xyz\n"
<EOF>
TESTPWD required The daemon returns RESULT=0 if the MRDM password is valid. Otherwise it returns RESULT=2. Additional data (DATALEN) is not accepted and is discarded if present. Example:
"ACTION=TESTPWD&MRDM=thepassword\0"
 
"RESULT=0\n"
"\n"
<EOF>
VERSIONS not required The daemon reports the current version numbers of the Inventory Scout itself. Additional data (DATALEN) is not accepted and is discarded if present. Example:
"ACTION=VERSIONS\0"
 
"RESULT=0\n"
"\n"
"1.2.3.4\n"
"5.6.7.8\n"
<EOF>
CATALOG required The daemon updates the scout's microcode catalog file with the file data passed. Both password and the data length parameter must be included in the request string. The daemon does not necessarily have to execute as root for this action but it must have file write permissions to /var/adm/invscout/microcode/catalog.mic. Example:
"ACTION=CATALOG&MRDM=xyz&DATALEN=17042\0"
"...17042 bytes of ascii data..."

"RESULT=0\n"
"\n"
<EOF>
MCODES required The daemon executes the Microcode Survey Option. Additional data (DATALEN) is not accepted and is discarded if present. Example:
"ACTION=MCODES&MRDM=xyz\0"
 
"RESULT=0\n"
"\n"
"Report Line 1\n"
"Report Line 2\n"
    :
    :
"Report Line N\n"
<EOF>
VPDS required The daemon executes the VPD Survey Option. Additional data (DATALEN) is not accepted and is discarded if present. Example:
"ACTION=VPDS&MRDM=xyz\0"
 
"RESULT=0\n"
"\n"
"Report Line 1\n"
"Report Line 2\n"
    :
    :
"Report Line N\n"
<EOF>

Results

The daemon returns a text result in a pseudo MIME format. 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 is always returned for every action, except for the PING action.

Internal scout result codes applicable only to the Java applet client are not documented in the following information.

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.

Result Codes
Result= Description
0 Complete success.
1 Daemon aborted due to memory allocation error. This can happen in either the parent server daemon or one of the service children.
2 Service child daemon aborted because the required password (MRDM=password) was missing or not valid.
3 Service child daemon aborted because the action name-value pair (ACTION=keyword) was missing or not valid.
4 Service child daemon aborted because it was unable to reset its user ID to invscout.
21 Service child daemon aborted due to overflow of socket input buffer. The text report part of the result is a native language error message. Client must reduce the length of the request string, or kill and restart the daemon with an increased buffer size.
22 Service child daemon aborted due to socket read error. The text report part of the result is a native language error message including the system's I/O errno string. A logfile entry will also contain the system's errno string.
23 Service child daemon aborted due to socket read timeout. The text report part of the result is a native language error message. Client must send a control character termination byte after the end of the request string, and must always send as many data bytes as specified in the DATALEN parameter. The timeout period may be changed with the -t command line argument.
24 Service child daemon aborted due to premature EOF while reading request string. The text report part of the result is a native language error message. Client must send a termination byte after the end of the request string before closing the socket connection.
25 Service child daemon aborted due to missing or invalid DATALEN parameter for an action that requires it. The text report pair of the result is a native language error message. Client must send the length of the data for all actions which pass additional binary data beyond the URL-encoded request string. Most such actions also require that the DATALEN value be limited to a specific maximum size.
26 Service child daemon aborted due to regular file I/O error, such as a permissions error, out of disk space, and so on. The text report part of the result is a native language error message. Usually, the I/O problem must be corrected on the server machine before the client can attempt the action again.
27 Service child daemon aborted because it was unable to retrieve the version number for an activity that required it.

Flags

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

Item Description
-o Overwrites an existing logfile. If the -o flag is not specified, new logfile lines are appended to any existing logfile.
-p Portno Changes this server's port number from the default value of 808 to Port.
-b Bufsize Inventory Scout commands are specified as URL-encoded strings read from a TCP/IP socket into a 1024 byte fixed length buffer. The -b flag can change the buffer size to Bufsize bytes if future protocol changes require a larger read buffer.
-d maxcatsize Changes the maximum microcode catalog file size from the default value of 50000 to a value that you specify.
-t Timeout 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. The -t option changes the default timeout period from 30 seconds to Timeout seconds.
-v Verblev 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. The -v flag changes the verbosity level from the default value of 18 to Verblev.
Verbosity Levels
Level Description
0 All error and status messages disabled.
5 Only fatal error messages are written. Fatal errors result in the death of the server. Usually, similar messages are written to both the Logfile and stderr.
10 All error messages are written. These include nonfatal errors such as protocol errors, as well as fatal errors. Nonfatal error messages are usually written only to the Logfile.
15 This level includes startup and shutdown banner messages. Simple banner messages are usually written to both the Logfile and stderr.
18 This level includes call trace status messages. Every client call results in a single trace message. This is the default level for the invscoutd daemon. Trace messages are written only to the Logfile.
20 This level includes program trace messages. Program traces are fairly detailed program execution status messages typically used for debugging purposes. This level is not suitable for usual production execution because over time, it floods the Logfile with large amounts of text. Trace messages are written only to the Logfile.
25 This is the maximum level and includes extensive program debug messages. This level is not suitable for usual production execution. Trace messages are written only to the Logfile.

Exit Status

This command returns the following exit values:

Item Description
0 Indicates successful initialization
Non-zero Indicates unsuccessful initialization

Security

The daemon must execute as effective user ID 0 (root). It is owned by root, and is installed with the "setuid" bit ON so that any user can launch it. At certain execution points, however, service children of the daemon reset their user ID to the authentication user ID invscout. The daemon does 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.

Files

Item Description
/usr/sbin/invscoutd Contains the invscoutd command
/etc/security/password Host system password file
/var/adm/invscout/microcode Directory for microcode-related actions. Default location for microcode catalog file.
/var/adm/invscout/microcode/catalog.mic Default microcode catalog file.
/var/adm/invscout/invscout.log Log file