Commands Reference, Volume 3

invscoutd Command

Purpose

Launches a permanent Inventory Scout server daemon.

Syntax

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

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

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=ping\0"

<EOF>

"action=ECHO&MRDM=xyz&datalen=5\0abcde"

"RESULT=0\n"
"\n"
"action=ECHO&MRDM=xyz&datalen=5\n"
"abcde"<EOF>

"action=UrlDecode&subaction=xyz\0"
 

"RESULT=0\n"
"\n"
"  0: ACTION       UrlDecode\n"
"  1: SUBACTION    xyz\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=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>

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

Flags

Specify any arguments, beginning with a hyphen (-). 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.

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

Exit Status

This command returns the following exit values:

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

Files

Related Information

The invscout command.