From: ARPA%"EVERHART%ARISIA.decnet@GE-CRD.ARPA" 21-JAN-1989 11:44 To: FASTEDDY Subj: FAL$LOG and the like Received: From SCFVM(MAILER) by DFTBIT with Jnet id 3041 for FASTEDDY@DFTBIT; Sat, 21 Jan 89 11:44 EST Received: by SCFVM (Mailer X1.25) id 3039; Sat, 21 Jan 89 11:45:50 EST Date: Fri, 20 Jan 89 16:54:00 EST Reply-To: INFO-VAX@KL.SRI.COM Sender: INFO-VAX Discussion From: EVERHART%ARISIA.decnet@GE-CRD.ARPA Subject: FAL$LOG and the like Comments: To: info-vax%kl.sri.com@RELAY.CS.NET To: "JOHN J. MCMAHON" Since this stuff was asked about, here it is... I got it awhile back and it is VERY UNSUPPORTED. Be cautious in its use as it could go away. However, knowing how to log what FAL is doing can substantially increase your network security against information stealing (and grind up INCREDIBLE amounts of disk and CPU if you're not careful). I advise having a version limit on the directory fal$log points at, just to avoid filling infinite disk. Should be large enough for a few hundred entries min. Don't even THINK of using fal$log=1 unless you're willing to commit to inspecting the results at least daily. Disabling poor man's routing for file accesses has some advantages, but again it depends on your environment. If everyone in a network does it, it reduces the difficulty of figuring out who was trying to copy a file off your system. Also remember: FAL accesses are not used where someone is logged into YOUR system for copying files; the FAL accesses are on the other end. I don't think anyone has any problems with sending this stuff; I got no caveats with it. Glenn Everhart (everhart%arisia.decnet@ge-crd.arpa) ---------------------------------------------------------------------- ; ; INTRODUCTION TO FAL LOGGING ; ; The following describes the format and use of the FAL logging options which ; are specified via the logical names FAL$LOG and FAL$OUTPUT. These are normally ; defined in the user's LOGIN.COM file, but they can be placed in a group or ; system logical name table to affect a larger class of remote file accesses. ; FAL$LOG conveys logging and control directives to FAL and FAL$OUTPUT is used ; to specify the name of the log file to create (in place of SYS$OUTPUT). ; ; NOTE: Use of the logical names FAL$LOG and FAL$OUTPUT by FAL is an UNSUPPORTED ; feature intended as a diagnostic, debugging, and performance monitoring ; tool for use by Digital. The format and function of these logical names ; may change at any time, or perhaps not be used in the future. ; ; NOTE: Logging of information other than file name and statistics (parameter ; bits 0, 1, and 5) can severly reduce data throughput!!! ; ; ; SYNTAX RULES ; ; The primary function of the logical name FAL$LOG is to request the logging of ; various types of information about the file operations performed by FAL. This ; includes identifying each file accessed, displaying the Data Access Protocol ; (DAP) messages exchanged, computing data throughput statistics, and logging ; the logical link and mailbox QIO calls and the subsequent delivery of ASTs. ; Logging operations are requested via the parameter bitmask value. A secondary ; use of the logical name is to specify qualifiers that control various aspects ; of FAL's operation such as determining buffer sizes or disabling features. ; Currently, the format of the FAL$LOG options string is: ; ; [parameter][/qualifier-1,...,qualifier-n] ; ; where each qualifier is of the form keyword=value (e.g., /BPM=20). ; ; The parameter and qualifiers are optional. However, the parameter if present ; must precede any qualifiers. In addition, only the first three characters of ; a qualifier keyword are examined to determine a match. Thus, /DISABLE=xx can ; be addreviated to /DIS=xx. Spaces and tabs are ignored and keywords can be ; be entered using either uppercase or lowercase characters. ; ; ; PARAMETER VALUES ; ; The parameter is a hexadecimal bitmask used to specify FAL logging options. ; If this parameter is non-zero (indicating that FAL logging output will be ; generated), then an attempt is made to translate the logical name SYS$OUTPUT ; prior to opening the log file. If FAL$OUTPUT is defined, then its equivalence ; string is used as the file specification of the log file; otherwise logging ; output is directed to SYS$OUTPUT which normally points to the default network ; log file named SYS$LOGIN:NETSERVER.LOG. The bitmask definitions for the ; parameter are as follows: ; ; bit0 -- enable logging of file name and type of file access requested. ; bit1 -- enable logging of data throughput and other performance ; statistics. ; bit2 -- enable logging of individual DAP messages as they are processed ; from the input buffer or assembled in the output buffer ; bit3 -- enable logging of DAP message packet and mailbox AST routine ; completions. ; bit4 -- enable logging of DAP message packet and mailbox QIO requests. ; bit5 -- enable logging of internal counters. ; ; ; QUALIFIER VALUES ; ; The following qualifiers are recognized where 'd' denotes a decimal digit and ; 'x' denotes a hexadecimal digit: ; ; /DISABLE=xx (Disable FAL Options) where the bitmask value denotes: ; ; bit0 -- disable DAP level CRC checksum generation and comparison. ; (Note that CRC checking will be automatically disabled if the ; initiating node does not support DAP level CRC computation.) ; bit1 -- disable DAP message blocking in both directions (i.e., transmit ; each DAP message in a separate QIO system service call). ; bit2 -- disable RMS multi-block caching to/from disk when block I/O ; file transfer mode is in effect. This restores the pre-VMS V3.4 ; block I/O processing behavior of FAL where each DAP DATA message ; resulted in one RMS $READ or $WRITE call to be executed. Note ; also that selection of this option elimimates one MOVC3 copy ; of the data in memory at the expense of greatly increasing the ; number of RMS I/O operations performed during a file transfer. ; bit3 -- disable poor-man's (or manual) routing (i.e., have FAL reject ; any file specification it receives that contains a node name). ; bits4-7 are undefined. ; ; /ENABLE=xx (Enable FAL Options) where the bitmask value denotes: ; ; bits0-7 are undefined. ; ; /BPM=ddddd (Bytes per Message) this is the maximum number of bytes per DAP ; message to display (used only if parameter bit2 is set). The default ; value is 20 bytes per message. ; ; /BPL=dd (Bytes per Line) this is the maximum number of bytes per line to ; display when dumping a DAP message (used only if parameter bit2 is set). ; The default value is 20 bytes per line. ; ; /RBK_CACHE=ddd (RMS Multi-block Cache Size) this controls the number of disk ; blocks per RMS $READ or $WRITE call to transfer when block I/O file ; transfer mode is selected (if bit2 of the /DISABLE option is set, this ; option is ignored). The number can be from 1 to 127. The default is 64. ; ; /DBS=ddddd (DAP Buffer Size) requests FAL to send this value in the DAP ; Configuration message for the field. ; ; /SYSTEM_ID=xxxx (System Identification) requests FAL to send this value in ; the DAP Configuration message for the fields (the ; OSTYPE field is the low order byte of the value). ; ; /VERSION=xxxxxxxx (DAP Version Number) requests FAL to send this value in ; the DAP Configuration message for the ; fields (the VERNUM field is the low order byte of the value). ; ; /SC1=xxxxxxxx (System Capabilities Part 1) requests FAL to send this value in ; the DAP Configuration message for bits <31-00> of the field. ; ; /SC2=xxxxxxxx (System Capabilities Part 2) requests FAL to send this value in ; the DAP Configuration message for bits <63-32> of the field. ; ; Note that any qualifier that cannot be interpreted or that contains an invalid ; value is ignored and a parse error message is written to the log file. ; ; ; EXAMPLES ; ; The following DCL commands illustrate how FAL logging options may be setup ; in one's LOGIN.COM file. ; ; $ DEFINE FAL$LOG 1 ; ; The above command enables the logging of file name and type of access in ; the default network log file NETSERVER.LOG. ; ; $ DEFINE FAL$LOG 3 ; $ DEFINE FAL$OUTPUT FAL.LOG ; ; This requests the logging of file name, type of acesss, and data throughput ; statistics in SYS$LOGIN:FAL.LOG. ; ; $ DEFINE FAL$LOG "3/RBK_CACHE=16/DBS=1056" ; $ DEFINE FAL$OUTPUT work_disk:[testing]statistics.star_to_galaxy ; ; The above definitions are used to gather data throughput statistics in the ; specified log file while altering buffer sizes. ; ; $ DEFINE FAL$LOG "7/bpm=80 ; ; This definition causes the first 80 bytes of each DAP message to dumped and ; file identification and statistics to be displayed in the log file. ; ; $ DEFINE FAL$LOG 7_50 ; ; Same as the previous example, except the VMS V3.n parameter format of xx_yyyy ; is used where yyyy is the number of bytes per DAP message to display expressed ; as a hexadecimal value. ; ; $ DEFINE FAL$LOG "/DISABLE=8" ; ; This disables poor-man's routing which prevents users from using FAL as a ; pass-through object on this node. ; ; $DEFINE FAL$LOG 2F ; ; This enables all FAL logging options excluding qualifier control options. ;