Launches a permanent Inventory Scout server daemon.
invscoutd [ -o] [ -pPortno] [ -bBufsize] [ -tTimeout] [ -vVerblev]
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. 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
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.
The action request string is a standard URL-encoded string. For example:
"ACTION=actionword&NAME1=value1&NAME2&NAME3=word%xx+word+word\0"
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 follows 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 HSC 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) |
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 will be echoed if provided, along with everything else. Additional data
(DATALEN) are not required but will be echoed if present, as is, after the
request string. For the ECHO request, DATALEN will be 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 will be parsed and returned if provided. Additional data
(DATALEN) are not required but will be parsed and returned if provided; however,
any actual additional data beyond the request string will be 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) are not accepted
and will be 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) are not accepted and will
be discarded if present. Example:
"ACTION=VERSIONS\0" "RESULT=0\n" "\n" "1.2.3.4\n" "5.6.7.8\n" <EOF> |
MCODES | required | The daemon executes the Microcode Survey Option. Additional
data (DATALEN) are not accepted and will be 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) are not accepted and will be 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> |
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 always is returned for every action, except 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= | 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. |
Specify any arguments, beginning with a hyphen (-). Space is not allowed between a flag and its value.
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. |
This command returns the following exit values:
0 | Indicates successful initialization |
Non-zero | Indicates unsuccessful initialization |
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 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.
/usr/sbin/invscoutd | Contains the invscoutd command |
/etc/security/password | Host system password file |
/var/adm/invscout/invsd.puk | Name of the Inventory Scout public key file |
/var/adm/invscout/invs.log | Log file |
The invscout command.