scotty(1)

NAME
scotty - a tcl interpreter with tcp/ip extensions

SYNOPSIS
scotty [ -c query ] [ -f file ] [ -n ] [ -i ]

DESCRIPTION
scotty is a tcl interpreter with extensions to obtain various status informations about TCP/IP networks which make scotty a nice interpreter for the tkined(1) editor. After startup, scotty evaluates the commands stored in $HOME/.scottyrc.

OPTIONS

-c command
    Process command and exit. This is useful for writing shell scripts.

-f filename
    Evaluate the commands contained in filename.

-n  Don't read the file $HOME/.scottyrc.

-i  Initialize the interpreter to run a script for the tkined(1) editor. This option will set up the correct search path.

TCL COMMANDS
scotty is based on tcl version 7.3 and hence it understands all of the commands provided by tcl 7.3. The following is a description of the extensions provided by scotty.

  GENERAL PURPOSE

getclock [date]
    Return the number of seconds since 1970. This is the same as the getclock command of extended tcl. The optional argument forces getclock to convert date. date should have the format as returned by getdate (see below).

getdate [clock]
    Returns the date in human readable format. The optional argument clock specifies the time in seconds since 1970 which will be converted to a format like 'Tue Apr 26 20:32:23 1994'. The command returns the current date if no argument is given.

sleep time
    Sleep time seconds. This is the same as the sleep command of extended tcl.

select readfileIds [writefileIds] [exceptfileIds] [timeout]
    This command allows a tcl program to wait on zero or more files being ready for reading, writing, have an exceptional condition pending, or for a timeout period to expire. readFileIds, writeFileIds, exceptFileIds are each lists of fileIds, as returned from open, to query. An empty list ({}) may be specified if a category is not used.

    The files specified by the readFileIds list are checked to see if data is available for reading. The writeFileIds are checked if the specified files are clear for writing. The exceptFileIds are checked to see if an exceptional condition has occured (typically, an error). The write and exception checking is most useful on devices, however, the read checking is very useful when communicating with multiple processes through pipes. Select considers data pending in the stdio input buffer for read files as being ready for reading, the files do not have to be unbuffered.

    Timeout is a floating point timeout value, in seconds. If an empty list is supplied (or the parameter is omitted), then no timeout is set. If the value is zero, then the select command functions as a poll of the files, returning immediately even if none are ready.

    If the timeout period expires with none of the files becomming ready, then the command returns an empty list. Otherwise the command returns a list of three elements, each of those elements is a list of the fileIds that are ready in the read, write and exception classes. If none are ready in a class, then that element will be the null list.

  EVENT LOOP

after ms cmd
    The after command allows to enter cmd into scotty's event loop. The command will be executed at global level after ms milliseconds. (This command behaves like tk's after command.)

addinput [-read] [-write] [-exception] fileid cmd
    Associate the callback cmd with fileId. If -read is specified, the callback is run when the file is ready for input. If -write is specified, the callback is run when the file is ready for output. If -exception is specified, the callback is run when an exception occures on fileId. If no flag is specified, then -read is assumed. The following substitutions are performed on cmd.
            %% Replaced with a single percent.
            %F Replaced with the fileid.
            %E Replaced with a list indicating which events occurred.
                 The list will contain one or more of the strings
                 READ, WRITE and EXCEPTION.

removeinput fileid
    Remove the callback from fileid. This must be done before the file is closed.

job create command interval [times]
    The job command allows you to enter tcl commands in a simple job scheduler. This job create command creates a new job consisting of the tcl command that will be invoked every interval milliseconds. The optional argument times sets the number of invocations. The job will automatically removed when it was done times times. The create command returns a jobs identifier (jobid).

job list
    Returns a list of all running jobs. Each job itself is a list of the job identifier (jobid), the command of the job, the interval time, the remaining time til the next evaluation, the max. times the job will be done (0 meaning unlimited) and the job status.

job kill jobid
    Remove the job given by jobid from the job queue.

job schedule
    Invoke the scheduler. This is usually done automatically. This command may be used during long computations since the scheduler is not preemptive.

job status jobid [value]
    Get or set the status of a job.

job command jobid [value]
    Get or set the command of a job.

job interval jobid [value]
    Get or set the interval of a job.

job current
    Get the identifier of the currently running job. An empty string will be returned if no job is running. This command is useful if a job should kill itself when its work is done.

  EVENT LOGGING

syslog level message
    Write message to the system log using priority level. You can use the following levels:

    emergency
        A panic condition. This is normally broadcast to all users.

    alert
        A condition that should be corrected immediately, such as a corrupted system database.

    critical
        Critical conditions, such as hard device errors.

    error
        Errors.

    warning
        Warning messages.

    notice
        Conditions that are not error conditions, but that may require special handling.

    info
        Informational messages.

    debug
        Messages that contain information normally of use only when debugging a program.

  TCP/IP NETWORKING

icmp [options] [query] hosts
    The icmp command can be used to test the availability and the configuration of IP devices. You need the ntping(1) program to use this command since sending icmp packets requires root permissions. ntping must be installed set uid root. The default query type is an icmp echo request send to the given hosts. The command returns a list of host / round trip time pairs. A call of icmp with options and no hosts will change the default settings for the given options. Non default query types are:

    -ttl n
        The ttl option, which may not be supported on every unix system, causes scotty to send an udp packet to an unused port number with the time to live set to n. The result is a list of host / round trip time pairs, where the host is the IP device being n hops away.

    -trace n
        The trace option works similar to the ttl option but it always returns the destination address even when the responding host chooses another interface with a different ip address to send the respond packet. This can be used to trace a route to a host since the command returns the host that discards the packet if it does not reach the recipient.

    -mask
        This query type returns a list of host / netmask pairs. It can be used to locate subnetworks.

    -timestamp
        Ask the hosts for their timestamps.
    The available options are:

    -timeout time
        The timeout time is given in seconds with a default of 5 seconds.

    -retries number
        Unanswered icmp echo request will be resent number times with a default of 2.

    -delay time
        Icmp packets will be send with a minimum delay between successive packets. The default delay is 0 milliseconds. You can change this delay using this option to time milliseconds. Delays are useful to reduce load on intermediate hosts like gateways or bridges.

    -size number
        Set the size of outgoing icmp packets to number bytes. The default packet size is 64 bytes. Sizes smaller than 64 bytes will silently rounded to 64 bytes.

nslook name-or-address
    The nslook command converts a domain name to an ip address or an ip address into a hostname, depending on the given argument. The answer depends on the local system configuration. You will either get a full domain name or a hostname as stored in the /etc/hosts file or in the corresponding YP map.

    All addresses or names as returned by a call to gethostbyaddr() or gethostbyname() are returned in a tcl list.

dns [options] a host
    The dns command sends a query to the domain name system (DNS) resolver for the specified host. The first form of this command asks for the ip address contained in the A record. If host is something like ra.ibr.cs.tu-bs.de, you will get the result 134.169.34.12 134.169.246.34.

dns [options] ptr name
    Send a query for the domain name pointer. Pointer records are used to map an ip address into a fully qualified host name. If name is something like 134.169.34.12, then the result may be RA.IBR.CS.TU-BS.DE.

dns [options] hinfo host
    Retrieve the host information record. If host is something like ra.ibr.cs.tu-bs.de, you will get the result SUN-4/75 SunOS.

dns [options] mx name
    Send a query for a mail exchanger record (MX). If name is a domain name for which an MX record exists, you will get a list of mail exchanger host. For example, when called with the domain name ibr.cs.tu-bs.de, you will get {ra.ibr.cs.tu-bs.de 0} {jupiter.ibr.cs.tu-bs.de 10}.

dns [options] soa name
    Ask the DNS for the start of authority (SOA). If name is something like cs.tu-bs.de, you will get the answer infbssys.ips.cs.tu-bs.de.
    The available options are:

    -server server
        Send the query to the specified server instead to the default server(s) of the system.

    -timeout time
        Set the timeout to time seconds. The default timeout is 2 seconds.

    -retries number
        Set the number of retries to number. The default number of retries is 2. Please note, that the resolver doubles the last timeout after every retry. The meaning of `retries' should be read as `tries'.

ntp host array
    This command sends an ntp version 3 mode 6 request to host and writes status information into array. The array will contain the elements peer.delay, peer.dispersion, peer.offset, peer.precision, peer.reach, peer.srcadr, peer.stratum, peer.valid, sys.peer, sys.precision, sys.refid, sys.rootdelay, sys.rootdispersion, sys.stratum and sys.system. See RFC 1305 for the meaning of these variables.

udp open [port]
    The udp commands described below provide access to the udp protocol. The first one creates a udp datagram socket and associates it with a tcl file handle which will be returned on command completion. The optional argument defines the port number to use. The command will search for an unused port if no port is given.

udp connect host port
    Open a datagram file handle that is connected to host and port. This makes frequent message exchanges faster since there is no need to give the host and port arguments to the send command once the udp file handle is connected to a target.

udp send file [host port] message
    Send a datagram containing message. The host and port arguments may not be used if the udp file handle is already connected to a remote host. If the udp file handle is not connected, you must use these optional arguments to identify the destination of the datagram.

udp receive file
    Receive a datagram from the udp file handle file. This command blocks until a message is received. In most cases, it might be a good idea to check for pending datagrams using the select command first.

udp close file
    Close the udp file handle file.

udp info [file]
    Calling udp info without any arguments returns a list of all tcl file handles that have been created using the udp create command. Info about the current connection of a udp file handle file is returned by using the optional argument. The result is a list containing the source ip address, source port, destination ip address and destination port.

tcp connect host port
    The tcp commands below are used to manage tcp connections. The tcp connect command creates a connection to a remote tcp server. The returned identifier may be used in commands like read, write, gets, puts and close. host gives the name of the host to connect to. port gives the desired port. Even if every socket is opened for both reading and writing, seek must not be invoked between a read and a write.

tcp listen [port]
    A listening tcp socket is set up. If port is empty or 0, then the system will select a port number for you. The returned identifier may be used in commands like accept, shutdown and close.

tcp accept file
    Accepts a connection on an existing server file (created with the tcp listen command) and returns an identifier with may be used in commands like read, write, gets, puts and close.

tcp shutdown file how
    Shutdown a connection for reading, writing or both. If how is "0", "read" or "receives", then further receives on file will be disabled. If how is "1", "write" or "sends", then further sends on file will be disabled and eof will be send on the socket. If how is "2", "all" or "both", then further sends and receives on file will be disabled.

tcp close file
    Close the tcp file handle file.

tcp info file
    Calling tcp info without any arguments returns a list of all tcl file handles that have been created using the tcp listen and tcp connect command. Info about the current connection of a tcp file handle file is returned by using the optional argument. The result is a list containing the source ip address, source port, destination ip address and destination port.

sunrpc info host
    Return a list of all registered Sun RPC services on host. The list elements are strings each containing the program number, program version, protocol name, port number and the name of one RPC service. The command fails, if host is an incorrect name or if the portmapper is not available.

sunrcp probe host program version protocol
    You can test a Sun RPC service using the sunrpc probe command. This calls procedure 0 that simply returns. Additional arguments to sunrpc probe will be ignored allowing one to write simple loops to test all registered RPC services of a host.

sunrpc stat host
    Make a rstat RPC call to host and return a list of name type value triples describing the status of the machine. This command fails if host is not reachable or does not support the rstat service.

sunrpc mount host
    Get a list of all NFS file systems mounted from host.

sunrpc exports host
    Get a list of all NFS file systems exported by host.

sunrpc ether host open

sunrpc ether host

sunrpc ether host close
    Query the etherd daemon. First you have to set up a connection to the etherd on host using sunrpc ether host open. Afterwards you can query the etherd which will return a list of name type value triples describing the packets counted since the last query. You should close the connection using sunrpc ether host close.

  SNMP INTERFACE
Access to the Simple Network Management Protocol (SNMP) version 1 and version 2 is provided by two new tcl commands. The first command handles queries to the MIB definitions and the second is used to create SNMP sessions. All interactions with SNMP agents are done using SNMP session handles. The differences between version 1 and version 2 are mostly hidden by this SNMP implementation (e.g. getbulk requests are mapped to getnext requests and version 1 traps are signalled as version 2 traps) once you have configured a valid session handle.

mib load file
    This command loads the MIB definitions contained in file. The file should contain a valid ASN.1 MIB definition. The builtin parser reads the file and writes a condensed format which will be used by future load commands. Parsing errors are written to stderr.

mib name [-exact] name
    The mib name command returns the shortname of a MIB object. The argument name may be either a name like sysUpTime or an object identifier like 1.3.6.1.2.1.1.3. The -exact switch forces strict lookups where it is not allowed that name contains an instance identifier. For example, mib name 1.3.6.1.2.1.1.3.0 will return sysUpTime.0 while mib -exact name 1.3.6.1.2.1.1.3.0 will fail. Note, that the shortname returned is not unique in all cases.

mib oid [-exact] name
    The mib oid command is the counterpart to mib name and converts a name to the associated object identifier. For example, mib oid sysUpTime.0 will return 1.3.6.1.2.1.1.3.0. If a name is not unique within the loaded MIB definitions, the object identifier of the first matching name will be returned. It is possible to make names unique by prepending portions of the MIB path like mib-2.system.sysUpTime. The -exact option has the same meaning as described for the mib name command.

mib syntax [-exact] name
    The syntax of a mib object is retrieved using the mib syntax command. name is allowed to be either an object name or an object identifier. The syntax returned is the syntax name as defined in the MIB definition. Hence, you will get the syntax DisplayString for sysDescr although it is only a textual convention which is encoded as an octet string. The -exact option has the same meaning as described for the mib name command.

mib description [-exact] name
    The mib description command retrieves the textual description of a MIB object. name is allowed to be either an object name or an object identifier. The -exact option has the same meaning as described for the mib name command.

mib successor [-exact] name
    The mib successor command returns a list of all known successors of the MIB node given by name. name is allowed to be either an object name or an object identifier. The format of the result depends on the format of name: If name is an object identifier, then the result will also be a list of object identifier. A list of names is returned if name is a mib name. For example, mib successor system will return the tcl list "sysDescr sysObjectID sysUpTime sysContact sysName sysLocation sysServices". The -exact option has the same meaning as described for the mib name command.

mib access [-exact] name
    The max-access definition of a mib object given by name can be retrieved using the mib access command. The returned access mode will be one of not-accessible, read-only, read-create, read-write, write-only. The -exact option has the same meaning as described for the mib name command.

mib format name value
    The mib format command can be used to apply textual conventions that are defined for name to value. This is used internally to return readable values from a SNMP request but may be helpful in situations where it is appropriate to format values by hand.

mib scan name value
    The mib scan command implements the reverse operations to mib format and converts a readable value into the underlying format. This may be useful in situations where you are interested to get the primitive value rather than the readable representation. The scan command returns the Ivalueif no textual convention or enumeration applies to name.

snmp session [options]
    The snmp session command creates session handles. All snmp communication is done using session handles. If called without any options, a version 1 session handle to localhost is created. The format of the options is explained in the description of the configure command.

snmp info
    snmp info returns a list of all active sessions.

snmp watch toggle
    This snmp watch command turns hex printing of SNMP packets on or off. This is mostly a debugging aid.
SNMP varbind lists are represented as tcl lists where each list element itself is a list describing one varbind element. A varbind element is usually a triple of the object identifier, the associated type and a value. An example might be {1.3.6.1.2.1.1.5.0 {OCTET STRING} ciscobs.rz.tu-bs.de} {1.3.6.1.2.1.1.7.0 INTEGER 6}. Type conversion is done using very simple rules: All numeric values are converted into numerical tcl values. Octet strings are represented as ASCII hex string where each hex value is separated by a colon, e.g. 6e:61:73:65. Textual conventions containing display hints or enumerations will be applied automatically. Therefore, a DisplayString will be represented as ordinary ASCII text like "nase". A typical example for an enumeration is {ifType.1 INTEGER ethernet-csmacd}. TimeTicks are represented as "0d 7:06:47.82", that is the number of days followed by the hours, minutes, seconds and deci-seconds. Most SNMP commands described below allow asynchronous SNMP operations by providing callbacks, which is nothing more than a tcl command to execute when the answer or and error is received. Some special format characters can be used to access the varbind or other information from the SNMP message. The format escapes are:

    %V  the varbind list (containing name, syntax and value for each varbind)

    %R  the request id

    %S  the session id

    %E  the error status

    %I  the error index

    %A  the network address of the agent

    %P  the port number of the agent

snmphandle configure [options]
    The configure session command can be used to query the current configuration or to change configuration options. The options determine if the session uses SNMP version 1 messages or version 2 messages with or without authentication. The options specific to SNMP version 1 session are:

    -address address

    -port port

    -community string
    The address may be an IP address in dot notation like 134.169.34.1 or a hostname that can be resolved to an IP address. The port argument defines the port on which the agent listens for SNMP messages. The string is the community used to identify the communication peers. The default setup when a new session handle is created is address = localhost, port = 161 and community = public. Options to configure SNMP version 2 sessions are:

    -srcparty {party-oid domain address port messagesize}

    -dstparty {party-oid domain address port messagesize}

    -srcpartyauth {clock lifetime key}

    -dstpartyauth {clock lifetime key}

    -context context-oid
    The remaining options determine the retry and timeout settings and are valid for SNMP version 1 and version 2 sessions:

    -retries number

    -timeout seconds
    A timeout of n seconds means that a SNMP request fails if no answer is received during this time interval. A retry count number means that the message will be resent number times during the seconds timeout interval.

snmphandle get varlist [callback [error-callback]]
    The get session command retrieves the list of instances given in varlist from the agent identified by snmphandle. The varlist must contain the instance identifiers (either as object identifier or as a name that can be resolved to an instance identifier). The syntax and value fields are optional. The following examples all retrieve the same instance: $s get {{sysDescr.0 DisplayString ""}}
    $s get {{1.3.6.1.2.1.1.1.0 DisplayString}}
    $s get sysDescr.0 The first is a complete varlist using a name, the second is a shortened varlist where the value is omitted and the third is a degenerated varlist which just contains an instance name. The degenerated form is very handy and can also be used to retrieve several variables in one request easily: $s get "sysDescr.0 sysName.0 sysContact.0" The get command will be done synchronously if both optional callback arguments are missing. In this case, the command returns the result as a varbind list. If the command contains a callback argument, a request will be send to the agent and the command returns immediately. The result of the command is the request id for this request. The callback will be evaluated from the event loop when a response is received. All format escapes (see above) will be expanded before callback is evaluated: $s get sysDescr.0 {puts "%V"} You can add an error-callback argument to handle errors in a different callback. It will be called from the event loop if the SNMP operation failed for some reason: $s get sysDescr.0 {puts "%V"} {puts "%S(%R): %E"}

snmphandle getnext varlist [callback [error-callback]]
    The getnext session command retrieves the values of the lexicographical successors to the named objects in varlist. To successively retrieve a subtree of the MIB tree, you can put the result of one getnext request into the next getnext request: set jtk [$s getnext system]; puts $jtk
    set jtk [$s getnext $jtk]; puts $jtk Note, that the walk command described below provides a faster and even simpler way to walk tables. The callback and error-callback arguments are used for asynchronous requests as described above.

snmphandle getbulk nr mr varlist [callback [error-callback]]
    The getbulk session command can be used to implement fast table retrieval. The getbulk operation does a getnext on the first nr elements given in varlist. For the remaining elements, the agent is ask to repeat the getnext operation mostly mr times. Note, that SNMP version 1 session will map a getbulk to a getnext request. An example of the getbulk request might be: $s getbulk 1 2 "sysUpTime ifIndex ifDescr" This will return sysUpTime.0 and the values for ifIndex.1, ifDescr.1, ifIndex.2 and ifDescr.2 assuming the device has 2 interfaces and implements snmp version 2. The callback and error-callback arguments are used for asynchronous requests as described above.

snmphandle set varlist [callback [error-callback]]
    The set session command can be used to set SNMP variables. The varbind list should usually contain object identifier, syntax, value triples as described above. Note that it is legal to omit the syntax part if the syntax can be found in the MIB database. This allows shorter argument lists. The following example is a valid set request to set the sysContact to "Bert Nase": $s set [list [list sysContact.0 "Bert Nase"] ] The callback and error-callback arguments are used for asynchronous requests as described above.

snmphandle walk varname varlist body
    The walk session command walks through a whole MIB tree. The command repeats sending getbulk requests using snmphandle until the returned varbind list is not contained in the subtree given by varlist. Foreach valid varbind list, the body is evaluated after the variable given by varname has been set to the actual varbind list. A simple example to walk the interface table may look like: $s walk x "ifIndex ifDescr" { puts $x }

snmphandle trap trapOid varlist
    Send a trap to the destination given by snmphandle. The trap type is defined by the trapOid which should be one of coldStart, warmStart, linkDown, linkUp, authenticationFailure, and egpNeighborLoss (see RFC 1450). The varlist may contain a varbind with additional information. Note, that sysUpTime.0 is appended automatically. However, it is up to the user to provide any required additional varbinds like the ifIndex for linkUp and linkDown traps. $s trap coldStart {{sysDescr.0 "Fridge"}}

snmphandle trapsink callback
    This command installs a trap handler. Traps received by the straps(8) trap forwarder that are valid for snmphandle will invoke the callback procedure. The format escapes described above can be used to get the address of the trap sending device.

snmphandle destroy
    This command destroys snmphandle. It cleans up all data associated with the handle and de-installs all file handlers belonging to this handle.

  SCOTTY'S RPC PROTOCOL

rpc server port
    Set up an RPC server listening an port port. This command returns a rpc handle that be used to register TCL procs that will be exported by a trivial RPC protocol on top of TCP. This RPC mechanism allows us to write cooperating scripts without worrying much about the communication protocol.

rpc client host port
    Connect to the RPC server running on host with port port. The returned client handle can be used to invoke an exported proc on the server host.

rpc delete handle
    Delete a server or a client RPC handle. All connections associated with the handle will be closed.

rpc register rpchandle proc
    Export proc as an RPC callable proc using the server handle rpchandle. Only registered procs can be called by RPC clients.

rpc unregister rpchandle proc
    Remove proc from the list of exported procs on server handle rpchandle.

rpc info rpchandle
    Calling rpc info without any arguments returns a list of all rpc handles that have been created using the rpc server and rpc client command. Info about a specific rpc file handle rpchandle is returned by using the optional argument. The result is a list containing the tcp file handle used for the communication and the list of registered commands for a rpc handle and a list of all files that represent connections to an rpc server. This list is empty if rpchandle belongs to a rpc client.

rpchandle [-async] proc arg1 arg2 ...
    To invoke a remote procedure proc, use the same syntax as used with a local invocation preceeded by a client rpchandle. The result of the remote procedure call will be returned or an error if the underlying communication channel signals errors. The -async options can be used to invoke proc without waiting for it to complete. The async option will never return a result.

SEE ALSO
tkined(1), ntping(1), Tcl(3)

FILES
$HOME/.scottyrc                  startup commands for scotty
/usr/local/lib/scotty/init.tcl    initialization file
/usr/local/lib/scotty/mibs/    archive of MIB files

AUTHORS
Juergen Schoenwaelder (schoenw@ibr.cs.tu-bs.de). The tcp connect, accept and shutdown commands are based on an older version written by Pekka Nikander, Telecom Finland (Pekka.Nikander@ajk.tele.fi) and extended by Tim MacKenzie (tym@dibbler.cs.monash.edu.au). Many thanks to Erik Schoenfelder (schoenfr@ibr.cs.tu-bs.de) who wrote the DNS command and ntping(1). The select command has been adopted from the extended tcl interpreter written by Karl Lehenbauer and Mark Diekhans. The addinput and removeinput commands were inspired by Mark Diekhans addinput for tk. The initial SNMP protocol implementation was done by Sven Schmidt (vschmidt@ibr.cs.tu-bs.de). It was revised and opimized by Juergen Schoenwaelder (schoenw@ibr.cs.tu-bs.de). Erik Schoenfelder (schoenfr@ibr.cs.tu-bs.de) provided code to handle textual conventions and enumerations.