2.2.4 Policy.txt

  • Article

The Corporate Error Reporting Version 1.0 Protocol allows for a set of configuration parameters that describe which tracking or response options are preferred. These parameters are set in one of two text files located in specific locations on the CER file share, and instruct the CER client exactly what information to include in the error report. The configuration parameters MUST be contained in a policy.txt and status.txt file as specified in this section and section 2.2.5.

If present, policy.txt MUST be placed in the root folder of the CER file share. Its format is a CRLF-delimited list of name-value pairs. It MUST be encoded using the ANSI character set. The file MUST conform to the following Augmented Backus-Naur Form (ABNF), as specified in [RFC4234]. Note that the terms in the "Policyrule" rule can appear in any order and all permutations are not illustrated in the ABNF for brevity and clarity.

 Policyrule              = [Tracking] [CrashesPerBucket] [URLLaunch] 
                           [NoSecondLevelCollection] [NoFileCollection] 
                           [NoExternalURL] [FileTreeRoot]
                           ; terms may appear in any order
 CERBooleanValue        = "YES" / "TRUE" / "1" / "NO" / "FALSE" / "0"
                           ; case insensitive
 Tracking                = %d84.114.97.99.107.105.110.103.61 CERBooleanValue CRLF
                           ; the encoded characters spell case-sensitive "Tracking="
 CrashesPerBucket        = %d67.114.97.115.104.101.115.32.112.101.114.32.98.117.99.1
                           07.101.116.61 (1DIGIT / ((%x31-39)1*DIGIT)) CRLF
                           ; the encoded characters spell case-sensitive "Crashes 
                           per bucket="
 URLLaunch               = %d85.82.76.76.97.117.110.99.104.61 Url CRLF
                           ; the encoded characters spell case-sensitive "URLLaunch="
 Url                     = URI ; [RFC 3986], see below for delimiter handling 
 NoSecondLevelCollection = %d78.111.83.101.99.111.110.100.76.101.118.101.108.67.111.
                           108.108.101.99.116.105.111.110.61 CERBooleanValue CRLF
                           ; the encoded characters spell case-sensitive "NoSecond
                           LevelCollection="
 NoFileCollection        = %d78.111.70.105.108.101.67.111.108.108.101.99.116.105.111.
                           110.61 CERBooleanValue CRLF
                           ; the encoded characters spell case-sensitive "NoFile
                           Collection=" 
 NoExternalURL           = %d78.111.69.120.116.101.114.110.97.108.85.82.76.61 
                           CERBooleanValue CRLF
                           ; the encoded characters spell case-sensitive "NoExternalURL="
 FileTreeRoot            = %d70.105.108.101.84.114.101.101.82.111.111.116.61 Path CRLF
                           ; the encoded characters spell case-sensitive "FileTreeRoot="
  
 Path                    = 1*260CHAR    ;    see below for delimiter handling

CERBooleanValue: The values "YES", "TRUE", and "1" represent True. The values "NO", "FALSE", and "0" represent False.

Tracking: A True CERBooleanValue instructs the CER client that it MUST enable internal tracking in the form of a hits.log (section 2.2.2.1) file and a crash.log (section 2.2.2.2) file. A False CERBooleanValue instructs the CER client that it MUST disable internal tracking. If this parameter is absent, the CER client SHOULD use a default value of "NO". <2>

Crashes per bucket: This MUST be a positive integer value or zero. This value indicates the maximum number of error reporting files to collect for each error. If this many error reporting files already exist for this error on the CER file share, then an additional error reporting file MUST NOT be submitted. If this parameter is absent, the CER client SHOULD use a default value of "5".

URLLaunch: This parameter informs the CER client that the specified URL references information to show the user.

Url: It MUST conform to the URL syntax, as specified in [RFC3986]. A CRLF pair MUST NOT appear in the Url, since that is reserved as the line delimiter.

NoSecondLevelCollection: A True CERBooleanValue instructs the CER client to ignore additional data requests specified in status.txt (section 2.2.5). A False CERBooleanValue instructs the CER client to honor additional data requests. If this parameter is absent, the CER client SHOULD use a default value of "NO".<3>

NoFileCollection: A True CERBooleanValue instructs the CER client to ignore file requests specified in status.txt (section 2.2.5). A False CERBooleanValue instructs the CER client to honor file requests. If this parameter is absent, the CER client SHOULD use a default value of "NO". File requests are the subset of data requests that gather files from the user's computer; they are specified in section 2.2.5 by the fDoc and GetFile rules.<4>

NoExternalURL: A True CERBooleanValue instructs the CER client to ignore URL information described in status.txt. A False CERBooleanValue instructs the CER client to honor URL information. If this parameter is absent, the CER client SHOULD use a default value of "NO".<5>

FileTreeRoot: The value MUST be a Universal Naming Convention (UNC) path. This parameter instructs the CER client to redirect the error reporting process to use this file tree location instead of the file tree location at which it found this file, starting from looking for a policy.txt file at that new file tree location. This new file tree location MUST meet the prerequisites/preconditions (section 1.5) and file tree paths (section 2.2.3) for the destination server. If this parameter is not indicated, the CER client MUST continue the error reporting process using the file tree root at which it found this file. To avoid an infinite loop, the CER client SHOULD keep track of how many times it has been redirected using this method, and if it is redirected more than 10 times, it SHOULD abort the error reporting process.

Path: A CRLF pair MUST NOT appear in the Path value, since that is reserved as the line delimiter.