Veracity Reference Manual - CiteSeerX

Veracity Reference Manual Version 3.4.2a (12 July 2003) for Veracity V3.4.2

Veracity Reference Manual

Version 3.4.2a (12 July 2003) for Veracity V3.4.2

Veracity Reference Manual Version 3.4.2a (12 July 2003) for Veracity V3.4.2

THIS REFERENCE MANUAL provides a concise and precise definition of the functionality of Rocksoftʼs Veracity product. You should refer to this manual when you have specific technical questions about Veracity.

If you are not already familiar with Veracity, you may wish to refer to the Veracity Tutorial Manual which provides a structured introduction to Veracity, along with numerous examples and application-specific information.



Contents1 Architecture 6

1.1 Introduction 61.2 Notation 61.3 Diagnostics 71.4 Pathname Nomenclature 101.5 Absolute And Relative Paths 111.6 An Overview Of Veracity Files 121.7 Pathname Inheritance 131.8 OpenVMS Pathname Processing 142.1 Introduction 162.2 Invoking Veracity 16

2 The OS Command Line Interface 16

2.3 Journal File Argument 172.4 Memory Limit Argument 172.5 Quiet Argument 173.1 Introduction 193.2 Shell Execution 193.3 Shell Macros 203.4 Shell Argument Syntax 213.5 Shell IO Streams 23

4 Veracity Shell Commands 24

4.1 Introduction 244.2 ABSENT 244.3 AGENT 244.4 ATTRIBUTE 254.5 CAPTURE 254.6 CD 254.7 CHECK 254.8 CHKSTATUS 254.9 DEFINE 264.10 DIFF 264.11 DIRECTORY 274.12 ENEO 274.13 EXISTS 284.14 EXIT 284.15 FIXEOLS 284.16 GET 28

4.17 HELP 284.18 HERE 284.19 HEXV 294.20 KEYRING 304.21 LIST 324.22 LS 324.23 MODE 324.24 PWD 334.25 QUIT 334.26 RESTORE 334.27 RUN 334.28 SAVEPOLICY 334.29 SELFTEST 344.30 SERVER 364.31 SETDIR 364.32 SHELL 364.33 SHOWDEFINES 374.34 SHOWDIR 374.35 SHOWSTATUS 374.36 SIGNOFF 384.37 SKIPTO 384.38 SNAPSHOT 384.39 TOLERATE 384.40 TRACE 384.41 TYPE 394.42 VERACITY 394.43 WRITE 39

5 The SNAPSHOT Command 41

5.1 Introduction 415.2 Overview of Arguments 415.3 Arg 1: Target Tree 425.4 Arg 2: Snapshot File 435.5 Arg A: OpenVMS Top Version Switch 445.6 Arg B: Backshot File 445.7 Arg C: Policy File 455.8 Arg D: Default Pathname 465.9 Arg E: Error Limit 475.10 Arg F: Fattening Path 475.11 Arg G: Snapshot Grade 485.12 Arg H: Hex Representation 495.13 Arg K: Snapshot Comment 50



5.14 Arg N: Network Node 515.15 Arg O: Output Canonicalization 565.16 Arg P: Password 565.17 Arg R: Report File 575.18 Arg S: Snapshot File 575.19 Arg T: Target Tree 585.20 Arg U: Load Optimization 585.21 Arg V: Tracing Level 595.22 Arg X: Temporary File 605.23 Arg Y: Reference File 605.24 Examples 61

6 The CHECK Command 63

6.1 Introduction 636.2 Overview Of Arguments 636.3 Arg 1: New Tree 646.4 Arg 2: Old Tree 656.5 Arg A: OpenVMS Top Version Switch 656.6 Arg B: List File 666.6 Arg C: Policy File 676.7 Arg D: Default Pathname 686.8 Arg E: Error Limit 696.9 Arg F: Fuzzy Filename Matching 696.10 Arg G: Snapshot Grade 716.11 Arg P: Password (Old Tree) 726.12 Arg R: Report File 726.13 Arg U: Load Optimization 736.14 Arg V: Tracing Level 746.15 Arg W: Password (New Tree) 746.16 Arg Z: Difference Error 756.17 A Critical Issue 756.18 Examples 76

7 The RESTORE Command 78

7.1 Introduction 787.2 Overview Of Arguments 787.3 Arg 1: Target Tree 797.4 Arg 2: Snapshot File 807.5 Arg C: Policy File 817.6 Arg D: Default Pathname 827.7 Arg E: Error Limit 827.8 Arg G: Snapshot Grade 83

7.9 Arg K: Console Commentary 847.10 Arg P: Password (Old Tree) 847.11 Arg R: Report File 857.12 Arg S: Snapshot File 857.13 Arg T: Target Tree 867.14 Arg U: Load Optimization 867.15 Arg V: Tracing Level 877.16 Examples 88

8 The GET Command 90

8.1 Introduction 908.2 Overview Of Arguments 908.3 Arg 1: Source File 918.4 Arg 2: Destination File or Directory 918.5 Arg B: List File 928.6 Arg N: Network Node 928.7 Arg R: Report File 928.8 Arg Y: Reference File 938.9 Examples 93

9 The AGENT Command 95

9.1 Introduction 959.2 Client/Server Terminology 969.3 Agent Architecture 979.4 Installing A Veracity Agent 999.5 The AGENT RUN Command 1039.6 The AGENT START Command 1049.7 The AGENT STOP Command 1049.8 The AGENT HASHPW Command 1059.9 The AGENT SAVE Command 1059.10 Agent Configuration File 1069.11 Master Agent Settings 1119.12 Virtual Agent Settings 1209.13 Predefined Configuration Files 1329.14 The HAVAL-TEA Security Method 1349.15 The SHA-AES Security Method 1379.16 The SHA-DES Security Method 1409.17 The System Security Method 1439.18 Application Ideas 1469.19 Attack by Replacement 1489.20 Summary Of Agent Security Barriers 148



10 Policy Files 153

10.1 Introduction 15310.2 Policy File Syntax 15310.3 Policy File Comments 15410.4 Policy File Patterns 15510.5 Policy File Spacing 15710.6 Policy File Arrows 15710.7 Policy File Actions 15810.8 Policy File Semantics 15810.9 Policy File Clipping 15910.10 Predefined Policy Files 160

11 Attributes 165

11.1 Introduction 16511.2 How Attributes Are Stored 16611.3 The Name Attribute 16711.4 The Type Attribute 16711.5 The Kind Attribute 16711.6 The Pseudo Attributes 16811.7 Streams 17211.8 Content Attributes 17511.9 Checksums 17611.10 Digests 17711.11 Data Attributes 17811.12 Non-Content Attributes 18011.13 Unix Non-Content Attributes 18011.14 OpenVMS Non-Content Attributes 18311.15 Macintosh Non-Content Attributes 18711.16 MS-DOS Non-Content Attributes 18911.17 Windows NT/2000/XP Non-Content Attributes 19111.18 Novell Netware Non-Content Attributes 19511.19 Symbolic Link Non-Content Attributes 19511.20 Directory Cycle Non-Content Attribute 196

12 Miscellaneous 198

12.1 Introduction 19812.2 Versions 19812.3 Veracity Quick Reference 21112.4 Supported Platforms 21212.5 User Licence 21312.6 AES Licence 219

12.7 Patents 220

13 Installation 221

13.1 Installing Veracity 22113.2 Step 1: Unpack The Distribution File 22113.3 Step 2: Install The Veracity Executable 22213.4 Step 3: Set Protections 22313.5 Step 4: Test The Installation 22313.6 Step 5: Running Veracity 22413.7 Windows Installation 22513.8 VServe 226

Appendix A: Glossary 228

Appendix B: References 236

Copyright 237

Trademarks 237Questions 237Credits 237



1 ArchitectureThis section provides an overview of Veracityʼs high-level architecture. This architecture provides a clean and simple interface between the operating system and Veracityʼs shell and shell commands.

1.1 IntroductionVeracity consists of three main components:

A set of shell commands: These commands accept arguments and perform all the “real” work in the same way that commands in most shells or command interpreters do.

A shell: The Veracity shell encloses the commands and provides a command-line interface to them. This allows command scripts to be executed.

An operating system interface: The Veracity shell is presented at the operating system command interpreter level, allowing Veracity shell commands to be executed directly from the operating system by placing them on the operating system command line after the Veracity command.

This interface allows the user to: • Execute a single Veracity shell command from the operating system shell. • Invoke an interactive session of the Veracity shell. • Execute a file of Veracity shell commands from either the operating system shell or the Veracity shell.

1.2 NotationA variant of EBNF is used to describe syntax. In this variant, literal strings are delimited by double quotes (e.g. “string”), optional constructs by square brackets (e.g. [optional]), and constructs repeated zero or more times by braces (e.g. {zeroormore}). Constructs to be repeated a fixed number of times are enclosed in braces followed by a decimal number (or range) indicating the number of times to be repeated (e.g. {sixtimes}6). Constructs to be repeated one or more times are enclosed in braces and followed by a plus sign (e.g. {oneormore}+). A string enclosed in angle brackets (e.g. <abcd>) represents a selection of exactly one of the enclosed characters. Subtraction of two such sets is set subtraction (e.g. <abcd> - <ab> = <cd>). The traditional BNF “::=” symbol is replaced by the visually simpler “=”. The traditional BNF angle brackets are abandoned. At times, the rules are bent too (as in the definition of punct below), but the meaning should be clear enough.

The following common definitions are assumed: printable = letter | digit | space | punctletter = upper | lowerupper = <ABCDEFGHIJKLMNOPQRSTUVWXYZ>lower = <abcdefghijklmnopqrstuvwxyz>digit = <0123456789>space = “ “punct = <!”#$%&’()*+,-./:;<=>?@[\]^_`{|}~>s = { space }+sz = { space }



1.3 DiagnosticsVeracity defines six diagnostic levels:

Success: No failure of any kind occurred. Processing proceeds normally.

Warning: A warning indicates a minor problem. Warnings have no effect on control flow. Warnings serve mainly to warn the user of particular conditions that might be symptomatic of deeper problems. Example: The snapshot command issues a warning if you specify that a file is a binary file, but it turns out to be a text file.

Error: Error status indicates that a significant problem has arisen, but that the problem does not require that the currently executing command be terminated immediately. A single shell command can generate many errors before terminating. However, when it does terminate, control is transfered to the nearest enclosing interactive shell (or the operating system shell if there is no enclosing interactive Veracity shell). Example: The snapshot command issues an error whenever it cannot read a file in the target directory tree.

Severe Error: A severe error (or “severe” for short) is the same as an error except that Veracity terminates the current command immediately, transfering control to the nearest enclosing interactive shell (or the operating system shell if there is no enclosing interactive Veracity shell). Example: The check command terminates with a severe error if it cannot locate a specified snapshot file.

Fatal Error: A fatal error indicates that Veracity has encountered a problem that prevents it from performing further work. If a fatal error occurs, Veracity aborts directly to the operating system command interpreter. Example: Veracity terminates with a fatal error if it cannot create a journal file (if one was requested).

Assertion Error: An assertion error occurs if Veracity detects an internal inconsistency. If this happens, Veracity terminates immediately and ungracefully, requesting you to report the problem so that it can be fixed. An assertion error implies a defect in Veracity. We hope that such errors will be extremely rare. Example: Veracity might terminate with an assertion error if it notices that a backwards link is inconsistent in a doubly linked list data structure.

Of these, only four represent legitimate diagnostics: warning, error, severe, and fatal. Success is the absence of the other diagnostics, and assertion errors arenʼt supposed to happen!

These six diagnostic levels are most precisely defined by their effect on control flow. A diagnostic can abort the current command, the current script, or the entire Veracity invocation. Each of these effects is immediate except in the case of the error diagnostic which causes the script to be aborted at the end of the execution of the current command.

Command Script(s) VeracitySuccess Warning Error Y Severe Y Y Fatal Y Y Y Assertion Y Y Y



The semantics of various diagnostic statusesVeracity employs six levels of diagnostic severity. While these levels naturally imply a simply hierarchy, their actual semantics are messier and are best specified in terms of their effect on control flow. Success and warning have no effect on control flow. Severe errors and errors cause the enclosing script to abort to the closest enclosing interactive shell (or the operating system shell if no such Veracity shell exists), but errors do not cause this to occur until the current command has finished executing. Fatal and assertion errors terminate Veracity immediately.

Whenever Veracity issues a diagnostic message, it indicates the diagnostic level at the start of the message by giving one of the letters “WESF” (warning, error, severe, fatal). Example:

S: Can’t open input file.

A status is defined to be a set of counters, one for each diagnostic level. Veracity is organized so that each shell command returns a status to its enclosing shell. Eventually control returns to the top shell, which converts the status into a corresponding status understood by the operating system.

The TOLERATE command can be used to prevent a Veracity shell script from being aborted in the event that an error or severe error occurs. In this way, it is possible for a shell to accumulate a number of errors and severe errors without terminating.

Diagnostics To OS Return-Status Mapping

The nature of the mapping between Veracity diagnostic counter status and the status it returns to the operating system (when Veracity terminates) is platform-specific and is defined in the sections below.

Unix

The Unix versions of Veracity returns a natural number that corresponds to the highest-level Veracity diagnostic that has a positive count, as shown in the following table.

0 Success1 Warning2 Error3 Severe4 Fatal5 Assertion

However, in Unix, the bottom 8 bits of exit statuses are used by Unix to indicate whether the program was terminated by a signal. So before presenting a value above to any other entity, Unix multiplies it by 256, yielding the following actual values:

0 Success256 * 1 Warning256 * 2 Error256 * 3 Severe256 * 4 Fatal256 * 5 Assertion

Thus, if Veracity had ten warnings and five errors, it would return 256 * 2 = 512.

So if Veracity ran successfully with absolutely no diagnostics, the exit status will be zero. Otherwise, if you get a value below 256 then this indicates that Veracity was terminated by a signal and you can look up that value somewhere to work out which signal. If you get a value of



256 or greater, then you can be sure that Veracity wasnʼt terminated by a signal, and you should divide the status by 256 to obtain a simple code from one to five.

There appears to be no strong standard that organizes Unix program exit statuses. Section 7.10 of the ANSI C Coding Standard (ISO/IEC 9899:1990) defines the symbols EXIT_SUCCESS (zero) and EXIT_FAILURE (usually 1) which are safe to use, but thatʼs as far as it goes. There is a Unix library called sysexits which attempts to define some standard exit statuses for various error conditions a program can encounter. However this is not a strong or portable standard. In the case of Veracity, it was considered far more important for Veracity users to be able to determine the maximum diagnostic level than it was to attempt to conform to this weak standard.

MS-DOS and Win32

The MS-DOS and Win32 versions of Veracity return a natural number that corresponds to the highest-level Veracity diagnostic with a positive count. Thus, if Veracity had ten warnings and five errors, it would return 2. The following table defines the mapping:

0 Success1 Warning2 Error3 Severe4 Fatal5 Assertion

OpenVMS

The OpenVMS versions of Veracity return a 32-bit OpenVMS status whose severity level corresponds to the highest level of positive diagnostic within Veracity. The following table defines the mapping:

Success=> STS$K_SUCCESSWarning=> STS$K_WARNINGError => STS$K_ERRORSevere => STS$K_SEVEREFatal => STS$K_SEVEREAssertion => STS$K_SEVERE

Veracity ORs these values with 0x10000000L so as to instructs DCL not to generate a message upon termination of Veracity.

Other Operating Systems

On all other operating systems, Veracity returns a simple success status if there were no diagnostics at all, or a simple failure status if there were one or more diagnostics. The values of the statuses returned are the values corresponding to the symbols EXIT_SUCCESS and EXIT_FAILURE as defined by section 7.10 of the ANSI C Coding Standard (ISO/IEC 9899:1990).

#include <stdlib.h>...exit(EXIT_SUCCESS);exit(EXIT_FAILURE);

If you would like Veracity to return a status that more closely reflects the Veracity diagnostics (as with MS-DOS and OpenVMS), please contact Rocksoft.



1.4 Pathname NomenclatureBecause Veracity has to traverse directory trees, it has to manipulate pathnames on a wide range of operating systems. Unfortunately, the various operating systems have slightly different pathname formats and use different terminology to refer to the components of pathnames. As a result, terms such as “pathname” and “path” are not clearly defined in a heterogeneous environment.

aardvark::beetle:[cat.dog.earwig] frog .gnu;6

<ext> <ver>

<------- apath ------><- rpath -> <id> <- ending ->

<------------ path -------------> <----- name ----->

<------ relative pathname ------>

<--------------------- pathname ---------------------->

apath = absolute path

rpath = relative path

id = identifier

ext= extension

ver= version

Components of a “pathname”

The terminology used to refer to components of pathnames varies from operating system to operating system. To avoid confusion, Veracity defines and uses a precise, operating system independent terminology. This figure gives an example of the application of this terminology to a OpenVMS pathname. Note: The absolute and relative paths here are only examples of paths that could be found in this pathname.

To avoid problems with pathname nomenclature, Veracity defines its own structure and terminology for pathnames. This scheme can be applied to most operating systems and provides a strong foundation for dealing with pathnames. Pathnames can be split up into the following components, each of which consists of a string of zero or more characters:

Pathname: This is the term used to describe complete file specifications. A pathname provides a complete absolute specification that identifies a single file. Pathnames are divided into two subcomponents: the path , and the name . This is by far the most significant subdivision of pathnames and is made by parsing from the right in search of the rightmost occurrence of the path-separation character (e.g. / for Unix, ] for OpenVMS).

Path: A path defines a single directory. The term absolute path is a synonym for “path”. Example: In “sloth:d1:[x.y.z]a.b;1” the path is “sloth:d1:[x.y.z]”.

Relative path: A relative path consists of a string giving a list of directories that define a traversal from a directory to itself or one of its child* directories. Example: If “sloth:d1:[x.y.z]a.b;1” exists, one relative path is: “[.y.z]”.

Relative pathname: A relative pathname is the same as a relative path, except that it contains a name component as well. Example: “[.y.z]sloth.dat”.

Name: A name identifies a single file within a directory. The name field may contain a number of subfields, depending on the operating system. For example, Unix does not structure the name field any further, but OpenVMS divides it into three parts. The term “filename” is



synonymous with “name”. Example: In “sloth:d1:[x.y.z]a.b;1” the name is “a.b;1”.

Identifier: The identifier is the essential part of the name and is defined to be everything to the left of the rightmost occurrence of “.”, or the entire name if there is no occurrence of “.”. Example: The identifier of the name “sloth.dat;89” is “sloth ”.

Ending: The ending is defined to be everything at, or to the right of, the rightmost occurrence of “.”, or the empty string if there is no occurrence of “.”. Example: The ending of the name “sloth.dat;89” is “.dat;89”.

Extension: The extension is defined to be the ending less the version. Example: Under OpenVMS, the extension of the name “sloth.dat;89” is “.dat”.

Version: The version is defined to be the suffix of the ending consisting of a semicolon followed by zero or more decimal digits, or the empty string if no such suffix exists. The concatenation of the extension and the version form the ending. Example: Under OpenVMS, the version of the name “sloth.dat;89” is “;89”.

The terminology above refers to specific components of pathnames. In addition, it is useful to be able to describe specifications of components that might contain a full specification of a component, but might also specify some parts in different ways (e.g. using logical names or relative directory specifications), and may omit some subcomponents, leaving them to default. Thus we also have:

Pathname specification: This provides information about a path.

Filename specification: This provides information about a filename.

1.5 Absolute And Relative PathsA key Veracity concept is that of relative and absolute paths. Consider the following directory tree:

usr manager ross work zoo mammals sloths walrae fish

An absolute path of a directory provides a complete path from the root of the file system to the target directory. For example, the absolute path of the manager directory is “/usr/manager/ ”, and the absolute path of the sloths directory is “/usr/ross/zoo/mammals/sloths/ ”.

Relative paths are defined in terms of a particular target directory tree being snapshotted or checked by Veracity. Such target directories are often referred to as the relative root. For example, if the command

$ veracity snapshot /usr/ross/zoo/

were issued, the relative root for the snapshot operation would be the zoo directory. Once the



relative root is defined, we can have relative paths. In this case, the relative path of the sloths directory would be just “/mammals/sloths/ ”, and the relative path of the zoo directory would be “/ ”. For various reasons, Veracity uses a relative path syntax that includes a leading slash. The syntax used in conventional Unix omits the leading slash (mammals/sloths/).

The concept of relative path is very important in Veracity. When Veracity takes a snapshot of a directory, it records only the relative path of each directory in the snapshot file. Similarly, policy file rule patterns specify patterns that match relative, not absolute, paths.

1.6 An Overview Of Veracity FilesIn addition to scanning the files in target directory trees, Veracity reads and writes files called Veracity files. These files are discussed in detail in the sections on the commands that use them. This section provides a complete list of the files so that you know whatʼs out there and can recognize Veracity files on sight.

All Veracity files are ordinary text files and you can always examine them using a text editor. Veracity files can appear in any directory and have any name. However, Veracity has been designed to encourage the user to conform to the naming scheme implemented in its pathname defaulting system. Veracity files usually appear in groups. A group of Veracity files is usually identified by a shared pathname identifier. The different files in the group can then be identified by their extensions. For example, in a directory, you might find:

sloth.vbfsloth.vrfsloth.vsf

The shared identifier (“sloth ”) of these files implies a relationship between them. The varying extensions indicate the differing contents of the files: “.vsf” is the snapshot file, “.vbf” is the previous version of the snapshot file, and “.vrf” is the report file. The table below gives the complete set of extensions for all the different kinds of Veracity files.

Name Nickname In/Out? Extension Policy file In .vpf Snapshot file Snapfile In/Out .vsf Backshot file Backfile In/Out .vbf Report file Out .vrf Journal file Out .vjf Shell file Scriptfile In .vxf Header file Headerfile In .vhf Temporary file Tempfile In/Out .v?f

Veracity files and their extensions

In addition to reading files in target directory trees, Veracity reads and writes Veracity files whose extensions match the pattern “.v%f” (where % represents a single character). Temporary files have the form .v?f (where ? represents a single decimal digit). Veracity files usually appear in groups that share a common filename identifier. Not all of the files in this table will be used in a given run. This table lists every file that Veracity is capable of using. All Veracity files are ordinary text files.

Here is a brief description of each kind of file.



Policy File: This input file is created manually by the user and specifies the checks that Veracity should perform on different parts of the target tree.

Snapshot file: Snapshot files are generated by the snapshot command and compared with a directory tree by the check command. A snapshot file contains information about a single directory tree.

Backshot file: This is the previous “version” of the snapshot file. The “version” here is independent of any versioning system provided by the host operating system. Whenever Veracity writes a new snapshot file, it deletes the old backshot file and renames the previous snapshot file to the backshot file.

Report file: Veracityʼs snapshot and check commands append a report onto the end of the report file. The report file acts as a record of Veracityʼs activity.

Journal file: Journal files contain logs of all console input and output during a single invocation of Veracity.

Script file: Script files contain sequences of Veracity shell commands. Script files can be executed by the Veracity shell.

Header file: Header files contain header comment text to be placed at the start of snapshot files generated by the snapshot command.

Temporary files: Veracity can create and destroy zero or more temporary files having file extensions matching the pattern “.v?f” where “?” is a single decimal digit. The user will usually not be aware of such files, as Veracity renames or deletes them before it terminates. However, if Veracity is interrupted for some reason, or cannot delete the temporary file, the user might find a temporary file in the directory afterwards.

1.7 Pathname InheritanceDuring the execution of a single Veracity command, Veracity can read and write many different files. For example, the snapshot command might read in a policy file, and write out a snapshot file, a backshot file, and a report file. As it would be very tedious for the user to have to specify the names of each of these files explicitly, Veracity provides a sophisticated filepath inheritance scheme. The details of the inheritance varies from command to command. However, the mechanism of inheritance does not. This section describes the mechanism.

For the purposes of inheritance, Veracity structures filenames into four fields: path, identifier, extension, and version (see pathname nomenclature). During the inheritance process, the filepath specification that is inheriting (A) is exposed to another filepath specification (B) and A “inherits” (is assigned) all the non-empty fields in B that are empty in A. For example:

B: Providing : /s/w/teapot.vsf;6A: Inheriting :slothResult : /s/w/sloth.vsf;6

Veracity provides a sophisticated inheritance scheme so as to allow the user to specify as little as possible on the command line. The exact rules of inheritance vary for different arguments of different shell commands. They are described along with each command. However, generally, arguments inherit 1) the argument itself, 2) the constant extension appropriate to the argument



(e.g. .vrf for the +R (report file) argument), 3) the constant identifier 0veracty, 4) the path corresponding to the operating systemʼs “current directory”. The purpose of the “0” in 0veracty is to ensure that the Veracity files appear near the top of sorted directory listings where they can be found. “veracty” is simply short for “veracity” and is necessarily truncated to cater for MS-DOS which permits at most 8-character identifiers.

Each argument of each Veracity shell command has its own inheritance hierarchy. These hierarchies are described in this manual in the form of a column in a table. The table below gives the inheritance hierarchy for the J argument.

Journal=J

.vjf

0veracty

CurDirExample inheritance hierarchy.Each argument of each of Veracityʼs shell commands has its own inheritance hierarchy which is used to provide default values when the argument is not specified, or only partly specified. These inheritance hierarchies are described in this manual in the form of tables. The table above describes the inheritance hierarchy for Veracityʼs J argument. The table indicates that the inheritance for this argument operates as follows. The argument starts with whatever value the user provided on the command line (=J) and is decomposed as a pathname. If the pathname has no extension, the argument “inherits” the extension “.vjf”. Then, if the argument has no file identifier, it inherits the identifier 0veracty. Finally, any pathname fields that are still empty inherit values from the path of the current directory. The final result is used by Veracity as the value of the J argument.

1.8 OpenVMS Pathname ProcessingThe OpenVMS version of Veracity applies standard OpenVMS filename processing ($parse) to each of its filename arguments and then hands the result on to the rest of Veracity as if the result was what appeared on the command line. The translation performed has the following properties:

• The translation is performed in one operation as the very first step in processing an argument. No further OpenVMS-specific filename transformations are performed past this point.

• The translation is performed repeatedly until the device specification is a concrete one (e.g. DKA300:[DAVE] rather than $USERS:[DAVE]). Do not expect any logical names to survive in the final specification.

• Only fields that are explicitly specified will be conveyed to Veracity. Normal OpenVMS full-filepath defaulting is not employed. Thus, if you define a logical name X to be SLOTH.VRF and specify X as a filename argument to Veracity, you will end up with SLOTH.VRF, not DKA300:[DAVE]SLOTH.VRF;. However, the resultant specification SLOTH.VRF will then be fed into whatever defaulting is used for the specific argument for the specific Veracity command, and so the path will be inserted at a later stage anyway (but by Veracity, not OpenVMS).

• Veracity normalizes the path component of the result of the $parse, so that it looks like a sensible, consistent directory specification. For example, if a logical name translated to DKA300:[000000][.WALRUS.SLOTH], Veracity would convert this to DKA300:



[WALRUS.SLOTH].

• If you specify a logical name (such as SYS$HELP) that translates to a list of two or more directory specifications, Veracity uses only the first specification.

• Veracity applies the OpenVMS translation process to the string result of command line arguments. Thus, if you have a logical name REPORT that translates to the name of the desired report file THE_REPORT.TXT, then you could specify (say to the snapshot command) “+rREPORT”.

In summary, Veracity translates OpenVMS file specifications, but does not perform the usual OpenVMS pathname inheritance that most other OpenVMS applications do. Such inheritance is performed explicitly at a later stage by Veracity.

This section describes Veracityʼs command line interface at the operating system (e.g. Unix shell, OpenVMS DCL) level. It explains how to invoke Veracity, and describes Veracityʼs OS-command-line arguments.



2 The OS Command Line Interface

2.1 IntroductionVeracity does not have a GUI. Instead it uses a command line interface that enables it to be ported to a wide variety of platforms and invoked directly from Unix/OpenVMS/MS-DOS/etc shells and scripts.

Veracity does not fully embrace the command line syntax of each host shell. Instead, it parses the OS-shell command line itself, interpreting the arguments to the veracity command as a Veracity shell command. This means that you can use the same syntax to invoke Veracity regardless of the platform you are using. For example, to take a snapshot using the transfer policy file, you could use the following command on any platform:

veracity snapshot +c_transfer

The remaining parts of this section explain how to invoke Veracity and describe OS-command-line-specific arguments.

2.2 Invoking VeracityTo run Veracity, give its name as a command to the host operating systemʼs command interpreter. For example (OpenVMS):

veracity

If no arguments are provided, Veracity writes out a help message and terminates. If one or more arguments are provided, they must collectively conform to the syntax of a Veracity shell command. If the syntax is legal, Veracity will execute the command and terminate. For example, to execute the snapshot command, enter:

veracity snapshot

Thus, the interface that Veracity presents to the operating system command interpreter is the same interface that it presents from its own internal shell; the only difference is that the keyword “veracity” must be provided at the start of operating system command lines.

While the execution of a single command may not seem very powerful, that single command can be the command “shell”, which can trigger off an unlimited number of other actions. If the shell command is given with no arguments, Veracity creates an interactive shell. If the shell command is given with a single argument, that argument must be the name of a Veracity script file which is then executed:

veracity shell -- Interactive.veracity shell doit.vxf -- Script.

Invoking Veracity with no arguments yields a help message. More specific help is also available. veracityveracity help

In addition to the argument shell command, you can specify two arguments (J and Q) to Veracity



that are associated with the entire execution of Veracity rather than the execution of the specific shell command. These arguments are removed before the shell command is executed, so the shell command never sees them. The arguments are discussed in the following sections.

2.3 Journal File ArgumentVeracity provides a facility for capturing all console output produced by Veracity to a file without involving the operating system in the capture. The file is a Veracity file called a journal file and is controlled by the Veracity operating system command-line argument J. If +J is specified on the operating system command line, all output written to the console during the entire invocation of Veracity is written to a file in the current directory called 0veracty.vjf (or the specified file if a specification is given). If a file of the specified name already exists, the output is appended to the file. By default, the argument is set to -J so that no journal file is written. The J argument is subject to the inheritance given in the table below. The J argument can only be specified on the Veracity operating system command line. It cannot be applied to individual shell commands.

Journal=J

.vjf

0veracty

CurDirInheritance hierarchy for the J argument.Veracityʼs J argument takes a file specification string argument to which the inheritance described in this table is applied. The top of the table has the highest priority, and the bottom of the table has the lowest priority.

Example: veracity shell doit +Jcheck_log

2.4 Memory Limit ArgumentVeracity allows you to set a self-imposed limit to the total amount of heap space (malloc()ed) that Veracity will use. If Veracity encounters this limit, it will terminate with a severe error. The limit is specified in kilobytes (1024 bytes) in decimal.

If you do not specify this parameter, it defaults to a high value intended to be encountered only in extreme circumstances. At the time of writing, this limit is set to 50,000K.

Veracity allocates approximately 200K at startup without reference to this limit, so limits smaller than that effectively wonʼt be honored.

Example: veracity snapshot ! Default limit applies.

veracity snapshot +M10000! Limit of about 10M.

veracity snapshot -M ! No limit!

2.5 Quiet ArgumentBy default, when Veracity executes, it writes out a startup message such as the following:



Veracity V3.4 (14-Jan-2003)

---------------------------

Copyright (c) Rocksoft Limited 1992-2003. All rights reserved.

To the extent permitted by law, all liability is excluded,

including contractual, tort and other forms.

It also generates a no-diagnostics message if it is successful. For example, successful execution of the snapshot command results in:

Snapshot successfully taken.

For interactive use, this output serves an important purpose: it assures the user that there really have been no errors. If (e.g. like most Unix commands) Veracity wrote no message upon success, then the user might worry about the possibility that the console output (possibly containing error messages indicating a failed run) has somehow been redirected somewhere, an occurrence that could be disastrous.

However, for batch use, these “success messages” can pose a problem. A user who has constructed a 1000-line command/batch/script file, that includes an invocation of Veracity, may not appreciate Veracity writing a startup and success message. After all, if all the commands in the script file issued success messages, execution of the script would be very “noisy” indeed!

To cater for this need, Veracity provides the operating system command line argument Q (quiet). If you specify +Q on the operating system command line, then Veracity will issue no “success” messages. By default, the argument is set to -Q so that success messages are printed.

Specifying +Q without a quietness level does not suppress any failure messages. If something goes wrong, Veracity will still write a diagnostic message to the console.

In fact there are actually four quietness settings: Normal, Quiet, Hushed, and Silent:

Normal: Normal console output.

Quiet: Same as silent except that a final success message to provide a positive indication of successful completion is written to the console.

Hushed: No console output unless something goes wrong.

Silent: No console output at all .Hereʼs how you can set them:

Examples:-q - Normal.+q - Hushed.+q0 - Normal.+q1 - Quiet.+q2 - Hushed.+q3 - Silent.



3 The Veracity Shell

This section describes the Veracity shell. The Veracity shell is a simple command-line shell that organizes the execution of the Veracity commands that do all the work.

3.1 IntroductionThe Veracity shell is a simple command line interpreter that organizes the execution of one or more Veracity shell commands to be executed. The Veracity shell was created for the following reasons:

1. To enable sequences of commands to be executed. This is a very important feature if the user wants to automate the process of getting Veracity to check many different directory trees.

2. To provide a portable script interpreter whose scripts can be moved from operating system to operating system and run under any implementation of Veracity. Most operating systems provide some kind of command interpreter (e.g. MS-DOS, DCL, csh). However, as they are all different, it is virtually impossible to write a portable script. By providing a single, portable, script interpreter, Veracity provides a consistent environment and enables scripts to be moved between operating systems. In addition provision of a shell is essential on operating systems that do not provide a command interpreter of their own.

3. As a tool to support automated regression testing.

4. As a convenience. A user working on a multi-tasking, multi-window workstation may wish to keep an interactive session of Veracity going in one window rather than having to run Veracity each time it is required.

5. As a convenient vehicle for enclosing utilities. In addition to the main snapshot and check commands, the Veracity shell provides a range of other useful commands.

In short, the Veracity shell provides a portable haven for scripting.

3.2 Shell ExecutionVeracity script files are usually very easy to understand because they do not have any control constructs. When Veracity interprets a script file, it simply reads and executes each line in the file sequentially. The script is aborted only if the exit or quit command is encountered, or if an error-level (or higher) diagnostic occurs.

Each line is processed roughly as follows. Each step processes the result of the previous step.

1. The line is checked for non-printable characters. If there are any, a severe error is generated.

2. All macro substitution variables in the command line are replaced by their corresponding string. The command line is processed from left to right. Substitutions are performed non-recursively.

3. Leading and trailing blanks are removed.



4. If the line is empty, it is ignored and the interpreter moves to the next line.

5. If the first character of the line is “!”, the line is a comment line, is ignored, and the interpreter moves to the next line.

6. The contents of the command line are then parsed in accordance with the command line syntax (shell command arguments).

7. If the zero argument is a prefix of exactly one of the available commands, then that command is executed with the remaining arguments as its arguments. Otherwise a severe error is generated.

8. Add the diagnostic counts (status) returned by the command to the shellʼs diagnostic totals.

9. Examine the status returned by the command. Under various conditions abort to a particular ancestor shell.

3.3 Shell MacrosThe Veracity shell provides a simple macro facility using the character $ as an escape. Thirty-six different macros are defined, having the names $0..$9 and $A..$Z (upper case only). Each macro can hold a string containing zero or more printable characters.

Macros are invoked simply by giving their name in the command line.

Macros can be defined using the define command. The define command takes two arguments. The first is the digit or letter of the macro to be defined. The second is a string to be assigned to the macro. In accordance with the command line parsing rules for Veracity shell commands, the string can be given directly if it does not contain blanks, but must be double quoted if it does. Examples:

define D d1:[users.dave]define 3 /usr/usrs/thisuser/testdirdefine M “This string contains blanks.”

Only the identifying character of the variable being assigned is used in define commands. This syntax is a simple way of preventing the variable from being substituted before it has a chance to be defined!

The macros $0..$9 are also assigned whenever a Veracity shell is created. $0 is assigned the name of the file being executed, and the other digit macros take the value of the arguments. See the section on the SHELL command for more details.

The following points resolve some remaining semantic details:

• There is only one instance of the $A..$Z macros. These macros are global to all shell scripts and modification of a macro within a subshell will affect the value of the macro in all its ancestor and descendant shells.

• A new instance of $0..$9 macros is created for each new shell and initialized with the arguments



to the shell command. The $0 macro takes the name of the script file being executed (in the form that it was specified to the shell command), or <<<interactive>>> if it is an interactive shell.

• If you want to include a dollar sign character in a command use “$$ ”.

• Veracity also defines “$/ ” which translates to the character that separates directory and file name fields in file names on the host machine. The escape “$]” is the same. Examples: Unix=”/ ”, OpenVMS=”]”, Mac=”:”, Windows=”\”, Netware=”\”.

• Veracity also defines “$.” which translates to the character that separates directory names in a directory specification. Examples: Unix=”/ ”, OpenVMS=”.”, Mac=”:”, Windows=”\”, Netware=”\”.

• Veracity also defines “$[“ which translates to the character or characters used to open a relative directory path specification for the filesystem of the host machine. Examples: Mac=”:”, Unix=”./ ”, OpenVMS=”[.”, Windows=”.\”, Netware=”.\”.

• Substitution is not performed iteratively. However, define commands can contain macro calls just as any other command can.

• Use the SHOWDEF command to display the current values of the macros at any time.

3.4 Shell Argument SyntaxThe main step given in the section on shell execution is that of parsing and analyzing the arguments on the command line. A legal command line consists of a finite string of zero or more printable characters that conforms to the following syntax rules. These particular rules assume left to right greedy parsing (they are ambiguous otherwise). So for example, in the raw_arg rule, sign will match an argument beginning with + even though in theory printable_b could too.

command_line = sz arguments szarguments = [ argument ] { s argument }argument = raw_arg | quoted_argraw_arg= [ sign paramname ] { printable_b }quoted_arg= “””” [ sign paramname ]{ printable_q } “”””sign= “-” | “=” | “+”paramname = digit | upper| lowerprintable_b = printable - < >printable_q = printable - <”>

In short, a legal command line consists of arguments consisting of runs of non-blanks separated by blanks, except where an argument commences with a double quote in which case the argument runs to the next double quote. The double quotes of such arguments are not considered part of the argument. This scheme enables the user to provide arguments containing either double quotes or blanks, but makes it impossible to specify arguments containing both double quotes and blanks.

Because some operating systems convert their command line to upper case before handing it to the invoked program, Veracity has been constructed so as to be generally insensitive to the case of its command line arguments. Shell commands may be given in upper case, lower case,



or a mixture of the two. Similarly, arguments such as +J may be given in upper (+J) or lower (+j) case. In this manual, upper case is usually used so as to more clearly distinguish between an argumentʼs letter and its string value (e.g. +Cmypolicy). However, when dealing internally with arguments, Veracity always preserves the case of its command line arguments so that it will be able to operate on operating systems (such as Unix) whose file names are case dependent.

After this parsing process is completed, Veracity has an ordered list of strings that are the command arguments. Each arguments is then classified as either a positional argument or a named argument. Progressing through the list, each argument that does not commence with one of the characters “-=+” is deemed a positional argument and is prepended with the string “+d” where d is a character representing a decimal digit. The first such argument is prepended with “+0”, the second with “+1”, and so on up to the tenth such string. If there are more than ten such strings, a severe error is generated. The following example illustrates the transformation, showing the original, and then the transformed, command line.

teapotsloth +tanchor walrus bunyip+0teapot +1sloth +tanchor +2walrus +3bunyip

At this point each arguments should correspond to the following syntax. If any argument does not, a severe error is generated.

argument = <-=+> arg_char { printable }arg_char = letter | digit

As given above, each legal argument consists of a sign , immediately followed by an identifying case-insensitive character , and a (possibly empty) string .

An argument has two components: an activation (it can be either on or off ) and a string . An argument on a command line has an effect on the argument specified by its character.

So at this stage of the command line analysis we have a list of arguments, each consisting of a sign, a character, and a string. These arguments are “executed” sequentially from left to right, by applying their effect to their corresponding arguments. The sign and the string components of the argument are processed independently . A sign of + turns the argument on. A sign of - turns the argument off. A sign of = leaves the argumentʼs boolean attribute unchanged. The argument string sets the value for the argument, unless the argument string is empty, in which case the argumentʼs value is unchanged. Because Veracity processes its command line arguments from left to right, a later argument can override the effect of an earlier one. Each argument has a default setting which is its initial value when the command line arguments are executed.

Example: The hypothetical command “teapot” has four arguments with the following names and defaults:

ArgumentSignString------------------------1 +“walrus.dat”2 +“sloth.txt”3 -“purple.dat”r -“”x +“command.com”

The following hypothetical Veracity shell command is given: teapot +raardvark zebra -R =2emu “-Xbanana split”



This results in the arguments having the following final settings: ArgumentSignString------------------------0 +“teapot”1 +“zebra”2 +“emu”3 -“purple.dat”r -“aardvark”x -“banana split”

Summary: Veracity shell arguments are separated by blanks except when they are enclosed in double quotes. Each argument is associated with a letter or digit either explicitly, or implicitly by position. Each argument has a boolean sign and a string value. The arguments of the command line are processed from left to right.

3.5 Shell IO StreamsIn addition to the files it reads and writes, Veracity uses two other IO channels: standard input and standard output. These channels are also referred collectively as the console, and are assumed to be interactive. However, there is no reason why they should not be attached to ordinary files using standard IO redirection.

If you wish to invoke Veracity interactively, but still capture the console output, use the Veracity operating system command line journal file argument +J to create a journal file.

Veracity never writes to standard error.

If, for any reason, Veracity is unable to write diagnostic messages to standard output, it terminates to the operating system with failure status.



4 Veracity Shell CommandsThis chapter describes in detail each of the Veracity shell commands available. The SNAPSHOT command, the CHECK command, the RESTORE command and the GET command form the core of Veracity and are described in their own chapters. The AGENT command allows you to run a Veracity agent and has its own chapter too. The remaining commands have been included in Veracity to support the creation of Veracity shell scripts and are described in this chapter.

4.1 IntroductionThis chapter describes the complete set of Veracity shell commands. Some commands, such as snapshot and check, are core Veracity commands that will be used by every user. Other commands, such as define and write, are useful mainly for scripting. Other commands are more obscure and will be used only for particular scripting purposes. Here is the complete set of Veracity shell commands.

shell_command =absent|agent | attribute| capture |cd | check | chkstatus|define | diff | directory|eneo | exists| exit |fixeols| help | here |hexv | keyring | ls |mode | pwd| quit |restore | run| savepolicy |selftest | server| setdir|shell | showdefines | showdir |showstatus | signoff | skipto|snapshot | tolerate | trace |type | write | getveracity

While some of these commands (e.g. the check command) have complex command line interfaces, most of the commands have no arguments or just one argument. For this reason, a legal syntax for each command is given, rather than the more abstract description in terms of arguments. In the syntax, each command name is given in its entirety, but you should be aware that abbreviations are permitted too.

Veracity shell commands return severe status if their arguments are syntactically incorrect or if they are unable to successfully locate or operate on argument files.

4.2 ABSENTThe absent command performs no action except to return a status. If the file specified in its argument doesnʼt exist, it returns success status, otherwise it returns severe status.

Syntax : absent = “absent” s filenameExample: absent deleteme.dat

4.3 AGENTThe agent command is one of the main Veracity commands. It allows you to run a Veracity



network agent and is explained in full detail in a separate chapter on the AGENT command.

4.4 ATTRIBUTEThe attribute command provides a quick and easy way to obtain any particular attribute (or small group of attributes) of a particular file. This command is useful when verifying the transfer of a single file from one machine to another.

The command takes a filename argument, which can optionally be followed by a list of attribute names. If you do not specify any attribute names, you get a default set of attributes. If you specify one or more attribute names, you get only those attributes. By default, signature attributes are printed out in hexadecimal. However, if you specify -H, they will appear in base-64 instead.

Syntax : attribute = “attribute” sfilename { s attname } [ s “-H” ]Example: attribute sloth.datExample: attribute sloth.dat B.md5 R.crc32Example: attribute walrus.txt -H

Note: The Cycle attribute will always be zero when viewed using the attribute command.

4.5 CAPTUREThe capture command enables the user to direct Veracity to append output to standard output (the console) to a specified file. The output is copied and continues to be sent to standard output.

A severe error is generated by capture start if the file cannot be created, or if a capture is already underway.

This command is useful in Veracity shellscripts that wish to capture the result of the execution of just part of a script.

Syntaxcapture = “capture start” filenamecapture = “capture stop”

Examples:capture start log.txtcapture stop

4.6 CDThe cd command is an alias for the SETDIR command.

4.7 CHECKThe check command is one of the main Veracity commands. It is explained in full detail in a separate chapter on the CHECK command.

4.8 CHKSTATUSThe chkstatus command checks the status of the previously executed command in the



current shell. It accepts one or more arguments each of which consists of a letter indicating a diagnostic level, followed by a diagnostic count for that level. The command checks each argument against the diagnostic count of the corresponding level in the status produced by the previous command, and generates a severe error for each argument whose count differs. If all its arguments conform, the command returns success status. In conjunction with the tolerate command, the chkstatus command can be used to check the execution of commands that are expected to produce one or more diagnostics. The command was named chkstatus because if it had been called checkstatus, it would have prevented abbreviation of the check command.

! n is a decimal number.Syntax : chkstatus { Wn | En | Sn }+Example: chkstatus E6 S0

4.9 DEFINEThe define command assigns a string value to one of the thirty-six shell macros. The command takes two arguments, the first being the letter or digit identifying the macro, and the second being the string to be assigned to the macro. Macro names that are letters must be in upper case.

If you want to assign to a macro a string containing one or more blanks, enclose the argument in quotes.

Syntaxdefine = “define” s macroname s stringmacroname = upper | digitExamples:define 3 /usr/usrs/thisuser/define M /user/local/bin/fwdefine Q “The time has come.”

The command interpreter expands the command line before it executes the define command. This allows definitions to be defined in terms of each other statically .

The ten digit macros are local to the currently executing shell, but the twenty-six letter macros are global to all shells.

See the section on macros for more details.

4.10 DIFFThe diff command performs a text comparison of two files and appends the results to a differences file. The command takes three forms.

The first form diff text performs a text-file comparison between its two argument files f1 and f2 and appends a differences report to the differences file diffile stating that the files are identical (if they are) or listing the differences between them if they are different. If the differences file does not already exist, it will be created first. The command returns success status whether or not the files are different with the following exceptions. If the files are different and the +e option is present, the command will return error status. If there is a problem writing to the logfile or reading the input files, it will return severe error status (and will write little or nothing to the differences file). The command writes a line to the console indicating what happened.



The second form diff summary writes a summary of the results of the diff text commands executed.

The third form diff zero zeros the difference counters used to generate differences summaries. Syntax diff = “diff text” f1 f2 diffile [ +e ] diff = “diff summary” diff = “diff zero”Examples: diff text expected.txt actual.txt diff.txt diff text old.dat new.dat log.txt +e diff zero diff summary

4.11 DIRECTORYThe directory command accepts a filename pattern as an argument and writes out a list of matching files in the current directory. Patterns use the same filename syntax as the patterns in policy files. Arguments to this command are treated as case-sensitive on all platforms. To delete files using a case-insensitive pattern, use the & case-sensitivity-modification pattern symbol. Path patterns are not yet supported.

Syntax : directory = “directory” s patternExamples: dir dir *.exe dir &*.EXE

4.12 ENEOThe eneo command takes a single filename argument. If the file does not exist, no action is taken. If the file does exist, it is deleted. In both cases success status is returned. However, if the file exists and cannot be deleted, eneo returns severe status.

As an alternative, a filename pattern may be specified, in which all files in the target directory that match the pattern are deleted. Patterns use the same filename syntax as the patterns in policy files. Arguments to this command are treated as case-sensitive on all platforms. To delete files using a case-insensitive pattern, use the & case-sensitivity-modification pattern symbol. Path patterns are not yet supported. An error is generated if any matching file cannot be deleted.

Syntax : eneo = “eneo” s filename

Examples: eneo deletemeonsight.dat

eneo *.exe

eneo &*.EXE

ENEO stands for Establish the Non Existence Of. Most operating systems provide a command to delete files. Typically these commands are verbs such as “delete”, “remove”, or “kill”. As a consequence, the designers of delete commands usually consider a command to have failed if it fails to find the file or files to be deleted. However, in practice, the delete command is very often used to establish the non-existence of one or more files. A particularly common use of this form is in scripts that, upon starting up, need to “clear the air” before performing their main task. If



certain files are there, they should be deleted. If they are not, then thatʼs OK too.

4.13 EXISTSThe exists command performs no action except to return a status. If the file specified in its single filename argument exists, it returns success status, otherwise it returns severe status.

Syntax : exists = “exists” s filenameExample: exists wombat.dat

See also the absent command.

4.14 EXITThe exit command terminates execution of the current shell. Control is returned to the enclosing shell or, if the current shell is the top-level shell, the operating system command interpreter. The exit command itself always returns success status, but does not cancel out any diagnostics produced during the execution of the shell it is terminating.

Syntax : exit = “exit”Example: exit

4.15 FIXEOLSThe fixeols command converts its argument text file to the local EOL format and the result is written to the 2nd argument file. If there is no 2nd argument, the input file is overwritten.

This command is used to produce portable regression testing scripts. Syntax : fixeols = “fixeols” s filename [ s filename ]Example: fixeols wombat.dat

4.16 GETThe get command is one of the main Veracity commands. It is explained in full detail in a separate chapter on the GET command.

4.17 HELPThe help command provides online help from within the Veracity shell. If no argument is given, a list of the help messages available is given. If a message name is given, and it is unknown, the result is a severe error, otherwise the specified message is displayed. The help command has been designed to provide a handy quick reference of important information. It is not intended to be a comprehensive online help facility.

Syntax:help = “help” [s message_name]Examples:helphelp commands

4.18 HEREThe here command acts as a target for the skipto command. When the shell interpreter



encounters an instance of the skipto command, it skips all the subsequent commands until it encounters a here command. skiptos and heres do not nest.

Syntax : here = “here”Example: here

4.19 HEXVThe hexv (hexadecimal verify) command is a diagnostic command specifically designed to assist in the verification that the check records in Veracity snapshot files contain signatures of the signal bytes of the corresponding spans as specified in the Rocksoft Text Tree Standard.

Veracity snapshot files are designed to be human-readable, and it is possible to mostly confirm by inspection that Veracity snapshot files conform to the conditions of the Rocksoft Text Tree Standard. There are two main aspects of snapshot files for which confirmation cannot be made by inspection. The first is the actual digests themselves, such as the B.md5 digest of a file. To check these, one must apply an independent MD5 program to the file to see if Veracity is generating the correct digest values. The second aspect that canʼt be confirmed by inspection is the set of check records, each of which is supposed to contain the digests of the signal characters in corresponding spans as defined in the Rocksoft Text Tree Standard. The hexv command provides automated support for verifying these by providing a means to dump the spans and their check digests in a readable hexadecimal format that can be compared with the snapshot file, and to check the dumped values for internal consistency.

Command Syntax

The hexv command maintains at all times an internal MD5 digest calculation state that begins when Veracity states up in the MD5 initial state and persists between shell commands. This state is affected only by the hexv command. In addition, the command maintains a stack of up to one other MD5 context.

Here are the forms of the hexv command: hexv traceonhexv resethexv data <one or more bytes in hex>hexv checkmd5 <32 hex digits>hexv pushhexv pop

traceon This command instructs Veracity to append a trace to a file called 0sigchk.txt in the current directory whenever it calculates the check record for a span in a snapshot file. The 0sigchk.txt is a Veracity shell file that contains hexv commands for each byte in the span, and commands to check the MD5 digests of the spans. Use this command in conjunction with the snapshot command. This command is not designed to work with the check command, although it might.

reset This command resets the state of the HEXV commandʼs internal MD5 digest and its stack. After this command, the state is that the internal MD5 digest is reset to its initial state, and the stack is set to empty.

data This command accepts one or more pairs of hex digits and feeds them into the internal



MD5 digest algorithm.

checkmd5 This command accepts an argument of 32 hex digits and compares them with the current internal MD5 digest value. If there is a difference, it outputs an error message.

push This command pushes a COPY of the internal MD5 digest onto a stack. The stack can only hold one copy, so donʼt give this command twice without an intervening pop.

pop Destroys the internal MD5 digest and pops the digest saved on the stack, making it the current digest.

Warning: This command is provided as an informal tool to check the conformance of snapshot files. It is not designed for use in serious applications of Veracity. This command may be renamed or deleted or changed in future versions of Veracity.

Procedure For Verifying Check Records

1. To verify that Veracity is generating the correct check records in a snapshot, give the following commands (or similar) to generate the snapshot and check the calculations of the signature check file.

$ veracity shellVeracity> eneo 0sigchk.txtVeracity> hexv traceonVeracity> snapshot +H +Psesame

Snapshot successfully taken.Veracity> shell 0sigchkVeracity> quit$

2. The commands above dumped the signature calculations into a trace file and then checked the calculations in the trace file. However, the dumped bytes in the trace file might not correspond to the bytes in the correctly defined spans. So, the next step is to get out the Rocksoft Text Tree Standard and the snapshot file itself and check the trace manually to ensure that the trace file lists the bytes in each span exactly as the span is defined in the standard.

3. The final step is to compare the digests in the trace file with the digests in the check records in the snapshot file. Once you have completed all these steps, you have a proof of sorts that the snapshot file contains the correct digests as you have demonstrated 1) that the trace file contains the bytes of the correct spans in the snapshot file, 2) that the trace file signatures are those of the dumped spans, 3) that the signatures in the snapshot file correspond with those in the trace file.

4. There is no need to test the check command because it must be checking all of the check records, and if its calculations were incorrect, it would generate an error. Hence, it must be performing identical calculations to the snapshot command. If you are concerned that the check command is omitting a check altogether, simply use a text editor to modify any part of a span in a way that doesnʼt violate its syntax, and see if the check command picks up the change by issuing an error stating that the spanʼs check record is inconsistent.

4.20 KEYRING



The keyring command provides support for managing client-side Veracity keyrings and client-side encrypted passwords.

Syntax: keyring = “keyring encryptpw” keyring = “keyring encryptpw” “+F”<filename>Examples : keyring encryptpw keyring encryptpw +Fencrypted.txt

Format Of Client-Side Encrypted Passwords

Here is the encrypted form of the password “sesame” encrypted with a password of “walrus”: EncryptedPW-DES-8E3D-189BB2564EF0208D8999A2553F31279B

The first four hex digits are the first two bytes of the double SHA-1 hash of the keyring password. The remaining hex digits are the DES3-CBC encryption of the padded password+CRC. Client-side encrypted passwords are calculated as follows:

1. The password P must be represented in ASCII.

2. The password P must not contain a nul.

3. A nul is appended to the password.

4. If the nul-terminated password is less than 12 bytes, nul pad to 12 bytes.

5. Add zero or more nuls until the total length mod 8 is 4.

6. Calculate and append the CRC-32 of the above in bigendian form. Call result X.

7. Hash the keyring password using SHA-1 and append “PAD4” to yield 24-byte DES3 key Y.

8. Encrypt X using DES3-CBC encryption algorithm with key Y.

9. Convert encrypted result to upper case text hexadecimal.

10. Calculate SHA-1(SHA-1(P)). Take the first two bytes and convert to text hex.

11. Prepend constant string Encrypt-PW-DES.

12. Glue it all together with hyphens. The purpose of the constant string EncryptedPW-DES is to allow encrypted passwords to be fairly reliably distinguished from non-encrypted passwords so that the snapshot command can accept either without you having to specify separately which type of password is being provided.

The 16-bit double SHA-1 hash value is there to make it easy to visibly confirm, if you have a list of encrypted passwords, that all the passwords in the list were encrypted using the same keyring key. (This check is imperfect, but itʼs mainly for visual human assistance).

Note: Client-side encrypted passwords are completely different from the hashed passwords used in agent configuration files. They are not interoperable.



The keyring encryptpw Subcommand

The encryptpw subcommand encrypts a password into an encrypted text form suitable for use by the snapshot command. If you provide no arguments, the command will prompt you interactively for the password to be encrypted and the password with which to encrypt it (called the keyring password). It then writes out the encrypted password and you can cut and paste it where you please.

keyring encryptpw

If you provide the +f argument and a filename, the command works differently. Instead of prompting for the password and keyring password, it obtains these from the following environment variables:

VERACITY_AGENT_PASSWORD VERACITY_KEYRING_PASSWORD

It then writes the encrypted password to the specified filename as a single line. The +f form is useful in client-side Veracity scripts.

4.21 LISTThe list command is used for generating lists of elements important to Veracity users. Only one argument is currently supported: restorable_attributes, which generates a list of the attributes supported by the RESTORE command.

list restorable_attributes

4.22 LSThe ls command is an alias for the DIRECTORY command.

4.23 MODEThe mode command is used during regression testing. During regression testing, it is very convenient to be able to compare output yielded by Veracity from a test with a preprepared correct answer. However, this is made difficult if the output contains dates and times and other such information that varies from run to run. The purpose of this command is to provide a facility to enable the user to throw Veracity into a mode in which it replaces all such variable information with fixed constant strings.

This command goes not guarantee to make Veracity deterministic in all aspects of its operation. Only those parts of Veracity whose indeterminacy have caused problems during regression testing will respond to this command.

Syntaxmode canonicalmode noncanonicalExamples:Veracity> mode canonicalNow in CANONICAL mode (used to support testing).All non-deterministic output will be suppressed.Veracity> mode noncanonicalNow in NONCANONICAL mode (Veracity’s normal mode).



Veracity>

Warning: This command should be used only during Veracity regression testing. It should not be used in production applications of Veracity.

4.24 PWDThe pwd command is an alias for the SHOWDIR command.

4.25 QUITThe quit command terminates Veracity immediately and returns control to the operating system. As a consequence, all currently executing scripts are terminated immediately too.

Syntax : quit = “quit”Example: quit

4.26 RESTOREThe restore command is one of the main Veracity commands. It is explained in full detail in a separate chapter on the RESTORE command.

4.27 RUNThe run command is an alias for the SHELL command.

4.28 SAVEPOLICYThe savepolicy command writes a specified predefined policy file to a specified file. The purpose of this command is to provide you with a starting point for creating your own customized policy file. By saving a predefined policy file, you can start with a working policy file and modify it.

If you specify no arguments, this command will write the default predefined policy file (called “default”) to a file called 0veracty.vpf in the current directory.

If the file to be written already exists, the command will generate an error. This is so as to prevent you from accidentally overwriting an existing policy file.

The command will tolerate a leading underscore in the predefined policy file argument (so as not to confuse those used to the syntax of the snapshot, check and restore commands), but you donʼt need it. If you specify an unknown predefined policy file, the command will list all existing predefined policy files.

Syntax :savepolicy =“savepolicy [ filespec ] [ +c[_]predef ]”Examples:savepolicysavepolicy mypolicy.vpfsavepolicy /usr/dave/mypolicy.vpfsavepolicy +Cskeletonsavepolicy mypolicy.vpf +cvaultsavepolicy mypolicy.vpf +c_vault



4.29 SELFTESTThe selftest command performs some tests on Veracity and generates a severe error if any of them fail. This command is mainly intended to be executed just once when Veracity is installed, but can also be executed now and again as an additional check.

The selftest command is also included in Veracity to enable comparisons to be made between various different algorithms available in Veracity. The selftest command can show the speeds of signature functions, encryption algorithms and compression algorithms.

Syntax : selftest = “selftest compspeed “selftest = “selftest cryptspeed”selftest = “selftest sigspeed”selftest = “selftest policyfiles”selftest = “selftest all”Example: selftest sigspeed

selftest compspeed

If you provide an argument compspeed, the selftest command will dynamically measure the speed of each compression algorithm and write the results to the console. This test requires you to provide a name of a file to use while performing the tests. The reason is that the compression functions will perform differently depending on the data being compressed. For example, you will get much different results compressing text files and executables.

Here is the output from the selftest compspeed command testing the compression algorithms against the Veracity executable and the Veracity sources, executed on 12-Jul-2003 on a 2.2 GHz PC (a Dell PowerEdge 2600) running Windows 2000 Server, for Veracity 3.4.2 compiled under Visual C/C++ 6.0.

Compressing the Veracity source files (text): Compression Speed Test

-----------------------

Measuring the speed of each compression algorithm.

BZip2 compress at1999 K/sec decompress at6045 K/sec ratio 17%

FastGZip compress at 19129 K/sec decompress at 70937 K/sec ratio 27%

GZip compress at8942 K/sec decompress at 78728 K/sec ratio 22%

RLCcompress at 70206 K/sec decompress at 118434 K/sec ratio 85%

Compressing the Veracity executable (binary): Compression Speed Test

-----------------------

Measuring the speed of each compression algorithm.

BZip2 compress at1930 K/sec decompress at4160 K/sec ratio 46%

FastGZip compress at 10350 K/sec decompress at 43578 K/sec ratio 50%

GZip compress at5048 K/sec decompress at 43578 K/sec ratio 47%

RLCcompress at 75272 K/sec decompress at 91999 K/sec ratio 98%

The ratio is the ratio of the compressed file size to the uncompressed file size. The lower the ratio, the better the compression.

selftest cryptspeed



If you provide an argument cryptspeed, the selftest command will dynamically measure the speed of each encryption algorithm and write the results to the console.

Here is the output from the selftest cryptspeed command executed on 12-Jul-2003 on a 2.2 GHz PC (a Dell PowerEdge 2600) running Windows 2000 Server, for Veracity 3.4.2 compiled under Visual C/C++ 6.0.

Cryptography Speed Test

-----------------------

Setting up test data for the tests...

Measuring the speed of each encryption algorithm.

AES-CBC encrypt at 34478 K/second decrypt at 38641 K/second

TEA2-CBC encrypt at 15609 K/second decrypt at 15975 K/second

DES3-CBC encrypt at7121 K/second decrypt at7125 K/second

selftest sigspeed

If you provide an argument sigspeed, the selftest command will dynamically measure the speed of each signature function and write the results to the console.

Here is the output from the selftest sigspeed command executed on 12-Jul-2003 on a 2.2 GHz PC (a Dell PowerEdge 2600) running Windows 2000 Server, for Veracity 3.4.2 compiled under Visual C/C++ 6.0.

Signature Speed Test

--------------------

Setting up test data for the tests...

Measuring the speed of each signature algorithm.

adler at761856 K/second.

crc16 at229376 K/second.

crc32 at188416 K/second.

fleat376832 K/second.

haval34 at 77824 K/second.




ipcat110592 K/second.

lenat least at 4069879808 K/second.

md2at600 K/second.

md4at143360 K/second.

md5at118784 K/second.

chkrw1at188416 K/second.

sha0 at 46195 K/second.

sha1 at 40960 K/second.

sum1 at327680 K/second.



snefru44 at 14576 K/second.




Note: In earlier versions of Veracity, the predefined policy files used the SHA-1 algorithm, as this was perceived as the most secure digest, and security was considered paramount. However, as MD5 is over three times faster and provides very roughly the same level of security, from



Veracity V1.1.3 on, MD5 has been made the default signature algorithm.

selftest policyfiles

If you provide an argument policyfiles, the selftest command will perform a syntax check on all of the predefined policy files. This is useful for the Veracity developers as a final check before releasing a new version.

selftest all

If you specify selftest all, the selftest command will also check each signature algorithm by feeding in predefined data and checking the result against predefined correct answers. This functionality only appears in the debug build of Veracity.

4.30 SERVERThe server command is an alias for the AGENT command.

4.31 SETDIRThe setdir command sets the current working directory.

Syntax : setdir = “setdir” s path

Example: setdir /usr/home/dave/

4.32 SHELLThe shell command suspends execution of the currently executing shell and places control in the hands of a newly created subordinate Veracity shell. If any arguments have been given to the shell command, the first argument is the name of a Veracity shellscript file to be executed by the new shell, otherwise, the new shell is an interactive shell and reads commands from standard input.

The new shell inherits the twenty-six global (letter) macros. In addition, upon entry to the shell, a new instance of the set of ten argument macros $0, $1, ... $9 is created and initialized. $0 is assigned the name of the script file or “<<<interactive>>>” if no arguments were given. $1...$8 are assigned the arguments to the shell that appear after the name of the shellscript file. $9 is always assigned the empty string. If there are fewer than eight arguments after the script file, the extra macros are assigned the empty string.

The shell command can be invoked recursively, allowing shell scripts to call each other. Syntax:shell = “shell” [ s filename { s argument } ]Examples:shell test /usr/vtest teapotshell slothshell

The first example above will cause the execution of the file test.vxf (in the current directory) to be executed as a script, with its digit macros having the values:

$0 = “test”



$1 = “/usr/vtest”$2 = “teapot”$3 = “”...$9 = “”

The second example will execute the shellscript file sloth.vxf in the current directory. The third example creates an interactive shell.

Shells can be nested to at most ten levels, not including the shell implicitly created to execute the shell command on the Veracity operating system command line. Thus if you gave the command veracity shell, you would find yourself in an interactive shell at level 1. Veracity would issue an error if an attempt were made to create a shell at level 11.

The file specification argument to the shell command is subject to the inheritance scheme given in the table below.

Shell=1

.vxf

0veracty

CurDirInheritance hierarchy for the shell command.

Veracityʼs shell command takes a single (optional) file specification argument. The argument takes the form of a pathname structured as 1) a path, 2) a name, 3) an extension, 4) a version (optional). Each argument is constructed by inheriting fields in accordance with this table with the top of the table having the highest priority and the bottom of the table having the lowest priority.

4.33 SHOWDEFINESThe showdefines command writes to the console the current values of the 36 shell macros. Only those macros whose value is not the empty string are listed.

Syntax : showdefines = “showdefines”Example: showdefines

4.34 SHOWDIRThe showdir command displays on the console the value of the current working directory.

Syntax : showdir = “showdir”Example: showdir

4.35 SHOWSTATUSThe showstatus command writes a message to the console giving the number of warnings, errors and severe errors that have been generated 1) by the previous command and 2) during the entire invocation of the current shell.

Syntax : showstatus = “showstatus”Examples: showstatus



4.36 SIGNOFFThe signoff command is just a shorthand for a particular form of the check command. Giving the command signoff arg1 arg2... is syntactically equivalent to giving the command:

check -1 -2.vbf arg1 arg2 ...

The signoff command compares the current snapshot file 0veracty.vsf in the current directory to the previous snapshot file (the “backshot” file) 0veracty.vbf in the current directory. The signoff command is a convenient way of checking what has happened. The idea is that the user execute the snapshot command to record the new state of the target directory tree and then use the signoff command to examine the differences between the old and new tree. In most cases, the changes will be acceptable, and the new snapshot file can become the prevailing snapshot. Use of the signoff command (i.e. comparison of old and new snapshots directly) avoids the “window” of unsafety that can open if you perform a check followed by a snapshot. Hereʼs the syntax for the signoff command.

Syntax: Identical to the CHECK command syntax.Examples:signoffsignoff +R/usr/dave/veracity_report

4.37 SKIPTOThe skipto command operates in conjunction with the here command and causes the shell to ignore all subsequent commands until a here command is encountered. This is like a goto command, except that you can only go forward (to the next here).

Syntax: skipto = “skipto”Examples : skipto

4.38 SNAPSHOTThe snapshot command is one of the main Veracity commands. It is explained in full detail in a separate chapter on the SNAPSHOT command.

4.39 TOLERATEThe tolerate command instructs the shell not to abort processing of the currently executing script if the next command generates one or more warnings, errors, or severe errors. Fatal errors and assertion errors still take effect.

Syntax : tolerate = “tolerate”Example: tolerate

4.40 TRACEThe trace command turns on or off command tracing during script execution. Tracing is useful for debugging large scripts. By default, tracing is turned off.

Syntax:trace = “trace” ( “on” | “off” )Examples:



trace ontrace off

When a new shell is created, it inherits the tracing status of its parent shell. However, parent shells do not inherit the tracing status of their subshells. Thus, if you turn on tracing within a shell, tracing will end when the shell terminates (unless its parent shell also happened to have tracing on too).

4.41 TYPEThe type command displays its argument text file on the console, pausing every screen for RETURN, so as to allow the user to read the file. This command is similar to the type, cat, and more commands of some operating systems, but provides a little extra protection. If the argument file is not a text file, the type command wonʼt attempt to display it. If it is a text file, it will display it but will replace all non-printables (including tabs) by “?”. These precautions avoid the inconvenience caused when oneʼs terminalʼs mode is changed after the accidental display of a non-text file, or of a text file containing unfriendly control characters.

Syntax : type = “type” filespec

Examples: type 0veracty.vrf type report.txt

4.42 VERACITYVeracity commands invoked from the operating system shell need to be prefixed with the veracity verb so as to invoke Veracity to execute the command. For example:

Unix> veracity snapshot

However, from within a Veracity shell, there is no need to prefix the command with veracity. You can just give the command on its own:

Veracity> snapshot

To remind users of this, a command called veracity has been defined that simply writes out a reminder message and generates a severe error. The command accepts any arguments, and completely ignores them.

Syntax: veracity = “veracity” [ anything ]Examples: veracity veracity snapshot veracity check

4.43 WRITEThe write command writes its single argument to the console (standard output), terminating the string with a newline character. As usual, if your argument contains blanks, you can enclose it in double quotes. If you specify +u, an additional line is written containing a sequence of hyphens (-) underlining the text. This feature is useful for headings.

Syntax:



write = “write” s string [ s “+U” ]Examples: write “Now about to start.” write “Welcome to Tester” +u



5 The SNAPSHOT CommandThis chapter is devoted to the snapshot command, which is one of the core Veracity commands. The snapshot command reads a directory tree and writes a snapshot file containing information about the tree. This chapter defines and describes this command.

5.1 IntroductionThe snapshot command reads a directory tree and generates a snapshot file containing information about the tree. The snapshot command accepts many arguments, but you will probably need very few in practice. If you provide no arguments at all:

veracity snapshot

then Veracity will take a snapshot of the directory tree rooted in the current directory, and write a snapshot file to 0veracty.vsf in the current directory. If a snapshot file already exists, it will be renamed 0veracty.vbf (with any existing 0veracty.vbf being deleted). It will also write a report file called 0veracty.vrf in the current directory. The snapshot commandʼs default behavior may be all that you need.

This chapter defines and describes the arguments to the snapshot command. There are also some examples at the end of the chapter.

5.2 Overview of ArgumentsThis page gives an overview of arguments to the snapshot command.

Argument Summary

The table below gives the arguments of the snapshot command. The first column gives the set of legal signs for each argument. The second column gives each argumentʼs letter and its default sign. The third column describes the argument. Most of the arguments take pathname specifications as values using the pathname syntax specific to the host operating system. These values are then passed through an inheritance hierarchy to yield a complete absolute pathname.

Allowed Default Description- = + 1 Equivalent to T.

= 2 Equivalent to S.

- = + -A OpenVMS TopVersions.

= B Backshot file.

- = + -C Policy File.

= D Default pathname.

- = + +E Error limit.

- = + +F Root of fatten tree.

- = + +G Snapshot grade.

- = + -H Signatures in hex.



- = + +K Snapshot comment.

- = + +N Network node.

- = + -O Canonical Output.

- = + -P Password.

- = + +R Report file.

= S Snapshot file.

- = + +T Root of target tree.

- = + -U Load Optimization.

- = + -V Tracing level.

= X Temporary file.

- = + -Y Reference file.

Inheritance Summary

Many of the arguments to the snapshot command accept a pathname specification as an argument value. This value (which may be incomplete) is then passed through an inheritance hierarchy to yield the final pathname.

The following table shows the snapshot commandʼs seven pathname arguments, one per column. Each argumentʼs string argument is treated as a pathname structured as 1) a path, 2) a name, 3) an extension, 4) a version (optional), and the inheritance specified here is applied on a field by field basis, with the top of the table having the highest priority and the bottom of the table having the lowest priority. The notation “=letter” represents any value specified for that argument. The notation “[P]” means that only the path field is inherited.

Target Policy Snap Back Report Reference Temp =T =C =S =B =R =Y .v?f =1 =2 =S, =2 =X .vpf .vsf .vbf .vrf .vsf =S =S =2 =D[P] =D =D =D =D =D =D 0veracty 0veracty 0veracty 0veracty 0veracty 0veracty

CurDir CurDir CurDir CurDir CurDir CurDir CurDir

Thus, for example the table shows that the pathname of the snapshot file generated by the snapshot command will be determined by first taking the string value of the S argument, then inheriting missing fields from the 2 argument (if present), then inheriting the extension .vsf if the extension is absent, then inheriting from the D argument, then inheriting the identifier 0veracty and finally inheriting the current path if the path is still empty at that point.

5.3 Arg 1: Target TreeThe target tree is the directory tree of which the snapshot command takes a snapshot. By default, this is the directory tree rooted in the current directory. However, by using the 1 argument, you can specify it to be any tree. Veracity can be instructed in its policy file to record



different amounts of information about different parts of the tree, but is always bounded to work within the target tree only (as defined by the treeʼs hard links (and symbolic links too if you have instructed Veracity to follow them)).

This argument is equivalent to the T argument, with the T argument having precedence when both are specified.

Remote Snapshots

If you are using Veracityʼs network functionality (see the N argument) to take a snapshot of a directory tree on a remote machine, then no inheriting of this argument occurs and you must specify a complete absolute path in this argument.

Special Remote Snapshot Syntax

If the 1 argument contains the @ character, then the part of the argument to the left of the / character is treated as if it were an argument to the +N argument. This enables you to specify remote snapshots using a single argument. For example:

veracity snapshot dave:[email protected]/home/dave/

If you want to include the @ character in a path argument, use the T argument instead.

Syntax

-1 Specify target tree pathname specification.=1 Specify target tree pathname specification.+1 Specify target tree pathname specification.

Inheritance: =T =1 =D[P] CurDir.

Example

Because this argument is a decimal digit 1, its argument name 1 can be omitted if it appears as the first anonymous argument on the command line.

veracity snapshot /usr/users/veracity snapshot =Rreport +1/usr/users/veracity snapshot dave:[email protected]/home/dave/

5.4 Arg 2: Snapshot FileThe snapshot file is the output file that is the primary result of the snapshot command. It consists of a text file containing information about the target directory tree. By default, the snapshot file is called 0veracty.vsf and is written into the current directory, but using the 2 argument, you can specify it to be any file.

This argument is equivalent to the S argument, with the S argument having precedence when both are specified.

Syntax

-2 Not allowed.



=2 Specify target tree pathname specification.+2 Not allowed.

Inheritance: =S =2 .vsf =D 0veracty CurDir.

Example

Because this argument is a decimal digit 2, its argument name 2 can be omitted if it appears as the second anonymous argument on the command line.

veracity snapshot =2usersnapveracity snapshot =2/sys/snapshots/veracity snapshot /usr/users/ usersnap.vsfveracity snapshot =Rreport /usr/users/ usersnap

5.5 Arg A: OpenVMS Top Version SwitchBy default, under OpenVMS, Veracity sees all versions of all files in the directories it reads. This can be annoying because if you edit a file, creating a new version, Veracity will report a file creation rather than a file change.

If, however, this argument is switched on, Veracity will “see” only the top versions. This feature is useful when you want to treat old versions of files as backups and focus Veracityʼs attention only on the top versions. It is also useful when you want to compare an OpenVMS directory tree with a directory tree on (say) a Unix computer, without having to purge old versions on the OpenVMS machine first.

If you specify +A, Veracity will see only the top versions. However, Veracity always records the complete name of each file and the check command might find itself unable to match up files whose name differs by version number only. (e.g. REPORT.TXT;5 vs REPORT.TXT;6). The solution is to invoke Veracityʼs OpenVMS version number fuzzy filename matching by specifying +Fversion to the check command as well as +A. This instructs Veracity to ignore the version numbers of the filenames when comparing them.

This argument has no effect on non-OpenVMS machines.

Syntax

-A All versions of files visible under OpenVMS.=A No action taken.+A Top versions visible only under OpenVMS.

Default: -A

Exampleveracity snapshot -a ! All versions visible.veracity snapshot +a ! Only top versions visible.

5.6 Arg B: Backshot FileThe backshot file is the previous “version” of the snapshot file. The backshot file is usually called 0veracty.vbf and located in the current directory. When you do a snapshot, the current



backshot file (if any) is deleted and the current snapshot file (if any) is renamed to the backshot file. The presence of a backshot file means that you can use the signoff command to compare a newly created snapshot with the previous snapshot to identify all changes since the last snapshot was taken. The B argument allows you to specify any file as the backshot file.

Note: This argument has been included for completeness, but is almost never used in practice.

Syntax

-B Not allowed.=B Specify backshot file pathname specification.+B Not allowed.

Inheritance: =B .vbf =S =D 0veracty CurDir.

Exampleveracity snapshot =B/sys/backups/snapshots/back.txtveracity snapshot =B/sys/backups/snapshots/veracity snapshot =Boldsnapshotveracity snapshot =B.backshot

5.7 Arg C: Policy FileA policy file is an input text file that is provided by the user. Policy Files determine the kind of information that is to be recorded about different parts of the target tree. For example, a policy file might specify that no information be recorded about a particular subtree except for three critical files for which extra signatures must be recorded. As an alternative to creating and specifying a policy file, the user can select one of a small set of predefined policy files. One of these predefined policy files is the default policy file which is used if no policy file is specified explicitly. For more information on policy files, see the chapter on policy files.

By default, Veracity uses the predefined policy file called default. However, the C argument allows you to specify your own policy file.

The effect of this argument is critically dependent upon its sign. If the sign is negative (“-”), the string component of the argument must be empty, and the default policy file is used. This is the same as specifying “+c _ default”. By default, the sign is negative. If the sign is positive and the first character of the argument is underscore (“_ ”) then the remaining string is treated as the name of a predefined policy file. If the first character is not an underscore, the string is treated as a policy file specification and is subject to the inheritance scheme. If you specify +C then the specified policy file must be found or Veracity will generate an error.

Note: This syntax does not permit the use of user-defined policy files whose first character is an underscore

Syntax

-C Use default policy file.=C Sets user-policy file name only.



+C Use user-supplied policy file.+C_* Use specified (*) predefined policy file.

Inheritance: =C .vpf =D 0veracty CurDir.

Example

The snapshot command uses the predefined policy file default unless you explicitly provide a policy file using +c. Predefined policy files are identified by preceding the predefined policy file name with an underscore.

veracity snapshot -cveracity snapshot +cveracity snapshot +c/usr/users/dave/snapshots/veracity snapshot +cmypolicyveracity snapshot +c.policyveracity snapshot =cmypolicy +cveracity snapshot +c_topveracity snapshot +c_skeleton

5.8 Arg D: Default PathnameBy default, the snapshot command performs all its operations in and on the current directory. However, sometimes thereʼs a need to focus the command on some other directory. The D (default pathname) argument allows you to do that without having to specify the directory to each of the snapshot commandʼs other arguments. Specifying a default pathname specification has much the same effect as setting the current directory to the specified directory for the duration of the execution of the snapshot command

The D argument actually accepts a pathname specification so you can specify the path, the name, the extension, or any combination of these. The other arguments will inherit from these components in accordance with their inheritance schemes.

Syntax

-D Not allowed.=D Specify normal pathname specification.+D Not allowed.

Inheritance: None.

Exampleveracity snapshot =Duserveracity snapshot =D/usr/users/veracity snapshot =D/usr/users/snapshot

In the first example, only the pathname identifier is specified, so Veracity will still operate in and on the current directory, but all the Veracity files will have an identifier of user instead of 0veracty. In the second example, a path is specified and the snapshot command will operate in and on that directory as if it were the current directory. In the third example, both a path and an identifier is specified, and so Veracity will operate in and on the specified directory and will use



the identifier snapshot for the Veracity files it writes there.

5.9 Arg E: Error LimitBy default, the snapshot command writes diagnostic messages to both the report file and standard output (the console). However, sometimes when traversing large file systems, the number of errors can sometimes grow very large and overwhelm the console. The error limit argument solves this problem by allowing you to place an upper bound on the number of diagnostics that can be written to the console. When this limit is exceeded, Veracity will write out a message saying that further messages will be suppressed from the console, and from then on will direct diagnostics only to the report file (if any).

The default is +E100 which means that up to 100 diagnostics will be written to the console and the report file, with further diagnostics being written only to the report file.

Syntax

-E No console error limit.=E Sets error limit value only.+E Imposes specified error limit.

Default: +E100

Exampleveracity snapshot -everacity snapshot +e500

5.10 Arg F: Fattening PathThe fattening path argument is used specifically for the snapshot operation that ʻfattensʼ an existing snapshot file with the data contained in a set of files. These data files must all reside in a single directory, and each file has a name which is the <MD5>.dat (in hexadecimal) of the file in the snapshot whose contents it is supplying.

The F argument specifies the path of the directory that contains this set of data files.

If you specify +F<path> then that parameter specifies that you want fattening to happen and that the MD5 files should be obtained from that directory. For example +Fc:\temp\digests\

The SNAPSHOT command checks the F argument path for syntactic legality up front.

If +F has been turned on, fattening is invoked for a file if:

1. You are taking a snapshot of a snapshot. 2. The snapshot does not contain a B.data attribute for the file. 3. The snapshot contains a B.data.pool attribute for the file.

4. The specified policy file requests B.data for the file. If these conditions hold, Veracity examines the fattening directory and looks for a file with the specified MD5. If it canʼt find it, it issues an error.



Here is an example fattening command: veracity snapshot -1fatten.vsf +cfatten.vpf +F/home/ross/md5/

Content files must have filenames of the following format: EFFFA56C9288CFC40788C7C2F8A299FE.dat

Important: Remember that there are two different policy files in the later stages of Viarius — one with B.data.pool and one with B.data. Note that because of point 4 above, you need to provide the B.data policy file for the fatten operation. This is healthiest because it means that the correct policy file to perform the Restore will be stored in the fat snapshot itself. This is important if you want to do a manual command line Restore without having to look up the policy file separately.

Syntax

-F No fattening.=F Not allowed.+F Specify pathname for fattening files.

Inheritance: None.

Exampleveracity snapshot +Cfatten.vpf +F/usr/users/

In the example, a path is specified and the snapshot command will use fattening files from the directory specified. The policy file must specify the B.data attribute.

5.11 Arg G: Snapshot GradeVeracityʼs snapshot command generates snapshot files that conform to the Veracity Snapshot Standard. This standard (or rather the Rocksoft Text Tree Standard) which it inherits) defines four grades of snapshot file:

Common: Common snapshots contain only a minimum set of features (which are defined in (but are a subset of) the Veracity Snapshot Standard) that all Veracity snapshot readers should be able to read and process. Use this grade for maximum interoperability with other products.

Standard: Standard snapshots contain only features defined in the Veracity Snapshot Standard. Use this grade when you want to be sure that the contents of the snapshot file are defined by the Veracity Snapshot Standard and that snapshot files will be readable by future versions of Veracity. All future versions of Veracity will be able to read standard-grade snapshots generated by all previous versions of Veracity. This makes standard grade snapshots perfect for archival purposes.

Extended: Extended snapshots can contain features that are implemented in Veracity, but which do not yet appear in the Veracity Snapshot Standard. These non-standard features may be altered or improved in future versions of Veracity and this may mean that previously generated snapshots that used those features may not be readable by later versions of Veracity. Use this grade when you are creating non-archival snapshots and want to use the full power of



Veracityʼs features.

Advanced: Advanced snapshots have almost no constraints placed on them and are mainly for experimental and development purposes. They are unlikely to be readable by future versions of Veracity.

The grade of a snapshot file appears in the Grade field in its header record, so you can always tell the grade of a snapshot file by inspection.

The snapshot commandʼs G argument allows you to specify the grade of the snapshot file to be generated. Not only does the specified grade appear in the Grade field of the snapshot file header record, but the snapshot command will issue an error message and will abort the writing of the snapshot file if you attempt to use any Veracity feature that would breach the constraints of its grade. For example, if you specified Standard grade and then specified in the policy file a file attribute that does not appear in the Veracity Snapshot Standard, Veracity would issue an error and abort.

Thus, once you specify a grade, Veracity will protect you from using features that would violate the constraints of that grade and you can be sure that any snapshot file that is generated will conform to the constraints of the grade.

Syntax

Snapshot grade identifiers are specified case-insensitively.

-G Not allowed.=G Specify snapshot standard grade identifier.+G Not allowed.

Default: =gStandard

Exampleveracity snapshot =gCommon

veracity snapshot =gStandard

veracity snapshot =gExtended

veracity snapshot =gAdvanced

5.12 Arg H: Hex RepresentationThe snapshot command is capable of writing the signatures in the snapshot file in a number of forms. By default, it writes the signatures in base-64 form. However, you can use this argument to specify that the signatures by represented in hexadecimal.

Syntax

-H Represent values using base-64.=H No effect.+H Represent values using hexadecimal.



Default: -H

Exampleveracity snapshot +h

5.13 Arg K: Snapshot CommentBy default, the snapshot command writes, at the top of each snapshot file, a header comment describing the nature of the snapshot file and providing information about Veracity. This ensures that if someone who hasnʼt heard of Veracity encounters a snapshot file, they can figure out what it is and how to use it. The check command ignores anything before “?S=====(SNAPSHOT” in a snapshot file, so the comment text doesnʼt affect the usability of the snapshot.

However, sometimes itʼs appropriate to omit the header comment, for example, if space is very important. At other times, it might be appropriate for you to replace the default header comment with your own. The K (for komment :-) argument provides you with these choices.

Syntax

-K No comment will be written.

+K_none No comment will be written.+K_default The default comment will be written.+K Writes 0veracty.vhf as comment.+Ksloth Writes sloth.vhf as comment.

Inheritance: =K .vhf =D 0veracty CurDir.

Default: +K_default

Exampleveracity snapshot -Kveracity snapshot +K_noneveracity snapshot +K_defaultveracity snapshot +Kveracity snapshot +Ksloth

Note: The Veracity Snapshot Standard (or rather the Rocksoft Text Tree Standard to which it refers) sets strict requirements on the text that can appear in a snapshot file. As a consequence of this, Veracity will reject any header comment file that contains non-printables (i.e. not ASCII 32..126 + EOL), that contains a line with trailing blanks, whose last line is not terminated, that contains a line starting with “.” or “-” or “From”, which contains ?+S=====(SNAPSHOT” or ?-S-----(SNAPSHOT)-----”, or which contains a line of more than 76 characters. An additional restriction is that it will reject files containing lines longer than 70 characters (so as to ensure interoperability with PGP whose default is 70). If any of these requirements are breached, Veracity will reject the comment file (generating a severe error) and you should amend your comment file. If you need to prepend some comment text that does not satisfy these conditions, you can specify -K and simply prepend your non-conformant header comment file to the snapshot file after Veracity has finished running. However, this should be a last resort.

Note: The header comment in a snapshot file serves the important purpose of ensuring that



people who encounter the snapshot file can learn about what the snapshot file is, and where a copy of Veracity can be obtained to operate upon the snapshot file. Please think about this issue before specifying -K. If you specify your own header comment, please consider including the URL for Veracity, so that people can at least find out how to use the snapshot.

5.14 Arg N: Network NodeBy default, Veracity takes a snapshot of a directory tree on the computer on which it is running. However, if someone has set up a Veracity agent on a computer on the internet, and your computer is connected to the internet too, you can use the snapshot command to take a snapshot of a directory on the remote computer.

Taking a snapshot of a directory on a remote computer is just the same as taking a snapshot of a directory on the current computer, except that Veracity gets its information about the directory tree from the remote computer. The remote computer provides information only. No files (e.g. snapshot file, report file) are created or deleted on the remote computer. All the Veracity files appear on the current computer.

The N (network node) argument determines whether the snapshot is taken on the current computer or a remote computer. By default, it takes the form -N which instructs Veracity to take a snapshot on the current computer, but if you specify +N followed by information identifying the remote computer, Veracity will attempt to take a snapshot of a directory tree on the remote computer. Hereʼs an example:

veracity snapshot / +Ndave:[email protected]:1234

The argument consists of four fields. vagentid/securitymethod:password@nodename:port

The nodename field is compulsory, but the other fields are optional. The @ is required only if a virtual agent ID and/or password is to be specified. The five fields are described in the following sections.

Virtual Agent ID

Each Veracity agent provides one or more Veracity virtual agents. To take a snapshot of a directory tree on a remote computer, you must identify the virtual agent that you wish to take the snapshot for you. Conceptually, the Veracity agent itself cannot take a snapshot for you; only one of its virtual agents can do that.

Each virtual agent has a Virtual Agent ID (consisting of characters from the set consisting of decimal digits, lower case letters, underscore and hyphen). The term “ID” was chosen rather than “name” so as to avoid confusion with domain names, but a virtual agent ID is really just a name for the virtual agent that uniquely identifies the virtual agent within the set of virtual agents provided by the enclosing Veracity agent. Thus, to uniquely identify a particular Veracity virtual agent in the world, you need a node name, a port number, and a virtual agent ID.

To specify the virtual agent ID field in the N argument, place it before an @. Hereʼs an example of how you might specify a virtual agent with an ID of “dave”:

veracity snapshot / [email protected]



If you explicitly specify the name of a virtual agent, then, if it is present, Veracity will attempt to connect to it, and if it is absent, Veracity will issue an error.

Much of the time, you will not need to provide a virtual agent ID. If you do not specify a virtual agent ID, Veracity will first look to see if the domain name you specified (to identify the computer) is associated with exactly one virtual agent. If it is, it connects to that virtual agent. This feature means that a computer, to which many domain names point, can run a single Veracity agent that contains one virtual agent associated with each domain name. By connecting to the computerʼs Veracity agent using a particular domain name, you implicitly select a virtual agent. For example, if the computer sloth.domain.com was running a single Veracity agent that provided many virtual agents, only one of which was associated with the name sloth.domain.com, then you could just say:

veracity snapshot / +Nsloth.domain.com

If you do not provide a virtual agent ID and it turns out that not exactly one virtual agent is associated with the domain you specified (or if you specified an IP address), Veracity will look for a virtual agent called default and connect to that if it is available (which it may or may not be). Only if a virtual agent called default is not available will Veracity then give up and return an error.

When you connect, Veracity will confirm the ID of the agent to which you have connected.

Security Method

Each Veracity virtual agent has a security method that determines the security handshaking protocol for establishing the connection. The currently supported security methods are:

None: No password is required and no encryption is performed.

HAVAL-TEA: A password is required to access the agent. A sophisticated protocol is used so that the password is never transmitted or disclosed to the agent. The protocol employs the HAVAL hash algorithm and the TEA (Tiny Encryption Algorithm) symmetric encryption algorithm. Once the connection is established, all communication is encrypted using TEA symmetric encryption.

SHA-DES: A password is required to access the agent. A sophisticated protocol is used so that the password is never transmitted or disclosed to the agent. The protocol employs the SHA-1 hash algorithm and the DES3-CBC encryption algorithm. Once the connection is established, all communication is encrypted using DES3-CBC symmetric encryption.

SHA-AES: A password is required to access the agent. Like SHA-DES, a sophisticated protocol is used so that the password is never transmitted or disclosed to the agent. The protocol employs the SHA-1 hash algorithm and the AES-CBC encryption algorithm. Once the connection is established, all communication is encrypted using AES-CBC symmetric encryption.

System: A password is required to access the agent. The password is transmitted from the client to the agent. The agent checks the password against the password of a system account associated with the virtual agent. The communication is encrypted using DES3-



CBC, but with a key that can be derived by watching the entire conversation.

The security method argument allows you to ensure that the agent to which you are connecting uses a particular security method. If you specify a security method argument and the agent does not use that method, then the connection will be aborted.

If you do not specify a security method argument, Veracity will attempt to use whatever security method the agent uses. If the agentʼs method requires a password, then you must have provides a password in the password field.

veracity snapshot / +Ndave/none:[email protected] snapshot / +Ndave/haval-tea:[email protected] snapshot / +Ndave/sha-aes:[email protected] snapshot / +Ndave/sha-des:[email protected] snapshot / +Ndave/system:[email protected]

The security method field can be used to ensure that the password you provide is not provided to the agent at a lower security level than you expected.

Password

Each Veracity virtual agent has a security method that determines whether a password must be provided to connect to the virtual agent and whether the resulting conversation with the agent will be encrypted. The currently supported security methods are described in the security methods section above.

If the virtual agent to which you connect is running the None method, then you do not need to specify a password. However, if it is running the SHA-DES, SHA-AES, HAVAL-TEA or System method, you must provide a password. The most direct way of doing this is to provide it on the command line using the following syntax (sesame is the password):

veracity snapshot / +Ndave:[email protected]

If you specify a password and no password is required, Veracity will generate an error so as to ensure that you arenʼt operating under a false sense of security.

In many cases, you will implicitly select a virtual agent using the domain name, and in those cases you need specify only a password (if the virtual agent requires one):

veracity snapshot / +N:[email protected]

If you include syntax “:” that suggests that a password is involved, but do not provide a password:

veracity snapshot / +Ndave:@domain.com

then Veracity will prompt for a password interactively. This eliminates the chance of your password being picked up by other users using ps -aux listings. On some platforms this feature turns off console echo during password input, which helps conceal your password if you are in a public place.

If you donʼt use the : syntax to provide a password on the command line or interactively, Veracity will look in the environment variable VERACITY_AGENT_PASSWORD for a password. If the environment variable is present, Veracity treats it as if the password had been provided explicitly



on the command line.

The password you provide (in whatever way) may be provided directly (plaintext) or in encrypted form. You can encrypt a password using the keyring encryptpw Veracity shell command. As encrypted passwords have been designed to have a very-recognizable syntax, Veracity will attempt to decrypt if it recognizes that syntax. Hereʼs an example encrypted password. It is the password “sesame” encrypted using the password “walrus”.

EncryptedPW-DES-8E3D-189BB2564EF0208D8999A2553F31279B

If Veracity is given an encrypted password, it will attempt to decrypt it using a keyring password. It first looks for the keyring password in the environment variable:

VERACITY_KEYRING_PASSWORD

If it cannot find it there, it will prompt interactively for the keyring password. The keyring password may not be provided in encrypted form.

The purpose of the encrypted password is to allow Veracity users to construct client-side scripts and systems that do not store agent passwords in plaintext on the disk.

Node Name

The node name field identifies the remote computer to which you wish to connect. This field is compulsory if you specify +N. The node name can take two forms. You can provide a domain name like this:

veracity snapshot / +Ndomain.com

You can also provide an IP address in dotted decimal form like this: veracity snapshot / +N123.4.5.6

If you are concerned about the integrity of the domain name system, you may wish to use the IP address form. However, as a rule, itʼs simpler to use domain names. In particular, the use of a domain name can conveniently allow you to auto-select a Veracity virtual agent without having to provide its ID. See the later section on the agent ID for more information.

Port

When a Veracity agent is running on a computer, it listens for connections on a single TCP port (as do nearly all agents). TCP ports are numbered in the range [0,65535] and it is possible to have more than one Veracity agent running on the same computer, with each agent listening to a different port.

The port field of the N argument allows you to specify which port (and hence which Veracity agent) you want to connect to on the remote computer. The port is expressed in decimal. Hereʼs an example which specifies port 1234:

veracity snapshot / +Ndomain.com:1234

In practice, however, itʼs unlikely that more than one Veracity agent will ever be needed on any one computer, particularly as Veracity supports a virtual agent facility (see the virtual agent ID argument below). So in practice, nearly all computers that are running a Veracity agent will run just one agent, and that agent will listen to just one port. The official Veracity port (as assigned



by the Internet Assigned Numbers Authority (www.iana.org)) is TCP port 1062 (decimal) as shown in the official list of port allocations at: http://www.isi.edu/in-notes/iana/assignments/port-numbers

The port field in the N argument defaults to the official Veracity default port. As almost all computers running Veracity agents run a single agent that listen to the official default Veracity port, you will probably never need to specify the port field.

Directory Path Constraint

If you specify +N to take a snapshot of a remote node, you must specify an absolute target directory path in the 1 or T arguments. There is no defaulting of the 1 or T arguments for network connections.

In the command examples in this page, / (Unix file system root path) is used as a path simply because it is so short. But you should specify an absolute path for the target directory on the remote machine.

Cross-Platform Snapshots

Veracity was designed from the ground up to interoperate between platforms, and as a result, there is no requirement that the remote computer be running the same operating system as the local computer. So it is quite possible to use Veracity on (say) a computer running FreeBSD, to take snapshots of remote computers running Windows NT, OpenVMS, Mac OS X, or any other operating system for which there is a Veracity-compatible agent.

Furthermore, the versions of Veracity for all the supported platforms know about the syntax quirks and file attributes of all the other supported platforms. This means that, from (say) a FreeBSD machine, you can take a snapshot of two remote OpenVMS machines (including all the OpenVMS file attributes) and compare the two snapshots using the Veracity check command.

You can compare snapshots of file systems on different operating systems by using the +F feature of the check command to compensate for the differences in filename syntax. This means that, working from a FreeBSD computer, you could take a snapshot of a remote Windows NT computer and a remote MacOS computer and then compare the two snapshots.

Specification Of The N argument In The 1 Argument

Veracity provides a single shortcut syntax in which you can specify both the virtual agent and the target directory path in the 1 argument. To do this, include an @ in the argument and use the following syntax:

veracity snapshot dave:[email protected]/home/dave/

Syntax

-N Take snapshot on the current computer=N Set network node value .+N Take snapshot on specified remote

computer.



Default: -N

Exampleveracity snapshot / +Ndave:[email protected]:1234veracity snapshot / +Ndomain.comveracity snapshot / +Ndomain.com:1234veracity snapshot / [email protected] snapshot / +Ndave:[email protected] snapshot /home/ +N:[email protected] snapshot @domain.com/veracity snapshot / :[email protected]/home/veracity snapshot [email protected]/home/dave/

5.15 Arg O: Output CanonicalizationThe output canonicalization argument is used to instruct Veracity to canonicalize various aspects of its output for the purpose of differencing and regression testing. The argument takes a string of (case-independent) letters in its string value:

D - Set snapshot file start and finish dates to 01-Jan-1970 00:00.00.S - Set the snapshot file salt to zero.

The argument string must consist of a string of zero or more characters, each being a (case-insensitive) letter. The default is -O (no canonicalization). If you specify +O but do not provide a string, the default is DS.

Syntax

-O No canonicalization.=O Applies default canonicalization.+ODS Generate canonical dates and salts.

Default: -O

Exampleveracity snapshot +OS- Canonicalize the snapshot salt.veracity snapshot +ODS - Canonicalize the snapshot salt and the snapshot start date.

5.16 Arg P: PasswordIf you create a snapshot file and leave it potentially exposed to malicious tampering, an intruder could make some changes to your files and write a new snapshot file that reflects the malicious changes. When you later invoke Veracity to check the files, Veracity would report no changes. For this reason, it is important to protect snapshot files in security applications.

The P argument enables you to detect snapshot file tampering by allowing you to specify a password that will be used to digitally sign the snapshot file. Veracity signs the snapshot file by including B.sha1 digests of the password and parts of the snapshot file. Later, when you check the snapshot file, you can provide the password to the check command to check the snapshot fileʼs password signatures as it is read.



Passwords must consist of a string of zero or more characters, each being a (case-insensitive) letter or decimal digit. The default is -P (no password). If you specify +P but do not provide a password, you will be prompted for one.

Warning: On Unix, the ps command can be used to see the command line of other users, which might allow others to see your snapshot password. If this of concern to you, then specify +P but do not provide a password. You will be prompted for one. An alternative is to run Veracity in interactive mode (Veracity shell) and then give the snapshot +Psesame command from within the Veracity shell.

Syntax

-P No password used.=P Set password value.+P Use specified password.

Default: -P

Exampleveracity snapshot +Psesame later...veracity check +Psesame

5.17 Arg R: Report FileWhen the snapshot command executes, by default, it appends a report of its run to a report file which is usually called 0veracty.vrf and located in the current directory. The R argument determines whether a report file is generated, and where.

Syntax

-R Donʼt generate report.=R Specify report pathname spec.+R Append report to specified report file.

Inheritance: =R .vrf =D 0veracty CurDir.

Exampleveracity snapshot -rveracity snapshot +rmyreportveracity snapshot +r/user/dave/reports/veracity snapshot +r/user/dave/reports/latest.txtveracity snapshot +r.txt

5.18 Arg S: Snapshot FileThe snapshot file is the output file that is the primary result of the snapshot command. It consists of a text file containing information about the target directory tree. By default, the snapshot file is called 0veracty.vsf and is written into the current directory, but using the S argument, you can specify it to be any file.

This argument is equivalent to the 2 argument, with the S argument having precedence when



both are specified.

Syntax

-S Not allowed.=S Specify target tree pathname specification.+S Not allowed.


Exampleveracity snapshot =Susersnapveracity snapshot =S.snapveracity snapshot =S/sys/snapshots/veracity snapshot =S/sys/snapshots/newsnap.txt

5.19 Arg T: Target TreeThe target tree is the directory tree of which the snapshot command takes a snapshot. By default, this is the directory tree rooted in the current directory, but using the T argument, you can specify it to be any tree. Veracity can be instructed in its policy file to record different amounts of information about different parts of the tree, but is always bounded to work within the target tree only (as defined by the treeʼs hard links (and symbolic links too if you have instructed Veracity to follow them)).

This argument is equivalent to the 1 argument, with the T argument having precedence when both are specified.

Syntax

-T Specify target tree pathname specification.=T Specify target tree pathname specification.+T Specify target tree pathname specification.


Exampleveracity snapshot =T/usr/users/veracity snapshot =Rreport =T/usr/users/

5.20 Arg U: Load OptimizationVeracity runs can be very IO intensive because, during a typical run, Veracity reads and snapshots/checks files as fast as it can. On slower machines this can cause the machine to spend a lot of time in the kernel (presumably servicing IO calls for Veracity), even when the priority of the process running Veracity is explicitly lowered using, for example, the Unix nice command. One Veracity user reported that running Veracity in the background on an Intel 486



caused the machine to spend 40% of its time in the kernel. When Veracity wasnʼt running, the machine ran fine.

This kernel-slamming effect suggests that Veracity is very efficient as, despite its reduced CPU allocation (niced), Veracity is processing the content of files so quickly that it can place sufficient IO calls to keep the kernel busy in the kernelʼs own (non-niced) time!

To allow Veracity to be run in the background without slamming the kernel, Veracity provides the U argument in its snapshot and check commands. By default, the argument is turned off (-U), but if you specify +U, then Veracity will introduce a constant real-time delay just before it reads each directory or file in the target tree.

In Veracity V2.1, if you specify +U, the default delay is 200 milliseconds, which applies an upperbound of five files a second for the snapshot command. This default is likely to be changed in future versions of Veracity to cater for the ever changing processor and disk speeds.

To specify your own custom delay, provide a non-negative integer in the argument, specifying it in milliseconds. For example, to introduce a one second delay between files, you would specify +U1000.

Note: The +U feature is currently implemented only in Unix versions of Veracity.

Syntax

-U No delay.+U Applies default delay.+Un Applies specified delay.

Default: -U

Exampleveracity snapshot ! No delay.veracity snapshot +u ! The default delay.veracity snapshot +u500 ! Half a second delay.veracity snapshot +u1000 ! One second delay.

5.21 Arg V: Tracing LevelBy default, the snapshot command does not provide any progress indicator as it traverses a directory tree. The V argument enables you to specify that the snapshot command generate trace messages as it progresses through the tree.

Note: Veracity only traces those directories and files that it is processing as specified in the policy file.

Syntax

-V No tracing.=V Set tracing level if on.+V Trace directories.



+V1 Trace directories.+V2 Trace directories and files.

Default: -V

Exampleveracity snapshot -v ! No tracing.veracity snapshot +v ! Trace directories.veracity snapshot +v1! Trace directories.veracity snapshot +v2! Trace dirs and files.

5.22 Arg X: Temporary FileWhen the snapshot command writes a new snapshot, it does so to a temporary file. Upon successful completion, it renames the temporary file to the snapshot file (after having deleted the backshot file and renamed the snapshot file to the backshot file). The X argument allows you to specify any file as the temporary file. By default, the temporary file is a file in the current directory of the form 0veracty.v?f where ? is a decimal digit.

Note: This argument has been included for completeness, but is almost never used in practice because the argumentʼs inheritance scheme always defines a sensible place for the temporary file.

Syntax

-X Not allowed.=X Specify temp file pathname specification.+X Not allowed.

Inheritance: .v?f =X =S =2 =D 0veracty CurDir.

Exampleveracity snapshot =Xtempveracity snapshot =X.tmpveracity snapshot =X/sys/snapshots/temp/veracity snapshot =X/sys/snapshots/temp.txt

5.23 Arg Y: Reference FileWhen the network version of the snapshot command executes, the remote agent must send the entire snapshot file to the monitoring client. The use of a reference file at the receiving end allows the Blocklets (tm) protocol to dramatically reduce the amount of data that must be transmitted during the transaction. The Y argument specifies where the reference file can be found.

The argument takes the negative form by default.

The argument cannot take the negative form AND have a non-empty string value.

It is an error for the argument to take the positive form during a non-network snapshot.

The positive form is an instruction that the Blocklets protocol MUST be used during the network



snapshot operation. If the agent does not support the Blocklets protocol, then the snapshot command will fail.

The argument should be a file specification for a text file to be read in as a reference snapshot for the Blocklets protocol. There is no constraint on this fileʼs contents at all. The contents can be white noise. However, the more similar the contents of the reference file are to the snapshot being transmitted, the more efficient the Blocklets protocol will make the transmission.

Syntax

-Y Donʼt use reference file.=Y Specify reference file pathname spec.+Y Use specified reference file.

Default: -Y


Exampleveracity snapshot -yveracity snapshot +yprevsnapveracity snapshot +y/user/dave/snapfiles/veracity snapshot +y/user/dave/snapfiles/latest.vsfveracity snapshot +y.txt

5.24 ExamplesThis section provides examples of the use of the snapshot command.

snapshotIf no arguments are given, the tree that is snapshotted is the one whose root is the current directory. The default policy file is used, which means that the entire tree will be recorded using the B.md5 attribute. The snapshot file is written in the current directory to 0veracty.vsf and a report file is written in the current directory to 0veracty.vrf.

snapshot =DwalrusThis is the same as the previous example except that the snapshot and report files will be written to walrus.vsf and walrus.vrf.

snapshot =D/usr/users/dave/work/This is the same as setting the current directory to the specified directory before the snapshot command and restoring the current directory afterwards.

snapshot =D/usr/users/sloth

In this example, the default argument has provided both a path and an identifier. As a result, the target directory will be the userʼs directory, and the snapshot and report files will be written to /usr/users/sloth.vsf and /usr/users/sloth.vrf instead of 0veracty.vsf and 0veracty.vrf in the current directory.

snapshot =T/usr/users/dave/work/ =Dwork

In this example, the target directory has been changed, but the Veracity files will be read from and written to the current directory using the identifier work.



snapshot /usr/users/dave/work/ /usr/usrs/dave/log/

The first argument is the target tree; the second is the snapshot file specification which, in this case, consists of just a path. This means that the snapshot file will be written to /usr/usrs/dave/log/0veracty.vsf. The report file will be written to the current directory.

snapshot +C_transfer

Same as no arguments except that the selection of the predefined policy file “transfer” means that the snapshot records the A.md5 signature instead of the B.md5 signature.

snapshot +C

Same as no arguments except that Veracity reads and uses the policy file “0veracty.vpf” from the current directory. If Veracity canʼt read the file, it will generate an error.

snapshot =S/snapshots/worktree

Takes a snapshot of the tree rooted in the current directory and writes it to /snapshots/worktree.vsf. The report file is written to 0veracty.vrf in the current directory.



6 The CHECK CommandThis chapter is devoted to the check command, which is one of the core Veracity commands. The check command compares two trees (real or as recorded in a snapshot file) and writes a report describing their differences. This chapter defines and describes this command.

6.1 IntroductionThe check command compares two directory trees and writes a report describing the differences between them. Each tree can be either an actual directory tree, or a snapshot file (as generated by the SNAPSHOT command). The two trees being compared are referred to as the old tree and the new tree so as to enable the check command to refer to them clearly.

The check command accepts many arguments, but you will probably need very few in practice. If you provide no arguments at all:

veracity check

then Veracity will compare the directory tree rooted in the current directory with the tree described by the snapshot file 0veracty.vsf in the current directory. The differences it finds will be displayed on the console and appended to a report file called 0veracty.vrf in the current directory. The check commandʼs default behavior may be all that you need.

This chapter defines and describes the arguments to the check command. There are also some examples at the end of the chapter.

6.2 Overview Of ArgumentsThis page gives an overview of arguments to the check command.

Argument Summary

The table below gives the arguments of the check command. The first column gives the set of legal signs for each argument. The second column gives each argumentʼs letter and its default sign. The third column describes the argument. Most of the arguments take pathname specifications as values using the pathname syntax specific to the host operating system. These values are then passed through an inheritance hierarchy to yield a complete absolute pathname.

Allowed Default Description- = + +1 Newtree. - = + -2 Oldtree. - = + -A OpenVMS TopVersions. - = + =C Policy File. = D Default pathname. - = + +E Error limit. - = + -F Filename matching method. - = + +G Snapshot grade. - = + -P Password for snapshot file for old tree. - = + +R Report file. - = + -U Load optimization. - = + -V Tracing level. - = + -W Password for snapshot file for new tree. - = + -Z Difference error.



Inheritance Summary

Many of the arguments to the check command accept a pathname specification as an argument value. This value (which may be incomplete) is then passed through an inheritance hierarchy to yield the final pathname.

The following table shows the check commandʼs six pathname arguments, one per column. Each argumentʼs string argument is treated as a pathname structured as 1) a path, 2) a name, 3) an extension, 4) a version (optional), and the inheritance specified here is applied on a field by field basis, with the top of the table having the highest priority and the bottom of the table having the lowest priority. The notation “=letter” represents any value specified for that argument. The notation “[P]” means that only the path field is inherited. The inheritance for the parameters 1 and 2 differ depending on the signs of the parameters.

NewTree OldTree -1 +1 -2 +2 Policy Report

=1 =1 =2 =2 =C =R

“.vsf” “.vsf” “.vpf” “.vrf”

=D =D[P] =D =D[P] =D =D

0veracty 0veracty 0veracty 0veracty CurDir CurDir CurDir CurDir CurDir CurDir

Thus, for example the table shows that the pathname of the report file generated by the check command will be determined by first taking the string value of the R argument, then inheriting the extension .vrf if the extension is absent, then inheriting from the D argument, then inheriting the identifier 0veracty and finally inheriting the current path if the path is still empty at that point.

A key feature of the check command is that it can compare any combination of snapshot files and real directory trees. All four combinations are possibly by specifying a sign (“-” (snapshot file) or “+” (directory tree)) to the 1 and 2 arguments. The defaulting hierarchy differs for these arguments depending on their sign and so four columns of defaulting are needed in this table. +1 and -2 are in bold as these are the default signs for these two arguments.

6.3 Arg 1: New TreeThe check command accepts two trees as arguments, the old tree and the new tree, each of which can be either an actual tree or a snapshot file. The 1 argument allows you to specify the new tree.

By default, the new tree is the actual directory tree rooted in the current directory.

Syntax

The sign of this argument determines whether you are specifying a snapshot file (-1) or an actual tree (+1) (the default).

-1 New tree is the specified snapshot file.=1 Modify specification.+1 New tree is the specified actual tree.

Inheritance: (for -1) =1 .vsf =D 0veracty CurDir.



Inheritance: (for +1) =1 =D[P] CurDir.

Example

The 1 argument can be provided in the +1 form (the default form) which specifies a real tree, or -1 which specifies a snapshot file. Because this argument is a decimal digit 1, its argument name 1 can be omitted if it appears as the first anonymous argument on the command line (and you want to specify a real tree).

veracity check /usr/users/veracity check +Rreport +1/usr/users/veracity check -1/usr/users/dave/snapshotveracity check -1snapshot.txtveracity check -1

6.4 Arg 2: Old TreeThe check command accepts two trees as arguments, the old tree and the new tree, each of which can be either an actual tree or a snapshot file. The 2 argument allows you to specify the old tree.

By default, the old tree is the snapshot file 0veracty.vsf residing in the current directory.

Syntax

The sign of this argument determines whether you are specifying a snapshot file (-2) (the default) or an actual tree (+2).

-2 Old tree is the specified snapshot file.=2 Modify specification.+2 Old tree is the specified actual tree.

Inheritance: (for -2) =2 .vsf =D 0veracty CurDir.

Inheritance: (for +2) =2 =D[P] CurDir.

Example

The 2 argument can be provided in the +2 form which specifies a real tree, or the -2 form which specifies a snapshot file (the default form). Because this argument is a decimal digit 2, its argument name 2 can be omitted if it appears as the second anonymous argument on the command line (and you want to specify a snapshot file).

veracity check /usr/users/ snapshot.txtveracity check +Rreport +2/usr/users/veracity check -2/usr/users/dave/snapshotveracity check -2oldsnapshot.vsf

6.5 Arg A: OpenVMS Top Version SwitchBy default, under OpenVMS, Veracity sees all versions of all files in the directories it reads. This can be annoying because if you edit a file, creating a new version, Veracity will report a file



creation rather than a file change.

If, however, this argument is switched on, Veracityʼs check command will “see” only the top versions of files in real directory trees. It will continue to see all files in directory trees it reads from snapshot files.

This feature is useful when you want to treat old versions of files as backups and focus Veracityʼs attention only on the top versions. It is also useful when you want to compare an OpenVMS directory tree with a directory tree on (say) a Unix computer, without having to purge old versions on the OpenVMS machine first.

If you specify +A, Veracity will see only the top versions of real directory trees. However, Veracity always records the complete name of each file, and the check command might find itself unable to match up files whose name differs by version number only. (e.g. REPORT.TXT;5 vs REPORT.TXT;6). The solution is to invoke Veracityʼs OpenVMS version number fuzzy filename matching by specifying +Fversion to the check command as well as +A. This instructs Veracity to ignore the version numbers of the filenames when comparing them.

This argument has no effect on non-OpenVMS machines and only affects the way that the check command reads actual directory trees. If a snapshot file contains many file versions, the check will still see them all regardless of this argument.

Syntax

-A All versions of files visible under OpenVMS.=A No action taken.+A Top versions visible only under OpenVMS.

Default: -A

Exampleveracity check -a! All versions visible.veracity check +a! Only top versions visible.veracity check +a +fversion

6.6 Arg B: List FileThe list file argument is used to generate a list of files that are present in the new tree but not the old tree and any files that are present in both but have their file contents changed. Only files that have the attribute B.data.pool are listed. This argument is used internally by Rocksoft in the new Blocklets Pool product. It is referenced here for completeness and for the chance that it might be useful to other people.

The format of the list file is a 32 character hexadecimal MD5 string, followed by two spaces, and then the file specification. The list file will contain a single file on each line. The format of this file is the same as that created by the GNU tool md5sum. It is also the same as the format used by the GET command.

List File Contents Exampled2f82497d3b2378f19ee49aea88159d7 tortoise.txt



267525f8e8bd95092597c852f4434fe7 turtle.txt

Syntax

-B Do not generate a list file.=B Generate list file with the given file specification.+B Use the specified list file.

Exampleveracity check +B/tmp/changes.txt

6.6 Arg C: Policy FileA policy file is an input text file that you can provide to instruct Veracity on how to process a tree. Policy Files determine the kind of information that is to be recorded about different parts of the target tree. For example, a policy file might specify that no information be recorded about a particular subtree except for three critical files for which extra signatures must be recorded. As an alternative to creating and specifying a policy file, you can select one of a small set of predefined policy files. One of these predefined policy files is the default policy file which is used if no policy file is specified explicitly. For more information on policy files, see the chapter on policy files.

Whereas policy files instruct the snapshot command what to record in the snapshot file, they instruct the check command what to check when comparing the old and new trees.

When the snapshot command takes a snapshot, it records a copy of the policy file in the snapshot file itself. This enables the check command to use the same policy file, even if the snapshot file has been separated from the policy file (e.g. if the snapshot file was sent to a different computer). By default, the check command uses the policy file stored in the old snapshot file.

For the sake of flexibility, the check command allows you to specify one of four sources of policy file: a predefined policy file, an user-provided policy file, the policy file in the old snapshot file (if any) and the policy file in the new snapshot file (if any).

The C argument is similar to that of the snapshot command, except that it provides even more alternatives. If you specify -C then the argument string must be empty, and the default predefined policy file is used (same as specifying +C_default). If you do not specify a sign for the C argument, the string must be empty and the policy file is obtained from the first of the following three sources that is available: 1) the policy file stored in the old snapshot file, 2) the policy file stored in the new snapshot file, 3) the predefined policy file default.

If you specify +C with a string argument commencing with “_ ” then the policy file used will be the predefined policy file whose name is the rest of the string. In addition to the predefined policy files provided by the snapshot command, the check command provides two pseudo predefined policy files old and new that allow you to specify the policy file stored in the snapshot file corresponding to the old or new tree. If you specify +C with a string argument not commencing with “_ ”, then the inheritance of the table above will be applied to arrive at an explicit policy file specification. This syntax does not permit the use of user-defined policy files whose first character is an underscore



Syntax

-C Use default policy file.=C Sets user-policy file name only.+C Use user-supplied policy file.+C_* Use specified (*) predefined policy file.+C_old Use policy file in old snapshot file.+C_new Use policy file in new snapshot file.


Example

The check command uses the policy file in the old snapshot file, unless you specify otherwise. veracity check -cveracity check +cveracity check +c/usr/users/dave/snapshots/veracity check +cmypolicyveracity check +c.policyveracity check =cmypolicy +cveracity check +c_topveracity check +c_skeletonveracity check +c_oldveracity check +c_new

6.7 Arg D: Default PathnameBy default, the check command performs all its operations in and on the current directory. However, sometimes thereʼs a need to focus the command on some other directory. The D (default pathname) argument allows you to do that without having to specify the directory to each of the check commandʼs other arguments. Specifying a default pathname specification has much the same effect as setting the current directory to the specified directory for the duration of the execution of the check command


Syntax


Inheritance: None.

Exampleveracity check =Duserveracity check =D/usr/users/veracity check =D/usr/users/snapshot



In the first example, only the pathname identifier is specified, so Veracity will still operate in and on the current directory, but all the Veracity files will have an identifier of user instead of 0veracty. In the second example, a path is specified and the check command will operate in and on that directory as if it were the current directory. In the third example, both a path and an identifier is specified, and so Veracity will operate in and on the specified directory and will use the identifier snapshot for the Veracity files it writes there.

6.8 Arg E: Error LimitBy default, the check command writes diagnostic messages to both the report file and standard output (the console). However, sometimes when traversing large file systems, the number of errors can sometimes grow very large and overwhelm the console. The error limit argument solves this problem by allowing you to place an upper bound on the number of diagnostics that can be written to the console. When this limit is exceeded, Veracity will write out a message saying that further messages will be suppressed from the console, and from then on will direct diagnostics only to the report file (if any).


Syntax


Default: +E100

Exampleveracity check -everacity check +e500

6.9 Arg F: Fuzzy Filename MatchingWhen files are copied from one operating system to another, their names sometimes have to be changed so that they conform with the naming conventions of the target operating system. Usually the file transfer program will do its best to preserve as much of the name as possible. However, sometimes changes in filenames are unavoidable. For example, the file “sloth ” on a Unix machine might become “SLOTH.;1” when transfered to a OpenVMS machine. There is no way to avoid such a change, as all OpenVMS full file specifications are required to be in upper case, contain a dot (.), and contain a version number (;1).

These differences mean that, by default, Veracity doesnʼt match up the corresponding filenames, and will simply generate a report stating that all the source files have been deleted and all the destination files have been created!

To address this problem, Veracity provides a special feature called fuzzy filename matching in which it tolerates minor differences between the filenames it is matching up. The F argument controls this feature. The check command fuzzy filename matching feature provides a range of matching schemes:



Exact: Filenames must match exactly. This is the default matching scheme that is used when fuzzy filename matching is not activated.General: This is a general purpose fuzzy filename matching algorithm that will work in a wide range of circumstances. This algorithm is rather complicated and will not be explained in detail here. However, it is useful to know that it can cope with the following differences between filenames: 1) filename identifier truncation to six characters, 2) filename extension truncation to three characters, 3) conversion of case, 4) appendage of an empty extension, 5) appendage of a version number, 6) appendage of a trailing semicolon (for an empty version number). If the filenames differ in any other way, Veracity will perceive them as separate files.Version: This method was designed for use under OpenVMS. It is the same as the Exact scheme except that it ignores OpenVMS version numbers.

Case: This method tolerates differences in alphabetic case of the filenames only.Under circumstances where the check command has matched up two different filenames, there is some ambiguity as to how to apply the policy file, as the two different filenames might fire different sets of rules, resulting in two different sets of attributes. Veracity resolves this by applying the policy file only to the old filename in each matching pair of filenames. It should be emphasized that each fuzzy matching scheme will attempt to make as exact a match as it can. Each scheme resorts to progressively greater levels of fuzziness only if it canʼt make a match at a previous level. Thus, for example, the Case method would match sloth in the first directory with sloth in the second directory even if the second directory also contained a file called Sloth. The presence of both sloth and Sloth in the second directory would not make the match ambiguous (and hence unmatchable), because the case method does not ignore the case of filenames unless it has to.

Syntax

-F Use exact matching.=F Sets user-policy file name only.+Fexact Use exact matching.+Fgeneral General purpose fuzzy matching.+Fversion Fuzzy OpenVMS version number matching.+Fcase Case-insensitive matching.

Default: -F

Exampleveracity check -f

veracity check +f

veracity check +fexact

veracity check +fgeneral

veracity check +fversion

The General fuzzy matching algorithm is very powerful and should cope with file transfers from any known operating system to any other. However, if you encounter a situation where this fuzzy matching does not seem to be working, please let us know, and we will improve the algorithm further.



Warning: The general fuzzy filename matching algorithm is complicated and heuristic and is not certain to match up all pairs of filenames that should be matched. Use this feature with care.

6.10 Arg G: Snapshot GradeVeracityʼs snapshot command generates snapshot files that conform to the Veracity Snapshot Standard. This standard (or rather the Rocksoft Text Tree Standard which it inherits) defines four grades of snapshot file (in increasing strength):



Extended: Extended snapshots can contain features that are implemented in Veracity, but which do not yet appear in the Veracity Snapshot Standard. These non-standard features may be altered or improved in future versions of Veracity and this may mean that previously generated snapshots that used those features may not be readable by later versions of Veracity. Use this grade when you are creating non-archival snapshots and want to use the full power of Veracityʼs features.


The grade of a snapshot file appears in the Grade field in its header record, so you can always tell the grade of a snapshot file by inspection.

The check commandʼs G argument allows you to specify the maximum grade of snapshot file that the check command will read. For example, if you specified =gStandard then the check command would generate an error it was instructed to read an Extended grade snapshot file.

This argument is useful as an additional check in situations where you want to operate entirely with common or standard grade snapshot files. Specify the G argument to the snapshot command to generate snapshots of the desired grade, and then use the G argument whenever you invoke the check command to ensure that no higher-grade snapshots were accidentally created.

Syntax


-G Not allowed.



=G Specify snapshot standard grade identifier.+G Not allowed.

Default: +GStandard

Exampleveracity check =gCommonveracity check =gStandardveracity check =gExtendedveracity check =gAdvanced

6.11 Arg P: Password (Old Tree)The P argument of the snapshot command instructs the snapshot command to lace the snapshot file it generates with digital signatures incorporating a secret password. The P argument of the check command enables you to check during a check run that the snapshot file corresponding to the old tree was generated using a particular password. If the snapshot file was not generated using a password, or if the password used was different, then the check command generates an error.

If you specify +P but do not provide a password, you will be prompted for one.

Warning: On Unix, the ps command can be used to see the command line of other users, which might allow others to see your snapshot password. If this of concern to you, then specify +P but do not provide a password. You will be prompted for one. An alternative is to run Veracity in interactive mode (Veracity shell) and then give the check +Psesame command from within the Veracity shell.

Syntax

-P No password check.=P Sets password only.+P Check old treeʼs snapshot file.

Default: -P

Exampleveracity check +Psesame

6.12 Arg R: Report FileWhen the check command executes, by default, it appends a report of its run to a report file which is usually called 0veracty.vrf and located in the current directory. The R argument determines whether a report file is generated, and where.

Syntax




Inheritance: +R .vrf =D 0veracty CurDir.

Exampleveracity check -rveracity check +rmyreportveracity check +r/user/dave/reports/veracity check +r/user/dave/reports/latest.txtveracity check +r.txt

6.13 Arg U: Load OptimizationVeracity runs can be very IO intensive because, during a typical run, Veracity reads and snapshots/checks files as fast as it can. On slower machines this can cause the machine to spend a lot of time in the kernel (presumably servicing IO calls for Veracity), even when the priority of the process running Veracity is explicitly lowered using, for example, the Unix nice command. One Veracity user reported that running Veracity in the background on an Intel 486 caused the machine to spend 40% of its time in the kernel. When Veracity wasnʼt running, the machine ran fine.


To allow Veracity to be run in the background without slamming the kernel, Veracity provides the U argument in its snapshot and check commands. By default, the argument is turned off (-U), but if you specify +U, then Veracity will introduce a constant real-time delay just before it reads each directory or file in the target tree.

The delay is applied to each directory and each file in each target tree that is read during the check command. This means that if you are comparing two directory trees, the delay will be introduced for each file that is read in each of the two trees; so if you specify a delay of 200 milliseconds, it will result in a maximum of 2.5 files processed per second, not five files a second as for the snapshot command. If you are comparing a snapshot file and a directory tree, the delay will be introduced only when reading the directories and files of the directory tree. Finally, if you are comparing two snapshot files, the delay will be applied once per directory compared. This allows you to perform signoffs in the background without slamming the kernel with IO calls to the snapshot files themselves!

All this means that if you specify the same delay for both your snapshot and check commands, the load on the system imposed by Veracity should be reduced by a similar amount.



Syntax

-U No delay.+U Applies default delay.



+Un Applies specified delay.

Default: -U

Exampleveracity check ! No delay.veracity check +u ! The default delay.veracity check +u500 ! Half a second delay.veracity check +u1000 ! One second delay.

6.14 Arg V: Tracing LevelBy default, the check command does not provide any progress indicator as it traverses a directory tree. The V argument enables you to specify that the check command generate trace messages as it progresses through the tree.


Syntax

-V No tracing.=V Set tracing level if on.+V Trace directories.+V1 Trace directories.+V2 Trace directories and files.

Default: -V

Exampleveracity check -v ! No tracing.veracity check +v ! Trace directories.veracity check +v1! Trace directories.veracity check +v2! Trace dirs and files.

6.15 Arg W: Password (New Tree)The P argument of the snapshot command instructs the snapshot command to lace the snapshot file it generates with digital signatures incorporating a secret password. The W argument of the check command enables you to check during a check run that the snapshot file corresponding to the new tree was generated using a particular password. If the snapshot file was not generated using a password, or if the password used was different, then the check command generates an error.

If you specify +W but do not provide a password, you will be prompted for one.

Warning: On Unix, the ps command can be used to see the command line of other users, which might allow others to see your snapshot password. If this of concern to you, then specify +W but do not provide a password. You will be prompted for one. An alternative is to run Veracity in interactive mode (Veracity shell) and then give the check +Wsesame command from within the



Veracity shell.

Syntax

-W No password check.=W Sets password only.+W Check new treeʼs snapshot file.

Default: -W

Exampleveracity check +Wsesame +2/snaps/

6.16 Arg Z: Difference ErrorBy default, the check command does not classify any differences (creations, deletions, and changes) that it finds as errors. However, if you are calling Veracity from a shell script, you may want Veracity to exit with error status if it has detected a change, so that you can react to it. The difference error argument allows you to do that by generating an error if there are one or more differences.

Syntax

-Z No error upon differences.=Z No effect.+Z Generate error if at least one difference.

Default: -Z

Exampleveracity check +z

6.17 A Critical IssueThere is a particular aspect of the semantics of Veracity that it is vital to know about when writing policy files and reading Veracityʼs reports. In a nutshell, it is that directory creations and deletions obscure other changes when Veracity is reporting changes. Consider the following policy file:

=====(BeginClipListV1)=====“#*.exe” -f-> +create +delete +B.md5=====(EndClipList)=====

This policy file suggests that it will instruct Veracity to monitor the creation, deletion and modification of all exe files within the target tree. This is nearly true, but there is a significant exception.

When Veracityʼs check command traverses two directory trees looking for changes, it only “enters” a directory if the directory is present in both the old and new trees being compared. If a directory is present in only one of the two trees (i.e. it has been created or deleted), the check



command identifies the change as the creation or deletion of the directory, and pays no further attention to the created or deleted subtree. The reason for this behavior is that if a directory tree of 1000 files is created or deleted, it makes sense to report this change as a single change rather than as 1000 changes. So when the check command sees that a directory has been created or deleted, it classifies it as a single directory creation or deletion change and does not traverse the created or deleted directory.

This means that, while the policy file above will ensure that the creation, deletion or change of one or more exe files will be detected, if a directory containing an executable file is created or deleted, Veracity will view this change solely as a directory creation or deletion. As the policy file above does not specify that the creation or deletion of directories be brought to the userʼs attention, the creation or deletion of any exe file within the created or deleted directory will not be identified.

All this means that if you want to monitor the creation and deletion of all instances of particular kinds of files within a target tree, you will also have to monitor the creation and deletion of all directories within the target tree too, and view the reported creation or deletion of a directory as potentially hiding the creation or deletion of the particular kind of file you are monitoring.

=====(BeginClipListV1)=====“#*” -d-> +create +delete“#*.exe” -f-> +create +delete +B.md5=====(EndClipList)=====

Depending on your circumstances, this may or may not introduce significant noise into your change reports. Usually, there is not much noise, as directory creations and deletions are usually relatively rare events.

The important thing is that you be aware of this potential pitfall.

6.18 ExamplesThis section provides examples of the use of the check command.

checkIf no arguments are given, the old tree is the snapshot file 0veracty.vsf in the current directory and the new tree is the directory tree rooted in the current directory. The policy file is the snapshot file for the old tree is used. The report file is written in the current directory to 0veracty.vrf.

check =DdaveThis is the same as the previous example except that the snapshot and report files will be read from and written to dave.vsf and dave.vrf.

check =D/usr/users/dave/work/This is the same as setting default to /usr/users/dave/work/ before the check command and restoring the default afterwards.

check /usr/users/dave/work/This is the same as check with no arguments except that the new tree is the tree rooted in /usr/users/dave/work/ rather than the tree rooted in the current directory.

check -1users.vsf -2sys.vsf +C



The new tree is read from the snapshot file users.vsf in the current directory. The old tree is read from the snapshot file sys.vsf in the current directory. The +C means that the policy file “0veracty.vpf” in the current directory is used to clip the comparison.

check -2sys.vsf +C_oldThe new tree is the directory tree rooted in the current directory. The old tree is read from the snapshot file sys.vsf in the current directory. The policy file is read from that file too.

check +1/usr/users/stuff/ +2/usr/usr2/users/stuff/Compares two directory trees directly. As usual, the contents of the files arenʼt compared, just their digests.

check +F +C_transferThe old tree is the snapshot file 0veracty.vsf in the current directory and the new tree is the directory tree rooted in the current directory. The transfer policy file is used and fuzzy filename matching is employed. The report file is written in the current directory to 0veracty.vrf. This setting is useful when a directory tree containing a mixture of binary and text files have been moved to a different machine running a different operating system.

check +Psesame

This is the same as a check command with no arguments except that in addition to performing the check, Veracity ensures that the snapshot file was generated with the password “sesame”.



7 The RESTORE CommandThis chapter is devoted to the restore command, which is one of the core Veracity commands. The restore command compares two trees (real or as recorded in a snapshot file) and restores the target tree to be identical to the old tree stored in the snapshot file. This chapter defines and describes this command.

7.1 IntroductionThe restore command compares two directory trees and restores the target tree to be identical to the old tree stored in the snapshot file. Each tree can be either an actual directory tree, or a snapshot file (as generated by the SNAPSHOT command). The two trees being compared are referred to as the old tree and the new tree so as to enable the restore command to refer to them clearly.

The restore command accepts many arguments, but you will probably need very few in practice. If you provide no arguments at all:

veracity restore

then Veracity will restore the directory tree rooted in the current directory to be identical with the tree described by the snapshot file 0veracty.vsf in the current directory. The differences it finds and fixes will be appended to a report file called 0veracty.vrf in the current directory. The restore commandʼs default behavior may be all that you need.

This chapter defines and describes the arguments to the restore command. There are also some examples at the end of the chapter.

7.2 Overview Of ArgumentsThis page gives an overview of arguments to the restore command.

Argument Summary

The table below gives the arguments of the restore command. The first column gives the set of legal signs for each argument. The second column gives each argumentʼs letter and its default sign. The third column describes the argument. Most of the arguments take pathname specifications as values using the pathname syntax specific to the host operating system. These values are then passed through an inheritance hierarchy to yield a complete absolute pathname.

Allowed Default Description- = + +1 Newtree. - = + -2 Oldtree. - = + =C Policy File. = D Default pathname. - = + +E Error limit. - = + -K Console commentary. - = + -P Password for snapshot file for old tree. - = + +R Report file. = S Snapshot file. - = + +T Root of target tree. - = + -V Tracing level.



Inheritance Summary

Many of the arguments to the restore command accept a pathname specification as an argument value. This value (which may be incomplete) is then passed through an inheritance hierarchy to yield the final pathname.

The following table shows the restore commandʼs six pathname arguments, one per column. Each argumentʼs string argument is treated as a pathname structured as 1) a path, 2) a name, 3) an extension, 4) a version (optional), and the inheritance specified here is applied on a field by field basis, with the top of the table having the highest priority and the bottom of the table having the lowest priority. The notation “=letter” represents any value specified for that argument. The notation “[P]” means that only the path field is inherited. The inheritance for the parameters 1 and 2 differ depending on the signs of the parameters.

NewTree OldTree -1 +1 -2 +2 Policy Report

=1 =1 =2 =2 =C =R

“.vsf” “.vsf” “.vpf” “.vrf”

=D =D[P] =D =D[P] =D =D

0veracty 0veracty 0veracty 0veracty

CurDir CurDir CurDir CurDir CurDir CurDir

Thus, for example the table shows that the pathname of the report file generated by the restore command will be determined by first taking the string value of the R argument, then inheriting the extension .vrf if the extension is absent, then inheriting from the D argument, then inheriting the identifier 0veracty and finally inheriting the current path if the path is still empty at that point.

A key feature of the restore command is that it can compare and repair any combination of snapshot files and real directory trees. All four combinations are possibly by specifying a sign (“-” (snapshot file) or “+” (directory tree)) to the 1 and 2 arguments. The defaulting hierarchy differs for these arguments depending on their sign and so four columns of defaulting are needed in this table. +1 and -2 are in bold as these are the default signs for these two arguments.

7.3 Arg 1: Target TreeThe target tree is the directory tree which the restore command modifies from a snapshot file. By default, this is the directory tree rooted in the current directory. However, by using the 1 argument, you can specify it to be any tree. Veracity can be instructed in its policy file to restore different amounts of information about different parts of the tree, but is always bounded to work within the target tree only (as defined by the treeʼs hard links (and symbolic links too if you have instructed Veracity to follow them)).

This argument is equivalent to the T argument, with the T argument having precedence when both are specified.

Remote Snapshots

If you are using Veracityʼs network functionality (see the N argument) to restore a snapshot of a directory tree on a remote machine, then no inheriting of this argument occurs and you must specify a complete absolute path in this argument.



Special Remote Snapshot Syntax

If the 1 argument contains the @ character, then the part of the argument to the right of the @ character is treated as if it were an argument to the +N argument. This enables you to specify remote snapshots using a single argument. For example:

veracity restore /home/dave/@domain.com/sesame

If you want to include the @ character in a path argument, use the T argument instead.

Syntax

-1 Specify target tree pathname specification.=1 Specify target tree pathname specification.+1 Specify target tree pathname specification.


Example


veracity restore /usr/users/veracity restore =Rreport +1/usr/users/veracity restore /home/dave/@domain.com/sesame

7.4 Arg 2: Snapshot FileThe snapshot file is the primary input file of the restore command. It consists of a text file containing information about the target directory tree. By default, the snapshot file is called 0veracty.vsf and is read from the current directory, but using the 2 argument, you can specify it to be any file.

This argument is equivalent to the S argument, with the S argument having precedence when both are specified.

Syntax

-2 Not allowed.=2 Specify target tree pathname specification.+2 Not allowed.


Example


veracity restore =2usersnapveracity restore =2/sys/snapshots/veracity restore /usr/users/ usersnap.vsfveracity restore =Rreport /usr/users/ usersnap



7.5 Arg C: Policy FileA policy file is an input text file that you can provide to instruct Veracity on how to process a tree. Policy Files determine the kind of information that is to be recorded about different parts of the target tree. For example, a policy file might specify that no information be recorded about a particular subtree except for three critical files for which extra signatures must be recorded. As an alternative to creating and specifying a policy file, you can select one of a small set of predefined policy files. One of these predefined policy files is the default policy file which is used if no policy file is specified explicitly. For more information on policy files, see the chapter on policy files.

Whereas policy files instruct the snapshot command what to record in the snapshot file, they instruct the restore command what to restore when comparing the old and new trees.

When the snapshot command takes a snapshot, it records a copy of the policy file in the snapshot file itself. This enables the restore command to use the same policy file, even if the snapshot file has been separated from the policy file (e.g. if the snapshot file was sent to a different computer). By default, the restore command uses the policy file stored in the old snapshot file.

For the sake of flexibility, the restore command allows you to specify one of four sources of policy file: a predefined policy file, an user-provided policy file, the policy file in the old snapshot file (if any) and the policy file in the new snapshot file (if any).

The C argument is similar to that of the snapshot command, except that it provides even more alternatives. If you specify -C then the argument string must be empty, and the default predefined policy file is used (same as specifying +C_default). If you do not specify a sign for the C argument, the string must be empty and the policy file is obtained from the first of the following three sources that is available: 1) the policy file stored in the old snapshot file, 2) the policy file stored in the new snapshot file, 3) the predefined policy file default.

If you specify +C with a string argument commencing with “_ ” then the policy file used will be the predefined policy file whose name is the rest of the string. In addition to the predefined policy files provided by the snapshot command, the restore command provides two pseudo predefined policy files old and new that allow you to specify the policy file stored in the snapshot file corresponding to the old or new tree. If you specify +C with a string argument not commencing with “_ ”, then the inheritance of the table above will be applied to arrive at an explicit policy file specification. This syntax does not permit the use of user-defined policy files whose first character is an underscore

Syntax

-C Use default policy file.=C Sets user-policy file name only.+C Use user-supplied policy file.+C_* Use specified (*) predefined policy file.+C_old Use policy file in old snapshot file.+C_new Use policy file in new snapshot file.




Example

The restore command uses the policy file in the old snapshot file, unless you specify otherwise. veracity restore -cveracity restore +cveracity restore +c/usr/users/dave/snapshots/veracity restore +cmypolicyveracity restore +c.policyveracity restore =cmypolicy +cveracity restore +c_topveracity restore +c_skeletonveracity restore +c_oldveracity restore +c_new

7.6 Arg D: Default PathnameBy default, the restore command performs all its operations in and on the current directory. However, sometimes there is a need to focus the command on some other directory. The D (default pathname) argument allows you to do that without having to specify the directory to each of the restore commandʼs other arguments. Specifying a default pathname specification has much the same effect as setting the current directory to the specified directory for the duration of the execution of the restore command


Syntax


Inheritance: None.

Exampleveracity restore =Duserveracity restore =D/usr/users/veracity restore =D/usr/users/snapshot

In the first example, only the pathname identifier is specified, so Veracity will still operate in and on the current directory, but all the Veracity files will have an identifier of user instead of 0veracty. In the second example, a path is specified and the restore command will operate in and on that directory as if it were the current directory. In the third example, both a path and an identifier is specified, and so Veracity will operate in and on the specified directory and will use the identifier snapshot for the Veracity files it writes there.

7.7 Arg E: Error LimitBy default, the restore command writes diagnostic messages to both the report file and standard output (the console). However, sometimes when traversing large file systems, the number of



errors can sometimes grow very large and overwhelm the console. The error limit argument solves this problem by allowing you to place an upper bound on the number of diagnostics that can be written to the console. When this limit is exceeded, Veracity will write out a message saying that further messages will be suppressed from the console, and from then on will direct diagnostics only to the report file (if any).


Syntax


Default: +E100

Example veracity restore -e veracity restore +e500

7.8 Arg G: Snapshot GradeVeracityʼs snapshot command generates snapshot files that conform to the Veracity Snapshot Standard. This standard (or rather the Rocksoft Text Tree Standard which it inherits) defines four grades of snapshot file (in increasing strength):



Extended: Extended snapshots can contain features that are implemented in Veracity, but which do not yet appear in the Veracity Snapshot Standard. These non-standard features may be altered or improved in future versions of Veracity and this may mean that previously generated snapshots that used those features may not be readable by later versions of Veracity. Use this grade when you are creating non-archival snapshots and want to use the full power of Veracityʼs features.


The grade of a snapshot file appears in the Grade field in its header record, so you can always



tell the grade of a snapshot file by inspection.

The restore commandʼs G argument allows you to specify the maximum grade of snapshot file that the restore command will read. For example, if you specified =gStandard then the restore command would generate an error it was instructed to read an Extended grade snapshot file.

This argument is useful as an additional check in situations where you want to operate entirely with common or standard grade snapshot files. Specify the G argument to the snapshot command to generate snapshots of the desired grade, and then use the G argument whenever you invoke the restore command to ensure that no higher-grade snapshots were accidentally created.

Syntax


-G Not allowed.=G Specify snapshot standard grade identifier.+G Not allowed.

Default: +GStandard

Exampleveracity restore =gCommonveracity restore =gStandardveracity restore =gExtendedveracity restore =gAdvanced

7.9 Arg K: Console CommentaryBy default, the check command writes a commentary to the console describing creations, deletions and modifications detected between the old and new trees. The restore command also detects these differences and corrects them, but normally the user will not want to see commentary on the differences that the restore command is fixing.

However, sometimes it is appropriate to see a trace of what the restore command is doing. The K (for konsole :-) argument allows the user to view a list of the differences that the restore command is fixing as it is fixing them.

Syntax

-K No console commentary will be written.+K Console commentary will be written.

Default: -K

Exampleveracity restore -Kveracity restore +K

7.10 Arg P: Password (Old Tree)The P argument of the snapshot command instructs the snapshot command to lace the



snapshot file it generates with digital signatures incorporating a secret password. The P argument of the restore command enables you to check during a restore run that the snapshot file corresponding to the old tree was generated using a particular password. If the snapshot file was not generated using a password, or if the password used was different, then the restore command generates an error.

If you specify +P but do not provide a password, you will be prompted for one.

Warning: On Unix, the ps command can be used to see the command line of other users, which might allow others to see your snapshot password. If this of concern to you, then specify +P but do not provide a password. You will be prompted for one. An alternative is to run Veracity in interactive mode (Veracity shell) and then give the restore +Psesame command from within the Veracity shell.

Syntax

-P No password check.=P Sets password only.+P Check old treeʼs snapshot file.

Default: -P

Exampleveracity restore +Psesame

7.11 Arg R: Report FileWhen the restore command executes, by default, it appends a report of its run to a report file which is usually called 0veracty.vrf and located in the current directory. The R argument determines whether a report file is generated, and where.

Syntax



Exampleveracity restore -rveracity restore +rmyreportveracity restore +r/user/dave/reports/veracity restore +r/user/dave/reports/latest.txtveracity restore +r.txt

7.12 Arg S: Snapshot FileThe snapshot file is the primary input file of the restore command. It consists of a text file containing information about the target directory tree. By default, the snapshot file is called



0veracty.vsf and is read from the current directory, but using the S argument, you can specify it to be any file.

This argument is equivalent to the 2 argument, with the S argument having precedence when both are specified.

Syntax

-S Not allowed.=S Specify target tree pathname specification.+S Not allowed.


Exampleveracity restore =Susersnapveracity restore =S.snapveracity restore =S/sys/snapshots/veracity restore =S/sys/snapshots/newsnap.txt

7.13 Arg T: Target TreeThe target tree is the directory tree which the restore command modifies from the snapshotfile. By default, this is the directory tree rooted in the current directory, but using the T argument, you can specify it to be any tree. Veracity can be instructed in its policy file to restore different amounts of information about different parts of the tree, but is always bounded to work within the target tree only (as defined by the treeʼs hard links (and symbolic links too if you have instructed Veracity to follow them)).

This argument is equivalent to the 1 argument, with the T argument having precedence when both are specified.

Syntax

-T Specify target tree pathname specification.=T Specify target tree pathname specification.+T Specify target tree pathname specification.


Exampleveracity restore =T/usr/users/veracity restore =Rreport =T/usr/users/

7.14 Arg U: Load OptimizationVeracity runs can be very IO intensive because, during a typical run, Veracity reads and snapshots/checks files as fast as it can. On slower machines this can cause the machine to spend a lot of time in the kernel (presumably servicing IO calls for Veracity), even when the



priority of the process running Veracity is explicitly lowered using, for example, the Unix nice command. One Veracity user reported that running Veracity in the background on an Intel 486 caused the machine to spend 40% of its time in the kernel. When Veracity wasnʼt running, the machine ran fine.


To allow Veracity to be run in the background without slamming the kernel, Veracity provides the U argument in its snapshot, check and restore commands. By default, the argument is turned off (-U), but if you specify +U, then Veracity will introduce a constant real-time delay just before it reads each directory or file in the target tree.

The delay is applied to each directory and each file in each target tree that is read during the restore command. This means that if you are comparing two directory trees, the delay will be introduced for each file that is read in each of the two trees; so if you specify a delay of 200 milliseconds, it will result in a maximum of 2.5 files processed per second, not five files a second as for the snapshot command. If you are comparing a snapshot file and a directory tree, the delay will be introduced only when reading the directories and files of the directory tree. Finally, if you are comparing two snapshot files, the delay will be applied once per directory compared.

All this means that if you specify the same delay for both your snapshot and restore commands, the load on the system imposed by Veracity should be reduced by a similar amount.



Syntax

-U No delay.+U Applies default delay.+Un Applies specified delay.

Default: -U

Exampleveracity restore ! No delay.veracity restore +u ! The default delay.veracity restore +u500 ! Half a second delay.veracity restore +u1000 ! One second delay.

7.15 Arg V: Tracing LevelBy default, the restore command does not provide any progress indicator as it traverses a directory tree. The V argument enables you to specify that the restore command generate trace messages as it progresses through the tree.




Syntax

-V No tracing.=V Set tracing level if on.+V Trace directories.+V1 Trace directories.+V2 Trace directories and files.

Default: -V

Exampleveracity restore -v ! No tracing.veracity restore +v ! Trace directories.veracity restore +v1! Trace directories.veracity restore +v2! Trace dirs and files.

7.16 ExamplesThis section provides examples of the use of the restore command.

restore

If no arguments are given, the old tree is the snapshot file 0veracty.vsf in the current directory and the new tree is the directory tree rooted in the current directory. The policy file is the snapshot file for the old tree is used. The report file is written in the current directory to 0veracty.vrf.

restore =DdaveThis is the same as the previous example except that the snapshot and report files will be read from and written to dave.vsf and dave.vrf.

restore =D/usr/users/dave/work/This is the same as setting default to /usr/users/dave/work/ before the restore command and restoring the default afterwards.

restore /usr/users/dave/work/This is the same as restore with no arguments except that the new tree is the tree rooted in /usr/users/dave/work/ rather than the tree rooted in the current directory.

restore -1users.vsf -2sys.vsf +CThe new tree is read from the snapshot file users.vsf in the current directory. The old tree is read from the snapshot file sys.vsf in the current directory. The +C means that the policy file “0veracty.vpf” in the current directory is used to clip the comparison.

restore -2sys.vsf +C_oldThe new tree is the directory tree rooted in the current directory. The old tree is read from the snapshot file sys.vsf in the current directory. The policy file is read from that file too.

restore +1/usr/users/stuff/ +2/usr/usr2/users/stuff/



Compares two directory trees directly. As usual, the contents of the files arenʼt compared, just their digests.

restore +F +C_transferThe old tree is the snapshot file 0veracty.vsf in the current directory and the new tree is the directory tree rooted in the current directory. The transfer policy file is used and fuzzy filename matching is employed. The report file is written in the current directory to 0veracty.vrf. This setting is useful when a directory tree containing a mixture of binary and text files have been moved to a different machine running a different operating system.

restore +PsesameThis is the same as a restore command with no arguments except that in addition to performing the restore, Veracity ensures that the snapshot file was generated with the password “sesame”.



8 The GET CommandThis chapter is devoted to the get command, which is one of the core Veracity commands. The get command retrieves one or more files from a remote computer running a Veracity agent. This chapter defines and describes this command.

8.1 IntroductionThe get command retrieves one or more files from a remote computer running a Veracity agent. For a Veracity agent to send a file there are several security checks that it performs. It first tries to authenticate the user to make sure the user is authorised to access the agent. The agent then checks to see if it is configured to send out file contents — by default agents are not allowed to. If the flag AllowData is set to Yes the agent is configured to send file contents. Finally the agent checks that the file is in its visible path.

See the AGENT command for more details on Veracity agents.

8.2 Overview Of ArgumentsThis page gives an overview of arguments to the get command.

Argument Summary

The table below gives the arguments of the get command. The first column gives the set of legal signs for each argument. The second column gives each argumentʼs letter and its default sign. The third column describes the argument. Most of the arguments take pathname specifications as values using the pathname syntax specific to the host operating system. These values are then passed through an inheritance hierarchy to yield a complete absolute pathname.

Allowed Default Description = =1 Source file. = =2 Destination file or directory. - = + -B List file. - = + -N Network Node. - = + +R Report file. - = + -Y Reference file.

Inheritance Summary

Many of the arguments to the get command accept a pathname specification as an argument value. This value (which may be incomplete) is then passed through an inheritance hierarchy to yield the final pathname.

The following table shows the get commandʼs five pathname arguments, one per column. Each argumentʼs string argument is treated as a pathname structured as 1) a path, 2) a name, 3) an extension, 4) a version (optional), and the inheritance specified here is applied on a field by field basis, with the top of the table having the highest priority and the bottom of the table having the lowest priority. The notation “=letter” represents any value specified for that argument. The notation “[P]” means that only the path field is inherited. The inheritance for the parameters 1 and 2 differ depending on the signs of the parameters.



Source Destination List Report Reference =1 =2 =B =R =Y

=1 =1 =2 =1

.vrf

=D[P] =D =D =D =D

0veracty 0veracty

CurDir CurDir CurDir CurDir CurDir

Thus, for example the table shows that the pathname of the report file generated by the get command will be determined by first taking the string value of the R argument, then inheriting the extension .vrf if the extension is absent, then inheriting from the D argument, then inheriting the identifier 0veracty and finally inheriting the current path if the path is still empty at that point.

8.3 Arg 1: Source FileThe source file is the file to retrieve from a remote computer running a Veracity agent. If you would like to retrieve more than one file from a Veracity agent, use the B argument.

This argument should contain the full specification for the file to retrieve.

Syntax

-1 Not allowed.=1 Specify the source file specification.+1 Not allowed.

Example


veracity get =1/usr/users/dave/zebra.txt [email protected] get /usr/users/dave/zebra.txt [email protected] get [email protected]/usr/users/dave/zebra.txt

8.4 Arg 2: Destination File or DirectoryThe destination file or directory is the output file or the output directory to store retrieved files. If you are retrieving a single file this will be the file name to write to, if you are retrieving multiple files (using the B argument) this will be a directory to write to.

If you are transferring a single file the destination file name defaults to the name of the file you are retrieving. If you are transferring multiple files the destination directory defaults to the current directory.

Syntax

-2 Not allowed.=2 Specify the destination file or directory specification.+2 Not allowed.



Example


veracity get /usr/users/dave/zebra.txt =2zebra_new.txt [email protected] get /usr/users/dave/zebra.txt zebra_new.txt [email protected] get /usr/users/dave/zebra.txt [email protected] get =2/usr/home/animals/ +B/usr/home/animal_list.txt [email protected] get +B/usr/home/animal_list.txt [email protected]

8.5 Arg B: List FileThe list file argument is used to retrieve multiple files from a remote computer running a Veracity agent. This argument is used internally by Rocksoft in the new Blocklets Pool product. It is referenced here for completeness and for the chance that it might be useful to other people.

To transfer multiple files, each file name should be written to a list file where the format of the list file is a 32 character hexadecimal MD5 string, followed by two spaces, and then the file specification. This file can be created using the GNU tool md5sum or by the CHECK command.

The argument should be the file specification of the list file.

Once the files have been retrieved they will be saved using their MD5 signature as their file name, e.g. d2f82497d3b2378f19ee49aea88159d7.dat.

List File Contents Exampled2f82497d3b2378f19ee49aea88159d7 tortoise.txt267525f8e8bd95092597c852f4434fe7 turtle.txt

Syntax

-B Transfer a single file.=B Sets list file specification.+B Use specified list file.

Exampleveracity get +B/tmp/files.txt [email protected]

8.6 Arg N: Network NodeThis argument is compulsory in the get command.

For details see the RESTORE command.

8.7 Arg R: Report FileWhen the get command executes, by default, it appends a report of its run to a report file which is usually called 0veracty.vrf and located in the current directory. The R argument determines whether a report file is generated, and where.



Syntax



Exampleveracity get /usr/users/dave/zebra.txt [email protected] -Rveracity get /usr/users/dave/zebra.txt [email protected] +R/tmp/myreport

8.8 Arg Y: Reference FileThe use of a reference file at the receiving end of the file transfer allows the Blocklets (tm) protocol to dramatically reduce the amount of data that must be transmitted during the transaction. The Y argument specifies where the reference file can be found.

The argument takes the negative form by default.

The argument cannot take the negative form AND have a non-empty string value.

The argument can only be used when transferring a single file.

The positive form is an instruction that the Blocklets protocol MUST be used during file transfer. If the agent does not support the Blocklets protocol, then the get command will fail.

The argument should be a file specification for a file to be read in as a reference file for the Blocklets protocol. There is no constraint on this fileʼs contents at all. The contents can be white noise. However, the more similar the contents of the reference file are to the file being transmitted, the more efficient the Blocklets protocol will make the transmission.

Syntax

-Y Donʼt use reference file.=Y Specify reference file pathname spec.+Y Use specified reference file.

Default: -Y

Inheritance: =1 =D 0veracty CurDir.

Exampleveracity get /usr/users/dave/zebra.txt +Yzebra_old.txt [email protected]

8.9 ExamplesThis section provides examples of the use of the get command.

get /usr/users/dave/zebra.txt [email protected] the file /usr/users/dave/zebra.txt from a remote computer and store it in the current



directory. Connect to the remote computer through a Veracity agent with virtual agent ID dave running on the domain domain.com.

get [email protected]/usr/users/dave/zebra.txtAlternative syntax of the command, same as above.

get /usr/users/dave/zebra.txt zebra_new.txt [email protected] the file /usr/users/dave/zebra.txt and store it in the current directory under the name of zebra_new.txt.

get +B/usr/home/animal_list.txt [email protected] all the files specified in /usr/home/animal_list.txt and store them in the current directory.

get +B/usr/home/animal_list.txt /tmp/ [email protected] all the files specified in /usr/home/animal_list.txt and store them in the UNIX temporary directory.



9 The AGENT CommandThis chapter describes the AGENT command, which allows you to run a Veracity network agent.

9.1 IntroductionThe snapshot command allows you to take a snapshot of a directory tree not only on the current computer, but also on a remote computer (using the +N argument), so long as the remote computer is running a Veracity (or Veracity-compatible) agent.

The agent command allows you set up and run such an agent as a process on your computer. The process will wait for connections to arrive from remote computers (which are executing the Veracity snapshot command (with +N argument)). When a connection arrives, the agent processes it and waits for another connection to arrive.

Here is a summary of some of the features provided by Veracity agents, as implemented by the agent command:

Simple installation: The agent can be installed in its standard configuration without fussing with any configuration files. Installation takes less than one minute!

Parallel serving: The agent can be configured to process connections in serial or in parallel. For serial, there is just one process which accepts and processes connections. For parallel, a master process accepts connections and forks off a new process to process each connection. Agents running on Novell Netware can currently only process connections serially.

Single TCP connection: Client/server connections use a single TCP connection.

Multiple agents per computer: A computer may run more than one Veracity agent at the same time, so long as the different agents listen to different TCP ports.

User-level agents: There is no requirement that agents run as “root” on a machine. Users may create a Veracity agent without extra privileges. However, user agents will only be able to serve whatever files the user process can read.

Official Veracity TCP Port: The Internet Assigned Numbers Authority has assigned TCP port 1062 (decimal) for Veracity, so there will be no port collisions.

Virtual agents: Each Veracity agent provides one or more virtual agents, each of which has its own configuration, security regime, and restrictions. Virtual agents can be connected to explicitly by name, or implicitly by domain name. Each virtual agent can only take snapshots within its prescribed visible directory tree.

Public serving: Veracity virtual agents can be configured with no security to provide public access to snapshots of a well-defined directory tree on the computer.

Private serving: Veracity virtual agents can be configured to provide a very high level of security to prevent unauthorized access. Security mechanisms include client-IP filtering, password protection with a sophisticated symmetric-key exchange protocol that does not require the password to be transmitted to the agent, and DES3-CBC encryption of the TCP/IP connection.

Go slow: Veracity virtual agents can be configured to process connections very slowly (with



real time delays) so as not to impact on other agent activities.

Predefined configurations: A variety of predefined configuration files are provided to cater for most installation needs. These can be used directly, or may be used as a template for your own customized configuration files.

Together, these features provide a sound basis to serve Veracity snapshots securely to authorized clients.

9.2 Client/Server TerminologyIn TCP/IP client/server systems, clients and servers are distinguished technically by the role they play in client/server conversations.

Technical definition of server software: A piece of software is a server if it listens to a TCP port for connections and accepts and services those connections. When a connection arrives, the server processes the connection and then listens for the next connection. Serving is a passive role. Typically servers never initiate connections themselves, though they might act in a client role to access the information they serve (as in web proxy servers). Example server software: webservers, news servers, mail servers, DNS servers. In a nutshell: Servers are PASSIVE.

Technical definition of client software: A piece of software is a client if it initiates TCP connections. Unlike server software, client software does not need to run continuously. Client software is usually activated by a user to connect to a server and obtain some information or perform some action. Example client software: web clients, email clients. In a nutshell: Clients are ACTIVE.

Under this classification, Veracity client/server systems consist of a small number of computers running Veracity client software and a large number of computers running Veracity agent (server) software. To monitor a computerʼs integrity, you install a Veracity agent on the computer. The agent waits for, and processes, requests for integrity information, but does not initiate any action on its own. Actual checks are initiated by Veracity clients under automated or direct user control. Thus, if you have an organization with one thousand computers, you would install one thousand Veracity agents and a few Veracity clients to monitor them. This architecture enhances security because the responsibility for monitoring the network rests with the clients rather than the agents (which are presumed to be under attack).

Unfortunately, in the world of marketing, the terms client and server have come to have completely orthogonal meanings:

Marketing definition of client software: Software is “client” software if you have to buy a relatively large number of copies. Client software is typically low priced. In a nutshell: Clients are 1:1 with users.

Marketing definition of server software: Software is “server” software if you have to buy a relatively small number of copies. Server software is typically high priced. In a nutshell: Servers are 1:1 with networks.

This confusion has arisen because the technical and marketing definitions usually coincide. For example, they coincide in the case of web clients and servers. In general, they coincide whenever software is organized so that users initiate connections to a relatively small number



of servers to perform some function for example to browse the web, or to fetch a file, or to read some email.

However, in the case of Veracity, a small number of clients, which for Veracity are roughly 1:1 with networks, access a large number of servers (the agents), which for Veracity are roughly 1:1 with computers/users, so there is a tension between the established technical and marketing terminology.

The approach taken in this manual is to call a spade a spade and stick to the technical definitions, which describe what actually happens when a Veracity client/server connection occurs.

9.3 Agent Architecture

Introduction

This page provides an overview of Veracity agent architecture.

Essential Components Of A Veracity Agent

It helps, when getting a grip on a new system, to know the actual components that are used in the system. Here are the main components required to run a Veracity agent on a computer running TCP/IP:

Veracity executable: There must be a Veracity executable on the computer, preferably installed in an official utilities directory. If you have not installed Veracity yet, you should refer to the separate installation chapter.

Agent configuration file: When the agent starts up, it reads in a configuration file. However, this file is unnecessary if you are using a predefined configuration.

Agent startup command in system startup script: A command must be given (e.g. veracity agent start) to start the agent. You can give this command interactively, but it should probably be included in the system startup script so that the agent will be created afresh upon reboot.

Thatʼs all thatʼs required!

Other Components Of A Veracity Agent

The components above are all the components you will need to establish a Veracity agent. Once the Veracity agent is running, it will generate the following files:

Agent master logfile: The agent writes a master logfile that describes its behavior. It appends to the logfile each time it starts up or processes a request. You can specify in the Veracity agent configuration file whether you want the agent to write a master logfile and the location and name of the file.

Agent virtual agent logfiles: A logfile can be written for each virtual agent that logs the virtual agentʼs behavior. The number of these logfiles will depend on the number of virtual agents. You can specify whether each virtual agent has a logfile and the name of the logfile in each virtual agentʼs record in the Veracity agent configuration file.



PID file: When a Veracity agent starts up, it writes the process ID of the agent process to a PID file. The PID file is just an ordinary text file which is either empty (to indicate that the agent is not running) or contains a single line containing the agentʼs PID in ASCII decimal digits. You can specify whether you want a PID file and its name in the Veracity agentʼs configuration file. On platforms that support file locking, the agent also places an advisory lock on the PID file to confirm that the agent is running with the PID specified in the PID file. If the PID file is absent, it means that the agent has never been run, or someone has deleted the PID file manually. If the PID file is present but empty, it means that the agent was run sometime in the past but was stopped. If the PID file is present and contains a PID, but there is no process with that PID, or there is a process but the PID file is not locked, then the agent has been run sometime in the past, but terminated abnormally. PID files are not generated by agents running on Novell Netware.

Here are some other notes on the architecture.

Processes

After being started, a Veracity agent consists of a master process that persists indefinitely and which listens for connections coming from the outside world. Veracity agents may be configured to process connections in serial, in which case the master process processes each connection before accepting and processing the next one, or in parallel in which the master process creates a slave process that processes the connection and then terminates.

TCP Ports

Each Veracity agent listens for connections on a single TCP port. It is possible to run more than one Veracity agent on the same computer so long as each agent listens on a different TCP port. However, in most cases, there is no need to run more than one Veracity agent on a computer. A lone Veracity agent should listen to the official Veracity port of 1062 (decimal), (as allocated by IANA).

User-mode Agents

There is no requirement that an agent process run with “root” privilege. A non-privileged user can create a Veracity agent, so long as they choose an unused TCP port. The user-process agent will be able to access only those files that the user process can access.

Normally, however, the virtual agent architecture (see below) means that only one Veracity agent should be required per computer.

Virtual Agents

When a Veracity agent process is starting up, it reads in the configuration file (mentioned earlier). The configuration file contains, along with some master-agent settings, settings for one or more Veracity virtual agents. These virtual agents are similar to Apache virtual servers in that they exist only virtually and do not (necessarily) have a one-to-one relationship to physical computers or even to server processes.

Although remote clients connect with the master agent process (which may or may not fork off a slave process to process the connection), conceptually they connect to a single virtual agent and the connection proceeds according to the constraints and settings defined by that agent.



Conceptually, the master agent process does not process a connection; only one of its virtual agents can do that. If you do not define any virtual agents in the configuration file, no connection can be processed.

The three most important attributes of a virtual agent are its ID, its visible tree and its security.

ID: A virtual agentʼs ID is a name that is unique within the set of virtual agents running within the same Veracity agent.

Visible tree: Each virtual agent can only take snapshots within its visible tree. The visible tree is defined by a setting which takes the form of a directory path that identifies the root of the visible tree.

Security: A virtual agentʼs security setting defines the conditions under which a remote client may connect. A virtual agent can be configured to provide no security, in which case anyone may connect to the agent and take a snapshot (within its target tree). Alternatively, an agent can be configured to accept connections only from authorized clients, and to encrypt the TCP connection with DES3-CBC symmetric encryption.

Together, these attributes allow you to set up virtual agents, on a single machine, that provide public snapshot access to some parts of the file system and private access to other parts of the file system.

9.4 Installing A Veracity Agent

Installing A Veracity Agent Is Easy

The process of installing a Veracity agent has been engineered to be as easy as possible. You do not need to create or edit complicated configuration files, enter paths, or make decisions about dozens of detailed settings. Starting a Veracity agent is achieved with a single command. You do, however, you have to install the Veracity executable first! So, please do this before attempting to start a Veracity agent. Also, please read the following notice:

When a Veracity agent starts, it “checks in” by sending Rocksoft a single UDP datagram containing the date and time, the IP address of the agent, the platform, and so on. Once running, a Veracity agent also checks in about once a month. Checkins provide Rocksoft with useful statistics that help to improve future versions of Veracity. We think checkins are harmless, but if you do not want Veracity to checkin, you can disable checkins by creating your own configuration file and setting the Checkin field to No.

The One Minute Installation (Single User)

To start a Veracity agent that provides a single virtual agent for your account on a multi-user computer, simply give the following command:

veracity agent start

This is just short for: veracity agent start _single_user

You will be prompted for the password that the agent will use to restrict access. The agent uses the “SHA-DES” security method (described in a separate page in this chapter) and is extremely secure.

The agent is just a process and will not survive a reboot. If you want it to survive a reboot, you



should add the start command to your system startup file using a hashed password argument as shown in the command below. Hashed passwords are discussed later in this page.

veracity agent start _single_userSHA-EE33294C97C42FFF14EA73AB81E428A6FC7B9A8B

The ʻsingle userʼ configuration is not available for agents running on Novell Netware.

Windows NT/2000/XP Installation

In the normal case, a Windows NT/2000/XP service is started automatically by Veracityʼs Windows Installer. No more action need be taken.

To start the agent manually on Windows NT/2000/XP, go to ʻServicesʼ under the Control Panel, double click on ʻVeracityʼ and click ʻStartʼ; or just reboot. Note: this only applies if you have installed Veracity as a service.

You may also type ʻnet start veracityʼ at the command prompt. You can see if Veracity is running by typing ʻnet startʼ, which tells you all of the services currently running. If you encounter any problems, check the event log, under ʻAdministrative Toolsʼ.

Novell Netware Installation

To configure the agent to start whenever Novell Netware boots up, you need to modify your sys:\system\autoexec.ncf file. Before the startx command add the line:

load veracity agent run ...

Where the ellipses represents the options you will need to give to the Veracity agent.

The One Minute Installation (All Users)

If you are a system administrator and want to start a Veracity agent that provides a separate virtual agent for each user (except root) of a multi-user computer, using each userʼs normal system password as their virtual agent password, simply log in as root and give the following command:

veracity agent start _users

The agent is just a process and will not survive a reboot. If you want it to survive a reboot, you should add the start command to your system startup file (e.g. rc.conf).

This form of installation uses the System security method, which provides a similar level of security as (non-SSL) telnet connections. This is not as secure as the SHA-DES security method (which is why this configuration does not provide a virtual agent for the root account), but still provides reasonable security. See the page in this chapter on the “System” security method for more information. If you want to provide a SHA-DES-method virtual agent for each user, you should create your own agent configuration file.

The ʻall usersʼ configuration is not available for agents running on Novell Netware.

Taking A Remote Snapshot

Once you have started a Veracity agent, you can take a snapshot remotely (or from the same



computer) using a command similar to the following command: veracity snapshot dave:[email protected]/users/dave/ +v

The various parts of the command are: dave -- Virtual agent ID (usually your username).sesame -- Virtual agent password (usually system password)domain.com -- Computer running Veracity agent./users/dave/ -- Full path of directory tree to snapshot.+v-- Option progress-tracing flag.

The snapshot will appear in the file 0veracty.vsf in the current directory on the client computer (the one on which youʼre running the snapshot command).

Once you have taken a snapshot, you can use it in a variety of ways, as described in other parts of this manual. In particular, to compare the snapshot against the previous snapshot taken, you can say:

veracity signoff

To compare it to the current directory tree on the client computer, you could say: veracity check

There are many other ways the snapshot file can be used.

Stopping The Agent

To stop the agent, simply delete its process, or use the following command: veracity agent stop

If you try and start a Veracity agent when there is already one running, Veracity will generate an error. This protects you against accidentally starting up multiple agents.

It is possible to run more than one Veracity agent on the same computer by using different ports or by listening on different IP addresses, but you have to make a special effort in the agent configuration files to do so. See the agent configuration file documentation for details.

To stop an agent running on Novell Netware type: unload veracity

Uninstalling Veracity under Windows

On all platforms other than Windows, nothing need be done but delete the Veracity executable and the text files, which are all in the directory you placed them when you installed Veracity (probably C:\veracity).

Under Windows, you can run the ʻUninstall Veracityʼ menu command, or select ʻRemoveʼ for Veracity in ʻAdd/Remove Programsʼ in the Control Panel.

If you want to manually ensure you have a clean system you can either: c:\veracity\vserve -remove ! This also stops veracity.delete c:\veracity



or NET STOP VERACITY ! (or control panel equivalent)Run “regedt32”, the registry editor (‘regedit’ on Win95/98/ME).Delete HKEY_LOCAL_MACHINE /System/CurrentControlSet/Services/VeracityDelete C:\veracity

The System Installation

The installations described above are perfect for providing a Veracity virtual agent service for one or all the users of a multi-user machine such as a webserver. However, they do not provide a way to monitor the computerʼs system files, as they do not fall within any userʼs home directory tree. To start a Veracity agent that provides a single virtual agent that covers the entire file system, give the following command (as root).

veracity agent start _system

You will be prompted for the agentʼs password. If you want to start the agent from within a startup script, you should provide a hashed password on the command line (see a later section in this page for more information).

Once you have started a system agent, you should be able to take a snapshot of any directory on the computer.

This _system installation uses the SHA-DES security method and is extremely secure. For more information, see a separate page in this chapter on the SHA-DES security method.

If you want to run the system virtual agent (using the hashed password) AND provide a virtual agent for every user (using their own system passwords) and the agent isnʼt running on Novell Netware, you can use:

veracity agent start _users_system

Custom Installations

The installations described above should cover most usersʼ needs for a Veracity agent. The installations above work by referring to predefined configuration files built into the Veracity executable itself. For example, when you say:

veracity agent start _single_user

Veracity sees the leading underscore and looks up a predefined built-in configuration file called single_user. If it doesnʼt see a leading underscore then it looks for a real configuration file.

veracity agent start config.txt

It helps, when writing an agent configuration file, to start with a working configuration file. To obtain a copy of one of the predefined configuration files used by the installations described above, give one of the following commands:

veracity agent save _usersveracity agent save _systemveracity agent save _users_systemveracity agent save _single_user



For information on the syntax and semantics of Veracity agent configuration files, see a separate page in this chapter.

Only the “system” predefined configuration file is available under Novell Netware.

Specifying Passwords

When you invoke a Veracity agent using a configuration that requires a password (e.g. configuration single_user), you can provide the password in three ways. First, you can omit it from the command line, so that you are prompted for it interactively:

veracity agent start _single_userAgent password: sesame

Second, you can provide it on the command line as shown below. This is not advisable though, as on Unix, the ps command allows other processes to see a processʼs command line.

veracity agent start _single_user sesame

Third, you can generate a hashed version of the password and provide that on the command line. You can generate a hashed password as follows:

veracity agent hashpw sesameHashes of this password are:SHA-EE33294C97C42FFF14EA73AB81E428A6FC7B9A8BHAVAL-78CCF663BBCED5157103B8BFABDF790E

The command provides two hashes, but the predefined configuration files all use SHA hashing, so you should use SHA- hash for non-customized installations. Once you have generated this hash, you can provide it instead of the password. For example:

veracity agent start _single_userSHA-EE33294C97C42FFF14EA73AB81E428A6FC7B9A8B

The hashed password is recognized as a hashed password by its SHA- prefix.

9.5 The AGENT RUN CommandThe veracity agent run command runs the agent interactively and echoes output to the agentʼs logfile to standard output so you can see what the agent is doing.

Once you give this command, Veracity will start up and then act as a Veracity agent. As agents are supposed to run indefinitely, you wonʼt get your interactive prompt back unless you interrupt the agent. This command is useful for debugging agent configuration files and testing the agent directly.

The command takes a single configuration file argument. If the argument starts with an underscore, the command will look for a predefined configuration file of the same name (but without the underscore). If your configuration file name starts with an underscore, you should rename it to avoid confusion, but a second alternative is simply to provide a full pathname.

If you do not provide a configuration file argument, the default predefined configuration file will be used.

If you provide one or more arguments after the configuration file name argument, these will



appear in the macros $1, to $7 for use in the configuration file. Syntax:“agent run” [ s config_file [arg1 [arg2 ... ]] ]Examples:veracity agent runveracity agent run config.txtveracity agent run _usersveracity agent run _systemSHA-EE33294C97C42FFF14EA73AB81E428A6FC7B9A8B

9.6 The AGENT START CommandThe veracity agent start command creates a new process and sets it running indefinitely as a Veracity agent. This command provides the simplest means of starting a Veracity agent.

The command takes a single configuration file argument. If the argument starts with an underscore, the command will look for a predefined configuration file of the same name (but without the underscore). If your configuration file name starts with an underscore, you should rename it to avoid confusion, but a second alternative is simply to provide a full pathname.

If you do not provide a configuration file argument, the default predefined configuration file will be used.

If you provide one or more arguments after the configuration file name argument, these will appear in the macros $1, to $7 for use in the configuration file.

Syntax:“agent start” [ s config_file [arg1 [arg2 ... ]] ]Examples:veracity agent startveracity agent start config.txtveracity agent start _usersveracity agent start _systemSHA-EE33294C97C42FFF14EA73AB81E428A6FC7B9A8B

9.7 The AGENT STOP CommandThe veracity agent stop command looks for a Veracity process owned by the current user, and if it finds one, terminates it.

The command determines which process to delete by referring to the agentʼs PID file. When a Veracity agent starts up, it writes the PID of the agentʼs master process to the file specified in the PIDFile field of the agentʼs configuration file. The agent stop command looks for the PID file, first by checking the environment variable VERACITY_AGENT_PID_FILE. If this variable is defined, it uses its value as the file specification for the PID file. If the variable is not defined, the agent stop command looks in various likely places where the file might be, for example files called veracity.pid in the current directory or userʼs home directory. If the platform is Unix and you are a superuser, it will look for /var/run/veracity.pid too.

If a PID file is not found, the command will write out a list of the places where it looked for the PID file. You can then either modify your agentʼs configuration file to instruct the agent to write its PID file to one of those places, or define an environment variable that identifies your own PID file.



If a PID file is found, the command reads the PID file. If the PID file is empty, the command states that the agent is not running. Otherwise, it attempts to read a PID from the file. If it succeeds, it looks for a process with that PID. If it finds such a process, it looks to see if the PID file is locked (Veracity agents lock their PID files to indicate that they are running (on platforms that allow locking)). If the PID file is locked, the command attempts to terminate the process with the specified PID, first gently, then, if necessary, with a SIGKILL. The command looks to see if the process still exists after it issues the signals, and will let you know for sure whether it succeeded or failed. If it succeeds, it sets the PID to empty.

Syntax:“agent stop”Examples:veracity agent stop

Note: If the master agent has forked off one or more child processes to process inbound connections, those processes will continue unhindered to complete the processing of their connections. This is desirable because it means that (unless you are running your agent in sequential mode (MaxProc=0)), stopping an agent using the agent stop command cannot interrupt the processing of any connection.

To stop an agent running on Novell Netware type: unload veracity

9.8 The AGENT HASHPW CommandThe veracity agent hashpw command provides a convenient way to generate the password hashes needed by the SHA-DES and HAVAL-TEA security methods in the Security field of virtual agent records in agent configuration files.

A password must consist only of characters from the set of characters consisting of decimal digits and upper and lower case letters. Passwords are case-sensitive.

Syntax:“agent hashpw” passwordExamples:veracity agent hashpw sesame

9.9 The AGENT SAVE CommandThe veracity agent save command writes a specified predefined agent configuration “file” to a specified file. The purpose of this command is to provide you with a starting point for creating your own customized sever configuration file. By saving a predefined configuration file, you can start with a working configuration file and modify it.

If you specify no arguments, this command will write the default configuration policy file (called “users”) to a file called veracity_config.txt in the current directory.

If the file to be written already exists, the command will generate an error. This is so as to prevent you from accidentally overwriting an existing configuration file.

The command will tolerate a leading underscore in the predefined configuration file argument (so as not to confuse those used to the syntax of the agent run and agent start commands), but



you donʼt need it. If you specify an unknown predefined agent configuration file, the command will list all existing predefined agent configuration files

Syntax : “agent save” [ predefname [ filename ] ]” Examples:agent saveagent save systemagent save _systemagent save _users /usr/dave/my_vagent.conf

9.10 Agent Configuration FileWhen a Veracity agent starts up, its only parameter is an agent configuration file which contains settings that instruct the Veracity agent on how it should behave.

Specifying An Agent Configuration File

To specify an agent configuration file, simply provide it in the command line when you start the agent (this also works in the same way for the agent run command).

veracity agent start myconfigfile.txt

If you do not specify a configuration file: veracity agent start

then the default predefined configuration “single_user” is used. You can also specify one of a range of other predefined configuration files by providing its name preceded by an underscore like this:


The predefined configuration files eliminate the need for most agent administrators to have to craft their own configuration file. For more information on predefined configuration files, see a separate page in this chapter.

You can provide extra arguments on the command line. These turn up in macros that can be used inside the configuration file (see the section on macros below). For example:

veracity agent start _systemSHA-EE33294C97C42FFF14EA73AB81E428A6FC7B9A8B

Example Veracity Agent Configuration File

An agent configuration file is just an ordinary text file containing the agent settings in text form. The file consists of a sequence of records each of which consists of a set of field name/value pairs. A master record controls the overall behavior of the agent. This is followed by one or more virtual agent records preceded by a default settings record for the virtual agent records. Hereʼs an example of an agent configuration file that sets up a single virtual agent called “system”.

=====(BeginServerConfigV1)=====

-----(BeginMasterServer)-----Arguments HashedPassword/I



ListenIP*ServerIP*ClientIP*Port 1062MaxProc 10MaxMemK 50000ServerDir $DLogFile $D.veracity_master.logPIDFile $D.veracity.pidUser $AGroup$BTimeoutMillisecs 30000CheckIn YesNeedsSuper YesAdminEmail $A@$C-----(EndMasterServer)-----

-----(BeginDefaultSettings)-----Enabled YesServerIP *ClientIP *AllowDataNoAllowFollow NoAllowFollowCycle NoAllowWrite NoTimeoutMillisecs 30000MinDelayMillisecs 0MaxDelayMillisecs 2000DomainNoneDomainAlias NoneCompression *-----(EndDefaultSettings)-----

# Define a secure virtual server that serves all files.-----(BeginVirtualServer)-----ID systemDesc The $C $V ServerSecurity SHA-DES:$1VisibleTree *LogFile NoneMasterLogYesUser $AGroup $BAdminEmail $A@$C-----(EndVirtualServer)-----

=====(EndServerConfig)=====

Textual Requirements

The configuration file must consist of ASCII seven-bit printables. Each line must not contain any trailing spaces. The last line must be correctly terminated.

Lines commencing with a run of zero or more spaces followed by the hash character (#) are treated as comment lines and ignored. Blank lines are also ignored. All other lines are parsed as delimiters or fields.



Master Agent Settings Record

The first record is called the master agent settings record. It contains the global settings for the master agent such as the name of its logfile and the email address of its administrator. The master record must contain exactly one occurrence of each possible master record field, but the fields can be in any order. See the Master Agent page for a complete description of these fields.

-----(BeginMasterServer)-----Arguments HashedPassword/IListenIP*ServerIP*ClientIP*Port 1062MaxProc 10MaxMemK 50000ServerDir $DLogFile $D.veracity_master.logPIDFile $D.veracity.pidUser $AGroup$BTimeoutMillisecs 30000CheckIn YesNeedsSuper YesAdminEmail $A@$C-----(EndMasterServer)-----

Virtual Agent Default Settings Record

The second record is called the virtual agent default settings record. It contains zero or more fields, being the default settings for the list of virtual agents to follow. A virtual agent may override a default setting. The default settings record is allowed to have any field that a virtual agent record can have, except ID.

-----(BeginDefaultSettings)-----Enabled YesServerIP *ClientIP *MasterLogNoAllowDataNoAllowFollow NoAllowFollowCycle NoAllowWrite NoTimeoutMillisecs 30000MinDelayMillisecs 0MaxDelayMillisecs 2000DomainNoneDomainAlias NoneCompression *-----(EndDefaultSettings)-----

Virtual Agent Settings Records

Following the default settings record is a sequence of one or more virtual agent records, each of which defines a single virtual agent. Each virtual agent must have a unique ID field and must contain every possible virtual agent field, with the exception that it may omit a field if the field



appears in the virtual agent default settings record. See the Virtual Agent page for a complete description of these fields.

-----(BeginVirtualServer)-----ID systemDesc The $C $V ServerSecurity SHA-DES:$1VisibleTree *LogFile NoneMasterLogYesUser $AGroup $BAdminEmail $A@$C-----(EndVirtualServer)-----

Macro Expansion

A macro expansion scheme is applied to all field values when the configuration file is read. The macro “escape” character is $. Here are the macros available:

$$ - ‘$’$[ - Pathname relative path base.MacOS= “:”Unix = “./”OpenVMS = “[.”Windows = “.\”Netware = “.\”$. - Pathname separator.MacOS= ‘:’Unix = ‘/’OpenVMS = ‘.’Windows = ‘\’Netware = ‘\’$] - Pathname closer.MacOS= ‘:’Unix = ‘/’OpenVMS = ‘]’Windows = ‘\’Netware = ‘\’$/ - Same as $]$1... - Arguments to “agent start” or “agent run” command.$7$A - Username of user running agent (e.g. “root”).$B - Group of user running agent (e.g. “wheel”).$C - Name of the computer (domain name) (e.g. “www.domain.com”).$D - Login dir of user running agent (e.g. “/root/”).$V - “Veracity” or “FreeVeracity” depending on agent program.$Z - “.” under Unix. “” on other OSs.

All other letter macros are legal, but map to the empty string. Letter macros must be in upper case. Lower case will result in a parsing error.

Macros $A, $B & $D are not available for agents running on Novell Netware.

IP Address Pattern Lists



Some fields contain IP address pattern lists. As these lists have a non-trivial syntax, their syntax is described here instead of each field having this syntax.

The purpose of an IP address pattern list is to define a subset of the set of IP addresses. In the context of a settings field this subset is interpreted as a constraint. For example, the ClientIP field, which has IP address pattern list syntax, defines the set of acceptable client IP addresses.

An IP address pattern list can consist of a single asterisk. This special-case form is interpreted as the set of all IP addresses (i.e. no constraint).

If an IP address pattern is not a single asterisk, then it must consist of a sequence of one or more IP address patterns, separated by commas. Each pattern defines a set of IP addresses and the entire pattern list defines the set consisting of the union of its component patterns.

Each pattern consists of a dotted decimal IP address, each of whose four byte parts can be expressed as a decimal number or as a single asterisk (which allows any value for that byte). Following the dotted decimal is an optional mask width. If this mask width is present, then it defines the number of bits, starting at the left of the 32-bit IP address and working right, that matter. For example, if the mask width were /20 then only the top 20 bits of the preceding 32-bit value would contribute to the constraint. The asterisks in the value and the mask width are both applied together, so, for example, the pattern *.2.3.4/24 is equivalent to the pattern *.2.3.*. Here is the formal syntax of IP address pattern lists.

pattern = “*”pattern = ip_pat { “,” ip_pat }ip_pat = dotted [ “/” num ]dotted = numw “.” numw “.” numw “.” numwnumw = “*” | numnum = digit { digit }digit=

Here are some example IP address pattern lists: *1.2.3.41.2.3.*1.2.*.**.*.*.**.2.3.4/201.2.3.4,5.6.7.8,12.13.14.151.2.3.*,1.2.4.*,3.4.*.*1.2.3.4/27,1.2.3.127/27

Wildcard Agents

In addition to ordinary virtual agents, a configuration file may specify a single “wildcard agent”. A virtual agent is a wildcard agent if its ID field is an asterisk:

ID *

In this specific context, the asterisk is deemed to match the username of any account on the agentʼs computer.

When a client connects to a Veracity agent, specifying an ID, the agent first looks for a virtual agent with exactly that ID. If it canʼt find one, it looks to see if there is a wildcard agent, if there



is, and the ID matches a username on the computer, then it creates an instantiation of the wildcard agent by expanding the following macros in the wildcardʼs agent fields. These macros are only available in wildcard agents.

$$U - Username of instantiated user.$$H - Home directory of instantiated user.$$G - Group of instantiated user.

The macros must be written with two dollars signs so that the dollar sign survives the first round of macro expansion which occurs when the configuration file is parsed.

These macros are not available for agents running on Novell Netware.

Here is an example of a wildcard virtual agent: -----(BeginVirtualServer)-----ID *Desc “The $$U $V Server”Security System:$$UVisibleTree $$HLogFile $$H.veracity.logUser $$UGroup $$GAdminEmail $$U@$C-----(EndVirtualServer)-----

Note that, in the above example, the security method is set to “System”. This means that the instantiated virtual agent will use the instantiated userʼs normal system password for authentication. The wildcard agent, along with the System authentication method, allows the default predefined configuration file (called users) to set up a virtual agent for every user on a computer without having to list all the users explicitly or set up passwords for them explicitly.

9.11 Master Agent SettingsThis page contains a description of each master agent settings record field. The fields are described here in alphabetical order, but can appear in the record in any order so long as they are all present.

Example Master Agent Settings Record-----(BeginMasterServer)-----Arguments Password/IListenIP*ServerIP*ClientIP*Port 1062MaxProc 10MaxMemK 50000ServerDir $DLogFile .veracity_master.logPIDFile .veracity.pidUser daveGroupusersTimeoutMillisecs 30000CheckIn Yes



NeedsSuper YesAdminEmail [email protected](EndMasterServer)-----

AdminEmail

The AdminEmail field provides the agent with an email address for the administrator of the Veracity agent. The agent might send email to the administrator if something goes wrong. The email address is treated by the agent as public information and may be conveyed to clients in error messages. In the current implementation you can only specify one email address.

AdminEmail [email protected]

Recommendation: Set this email to your personal email address until you get used to the Veracity agent. At a later date you can direct it somewhere else.

Arguments

The Arguments field provides an opportunity for you to describe the additional command line arguments that the configuration file requires when it is invoked. For example, the single_user predefined configuration file requires a single argument like this:

veracity agent run _single_userSHA-EE33294C97C42FFF14EA73AB81E428A6FC7B9A8B

When the configuration file is parsed, the hex argument appears in the $1 macro. If the user forgets the argument, the $1 macro will expand to the empty string somewhere in the configuration file, and the user will get a confusing configuration file syntax error rather than a message stating that not enough arguments were provided.

The Arguments field provides a way to specify how many additional arguments the configuration file expects, and what they are called. Use the value None if there are no arguments. Examples:

Arguments NoneArguments HASHEDPASSWORDArguments USER HASHEDPASSWORD

Now, if the user forgets an argument, Veracity will write out a message listing the arguments required.

If you want Veracity to prompt for missing arguments instead of writing an error message, append a qualifier on the end of each argument you want to be prompted for, like this:

Arguments HASHEDPASSWORD/IArguments USER/P HASHEDPASSWORD/I

/P is for prompting with echo. /I is for prompting with no echo (invisible).

Note: It is important that this field appear in the configuration before the first use of any macro (e.g. $1), otherwise an empty macro value could trigger a syntax error in the file before the arguments field is parsed. This would result in an error message stating that there is a syntax error in the configuration file rather than an error message stating that there are not enough arguments and using the arguments field to provide a template of required arguments.

Note: This field protects only against users who provide too few arguments. It does not protect



against too many arguments, or syntactically incorrect arguments. The field is designed to avoid presenting a confusing syntax error when the user forgets an argument.

Recommendation: Set this field to None if your configuration file does not use any of the dollar macros ($1, $2 etc). If it does use one or more of these macros, set the field to the right number of argument descriptors.

CheckIn

The CheckIn field determines whether the Veracity agent will checkin to Rocksoft. If checkin is turned on, the Veracity agent will send a message to Rocksoft when it starts up and every 30 days thereafter. Each check-in message consists of a single UDP datagram and contains the following information:

• Type of message (Veracity checkin message).

• Check-in record format version.

• Name of the Veracity agentʼs host computer.

• IP address of the Veracity agentʼs host computer.

• IP address on which agent is listening.

• TCP port on which agent is listening.

• Local date and time on the agent.

• Agentʼs platform (operating system).

• Agent program (e.g. Veracity).

• Program version.

• Name of configuration file (“custom” if not predefined).

• Is the agent running in privileged mode?

• Number of days agent has been running.

• Number of connections processed by the agent.

• Checksum of the previous fields.

Startup check-ins allow Rocksoft to:

• Determine how many copies are in use.

• Determine the version mix of active copies.

• Determine the platform mix of active copies.

• Determine which predefined configuration files are popular.

• Have a shot at detecting large numbers of unlicensed copies.



The Checkin field takes a Yes/No value: CheckIn NoCheckIn Yes

Recommendation: Set this field to Yes. Checkins cost just a few bytes of network traffic and provide Rocksoft with useful feedback. You should set this field to No only if you believe that communicating this information in plaintext through the internet to Rocksoft would impact your security in some way.

ClientIP

The ClientIP field defines a constraint on the IP address of connecting clients. If a connection arrives with a from IP address that does not satisfy the constraint, the agent will close the connection.

This field consists of an IP Address Pattern List. ClientIP *ClientIP 1.2.3.4ClientIP 1.2.3.*ClientIP 1.2.3.4/20ClientIP 1.2.3.*/23ClientIP 1.2.3.4,4.5.6.*/20

This constraint is applied by the master agent when connections arrive. Once the conversation has reached the point where a virtual agent has been identified, the virtual agentʼs ClientIP constraint will be applied too.

See also the ListenIP field and the ServerIP field.

Recommendation: Set this field to its wildcard value (*). This will not impair security, so long as your virtual agents are securely configured. However, if you want to tighten your security, then you should consider using this field. If you are using Veracity for internal corporate security, and outside connections are not expected, it would be prudent to filter all but connection originating from within your organization.

Group

When the master Veracity agentʼs process starts up, it attempts to change the processʼs GID to that of the group specified in this field. If it cannot change its group to the specified group, it aborts the startup with an error. On Unix, the master agent will only be able to change the group if the master agent is started as the superuser or as the group specified in this field.

This field is not available for agents running on Novell Netware.

Once the master agentʼs process has changed its group to the specified group, it remains in that group until it terminates. If the Maxproc setting is zero, the master agent will process each connection itself and will make no attempt to change its group for each connection. However, if the Maxproc setting is positive, the master agent will fork off a process to handle each inbound connection. Each such child process will initially inherit the master processʼs group. However, if the invoked virtual agent specifies a group in its Group field, the child process will attempt to change its group before processing the connection, and will abort if it cannot.



If you specify a value of * in this field, the master processʼs group will not be altered on startup.

This field can be used to improve security by restricting the master agent and all its children to having on the powers of a particular group.

The field will usually be specified as a group name. However, if the field consists of a hash followed by decimal digits (e.g. #1001) then this is converted directly into a GID. If the field is of the form “group(USERNAME)” then the group is set to the group of the specified username.

Group *Group wheelGroup usersGroup group(dave)Group #1001

Recommendation: Set this field to * unless you are certain that you want to define the group of the Veracity master agent process.

LogFile

The LogFile field provides the complete pathname of the master logfile. The master agent appends messages about its activity to the logfile. If you do not want a master logfile to be written, use the value “None” or “none”.

LogFile /var/log/veracity_log.txtLogFile None

Recommendation: It doesnʼt much matter where the logfile resides. Just be sure to specify a logfile to which the agent is capable of writing. You may also wish to place the logfile in a place in the file system where it is hidden from users. If you are running more than one Veracity agent, you should take care to ensure that the different agents use different log files.

MaxMemK

The MaxMemK field sets the maximum number of kilobytes of heap space that any one agent process (master or child) may consume. This is a limit not on the total amount of memory consumed by a process, but the amount of memory procured for the heap using malloc.

If an agent process exceeds the limit, it will abort the request it is processing at the time, generate an error message in the appropriate logfiles, but keep on running. If the process in question is a child process, it will terminate as usual. If it is a master process, it will wait for its next connection. Veracity has been carefully engineered to ensure that if the agent runs out of memory during a run, it can recover completely and continue to process more connections, even if it is running with MaxProc=0.

This field is expressed in decimal and must not exceed the machineʼs architectural memory width. If you specify a value of None then this explicitly specifies that there is to be no limit.

MaxMemK 50000MaxMemK None

The value of this field completely overrides the Veracity default memory limit.

If you specify a memory limit on the command line using the M option when you start the agent,



that option will override this field completely.

Recommendation: If you are running your Veracity agent as a root process (on which there are no OS-imposed limits) then you should be sure to set a memory limit so as to ensure that the Veracity agent does not, under any circumstances, consume so much memory that it crashes the computer. A good safe value is 30000 (30M) as Veracity is known to be able to run over an entire Unix file system with about 10M. However, you may wish to use a higher value if you have directories with tens of thousands of files, or are using the *.data attributes on large files. You may wish to use a lower value if memory is in short supply on your computer. If you are not running your Veracity agent as a root process, then a memory limit is less critical, but probably still a prudent idea.

MaxProc

The MaxProc field sets the maximum number of child processes that the master agent process is allowed to have active at any one time. Once there are this many child processes, further connections will be rejected until a child process terminates. If you set this field to zero, the master agent will process every connection itself, sequentially. If you set this field to a positive value, the master agent will always fork a child process to handle each connection.

This field is ignored on platforms that do not support forking. On those platforms, no child processes are created, and all connections are processed by the master agent process sequentially.

If the MaxProc value is zero, then there will be no agent child processes and the User and Group fields in the virtual agent records will be ignored. Currently this field must be set to zero for agents running on Novell Netware.

This field is expressed in decimal and must be in the range [0,1000000]. MaxProc 10

Recommendation: If you are setting up a public Veracity agent, itʼs possible that the agent could be subject to huge spikes in traffic when you announce the agent, so itʼs probably a good idea to set this value quite high (e.g. 20). However, if you are installing a Veracity agent on a corporate computer solely so that a central client can check the computerʼs integrity, then a value of zero might be appropriate because it would cause the client to generate an error if it happened to hit the agent at the same time as an intruder - which would be a useful security signal.

PIDFile

The PIDFile field provides the complete pathname of the PID file. The PID file is a small text file that the master agent writes (and locks (on platforms that support locking)) upon startup. It contains the PID (process identification) of the Veracity agent master process. The PID file is used by the agent start and agent run commands to determine if an agent is already running before starting a new one. The PID file is also used by the agent stop command to stop the agent. The PID file is also useful to system administrators who want to stop the agent process manually without having to do a process listing to identify the PID. For example, under Unix:

Unixshellprompt> kill -9 `cat .veracity.pid`



If you do not want a PID file to be written, use the value “None” or “none”. However, if you do this, you wonʼt be able to use the agent stop command to stop the agent, and the agent start command will attempt to start an agent even if there is already one running (which will usually yield an error message saying that the new agent could not start because it could not allocate the agentʼs TCP port). This field is not available for agents running on Novell Netware.

PIDFile /var/run/veracity.pidPIDFile None

Recommendation: It doesnʼt much matter where the PID file resides. Just be sure to specify a PID file to which the agent is capable of writing. Also, if you are running more than one Veracity agent, you should take care to ensure that the different agents use different PID files.

Port

The Port field provides the number of the TCP port on which the master agent should listen for inbound client connections. This field is expressed in decimal.

The official Veracity port (as assigned by the Internet Assigned Numbers Authority (www.iana.org)) is TCP port 1062 (decimal) as shown in the official list of port allocations at: http://www.isi.edu/in-notes/iana/assignments/port-numbers

Port 1062

Recommendation: You should use the standard Veracity port number 1062 unless you either wish to “hide” the Veracity agent on some obscure port (security by obscurity!) or wish to run more than one Veracity agent on your computer.

ListenIP

The ListenIP field defines the set of IP addresses on which the agent will listen; that is, the set of IP addresses that packets sent from a client to the agent must be addressed to. This field is the first IP address constraint to be applied and is implemented at the bind()/accept() level.

You may specify an asterisk or a single IP address in dotted decimal. If you specify an asterisk, then the Veracity agent will listen on all IP addresses associated with the Veracity agentʼs host computer. If you specify a single IP address, it must be an IP address associated with the host computer, and the Veracity agent will listen on that address only.

This field is useful on computers that have more than one IP address, such as gateways and many webservers.

If you are managing a computer that is used by two different entities with two different IP addresses, this field allows you to run two different Veracity agents, one for each IP address, with each agent configured with its own set of Veracity virtual agents in accordance with the wishes of each entity.

The rules of TCP port/IP allocation and listening mean that you cannot create more than one Veracity agent listening on the same port unless all the agents are listening on separate distinct IP addresses. It is not possible to run two or more agents on the same port if at least one of them is listening to all IP addresses using “*”.

ListenIP *



ListenIP 1.2.3.4

A further level of agent target IP address filtering is available in the ServerIP field. The ListenIP field specifies the set of addresses to which the agent will pay any attention. Once a connection arrives, the address to which the client addressed its connection is subject to a further level of filtering in the ServerIP field. Once a virtual agent has been selected the virtual agentʼs ServerIP constraint is applied too.

Recommendation: Set this field to * unless you either want to improve security by responding to only one IP address, or unless you want to run two or more Veracity agents that listen to the same port on the same computer using different IP addresses.

ServerIP

The ServerIP field defines a constraint on the IP addresses to which clients may connect. If a connection arrives with a to IP address that does not satisfy the constraint, the agent will close the connection. This constraint is applied after, and in addition to, the ListenIP constraint.

This field consists of an IP Address Pattern List. ServerIP *ServerIP 1.2.3.4ServerIP 1.2.3.*ServerIP 1.2.3.4/20ServerIP 1.2.3.*/23ServerIP 1.2.3.4,4.5.6.*/20

This fieldʼs constraint is applied by the master agent when connections arrive. Once the conversation has reached the point where a virtual agent has been identified, the virtual agentʼs ServerIP constraint will be applied too.

See also the ListenIP field and the ClientIP field.

Recommendation: Set this field to its wildcard value (*). This will not impair security, so long as your virtual agents are securely configured. However, if you want to tighten your security, then you should consider using this field. If you want your agent to respond only to connections addressed or one particular IP address, then use the ListenIP field. If you want your agent to respond only to connections addressed to a small subset of IP addresses, then set the ListenIP field to * and list the IP addresses in the ServerIP field.

NeedsSuper

The NeedsSuper field tells the master agent whether the author of the agent configuration file thinks that superuser powers are needed to animate this configuration file. If this field is set to Yes and the process attempting to run or start the Veracity agent is not a superuser process, the agent will abort the startup with an error message explaining that superuser powers are required. This field is not available for agents running on Novell Netware.

This field is useful when you want to avoid underprivileged startups. NeedsSuper YesNeedsSuper No

Recommendation: Set this field to Yes if your configuration file contains a wild agent or if it



provides access to more than one userʼs files.

ServerDir

The ServerDir field specifies the directory that the master agent and virtual agent processes set as current when they start up. The purpose of this field is to ensure that if one of these processes writes any file (e.g. core dump) it goes somewhere where it wonʼt do any damage.

This field must be a legal absolute directory path, including the trailing delimiter. If you wish to set it to the home directory of the user that starts the agent, use $D.

ServerDir $DServerDir /var/run/veracity/

Recommendation: Set this field to $D unless you have good reason to do otherwise.

TimeoutMillisecs

The TimeoutMillisecs field specifies the number of milliseconds that the master agent should wait (before terminating the connection) if the client suddenly does not respond during the TCP conversation. During the processing of a connection, this timeout value prevails until the conversation has reached the point where a virtual agent has been identified. At that point, the virtual agentʼs TimeoutMillisecs setting prevails until the connection is terminated.

TimeoutMillisecs 30000

Note: The semantics of this field are not yet implemented.

Recommendation: Set this field to 30000 (30 seconds), unless you can think of a better value.

User

When the master Veracity agent process starts up, it attempts to change the processʼs UID to that of the user specified in this field. If it cannot change its user to the specified user, it aborts the startup with an error. On Unix, the master agent will only be able to change its user if it has started as the superuser or as the user specified in the User field. This field is not available for agents running on Novell Netware.

Once the master agent process has changed its UID to that of the specified user, it retains that UID until it terminates. If the Maxproc setting is zero, the master agent will process each connection itself and will make no attempt to change its user for each connection. However, if the Maxproc setting is positive, the master agent will fork off a process to handle each inbound connection. Each such child processes will initially inherit the master processʼs user. However, if the invoked virtual agent specifies a user in its User field, the child process will attempt to change its user before processing the connection, and will abort if it cannot.

If you specify a value of * in this field, the master processʼs user will not be altered on startup.

This field can be used to improve security by restricting the master agent and all its children to having the powers of a particular user.

The field must be specified either as the wildcard * or as a username. User *



User thomasUser richardUser henry

Recommendation: Set this field to * unless you are certain that you want to define the user of the Veracity master agent process.

9.12 Virtual Agent SettingsThis page contains a description of each virtual agent settings record field in alphabetical order. These fields can appear in virtual agent default settings records and virtual agent records.

Example Virtual Agent Settings Record-----(BeginVirtualServer)-----ID defaultEnabled YesDesc “The domain.com Default Veracity Server”Domaindomain.comDomainAlias veracity.domain.comSecurity NoneCompression *VisibleTree /www/LogFile /home/logs/vagent_ross.logMasterLogNoUser wwwGroup wwwClientIP *ServerIP *AllowDataNoAllowFollow NoAllowFollowCycle NoAllowWrite NoTimeoutMillisecs 300MinDelayMillisecs 0MaxDelayMillisecs 2000AdminEmail [email protected](EndVirtualServer)-----

AdminEmail

The AdminEmail field should contain the email address of a human that the virtual agent can notify if anything interesting happens.

AdminEmail [email protected]

Recommendation: If you are setting up a Veracity agent for the first time, you should set this field in all virtual agents to your personal email address so you can get used to how it all works. If you are setting up virtual agents for users on your computer, you should set this field to the email address of the user associated with the virtual agent.

AllowData

The AllowData field determines whether connecting clients are allowed to access the content of files. When a remote client connects to a Veracity agent, it provides the agent with a policy



file that tells the agent which file attributes should be included in the snapshot file. One of the classes of attributes that is normally available is the *.data class. These include:

B.data - The bytes in the file.T.data - The bytes with normalized EOLs.A.data - One of the above.U.data - MacOS: User fork.R.data - MacOS: Resource fork.S.data - MacOS: Resource fork system bytes.

So if the client specifies B.data for a file in a policy file, then the snapshot returned will contain the entire contents of the file. This may be undesirable for a variety of reasons. Here are some:

Network traffic: Allowing *.data attributes means that remote clients can suck the entire contents of your agentʼs visible tree through the net. You may not wish your agent to spend effort doing this.

Privacy: You may wish to serve the cryptographic hashes of a tree of files to the public without disclosing their contents.

Security: If you are running your Veracity agent in a security role, where the files on the computer are confidential, it would be imprudent to empower the Veracity agent to serve the content of the files, as your central client probably does not need the fileʼs contents to perform its security checks. Enabling the serving of file contents only runs the risk of an intruder one day exploiting the facility to read the contents of files on the serving computer.

On the other hand, content serving may be very useful in security applications for determining the actual changes that have been made to security-critical files.

AllowData NoAllowData Yes

Recommendation: Set this field to No unless you can think of a good reason why you want to serve file contents.

AllowFollowThe AllowFollow field determines whether to allow the client to instruct the agent to follow symbolic links when traversing the visible tree. When a remote client connects to a Veracity agent, it provides the agent with a policy file that contains directives about how the agent should traverse the target tree. One of the classes of pseudo attributes that is normally available is the follow class. These include:

follow - Follow symbolic links.follow_dir- Follow links only to directories.follow_file - Follow links only to regular files.follow_vol- Follow links only to volatile files.* follow_cycle - Traverse cyclic directories.

In an agent context, these directives can pose a security risk because they could enable the client to access information about files outside the agentʼs designated visible directory tree. This can only happen if the tree actually contains a symbolic link to some other part of the file system, so itʼs probably a minor risk, but itʼs always a good idea to eliminate even minor risks unless one has a reason not to.



The AllowFollow field of the virtual agent record indicates whether the virtual agent should allow these follow attributes to appear in policy files. The follow_cycle is omitted from this list, being controlled by a separate virtual agent field called AllowFollowCycle.

AllowFollow NoAllowFollow Yes

Recommendation: Set this field to No, unless you can think of a good reason why you want to allow clients to potentially stray outside the confines of your virtual agentʼs designated visible tree.

AllowFollowCycle

Note: See the AllowFollow field for background information.

The AllowFollowCycle field determines whether the agent will allow the follow_cycle pseudo attribute to appear in policy files. The follow_cycle pseudo attribute instructs Veracity to traverse the directory file (to which the attribute is attached) even if the directory has been determined to be cyclic (i.e. it is contained within its own subtree (usually via a symbolic link)). This is an obscure pseudo attribute that will be of use only in the most special circumstances where you wish to compare a cyclic tree with a corresponding unrolled tree and can write policy file productions that limit the application of this attribute to a finite number of directory levels.

AllowFollowCycle NoAllowFollowCycle Yes

Recommendation: Set this field to No, unless you can think of a good reason why you want to allow clients to be able to instruct your agent to traverse directory cycles if they are encountered in the visible tree. Donʼt set this to Yes unless you know what you are doing!

AllowWrite

The AllowWrite field determines whether connecting clients are allowed to modify the content of files using the Veracity RESTORE command. When a remote client connects to a Veracity agent, it provides the agent with a policy file that tells the agent which file attributes should be modified by the agent. One of the classes of attributes that is normally available is the *.data.* class.

So if the client specifies B.data.* for a file in a policy file, then the agent may modify the entire contents of its visible tree. This may be undesirable for a variety of reasons.

AllowWrite NoAllowWrite Yes

Recommendation: Set this field to No unless you are planning on using the Veracityʼs RESTORE functionality.

ClientIP

The ClientIP field defines a constraint on the IP address of connecting clients attempting to access the virtual agent. If a connection arrives for the virtual agent with a from IP address that does not satisfy the constraint, the agent will close the connection.

This field consists of an IP Address Pattern List.



ClientIP *ClientIP 1.2.3.4ClientIP 1.2.3.*ClientIP 1.2.3.4/20ClientIP 1.2.3.*/23ClientIP 1.2.3.4,4.5.6.*/20

This constraint is applied when the conversation with the client reaches the point where the client has identified a virtual agent. The conversation can only reach this point if the original connection to the master agent survived the master agentʼs ClientIP constraint.

See also the ServerIP field.

Recommendation: Set this field to its wildcard value (*). This will not impair security, so long as your virtual agent has a secure password. However, if you want to tighten your security, then you should consider using this field or the ServerIP field of the master agent. If you are using Veracity for internal corporate security, and outside connections are not expected to this virtual agent, it would be prudent to filter all but connections originating from within your organization.

Compression

The Compression field specifies the compression method that the agent will use to compress the snapshot file (and report) that it returns to the client. Compression reduces the amount of data that has to be sent through the network when a snapshot is taken.

A value of None means that the agent will not use any compression. All clients should be able to use the None method.

A value that is the name of a supported compression method means that the agent must use that method only and reject clients that do not support that method.

Currently there are four compression methods defined:

RLC (Run Length Coding) A very fast algorithm but with minimal compression.

GZip This compression algorithm is about 10x slower than RLC but provides much better compression.

FastGZip This is the GZip compression algorithm set for speed over compression. It is almost as good at compression as standard GZip but is about twice as fast.

BZip2 This compression algorithm is anywhere from 4x to 10x slower than GZip depending on the file, but provides better compression.

You can compare the compression ratio and compression speeds using the SELFTEST command.

A value of * means that the agent will send the client a list of methods that it supports (including None) and allow the client to choose a method. The client should choose the best method that it knows.

Compression *Compression NoneCompression RLCCompression GZipCompression FastGZip



Compression BZip2

Recommendation: Set this field to *. This value allows the client to choose any method supported by the agent, and so provides the maximum interoperability with client software. Set this field to a specific compression method only if you want to force a particular method (e.g. to ensure that bandwidth isnʼt wasted).

Desc

The Desc field contains a one-line description of the virtual agent. This description should be considered public information, as it is may be transmitted to clients when they attempt to connect to the agent. Desc field values are allowed to contain spaces, and there is no need to enclose them in quotes of any kind.

Desc The domain.com Default Veracity Agent

Recommendation: You should provide the name of the agentʼs computer (or domain associated with your virtual agent) and perhaps an indication of the purpose of the agent.

Domain

The Domain field contains the primary domain name to be associated with the virtual agent. When a remote client connects and does not provide a virtual agent ID, the domain name used by the client to connect to the master agent can be used to identify the virtual agent to which the client intended to connect.

This field is useful on webservers that support many virtual web servers under different domain names. The Veracity agent can support a corresponding set of Veracity virtual agents each of which is associated with a particular domain name. This allows users to connect to the Veracity agent using their own domain name without having to specify the ID of their Veracity virtual agent explicitly. If you do not wish to provide a value for this field, use the value None or none.

Domain domain.com

Recommendation: Set this field to the domain name associated with the virtual agent. If you are setting up just a single virtual agent, set this field to the domain name of its host computer.

DomainAlias

The DomainAlias field is the same as the Domain field except that it provides one or more additional domain names to be associated with the virtual agent. This allows the virtual agent to be identified if the remote client connects with either domain name. If you specify more than one name, separate them with one or more spaces. If you do not wish to provide a value for this field, use the value None or none.

DomainAlias NoneDomainAlias veracity.domain.comDomainAlias veracity.domain.com check.domain.com

Recommendation: Set this field to None unless you need your agent to be auto-identified during connections using a second domain name.

Group



When a Veracity master agent forks off a child process to process an inbound connection, the child process inherits the master agentʼs group. However, if the virtual agent that is accepting the connection has a Group field that has a value other than *, the child process will attempt to change its group to the specified group, and will abort with an error if it canʼt.

This field can be used to improve security by ensuring that the virtual agent can only access files that are readable by the specified group. This field is not available for agents running on Novell Netware. If the field consists of a hash followed by decimal digits (e.g. #1001) then this is converted directly into a GID. If the field is of the form “group(USERNAME)” then the group is set to the group of the specified username.

Group *

Group wheel

Group users

Group group(dave)

Group #1001

Note: This field has no effect if the master agentʼs Maxproc field is zero or if the value of this field is *.

Recommendation: If you are setting up a virtual agent that is supposed to be able to read the computerʼs entire file system, then itʼs best to set this field to * so that it inherits the master agentʼs group. However, if you are setting up a virtual agent for an individual user (e.g. so that the user can check the contents of their webspace) then you should set the group to the userʼs group.

ID

The ID must contain an identification identifier for the virtual agent that is unique within the set of virtual agents running on the particular Veracity agent. The ID must consist of characters from the set consisting of decimal digits, lower-case letters, underscore and hyphen.

This identifier may be used by remote clients to identify the virtual agent. If the remote client does not specify an ID, then the domain name used by the client to access the agent will first be used to identify a virtual agent. However, if this fails, the client will look for a virtual agent called default.

ID dave

Recommendation: If you are setting up a single virtual agent, call it default. This will allow you to omit the ID when you connect to the virtual agent. However, if you are primarily concerned with security, you may wish to specify a cryptic ID so as to provide an extra barrier for intruders (who would have to figure out the virtual agentʼs ID as well as its password). If you are setting up a virtual agent for each user on your computer, set the ID of each virtual agent to the corresponding username; this is not a requirement, but will avoid confusion.

LogFileThe LogFile field provides the complete pathname of the virtual agentʼs logfile. The virtual agent appends messages about its activity to the logfile. If you do not want a logfile for the virtual agent, specify the value “None” or “none”.

LogFile /home/dave/logs/veracity_log.txtLogFile None

Recommendation: It doesnʼt much matter where the logfile resides. Just be sure to specify a



logfile to which the virtual agent is capable of writing. If you are creating a virtual agent for each of your users, the logfile for each virtual agent should be in the userʼs directory tree.

MasterLog

The MasterLog field provides a way to suppress the logging of virtual agent activity to the master agentʼs logfile. By default, logging of virtual agent activity to the master agentʼs logfile and the virtual agentʼs logfile occurs independently, in accordance with their respective LogFile fields, with activity being logged to both the master agentʼs logfile and the virtual agentʼs logfile if both LogFile fields are specified.

The MasterLog field has no effect on this if it is set to Yes, but if it is set to No, it suppresses logging of the virtual agentʼs activity to the master logfile if there is one. This field is useful when you want to have a master log, but you donʼt want it cluttered with the virtual agent activity.

MasterLog No

MasterLog Yes

Recommendation: The appropriate setting for this field depends on how many virtual agents you have and the extent to which you wish to centralize logging. If you have a single virtual agent, itʼs probably best to centralize all logging in the master agentʼs logfile, in which case youʼll want to set the virtual agentʼs LogFile field to None and the MasterLog field to Yes. If you are running agents for just a few users, and providing them with logfiles, but want to keep track of things in the master log file too, then you should set the virtual agentʼs LogFile field to a filename and the MasterLog field to Yes. If you have many virtual agents, itʼs probably best to decentralize logging and keep the master logfile for master agent events only. In that case, you should set the virtual agentʼs LogFile field to a filename and set the MasterLog field to No. If this is all too confusing, just set the field to Yes.

MinDelayMillisecs

The MinDelayMillsecs field allows you to specify the minimum acceptable delay value that clients are allowed to specify when they connect. If a client specifies a lower delay, the agent will terminate the connection.

The delay value is the real-time delay that the agent will introduce in between reading each file when taking the snapshot. The delay is specified by the client in the +U argument of the snapshot command and by default it is zero.

This field is useful for controlling the amount of system resources that a particular virtual agent can consume. You may, for example, wish to allow a user to take snapshots of their webspace, but not at the cost of a sharp spike of resource use. This field allows you to slow down connections to a virtual agent so that they donʼt have such a sharp impact on system performance.

You can set different delays for different virtual agents, so that (for example) virtual agents used to check the security of the computer have no delay, whereas user virtual agents have a small delay.

This field must be in the range [0,1000000]. MinDelayMillisecs 0

Recommendation: Set this field to zero unless you anticipate system load problems of some kind. You might as well give remote clients speedy performance if your computer can cope with



the load. If you experience load problems, try a value of 100 and see if that helps.

MaxDelayMillisecs

The MaxDelayMillsecs field allows you to specify the maximum acceptable delay value that clients are allowed to specify when they connect. If a client specifies a higher delay, the agent will terminate the connection.

The delay value is the real-time delay that the agent will introduce in between reading each file when taking the snapshot. The delay is specified by the client in the +U argument of the snapshot command and by default it is zero.

This field is useful for ensuring that remote clients do not use the delay argument to create processes on your machine that take too long to process and terminate. It is conceivable that a malicious remote client could repeatedly connect and create dozens of slow-motion connections that use up process slots and memory and cause the master agent to bump up against the MaxProc limit. This field somewhat mitigates that possibility.

This field must be in the range [0,1000000]. MaxDelayMillisecs 2000

Recommendation: Set this field to 2000 (two second delay per file) to prevent remote clients from creating slave processes on your computer that take too long to run and chew up process slots and memory.

Security

The Security field defines the security method that will gate access to the virtual agent (along with the ClientIP and ListenIP settings). The field supports several different methods.

Security - None

If you specify None then the virtual agent requires no authentication. Anyone can connect to the virtual agent and no encryption is applied to the TCP connection during the connection.

Security None

Security - HAVAL-TEA

If you specify HAVAL-TEA (followed by a hashed password argument) then the virtual agent requires the client to provide a password (corresponding to the special argument). If the client provides the appropriate authentication, the remainder of the TCP conversation is encrypted with a session-key using TEA (Tiny Encryption Algorithm) symmetric encryption.

Security HAVAL-TEA:HAVAL-78CCF663BBCED5157103B8BFABDF790E

The hexadecimal argument is the big-endian upper-case hexadecimal representation of the HAVAL digest of the HAVAL digest of the ASCII representation of the password. The variant of HAVAL used is the 5 round 128 bit variant. The variant of TEA used is the 32-round revised version run in CBC mode. You can generate one of these values using the following command:

veracity agent hashpw sesame



where sesame is the password you wish to hash. Alternatively, you can provide the password in plaintext like this:

Security HAVAL-TEA:sesame

The part after HAVAL-TEA will be interpreted as a plaintext password if it doesnʼt start with HAVAL-.

The protocol used by the client and the agent under the HAVAL-TEA method is quite sophisticated and has the following properties:

Password never transmitted: The password is never transmitted from the client to the agent, even in encrypted form. Only the HAVAL hash of the password is transmitted and only after it has been TEA encrypted.

Config file does not reveal password: Knowledge of the agentʼs configuration file (and hence password hashes) does not reveal the password and does not allow one to connect to the virtual agent.

Two-way authentication: The protocol allows both the client and the agent to authenticate each other. Each side must prove that it knows (or once knew) the password before the other side will proceed with the conversation. However, these proofs are conducted without either side revealing the password to the other.

Session key: Each connection is TEA encrypted with a different session key that is jointly generated randomly by the client and the agent.

All these features mean that virtual agents that use the HAVAL-TEA security method have a very high degree of security. For more information on this protocol, see the separate page in this chapter on the topic and the Veracity Standards web.

Security - SHA-DES

If you specify SHA-DES (followed by a hashed password argument) then the virtual agent requires the client to provide a password (corresponding to the special argument). If the client provides the appropriate authentication, the remainder of the TCP conversation is encrypted with a session-key using DES3-CBC encryption.

Security SHA-DES:SHA-0380BEA27363E56C37F0BFDA438F429080848051

The hexadecimal argument is the big-endian upper-case hexadecimal representation of the SHA-1 digest of the SHA-1 digest of the ASCII representation of the password. You can generate one of these values using the following command:



Security SHA-DES:sesame

The part after SHA-DES will be interpreted as a plaintext password if it doesnʼt start with SHA-.

The protocol used by the client and the agent under the SHA-DES method is quite sophisticated



and has the following properties:

Password never transmitted: The password is never transmitted from the client to the agent, even in encrypted form. Only the SHA-1 hash of the password is transmitted and only after it has been DES3-CBC encrypted.



Session key: Each connection is DES3-CBC encrypted with a different session key that is jointly generated randomly by the client and the agent.

All these features mean that virtual agents that use the SHA-DES security method have a very high degree of security. For more information on this protocol, see the separate page in this chapter on the topic and the Veracity Standards web.

Security - SHA-AES

If you specify SHA-AES (followed by a hashed password argument) then the virtual agent requires the client to provide a password (corresponding to the special argument). If the client provides the appropriate authentication, the remainder of the TCP conversation is encrypted with a session-key using AES-CBC encryption.

Security SHA-AES:SHA-0380BEA27363E56C37F0BFDA438F429080848051

The hexadecimal argument is the big-endian upper-case hexadecimal representation of the SHA-1 digest of the SHA-1 digest of the ASCII representation of the password. You can generate one of these values using the following command:



Security SHA-AES:sesame

The part after SHA-AES will be interpreted as a plaintext password if it doesnʼt start with SHA-.

The protocol used by the client and the agent under the SHA-AES method is quite sophisticated and has the following properties:

Password never transmitted: The password is never transmitted from the client to the agent, even in encrypted form. Only the SHA-1 hash of the password is transmitted and only after it has been AES-CBC encrypted.





Session key: Each connection is AES-CBC encrypted with a different session key that is jointly generated randomly by the client and the agent.

All these features mean that virtual agents that use the SHA-AES security method have a very high degree of security. For more information on this protocol, see the separate page in this chapter on the topic and the Veracity Standards web.

Security - System

If you specify System followed by a colon and a username, then the virtual agent requires the client to provide the password for the specified account (here “dave”) on the agent. The communication is encrypted using DES3-CBC, but with a key that can be derived by watching the entire conversation. For more details on this security method, see the separate page on this method.

Security System:dave

Recommendation: If your virtual agent is to be a public agent that you want anyone to be able to access, set the Security field to the None method. Otherwise, choose a password, hash it using the agent hashpw command and copy and paste the hash into the agent configuration file, specifying the SHA-DES method.

ServerIP

The ServerIP field defines a constraint on the IP addresses to which clients attempting to connect the virtual agent may connect. If a connection arrives with a to IP address that does not satisfy the virtual agentʼs ServerIP constraint, the agent will close the connection.

This field consists of an IP Address Pattern List. ServerIP *ServerIP 1.2.3.4ServerIP 1.2.3.*ServerIP 1.2.3.4/20ServerIP 1.2.3.*/23ServerIP 1.2.3.4,4.5.6.*/20

This constraint is applied when the conversation with the client reaches the point where the client has identified a virtual agent. The conversation can only reach this point if the original connection to the master agent survived the master agentʼs ListenIP and ServerIP constraints.

See also the ClientIP field.



Recommendation: Set this field to its wildcard value (*). This will not impair security, so long as your virtual agents are securely configured. However, if you want to tighten your security, then you should consider using this field. If you do decide to use this field, consider using the corresponding field in the master record instead.

TimeoutMillisecs

The TimeoutMillisecs field specifies the number of milliseconds that a virtual agent should wait (before terminating the connection) if the client suddenly does not respond during the TCP conversation. During the processing of a connection, this value prevails from the point at which a virtual agent is identified to the closing of the connection. Prior to the identification of the virtual agent, the master agentʼs TimeoutMillisecs value prevails.

TimeoutMillisecs 30000

Note: The semantics of this field are not yet implemented.

Recommendation: Set this field to 30000 (30 seconds), unless you can think of a better value.

User

When a Veracity master agent forks off a child process to process an inbound connection, the child process inherits the master agentʼs UID (here referred to as “user”. However, if the virtual agent that is accepting the connection has a User field that has a value other than *, the child process will attempt to change its user to the specified user, and will abort with an error if it canʼt.

This field can be used to improve security by ensuring that the virtual agent can only access files that are readable by the specified user. This field is not available for agents running on Novell Netware.

User *User daveUser root

Note: This field has no effect if the master agentʼs Maxproc field is zero or if the value of this field is *.

Recommendation: If you are setting up a virtual agent that is supposed to be able to read the computerʼs entire file system, then itʼs best to set this field to * so that the child process inherits the master agentʼs group of root. However, if you are setting up a virtual agent for an individual user (e.g. so that the user can check the contents of their webspace) then you should set this field to that userʼs username.

VisibleTree

The VisibleTree field specifies the directory tree that the virtual agent is to make visible to the client. The tree is specified by providing the absolute path of the directory at the root of the tree. The absolute path must contain a trailing path delimiter. As a special case value, you may disable the visible tree restriction entirely by specifying *.

VisibleTree /home/users/VisibleTree *



(On Unix, the value * is equivalent to the value /. However, on non-Unix machines, there is no equivalent syntactically correct absolute path that allows access to all devices. Hence the need for the * setting).

The VisibleTree setting is one of the most security-critical settings because it determines the directory tree that is to be visible to the client. The client can take a snapshot of the entire visible tree or just a subtree of the tree. The client provides an absolute path and the agent checks that it falls within the visible tree before processing the request.

Donʼt forget that you can set up different virtual agents with different visible trees. So, for example, if you want to serve /www/ and /ftp/, you donʼt need to create an agent that serves /. Just create two virtual agents, one for each tree.

Warning: This setting provides a solid boundary on what the remote client can see except when the visible tree contains symbolic links and you have set the AllowFollow setting to Yes. To ensure that the client can only see within the visible tree, be sure to turn off AllowFollow.

Recommendation: Set this field to define the minimum possible tree that you can provide that will still satisfy the needs of authorized remote clients. If you are setting up an agent to monitor the entire machine, this field will have to be /. If you are setting up a virtual agent for each user of your computer, you should set the visible tree path of each user to the userʼs home directory (or perhaps web directory if the users just wish to check their webspace).

9.13 Predefined Configuration Files

Introduction

Veracity agent configuration files provide a lot of expressive power for defining exactly the kind of Veracity agent you want to run. However they are quite detailed, and setting them up can be a time-consuming and nerve-wracking task for the novice Veracity agent administrator. For this reason, a range of predefined configuration files are available that provide commonly required configurations of Veracity agents.

Although these predefined configuration files are referred to as “files” they do not actually exist as files on the disk. Instead, they are built into the Veracity executable. This simplifies installation and effectively eliminates the chance of their being accidentally damaged or deleted. To run a Veracity agent with a predefined configuration file, simply provide the name of the predefined configuration file to the start (or run) command, prefixed by an underscore, like this:

veracity agent start _single_user

The above command instructs Veracity to start an agent using the predefined configuration file called “single_user”. (This is, in fact, the default predefined configuration file so the above command is equivalent to the command veracity agent start).

Some predefined configuration files take one or more command line arguments like this: veracity agent start _system sesame

If you forget an argument, you will be prompted for it.



Saving A Predefined Configuration File

If you find that a predefined configuration file is nearly, but not quite, what you need, you can save a copy of it to a file using the following command:

veracity agent save _users

You can then edit the file to your requirements and then provide its filename to the agent start command.

The remaining sections of this page provides a brief description of the various Veracity agent predefined configuration files.

The users Predefined Configuration File

The users predefined configuration file provides a single virtual agent for each account on the agent computer (except for the root account). The ID and password of each userʼs virtual agent is the same as their system username and password. Each userʼs virtual agent provides access only to the directory tree rooted in the userʼs home directory. As this configuration provides snapshot access to the files of many users, you must be root to start the agent in this configuration. This predefined configuration file is not available for agents running on Novell Netware.

All the virtual agents use the System security method. This is not as secure as either of the SHA-DES or HAVAL-TEA security methods, but has the advantage that virtual agents can be created for all users without having to specify a password for each user explicitly.


The system Predefined Configuration File

The system predefined configuration file provides a single virtual agent whose ID is system and whose password is specified by its argument. You can generate a hash using the agent hashpw command as shown below. The agent provides access to the computerʼs entire file system, making this secure configuration suitable for remote monitoring of the operating system integrity.

veracity agent start _systemPassword:sesameorveracity agent start _system sesameorveracity agent hashpw sesameveracity agent start _systemSHA-EE33294C97C42FFF14EA73AB81E428A6FC7B9A8B

This system agent uses the SHA-DES security method which is extremely secure. As this configuration provides snapshot access to the entire file system, you must be root to start the agent in this configuration.

The users_system Predefined Configuration File

the users_system predefined configuration file provides the union of the virtual agents provided by the users and system configuration files. This configuration provides secure root access while



also providing simple access for all the computerʼs users. This predefined configuration file is not available for agents running on Novell Netware.

veracity agent start _users_systemPassword:sesameorveracity agent start _users_system sesameorveracity agent hashpw sesameveracity agent start _users_systemSHA-EE33294C97C42FFF14EA73AB81E428A6FC7B9A8B

As this configuration provides snapshot access to the files of many users, you must be root to start the agent in this configuration.

The single_user Predefined Configuration File

The single_user predefined configuration file provides a single virtual agent for a single user - the user who starts the agent. The agentʼs ID is the userʼs username and the password is the userʼs system password. The virtual agent provides access to the directory tree rooted in the userʼs home directory. This predefined configuration file is not available for agents running on Novell Netware.

As this configuration provides snapshot access only to the invoking userʼs files, it does not require that user to be root. This configuration uses the SHA-DES security method and so it is extremely secure.

veracity agent start _single_userPassword:sesameorveracity agent start _single_user sesameorveracity agent hashpw sesameveracity agent start _single_userSHA-EE33294C97C42FFF14EA73AB81E428A6FC7B9A8B

Future Predefined Configuration Files

If you create a configuration file that you think should be included as a predefined configuration file in a future release of Veracity, please email Rocksoft.

9.14 The HAVAL-TEA Security MethodThis page provides a description of the HAVAL-TEA method so as to reassure users of its security (and allow them to identify any defects).

The HAVAL-TEA and SHA-DES security methods provide about the same level of security, which is considered to be less than the SHA-AES security method. These protocols are provided for backward compatibility and for customers who do not wish to use the new SHA-AES security method.

The HAVAL-TEA security method is less well known than the others and employs algorithms developed by university researchers in Australia and England.



Cryptographic Algorithms

It is foolish to attempt to devise and trust new cryptographic algorithms for particular products because the strength of an algorithm is usually derived solely from its reputed uncrackability, and this property can only be built up over time. For this reason, the Veracity network protocol only uses well-known and trusted cryptographic algorithms. Only the protocol itself has been devised by Rocksoft. Here are the algorithms the HAVAL-TEA protocol employs:

HAVAL54: This is the five round 128 bit version of the HAVAL cryptographic hash algorithm created by Y. Zheng, J. Pieprzyk and J. Seberry of the University of Wollongong, Australia. We call this variant “HAVAL54” (five rounds, four longwords). This algorithm reads a block of bytes (of any length) and produces a cryptographically strong 128-bit (16 byte) hash of the block. In this page, the HAVAL53 hash of data block X is written as H(X).

TEA2-CBC: This is the 32-round revised version of the TEA (Tiny Encryption Algorithm) symmetric encryption algorithm created by David Wheeler and Roger Needham at the Computer Laboratory of Cambridge University. This algorithm has a 128-bit key and encrypts 64-bit blocks. A small defect was found in the original release of the algorithm and so a revised version was published, which is the version used by Veracity. We call it “TEA2” for this reason. By applying the algorithm in Cipher Block Chaining (CBC) mode, additional security is provided. In this page, the TEA2-CBC encryption of data block X with key K is written as TEA2CBC(X,K).

These algorithms are combined in various ways to create the protocol.

Step By Step: The Protocol Conversation

In the following, A;B means the data block A followed by the data block B.

The protocol is based on the client and agent sharing knowledge based to a secret password P that is specific to the agent. The password consists of a sequence of one or more characters taken from the set of decimal digits and upper and lower case letters. The password is represented as ASCII bytes for processing.

The agentʼs configuration file contains H(H(P)). This is expressed in hexadecimal following the HAVAL-TEA: method keyword. Because the agent only stores H(H(P)), it is not possible to determine the password of a virtual agent from its configuration file entry. Connections proceed as follows and the conversation is aborted at each stage if any check fails.

Client and agent agree on security method: When the client connects to a virtual agent, the virtual agent sends back a message informing the client of its security method. The client then has an opportunity to accept the method and continue the conversation or disconnect.

Client sends random X: If the client is happy with the use of the HAVAL-TEA security method, it generates a 16-byte random number X and sends TEA2CBC(X;H(X),H(H(P))) to the agent.

Agent checks X: The agent uses H(H(P)) to decrypt the message from the client and retrieve X and H(X). It then calculates H(X) from X and compares it to the H(X) sent by the client. If the two match, then this proves that the message was encrypted by H(H(P)) and this proves that the client possesses H(H(P)) which is enough authentication for the agent to proceed to the next step.

Agent sends random Y: Now itʼs the agentʼs turn to generate a random number. The agent



generates a 16-byte random number Y and sends TEA2CBC(Y;H(Y),H(H(P))) to the client. The agent guarantees to never generate Y = X.

Client checks Y: The client uses H(H(P)) to decrypt the message from the agent and retrieve Y and H(Y). If Y is equal to the random number X previously sent, the client assumes that it is talking to a spoof agent that is conducting a replay attack and it terminates the conversation. The client then calculates H(Y) from Y and compares it to the H(Y) sent by the agent. If the two match, then this proves that the message was encrypted by H(H(P)) and this proves that the agent possesses H(H(P)) which is enough authentication for the client to proceed to the next step.

Calculation of session key S: The client and agent then each independently calculate 128-bit session key S as S=H(H(H(P));X;Y). The session key includes the two random numbers which ensure that each session key is likely to be unique, along with the secret information H(H(P)) shared by the client and the agent. The secret information is a good backup in case the client and agentʼs random number generators are predictable for some reason. All this information is hashed to yield the session key so that if someone somehow uses the streamed data to determine the session key, they still cannot determine H(H(P)). The session key is not transmitted by either the client or the agent.

Client sends H(P): To prove that it knows P, the client sends the agent TEA2CBC(H(P),S). The agent decrypts H(P) using the session key. It then calculates H(H(P)) from the H(P) just sent and compares the calculated H(H(P)) with the H(H(P)) provided by the configuration file. If the two match, then this proves that the client knows H(P) (and therefore almost certainly P). This is the final piece of authentication required by the agent and an important piece because by providing H(P), the client proves that it did not merely get a look at H(H(P)) in the configuration file. This step of the protocol prevents those who see H(H(P)) in the configuration file from connecting. To connect, you must know H(P) and hence effectively P.

TEA2-CBC encryption: Once the exchanges described above have taken place, the remainder of the TCP connection is encrypted using TEA2-CBC encryption with 128-bit raw key S.

Protocol Properties

The protocol has the following properties:

Password P is never transmitted: The password P is never transmitted through the network, not even in encrypted form. Only the hash of the password is transmitted and even that is heavily TEA2-CBC encrypted first. Furthermore, the protocol does not transmit H(H(P)) in plain or encrypted form, and it does not transmit H(P) in plaintext.

Config file does not reveal password: The configuration file does not contain the password. It only contains H(H(P)).

Reading config file does not allow access: The configuration file contains H(H(P)) only. But H(P) is required to connect. This means that read-access to the agentʼs configuration file does not allow access to the agent.

Reading config file enables eavesdropping: If an intruder can read the configuration file AND can sniff packets, then the intruder can decrypt any conversation with the agent. If the intruder can decrypt a conversation, he can determine H(P) and thereafter connect to the



agent himself at will. Therefore it is important either to keep the agent configuration file secret or to ensure that no one can read the packets of connections to the agent.

Reading config file enables spoofing: If you can read the configuration file and can divert packets headed for the agent, it might be possible to create a spoof agent. Therefore if packet diversion is a possibility at your site, it is important to keep the configuration file secret.

Agent crypto-silent until it sees H(H(P)): The protocol is designed so that the agent does not provide any crypto-related information to the client until the client sends it H(H(P)).

Two-way authentication with zero leakage: In addition to the agent initially authenticating the client by requiring evidence of knowledge of H(H(P)), the client authenticates the agent by requiring evidence of knowledge of H(H(P)). Neither proof conveys H(H(P)) to the other party, so the failing party does not obtain any information from the failed transaction.

H(P) transmission protected: The client only hands over H(P) after the client has authenticated the agent and has set up a session key with which to encrypt H(P).

Protocol Design Notes

The following design notes may be of interest:

Two levels of hash needed: If the agent stored H(P) in its configuration file instead of H(H(P)), then the client would have to send P to prove that it knows P. This would involve transmitting P (admittedly encrypted) which seemed like a bad idea. The current protocol does not ever transmit P, either encrypted or unencrypted. By eliminating P itself from all storage and communication, the protocol reduces the chance of a human getting their hands on P.

Dual contribution to session key: Both the client and the agent contribute to the randomness of the session key. This is important because if the random component of the session key were generated entirely by one party, the other party might worry that the first party might be compromising the security of the connection by using a random key that wasnʼt sufficiently random.

Playback attacks eliminated: The protocol eliminates playback attacks by either party because both sides generate part of the session key and the communication can only be understood by an entity that possesses H(H(P)).

9.15 The SHA-AES Security MethodThis page provides a description of the SHA-AES method so as to reassure users of its security (and allow them to identify any defects).

The SHA-AES security method is the most secure and the fastest security method provided by Veracity. It employs standard algorithms published and certified by the US Government.


It is foolish to attempt to devise and trust new cryptographic algorithms for particular products because the strength of an algorithm is usually derived solely from its reputed uncrackability,



and this property can only be built up over time. For this reason, the Veracity network protocol only uses well-known and trusted cryptographic algorithms. Only the protocol itself has been devised by Rocksoft. Here are the algorithms the protocol employs:

SHA-1: This is NISTʼs secure hash function. It reads a block of bytes (of any length) and produces a cryptographically strong 160-bit (20 byte) hash of the block. In this page, the SHA-1 of data block X is written as H(X).

AES-CBC: This is NISTʼs AES (Advanced Encryption Standard) algorithm. On January 2nd, 1997, NIST made a call for algorithms to replace the aging DES (Data Encryption Standard) algorithm. Out of fifteen AES candidate algorithms, Rijndael was selected on October 2nd, 2002. This algorithm is considered more secure than the Triple-DES algorithm. Veracity uses the algorithm with a 128 bit key and in Cipher Block Chaining Mode (CBC). Veracityʼs implementation comes from Dr Brian Gladman. See the AES licence section for the licensing details. The algorithm is reputedly uncracked. In this page, the AES-CBC encryption of data block X with key K is written as AESCBC(X,K).





The agentʼs configuration file contains H(H(P)). This is expressed in hexadecimal following the SHA-AES: method keyword. Because the agent only stores H(H(P)), it is not possible to determine the password of a virtual agent from its configuration file entry. Connections proceed as follows and the conversation is aborted at each stage if any check fails.


Client sends random X: If the client is happy with the use of the SHA-AES security method, it generates a 20-byte random number X and sends AESCBC(X;H(X),H(H(P))) to the agent.

Agent checks X: The agent uses H(H(P)) to decrypt the message from the client and retrieve X and H(X). It then calculates H(X) from X and compares it to the H(X) sent by the client. If the two match, then this proves that the message was encrypted by H(H(P)) and this proves that the client possesses H(H(P)) which is enough authentication for the agent to proceed to the next step.

Agent sends random Y: Now itʼs the agentʼs turn to generate a random number. The agent generates a 20-byte random number Y and sends AESCBC(Y;H(Y),H(H(P))) to the client. The agent guarantees to never generate Y=X.

Client checks Y: The client uses H(H(P)) to decrypt the message from the agent and retrieve Y and H(Y). If Y is equal to the random number X previously sent, the client assumes that it is



talking to a spoof agent that is conducting a replay attack and it terminates the conversation. The client then calculates H(Y) from Y and compares it to the H(Y) sent by the agent. If the two match, then this proves that the message was encrypted by H(H(P)) and this proves that the agent possesses H(H(P)) which is enough authentication for the client to proceed to the next step.

Calculation of session key S: The client and agent then each independently calculate 160-bit session key S as S=H(H(H(P));X;Y). The session key includes the two random numbers which ensure that each session key is likely to be unique, along with the secret information H(H(P)) shared by the client and the agent. The secret information is a good backup in case the client and agentʼs random number generators are predictable for some reason. All this information is hashed to yield the session key so that if someone somehow uses the streamed data to determine the session key, they still cannot determine H(H(P)). The session key is not transmitted by either the client or the agent.

Client sends H(P);PADx12: To prove that it knows P, the client sends the agent AESCBC(H(P);PADx12,S). PADx12 refers to 12 bytes of padding, this is necessary since the AES algorithm encrypts in blocks of 16 bytes. The agent decrypts H(P) using the session key. It then calculates H(H(P)) from the H(P) just sent and compares the calculated H(H(P)) with the H(H(P)) provided by the configuration file. If the two match, then this proves that the client knows H(P) (and therefore almost certainly P). This is the final piece of authentication required by the agent and an important piece because by providing H(P), the client proves that it did not merely get a look at H(H(P)) in the configuration file. This step of the protocol prevents those who see H(H(P)) in the configuration file from connecting. To connect, you must know H(P) and hence effectively P.

AES-CBC encryption: Once the exchanges described above have taken place, the remainder of the TCP connection is encrypted using AES-CBC encryption with first 128 bits of the session key S.

Protocol Properties


Password P is never transmitted: The password P is never transmitted through the network, not even in encrypted form. Only the hash of the password is transmitted and even that is heavily AES-CBC encrypted first. Furthermore, the protocol does not transmit H(H(P)) in plain or encrypted form, and it does not transmit H(P) in plaintext.



Reading config file enables eavesdropping: If an intruder can read the configuration file AND can sniff packets, then the intruder can decrypt any conversation with the agent. If the intruder can decrypt a conversation, it can determine H(P) and thereafter connect to the agent himself at will. Therefore it is important either to keep the agent configuration file secret



or to ensure that no one can read the packets of connections to the agent.










9.16 The SHA-DES Security MethodThis page provides a description of the SHA-DES method so as to reassure users of its security (and allow them to identify any defects).

The HAVAL-TEA and SHA-DES security methods provide about the same level of security, which is considered to be less than the SHA-AES security method. These methods are provided for backward compatibility and for customers who do not wish to use the new SHA-AES security method.

The SHA-DES security method employs standard algorithms published and certified by the US Government.




It is foolish to attempt to devise and trust new cryptographic algorithms for particular products because the strength of an algorithm is usually derived solely from its reputed uncrackability, and this property can only be built up over time. For this reason, the Veracity network protocol only uses well-known and trusted cryptographic Algorithms. Only the protocol itself has been devised by Rocksoft. Here are the algorithms the protocol employs:


DES3-CBC: This is NISTʼs DES (Data Encryption Standard) algorithm. The standard DES algorithm was broken in the late 1990s by throwing compute power at its relatively small 56-bit keyspace. However, when implemented in its Triple-DES form (also referred to in this manual as DES3), it has a keyspace of 168 bits - which is out of reach by compute-power cracking using current hardware. By applying Cipher Block Chaining (CBC), additional security is provided. DES3-CBC is the strongest form of DES and is reputedly uncracked. In this page, the DES3-CBC encryption of data block X with key K is written as DES3CBC(X,K).





The agentʼs configuration file contains H(H(P)). This is expressed in hexadecimal following the SHA-DES: method keyword. Because the agent only stores H(H(P)), it is not possible to determine the password of a virtual agent from its configuration file entry. Connections proceed as follows and the conversation is aborted at each stage if any check fails.


Client sends random X: If the client is happy with the use of the SHA-DES security method, it generates a 20-byte random number X and sends DES3CBC(X;H(X),H(H(P));”PAD4”) to the agent. The ASCII bytes “PAD4” are used to pad the 160-bit (20 byte) SHA-1 hash to a 192-bit (24 byte) DES3CBC raw key.

Agent checks X: The agent uses H(H(P));”PAD4” to decrypt the message from the client and retrieve X and H(X). It then calculates H(X) from X and compares it to the H(X) sent by the client. If the two match, then this proves that the message was encrypted by H(H(P));”PAD4” and this proves that the client possesses H(H(P)) which is enough authentication for the agent to proceed to the next step.



Agent sends random Y: Now itʼs the agentʼs turn to generate a random number. The agent generates a 20-byte random number Y and sends DES3CBC(Y;H(Y),H(H(P));”PAD4”) to the client. The agent guarantees to never generate Y= X.

Client checks Y: The client uses H(H(P));”PAD4” to decrypt the message from the agent and retrieve Y and H(Y). If Y is equal to the random number X previously sent, the client assumes that it is talking to a spoof agent that is conducting a replay attack and it terminates the conversation. The client then calculates H(Y) from Y and compares it to the H(Y) sent by the agent. If the two match, then this proves that the message was encrypted by H(H(P));”PAD4” and this proves that the agent possesses H(H(P)) which is enough authentication for the client to proceed to the next step.

Calculation of session key S: The client and agent then each independently calculate 192-bit session key S as S=H(H(H(P));X;Y);”PAD4”,. The session key includes the two random numbers which ensure that each session key is likely to be unique, along with the secret information H(H(P)) shared by the client and the agent. The secret information is a good backup in case the client and agentʼs random number generators are predictable for some reason. All this information is hashed to yield the session key so that if someone somehow uses the streamed data to determine the session key, they still cannot determine H(H(P)). The session key is not transmitted by either the client or the agent.

Client sends H(P): To prove that it knows P, the client sends the agent DES3CBC(H(P);”PAD4”,S). The agent decrypts H(P) using the session key. It then calculates H(H(P)) from the H(P) just sent and compares the calculated H(H(P)) with the H(H(P)) provided by the configuration file. If the two match, then this proves that the client knows H(P) (and therefore almost certainly P). This is the final piece of authentication required by the agent and an important piece because by providing H(P), the client proves that it did not merely get a look at H(H(P)) in the configuration file. This step of the protocol prevents those who see H(H(P)) in the configuration file from connecting. To connect, you must know H(P) and hence effectively P.

DES3-CBC encryption: Once the exchanges described above have taken place, the remainder of the TCP connection is encrypted using DES3-CBC encryption with 192-bit raw key S.

Protocol Properties


Password P is never transmitted: The password P is never transmitted through the network, not even in encrypted form. Only the hash of the password is transmitted and even that is heavily DES3-CBC encrypted first. Furthermore, the protocol does not transmit H(H(P)) in plain or encrypted form, and it does not transmit H(P) in plaintext.



Reading config file enables eavesdropping: If an intruder can read the configuration file AND can sniff packets, then the intruder can decrypt any conversation with the agent. If the



intruder can decrypt a conversation, it can determine H(P) and thereafter connect to the agent himself at will. Therefore it is important either to keep the agent configuration file secret or to ensure that no one can read the packets of connections to the agent.







Standard algorithms used: SHA-1 produces hashes of 20 bytes, but DES3-CBC requires raw keys of 24 bytes. This means that some key padding is requires to make it all work. It was tempting to use in this DES-based method an alternative hash algorithm that would generate 24 byte hashes. However, it was considered more important to combine DES in this method with another US Government standard algorithm (SHA-1) so as to cater for US Government users who require mandated algorithms.




9.17 The System Security MethodThe System security method is not as secure as the SHA-DES security method, but it still provides a good level of security for everyday use. Unlike the SHA-DES method, which does



not transmit the userʼs password at all, the System method requires the userʼs encrypted password to be transmitted down the communications link. This is similar to the level of security provided by an ordinary telnet connection; the System method encrypts everything to prevent the password and snapshot from being casually extracted from the communication, but the encryption keys are deducible from the communication. Hence, to a cryptanalyst, the password is effectively in plaintext.

The sole advantage of using the System security method over the SHA-DES security method is that the System method uses the already-defined login password of a specified user. This means that the password does not need to be specified in the configuration file and will change automatically when the user changes their system password. Because the password does not have to be explicitly specified for each user in the configuration file, the users configuration file can set up a virtual agent for every user on a machine without the Veracity-master having to manually specify and hash a password for each user. This is a huge advantage because it reduces installation to a single command.

As the System security method requires the agent to access system hashed passwords, this method can only be used by Veracity agents running as the superuser or administrator.

The remainder of this page provides a detailed description of the System security method so that you can decide whether you want to keep using it for your users or convert all your virtual agents to the SHA-DES security method.


It is foolish to attempt to devise and trust new cryptographic algorithms for particular products because the strength of an algorithm is usually derived solely from its reputed uncrackability, and this property can only be built up over time. For this reason, Veracity network protocols use only well-known and trusted cryptographic algorithms. Only the enclosing protocols have been devised by Rocksoft. Here are the algorithms the protocols employs:


DES3-CBC: This is NISTʼs DES (Data Encryption Standard) algorithm. The standard DES algorithm was broken in the late 1990s by throwing compute power at its relatively small 56-bit keyspace. However, when implemented in its Triple-DES form (also referred to in this manual as DES3), it has a keyspace of 168 bits - which is out of reach by compute-power cracking using current hardware. By applying Cipher Block Chaining (CBC), additional security is provided. DES3-CBC is the strongest form of DES and is reputedly uncracked. In this page, the DES3-CBC encryption of data block X with key K is written as DES3CBC(X,K).

These algorithms are combined in various ways to create the System protocol.



The protocol is based on the client and agent sharing knowledge based to a secret password P that is specific to the agent. The password is represented as ASCII bytes for processing.



The agentʼs configuration file contains the username whose system password will guard the virtual agent. The operating system stores the passwordʼs hash and the agent refers to this hash during the authentication process.

Client and agent agree on security method: When the client connects to a virtual agent, the virtual agent sends back a message informing the client of its security method. The client then has an opportunity to accept the method and continue the conversation or disconnect. Client sends random X: If the client is happy with the use of the System security method, it generates a 20-byte random number X and sends X in plaintext to the agent.

Agent sends random Y: The agent generates a 20-byte random number Y and sends Y in plaintext to the client.

Calculation of session key S: The client and agent then each independently calculate session key S as S=H(X;Y);”PAD4”. The session key includes the two random numbers X and Y which ensure that each session key is likely to be unique. This information is hashed to yield the session key. The session key is not transmitted by either the client or the agent, but is deducible from the conversation so far.

Client sends DES3(P;Z*,S): To prove that it knows P, the client sends the agent DES3(P;Z*,S) where Z is zero or more 0 padding bytes (required to provide DES with a block that is a multiple of 8 bytes). Note that though the password is encrypted, it is encrypted using a session key that was constructed from information already transmitted during the conversation. Therefore, the password is transmitted in logical plaintext, even though the casual packet sniffer will make no sense of the communication. The agent receives the password and hashes it to compare it with the hashed password in the system database. The agent lets the client know whether it provided a valid password.

DES3-CBC encryption: Once the exchanges described above have taken place, the remainder of the TCP connection is encrypted using DES3-CBC encryption with 192-bit raw key S.

Protocol Properties


Password P is transmitted: The password P is transmitted through the network. It is encrypted to eliminate casual sniffing, but the encryption key is deducible from the conversation so it is effectively transmitted in plaintext. The same applies to the snapshot file returned.

Config file does not reveal password: The configuration file does not contain the password. It only contains the name of the user whose password is to be used.

Reading config file does not allow access: The configuration file does not contain the password or even the hash of the password. This means that read-access to the agentʼs configuration file does not allow access to the agent.

Eavesdropping unhindered: The protocol provides no protection against a sophisticated packet-sniffing intruder. If an intruder can sniff packets, and knows the protocol (which we must assume they do) then the intruder can decrypt the conversation with the agent and derive the password used during the conversation and can read the snapshot file returned. Knowledge of the password provides access to the agent, so anyone who eavesdrops on a



valid conversation with the agent will be able to connect too, unless they are blocked by the agentʼs client IP filtering.

Agent crypto-silent until it sees P: The protocol is designed so that the agent does not provide any crypto-related information to the client until the client has sent it P.

No agent authentication: The protocol does not require the agent to authenticate itself to the client. Only the client authenticates itself to the agent. The client must rely on the internet domain name system delivering it a connection to the correct computer.



Standard algorithms used: SHA-1 produces hashes of 20 bytes, but DES3-CBC requires raw keys of 24 bytes. This means that some key padding is requires to make it all work. It was tempting to use an alternative hash algorithm that would generate 24 byte hashes. However, it was considered more important to use well-known mainstream algorithms that everyone knows and trusts.


No standard hash: It is tempting to attempt to construct a protocol with the same security as the SHA-AES protocol but using the built-in system passwords. While possible in theory, this proposal suffers from the practical problem that different operating systems hash their passwords in different ways. Consequently, to implement a SHA-AES-like method that used system passwords and retains cross-platform interoperability would require every Veracity client to implement the password hash algorithm of every operating system or do something radical like make the shipment of Java bytecodes for hash calculation part of the protocol! In contrast, the current System security method, while less secure, has the advantage of being naturally interoperable.

9.18 Application IdeasThe Veracity agent is an extremely powerful tool because it allows you to certify the configuration of computers set up anywhere on the internet. Here are some application ideas:

Corporate Network Security

Veracity agents can be used to monitor the integrity of thousands of computers within a corporate network. To do this, install Veracity on each computer, setting each agent up with just one default virtual agent with its own unique password. Then write a script on one or more central clients to connect to and check the thousands of computers each day. If anything changes youʼll know about it within 24 hours. Because Veracity agents allow you to specify a policy file, the central clients could perform quick checks of critical files on each computer each hour if required.



The Veracity monitoring solution will even work with extranets as it uses just a single TCP stream per connection and uses a standard TCP port. This means that it is easy to configure firewalls to allow the Veracity traffic through.

Web Monitoring

Most webs are constructed offline and uploaded by FTP to webservers operated by internet service providers (ISPs). These webservers are online 24 hours a day and are excellent targets for intruder attack. ISPs can use integrity tools such as Veracity to monitor their system files (which are not supposed to change). However, monitoring unauthorized changes in user webs is more problematic because many of the webs on the webserver may be being altered by the users.

By installing a Veracity agent on its webserver and creating a virtual agent for each user, an ISP can empower its users to check their own webs using a Veracity client. This is not only a valuable security service, but also allows users easily to determine if the online version of their web is the same as their offline version (sometimes one forgets to upload a new page).

Firewall Monitoring

To monitor the configuration of a firewall, set up a Veracity agent on the firewall. You will then be able to take a snapshot of the firewall and compare it to the snapshot of the official configuration of the firewall. To automate the checking, set up a cron job on a second computer to take and check regular snapshots of the firewall.

Remote Software Diagnosis

Software vendors who install systems at customer sites can install Veracity on their customersʼ sites too. Then, if a customer phones to complain that something isnʼt working, the vendor can use a Veracity client to connect and take a snapshot of the customerʼs computer and compare it to a previously stored snapshot of the correct configuration. This will instantly identify any files that have become corrupt or which the customer has changed.

Official Records Monitoring

Organizations, such as governments, that must preserve documents for a period of time (e.g. under the 30-years rule) and then disclose them, could place the documents on a server and provide Veracity access only. Historians, or other entities with an interest in eventually obtaining the documents could monitor the server remotely to ensure that the documents have not been damaged or deleted. If they were, the historians could contact the organization immediately to enquire as to what happened.

Warm Backup Continuous Verification

If you maintain a hot or warm backup of a computer, you can use Veracity to continuously ensure that the file system of the backup computer is up to date. Just install a Veracity agent on your main computer and then set up a cron job on the backup computer that regularly takes a snapshot of the main computerʼs file system and the compares it to its own file system.



9.19 Attack by ReplacementThe most damaging attack that could be launched against a Veracity agent is for an intruder to gain root access to the agentʼs computer and then replace the Veracity agent with a spoof agent that either returns only the expected snapshot files, or traverses an officially correct copy of the file system, while the real file system then becomes available for subtle modification (e.g. installation of a “root kit”).

This would be a difficult attack to organize, involving as it would, a myriad of detail such as preserving all the inodes of files copies to a separate disk. However, itʼs hard to argue that this kind of attack is not possible, as, by definition, all of the information required to satisfy the remote client that is monitoring the agent, must be present somewhere in the agent itself. It would seem to be impossible to hide the information perfectly without special hardware support.

It is, however, possible to hide the information quite well. Essentially the information that is required to create a spoof agent is the existing file system and the information in the Veracity configuration file (and in particular the password hashes). One simple way to make it difficult for an intruder to retrieve this information is simply to delete the Veracity agent configuration file after the Veracity agent has been started. This would prevent the intruder from stopping the agent, modifying the configuration file and the executable and restarting it. Without the information in the configuration file (which includes the hashed passwords) the agent can not convince its remote clients that all is well.

To overcome this lack of information, an intruder would have to dump the virtual address space of the Veracity master agent and analyze it to find the configuration file data structure. While possible, this sort of attack would be conducted only the most persistent and well-informed intruder. Intruders who do notice a Veracity agent are more likely to either delete the process or leave.

Rocksoft is working on the development of far more sophisticated ways to detect agent spoofing. However, for the time being, deletion of the configuration file will make any attempt at agent spoofing extremely difficult, if not near-impossible in practice.

9.20 Summary Of Agent Security BarriersAs the Veracity agentʼs security features are somewhat involved, this page provides a list of the barriers that an intruder would have to surmount to gain unauthorized access. You can choose to erect some or all of these barriers by tightening the settings in your agentʼs configuration file.

Note: Veracityʼs default configurations, as defined by its predefined agent configuration files, are reasonably secure and you should not be concerned about the security implications of running a Veracity agent on your computer, nor should you feel that reading this page is a necessary security measure. However, if you are administering a very high security system, or want to understand Veracityʼs security features better, then you should read this page and attend to its issues thoughtfully.

Barriers To Connecting To A Master Agent

Before an intruder can attempt to gain access to a Veracity virtual agent, he must first strike up a conversation with the enclosing Veracity (master) agent. To do this, he must satisfy the following constraints:



Existence: To can gain access to a Veracity agent, an intruder must know (or guess) that the host computer is running a Veracity agent. If an intruder is not aware of what a Veracity agent is, or does not think of the idea that your computer might be running one, then an attack is unlikely! For this reason, it may be a wise precaution, in high-security installations, not to publicize the existence of a Veracity agent. This said, publicizing the existence of a Veracity agent certainly does not constitute a security risk in its own right.

ListenIP (master): Once an intruder suspects that a particular computer may be running a Veracity agent, he needs to form a TCP connection to the agent. To do this, he has to know the IP addresses on which the agent is listening. By default, Veracity agents listen on all addresses assigned to their host. However, you can change this to a single address using the ListenIP field in the master agent record. If you do this, and your machine has many IP addresses, the intruder will have to search them for the agent. However, the usual case is that a computer has a single IP address and this is not a barrier at all.

Port (master): In addition to finding the IP address on which the agent is listening, the intruder must also determine the TCP port on which the Veracity agent is listening. Usually, this will be trivial because Veracity agents should be run on the official Veracity TCP port of 1062 so as to avoid port clashes. However, if you wish, you can configure your agent to use a different port, using the Port field to listen on a different port. If you do this, the intruder will have to search the ports on your computer for the Veracity agent. Using a non-standard port for a Veracity agent is not encouraged, but may be beneficial in very-high security applications where every opportunity to add extra security should be taken.

ServerIP (master): If the intruder satisfies the above constraints, he will have formed a TCP connection with the master agent. The first thing the master agent does after accepting a connection is to apply an additional constraint to the IP address on which the agent accepted the connection. The additional constraint is defined by the ServerIP setting (in the master agentʼs settings record). If this constraint is not met, the connection is terminated.

ClientIP (master): The second thing the master agent does after accepting a connection is to check the IP address from which the client is connecting against the ClientIP field in the master agentʼs configuration record. If the clientʼs IP address does not satisfy the constraint, the connection is terminated. By default, Veracity agents do not restrict the set of acceptable client IP addresses. However, it is a very good idea to do so if you do not want connections from any but a small number of networks or IP addresses. A tight ClientIP setting forces the intruder to either gain access to one of the acceptable machines, or engage in IP from-address spoofing and return packet diversion. From-address spoofing is easy, but return packet diversion is difficult unless the intruder can intercept packets leaving the agentʼs network.

With the exception of the ClientIP field, which is exceptionally strong, the measures above do not provide a high degree of security and unless the intruder has been blocked by not having an acceptable originating (client) IP address, itʼs reasonable to assume that he can make a connection to a Veracity master agent. However, connection to a Veracity agent provides no attacking advantage (except perhaps in a denial of service attack). To access any information, the intruder, once connected to the master agent, must connect to a virtual agent. The next section addresses this.



Barriers To Connecting To A Virtual Agent

Here are the barriers to connecting to a Veracity virtual agent, having already connected to a Veracity master agent.

Virtual Agent ID: To connect to a virtual agent, the intruder must know, and provide, the virtual agentʼs ID. This is a similar problem to username guessing, and in fact is username guessing on Veracity agents running a wildcard virtual agent. In most cases, it will not be too hard for an intruder to guess the name of a virtual agent, particularly if the agent is running the system or default virtual agents. It is probably best not to obfuscate the virtual agent names for the purpose of security, but if you want to enhance security, choosing an obscure name for your virtual agents could certainly help because it would be like having two passwords.

ServerIP (virtual): Once the intruder has provided the master agent with a virtual agent ID, the intruder is immediately subjected to further IP address checks based on the fields in the virtual agentʼs record. First, a check is performed on the IP address on the agent to which the client connected. This is a similar kind of test as was conducted when connecting to the master agent, but applies on a per-virtual-agent basis.

ClientIP (virtual): A check is performed on the originating IP address. This is a similar kind of test as was conducted when connecting to the master agent, but applies on a per-virtual-agent basis.

Virtual Agent Password (virtual): Assuming that the intruder has guessed the ID of a virtual agent, he next has to provide the virtual agentʼs password. It is possible for a virtual agent to have no password, but none of Veracityʼs predefined agent configuration files define virtual agents with no password, so youʼd have to go out of your way to set one up. The agent password is the last major security barrier to gaining access to a virtual agent, and is one of the strongest barriers. So long as you have chosen your password with care, there should be little chance of an intruder guessing it. If your virtual agent is running the System security method, then the intruder could obtain the password by listening in on a successful legitimate connection to the virtual agent. If your virtual agent is running the SHA-DES or HAVAL-TEA security method, the intruder would need to be able to read the agentʼs configuration file AND listen in. By far the two strongest security barriers are ClientIP filtering and virtual agent passwords.

Barriers To Accessing Particular Files

Let us suppose that the intruder has managed to satisfy all the constraints of the previous sections and has connected to a virtual agent. What barriers remain to prevent the intruder from gaining access to the agentʼs files?

Well, perhaps the most important thing to remember is that, unless the AllowWrite setting is set to “Yes”, the intruder cannot use the connection to modify any files on the agentʼs host, as a Veracity agent writes only to its logfile and PID file and the names of these files are specified in the master agent record and are not subject to alteration by the client. Furthermore, while Veracity is quite complicated, it uses almost no fixed-length buffers, performing all its operations in the heap with frequent integrity assertions. Thus, the chance of a Veracity agent being manipulated into writing arbitrary files as a result of the traditional buffer overrun bug is very low. One may reasonably assume that a Veracity agent will never allow an intruder write access



to any file under any circumstances. This leaves only the danger of unauthorized disclosure of information, which this section addresses.

Here is a list of the barriers an intruder will face to accessing files in the Veracity agentʼs file system.

AllowWrite (virtual): Perhaps the most important constraint is the AllowWrite setting in the virtual agentʼs configuration record. This field determines whether the connecting client is allowed to modify the contents of files accessible by the Veracity virtual agent. The security implications of the client being able to modify files are obvious. However, client is only able to modify files through the RESTORE command. By default, Veracity has this setting turned off. If you are concerned about security, you should keep this attribute turned off (“No”) unless you are planning to perform restores.

AllowData (virtual): The second most important constraint is the AllowData setting in the virtual agentʼs configuration record. This field determines whether the connecting client is allowed to obtain the contents of files. By default, all Veracity virtual agents do not allow access to the contents of files, which means that the worst that an intruder can do even if he does gain access is obtain the names, file attributes, lengths, and cryptographic hashes of files. Access to this information, might, in itself, constitute a breach of security, but it is likely to be a far less damaging breach than disclosure of actual file contents. Therefore, if you are concerned about security, you should keep this attribute turned off (“No”) unless you absolutely must access file data remotely yourself.

VisibleTree (virtual): The next most important constraint is the VisibleTree setting in the virtual agentʼs configuration file. This setting defines a directory tree about which the client may obtain information. The client may not access information about any other files on the computer system. This is a very important constraint because it places a bound on what an intruder can see.

AllowFollow (virtual): If the visible tree contains symbolic links to other trees in the file system, it may be possible for an intruder to “escape” the visible tree defined in the VisibleTree setting. The AllowFollow setting allows you prevent such escapes by instructing the virtual agent never to follow symbolic links even if explicitly requested to do so by the client. By default, Veracity has this setting turned off (“No”) and you should leave it off unless you absolutely must perform remote access traversals that follow symbolic links.

User and Group (master and virtual): While the security barriers above should be more than sufficient to prevent unauthorized access, there are still four more features that provide a safety net in the event that someone does manage to form an unauthorized connection to a virtual agent. The master agent and each virtual agent provide User and Group settings that allow you to specify the user and group of the agentʼs process. If you specify these, then if something goes wrong and the constraints above are breached in some form, the agentʼs process will only be able to read files that are readable by the specified user and group. The user and group fields are not available for agents running on Novell Netware.

Summary Of Security Precautions



The most important things you can do to secure your Veracity agent and its virtual agents are:

• Leave AllowWrite turned off.

• Tighten the ClientIP field in the master agent.

• Ensure that every virtual agent has an obscure password.

• Use the SHA-AES (or SHA-DES or HAVAL-TEA) security method, if possible.

• Choose the tightest possible VisibleTree.

• Leave AllowData turned off.

• Leave AllowFollow turned off. Those who are very concerned with security may also:

• Keep the agentʼs existence a secret.

• Configure the agent to listen to an obscure IP address.

• Configure the agent to listen to a non-standard port.

• Use only obscure virtual agent IDs.

• Set the User and Group fields as a safety net.

• Configure a daemon to watch the Veracity agent log for breakins.



10 Policy Files 10.1 Introduction

Policy Files are ordinary text files, created by the user, that formally describe what Veracity should and shouldnʼt pay attention to during its recording and checking of directory trees.

Policy Files are used by the SNAPSHOT command to determine the information to be written to the output snapshot file, and by the CHECK command to determine what should be checked. To specify that a policy file be used by the SNAPSHOT command or CHECK command, simply supply the policy file to the command using the +C argument. For example:

veracity snapshot +Cmypolicyfile.vpf

Here is an example of a policy file. =====(BeginClipListV1)=====

“#*”-*-> +create +delete

“/users#*”-f-> +B.md5

“/users/temp#*” -f-> -all

=====(EndClipList)=====

Veracity also provides a range of predefined policy files.

The remaining parts of this section define policy files in detail.

10.2 Policy File SyntaxPolicy Files must satisfy the following constraints:

• Lines must consist of printable characters only (ASCII [32,126]).

• Lines can be no longer than 76 characters long (not including EOLs).

• Lines must not contain trailing blanks.

• The last line of the file must be terminated.

Policy Files must conform to the following syntax: policy file = purew begin_marker w { rule w } end_marker purewbegin_marker = “=====(BeginClipListV1)=====”end_marker = “=====(EndClipList)=====”rule = pattern w arrow w actionpattern = “””” { any_char_except” } “”””arrow= “-d->” | “-f->”| “-s->” | “-v->”| “-*->” | “-df->” | “-dfv->” | “-fv->”action = attribute_switch { w attribute_switch }



attribute_switch = sign attributesign = ( “-” | “+” )attribute = fileat_att | special_attspecial_att= “binary” | “text”| “auto” | “create” | “delete” | “error” | “no_text_lf_warning” | “no_text_cr_warning” | “no_text_sub_warning” | “no_text_ltl_warning” | “no_text_llu_warning” | “no_text_warnings” | “follow”| “follow_dir” | “follow_file” | “follow_vol” | “no_nonbinary_warning” | “no_nontext_warning”| “no_kind_warnings” | “no_cycle_error” | “no_cycle_match_error” | “follow_cycle” | “len_allow_increase”fileat_att = { attname_ch }attname_ch = upper | lower | digit | <.$_>upper= <ABCDEFGHIJKLMNOPQRSTUVWXYZ>lower= <abcdefghijklmnopqrstuvwxyz>digit= <0123456789>w = { whitething }purew= { whitech }whitething = whitech | commentcomment = “[“ { any_ch_except_EOL_or_] } “]”whitech = “ “ | EOL

Here is an example of a complete policy file: =====(BeginClipListV1)=====“#*” -*-> +create +delete“#*” -s-> +SymLink“#*” -f-> +B.md5“/&0veracty.v%f~” -f-> -all=====(EndClipList)=====

Policy Files consist of a list of pattern/action rules called rules. Patterns define a set of matching relative pathnames. For example, the pattern “/user/john#*.exe” selects all files in the subtree rooted in the directory “/user/john/ ” (relative path) that end in “.exe”. The list of rules is applied separately to each file. Each file starts off with an empty attribute set. Actions modify the set of attributes for each file whose relative pathname matches the pattern. For example, the action +B.md5 adds B.md5 to the set of attributes associated with the files matching the associated pattern. A later section contains more information about the way in which rules are applied. In the meantime, we examine patterns and actions in detail. But first, comments.

10.3 Policy File CommentsPolicy Files can contain comments where the syntax allows it. Comments are delimited by pairs of square brackets and cannot cross line boundaries. These syntax rules for comments ensure that comments will always be clearly visible and wonʼt gobble up important parts of the policy file if a “]” is accidentally omitted.



For similar reasons, the syntax for policy files requires beginning and ending markers at the start and end of policy files. This is to ensure that a policy file will not be accepted by Veracity if it has been accidentally truncated or pretruncated. Despite all this, the syntax is not otherwise line based, and rules are allowed to span many lines.

Here is an example of a policy file that contains comments. =====(BeginClipListV1)=====

[Predefined Policy File DEFAULT][------------------------------][Securely monitors the whole tree.]

“#*” -*-> +create +delete“#*” -s-> +SymLink“#*” -f-> +B.md5

[Ignore Veracity files.]“/&0veracty.v%f~” -f-> -all

=====(EndClipList)=====

10.4 Policy File PatternsThe purpose of a pattern is to define a set of matching relative pathnames specified relative to the target directory tree. For example, if the target directory tree were usrdsk::d1:[users.ross], a pattern might match some of the relative pathnames of files in usrdsk::d1:[users.ross...]*.*;*. However, being relative, the pattern would specify only restrictions within the tree usrdsk::d1:[users.ross...]*.*;*; it would not refer to usrdsk::d1:[users.ross] directly at all. In short, patterns are matched against the relative path, not the absolute path (see pathname nomenclature).

While most operating systems provide a hierarchical file system, the different operating systems differ in their exact pathname syntax:

MS-DOS dev:\dir1\dir2\dir3\name.extMacintosh dev:dir1:dir2:dir3:nameUnix/dir1/dir2/dir3/nameOpenVMSnode::dev:[dir1.dir2.dir3]name.ext;verNetwarevolume:\dir1\dir2\dir3\name.ext

Luckily, patterns apply only to directory subtrees, and so the entire left side may be omitted from all patterns. If we choose the top of our target directory subtree to be dir1, we then have:

MS-DOS \dir2\dir3\name.extMacintosh :dir2:dir3:nameUnix /dir2/dir3/nameOpenVMS [dir2.dir3]name.ext;verNetware \dir2\dir3\name.ext

This leaves just two components: a relative path, and a file name.

In order to make policy files portable across different machines, Veracity normalizes the relative pathnames before presenting them to the pattern matching system. It does this by transforming the pathname into an abstract form. This involves replacing the directory name delimiters in



the path with an abstract delimiter designated here by m . All pathnames commence with an m which corresponds to the top of the target directory tree. Thus each of the four pathname forms given above can be reduced to the following single abstract form:

m “dir2” m “dir3” m “name.ext”

It is this abstract form to which patterns are applied. For the purposes of pattern matching, m can be considered to be a previously unheard of character that has been added to the ASCII character set specially for the purposes of pattern matching (e.g. it has an ASCII code of 1000). We denote this above form the “abstract string”.

The patterns themselves consist of ordinary strings containing special sequences (wildcards) that are designated to match particular constructs in the abstract string. Because, in practice, wildcards occur very often in patterns, ordinary characters have been used to represent the wildcards, with those characters being available as ordinary characters only through an escape mechanism. The wildcards available are:

/ - Matches m.# - Matches one or more characters beginning and ending with m.* - Matches zero or more characters not containing m.% - Matches a single character that is not m.^ - Matches one or more decimal digits.~ - Matches either the empty string OR a semicolon followed by one or more decimal digits.& - Toggles case sensitivity.\/ - Matches the byte ‘/’.\# - Matches the byte ‘#’.\* - Matches the byte ‘*’.\% - Matches the byte ‘%’.\^ - Matches the byte ‘^’.\~ - Matches the byte ‘~’.\& - Matches the byte ‘&’.\\ - Matches the byte ‘\’.\x[??] - x can be in upperor lower case. - Each ? must be an upperor lower case hex digit. - Matches the single bytedescribed by the two hexdigits.\x[????] - x can be in upper or lower case. - Each ? must be an upper orlower case hex digit. - Matches the single bytespecified by the four hex digits.Guaranteed not to match if the top twodigits are not zero. This feature wasadded to support Unicode in the future.

The matching of each pattern starts in case-sensitive mode. Each occurrence of & causes the



case-sensitivity of the pattern matcher to toggle.

Once a filename has been normalized, it behaves just like an ordinary string, and pattern matching takes place entirely at the character level with no reference to any other semantics whatsoever (even the directory or non-directory status of files). This makes patterns simple to deal with, even when they are used on a number of different operating systems. The table below gives some examples of patterns.

PatternWhat It Matches----------------------“#*” - The entire tree.“#*.exe”- All files ending in “.exe”.“/sloth*” - All files that start with “sloth” in the target tree’s top directory.“&#*.v%f” - All Veracity files in the tree.“#junk#*” - All files whose path contains a directory called “junk”.“#*\/*” - Any file whose name contains “/”.“#*\\*” - Any file whose name contains “\”.“#*\#*” - Any file whose name contains “#”.“#*\**” - Any file whose name contains “*”.“#*\%*” - Any file whose name contains “%”.“#*.*;^”- OpenVMS filenames.“&#*.dat~” - All .dat files under all OSs.

10.5 Policy File SpacingVeracity ignores all spaces and newlines that appear within a pattern. This allows you to align various fields of the pattern with those of nearby patterns. For example:

=====(BeginClipListV1)=====“# *” -*-> +create +delete“# *” -f-> +B.md5“/sloth# *” -f-> -all=====(EndClipList)=====

If you want a space character or newline to appear as part of the pattern, use: \X[20] for space.\X[0A] for newline.

You can also add spaces between other components of policy files. Rules can even be split over many lines. However, comments cannot cross lines.

10.6 Policy File ArrowsThe arrow, which forms the syntactic glue between the pattern and the action, specifies the type or types of file to which the rule applies. Here is the arrow syntax:

arrow = “-d->” | “-f->”| “-s->” | “-v->”| “-*->” | “-df->” | “-dfv->” | “-fv->”

-f->Regular files.-d->Directory files.-s->Symbolic links.



-v->Volatile files.-*->All files.-df-> Directory and regular files.-dfv-> Directory, regular, and volatile files.-fv-> Regular and volatile files.

Veracity categorizes each directory entry into one of four mutually exclusive types:

Directory (D): Directory files are the files that form the directory tree structure.

Regular file (F): Regular files are ordinary files that contain zero or more bytes of data. Veracity “regular files” correspond exactly with Unix “regular files”.

Symbolic Link (S): A symbolic link is a special kind of directory entry that provides a path that points to a different file that the operating system pretends is really the file in the directory. Veracity recognizes symbolic links only under Unix.

Volatile file (V): Veracity categorizes all other files as “volatile” files. Volatile files are called “volatile” because they do not have a stable content. Example volatile files under Unix are character device files, block device files, and FIFO files.

The arrow of each rule specifies the type of the files to which the rule refers. The arrow -*-> encompasses all four kinds. The combination arrows (e.g. -df->) cover more than one type of file.

Some attributes cannot be applied to some file types. For example the SymLink attribute is applicable only to symbolic links, and the B.* attributes cannot be applied to volatile files. You can expect Veracity to issue some policy file errors if you attempt to apply an attribute to the wrong type of file.

10.7 Policy File ActionsWhile patterns define sets of matching relative pathnames, actions modify the set of attributes associated with files matching such patterns. An action specifies the addition or removal of zero or more attributes from a set of attributes.

Each attribute can be turned on (“+”) or turned off (“-”) (included or not included in a set of attributes). Turning an attribute on instructs Veracity to ring the alarm bells if the property the attribute represents changes for a matching file. Thus, +B.md5 means that Veracity will report if the MD5 digest of the binary stream of a file changes.

The set of attributes is discussed in detail in the chapter on attributes.

10.8 Policy File SemanticsA policy file consists of a list of pattern/action rules that collectively partition the set of possible filenames into one or more partitions and assign a set of attributes to each partition. The assignment is performed sequentially and cumulatively, with later rules being capable of undoing the actions of earlier rules. When Veracity compares two directories, it applies the entire set of rules to the pathname of each file in the two directories.

Definition: The purpose of a policy file is to define a mapping from a normalized relative pathname to a set of attributes.

To determine the attributes that apply to a particular pathname, start at the top of the



list with an empty set of attributes and work down the list matching the target pathname against each pattern. Whenever there is a match, the rule “fires” and the action associated with the pattern is “executed” by adding or subtracting the specified attributes to or from the current set of attributes. It is perfectly acceptable (not an error) for an attribute to be subtracted from a set when the attribute is not in the set. Similarly, it is acceptable for an attribute to be added to a set that already contains that attribute. In each case, that component of the action has no effect.

Firings do not affect the processing of rules, which are processed sequentially until all rules have been inspected. The set of attributes that remains when all the rules have been processed for a particular target pathname is the set that apply for that pathname.

Example

A system manager doesnʼt much care what happens in his file system. Most of the time there are a hundred users logged in and so it would be impractical (and probably unethical) to investigate all changes in the file system. However, there have been reports that an intruder is around and so the manager wants to set some traps. The manager decides to monitor all files in bin except in the bin/tmp directory. In addition, the manager decides to monitor any changes to the jones account which has been set up with password “jones” as a bait for intruders. The only difficulty is that the backup system modifies .backup files in all user directories (including the jones directory) and the manager does not wish to be alerted whenever a backup occurs. Hereʼs a policy file that provides the solution:

=====(BeginClipListV1)=====“/bin#*”-*-> +create +delete“/bin#*”-f-> +B.md5“/bin/tmp#*” -*-> -all“/users/jones#*” -*-> +create +delete“/users/jones#*” -f-> +B.md5“/users/jones#.backup” -f-> -all=====(EndClipList)=====

10.9 Policy File ClippingAs we have seen, Veracity uses the policy file to determine which attributes to calculate and write to the snapshot file. However, the policy file can play an even more powerful role, by actually preventing Veracity from traversing particular subtrees.

Whenever Veracity is about to traverse a particular subtree of the target directory tree, it first checks to see whether it needs to traverse it. If it doesnʼt, it skips that entire subtree and writes a stub to represent the directory subtree in the snapshot file. If particular subtrees of your target tree are not of interest to you, this can save a lot of time. It can also reduce the size of the snapshot file.

The criteria which Veracity uses to decide whether a particular subtree is worth exploring is: could a file of any imaginable name in any imaginable descendent directory, when fed through the rules in the policy file, possibly end up with a non-empty attribute set? If the answer is “yes”, then Veracity traverses the tree. Itʼs important to note that this analysis is performed without any reference to any existing files; it just has to be possible that a file satisfying the conditions for a rule to fire could exist within the subtree.



The simplest way to clip (ignore) a subtree is to turn off all attributes of all files in the subtree. The following policy file causes the tmp subtree to be clipped.

=====(BeginClipListV1)=====“#*” -*-> +create +delete“#*” -f-> +B.md5“/tmp#*” -*-> -all=====(EndClipList)=====

The following policy file does NOT cause the users subtree to be clipped, because there could be a subdirectory in the users subtree called dave and, if that were the case, all files within that directory would have the B.md5 attribute turned on.

=====(BeginClipListV1)=====“#*” -*-> +create +delete“#*” -f-> +B.md5“/users#*” -f-> -all“#dave#*” -f-> +B.md5=====(EndClipList)=====

The following policy file does not cause the users subtree to be clipped either, as the -all applies only to the top of the subtree. Veracity must assume that the root might contain subdirectories, and so it has to go down and have a look.

=====(BeginClipListV1)=====“#*” -*-> +create +delete“#*” -f-> +B.md5“/users/*” -f-> -all=====(EndClipList)=====

Veracity uses some intelligence when deciding whether to clip a directory subtree. However, it does not implement a unification algorithm. So if you want to be sure that Veracity wonʼt go wandering down a subtree and representing it in the snapshot file, the best way is simply to specify -all for all files in the entire subtree and then make sure that none of the subsequent rules turn any attributes on for any potential files in the subtree.

Rule of thumb: Use ““...\#*” -*-> -all” to clip subtrees.

10.10 Predefined Policy FilesAlthough policy files are very powerful, they can be bothersome to construct and maintain, and so Veracity provides a selection of predefined policy files to cover a variety of particularly common requirements. A list of these predefined policy files appears in the table below. These predefined policy files do not exist as independent files, but instead are embedded into the Veracity executable. This means that you donʼt have to worry about installing them, or maintaining them, or an intruder somehow finding them and modifying them.

Name Description. binary For a tree of binary files. default The default policy file. Monitors the whole tree. diff Full binary or text differences of trees. diff_ntw Same as diff, but with no text warnings.



fast Uses high-speed Fletcher 16-bit insecure checksum. notarize Monitors using a selection of crypto digests. null The empty cliplist. Monitors nothing. security Monitors content, security-critical file attributes. simple Same as default without Mac resource fork checking. skeleton Records only directory tree and file names. No sigs. source Monitors common source files only (.c, .h, etc). structure Records only directory tree and file names. No sigs. text For a tree of text files. text_ntw Same as text, but with no text warnings. top Same as default, but records only the top directory. topskel Same as skeleton, but only does the top directory. touch Monitors structure and file attrs, but not content. transfer For transfering files to other OSs. transfer_ntw Same as transfer, but with no text warnings. vault Same as default, but allows file creations. web For transfering webs between different OSs. web_ntw Same as web, but with no text warnings.

Predefined policy files.

Users who do not wish to construct their own policy file can select one of Veracityʼs predefined policy files by specifying +C_predefname . This table provides a complete list of the available predefined policy files. For example, to specify the skeleton policy file, you would give +C_skeleton as an argument to the snapshot command. The snapshot command always lists the selected policy file in the report file, so if you want to see a policy file, simply apply the check command to an empty tree and then examine the report file. The set of predefined policy files has been designed to cover the most common cases in the everyday use of Veracity.

These predefined policy files are nothing magical; they are ordinary policy files that could be extracted into an external policy file and specified explicitly. Veracity always lists the policy file it uses in the report file, so to see a particular policy file, snapshot an empty (to save time) tree, specifying the policy file of interest, and then examine the report file. The following notes describe the predefined policy files.

binary: The binary policy file is the same as the default policy file except that, in addition, it instructs Veracity to check that each file is a binary file and issue a warning if it isnʼt. This policy file is useful when you have a tree of binary files, and you want to check that no text files have snuck in. In particular, it is useful when you want to verify the transfer of a tree of binary files from one computer system to another using BINARY transfer mode, and you want to check that no text files have crept in to the set of files to be transfered. Note: Veracityʼs binary/text classification algorithm is heuristic, and so there is a chance of it misclassifying the binary/text type of some files.

default: The default policy file takes a snapshot of the entire target tree using the B.md5 signature. It will detect creations, deletions, and modifications of all directories and files in the target directory tree.



diff: The diff policy file instructs Veracity to record all of the contents of all of the files in the entire target tree and to provide a complete binary or text differences (as appropriate) for each file that has changed. Because the snapshot file must store the contents of every file, the snapshot file will be of the same order in size as the directory tree that it represents, so use this policy file with caution! This policy file is useful in high-security applications (where you want to know what the changes made were as well as what files have changed) and for comparing two trees of program source files.

diff_ntw: The diff_ntw policy file is the same as the diff policy file except that it suppresses text warnings when processing the text files in the tree. Use this policy file when you want to use the diff policy file, but donʼt care if the files are exactly portable to other operating systems.

fast: The fast predefined policy file is the same as the default policy file except that instead of using the secure 128-bit MD5 digest algorithm, it uses the high-speed insecure 16-bit Fletcher checksum. Use this policy file when you want Veracity to run at its fastest. However, be warned that Fletcher checksums can be easily forged, and that the raw probability of an individual Fletcher checksum failing is approximately 1 in 65536 which, while still low, is not negligible.

notarize: The notarize policy file records the entire tree using a selection of B.* digest attributes. This policy file is useful in notarizing applications where you want to record, for each file, a signature that is likely to be relied upon even in many years time when some (but hopefully not all) of the digests in the selection have been cracked or broken by brute force.

security: The security policy file is designed to monitor a tree securely, including the file attributes of the files in the tree that pertain to security. As security is a tricky area, you will probably have to create your own customized policy file, but this predefined policy file can act as a good starting point.

simple: The simple policy file is the same as the default predefined policy file except that it doesnʼt include any platform-specific attributes (such as U.md5 on the Macintosh).

skeleton: The skeleton policy file records the entire tree, but only records the directory structure and filenames; it does not calculate or store any of the file signatures. Thus it will report directories and files that have been created or deleted, but will not report modifications. This policy file is useful for ensuring that files havenʼt gone missing. However, it should not be used if you wish to protect the contents of files.

text: The text policy file is the same as the default policy file except that it records the signatures of the text projection (T.*) of each file rather than the binary projection. In addition, it checks each file to see if it is a text file, and if it isnʼt issues a warning. This policy file is useful when you are going to transfer a directory or tree of text files from one computer system to another in TEXT mode, and you want to check the transfer and also check for binary files within the set of files transfered (because they would be corrupted). Note: Veracityʼs binary/text classification algorithm is heuristic, and so there is a chance of it misclassifying the binary/text type of some files.

text_ntw: The text_ntw policy file is the same as the text policy file except that it suppresses text warnings. This policy file is useful when you have a tree of text files, and you want to be sure that no binary files have snuck in, and you donʼt care if the text files contain non-portable



constructs. This policy file is also useful for checking the transferal of trees of text files to other computers, where you are confident that any impurities (e.g. last line unterminated) in the text files you are transfering are unlikely to cause your transfer program to modify the text file during transit (e.g. to add an EOL to the last line). Veracity will still detect any modifications that do occur, but it wonʼt warn you in advance of text file impurities that could cause such problems.

top: The top policy file is the same as the default policy file except that it only records information about the directory at the top of the target directory tree. This policy file is useful when you want to check a single directory.

topskel: The topskel policy file is the same as the skeleton policy file except that it pays attention only to the top directory in the target directory tree.

touch: The touch policy file monitors tree structure and key file attributes, but not file content, so as to rapidly identify files that may have been changed (touched). This policy file provides a simple fast check for rapid rotation security scanning, but should be backed up by less frequent cryptographic file-content scans to ensure that content changes are reliably detected.

transfer: The transfer policy file is much the same as the default policy file except that it uses A.md5 instead of B.md5. This makes it suitable for verifying binary and text file transfers between machines running different operating systems.

transfer_ntw: The transfer_ntw policy file is the same as the transfer policy file except that it suppresses text warnings. This makes it suitable for verifying binary and text file transfers between machines running different operating systems, where you are confident that any impurities (e.g. last line unterminated) in the text files you are transfering are unlikely to cause your transfer program to modify the text file during transit (e.g. to add an EOL to the last line). Veracity will still detect any modifications that do occur, but it wonʼt warn you in advance of text file impurities that could cause such problems.

vault: The vault policy file is the same as the default policy file except that it does not report the creation of directories and files. This allows it to be used to create a “vault” for files on a hard disk. In such a vault, you can add files to the target directory tree, but once they are there, they must stay there. So long as regular snapshot/signoff pairs are performed on the tree, the files will remain safe and the tree will behave like a big bank vault for your files.

web: The web policy file is designed for checking World Wide Web directory trees that must be frequently moved from the web developerʼs computer to the webserver. The policy file caters for binary and text files using the flexible A.md5 signature and uses its own knowledge of the type (binary/text) of various common web files to increase the certainty that type decisions will be made correctly. This is an excellent policy file for uploading webs.

web_ntw: The web_ntw policy file is the same as the web policy file except that it suppresses text warnings. Many web creation tools generate HTML text files that contain constructs (such as very long lines) that can cause problems when those files are transfered to another computer system in text mode (e.g. FTP text mode). If you use the web policy file, Veracity will generate warnings for such constructs. This can become annoying if the constructs are NOT causing the files to be modified during transit, and in such cases, you should use web_ntw instead. Veracity will still detect any modifications that do occur during transit; it just



wonʼt generate warnings in advance.

The exact definition of some of these predefined policy files may vary from operating system to operating system. For example, the system predefined policy file has to preclude different files under different operating systems. Under the Macintosh most of the policy files include attributes that monitor parts of the resource fork.

If you want to see a predefined policy file, invoke Veracity on a tiny tree, specifying the policy file and then look in the report file for a listing of the predefined policy file. For example to see the web predefined policy file on a Unix machine, you could give the following commands:

mkdir testtmpcd testtmpveracity snapshot +c_webmore 0veracty.vrf

Rocksoft is always on the lookout for new policy file ideas. If you have an idea for a new predefined policy file, please let us know and will consider including it in the next release.

Warning: If you choose to use a predefined policy file, you should examine the report file the first time you use the policy file so as to ensure that the policy file contains productions appropriate to your application.



11 AttributesAlthough Veracityʼs primary purpose is to monitor the content of files, it is also capable of monitoring other aspects of files. In general, Veracity monitors attributes of files, with the content of a file being just one kind of attribute. This chapter categorizes and defines the attributes that Veracity is capable of monitoring.

11.1 IntroductionWhen Veracity records information about a file in a snapshot file, it treats the information as a collection of attributes of the file. The term “file attributes” is often used to refer to information about a file such as the fileʼs modification date or owner. However, in the context of Veracity, the term “attribute” is used to refer to any aspect of a file that Veracity can record. Attributes include information about the content of the file (e.g. the MD5 digest of the binary stream) as well as information about the file (e.g. modification date).

The diagram below provides a categorization of Veracityʼs file attributes. attributes real non-content Name Type Various OS-specific file attributes content non-signature Kind signature concrete B.sig R.sig S.sig T.sig U.sig virtual A.sig pseudo create delete binary text auto error all null ... and more

Note: (“sig” => sha1,md5,crc32,len etc)A categorization of Veracityʼs attributes.The generality of Veracityʼs notion of attribute allows it to support a wide range of attributes. This figure provides a tree-structured categorization of these attributes. Each of these categories is discussed in the main text.

The tree is complex but looks worse than it is. The following notes describe each category.



Real vs pseudo attributes: Veracityʼs attributes are split into two groups: real and pseudo . Real attributes describe actual attributes of files, for example the length of a file. Pseudo attributes are really just directives that modify the behavior of Veracity towards the file.

Content vs non-content: The category of real attributes is subdivided into content and non-content attributes. Content attributes are functions of the content of a file. For example, the length of a file is a content attribute. Non-content attributes are functions of administrative information about the file. For example, the modification date of a file is a non-content attribute.

Signature vs non-signature: The category of content attributes is subdivided into signature and non-signature attributes. A signature attribute is an attribute that is a signature of some kind calculated from some projection of the content of the file for the purpose of monitoring changes in the content of the file. A non-signature attribute is also a function of the content of the file but for a different purpose. Veracity has only one such attribute and that is the Kind attribute which records whether the file is a binary file or a text file. The Kind attribute is classified as a content attribute because sometimes Veracity calculates it by inspecting the contents of the file.

Concrete vs Virtual: Signature attributes are divided into the subcategories of concrete and virtual. This distinction is really to cope with the A.* attributes which are really either B.* or T.* depending on the value of the type field. The A.* attributes are called “virtual attributes” because they never appear directly in the snapshot file. Instead, they are stored in the snapshot file as either B.* or T.*.

11.2 How Attributes Are StoredWhen you specify in the policy file that Veracity should watch over particular attributes of a particular file, Veracity stores those attributes in the fileʼs record in the snapshot file. There is no mystery here. With the exception of the A.* attributes (which are stored as B.* or T.*), each attribute is simply stored in text form as a field in the fileʼs record. The snapshot file is a text file, so you can always hop into a text editor and have a look at the information that Veracity has stored. Thus, if you included in your policy file the following production:

“#*.exe” -f-> +binary +B.len +B.md5 +B.sha1

you might find a file record in the snapshot file that looks like this: ((T=F)(K=B)(N=myprog.exe) (B.len=’zAAACWw) (B.md5=’zEDHe7mtwdgWGaZj25Uuvmw) (B.sha1=’zYl+UJOY4K+viT67Cq9eAzmzrDmA))

Itʼs worth becoming familiar with how this is organized.

The T field is the Type field and records whether the file is a Directory, a File, a Symbolic link, or a Volatile file. This field is present in every file record.

The K field is the Kind field which is present only when the policy file has instructed (through specification of binary, text, or auto) that the kind field by recorded. In the example above, the kind was specified in the policy file as binary.

The N field is the Name field and records the name of the file exactly as presented by the file system. This field is present in every file record.



The remaining fields record various signatures of the binary stream of the file. Each signature field starts with “‘z”. This is a mode-setting sequence that indicates that the remainder of the field is expressed in base-64. In base-64, the block of bytes is divided into 6-bit groups, each of which is coded as a single ASCII character. The base-64 character set consists of upper and lower case letters and digits and the + and / characters. Base 64 is used because it is more compact than the more straightforward hexadecimal. However, if you want such attributes to be stored in the snapshot file in hexadecimal, you can do this by adding +H to the snapshot command.

Veracity manipulates the values of all attributes as blocks of zero or more bytes, so there are no restrictions on the length or content of an attributeʼs value.

11.3 The Name AttributeThe name attribute is compulsory. It appears automatically in every file record in the snapshot file and cannot be specified in the policy file in the same way that (say) create and delete can. The name field contains the exact name of the file under the host operating system. For example, if the pathname were “bignode::d1:[aardvark.bear]sloth.txt;42” then the name attribute would be “sloth.txt;42”. There are no length or content restrictions on the name attribute; it is defined to consist of zero or more 8-bit bytes (containing any of the 256 possible bytes [0,255]). The name field is represented in file records in the snapshot file using the name N (to save space):

(N=myprog.exe)

11.4 The Type AttributeThe type attribute records whether the file is a Directory, a File, a Symbolic link, or a Volatile file. This field is present in every file record and is represented in the snapshot file by the field T.

(T=F)

Files of type symlink and volatile are recognized as appearing only on Unix operating systems.

11.5 The Kind AttributeThe Kind field records whether a file is binary or text. It is present in a file record only when the policy file has instructed (through specification of binary, text, or auto) that the kind field be recorded. By default, Veracity does not record the kind field.

(K=B)

To instruct Veracity to record the kind field for a file, you must arrange for the rules of the policy file to associate exactly one of the following three pseudo attributes with the file. Veracity issues an error if more than one of these attributes is active for any file.

Binary: By specifying this attribute, you are asserting that the file in question is a binary file and that the Kind field for the file be set to B. Note: If Veracity thinks that the file is not a binary file, it will issue a warning.

Text: By specifying this attribute, you are asserting that the file in question is a text file and that the Kind field for the file be set to T. Note: If Veracity thinks that the file is not a text file, it



will issue a warning.

Auto: By specifying this attribute, you are specifying that Veracity should examine the file and use any information available to it to make up its own mind of the Kind of the file. If Veracity identifies the file as binary or text, it will set the Kind to B or T. However, if it cannot determine the Kind of the file (e.g. because the file is unreadable), it generates an error message and does not record the Kind attribute in the snapshot file.

If one of these attributes is specified for a particular file, then the check command will compare the kinds of the old and new versions of the file and will issue an error message if they are different. If none of the above attributes are active for the file, the check command does not check the Kind of the file, even if it is present in the snapshot file.

While the kind field can be used as a useful sanity check of a fileʼs kind, its main purpose is as directive information for the A.* attributes. If a file has an A.* attribute turned on, then it must also have exactly one of the above attributes turned on as well. If it doesnʼt, Veracity will issue an error message.

Warning: Veracityʼs algorithm for determining the kind (binary or text) of a file is heuristic, and it is possible that it will misclassify some files (binary instead of text, or text instead of binary). It follows that you should not rely on the correctness of Veracityʼs automatic binary/text classification algorithm in critical applications.

11.6 The Pseudo AttributesVeracityʼs pseudo attributes take the syntactic form of attributes, but are actually directives that instruct Veracity to behave in particular ways when processing the files that have these attributes turned on. Here is a description of all of Veracityʼs pseudo attributes:

all: The all attribute is an abbreviation for all attributes. It can only be used in the negative form (-all) and is very useful for clipping subtrees.

create and delete: These two attributes instruct Veracity to detect the creation or deletion of the specified file.

binary, text, and auto: These attributes determine the value of the Kind field and are discussed in detail in the section on the kind attribute.

error: The error attribute has no effect other than to cause an error to be issued for each file for which it is turned on. The error attribute is useful for ensuring that all cases have been considered in a policy file. For example, consider the case of a user who wishes to use different signatures for different kinds of files. The following policy file shows how the error attribute can be used to ensure that Veracity will generate an error message if it encounters any files not having one of the extensions .exe, .txt, .dat, or .db.=====(BeginClipListV1)=====“#*” -f-> +create +delete +error“#*.exe” -f-> +B.md5 +B.sha1 -error“#*.txt” -f-> +T.sha1 +T.len -error“#*.dat” -f-> +B.sha1-error“#*.db” -f-> +B.sha1-error=====(EndClipList)=====



follow: The follow attribute is available on all platforms, but is applicable only to symlinks (symlinks are a Unix-specific construct). By default, Veracity (1.2 and higher) does not follow symlinks. However, if you specify the follow pseudo attribute for a symlink, Veracity will “follow” the symlink through a chain of one or more symlinks to its target file and behave as if the target file is actually in the directory, with the same name as the symlink. The target file does not replace the symlink in the directory, even though it has the same name; both the symlink and the target file will appear to be present. This is possible because Veracity keeps files of different type (Directory, SymLink, Regular, Volatile) in different namespaces. The follow attribute is useful when you want to check a directory tree in a manner that treats the symlinks it contains as if they were real links. A hazard with using follow is that Veracity might encounter a directory cycle. If this happens, Veracity will detect the cycle, generate an error, clip the tree, and keep going. Note: In the context of a policy file rule list, this pseudo attribute is independent from the other follow_* attributes (follow_cycle, follow_dir etc.). It is not a “macro” shorthand for +follow_dir +follow_.... Thus, for example, the actions +follow_dir +follow -follow will leave the follow attribute turned on. Hereʼs an example of the follow attribute in a policy file:=====(BeginClipListV1)=====“#*” -*-> +create +delete“#*” -s-> +follow“#*” -f-> +B.md5=====(EndClipList)=====

follow_cycle: The follow_cycle is applicable only to directory files. By default, if Veracity encounters a cyclic directory, it does not traverse the subtree rooted in the cyclic directory, but instead writes a “directory stub” to the snapshot file (if the snapshot command) and issues an error (if no_cycle_error is not turned on). However, if you turn on follow_cycle, Veracity will “follow” the cyclic directory by attempting to traverse its subtree. Warning: If you turn on this attribute for all the directories in a subtree (e.g. “#*”, Veracity could go into an infinite loop (or one that terminates with a “pathname too long” error or “path too deep” error) if it encounters a directory cycle. This attribute should only be needed when you wish to compare a cyclic directory structure with an “unrolled” directory structure, where you have taken adequate precautions in the policy file to ensure that the cycle will not be followed down forever. This attribute is entirely independent from the other follow_* pseudo attributes. In particular, the follow attribute does not turn on cycle following. See also the no_cycle_error and no_cycle_match_error pseudo attributes.

follow_dir: The follow_dir attribute is the same as the follow attribute except that it only turns on the following of symlinks to directory files.

follow_file: The follow_file attribute is the same as the follow attribute except that it only turns on the following of symlinks to regular files. This attribute is useful when you want Veracity to “see” the whole tree including the symlinked files, but you donʼt want Veracity to chase symlinked directories. If you use this attribute, you may wish to also specify follow_vol so as to see all non-directory files.

follow_vol: The follow_vol attribute is the same as the follow attribute except that it only turns on the following of symlinks to volatile (e.g. devices, pipes) files.

len_allow_increase: This attribute is applicable to regular and directory files. If this attribute is turned on for a file, then the check command will not report increases in *.len attributes



(e.g. B.len) for that file. This attribute is useful for ensuring that logfiles do not decrease in length.

no_cycle_error: The no_cycle_error is applicable only to directory files. It instructs Veracity not to generate an error if it encounters a cyclic directory (i.e. one that has the same as one of its ancestor directory in the tree traversal). By default, Veracity does generate an error. Veracity records cycle information in its snapshot files, so it is possible to encounter a cycle when traversing the directory tree recorded in a snapshot file! See also the no_cycle_match_error and follow_cycle pseudo attributes.

no_cycle_match_error: The no_cycle_match_error is applicable only to directory files. By default, when Veracityʼs CHECK command compares two trees, it compares the cycleness (links to nearest identical ancestor or zero if uncyclic) of each pair of corresponding directories, and issues an error if the two cyclenesses differ. However, if you turn on this attribute for a directory, such an error will not be generated. See also the no_cycle_error and follow_cycle pseudo attributes.

no_kind_warnings: The no_kind_warnings attribute is applicable to regular files only. It instructs Veracity to suppress all kind warnings (nonbinary,nontext). Note: In the context of a policy file rule list, this pseudo attribute is independent from the no_nontext_warning and no_nonbinary_warning attributes. It is not a “macro” shorthand for +no_nontext_warning +no_nonbinary_warning. Thus, for example, the actions +no_nonbinary_warning +no_kind_warnings -no_kind_warnings will leave the no_nonbinary_warning attribute turned on.

no_nonbinary_warning: The no_nonbinary_warning attribute is applicable to regular files only. It instructs Veracity not to issue a warning if the binary pseudo attribute is set, but Veracity thinks the file is a text file. This attribute is useful when you are using an A.* attribute and are specifying the kinds of some or all files by extension, and donʼt want Veracity to issue warnings if it disagrees with your categorization. In the following policy file, Veracity is instructed to make up its own mind (+auto) about the kind of files, except for .gif files which the user is asserting are definitely binary. The +no_nonbinary_warning ensures that Veracity wonʼt issue a warning if it thinks that a .gif file is really a text file.=====(BeginClipListV1)=====“#*” -*-> +create +delete“#*” -f-> +A.md5 +auto“#*.gif” -f-> +binary -auto +no_nonbinary_warning=====(EndClipList)=====

no_nontext_warning: The no_nontext_warning attribute is applicable to regular files only. It instructs Veracity not to issue a warning if the text pseudo attribute is set, but Veracity thinks the file is a binary file. This attribute is useful when you are using an A.* attribute and are specifying the kinds of some or all files by extension, and donʼt want Veracity to issue warnings if it disagrees with your categorization. In the following policy file, Veracity is instructed to make up its own mind (+auto) about the kind of files, except for .txt files which the user is asserting are definitely text. The +no_nontext_warning ensures that Veracity wonʼt issue a warning if it thinks that a .txt file is really a binary file.=====(BeginClipListV1)=====“#*” -*-> +create +delete



“#*” -f-> +auto +A.md5“#*.txt” -f-> -auto +text +no_nontext_warning=====(EndClipList)=====

no_text_lf_warning: The no_text_lf_warning attribute is applicable to regular files only. It instructs Veracity not to issue a warning if it discovers a line feed (LF (decimal 10)) character within a text line while calculating a T.* attribute. By default, Veracity issues such warnings (except on OpenVMS).

no_text_cr_warning: The no_text_cr_warning attribute is applicable to regular files only. It instructs Veracity not to issue a warning if it discovers a carriage return (CR (decimal 13)) character within a text line while calculating a T.* attribute. By default, Veracity issues such warnings.

no_text_sub_warning: The no_text_sub_warning attribute is applicable to regular files only. It instructs Veracity not to issue a warning if it discovers an MS-DOS end-of-file character (SUB (decimal 26)) character within a text line while calculating a T.* attribute. By default, Veracity issues such warnings.

no_text_ltl_warning: The no_text_ltl_warning attribute is applicable to regular files only. It instructs Veracity not to issue a warning if it discovers a line longer than 254 characters long (not including the EOL character(s)) within a text file while calculating a T.* attribute. By default, Veracity issues such warnings.

no_text_llu_warning: The no_text_llu_warning attribute is applicable to regular files only. It instructs Veracity not to issue a warning if it discovers that the last line of a text file is unterminated (no EOL character(s)) while calculating a T.* attribute. By default, Veracity issues such warnings.

no_text_warnings: The no_text_warnings attribute is applicable to regular files only. It instructs Veracity to suppress ALL text warnings (lf,cr,sub,ltl,llu) when calculating T.* attributes. Note: In the context of a policy file rule list, this pseudo attribute is independent from the other no_text_*_warning attributes. It is not a “macro” shorthand for +no_text_lf_warning +no_.... Thus, for example, the actions +no_text_cr_warning +no_text_warnings -no_text_warnings will leave the no_text_cr_warning attribute turned on.

null: The null attribute has absolutely no effect. It has been included to allow placeholder rules. Veracity will issue a syntax error if a rule has an empty action, and so if you want an empty action, you have to say so explicitly by specifying -null or +null.

A Note On Create And Delete

Veracity does not, by default, issue an error message if a file is created or deleted within the target directory tree. If you specify an empty policy file, you will be warned of nothing, except possibly an unreadable top directory. If you specify a policy file specifying just (say) B.md5 you will be warned if the file changes, but you will not be warned if the file is created or deleted. To detect creations or deletions, you must specify the create or delete attributes explicitly. As a



rule of thumb, if you donʼt ask in the policy file for something to be monitored, it wonʼt be.

A Note On Symbolic Links

Symbolic links are entries in Unix directory files that point to other files. These entries carry no type information. Thus, in order for Veracity to determine the type of file to which a symlink refers, it has to access that file. This means that if you, for example, specify +follow_dir to instruct Veracity to “follow” only softlinks that point to directory files, Veracity has to follow ALL softlinks so as to see which ones point to directory files! If Veracity canʼt follow one of these symlinks (e.g. because the target file is protected), it MUST issue an error, because the target file might be an (e.g.) directory which the user had intended Veracity to follow (when specifying +follow_dir). But the file might not be a directory after all, in which case the error message may appear unwarranted or spurious to the user. Please be aware that if you specify a +follow_* pseudo attribute, that Veracity will be forced to attempt to follow ALL symbolic links (unless they are clipped out) and will generate an error for each symbolic link it canʼt follow. Once Veracity has followed all the symbolic links, it will only add to the directory (it builds in memory) the ones that point to files of the specified type(s).

11.7 StreamsA stream is a particular view of a file. If we consider a file to be a block of bytes, then a stream is another block of bytes which is a projection of the original block. Veracity provides the following streams:

Binary (B): This is the bytes in the file as they are stored by the host operating system. No tricks. No mysteries. No transformations. Just the bytes.

Text (T): The text stream is intended to be applied to text files only. In this projection, all characters are viewed as their 16-bit Unicode codes (sequenced in big-endian byte order) and operating-system-specific end-of-line bytes (e.g. CR/LF) are viewed as “standard” Unicode LS (2028H) characters, and any EOF bytes are ignored. Veracity also issues warnings if the text file breaks rules that ensure its portability. For example, Veracity will issue a warning if one or more lines are too long.

Auto (A): The auto stream is a virtual stream that is either the B or T stream, and exists only if the Kind attribute has a value of B or T. Because the A stream is virtual, you wonʼt find it in the snapshot file (e.g. A.md5). Instead you will find B.md5 if the file kind is B or T.md5 if the file kind is T.

Resource (R): The resource stream is available only on the Macintosh, and can be ignored on all other machines. On the Macintosh, all files have two “forks”: a data fork and a resource fork. The data fork is a block of bytes that corresponds to the notion of “file” on other operating systems. The resource fork is a block of bytes that contains “resources” such as fonts and GUI designs. In the Macintosh implementation of Veracity, the B stream is the block of bytes that is the contents of the data fork, and the R stream is the block of bytes that is the contents of the resource fork. The R stream is not available on other operating systems. If you take a snapshot on a Macintosh and then attempt to use it under a different operating system, Veracity will issue a single error message indicating that the R stream is



not available.

System (S): The Macintosh system bytes stream is available only on the Macintosh, and can be ignored on all other machines. This stream consists of bytes 16 to 255 (assuming that the first byte in the fork is numbered 0) of the resource fork (or as many of those bytes that exist). These are the bytes in the resource for that the Macintosh operating system seems to modify at will (e.g. even when a file is merely copied). See the section below on Macintosh streams for a more detailed explanation.

User (U): The Macintosh user bytes stream is available only on the Macintosh, and can be ignored on all other machines. This stream consists of bytes 0 to 15 followed by bytes 256 onwards (assuming that the first byte in the fork is numbered 0) of the resource fork (or as many of those bytes that exist). These are the bytes in the resource fork that the Macintosh operating system does not modify at will. See the section below on Macintosh streams for a more detailed explanation.

Each of these streams consists of a block of bytes from which the fileʼs content attributes are calculated.

Macintosh Streams

In order to enable Veracity to effectively monitor Macintosh files, no less than three Macintosh-specific streams had to be defined.

On the Macintosh, all files have two “forks”: a data fork and a resource fork. The data fork is a block of bytes that corresponds to the notion of “file” on other operating systems. The resource fork is a block of bytes that contains “resources” such as fonts and GUI designs. Accordingly, Veracity uses its B stream to represent the block of bytes that is the contents of the data fork, and a new R stream for the block of bytes that is the contents of the resource fork.

This, perhaps should have been all that was required. However, after some research and experimentation, it was discovered that the Macintosh Operating System (MacOS) actually treats part of the resource fork as its own, and is capable of (and quite likely to) modify it. It seems that it wonʼt modify resource forks in files just sitting on a disk, but it will change some bytes if you copy a file in the Finder or in any other way involve the file in some transformation involving the MacOS.

This meant that early versions of Veracity would remain quiet about files stored safely on disk, but as soon as the files were backed up and restored, Veracity would indicate that all R.* attributes of all the restored files were not the same as the originals. This wasnʼt a bug in Veracity: the resource forks really were different! But they were different in a way that didnʼt matter to the user.

Hereʼs a brief map of the resource fork: Off Name of SectionLength--- ----------------------- --------- 0 Resource header 16 bytes 16 Reserved for system use 240 bytes256 Resource data ? bytes ? Resource map ? bytes



Note: The resource header field containsthe length and offset for the last twofields.

The Apple documentation isnʼt very clear on this, but it appears that the MacOS sees fit to modify any of the 240 bytes following the first 16 bytes of each resource fork. The bytes before and after this 240-byte zone are not modified by the MacOS unless there is a change in a resource.

To solve the problem, two additional streams were added: S and U. This means that there are now three streams that can be used to monitor Macintosh resource forks:

R.* - The entire resource fork.S.* - The 240 “system” bytes.U.* - The bytes before and afterthe 240 system bytes.

Thus:

If you want to monitor files sitting on your disk to ensure that they are not changed at all, and you are sure that youʼll never need to verify your files after a copy or restore operation, use an R.* attribute.

If youʼre going to be manipulating your files and then verify them and you donʼt care if the system bytes change, use a U.* attribute.

If you want to detect any changes to files on disk, but you also want to be able to check them after a restore, use both the S.* and U.* attributes.

If youʼre confused, just use a U.* attribute. Thatʼs what all the Macintosh predefined policy files do.

Text Stream Warnings

Whenever you specify a text (T.*) attribute for a file, Veracity performs some portability checks on the file and issues warnings if any of the following features are found. To suppress ALL these kinds of warning, turn on the no_text_warnings pseudo attribute.

LF in Line: Text files whose lines contain line feeds will cause trouble when an attempt is made to transfer them to Unix as, under Unix, each line feed will be interpreted as an EOL. Veracity issues a warning for each LF character that appears within a line. To suppress these warnings, turn on the no_text_lf_warning pseudo-attribute in the policy file. This warning is automatically suppressed on operating systems that represent EOL using LF. Also, due to an OpenVMS-specific problem, this warning is not implemented in the OpenVMS version of Veracity.

CR in Line: Text files whose lines contain carriage returns will cause trouble when an attempt is made to transfer them to the Macintosh as, under the Macintosh operating system, each carriage return will be interpreted as an EOL. Veracity issues a warning for each CR character that appears within a line. To suppress these warnings, turn on the no_text_cr_warning pseudo-attribute in the policy file. This warning is automatically suppressed on



operating systems that represent EOL using CR.

MS-DOS EOF in Line: Text files whose lines contain the MS-DOS EOF character (ASCII 26 decimal) will cause trouble when an attempt is made to transfer them to MS-DOS. The file will be interpreted as ending at the first EOF character! Veracity issues a warning for each MS-DOS EOF character it encounters (except in an MS-DOS file!). To suppress these warnings, turn on the no_text_sub_warning pseudo-attribute in the policy file (SUB is the ASCII mnemonic for character 26). This warning is automatically suppressed on MS-DOS and Win32.

Line too long: Some file transfer programs and operating systems cannot cope with text files longer than 255 characters (because they store the length of the line in a byte). Veracity issues a warning for each line it finds that is longer than 254 characters (not including the EOL bytes). The value of 254 was chosen, as some systems might not be capable of 255 if they store an EOL character in the line buffer. To suppress these warnings, turn on the no_text_ltl_warning pseudo-attribute in the policy file.

Last line unterminated: Files whose last line is unterminated (donʼt have a proper EOL) cause problems when they are transfered to operating systems such as OpenVMS whose text file representation supports only complete lines. If the last line of a text file is unterminated, Veracity issues a warning. To suppress these warnings, turn on the no_text_llu_warning pseudo-attribute in the policy file.

These warnings ensure that you will be forewarned if any text file that you are about to transfer contains features that are likely to cause it to become corrupted during its transmission. However, these warnings are not critical (thatʼs why theyʼre warnings, not errors). If any file actually is corrupted, for whatever reason, Veracity will detect it in the usual way. Veracity issues the warnings solely to avoid the confusion that can result when a text file is signaled as being corrupted when the corruption is something subtle (such as termination of the last line) that is not easily visible to the user. Itʼs better to be warned precisely of a potential problem by the snapshot command, than try to figure out the difference between a source and target text file after the check command has indicated a signature mismatch.

To avoid bombarding you with warnings in the case of text files that contain many such constructs, Veracity only issues one warning of each kind for each file it processes (for which a T.* attribute is being calculated).

11.8 Content AttributesVeracityʼs content attributes record information about the contents of a file. Content attributes are divided into signature and non-signature content attributes. The only non-signature content attribute is the Kind attribute which was described in a previous section.

Each signature content attribute name consists of a stream name being an upper case letter, followed by a dot, followed by a name (usually in lower case) that describes the transformation that is applied to the stream to arrive at the attribute. For example, the attribute that is the MD5 digest of the binary stream of a file is called B.md5. Other examples of content attributes are: B.data, R.crc32, T.md5. As always, attribute names are case sensitive.

Veracityʼs signature attributes provide checksums and digests of various streams of a file. The set of signature attributes is the cross product of the set of streams and the set of signature



algorithms (checksums and digests). The next two sections describe the signature algorithms available.

11.9 ChecksumsThis section lists all the checksum algorithms provided by Veracity. Of the checksum algorithms presented here, the best is either the 32-bit CRC-32 (crc32) or the Adler32 (adler) algorithm, and these should be the first choice. However, if this is too slow, the high speed 16-bit Fletcher fle algorithm can be substituted instead. If you are not using a digest as well, itʼs also probably a good idea to throw in the Length (len) algorithm as a sanity check, although this is entirely optional.

Warning: If you are using Veracity in a security application (i.e. you wish to detect modifications by viruses and intruders), you should not use checksum algorithms exclusively; use at least one digest algorithm as well. Checksum algorithms can be inverted, enabling an intruder to modify a file in a manner that results in it having the same checksum.

crc16 — This is the popular CRC-16 algorithm. The exact specification of the algorithm is given by the following parameters to the “The Rocksoft Model CRC Algorithm” which is described in [Williams93].

Name: “CRC-16”Poly: 8005Init: 0000RefIn : TrueRefOut : TrueXorOut : 0000Check : BB3D

Its width is two bytes (16 bits).

crc32 — This is the popular CRC-32 algorithm. The exact specification of the algorithm is given by the following parameters to the “The Rocksoft Model CRC Algorithm” which is described in [Williams93].

Name: “CRC-32”Poly: 04C11DB7Init: FFFFFFFFRefIn : TrueRefOut : TrueXorOut : FFFFFFFFCheck : CBF43926

This is the state of the art in 32-bit checksum algorithms. Apparently it is used in PKZIP, AUTODIN II, Ethernet and FDDI. Its width is four bytes (32 bits).

adler — This is the checksum algorithm used by the popular compression algorithm GZip. It is faster than CRC-32 but also slightly weaker. Its width is four bytes (32 bits).

fle — This is the popular 16-bit Fletcher checksum algorithm which is nearly as good as CRC-16 at detecting errors, but is faster. This is the state of the art in 16-bit checksum algorithms. Its width is two bytes (16 bits).

ipc — This is the 16-bit checksum algorithm used to check packets in the IP (Internet Protocol),



which is used to implement much of the Internet. The checksum is basically the 16-bit ones-complement sum of the message as structured into 16-bit words. It is described in detail in [Braden88]. While this algorithm is extremely fast (faster even than the Fletcher algorithm), it does not provide as strong error detection. For example, the checksum remains invariant if pairs of zero bytes are inserted anywhere in the stream, or if any two bytes in the message that are separated by an odd number of bytes in the message are swapped. Unless you really need speed, use the Fletcher (fle) algorithm instead. The width of IPC is two bytes (16 bits).

len — This trivial algorithm simply returns the number of bytes fed to it. While very useful as a sanity check, it should never be the only checksum algorithm used. This attribute is of variable width and consists of the big-endian representation of the length with all leading zero bytes deleted except for one zero in the case of a length of zero. (Note: If the len_allow_increase pseudo attribute is turned on for a file, then Veracity wonʼt report on increases in the length (*.len) signatures of the file, only decreases. This is useful for monitoring the length of logfiles which change often, but should not decrease in length).

chkrw1 — This is the obscure 16-bit algorithm called CHKRW1 (CHecKsum Ross Williams number 1). This is a fairly weak 16-bit checksum algorithm created in a hurry by Ross Williams in 1989 to checksum data compression test data. Checksums of data compression data using this algorithm appear in the book [Williams91] and so the algorithm was included so as to allow Veracity to be used by data compression researchers to confirm these checksums. While this algorithm is not an extremely poor checksum algorithm, it is certainly inferior to most of the other algorithms. Its width is two bytes (16 bits).

sum1 — This algorithm simply returns the sum of the message bytes mod 2**8. This algorithm has been included for completeness and is not recommended. Its width is one byte (8 bits).

sum2 — This algorithm simply returns the sum of the message bytes mod 2**16. This algorithm has been included for completeness and is not recommended. Its width is two bytes (16 bits).

sum4 — This algorithm simply returns the sum of the message bytes mod 2**32. This algorithm has been included for completeness and is not recommended. Itʼs width is four bytes (32 bits).

11.10 DigestsThis section describes all the digests algorithms provided by Veracity. Digests are different from checksums because checksums can usually be inverted, whereas digests provide a measure of cryptographic protection against this, making them suitable for security applications.

Of the digest algorithms presented here, MD5 has been chosen as Veracityʼs default signature, as it provides a strong combination of high speed and high security.

Haval — The HAVAL (HAsh of VAriable Length) algorithm is a message digest algorithm created by Y. Zheng, J. Pieprzyk and J. Seberry of the University of Wollongong, Australia. The algorithm is described in the paper Y. Zheng, J. Pieprzyk and J. Seberry: ``HAVAL — a one-way hashing algorithm with variable length of outputʼʼ, Advances in Cryptology — AUSCRYPTʼ92, Lecture Notes in Computer Science, Springer-Verlag, 1993. HAVAL is a highly-secure high-speed digest algorithm that is considered to be of the best in the world. HAVAL has two parameters. The first is the number of rounds, which can be 3, 4 or 5. The second is the output width, which can be 128, 160, 192, 224, or 256 bits. Veracity provides four variants from this



selection as described below.

haval34 — This is Haval with three rounds and a 128-bit output width.

haval38 — This is Haval with three rounds and a 256-bit output width.

haval54 — This is Haval with five rounds and a 128-bit output width.

haval58 — This is Haval with five rounds and a 256-bit output width.

md2 — This is the “RSA Data Security, Inc. MD2 Message-Digest Algorithm”. The defining document for MD2 is the RFC [Kalisky92]. MD2 is the slowest of the digests and does not provide much extra security and so it is recommended only as an additional digest when extremely high security is required. Its width is 16 bytes (128 bits).

md4 — This is the “RSA Data Security, Inc. MD4 Message-Digest Algorithm”. MD4 is a fast, fairly secure digest algorithm. However, when it was released, it was so popular that its inventors became concerned that it may not be secure enough for widespread use and released a more secure version which they named MD5. As such, MD5 is preferred. The defining document for MD4 is the RFC [Rivest92a]. Its width is 16 bytes (128 bits).

md5 — This is the “RSA Data Security, Inc. MD5 Message-Digest Algorithm”. This is a fast and secure algorithm and is widely considered to represent the state of the art in digest algorithms. The defining document for MD5 is the RFC [Rivest92b]. Its width is 16 bytes (128 bits).

sha0 --- This is the first version of the United States National Institute of Standards and Technology Secure Hash Algorithm (US NIST SHA). This algorithm has been superseded by the SHA-1 algorithm, but has been included in Veracity for reference purposes. Its defining document is [NIST93]. SHA-0ʼs width is 20 bytes (160 bits).

sha1 --- This is the second (and, as at July 1994, the most current) version of the United States National Institute of Standards and Technology Secure Hash Algorithm (US NIST SHA). Its defining document is [NIST94]. Its width is 20 bytes (160 bits).

Snefru — The is the Snefru algorithm, also known as “The Xerox Secure Hash Function”. Although the name “Snefru” looks as if it is an acronym, it is actually named after a Pharaoh of ancient Egypt. The Snefru algorithm is described in detail in [Merkle??]. Unlike the other algorithms, Snefru has two parameters called the security level (number of transformation iterations) and the output size (width of the digest in longwords (4-byte chunks)), each of which can take either the value 4 or 8. This leads to four different versions of Snefru which are presented in Veracity as the four distinct signature algorithms listed below.

snefru44 — This is Snefru with (SL=4,OS=4). Its width is 16 bytes (128 bits).




11.11 Data AttributesThe .data signature can be applied to all streams and represents the entire contents of the stream in question. Hereʼs the complete list of *.data attributes:



B.data - The entire binary stream.T.data - The entire text stream.A.data - Either B.data or T.data depending on the file kind.R.data - The entire Macintosh resource fork.S.data - The entire block of system bytes in the Macintosh resource fork.U.data - The entire set of user bytes inthe Macintosh resource fork.

So, for example, just as you can specify B.md5 to record and check the MD5 digest of the binary stream of the file, and B.len to record and check the length of the binary stream of a file, you can also specify B.data to record and check the entire contents of the binary stream of a file. The *.data attributes are very powerful, but must be used carefully. By instructing Veracity to record the entire contents of some files, the contents of those files must be stored in the snapshot file. This will make the snapshot file much bigger. If you took a snapshot of an entire directory tree in this way, the snapshot file would be at least as large as the tree itself, whereas usually itʼs only about 1/200th of the size of the tree. The benefit of using a *.data attribute is that the CHECK command can use the *.data attribute to provide a full binary or text differences of files that have changed.

For example, the following policy file instructs Veracity to detect all file creations and deletions and to record and check the binary and text streams of the file “secure.c”.

=====(BeginClipListV1)=====“#*” -*-> +create +delete“#secure.c” -f-> +B.data +T.data=====(EndClipList)=====

After changing “secure.c”, hereʼs the sort of output you might find in the report file: #:secure.c B.data T.data.Here is a complete binary comparison of B.data:+--------+-----------------------+-----------------------+--------+--------+| Offset |HEX1 |HEX2 | ASC1 | ASC2 |+--------+-----------------------+-----------------------+--------+--------+|(in hex)|00 01 02 03 04 05 06 07|00 01 02 03 04 05 06 07|01234567|01234567|+--------+-----------------------+-----------------------+--------+--------+|00000000|7B 0D 20 41 53 5F 48 43|7B 0D 20 41 53 5F 43 43|{. AS_HC|{. AS_CC||........|.......................|.......................|........|........||00000020|5F 48 43 4F 44 45 28 6C|5F 43 43 4F 44 45 28 6C|_HCODE(l|_CCODE(l||........|.......................|.......................|........|........||000000F0|3B 0D 20 70 5F 72 69 6E|3B 0D 7D 0D|;. p_rin|;.}. ||000000F8|67 2D 3E 6C 6B 5F 62 61| |g->lk_ba| ||00000100|63 20 20 20 20 20 20 20| |c | ||00000108|20 20 3D 20 70 5F 6C 6B| | = p_lk| ||00000110|3B 0D 7D 0D| |;.}. | |+--------+-----------------------+-----------------------+--------+--------+

Here is a complete text comparison of T.data:

+----------00002| AS_HCODE(lk_chk(p_ring);)00003| AS_HCODE(lk_chk(p_lk);)+---------->00002| AS_CCODE(lk_chk(p_ring);)00003| AS_CCODE(lk_chk(p_lk);)+----------

+----------00009| p_ring->lk_bac= p_lk;+---------->00009+----------



In particular, the *.data attributes are very useful in the following applications:

Security: In security applications itʼs important to monitor changes in all files that could affect security. As most files arenʼt supposed to change, this is easy to do using Veracity. Unfortunately, there is usually a small set of files that are both critical to security and which change quite often. Examples are login scripts and network configuration files. Such files often have to be changed whenever a new application is installed. For such files, knowledge that a change has taken place doesnʼt help much, as changes are so frequent. The user needs to know what the change is, without having to load a backup tape to perform a comparison. The *.data attributes allows security conscious users to obtain a full differences of frequently changing security-critical files (or any other files).

Source code change detection: If you specify the T.data attribute for all of the source files in a directory tree, you can use Veracity to perform a full text differences of an entire source tree. You might need a large amount of memory to do this though.

Note: The current version of Veracity loads and processes each directory in one operation. Thus if you use *.data attributes, Veracity will run out of memory unless you have enough memory for Veracity to store the attributes youʼve requested for each entire directory.

11.12 Non-Content AttributesThe non-content attributes store information about a file that is not directly based on the fileʼs actual content. For example, a fileʼs modification date, or owner are both examples, of non-content attributes. As non-content attributes tend to be operating-system specific, the attributes have been categorized by operating system, and the name of each attribute commences with an upper case letter indicating its operating system, as follows:

L OSExamples- ----------U Unix UTyp UMtmM Macintosh MAtt MFlaD MS-DOS DCtm DAttN Windows NTFS NOwn NGrpV OpenVMS VAlq VAclW NetWare WTyp WMtmS SymlinksSymLink SymChain

Most of the attributes consist of an upper case operating system letter followed by a three letter mnemonic for the attribute with the first letter of the mnemonic in upper case. These short names prevent policy files from becoming too cluttered, and save space in the snapshot file.

The symbolic link attributes have been assigned their own category because, while they are currently Unix-specific attributes (and are recognized by Veracity only on Unix), theoretically they could appear on other operating systems too.

11.13 Unix Non-Content AttributesThe table below provides a list of the Unix non-content attributes that Veracity can monitor. The second column gives the width of the attribute in bits along with a letter that indicates the attributeʼs portability:

P Portable between machines running different Unixes.



U Portable within machines running identical Unixes.

M Specific to a particular machine.

D Digital Unix only.

Name Wid DescriptionURfm U? Raw file mode. UTyp P16 Portable file type (see below). UPer P16 File permissions (see below). UNod M? INode number. UDev M? Device ID. ULin P? Number of hard links to the file.UUsr M? User ID. UGrp M? Group ID. USiz P? Size of the file in bytes. UAtm P? Access datetime. UMtm P? Modification datetime. UCtm P? Change datetime. UAcl D? Access Control List (ACL) UDaa D? Directory Access ACL UDda D? Directory Default ACL

Where the width is unspecified (?), this means that the value is represented in a variable length format. The value is treated as a natural number and represented as a sequence of zero or more bytes arranged in big-endian form (i.e. high-order byte first). All leading zero bytes are then deleted, with one zero byte being retained if the value of the number is zero. This format was adopted in Veracity V1.2 to cater for the differing and POSIX-unspecified widths of these attributes on different Unix machines. It enables values such as ULin and USiz to be portable between different Unixes, even if the width of the values varies.

Unixʼs raw file mode is a number that contains the file type and the file permissions. Veracity allows you to monitor this value using its URfm attribute. However, this attribute is unsatisfactory because it combines the file mode and permissions (which you may wish to monitor independently) and because it is not portable between different versions of Unix. To solve this problem, Veracity provides two additional file attributes that separate the information in the file mode into two Unix-portable attributes.

The UTyp (portable file type) is a 16-bit value that contains the file type encoded as a Unix-portable bit array as follows (0=False, 1=True):

0 - Directory.1 - Character-special.2 - Block-special.3 - Regular file.4 - FIFO.



5 - Symbolic link.6 - Socket.All other bits are set to zero.

Within Veracity, these bits are set or reset in accordance with the POSIX macros S_ISDIR(m) etc.

The UPer (portable permissions) attribute is a 16-bit value that contains the file permissions encoded as a Unix-portable bit array as follows (0=Disallow, 1=Allow):

FEDC B A 9 876 543 210---------------------- Usr Grp Oth0000 U G S RWX RWX RWX----------------------U=Set User ID.G=Set Group ID.S=Sticky bit.

Each datetime (UAtm, UMtm and UCtm) is represented by a natural number that codes the date in accordance the bit fields in the table below. The year field extends out indefinitely to the left. The natural number coding the date is then represented in the variable width format described earlier. Thus, the datetime 01-Jan-1970 00:00:00 would be coded as a single zero byte.

Bits Field Values Meaning------ ------ ------ -------??..26 Year0..?? 1970...25..22 Month 0..11 Jan..Dec21..17 Day 1..31 1..3116..12 Hour0..23 0..2311.. 6 Minute 0..59 0..59 5.. 0 Second 0..59 0..59

The UAcl, UDaa, UDda attributes monitor various ACL attributes. Unlike the other Unix attributes, their values take the form of strings of arbitrary length (being the textual representation of the ACLs). While these attributes are intended to be available on all Unix machines, currently they are supported only under Digital Unix. The UAcl is available for directory files, regular files, and volatile files, but not symlinks. The UDaa and UDda attributes are available for directory files only.

The following notes fill in the remaining details of the Unix attributes:

• As a general rule, an attempt has been made to represent each field in a format that will be as portable as possible. However, some fields (such as the inode) have semantics that are inherently non-portable.

• All the fields are stored in big-endian order in the snapshot file.

• The UAtm (date of last access) attribute is a little problematic to monitor because it is changed if Veracity accesses the content of a file! Veracity canʼt help this; itʼs a property of the file system. Perhaps future versions of Veracity will explicitly rewrite the value so as to restore it to its former value after performing the read (however this would break Veracityʼs “donʼt touch” design rule so this feature needs more thought before being implemented). In the current version of Veracity, if you want to monitor UAtm, you will not also be able to monitor B.md5 and other such content attributes.

• Under Unix the B stream can be used to check the contents of directory files.



11.14 OpenVMS Non-Content AttributesCompared to the other operating systems, OpenVMS file attributes are complicated. A comprehensive list of them can be found the in the description of the various fields of the various RMS control blocks in the OpenVMS Record Management Services Reference Manual (May 1993).

Under OpenVMS, to obtain file attributes, you create a FAB block and chain a whole lot of XAB blocks to the FAB using pointers, and then pass the whole mess into a $OPEN or $DISPLAY call. The result will be that many of the attribute fields will be filled in. Here is a list of the RMS blocks available:

Used MnemonicName (*Block) Purpose

---- --------------------- -------

Yes FAB File AccessThe root block. File name and basic attrs.

No NAM Name More sophisticated filename processing.

No RAB Record Access Record characteristics and access.

Yes XABALL Allocation Control Allocation of file on the host device.

Yes XABDAT Date and time Date and time for specialized media.

Yes XABFHC File Hdr.Charistcs. Miscellaneous information (e.g. length).

No XABITM Item List Item list arguments to RMS.

No XABJRN Journaling Journalling operations.

No XABKEY Key definitionKey definition for indexed files.

Yes XABPRO ProtectionsOwnership, accessibility, protections.

No XABRDT Revision datetimeSpecify revision time upon $CLOSE

No XABRURecovery Unit To do with journaling.

Yes XABSUM Summary Misc overall information about file.

No XABTRM Terminals Precise definition of terminal reads.

Thatʼs all the blocks. Some of the blocks are not applicable, as they are used only to provide information to RMS, or are applicable only in obscure applications. The Used column indicates whether Veracity bothers with a particular block. Of the blocks that are of interest, only some fields correspond to “permanent” file attributes.

Hereʼs a list of all the fields in all the blocks. The Name column contains the Veracity attribute name for the field (which you can specify in a policy file) if one has been defined, or ---- if there is no corresponding Veracity attribute. Most of the attributes that have been omitted are too volatile, ill-defined, or temporary to be monitored. However, if you see an attribute that is currently unsupported that you would like to monitor, please contact Rocksoft and weʼll consider adding it.

The length of each field is provided by the B (byte), W (word), L (longword), or Q (quadword) in each OpenVMS symbol name.

VMS Fieldname Name Description

------------- ---- -----------

FAB:

FAB.FAB$B_ACMODES ---- File access modes.

FAB.FAB$L_ALQ VAlq Allocation quantity (blocks).

FAB.FAB$B_BID ---- Block identifier.

FAB.FAB$B_BKS VBks Bucket size (in blocks).

FAB.FAB$B_BLN ---- Block length.

FAB.FAB$W_BLS ---- Magnetic tape block size.

FAB.FAB$V_CHAN_MODE -- Channel access mode protection.



FAB$L_CTX---- Context

FAB$W_DEQVDeq Default file extension quantity.

FAB$L_DEV---- Device characteristics.

FAB$L_DNA---- Default file specification string address.

FAB$B_DNS---- Default file specification string size.

FAB$B_FAC---- File access.

FAB$L_FNA---- File specification string address.

FAB$B_FNS---- File specification string size.

FAB$L_FOP---- File processing options.

FAB$B_FSZVFsz Fixed-length control area size.

FAB$W_GBCVGbc Global buffer count.

FAB$W_IFI---- Internal file identifier.

FAB$B_JOURNAL VJou Journal flags status.

FAB$V_LNM_MODE ---- Logical name translation access mode.

FAB$L_MRNVMrn Maximum record number.

FAB$W_MRSVMrs Maximum record size.

FAB$L_NAM---- Name block address.

FAB$B_ORGVOrg File organization.

FAB$B_RATVRat Record attributes.

FAB$B_RFMVRfm Record format.

FAB$B_RTV---- Retrieval window size.

FAB$L_SDC---- Secondary device characteristics.

FAB$B_SHR---- File sharing.

FAB$L_STS---- Completion status code.

FAB$L_STV---- Status values.

FAB$L_XAB---- Extended attribute block address.

------------------------------------------

NAM:

NAM$W_DID (Wx3)VDid Enclosing directory identification (3 unsigned words).

NAM$W_FID (Wx3)VFid File identification (3 unsigned words).

All other fields of this block are unused.

------------------------------------------

RAB: This block is unused.

------------------------------------------

XABALL:

XAB$B_AIDVAid Area identification number.

XAB$B_ALNVAln Alignment boundary type.

XAB$L_ALQ---- Allocation quantity (appears in FAB).

XAB$B_AOPVAop Allocation options.

XAB$B_BKZVBkz Area bucket size.

XAB$B_BLN---- Block length.

XAB$B_COD---- Type code.

XAB$W_DEQ---- Default extension quantity (already in FAB).

XAB$L_LOCVLoc Location.

XAB$L_NXT---- Next XAB address.

XAB$W_RFI---- Related file identifier.

XAB$W_VOL---- Related volume number.

------------------------------------------

XABDAT:

XAB$Q_BDTVBdt Backup date and time.


XAB$Q_CDTVCdt Creation date and time.


XAB$Q_EDTVEdt Expiration date and time.


XAB$Q_RDTVRdt Revision date and time.



XAB$W_RVNVRvn Revision number.

XAB$Q_RCD---- Time and date file was recorded.

XAB$Q_EFF---- Time and date file information was effective.

------------------------------------------

XABFHC:

XAB$B_ATR---- Record attributes (==FAB$B_RAT).

XAB$B_BKZ---- Bucket size (==FAB$B_BKS).



XAB$W_DXQ---- Default file extension quantity (==FAB$W_DEQ).

XAB$L_EBKVEbk End of file block.

XAB$W_FFBVFfb First free byte in end-of-file block.

XAB$W_GBC---- Default global buffer count.

XAB$L_HBK---- Highest virtual block in file (==FAB$L_ALQ).

XAB$B_HSZ---- Fixed-length control header siz (==FAB$B_FSZ).

XAB$W_LRLVLrl Longest record length.

XAB$W_MRZ---- Maximum record size (==FAB$W_MRS).


XAB$B_RFOVRfo File org and rec format (==FAB$B_RFM,FAB$B_ORG).

XAB$L_SBNVSbn Starting logical block number.

XAB$W_VERLIMIT VVlm Version limit for the file.------------------------------------------XABITM: This block is unused.XABJRN: This block is unused.XABKEY: This block is unused.------------------------------------------XABPRO:Variable len......VAcl Veracity text attribute containing ACL string.XAB$L_ACLBUF xxxx Address of buffer that contains ACL.XAB$L_ACLCTX xxxx ACL positioning context.XAB$W_ACLLEN xxxx Length of the ACL.XAB$W_ACLSIZ xxxx Length of buffer containing binary ACEs.XAB$L_ACLSTS---- System error status for ACL processing.XAB$B_BLN---- Block length.XAB$B_COD---- Type code.XAB$W_GRPVGrp Group number of file owner.XAB$W_MBMVMbm Member number of file owner.XAB$B_MTACC VMta Magnetic tape accessibility.XAB$L_NXT---- Next XAB address.XAB$W_PROVPro File protection.XAB$B_PROT_OPT ---- File protection options.XAB$L_UICVUic User identification code (VGRP,VMBM).------------------------------------------XABRDT: This block is unused.XABU : This block is unused.------------------------------------------XABSUM:XAB$B_BLN---- Block length.XAB$B_COD---- Type code.XAB$B_NOAVNoa Number of allocation areas defined for the file.XAB$B_NOKVNok Number of keys defined for this file.XAB$L_NXT---- Next XAB address.XAB$W_PVNVPvn Prolog version number.------------------------------------------XABTRM: This block is unused.------------------------------------------



In Veracity, all attributes are stored in big-endian order regardless of the endianess of the host OS. Arrays of words or longwords are stored with each word or longword in big-endian order.

If the above list is too daunting, perhaps the following will help. The OpenVMS DCL DUMP command displays some file attributes. Here is how the ones defined above map to them. The Veracity attribute name appears to the left with “----” being used to indicate an attribute that Veracity does not monitor because it was not considered appropriate. Question marks are used to indicate current gaps in Veracityʼs coverage (i.e. attributes that it possibly should be capable of monitoring).

$ dump/header/block=count=0 login.com

Dump of file $USERS:[000000.ROSS]LOGIN.COM;17 on 30-APR-1995 21:41

File ID (6812,34,0)End of file block 1 / Allocated 3

File Header

Header area

---- Identification area offset: 40

---- Map area offset: 100

---- Access control area offset: 255

---- Reserved area offset: 255

---- Extension segment number: 0

---- Structure level and version: 2, 1

VFid File identification:(6812,34,0)

---- Extension file identification: (0,0,0)

---- VAX-11 RMS attributes

VRfmRecord type: Variable

VOrgFile organization: Sequential

VRatRecord attributes: Implied carriage control

VLrlRecord size: 60

VAlqHighest block: 3

VEbkEnd of file block: 1

VFfbEnd of file byte: 490

VBkzBucket size: 0

VFszFixed control area size: 0

VMrsMaximum record size: 0

VDeqDefault extension size: 0

VGbcGlobal buffer count: 0

VVlmDirectory version limit: 0

???? File characteristics:

---- Map area words in use: 2

???? Access mode: 0

VUic File owner UIC: [ROSS]

VPro File protection: S:RWED, O:RWED, G:, W:

VDid Back link file identification: (3367,18,0)

VJou Journal control flags:

???? Active recovery units: None

???? Highest block written: 3

---- Identification area

NAME File name: LOGIN.COM;17

VRvn Revision number: 3

VCdt Creation date: 7-FEB-1995 01:20:21.42

VRdt Revision date:30-APR-1995 02:32:58.52



VEdt Expiration date:

VBdt Backup date: 30-APR-1995 20:01:08.02

---- Map area

---- Retrieval pointers

----Count: 3 LBN: 146397

VAcl The ACL field that is dumped for non-empty ACLs.

---- Checksum:23139

11.15 Macintosh Non-Content AttributesVeracity can monitor all Macintosh file attributes as provided by the CInfoPBRec block returned by the PBGetCatInfo function as described in Inside Macintosh (IV-155, IV-186 to IV-187). In addition, there are some server protection fields available that are returned by PBHGetDirAccess (V-394).

Field MacField NameFD Type Width Format

----- -------- ------ ---- ----- ------

File Ref NumioFRefNumMNumFD uword 2 bytes

File attributesioFlAttrib MAttFD ubyte 1 byteFlags

User access ioACUser MUacFD ubyte 1 bytes Flags

Type ioFlFndrInfo.fdType MTypFchar[4] 4 bytes char[4]

Creator ioFlFndrInfo.fdCreator MCreFchar[4] 4 bytes char[4]

Flags ioFlFndrInfo.fdFlags MFlaFuword 2 bytes Flags

Flags ioDrUsrWds.frFlagsMFla D uword 2 bytes Flags

Flags ioFlFndrInfo.fdFlags MFlm* Fuword 2 bytes Flags

Flags ioDrUsrWds.frFlagsMFlm*D uword 2 bytes Flags

* Same as MFla except with bit 8 (hasBeenInited) and bit 9 (isLetter) zeroed.

Location ioFlFndrInfo.fdLocation MLocFword[2] 4 bytes Point

Location ioDrUsrWds.frLocationMLoc D word[2] 4 bytes Point

WindowioFlFndrInfo.fdFldr MWinFuword 2 bytes

Entity IDioDirID MEniFulong 4 bytes

Entity IDioDrDirIDMEni D ulong 4 bytes

Datafork.firalloc ioFlStBlkMDfaFuword 2 bytes

Datafork.logeofioFlLgLenMDleFulong 4 bytes

Datafork.phyeofioFlPyLenMDpeFulong 4 bytes

Rsrcfork.firalloc ioFlRStBlk MRfaFuword 2 bytes

Rsrcfork.logeofioFlRLgLen MRleFulong 4 bytes

Rsrcfork.phyeofioFlRPyLen MRpeFulong 4 bytes

Creation time ioFlCrDatMCtmFdt_t ? bytes Date

Creation time ioDrCrDatMCtm D dt_t ? bytes Date

Modification time ioFlMdDatMMtmFdt_t ? bytes Date

Modification time ioDrMdDatMMtm D dt_t ? bytes Date

Backup time ioFlBkDatMBtmFdt_t ? bytes Date

Backup time ioDrBkDatMBtm D dt_t ? bytes Date

Icon ID ioFlXFndrInfo.fdIconID MIciFuword 2 bytes

CommentIDioFlXFndrInfo.fdComment MCmiFuword 2 bytes

CommentIDioDrFndrInfo.frComment MCmi D uword 2 bytes

HomeDirIDioFlXFndrInfo.fdPutAway MHdiFulong 4 bytes

HomeDirIDioDrFndrInfo.fdPutAway MHdi D ulong 4 bytes

ParentDirID ioFlParIDMPdiFulong 4 bytes

ParentDirID ioDrParIDMPdi D ulong 4 bytes

Clump size ioFlClpSiz MCluFulong 4 bytes

Folder rectangle ioDrUsrWds.frRect MRec D word[4] 8 bytes Rect



Folder view ioDrUsrWds.frView MVie D uword 2 bytes

Number of filesioDrNmFlsMNfl D uword 2 bytes

Scroll positionioDrFndrInfo.frScrollMScr D word[2] 4 bytes Point

Open chain ioDrFndrInfo.frOpenChain MOch D ulong 4 bytes

Fields from PBHGetDirAccess:

Field MacField NameFD Type Width Format

----- -------- ------ ---- ----- ------

OwnerID HParmBlkRec.ioACOwnerID MOwn D ulong 4 bytes Username

GroupID HParmBlkRec.ioACGroupID MGrp D ulong 4 bytes Username

Access rights HParmBlkRec.ioACAccess MAcc D ulong 4 bytes Flags

All of these attributes have been provided for completeness. However, most Macintosh Veracity users will wish to monitor just a few of these attributes. Three important attributes to monitor are MFla, MTyp, and MCre.

The FD column of the table above indicates whether the attribute can be monitored for files and/or directories. The Name column gives the name to specify in the policy file.

Note: The ioFVersNum field of CInfoPBRec is no longer supported by Apple and is not included in this list.

Note: ioFlAttrib contains dynamic attributes (instantaneous read/write access), but it was included anyway.

Note: ioACUser is the access the current user has to the files. It is not an attribute of just the files themselves.

The MFla attribute is a 16-bit value that contains the fileʼs flags. The following extract from an Apple Technical Note by Jim Friedlander and Steve Falkenburg explains what they all mean.

Bit Meaning

0 Reserved in System 7; set to 0.

(previously set if file/folder is on the desktop)

1 Color information.




(previously never SwitchLaunch prior to System 7)


(previously always SwitchLaunch prior to System 7)

6 isShared bit. Set if file is a shareable application. Set to 0 for non-applications.

7 hasNoINITS bit. Set if the file contains no ‘INIT’ resources; set to 0. Reserved for

directories; set to 0.

8 hasBeenInited bit. Set once the Finder has recorded information from the files bundle

resource into the desktop database and given the file or folder a position on the desktop.

Clear for newly created files.

9 isLetter bit. Set if the file is an AOCE letter under System 7 Pro and later. Formerly

the Changed bit. Set to 0 for non-letters.

10 hasCustomIcon bit. Set if the file or folder has a custom icon. (previously the Busy bit

prior to System 7)

11 isStationery bit. Set if the file is a stationery pad under System 7 and later.

Reserved for directories, in which case set to 0. (previously NoCopy or BOZO bit, not

used in 5.0 and later)



12 nameLocked bit. If set, the file or directory can’t be renamed from the Finder and the

icon can’t be changed. (previously called the System bit)

13 hasBundle bit. The file contains a bundle resource. Reserved for directories, in which

case set to 0

14 invisible bit. The file or directory is invisible from the Finder and from the Standard

File dialogs.

15 isAlias bit. The file is an alias file. Reserved for directories in which case set to 0.

(previously the Locked bit prior to System 7)

In practice, it turns out that MacOS changes bits 8 and 9 quite often, and so an additional Veracity attribute MFlm (Macintosh flags with mask) has been provided that ignores (records as zero) bits 8 and 9. It is recommended that you use MFla, but switch to MFlm if you find that notification of changes to bit 8 and 9 are cluttering your Veracity reports.

Each datetime (MCtm, MMtm and MBtm) is represented by a natural number that codes the date in accordance the bit fields in the table below. The year field extends out indefinitely to the left. The natural number coding the date is then represented in the variable width format described earlier. Thus, the datetime 01-Jan-1970 00:00:00 would be coded as a single zero byte.


Recommendation

If you are uncertain about which Macintosh attributes to monitor, we suggest that you use the following rules in your policy file:

“#*” -df-> +create +delete +MFlm“#*” -f-> +B.md5 +U.md5 +MTyp +MCre

This instructs Veracity to monitor the flags of each directory and non-directory file, and the MD5 digest of the data and resource fork and the type and creator of each non-directory file.

11.16 MS-DOS Non-Content AttributesVeracity can monitor all the MS-DOS file attributes, using the following Veracity non-content attributes. These attributes are available to the Win32 version of Veracity (running on Windows 95/98/ME or Windows NT/2000/XP) as well as the MS-DOS version of Veracity (running on stand-alone MS-DOS, Windows 95/98/ME, or Windows NT/2000/XP) with just a few exceptions.

Name Leng Description---- ---- -----------DSnmVar Short (8.3) name.DLnmVar Long filename in ASCII.DLnuVar Long filename in Unicode.DSizVar Size of the file in bytes.DAtmVar Access datetime.DCtmVar Creation datetime.DMtmVar Modification datetime.



DAtt 1 Attribute flags coded as a single byte:0 = ReadOnly.1 = Hidden.2 = System.3 = Volume ID.4 = Subdirectory.5 = Archive.6 = 07 = 0DAza 1 Same as DAtt except that thearchive bit is recorded as zero.DArc 1 The archive bit - ‘0’ or ‘1’.DAsb 1 Same as Datt except that the archivebit and the readonly bit arerecorded as zero.

Each datetime (DAtm, DMtm and DCtm) is represented by a natural number that codes the date in accordance the bit fields in the table below. The year field extends out indefinitely to the left. The natural number coding the date is then represented in the variable width format described earlier. Thus, the datetime 01-Jan-1970 00:00:00 would be coded as a single zero byte.


The DSiz field is stored as a variable-length number.

The subdirectory attribute bit indicates whether the file is actually a directory (the terms “directory” and “subdirectory” are generally interchangeable). The archive bit is a bit that is set to 1 by MS-DOS whenever the file is changed. MS-DOS backup utilities use this bit to perform incremental backups, and reset the bit to 0 whenever the file is backed up. This means that the bit tends to flop about and cause spuriously inconsequential DAtt change reports. Veracity deals with this problem by providing an additional attribute DAza which is the attribute byte but with the archive bit always represented as zero. The DArc attribute stores the archive bit all on its own and may be used in combination with DAza in some situations. The DAsb (DOS Attribute Stable Bits) was introduced to assist in the production of CD-ROMs. When a CD-ROM is written, some CD-ROM writers set the readonly bit of the CD-ROM copy of each file written. This makes it difficult to check the attributes of files written to a CD-ROM. By ignoring the “unstable” bits in the attribute flag, the DAsb attribute enables the attributes of DOS files just written to a CD-ROM to be checked. This attribute may have other applications too.

The MS-DOS version of Veracity can read the DLnm attribute only for FAT12 and FAT16 file systems.

The DLnu attribute is currently available only to the MS-DOS version of Veracity, and only when applied to FAT12 or FAT16 file systems.

Please contact Rocksoft if you need any of the above restrictions lifted.



11.17 Windows NT/2000/XP Non-Content AttributesIn addition to being able to monitor the MS-DOS Attributes, the Win32 version of Veracity, when run on a Windows NTFS platform, can monitor the following attributes of files in an NTFS file system. All these attributes are of variable length, including the compressed size which is represented as a variable-length number (see the Unix non-content attributes for more information on this).

NameLeng Description-------- -----------NOwn Var File owner.NGrp Var File group.NDac Var Discretionary ACL (DACL).NSac Var System ACL (SACL).

NOwnBVar File owner(binary SID).NGrpBVar File group(binary SID).NDacBVar Discretionary ACL (DACL) (binary SID).NSacBVar System ACL (SACL) (binary SID).

NCsz Var Compressed size of the file.

NNas Var Number of alternative data streams.NStr Var Names of alternative data streams.NStrmd5 Var MD5 of alternative data streams concatenation.

(ACL = Access Control List).

These attributes are available only to the Win32 version of Veracity running on Windows NT/2000/XP and only for NTFS file systems. Other file systems (e.g. FAT16 and FAT32) do not store these attributes. Veracity will generate an error if you instruct it to fetch one of these file attributes from a non-NTFS volume.

Symbolic Versus Binary SID Representations

Windows NT/2000/XP has a concept of a SID (Security Identifier) which is a unique binary block that identifies a single user or group on a Windows NT/2000/XP system. Internally, Windows NT/2000/XP represents SIDs in binary form, only translating them to text when it is necessary to display them. Here is an example of the two forms, with the binary form being displayed in hexadecimal.

Text: A:AdministratorsBinary : 01020000000000005200000002000200000

Each user or group in the system has its own unique binary SID. These binary SIDs are allocated by Windows NT/2000/XP depending on the order of creation of users and groups and possibly other unknown factors particular to the way Windows NT/2000/XP works. As a result, the correspondence between named users and groups and their SIDs may differ between Windows NT/2000/XP computers, even if the file systems and security look the same in all the browsing tools. For example, the user Dave might correspond to 000020B0F on one Windows NT machine and 0000403E05 on another (Note: The hex strings were made up at random for the purposes of illustration only).



Thus, for the purposes of Veracity, a SID may be recorded by recording its corresponding user or group name (symbolic form) or by recording the bytes in the SID (binary form). Symbolic form has the advantage of allowing two Windows NT file systems to be compared, even if the user and group databases of each were built independently (and hence have differing name-to-SID mappings). Binary form is not portable in this way, but may be more secure, depending on your point of view.

Rather than choose between the two representations, Veracity provides two sets of Windows NT attributes. The first set, the binary NT attributes, (NOwn, NGrp, NDac, NSac) stores each SID in its symbolic form. The second set, the symbolic NT attributes, (NOwnB, NGrpB, NDacB, NSacB) stores each SID in its binary form (using upper case hexadecimal digits). The NOwn/NOwnB and NGrp/NGrpB attributes correspond to a single SID, whereas the NDac/NDacB and NSac/NSacB attributes contain a list of ACEs, each of which has a SID component that will appear in binary or symbolic form as specified. The NCsz attribute does not contain a SID so it is independent of all this.

Rocksoft does not assert that one form of these attributes is more or less secure than the other. As user and group names must be unique, we can see no obvious reason why the symbolic attributes would be insecure, but security is slippery, and we can make no guarantees. We have provided both forms so that you, the user, may decide. If security is very important to you, use both.

For general purpose security use, we recommend that you use the symbolic SID attributes (as these provide a much more readable change report) adding the binary SID attributes only if you want additional security (and a bigger snapshot file!). If you are an expert in NT security issues and have some light to shed on this issue, please contact Rocksoft so that we can improve this page.

The remainder of this page describes the symbolic attributes only (NOwn, NGrp, NDac, NSac). The binary attributes are exactly the same except that whenever a SID appears, it is represented in binary form as a string of hexadecimal digits rather than in symbolic form as (e.g.) a user name.

Owner (NOwn) and Group (NGrp) Attributes

The file owner and group attributes are recorded in the form of an entity type letter, followed by a colon, followed by the name of the entity, followed by a slash and a letter (D or P) to indicate if the value defaulted or is explicitly present. For example:

U:Dave/PW:Everyone/D

which means the User called Dave explicitly specified, and the well-known group Everyone which defaulted. Here is a complete list of the entity type letters Veracity uses and what they mean:

U - User.G - Group.D - Domain.A - Alias.W - Well known group.D - Deleted account.I - Invalid.U - Unknown.



E - Error (if an error occurscalculating this field).

If a name field contains certain forbidden characters, they are translated (“escaped”) as shown below. This ensures that such names can be safely embedded within the ACL syntax about to be described, without posing a security risk.

(-> \L)-> \R/-> \S,-> \C:-> \N<-> \X>-> \Y\-> \\

The NDac and NSac Attributes

An Access Control List is represented by a single string in one of the following formats: <NoACL>(<EmptyACL>)(ACE1,ACE2,...,ACEn)/D(ACE1,ACE2,...,ACEn)/P

These forms represent no ACL present, an present but empty ACL, and ACLs that are explicitly present (/P) or have defaulted /D. The <EmptyACL> syntax was introduced to ensure that empty ACLs are noticed.

An ACL (Access Control List) consists of a list of ACEs (Access Control Entities) bounded by parentheses and separated by commas. It ends with /P if the ACL is explicitly present for the object or /D if the ACL was inherited from some other object (e.g. an ancestor directory). Here is an example ACL string:

(+U:Sloth//ZXD-01Bf,+W:Everyone//ZOPXD-01FF)/P

Each ACE starts with a plus sign for an ACE that grants an access, a minus sign for an ACE that denies an access, or an asterisk for an audit ACE. If any other kind of ACE is present in the list, Veracity will generate an error. The ACE-type indicator character is followed by a user/group specifier (in the format described earlier) followed by a slash. Then follows a series of letters representing the ACE flags that are turned on. If no such flags are turned on, this field will consist of the empty string. Here are the letters used to represent the flags.

c - Container inherit ACE.i - Inherit-only ACE.n - No propagate inherit ACE.o - Object inherit ACE.f - Failed access ACE.s - Successful access ACE.

Then follows another slash followed by a representation of the ACEʼs access mask. Access masks consist of a 32-bit value. The semantics of the bottom 16-bits depends on the type of the object to which the ACE is attached (“specific rights”) and so are represented by Veracity as a raw four-digit hexadecimal number. The top 16 bits are more clearly defined and are



represented by a string containing a letter for each bit that is turned on. A hyphen separates the representation of the top and bottom 16 bits. Here are the meanings and letters for the top 16 bits of the access mask.

L Bit Meaning- --- -------R31 GENERIC_READW30 GENERIC_WRITEE29 GENERIC_EXECUTEA28 GENERIC_ALLg27 Reservedf26 ReservedM25 MAXIMUM_ALLOWEDY24 ACCESS_SYSTEM_SECURITYd23 Unspecifiedc22 Unspecifiedb21 UnspecifiedZ20 SYNCHRONIZEO19 WRITE_OWNERP18 WRITE_DACX17 READ_CONTROLD16 DELETE

The NDac and NSac attributes consist of a string as described above. This string is represented in plaintext in the snapshot file, so if you want to see exactly how Veracity is representing a particular ACL, you can look there. Another way to see whatʼs going on is to use the attribute command to inspect these attributes for a particular file. For example:

veracity attribute myfile.txt NDac NSac

Design Notes

Note: Microsoft Windows NT 4.0 does not provide an operating system call that delivers a textual representation of an ACL. Consequently, the textual representation used by Veracity to represent ACLs was created by Rocksoft based on the technical literature available to Rocksoft. Rocksoft contacted Microsoft Support to determine if there is a “standard” for textually representing ACLs, but Microsoft could provide no such standard. If you know of such an informal or formal standard, or have any suggestion for how we can improve our ACL representation, please let us know.

Note: To the best of Rocksoftʼs knowledge, the ACL representation used in Veracity is comprehensive (i.e. represents ALL the information in the ACL) and secure (i.e. it is not possible to subvert the ACL syntax by setting an ACL to particular values (e.g. the name field)). However, as this attribute is security critical, please let us know immediately if you discover an omission or fault in this representation.

NTFS Alternative Data Streams

NTFS alternative data streams are a perfect place where viruses can hide undetected, as alternative data stream data does not affect the displayed file size and the data is not displayed by normal system utilities.

Veracity uses three attributes to detect the presence of, or changes in, alternative data streams in NTFS files.



The simplest attribute, NNas has a value which is the number of alternative data streams present in the file. This is suitable for most security applications where no files are expected to have any alternative data streams present. Use of this attribute will detect any data streams that appear.

If there are files that have existing data streams that are expected to be present, the NStr attribute should be used in addition. The value of NStr is the concatenation of all stream names separated by the vertical bar (|) character. NStr will detect any changes in stream names, not merely the number of streams.

For absolute detection of any changes in the content of alternative data streams, the attribute NStrmd5 is most suitable. The value of NStrmd5 is the MD5 digest of the concatenation of the data for all streams, each stream preceded by the length of that stream as a 64-bit value (high word first). Therefore any change in any stream or any movement of data from one stream to another will be detected.

The process that executes Veracity needs to be able to set Backup privilege in order to read data stream data.

11.18 Novell Netware Non-Content AttributesThe table below provides a list of the Novell Netware non-content attributes that Veracity can monitor.

NameDescription---------------WRfmRaw file mode. Contains file type and file privileges.WTypFile type. (Directory, Regular or FIFO).WNodDirectory entry number.WDevVolume number.WSizFile size.WUsrObject ID of the owner.WBidObject ID of the last user to backup the file.WMidObject ID of the last user to modify the file.WAtmAccess time.WBtmBackup time.WCtmChange time.WMtmModification time.

11.19 Symbolic Link Non-Content AttributesSymbolic links (symlinks) appear in Unix file systems and are directory entries that contain the path of a file in the file system. When Unix sees a symbolic link, it pretends (in most contexts) that the file so pointed to is actually in the directory that contains the symbolic link and has the same name as the symbolic link.

Veracity provides three special attributes for monitoring the value of symbolic links. Perhaps these attributes should be called “content” attributes rather than “non-content” attributes, as they record the content of symbolic links, but it seems appropriate to document them here, as they do not monitor the actual data content of files.

The three attributes are available on all platforms, but are applicable only to symbolic links. Here they are:



SymLink: The SymLink attribute records the value of a symbolic link. For example, if a symbolic link points to “../sources” that is exactly what the SymLink value will be. Veracity stores exactly the symbolic linkʼs string value, not the full path that the value implies. This enables trees containing relative symlinks to be compared, even when they are in different places on different Unix machines.

SymChain: The SymChain attribute records the entire symbolic link chain (of one or more links) that stems from the symbolic link. Such a chain arises when one symbolic link points to another symbolic link. To calculate the SymChain attribute, Veracity follows the entire chain and records the value of each symbolic link in the chain in a list. Veracity does not employ cycle detection when following symbolic link chains, but it will terminate once it reaches a upper limit of links (unspecified and subject to change, but currently about 20 links). If the chain canʼt be followed all the way to a non-symlink file, Veracity will generate an error and not record the SymChain attribute. To prepare the final value that represents the chain, Veracity separates the elements with commas, representing commas in elements as backslash lower-case c and representing backslashes as double backslashes. This attribute is useful in security applications where you want to ensure that a symlink chain hasnʼt been spliced by an intruder so that it can be modified at will.

SymTarget: The SymTarget attribute records the absolute full pathname of the file that is at the end of the chain of symbolic links stemming from the link in question.

These three attributes are provided, so as to be comprehensive. However, in most applications, all you really need to do to keep track of the values of symbolic links is to include a single rule in your policy file to monitor the SymLink attribute, as shown below.

=====(BeginClipListV1)===== “#*” -*-> +create +delete “#*” -s-> +SymLink “#*” -f-> +B.md5 =====(EndClipList)=====

Note: By default, Veracity does not follow symbolic links. However, you can tell it to do so using the follow pseudo attributes. If you choose to follow symlinks, you may or may not wish to monitor their values too; the choice is yours.

Note: Veracity represents these values in the snapshot file using Unicode.

11.20 Directory Cycle Non-Content AttributeMost file systems consist of a tree of directories. However, in some file systems, it is possible for directory cycles to form. This can occur, for example, when a directory contains an entry for a directory that is an ancestor directory. Some file systems exclude such structures, but others facilitate it by providing mechanisms such as symbolic links and uncontrolled hard linking.

Cycles pose a hazard for directory-traversing tools such as Veracity because they can cause such tools to fall into an infinite loop. Veracity protects itself from this by performing cycle checks. Before entering a directory to process it, Veracity checks to see if the directory is the same directory as any of its ancestors in the traversal. If it is, by default Veracity issues an error and does not traverse the directory (or the subtree of which it is root). You can change



the action that Veracity takes, when it encounters a cycle, using the pseudo attributes follow_cycle, no_cycle_error, and no_cycle_match_error. follow_cycle instructs Veracity to enter cyclic directories. no_cycle_error instructs Veracity not to generate an error when it encounters a cycle. no_cycle_match_error instructs Veracity not to issue an error if the cycleness of a directory (it has entered) has changed.

The cycleness of a directory is the number of links up the directory ancestor chain to the nearest identical ancestor directory, or zero if there is no identical ancestor. The cycleness of a directory can depend on where Veracity starts within the directoryʼs cycle.

Veracity calculates and records the cycleness of every directory it enters and by default will generate an error during a check if the cycleness has changed (unless no_cycle_match_error is set for the directory). However, it does not calculate, record, or check the cycleness until it actually enters a directory. Thus, if you have clipped out a directory (using a policy file rule), the cycle check will not be performed by default. This behavior ensures that when you specify that a directory be clipped, that Veracity makes no attempt to access it by default. This enables you to clip inaccessible directories without Veracity issuing errors because it cannot access the directory to calculate its cycleness!

If you do not wish to enter a directory (i.e. you want to clip it), but you still want to monitor its cycleness, you can do so using Veracityʼs Cycle attribute. This attribute is applicable only to directory files and records the cycleness of the directory. For example:

=====(BeginClipListV1)=====“#*” -*-> +create +delete“#*” -s-> +follow“#*” -f-> +B.md5“/usr/util/util”-d-> +Cycle“/usr/util/util#*” -*-> -all=====(EndClipList)=====

This policy file instructs Veracity to monitor the creation and deletion of all files, to “follow” softlinks, to monitor the content of all regular files (using B.md5), and to clip the util directory. By default, the cycleness of each directory is checked upon entry, but as the util directory is clipped, that wonʼt happen, and so its cycleness is monitored explicitly using +Cycle.

Note: The Cycle attributeʼs value depends on where you “start” in the tree traversal. A particular consequence of this is that if you access the Cycle attribute using the attribute command, the value will always be zero because the attribute command only examines a single file and will not have the chance to build a chain of ancestor directories with which it might identify the directory as being cyclic.



12 MiscellaneousThis section contains information that needs to be in the reference manual, but which doesnʼt fit neatly into the other chapters.

12.1 IntroductionThis section contains information that needs to be in the reference manual, but which doesnʼt fit neatly into the other chapters.

12.2 Versions

Introduction

This page contains a record of every version of Veracity ever released, and the differences between them.

Veracity V1.0 (06-Jul-1994)

This was the first version of Veracity ever to be released. It was available for Macintosh, MS-DOS, OpenVMS VAX, OpenVMS Alpha, Digital Unix, and SunOS.

Veracity V1.0.1 (21-Sep-1994)

This maintenance released fixed some initial problems.

Veracity V1.1 (05-Feb-1995)

Version 1.1 saw the addition of some significant new features. These features positioned Veracity as not only a significant, but a comprehensive, security tool that could monitor all Unix file attributes and provide a full differences of critical security files that change often.

• Added *.data attributes for full differences.

• Added B.data attribute.

• Added T.data attribute.

• Added A.data attribute.

• Added R.data attribute.

• Added S.data attribute.

• Added U.data attribute.

• Veracity now writes out a message at startup.

• Veracity now copies diagnostics to the console up to a limit.

• Added +V argument to SNAPSHOT and CHECK commands.

• Added +E argument to SNAPSHOT and CHECK commands.



• Added monitoring of all Unix file attributes.

• Added URfm attribute.

• Added UTyp attribute.

• Added UPer attribute.

• Added UNod attribute.

• Added UDev attribute.

• Added ULin attribute.

• Added UUsr attribute.

• Added UGrp attribute.

• Added USiz attribute.

• Added UMtm attribute.

• Added UCtm attribute.

• Added UAtm attribute.

• Added Macintosh R, S and U streams.

• No expiry date on this and later versions of Veracity. (Actually, it will expire on 31-Dec-2033 because of the internal date format, but Veracityʼs internal 32-bit date format will have been revised by then).

• Revised and strengthened the license file system.

• Added PURGE command.

• Added DIRECTORY command.

• ENEO command now takes a pattern argument.

• Added extra online help messages.

• The journal file now contains start and end datetimes.

• Added topskel predefined policy file.

• Fixed two bugs in MS-DOS version.

• Fixed a bug in fuzzy filename matching.

Veracity V1.1.1 (11-Aug-1995)

Version 1.1.1 addressed some OpenVMS issues.

• Fixed a problem in the processing of OpenVMS binary files.

• Added VERSION fuzzy matching for OpenVMS.



• Added +A command line argument for OpenVMS.

• Added DIFF command to allow user to compare files.

• Added CAPTURE command to support regression testing.

• Added $. macro.

• Added ^ policy file pattern element.

• Added ; stripping in general fuzzy match algorithm.

Veracity V1.1.2 (22-Oct-1996)

Veracity V1.1.2 was released mainly to eliminate a message generated by V1.1.1 that told the user, a year after its release, that Veracity V1.1.1 was likely to have been superseded by a new version.

• Remove the “year old” warning.

• Added exit message in Macintosh version.

• Changed Mac version to set creator of output files to BBEdit.

Veracity V1.1.3 (25-Jun-1997)

Version 1.1.3 was a maintenance release that fixed a number of minor problems and added some new features.

• Ported to Win32 (Windows 95 and Windows NT).

• MS-DOS version now sees hidden files.

• MS-DOS version now looks for license file in env var ROCKLF.

• Updated snapshot file header comment.

• Updated report file header comment.

• Updated journal file header comment.

• Updated HELP command messages.

• Changed DEC OSF/1 license identifier to Digital Unix.

• Changed OpenVMS AXP license identifier to OpenVMS Alpha.

• Improved OpenVMS handling of command arguments.

• Completely revised all predefined policy files.

• Added code to stop Veracity reading non-regular Unix files.

• Added ~ policy file pattern component.



Veracity V1.2 (18-Oct-1998)

Version 1.2 saw the strengthening of Veracity and the addition of a wide-range of new features including a comprehensive new approach to symbolic links and non-regular files, directory cycle detection, complete MS-DOS and Windows NT file attribute monitoring, Digital Unix ACL monitoring, and pseudo attributes to suppress various text warnings that were generating too much noise in web transfer verification applications.

• Added UAcl attribute.

• Added UDaa attribute.

• Added UDda attribute.

• Eliminated hanging of Unix version upon reading a pipe with +auto.

• Added no_text_lf_warning attribute.

• Added no_text_cr_warning attribute.

• Added no_text_sub_warning attribute.

• Added no_text_ltl_warning attribute.

• Added no_text_llu_warning attribute.

• Added no_text_warnings attribute.

• Added transfer_ntw predefined policy file.

• Added text_ntw predefined policy file.

• Added web_ntw predefined policy file.

• Added diff_ntw predefined policy file.

• Deleted system predefined policy file.

• A complete overhaul of Veracityʼs processing of symbolic links and non-regular files.

• Enlarged filetypes from Dir/File (DF) to Dir/File/Symlink/Volatile (DFSV).

• Veracity no longer follows symbolic links by default.

• Veracity can follow symbolic links as specified.

• Added SymValue attribute.

• Added SymChain attribute.

• Added SymTarget attribute.

• Added follow pseudo attribute.

• Added follow_dir pseudo attribute.

• Added follow_file pseudo attribute.



• Added follow_vol pseudo attribute.

• Changed snapshot file format: • (Version=1)=> (Version=2)

• ((Stub=N)(TotalFiles=34)(Dirs=18))

• => ((Stub=N)[(Cycle=0)](Num=34))

• (N=Dsloth)=> (T=D)(N=sloth)

• (N=Xsloth)=> (T=F)(N=sloth)

• (N=Bsloth)=> (T=F)(N=sloth)(K=B)

• (N=Tsloth)=> (T=F)(N=sloth)(K=T)

• Note: The Dirs field has been eliminated.

• Note: Added (optional) K attr for kind of file.

• Veracity V1.2 can read V1 and V2 snapshot files.

• Added cycle detection (active by default).

• Added no_nonbinary_warning pseudo attribute.

• Added no_nontext_warning pseudo attribute.

• Added no_kind_warnings pseudo attribute.

• Added no_cycle_error pseudo attribute.

• Added follow_cycle pseudo attribute.

• Added no_cycle_match_error pseudo attribute.

• Added DSnm attribute.

• Added DLnm attribute.

• Added DLnu attribute.

• Added DSiz attribute.

• Added DAtm attribute.

• Added DCtm attribute.

• Added DMtm attribute.

• Added DAtt attribute.

• Added DAza attribute.

• Added DArc attribute.

• Added NOwn attribute.



• Added NGrp attribute.

• Added NDac attribute.

• Added NSac attribute.

• Added NCsz attribute.

• Added NOwnB attribute.

• Added NGrpB attribute.

• Added NDacB attribute.

• Added NSacB attribute.

• Added NCszB attribute.

• Changed fuzzy match minimum match threshold from 8 to 6.

• Added Cycle attribute.

• Added -df-> arrow in policy file syntax.

• Added -dfv-> arrow in policy file syntax.

• Added -fv-> arrow in policy file syntax.

• Converted most U* attributes to variable length number format.

• Added the SIMPLE predefined policy file.

• Relaxed restriction on long lines in license files.

• Changes no longer classified as errors.

• Added +Z argument to CHECK command.

• Added MFlm attribute.

• Added command SELFTEST CLIPFILES.

• Released for Red Hat Linux.

Veracity V2.0 (01-May-1999)

As some customers wanted to store snapshot files as legal evidence for decades, it became clear that Rocksoft should publish a formal snapshot standard to which Veracity snapshot files would conform. The process of developing this standard prompted a total re-evaluation of the design of snapshot files, and the end result was the publication of two standards, the Rocksoft Text Tree Standard and the Veracity Snapshot Standard, which jointly formally defined an improved snapshot file format.



Veracity was then modified to conform to the new format. The fact that the changes were significant, and the fact that the new version of Veracity was the first to conform to a formal published snapshot standard, prompted an increase in the major version number, yielding Veracity V2.0. Here are (most) of the changes that were made:

• Veracity modified to read and write the new snapshot files.

• The syntax of policy files was modified slightly.

• Text files now normalized into Unicode form. This eliminated the potential EOL security problems of the T.* normalization mechanism of previous versions.

• Check records now use MD5 instead of SHA-1.

• Added the G (grade) argument to the snapshot and check commands.

• Now ignores unknown fields in records in snapshot files.

• Deleted ---> arrow from policy file syntax.

• Changed syntax of begin/end markers in policy files.

• Removed the quote-escape preprocessing of policy files.

• Snapshot files now contain their creation date and time.

• Made *.len attributes variable width.

• Added HEXV command.

• Added DAsb attribute. • MFlm now ignores bit 9 as well as bit 8.

• Changed UAtm, UMtm and UCtm attributes to variable-width format.

• Changed DAtm, DMtm and DCtm attributes to variable-width format.

• Changed MMtm, MCtm and MBtm attributes to variable-width format.

• Changed snapshot format of DLnu to Unicode.

• Changed Symlink attributes internal format to Unicode.

• Categorized all Unix non-content attributes as standard.

• Categorized all MS-DOS non-content attributes as standard.

• In symlink values, escaped commas with “\c” instead of “\,”.

• Changed Unix ACL attributes to Unicode representation.

• Changed NT attributes to Unicode representation.

• Added +SymLink to predefined policy file Security.



• Converted the Cycle attribute to Unicode. Defined as standard.

• Defined all OpenVMS file attributes as standard.

• The license file system was eliminated.

Veracity V2.0 cannot read the snapshot files generated by earlier versions of Veracity, just as earlier versions cannot read the snapshots of V2.0. However, Rocksoft asserts that all future versions of Veracity will be able to read and understand snapshots (of content DirectoryTree and of Common or Standard grade) written by previous versions of Veracity not earlier than V2.0. This assertion is a Veracity mission-critical goal, but should not be interpreted as a legal commitment by Rocksoft or associated entities.

This commitment to backwards compatibility means that users can archive snapshot files for many years, and be confident that the snapshots will still be readable by future versions of Veracity.

Known Problems/Bugs Of V2.0

V2.0 suffers from the following known problems:

• Writes snapshot Version field as 3.0 instead of 3.1.

• Does not eliminate / from platform names (e.g. HP/UX) in the Writer field of snapshot files, as required by the Rocksoft Text Tree Standard.

• Crashes during some long runs on Macintosh.

• On Windows NT, cannot read files whose names contain non-ASCII Unicode characters.

• Symlink attribute values may end with garbage characters on some Unix platforms.

This list of problems was compiled on 22 May 1999.

Veracity V2.0.1 (05-Jun-1999)

V2.0.1 is a maintenance release:

• Ported to NetBSD/i386.

• Snapshot Version field updated to 3.1.

• Eliminates / from platform names (e.g. HP/UX) in the Writer field of snapshot files, as required by the Rocksoft Text Tree Standard.

• The Macintosh crashes have been fixed.

• MBtm attribute now maps the 0 value to 01-Jan-1970.

• Fixed the SymLink attribute bug (garbage characters).

• Suppressed a console blank line that was being written under +q.



Known Problems/Bugs Of V2.0.1

V2.0.1 suffers from the following known problems:

• On Windows NT, Veracity V2.0.1 cannot read files whose names contain non-ASCII Unicode characters.

Veracity V2.1 (20-Jan-2000)

V2.1 is a general maintenance release that was ultimately never actually released. However, the changes made for this version appear in later versions, so they are listed here.

• Prepared the code for release as FreeVeracity.

• Revised the platform definitions in the source code.

• Added FREEV symbol so the code can be compiled as Veracity or as FreeVeracity.

• Added the freeveracity shell command.

• Now generates snapshot files that are 70 characters wide instead of 76 characters wide, so as to avoid problems with PGP.

• Added the case fuzzy filename matching scheme.

• Added +M argument to snapshot command.

• Improved leak detection in the main program.

• Added len_allow_increase pseudo attribute.

• Shortened snapshot, report and journal file header comments.

• The *.len attribute values are shown when changed.

• Added the saveclip shell command.

• Modified the security predefined policy file for GNU/Linux.

• Added an error message for -Cmypolicy.

• Added U slowdown argument to snapshot and check commands.



• On Windows NT, Veracity V2.1 cannot read files whose names contain non-ASCII Unicode characters.

Veracity V3.0 (10-Aug-2000)

V3.0 introduces a network client/server architecture that allows you to take snapshots of remote computers through a TCP/IP network. This is perhaps the most significant improvement ever made to Veracity; hence the major version number increment.



• Added network server functionality in the new server command.

• Added network client functionality to the existing snapshot command.

• Renamed N argument of snapshot and check commands to D

• Introduced new N network node argument of snapshot and check.

• The quiet option +Q now takes a numeric argument to say how quiet.

• Veracity now will refuse to read any file on the /proc device on Unix.

• Added a new predefined policy file structure.

• Added a new predefined policy file null.

• Added a new predefined policy file source.

• Added a new predefined policy file touch.

• Revised the security predefined policy file.

• Source is now gcc -Wall clean.

• Added -----<BeginSnapshot>----- etc markers in report files.

• Added new keyring command to manage client-side encrypted passwords.

• Created and bundled Agent Process PERL script snaplet.pl.

• Beta test versions now formally identified in startup banner.

• snapshot and check commands now prompt for snapshot passwords if empty.

• Renamed snapshot commandʼs +M argument to +K.

• Added new top-level argument +M (memory limit).



• On Windows NT, Veracity V3.0 cannot read files whose names contain non-ASCII Unicode characters.

Veracity V3.1 (16-Dec-2000)

V3.1 Adds new platforms HP-UX 11 and Compaq Himalaya OSS Non-Stop to the list of platforms that support the networking architecture. This version also fixes some outstanding bugs from previous versions:

• Snapshots can now be taken from the root directory of a disk.

• Policy Files are now more portable across systems using differing EOL formats.

• Standard policy files have been narrowed for more aesthetic PGP-encryption.



• Client server termination has been tidied up.

• URLs in help files and documentation have been updated.

• All documentation and intellectual property notices have been updated to reflect Rocksoftʼs transition to a public company.



As for V3.0.

Veracity V3.2 (03-January-2002)

V3.2 Introduces network functionality to the Windows range of platforms and to Mac OS X. As part of this effort, much of Veracity has been made more platform-independent. In particular, terminology has moved away from Unix-centric terms.

A brief list of new features is:

• Network server functionality added for all Windows platforms.

• Network server functionality added for Mac OS X.

• Server ids have been made case-dependent; mixed-case is allowed.

• An installer has been added for all Windows platforms.

• The Windows version runs as a service on Windows NT, 2000 and XP.

• The slash server has been renamed to the system server.

• The users_slash server has been renamed to the users_system server.

• The predefined server configuration files are platform-independent.

• The superuser account is referred to as root, Administrator or SYSTEM, as appropriate.

• The Veracity client makes no assumptions about directory path format of the Veracity server.



• On Windows NT, Veracity V3.2 on restarting as a service in interactive mode, generates gethostname errors but continues to work.

Veracity V3.3 (09-April-2002)

V3.3 Introduces the Blocklets file transfer protocol which can reduce network bandwidth between the monitor and the agent by several orders of magnitude.




• Blocklets and blocklets protocol added.

• Ctrl-C handler added for Windows 9x agents.

• New options for canonical output and for reference files added.

• ACLs added for Solaris.

• Previous problems with NTFS attributes fixed.

• Spaces now allowed in virtual agent names for Windows.

• New platforms Linux/AS-400 and Linux/Sparc added.

• Minor speed improvements.



• Blocklets protocol uses up a lot of memory at both Agent and Monitor ends.

• ‘veracity attrib ./filename’ causes a memory leak and abort.

Veracity V3.4 (14-January-2003)

V3.4 Adds the ʻRestoreʼ command to Veracity, allowing Veracity to repair file changes, not just detect them.


• RESTORE command added.

• Attributes for NTFS Alternative Data Streams added.

• +Q3 switch added.

• Clip files renamed to Policy files.

• Veracity agent code reorganized.



• Blocklets protocol uses up a lot of memory at both Agent and Monitor ends.

Veracity V3.4.1 (14-June-2003)

V3.4.1 Adds the GET command to Veracity along with other features to support network-based repair operations.



A brief list of new features is: • GET command added.

• Taking snapshots of snapshots is now possible.

• The RESTORE command now works across networks.

• Blocklets protocol now works correctly with files of arbitrary length.

• Snapshot fattening, SNAPSHOT +F, option added.



• Blocklets protocol will not work with files of arbitrary length.

Veracity V3.4.2 (14-June-2003)

V3.4.2 Adds a number of enhancements to improve the performance and flexibility of network repair operations.


• The LIST command was added.

• Trial version of Veracity with built in expiry created.

• New encryption algorithm AES-128 added.

• Large speed improvements have been made to network operations

• The CHECK +B option has been added

• SELFTEST sigspeed accuracy enhancements made for fast PCs

• SELFTEST compspeed and cryptspeed functions added.

• SELFTEST unit test functionality added.

• Added help pages for the SELFTEST, RESTORE and GET commands.

• Added the Adler32 signature algorithm

• The SERVER stop command now shuts down UNIX servers cleanly - i.e. waits for transactions to finish.

• The AGENT command added as an alias for SERVER.

• +U option for Windows now works.



• AllowWrite agent attribute added to configuration file

• +no_missing_directory_error attribute added

• Ported to Novell Netware 6.

• Ported to HP-UX Itanium.

• Sundry bug fixes



• None.

12.3 Veracity Quick ReferenceThis page contains a summary of the most important quick-reference information you need to run Veracity.

Basic Checkingveracity snapshot- Take a snapshot of the current tree.veracity check- Compare snapshot with current tree.

Snapshot And Signoffveracity snapshot- Take a snapshot of the current tree.veracity signoff - Report all changes since previous snapshot taken. (Compares snapshot file with previous snapshot file).

Comparing Thingsveracity check +1/abc/newtree/ +2/abc/oldtree/ - Compare tree with tree.veracity check -1newsnap -2oldsnap - Compare snap with snap.veracity check +1/abc/newtree/ -2oldsnap - Compare snap with tree.veracity check -1newsnap +2/abc/oldtree- Compare tree with snap.

Checking Heterogeneous Tree Transfersveracity snapshot +c_transfer - On the source machine.veracity check +f - On the destination machine.

Policy Filesveracity snapshot +c - Uses 0veracty.vpfveracity snapshot +c_transfer - For heterogeneous transfersveracity snapshot +c_skeleton - Records tree structure only.veracity snapshot +c_text - For a tree of text files.veracity snapshot +c_top- Top directory only.veracity snapshot +c_web- For checking webs.veracity snapshot +c_diff - Full differences.



=====(BeginClipListV1)=====“#*” -*-> +create +delete“#*” -s-> +SymLink“#*” -f-> +B.md5=====(EndClipList)=====

Veracity Files0veracty.vpf - Policyfile.0veracty.vsf - Snapshot file.0veracty.vbf - Backshot file.0veracty.vjf - Journal file.0veracty.vrf - Reportfile.0veracty.vxf - Shell file.

12.4 Supported PlatformsVeracity is available for the following platforms:

• MS-DOS

• Win32 (Windows 95/98/ME and NT/2000/XP)

• Macintosh OS X

• OpenVMS VAX

• OpenVMS Alpha

• Digital Unix

• IRIX

• HP/UX

• Compaq Himalaya OSS

• Novell Netware 6 SP3

• SunOS

• Solaris

• AIX

• Linux

• Linux Sparc

• Linux AS-400

• BSD/OS

• FreeBSD

• NetBSD

• OpenBSD



12.5 User LicenceRocksoft Software Licence Agreement

Version 2 (1 February 2002) -- International

IMPORTANT: THIS IS A LEGAL AGREEMENT BETWEEN YOU AND ROCKSOFT LIMITED AND SHOULD BE READ CAREFULLY BEFORE USING THE SOFTWARE. BY UNSEALING THE MEDIA SEAL (IF ANY) OR BY READING, COPYING, OR USING THE SOFTWARE OR ASSOCIATED DOCUMENTATION IN ANY WAY, YOU ACKNOWLEDGE THAT YOU HAVE READ THIS ENTIRE LICENCE AGREEMENT, UNDERSTAND IT, AND AGREE TO BE BOUND BY ITS TERMS AND CONDITIONS. IF YOU DO NOT AGREE TO THE TERMS AND CONDITIONS OF THIS AGREEMENT, RETURN THE PACKAGE WITH PROOF OF PURCHASE AND WITH THE MEDIA SEAL (IF ANY) UNBROKEN WITHIN THIRTY (30) DAYS OF THE DATE OF DELIVERY TO THE PLACE WHERE YOU OBTAINED IT FOR A FULL REFUND.

Note: Important exclusions and disclaimers are contained in sections 8, 9 and 10 below.

1 Definitions

1.1 Rocksoft is the company Rocksoft Limited, Adelaide, Australia (Australian Company Number (ACN) 008 280 153).

1.2 The Licensee is the individual or organisation that has legitimately obtained a licence for a Rocksoft software product. This document is written as if the reader is the Licensee, and all references to “you” refer to the Licensee.

1.3 The Licence Fee is the amount (if any) paid by the Licensee to a Representative in consideration of the grant of this Licence.

1.4 The term Representative means only those persons or organisations expressly authorised by Rocksoft to be involved in the creation, production, delivery, or licensing of the Software, and includes, but is not limited to: Rocksoft, employees and authorised agents of Rocksoft, Rocksoft’s authorised distributors and sub-distributors, and their employees and authorised agents.

1.5 The Seller is the Representative who sold the Product to you.

1.6 The Product is the Rocksoft software product that is identified by the packaging, invoice, or delivery docket accompanying the Product, or is in some other way identified during the transaction between you and the Seller. The Product consists of the Software, the Documentation, packaging, and other supporting materials.

1.7 The Software is the machine-readable component of the Product, consisting of information stored on any media or transmitted through a network, including all revisions enhancements or updates to that software supplied to you pursuant to the provisions of this Agreement.

1.8 The Documentation is the printed material supporting the Software.

1.9 The term media refers to floppy disks, CD-ROMs, and any other physical media capable of holding or storing a copy or representation of the Software.

1.10 A media action is any physical action that must be performed by a human to change the accessibility of software on a media with respect to one or more computers. Examples of media actions are inserting a disk into a disk drive, and removing a disk from a disk drive.

1.11 A working copy of a piece of software is any copy that is configured in such a way that it is available to one or more computers without first requiring any media action.



1.12 A backup copy of a piece of software is any copy that is configured in such a way that it can’t be accessed by any computer without some media action having to be performed first. Note: As soon

as a backup copy becomes available without first requiring any media action, to one or more computers, the copy becomes a working copy.

Similarly, a working copy that is reconfigured in such a way that it can’t be accessed by any computer without some media action having to be performed first, becomes a backup copy.

1.13 A piece of software is defined to be exposed to a particular computer if the software can be run on the computer by users of the computer (or by users of other computers) without “significant barriers” such as having to supply a password not known to them.

1.14 N is a parameter of the Product/Licence called the “number of computers” (or any other sensible phrase that denotes quantity with respect to the Licence). This value defines the maximum number of specific computers that can be designated as “registered” for use with the Software. N is not specified in this Agreement, but should be defined by the Seller and should appear as part of the customer invoice or delivery docket. In the event that no N has been specified in writing by the Seller, and no N is specified on the product packaging, N is defined to be one (1).

1.15 The Date of Delivery refers to the date upon which the Licensee took delivery of the Software. This will usually be the date on the delivery docket. In the case of an “over-the-counter” retail sale, the date of delivery is the purchase date as evidenced by the purchase receipt. There shall be only one delivery date in relation to each Licence, notwithstanding any subsequent transfer of the Software.

2 Framing

2.1 Licence: In consideration of your payment of the Licence Fee and your agreement to abide by the terms and conditions of this Agreement, Rocksoft grants you a non-exclusive licence to use the Software on the terms and conditions contained in this Agreement.

2.2 Free Licences: Where you have legitimately obtained a copy of the Software from a Representative or any other person without being required to pay a Licence Fee (which includes, without limitation, experimental, beta test, and demonstration copies of the Software), in consideration of the grant of this Licence, you agree to comply with the provisions of this Agreement and to send an email message to [email protected] within 30 days, providing feedback on the product. Such “free” Licences are otherwise identical to other Licences except that Rocksoft reserves the right not to provide the support and updates specified under Section 7 of this agreement.

2.3 Licensed Not Sold: The Software is licensed, not sold, to you for use only under the terms and conditions of this Agreement, and Rocksoft reserves all rights not expressly granted to you. You own all the physical materials that carry the Software and Documentation (e.g. CD-ROMs and paper upon which the manuals are printed), but you obtain no title or ownership with respect to all copies of the Software and Documentation and the confidential information contained within the Software and Documentation.

2.4 Right To License: Rocksoft warrants that it has sufficient rights to the Software to license it to you.

2.5 Suggestions: Where you have made a suggestion or recommendation (in relation



to the Software or otherwise) to Rocksoft or its Representatives, you hereby grant Rocksoft a licence (free of charge to Rocksoft) to use that suggestion or recommendation in any way it so chooses.

3 Licence

Providing that you maintain a written record, associated with this Licence, that clearly identifies a set of at most N registered computers (of any hardware and software combination) owned or controlled (e.g. rented) by you, then this Licence allows you to:

3.1 N Copies: Create and maintain up to N working copies of the Software.

3.2 Use Per Computer: Use, and permit other parties to use, the Software on each of the registered computers only, with no limit applying to the number of users who can be running the Software on each registered computer, nor to the number of copies of the Software that can be simultaneously executing on each registered computer.

3.3 Backup Copies: Create and maintain backup copies of the Software, provided that each backup copy is created and used solely for the purpose of replacing working copies of the Software in the event that a working copy of the Software is damaged or destroyed.

3.4 Licence Transfer: Transfer the Software and this Agreement, including its rights, obligations, and history with respect to Rocksoft and its Representatives, to another party provided that

1) the other party reads and agrees to the terms and conditions of this Agreement, and

2) at the commencement of the transfer process you cease to be licensed to use the Software for any purpose except to the extent necessary to complete the transfer of the Software and this Agreement, and

3) written notice is given by you to Rocksoft of the name and address of the transferee and

4) at the end of the transfer process the transferor must destroy all remaining copies of the Software and Documentation that the transferor controls, whether or not they conform to the terms and conditions of this Agreement.

Following transfer, the transferor will cease to have any of the rights granted under this Agreement but the provisions of Section 6 below shall apply to the transferor as if the Agreement had been terminated.

4 Restrictions

4.1 Copy Restriction: Subject to Section 3 above, you may not copy, modify, network, copy through a network, lease, rent, grant sublicences or other rights in the Software, distribute, loan, translate, create derivative works, or provide use of the Software in a computer service business, or in any other way, directly or indirectly cause the creation, or encourage the creation, of copies, or derivative works, of the Software (or any part of it).

4.2 No Software Exposure: Subject to Section 3 above, you may not expose the Software to computers that are not owned or controlled by you, or in any other way assist others directly or indirectly to make copies of the Software (or any part of it). In particular, you may not expose the Software to a network containing computers not owned or controlled by yourself.



4.3 No Removal Of Notices: You may not remove any notice of proprietary rights (i.e. notices of copyright, patent, trademark, trade name) from any part of the Product.

4.4 No Disassembly: You agree that the Software may contain copyright material, trade secrets, and other proprietary material and that you must not decompile, disassemble, reverse engineer, or otherwise transform the Software to a form more humanly understandable than that in which the Software was provided to you by Rocksoft.

4.5 Confidentiality: You agree that the Software may contain confidential information and that you must not divulge, directly or indirectly, any such confidential information to any person, unless and until such confidential information ceases to be confidential for any reason not resulting from your own actions. You acknowledge that non-confidential information may still be subject to copyright restrictions.

4.6 No Implicit IP Rights: This Agreement does not grant you any rights to copyright, patents, trade secrets, trade names, trademarks (whether registered or unregistered), or any other rights, franchises, or licences (apart from the express Licence granted by this Agreement) in respect of the Software.

4.7 Multiple Media: If the Software has been provided to you on more than one kind of media (e.g. CD-ROM as well as by FTP) this has been done solely to facilitate installation, and does not constitute a widening of this Licence. In particular, it does not constitute an increase in N.

4.8 Erasure Of Beta Versions: If, for whatever reason, you are provided with an experimental version of the Software (which includes, without limitation, a beta test version of the Software) by Rocksoft, then you agree to delete/erase that version of the Software within the time limit specified by Rocksoft, or, where no time limit is specified, then within one month of receiving the particular version of the Software.

4.9 Licensing System: You agree not to interfere with or obstruct, or attempt to interfere with or obstruct, the functioning of any automatic licensing system/mechanism incorporated in or applied to the Software by Rocksoft. This includes any software or hardware to prevent the use of the Software in breach of this Agreement.

5 U.S. Government Use

If you are acquiring the Software on behalf of any unit or agency of the United States Government (USG), the following provisions apply.

You agree on behalf of the USG that:

5.1 Privately Developed: Rocksoft asserts that the Software has been developed entirely at private expense, and that no part of it was developed using USG funds.

5.2 Software A Trade Secret: Rocksoft asserts that the Software may be deemed a trade secret of Rocksoft for all purposes, including for the purpose of the USG Freedom of Information Act.

5.3 Classified As Commercial: If the Software is supplied to the USG Department of Defense (USGDoD), the Software is classified as “Commercial Computer Software”, and the USG is acquiring only “restricted rights” in the Software as that term is defined in clause 52.227-7013(c)(1) of the USGDoD Federal Acquisitions Register (DFARS).

5.4 Restricted Rights: If the Software is supplied to any unit or agency of the USG other than USGDoD, the USG is acquiring only “restricted rights” as that term is defined in clause 52.227-19(c)(2)

of the Federal Acquisitions Register (FAR), or, in the case of NASA, in clause 18-52.227-86(d) of the NASA supplement to the FAR.



6 Termination

6.1 Effective Until Terminated: This Agreement is effective until terminated. The Agreement will terminate if you fail to comply with the provisions of this Agreement or if you choose to terminate the Agreement at any time and provide Rocksoft written notice of such termination. There are no other conditions that will trigger termination.

6.2 Destroy All Copies: Upon termination of this Agreement for any reason, you must destroy the distribution copies of the Software and all copies derived from them, whether or not they comply with the provisions of this Agreement.

6.3 No Right To Refund: Upon termination of this Agreement for any reason, you shall have no right to refund of the whole or any part of any Licence Fee or other amount you have paid for the product.

6.4 Surviving Clauses: Upon termination of this Agreement for any reason, you shall continue to be bound by the provisions of Sections 4, 7.5, 8, 9 and 10 of this Agreement.

6.5 Relicensing: Rocksoft and its Representatives reserve the right to refuse to re-license the Software to you following termination.

6.6 No Prejudice: Termination will be without prejudice to any rights Rocksoft may have as a result of breach of this Agreement.

7 Support And Updates

7.1 Free Support For One Year: During the single calendar year (your “Support Year”) whose first day is the Date Of Delivery, Rocksoft or its Representatives will provide you, free of charge, with technical support in the installation and use of the Software and all updates to the software shipped by Rocksoft during that year.

7.2 Support Only For Latest Version: Rocksoft reserves the right to

refuse to provide support for any but the most recently released version of the Software.

7.3 Updates Have Backup Copy Status: Updates are covered by this Agreement, are deemed to form part of the Software, and have the status of backup copies (from which you may refresh working copies at your leisure).

7.4 Registration: In order to claim your rights under 7.1 or 7.2, you must first register as a “registered user” of the Software by providing Rocksoft with at least the following information: your name, your postal address, your email address, any information requested by Rocksoft to identify the product (e.g. the product name and serial number), and the identity of the Seller.

7.5 Updates Destroyed After Termination: If you receive an update for the Software after this Agreement has terminated, you must destroy the update and notify Rocksoft.

8 LIMITED WARRANTY

8.1 MEDIA WARRANTY: ROCKSOFT WARRANTS THE MEDIA UPON WHICH THE SOFTWARE IS PROVIDED TO YOU TO BE FREE FROM DEFECTS IN MATERIALS AND WORKMANSHIP UNDER NORMAL USE FOR A PERIOD OF THIRTY (30) DAYS FROM THE DATE OF DELIVERY, AND DURING THIS PERIOD, UPON PROOF OF PURCHASE, THE SELLER OR ROCKSOFT WILL EXCHANGE DEFECTIVE MEDIA AT NO CHARGE TO YOU.

FOR THIS WARRANTY, THE ENTIRE LIABILITY OF ROCKSOFT AND THE REPRESENTATIVES, AND YOUR EXCLUSIVE REMEDY, IS THE EXCHANGE OF THE DEFECTIVE MEDIA FOR MEDIA WHICH IS FREE FROM DEFECTS.



8.2 IMPLIED WARRANTIES: TO THE EXTENT PERMITTED BY LAW, ANY EXPRESS OR IMPLIED WARRANTIES ON THE MEDIA, INCLUDING IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE LIMITED IN DURATION TO THIRTY (30) DAYS FROM THE DATE OF DELIVERY.

9 DISCLAIMER OF ADDITIONAL WARRANTIES ON THE SOFTWARE

9.1 NO WARRANTIES: TO THE FULL EXTENT PERMITTED BY LAW, ROCKSOFT

HEREBY EXCLUDES ALL CONDITIONS OR WARRANTIES, WHETHER IMPOSED BY STATUTE OR BY OPERATION OF LAW OR OTHERWISE, NOT EXPRESSLY SET OUT HEREIN. TO THE FULL EXTENT PERMITTED BY LAW, ROCKSOFT MAKES NO EXPRESS OR IMPLIED WARRANTIES OR CONDITIONS INCLUDING, WITHOUT LIMITATION, THE WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, WITH RESPECT TO THE SOFTWARE.

9.2 SOFTWARE PROVIDED “AS IS”: ROCKSOFT DOES NOT WARRANT THAT THE SOFTWARE WILL MEET YOUR REQUIREMENTS OR THAT ITS OPERATION WILL BE UNINTERRUPTED OR ERROR-FREE, OR THAT DEFECTS IN THE SOFTWARE WILL BE CORRECTED. THE SOFTWARE IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND. ROCKSOFT DOES NOT WARRANT, GUARANTEE, OR MAKE ANY REPRESENTATIONS REGARDING THE USE, OR THE RESULTS OF USE, OF THE SOFTWARE WITH RESPECT TO ITS CORRECTNESS, ACCURACY, RELIABILITY, CURRENT RELEASE STATUS, OR OTHERWISE.

9.3 ENTIRE RISK ASSUMED BY YOU: THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF THE SOFTWARE IS ASSUMED BY YOU. IF THE SOFTWARE IS DEFECTIVE, YOU, (AND NOT ROCKSOFT OR ITS REPRESENTATIVES) ASSUME THE ENTIRE COST OF ANY SERVICING, REPAIR, OR CORRECTION THEREOF.

9.4 NO INCREASE IN WARRANTY SCOPE: NO ORAL OR WRITTEN INFORMATION OR ADVICE GIVEN BY ROCKSOFT OR ITS REPRESENTATIVES SHALL CREATE A WARRANTY OR IN ANY WAY INCREASE THE SCOPE OF THIS WARRANTY. YOU MAY NOT RELY ON ANY SUCH INFORMATION OR ADVICE AND YOU HEREBY ACKNOWLEDGE THAT YOU HAVE NOT RELIED UPON SUCH INFORMATION OR ADVICE.

10. LIMITATION OF LIABILITY

10.1 NO LIABILITY: TO THE FULL EXTENT PERMITTED BY LAW, IN NO EVENT SHALL ROCKSOFT BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT, OR CONSEQUENTIAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, AND LOSS OF BUSINESS INFORMATION OR SOFTWARE), EVEN IF ROCKSOFT OR ONE OR MORE OF ITS REPRESENTATIVES HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES AND WHETHER ARISING FROM BREACH OF THIS AGREEMENT, TORT (INCLUDING NEGLIGENCE), BY OPERATION OF LAW OR OTHERWISE HOWSOEVER.

10.2 NO EXCLUSION OF STATUTORY RIGHTS: NOTHING IN THIS AGREEMENT, AND IN PARTICULAR CLAUSE 10.1, IS INTENDED OR SHALL BE CONSTRUED AS EXCLUDING OR MODIFYING ANY STATUTORY RIGHTS, WARRANTIES, OR CONDITIONS WHICH ARE APPLICABLE TO THIS AGREEMENT OR THE SOFTWARE SUPPLIED HEREUNDER, AND WHICH BY VIRTUE OF ANY NATIONAL OR STATE FAIR TRADING, TRADE PRACTICES, OR OTHER LEGISLATION OR LAW MAY NOT BE MODIFIED OR EXCLUDED. HOWEVER, WITHIN THESE CONSTRAINTS, THE PROVISIONS OF THIS CONTRACT (AND IN PARTICULAR CLAUSE 10.1) SHALL STAND AS STRONGLY AS PERMITTED BY THE LAW. IN PARTICULAR, IF THE WARRANTY EXCLUSION PROVISIONS OF CLAUSE 10.1 ARE WEAKENED IN LAW SO THAT SOME FORM OF WARRANTY IS CONSIDERED IN LAW TO EXIST, TO THE FULL EXTENT PERMITTED BY LAW, ROCKSOFT’S LIABILITY FOR ANY BREACH OF ANY SUCH WARRANTY SHALL BE AND IS HEREBY LIMITED TO THE AMOUNT PAID BY YOU FOR THAT PART OF THE PRODUCT SUPPLIED BY ROCKSOFT HEREUNDER WHICH CAUSED THE DAMAGES OR THAT IS THE SUBJECT MATTER OF, OR IS DIRECTLY RELATED TO, THE CAUSE OF ACTION.

10.3 NO DIRECT OR CONSEQUENTIAL DAMAGES: LICENSEE ACKNOWLEDGES THAT THE SOFTWARE COULD CONTAIN ERRORS THAT RESULT IN THE SOFTWARE FAILING TO NOTIFY THE USER OF A



CHANGE, OR PRONOUNCING DATA AS UNCHANGED WHEN IT IS CHANGED AND VICE VERSA. LICENSEE ASSUMES THE ENTIRE RESPONSIBILITY FOR ANY DIRECT AND CONSEQUENTIAL DAMAGES RESULTING FROM SUCH ERRORS, INCLUDING DIRECT AND CONSEQUENTIAL DAMAGES OF LOSS OF DATA.

10.4 LIABILITY BOUNDED BY PURCHASE PRICE: IN NO EVENT WILL ROCKSOFT’S TOTAL LIABILITY TO YOU FOR DAMAGES, LOSSES, AND CAUSES OF ACTION (WHETHER ARISING FROM BREACH OF THIS AGREEMENT, TORT (INCLUDING NEGLIGENCE), BY OPERATION OF LAW OR OTHERWISE HOWSOEVER) EXCEED THE AMOUNT PAID BY YOU FOR THE PRODUCT.

11 General

11.1 Arbitration: Any disputes arising in connection with this Agreement, which cannot be settled by negotiation between the parties or their representatives, shall be submitted to arbitration in accordance with the Rules for the Conduct of Commercial Arbitrations of the Institute of Arbitrators, Australia. During such arbitration, both parties may be represented by a duly qualified legal practitioner.

11.2 Laws Of South Australia: This Agreement will be construed under the laws of South Australia except for that body of law dealing with conflict of law; Licensee consents to jurisdiction in the state and federal courts located in the state of South Australia.

11.3 Entire Agreement: This Agreement contains the entire Agreement between the parties hereto with respect to the subject matter hereof, and supersedes all prior agreements and/or understandings (oral or written). Failure or delay by Rocksoft in enforcing any right or provision hereof shall not be deemed a waiver of such provision or right with respect to the instance or any subsequent breach. If any provision of this Agreement shall be held by a court of competent jurisdiction to be contrary to law, that provision will be enforced to the maximum extent permissible, and the remaining provisions of this Agreement will remain in full force and effect.

11.4 Trademarks: Rocksoft and Veracity are registered trademarks of Rocksoft Limited.

-- 0 --

Should you have any questions about this Agreement, or if you wish to contact Rocksoft for any reason, please contact

Rocksoft LimitedPO Box 3066Rundle Mall SA 5000Australia

[email protected]. 008 280 153

-- End of Agreement --

12.6 AES LicenceThis software includes an implementation of the AES encryption algorithm based on code released by Dr Brian Gladman under the following licence.

Copyright (c) 2001, Dr Brian Gladman <[email protected]>, Worcester, UK. All rights reserved.



LICENSE TERMS

The free distribution and use of this software in both source and binary form is allowed (with or without changes) provided that:

1. distributions of this source code include the above copyright notice, this list of conditions and the following disclaimer;

2. distributions in binary form include the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other associated materials;

3. the copyright holderʼs name is not used to endorse products built using this software without specific written permission.

DISCLAIMER

This software is provided ʻas isʼ with no explicit or implied warranties in respect of its properties, including, but not limited to, correctness and fitness for purpose.

12.7 PatentsVeracity is protected by the following two US Patents.

US Patent #5,737,594 (Fuzzy Matching)

This patent covers Veracityʼs “fuzzy filename matching” algorithm which Veracity uses to match up the files in pairs of directories whose filenames differ in minor ways.

Title: Method for matching elements of two groups.

Abstract: A method for matching-elements of two groups of data objects whose elements do not necessarily exactly match. The method consists of examining successively more abstract projections of the two groups until exact matches occur within elements of the same group, or between elements of the different groups or until there are no longer any more abstract projections to apply. Both random access end sequential embodiments are described.

For more information, you can browse the full text of this patent which is available online at the Delphion patent web.

US Patent #5,822,746 (Cliplist Execution)

This patent covers the execution of cliplists.

Title: Method for mapping a file specification to a sequence of actions.

Abstract: A method for mapping a file specification to a sequence of zero or more actions. A file specification consists of any finite string of bits that provides information about the identity of a file in a computerʼs file system. An action can be any process that effects a change upon the computer system containing the file. The mapping method involves sequentially applying a list of pattern/action rules, with each ruleʼs action being executed if the ruleʼs pattern matches the file specification. Upon completion, the series of actions that has been executed is the sequence of actions corresponding to the file specification.

For more information, you can browse the full text of this patent which is available online at the Delphion patent web.



13 InstallationThis section contains instructions on how to install Veracity.

13.1 Installing VeracityTo install and run Veracity on your computer, you will need:

• A Veracity distribution archive file.

• At least two megabytes of free disk space.

• About twenty minutes. If you are reading this web page offline and you donʼt have a Veracity distribution archive file, then you may need to go online and visit the Veracity web to obtain one.

13.2 Step 1: Unpack The Distribution FileBy now, you should have FTPed a Veracity distribution file. You should either have a Veracity executable, or a Veracity distribution file (e.g. .zip, .hqx). If you have a distribution file, you will need to unpack it as explained below.

Veracity is shipped as a single archive file for most platforms, or as a self-installing .exe for Windows. Here are examples of how to unpack Veracity on various kinds of platform. The V characters stand for the Veracity version number.

Win95/98/ME : Run Veracity Setup and follow the instructions.WinNT/2K/XP : Run Veracity Setup and follow the instructions.MS-DOS: pkunzip -d veravVVV.zipMac OS: Drop veracity_vVVV_mac.hqx onto Stuffit Expander.Mac OS X : tar -xf veracity_vVVV_macosx.tarUnix : tar -xf veracity_vVVV_solaris.tarOpenVMS : unzip veracity_vVVV_vmsalpha.zip (OpenVMS Alpha) unzip veracity_vVVV_vmsvax.zip (OpenVMS VAX)Netware : unzip veracity_vVVV_netware.zip

Note: The “Win32” version of Veracity runs on both Windows 95/98/ME and Windows NT/2000/XP.

If all goes well, a small directory tree called “veracity” (or another name that you have specified) will be created. The directory tree should look something like this:

veracity - The Veracity directory.0readme.txt - The readme.0veracty.vsf - A snapshot file covering these files.veracity[.exe] - The Veracity executable.veracity_licence_v1.txt - The user licence.

The Windows distribution will also contain: unins000.exe - The Veracity uninstall executableunins000.dat - The Veracity uninstall data file

and optionally (for Windows NT, 2000 and XP):



vserve.exe- The Veracity service executable

The Novell Netware distribution will contain: veracity.nlm - The Veracity NLM

If it has not been placed by Veracity Setup, move the freshly unpacked Veracity directory to a permanent place on your disk. You can place the Veracity directory anywhere you like. Here are some suggested places:

Win95/98/ME : No action required.WinNT/2K/XP : No action required.MS-DOS: C:\VERACITY\Mac OS: HardDisk:Veracity:Mac OS X : /usr/local/bin/veracityOpenVMS : SYS$SYSDEVICE:[VERACITY]Unix : /usr/local/bin/veracity/Netware : sys:\system\

Warning: Do not rename the Macintosh version of Veracity to a name that contains a space (or the part of the name after the space will be treated as the first command line argument!).

Unpacking Utilities

Hereʼs where to find the unpacking utilities. If you canʼt access these servers, try doing an Archie search for files of similar names to find copies on other servers. Theyʼre everywhere.

Win95/98/ME : http://www.winzip.com/WinNT/2K/XP : http://www.winzip.com/MS-DOS: ftp://cs.nyu.edu/pub/local/porter/pkunzip.exeMac OS: ftp://ftp.amug.org//pub/info-mac/cmp/ stuffit-expander*.hqxMac OS X : The tar command is part of Mac OS X.OpenVMS : ftp://ftp.wku.edu/vms/unzip.vax _ exe: ftp://ftp.wku.edu/vms/unzip.alpha _ exeUnix : The tar command is part of Unix.Netware : unzip should already be present in Novell Netware 6.

Veracity is sometimes also shipped as a collection of executables along with the files 0readme.txt and veracity_licence_v1.txt. In that case, you wonʼt have to unpack anything.

13.3 Step 2: Install The Veracity ExecutableMake the Veracity executable available for execution in your shell (as the command “veracity”) by either defining a symbol for it or placing the executable in the “path”. Here are some examples of how to do this:

Win95/98/ME : SET PATH=%PATH%;C:\VERACITYWinNT/2K/XP : SET PATH=%PATH%;C:\VERACITYMS-DOS: PATH=%PATH%;C:\VERACITYMac OS: No action required.Mac OS X : as for Unix.OpenVMS : veracity == “$sys$sysdevice:[veracity]veracity.exe”Unix : alias veracity /usr/local/bin/veracity/veracityor Unix : set path=($path /usr/local/bin/veracity)



Put the definition in an appropriate login script (e.g. AUTOEXEC.BAT, .login, LOGIN.COM) so that the veracity command will be available next time you log in.

13.4 Step 3: Set ProtectionsUnder some operating systems, you should check to ensure that the Veracity directory and the files it contains have their protections properly configured. We have endeavored to generate distribution files that do this automatically, but you should check the protections too. Here are some examples of how to set the protections correctly.

Win95/98/ME : No action required.WinNT/2K/XP : If Veracity is to be run as a service, the user or group that is to run the service must be given the user rights: Act as part of the operating system Increase quotas Replace a process level token Under WinNT, this can be achieved using the ‘User Manager’ under ‘Administrative Tools’; and under Windows 2000, by using ‘mmc’ and selecting Security Templates->Setup Security-> Local Policies->User Rights Assignment’MS-DOS: No action required .Mac OS: No action required (unless installing an agent).Mac OS X : As for Unix.Unix : chmod go=rx /usr/local/bin/veracity chmod go=r /usr/local/bin/veracity/* chmod go=x /usr/local/bin/veracity/veracityOpenVMS : set prot=(s:rwed,o:rwed,g:r,w:r) sys$sysdevice:[000000]veracity.dir set prot=(s:rwed,o:rwed,g:e,w:e) veracity.exe set prot=(s:rwed,o:rwed,g:r,w:r) veracity_licence_v1.txt

Itʼs OK to configure the protections so that everyone using the machine can see the Veracity directory and use Veracity, but please ensure that the directory is not exposed to the Internet.

13.5 Step 4: Test The InstallationVeracity should now be installed. To ensure that it is, log out and in again (so as to test the definition in your login script too), set the current directory to anywhere thatʼs not the Veracity directory, and give the command

veracity

from the command line. Under Windows, you will have to select the ʻMS-DOS Command Promptʼ, which is usually found under the ʻProgramsʼ or ʻAccessoriesʼ menu. If your version of Windows does not have the MS-DOS icon (e.g. Windows 2000) you can select ʻStart->Runʼ and type ʻcmd.exeʼ.

Veracity should generate a friendly help message. If it does, then itʼs correctly installed. Congratulations!

Email [email protected] if you encounter any problems.

The next page contains a quick guided tour that shows you how to run Veracity.



13.6 Step 5: Running VeracityNow that you have installed Veracity, you can run it. Veracity is a very flexible tool that can be used in many different ways. Here we describe how to take a snapshot of a directory tree and use it to check the directory tree later.

Note: Veracity does not yet have a GUI. As such Veracity should always be run from your computerʼs command language (e.g. DOS shell, Unix shell, Mac OS X terminal, Netware Console, OpenVMS DCL).

Snapshotting A Directory Tree

To take a snapshot of a directory tree, go to the directory that is the top of the tree and give the command:

veracity snapshot

Note: Macintosh users (prior to Mac OS X) must actually move the Veracity application file into the directory at the top of the tree, and then double click on it and type the command snapshot.

It is recommended that you choose a small tree for your first Veracity run, as large trees can take a while.

Veracity will scan the tree and generate the following text files: 0veracty.vsf - The snapshot file.0veracty.vrf - The report file.0veracty.vbf - Previous version ofsnapshot (if any).

If there were any problems, they will be listed on the console and in the report file.

Checking A Directory TreeGo to the top of the tree (where you left a 0veracty.vsf file) and give the command:

veracity check

Veracity will read the snapshot file, scan the tree, and report any changes it finds in the tree (since the snapshot was taken) to the console and to the report file 0veracty.vrf.

Important: By default, Veracity stores and checks only the structure of the tree and the cryptographic hashes of the files in the tree. Veracity is certainly capable of monitoring all file attributes, but you have to use different settings (e.g. the security predefined policy file).

Thatʼs all there is to it!

The Next Step

This has been an extremely brief introduction whose purpose was just to get you started. Please do not assume the above is all there is to Veracity; itʼs far more powerful than this. For example, Veracity can monitor all file attributes. To learn about Veracityʼs powerful features and applications, you are strongly advised to visit the Veracity Tutorial Manual FreeVeracity Tutorial Manual and work through the introductory tutorial. The tutorial manual also contains detailed information about how to apply Veracity in various applications.



13.7 Windows InstallationThe Windows installation is handled by the Windows Installer program, setup.exe. The sequence of steps to follow is largely self-explanatory.

If Veracity is to be run as a service under Windows NT/2000/XP, the user or group that is to run the service must have previously been given the user rights:

Act as part of the operating systemIncrease quotasReplace a process level token

Under WinNT, this can be achieved using the ʻUser Managerʼ under ʻAdministrative Toolsʼ; and under Windows 2000, by using ʻmmcʼ and selecting Security Templates->Setup Security-> Local Policies->User Rights Assignmentʼ.

Now start the installation:

Double-click on setup.exe to invoke the installer. Shut down other running applications and click ʻNextʼ.

Read the licence agreement carefully and click ʻYesʼ if you accept the terms.

Select a folder where you would like Veracity installed. The default location is C:\veracity. If you prefer another location, browse to it and select. When you are satisfied with the location, click ʻNextʼ.

Select whether you want Veracity installed as a service under Windows NT/2000/XP. Under Windows 95/98/ME this is not an option. When you are satisfied with your selection, click ʻNextʼ.

Select the name of the shortcut to be added to the Start Menu folder. If you click in the checkbox, no icons will be created. When you are satisfied with your selection, click ʻNextʼ.

Review your decisions and click ʻInstallʼ if you are happy with the proposed configuration.

Wait a moment while Veracity is installed.

Enter and confirm the password for the Veracity agent that will run on the computer, and click ʻOKʼ. This password will be stored in encrypted form and will allow Veracity to be restarted as a service after each reboot. If you do not wish a password to be stored, click ʻNo Stored Passwordʼ. In this case, the Veracity agent will prompt for a password after each reboot and will not run until the password is entered.

Take a moment to read the 0readme file for the latest information. Click ʻNextʼ when you have finished.

By default, Veracity will start as a service immediately under Windows NT/2000/XP. If you do not wish the service to start immediately, then deselect the checkbox. When you are happy with your selection, click ʻFinishʼ.

The Veracity installation is complete!



13.8 VServeVserve is the Windows installer executable that is part of the Windows NT, 2000 or XP distribution. It is used by the installer to install Veracity as a service under Windows. The user would not normally need to run vserve directly except to uninstall Veracity manually or to change agent configuration files without uninstalling.

There are 3 invocations of vserve:

1) To install: vserve.exe -install c:\full\path\veracity.exe <start args> [SHA-hash]

Where <start args> is typically “agent start _config_file” (i.e., you pass vserve a typical, DOS window command line).

When installing (i.e. the ʻ-installʼ options is present), vserve.exe scans all its arguments for a SHA hash. If not present, vserve.exe prompts for a password regardless of whether one is required for the provided configuration file. (This is because typically, only the installer (setup.exe) invokes vserve.exe with the ʻ-installʼ option, and it always passes vserve.exe the _system configuration file).

The installer (setup.exe) invokes Veracity with the following command line: vserve.exe <path2veracity> agent start _system

(which implies that vserve.exe will always bring up the password dialog).

If vserve is invoked with *no* arguments at all, vserve.exe defaults to the following: vserve.exe c:\veracity\veracity.exe agent start

If the pathname of the Veracity executable (vserve.exe) contains spaces, vserve.exe concatenates arguments until they form a valid pathname that points to an executable file. Failure to construct a sensible pathname before running out of arguments causes vserve.exe to issue a warning and default to c:\veracity\veracity.exe.

NOTE: if the pathname to the Veracity binary contains >1 consecutive whitespace characters, vserve.exe will fail to find the Veracity binary. Vserve.exe concatenates arguments with only a single whitespace character.

2) To remove: vserve.exe -remove

No arguments are required. Vserve.exe automatically attempts to stop the service (and prints a diagnostic stating its success), before removing all registry entries from the registry. The setup.exe uninstaller takes care of removing the actual Veracity files.

3) To change the name of the configuration file: vserve.exe -config [-interactive]

Vserve checks that the name of the configuration file <config_file> exists, and goes through the concatenation of arguments process if the pathname of the configuration file contains whitespace (the same algorithm is used as for the location of the Veracity executable during



installation). If Veracity can not ultimately locate the configuration file, it exits with an error. None of the registry entries are changed in the event of this error.

The ʻ-interactiveʼ flag dictates whether vserve runs Veracity in a DOS console on the userʼs display, or whether it runs Veracity silently (invisibly). The interactive flag should be used when the configuration file requires Veracity to prompt the user for a password upon starting. Failure to specify the ʻ-interactiveʼ flag when the provided configuration file requires a password will cause the service to ʻhangʼ on startup.

Vserve.exe recognizes its four internal configuration files (_system, _users, _users_system, _single_user) and sets the interactive flag accordingly. When specifying the name of an internal configuration file, the ʻ-interactiveʼ flag can be used to ensure that Veracity always runs in a foreground window, but omitting the ʻ-interactiveʼ flag will have no effect if the predefined configuration file requires a password to be entered upon startup.



Action

In the context of Veracity, the term “action” is usually used to refer to a list of attributes specified on the right hand side of a policy file rule.

Adler32

A 32-bit CRC algorithm used by the GZip compression algorithm.

ASCII

American Standard Code for Information Interchange. This is the most widely used character set. It consists of 256 characters numbered 0 to 255 with each character consuming eight bits. Veracity models all files and filenames as finite blocks of ASCII characters. See also EBCDIC.

Attribute

An attribute is any piece of information that is associated with an abstract thing. In the context of Veracity, an attribute is one of a well-defined set of Veracity-defined file properties that record information about files. An example is the UMtm attribute which on Unix computers stores the modification date and time of a file.

Binary file

A binary file is a non-text file. See also Text file.

Birthday attack

A particular class of attack against one-way functions. The technique does not allow the function to be completely inverted, but it does find two inputs that correspond to the same output. It does this by computing the function value of many different randomly generated inputs and searching for identical pairs in the set of outputs. Birthday attacks mean that under some conditions digest

algorithms that are n bits wide and which have an a-priori difficulty of O(2**n) can be cracked with just O(sqrt(2**n)) effort. Thatʼs a great birthday present for any cryptanalyst.

Byte

Formally an abstract unit of information. However, in the context of Veracity, it is used exclusively to refer to groups of eight bits.

Checksum

The number produced by a checksum algorithm. See also Checksum algorithm.

Checksum algorithm

A checksum algorithm is a signature algorithm that does not attempt to provide cryptographic protection against inversion. The term “checksum” originally referred to checking algorithms that summed the bytes, but is now generally used to refer to any non-cryptographic checking algorithm. See also Signature algorithm.

Clip file

This is the old name for a Policy file. See the Policy Files section for details.

Corrupted

Data is said to be corrupted if it has been modified without the userʼs authorization or approval. Corruption is a subtle concept that can only be measured relative to a userʼs intent. If a file is transfered across a phone line and a digit of a number is accidentally altered, the file is then corrupt. However, if the user were to enter the editor and make exactly the same change, the file would not be corrupt.

Appendix A: Glossary



CRC

(Cyclic Redundancy Code) This acronym describes a class of “checksum” algorithms that operate by treating the message as a large binary number and then dividing it in binary without overflow by a fixed constant. The remainder is the “checksum”.

CRC-16

A particular high-quality well-defined 16-bit CRC algorithm.

CRC-32

A particular high-quality well-defined 32-bit CRC algorithm.

Current directory

The current directory is the directory that the operating system considers to be “current” at the time when Veracity is invoked. Most operating systems have a concept of a “current” directory and enable the user to manipulate this explicitly (Unix: cd dir, OpenVMS: set def dir, MS-DOS: cd dir, Macintosh: the folder containing the Veracity executable). By default, Veracity operates in and on the current directory (and possibly the directory tree rooted in it) if no other directory is specified. The current directory is sometimes also referred to as the Default directory (as in OpenVMS). See also Top directory. See also Root directory. See also Veracity directory

Cycle

See Directory Cycle

Dangerous-side failure

A dangerous side failure occurs where a system fails in a manner that threatens its safety mission. For example, if a traffic light fails by becoming permanently red, this is a safe-side failure because no one is likely to be hurt, but if a traffic light fails by becoming permanently green, this is a dangerous-

side failure because it could cause car accidents. See also Safe side failure.

DCL

(Digital Command Language) The command language provided by HP/Compaqʼs OpenVMS operating system.

Default directory

See Current directory.

Digest

The number produced by a digest algorithm. Typically this number is 16 to 32 bytes long.

Digest algorithm

A digest algorithm is a signature algorithm that provides cryptographic protection against inversion. That is, given a digest produced by a digest algorithm, it is very difficult (i.e. computationally infeasible) to find a message that has that digest. This property means that if you know the digest of a file, it is almost impossible for someone to change the file in such a way that the result will have the same digest. This is the basis of Veracityʼs application as a security tool. See also Signature algorithm.

Directory Cycle

A directory cycle arises in a directory tree when an entry in a directory (being either a hard link or a symbolic link (softlink)), points to an ancestor directory. Any computer program that follows the link will find itself traversing the same directory tree repeatedly in a cycle. Cycles can also arise in more complicated ways. Veracity performs comprehensive cycle detection to prevent itself from getting stuck in an infinite loop.

Directory tree

Most modern computer systems store files in a hierarchy (tree structure) of directories,



each of which contains zero or more files. A directory tree consists of a subtree of such a hierarchy and can be specified (e.g. to Veracity) simply by identifying the directory at the top (root) of the subtree using either a relative or absolute path.

EBCDIC

(Extended Binary Coded Decimal Interchange Code) An archaic collection of character sets used on ageing IBM machines. See also ASCII.

EOF

(End Of File) This term is used to describe the end of a file. The term can be used either to represent the abstract position at the end of the file or, in some instances, the concrete character used on some machines to indicate the end of a text file. See also EOL.

EOL

(End Of Line) This term is used to describe the end of a line in a text file. The term can be used either to represent the abstract position at the end of a line, or the special character(s) used on some machines to indicate the end of a line. Unfortunately, while most machines conform to the ASCII standard in their representation of text characters, they vary in the way in which they represent end-of-line. See also EOF.

File attribute

A piece of information about a file, for example, its name. Veracity models a file as a collection of file attributes.

File Kind

In the context of Veracity, the “kind” of a regular file refers to whether it is a binary or a text file.

File Type

In the context of Veracity, the “type” of a

file refers to which of the following mutually exclusive file type categories it falls: Directory (D), Regular File (F), Symbolic Link (S), Volatile File (V).

Fletcher checksum

A recently invented 16-bit checksum algorithm that has nearly all of the error detection capabilities of the CRC-16 algorithm, but which can be more efficiently implemented.

Hacker

The term hacker has two main meanings. Traditionally, it refers to a person who is highly involved with computers and highly proficient at programming them. However, the term has recently been used in the public sphere to denote a person attempting to break into a remote computer system through a communications network. This second meaning is unfortunate because it has largely made the first culture invisible to the public who refer to those in it, at best, as “boffins”. For this reason, this manual generally refers to what the public call hackers as “intruders” or “opponents”. See Intruder. See also Opponent.

Hash function

This is really just another name for a signature algorithm. This term is used in the field of data structures to refer to a non-cryptographic function used to locate elements in a so-called “hash table”. However, in the field of cryptography, it has a much stronger cryptographic flavor and is usually used to refer to a digest algorithm. Even so, those using the term often feel obliged to add a qualifier such as “strong” or “secure” as in “The Xerox Secure Hash Function”.

Heterogeneous file transfer

The transfer of a file from a machine running one operating system to a different



machine running a different operating system.

Homogenous file transfer

The transfer of a file from a machine running one operating system to a different machine running the same operating system.

Integrity

The degree to which a computer system or its data conforms to its formal requirements.

Internet checksum

The 16-bit checksum algorithm used to check IP network packets in the IP (Internet Protocol) that is used throughout the Internet.

Intruder

A person who attempts to break into a computer system and subvert its security, possibly by direct physical means such as walking in and logging in to the operatorʼs console, but more usually by remotely connecting to and logging in to the computer system through a communications network.

Journal file

An output file that Veracity can be instructed to produce that contains a copy of the output sent to standard output. In other systems, this is sometimes called a “log file”.

Kind

See File Kind

Message

An abstract term used in the cryptographic

literature to denote the data being fed into a checksum or digest algorithm.

Message digest

Another term for “digest”. See also Digest.

MD

(Message Digest) The long form of “digest”. Whereas IBM has adopted the acronym MDC for its digest algorithms, MD has been adopted by RSA Data Security for its digest algorithms. See Message digest. See also MDC.

MD2

An abbreviation for the “RSA Data Security, Inc. MD2 Message-Digest Algorithm”. This is a fairly slow digest algorithm that provides good security.

MD4

An abbreviation for the “RSA Data Security, Inc. MD4 Message-Digest Algorithm”. MD4 is a fast, fairly secure digest algorithm. When it was released, it was so popular that its inventors became concerned that it might not be secure enough for widespread use, and released a more secure version which they called MD5.

MD5

An abbreviation for the “RSA Data Security, Inc. MD5 Message-Digest Algorithm”. This is a fast and secure algorithm.

MDC

(Modification Detection Code). Another term for “digest”. This acronym is favored by IBM who have named their digest algorithms MDC-1, MDC-2, and MDC-4. See MD. See also Digest.

Modification detection code

See MDC.

Opponent



A generic term used to refer to an abstract enemy bent on subverting the security of your computer system.

Output file

Any file written by Veracity.

Password

Veracity allows a password to be woven through a snapshot file using message digests so that the snapshot file cannot be modified (without detection) without the password.

Policy File

A file created by the user specifying to Veracity the checks that should be performed in each part of the target tree.

Printable

In the context of Veracity, this term is used to refer to the set of printable characters of the 7-bit ASCII character set. That is: space (32) to tilde (126) inclusive.

Production

See Rule.

Quality by process

A method of controlling quality by increasing the reliability of the process that is producing the objects whose quality is being measured. See also Quality by test.

Quality by test

A method of controlling quality by testing the result of a process to ensure that the objects so produced meet a certain quality standard. Veracity provides quality by test. See also Quality by process.

Randomness

The randomness of a checksum or digest algorithm is the extent to which the algorithm scrambles its signature based on the input block. See also Signature.

Regular file

A regular file is a file that is an ordinary file containing zero or more bytes of data. Files that are not regular files are: directory files, symbolic links, and “volatile” files. Within this documentation, regular files are usually referred to as just “files”.

Report file

A file to which Veracityʼs snapshot, check and restore commands append reports of their activity.

RFC

(Request For Comment) The Internet RFCs are a collection of documents that define a set of standards describing the technical implementation of the Internet.

Rocksoft Limited

A software company based in Adelaide, Australia that specializes in data integrity. Rocksoft is the vendor of Veracity.

Root directory

The root directory of a computer system or a device is the directory that directly or indirectly contains all the other directories in the computer system or on the device. The root directory of a directory tree is the directory at the top of the tree. This is sometimes referred to as the root of the tree. See also Current directory. See also Top directory.

Rule

In the context of Veracity, the term “rule” is used to refer to a (pattern, arrow, action) triplet in a policy file. A policy file is considered to consist of a list of rules. See also Production.



Safe-side failure

A safe side failure occurs where a system fails in a manner that does not threaten its safety mission. For example, if a traffic light fails by becoming permanently red, this is a safe-side failure because no one is likely to be hurt, but if a traffic light fails by becoming permanently green, this is a dangerous-side failure because it could cause car accidents. See also Dangerous side failure.

Signature

The number produced by a signature algorithm. See also Signature algorithm.

Signature algorithm

The term “signature” is generally used in the field of cryptography to describe a method in which a server can digitally “sign” a document in a manner that does not allow him to deny the signature at a later date. However, in the context of Veracity, the term “signature algorithm” is used a little more loosely to denote the set of checksum and digest algorithms. A “signature algorithm” accepts a finite sequence of bytes (the “message”) and returns another finite sequence of bytes called a “signature” that in some sense is representative of the message. Signature algorithms are always many-to-one functions. If an attempt has been made by an algorithmʼs designers to make it computationally infeasible to invert the algorithm, the algorithm is classified as a digest algorithm, otherwise it is a checksum algorithm.

Script

A file containing Veracity shell commands.

SHA

(Secure Hash Algorithm). A strong digest algorithm proposed by the US NIST (National Institute of Standards and Technology) agency as a standard digest algorithm. The terminology here is a little

confusing. NIST released a first version of SHA which it referred to as “SHA”. It subsequently found a problem with it and released a second version which it called “SHA-1”. Within Veracity, the term “SHA-0” is used to refer to the first version, “SHA-1” is used to refer to the second version, and the term “SHA” is used to refer to the pair of algorithms in the abstract.

Shell

A shell is a command interpreter. The term “shell” is derived from the Unix operating system which is structured as a nested set of “shells”, the outermost one of which interacts with the user and is given the name “shell”. In the context of Veracity, the term is used to denote the Veracity command interpreter.

Snapshot

See Snapshot file.

Snapshot file

In the field of photography, a snapshot is an informal name used for a photograph which records a particular moment in time. In Veracity the term is used to describe a file containing information about a directory tree at a particular moment in time. Itʼs just like taking a photograph of a directory tree. Veracity snapshot files usually record only the signatures of files in tree and so are usually about 1/200th of the size of tree.

Snefru

Snefru is a digest algorithm produced by Xerox. Although it looks as if it is an acronym, itʼs actually named after a Pharaoh of ancient Egypt. Itʼs official name is “The Xerox Secure Hash Function”.

Soft Link

An informal term for a Symbolic Link. Symbolic links are sometimes called “soft



links” because they contrast to the so-called “hard links” used most of the time by the operating system to structure its file system trees.

Stub

A construct written to a snapshot file as a placeholder for a particular directory clipped by the policy file, or because the directory was inaccessible.

Symbolic Link (symlink)

A symbolic link is a special kind of directory entry that contains a relative or absolute path to another file. Unix, and other operating systems that support symbolic links, treat the entry as if it were actually the file to which the entry points. By default, Veracity does not follow symbolic links in this way, but it will do so if you specify the follow attribute. Veracity can also monitor the value of symbolic links. Symbolic links are sometimes called “symlinks” or “soft links”.

Symlink

See Symbolic link.

Text file

Any file whose contents are intended by the fileʼs creator to be interpreted as a sequence of zero or more lines containing ASCII printable characters. See also Binary file.

Top directory

The top directory of a directory tree is the directory at the root of the tree. Trees are upside down in computing. See also Current directory. See also Root directory. See also Veracity directory.

Tree

This term is used loosely in the context of Veracity to refer to a directory tree of files. See also Directory tree.

Tree of files

This term is used loosely in the context of Veracity to refer to a directory tree of files. See Directory tree.

Trojan horse

This term is derived from ancient Greek myth/legend/history in which the Greeks presented their enemy the Trojans with an enormous wooden horse. The Trojans wheeled the horse into their city only later to discover that it was full of Greek soldiers who opened the city gates and enabled the Greeks to execute a crushing defeat. In computing, the term “Trojan horse” is used to denote any software object that in some sense gains the trust of its user, but later betrays that trust. For example, a user who obtains a copy of a compiler off the Internet might at first be wary of the compiler, but then later trust it enough to inform the virus detection system not to monitor the compiler any more. If the compiler then releases a virus in the system, it has behaved like a Trojan horse.

Type

See File Type

Unix shell

See Shell.

Veracity

A commercial data integrity program distributed by Rocksoft Limited that assists the user to monitor the integrity of a directory tree by recording the signatures



of files in the tree and then comparing them with those of the same files at a later date.

Veracity directory

When you install Veracity, you should create a directory whose purpose is to store the Veracity executable and associated files. This is called the Veracity directory. See also Current directory. See also Top directory.

Veracity agent

Refers to when Veracity is running as a TCP-style server, allowing users from remote computers to take snapshots of the local files.

Veracity server

This is the old name for a Veracity Agent. See the Veracity Agent section for details.

Version number

A fileʼs version number is a number associated with the file that indicates its order within a set of other files having the same name. The version number is sometimes treated as part of the name of the file as on OpenVMS in which the full name of version 5 of a file called sloth.dat would be sloth.dat;5.

Virus

A hostile piece of software designed to penetrate and subvert the security of a computer system. Viruses spread by replicating themselves on the hostʼs hard disk and floppy disks and, if successful, can strike at any time, corrupting or deleting data at will. Viruses present such a threat to computer systems that there is now a roaring trade in virus protection software.

Volatile file

A volatile file is a file whose content is “volatile” in some way and shouldnʼt be read by Veracity. Volatile is one of four file types

defined by Veracity (the others are directory regular file, and symbolic link). Veracity categorizes a file as volatile if itʼs clear that the fileʼs content is not stable. Examples of Unix files categorized as “volatile” are character device files, block device files, and FIFO files. The category may also be used to categorize similarly unstable files in other operating systems. Because Veracity categorizes all such files into the separate “volatile” category, and does not permit the user even to specify any content attributes for volatile files in the policy file, the user can be sure that Veracity will not get stuck attempting to read a device file, because it will never attempt to read such files.

Width

The width of a signature algorithm (checksum or digest) is the number of bits or bytes that the algorithm produces as its signature.

Worm

A virus like computer program that propagates itself through a network.



[Bontchev] Bontchev V., “Possible Virus Attacks Against Integrity Programs And How To Prevent Them”, Vesselin Bontchev, Virus Test Center, University of Hamburg, Vogt-Koelln-Strasse 30, 2000 Hamburg 54, Germany, [email protected].

[Borenstein92] Borenstein N., Freed N., “MIME (Multipurpose Internet Mail Extensions): Mechanisms for Specifying and Describing the Format of Internet Message Bodies”, Internet RFC-1341, June 1992. Available by anonymous FTP from nic.ddn.mil.

[Braden88], Braden R., Borman D., Partridge C., “Computing the Internet Checksum”, Internet RFC-1071, September 1988. Available by anonymous FTP from nic.ddn.mil.

[Garmonsway79] Garmonsway G.N., “The Penguin English Dictionary”, Penguin Books Ltd, Harmondsworth, Middlesex, England, (ISBN: 0-14-051.029-X), 1979.

[Kalisky92] Kalisky B., “The MD2 Message-Digest Algorithm”, Internet RFC-1319, April 1992. Available by anonymous FTP from nic.ddn.mil.

[Kane94] Kane P., “PC Security And Virus Protection Handbook”, M&T Books, 115 West 18th Street, New York, New York 10011, (ISBN: 1-55851-390-6), 1994.

[Merkle??] Merkle R.C., “Snefru 2.5: The Xerox Secure Hash Function”, available by anonymous FTP from parcftp.xerox.com in /pub/hash (itʼs not clear what year this is).

[NIST93] Federal Information Processing Standards Publication (FIPS PUB) 180: Secure Hash Standard, Computer Systems Laboratory, US National Institute of Standards and Technology, 11 May 1993.

[NIST94] Federal Information Processing Standards Publication (FIPS PUB) 180-1: Secure Hash Standard (Draft), Computer Systems Laboratory, US National Institute of Standards and Technology, 26 May 1994.

[Pieprzyk93] Pieprzyk J, Sadeghiyan B., “Design of Hashing Algorithms”, Lecture Notes In Computer Science , Number 756, Springer Verlag, 1993.

[Rivest92a] Rivest R., “The MD4 Message-Digest Algorithm”, Internet RFC-1320, April 1992. Available by anonymous FTP from nic.ddn.mil.

[Rivest92b] Rivest R., “The MD5 Message-Digest Algorithm”, Internet RFC-1321, April 1992. Available by anonymous FTP from nic.ddn.mil.

[Sci.crypt] sci.crypt is an internet newsgroup on cryptology which often includes discussions of digest algorithms.

[Simmons92] Simmons G.J., “Contemporary Cryptology: The Science of Information Integrity”, IEEE Press, 445 Hoes Lane, PO Box 1331, Piscataway, NJ 08855-1331, USA, (ISBN: 0-87942-277-7), 1992.

[Williams91] Williams R.N., “Adaptive Data Compression”, Kluwer Academic Publishers, 101 Philip Drive, Assinippi Park, Norwell, Massachusetts 02061, USA, (ISBN: 0-7923-9085-7), 1991. See p.183 for a definition of the CHKRW1 checksum algorithm.

[Williams93] Williams R.N., “A Painless Guide to CRC Error Detection Algorithms”, http://www.ross.net/crc/, 1993.

[Williams94a] Williams R.N., “An Introduction To Digest Algorithms”, Proceedings of the Digital Equipment Computer Users Society Australia, 1994. ftp://ftp.rocksoft.com/papers/.

[Williams94b] Williams R.N., “Data Integrity With Veracity”, Proceedings of the Digital Equipment Computer Users Society Australia, 1994. See also ftp://ftp.rocksoft.com/papers/.

[Yuval79] Yuval G., “How to Swindle Rabin”, Cryptologia , 3(3), July 1979, pp. 187--190. Note: The author has not yet sighted this paper.

Appendix B: References



CopyrightThe entire contents of all the pages of this Veracity Reference Manual is:

Copyright © Rocksoft Limited 1994-2003. All rights reserved.

TrademarksMacintosh is a trademark of Apple ComputerMS-DOS is a trademark of Microsoft.Novell and Netware are registered trademarks of Novell.Rocksoft is a registered trademark of Rocksoft Limited, Australia.Unix is a registered trademark of AT&T.VAX and OpenVMS are trademarks of Compaq.Veracity is a registered trademark of Rocksoft Limited, Australia.Windows and Windows NT are trademarks of Microsoft.

Throughout this manual, the following abbreviations are used:

MD2 is used to denote the “RSA Data Security, Inc. MD2 Message-Digest Algorithm”.MD4 is used to denote the “RSA Data Security, Inc. MD4 Message-Digest Algorithm”.MD5 is used to denote the “RSA Data Security, Inc. MD5 Message-Digest Algorithm”.

QuestionsPlease email Rocksoft if you have any questions about intellectual property associated with Veracity.

CreditsVeracity was conceived, designed and implemented by Ross Williams. This reference manual was written by Ross Williams in 1994 as a printed manual, and converted by him to a web in April 1997. Last updated by Peter Cassidy in July 2003.

Thanks go to Simon Hackett of Internode Systems for many helpful discussions, to Jeremy Begg of VSM Software Services for assistance in porting Veracity to OpenVMS, and to Mark Newton and Ivan Brawley of Internode Systems for technical advice. Thanks also to the hundred or so other people (mostly on the Internet) who answered technical questions during the initial development period. Disclaimer of Liability: Rocksoft makes no express or implied representations or warranties in relation to this Software. To the full extent permitted by law, unless a specific contract is negotiated between Rocksoft and the user of this Software, Rocksoft will not be liable to the user under any law for any loss or damage (including but not limited to direct, indirect, economic and consequential loss or damage) in respect of any matter whatsoever related to the use of this Software, including without limitation, loss or damage caused by the negligent acts or omissions of Rocksoft or lost profits and damage suffered as a result of claims by any third person. Further, Rocksoft does not accept any responsibility or liability for any computer virus infection arising from the Software, or any loss or damage caused by the hardware or other software that is used in conjunction with the Software.

Veracity Reference Manual - CiteSeerX

Documents

Transcript of Veracity Reference Manual - CiteSeerX