home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / srev13g.zip / SREFLOGS.DOC < prev    next >
Text File  |  1999-04-20  |  17KB  |  405 lines
  1. 22 April 1999 
  2.              Configuring the SRE-http Common-Log Audit File,
  3.                        and specifying scheduled programs
  4.  
  5. A) Introduction
  6.  
  7. In keeping with http server standards, SRE-http will maintain a
  8. common-log format audit file.
  9.  
  10. Besides offering a compact synopsis, a number of tools exist to help you
  11. analyze common-log files. Furthermore, as an adjunct to the common-log audit
  12. file, SRE-http can also record the browser used by each request (as
  13. well as the referer) in seperate log files.
  14.  
  15. This document discusses how to modify the SREFLOGS.INI file.  SREFLOGS.INI
  16. (which should be in the CFGS\ subdirectory of your GoServe working directory)
  17. contains the configuration options for these three log files. These
  18. options include the host-specific (and port-specfic)  filenames for
  19. these log files, audit-suppression instructions, and a few display options.
  20.  
  21. At this moment, there is no SRE-http configurator for SREFLOGS.INI --
  22. you'll have to use your favorite text editor.  Also note that, as
  23. with most other SRE-http configuration files, you can change it
  24. on the fly (SRE-http checks SREFLOGS.INI about every 20 seconds).
  25.  
  26. In addition to configuring the log files, SREFLOGS.INI can be used
  27. to run programs on a scheduled basis. The principal use of this scheduling
  28. is to rename log files (using the RENLOGS.CMD program); say, on a weekly 
  29. basis.  However, you can use this scheduling for any other purpose.
  30. Section C.2b below describes this feature.
  31.  
  32.  
  33. -------------------------------------------------
  34. B) Basic configuration
  35.  
  36. A few basic points:
  37.   i) If you want to record information to these audit files, you need to
  38.      enable the WRITE_LOGS parameter (you can use the configurator to do this).
  39.  
  40.  ii) If you are running a single-host server on port 80, and you
  41.      are happy to record all requests in a standard fashion, then you can
  42.      use the default version of SREFLOGS.INI.
  43.  
  44.      If you choose to do this, three files in the DATA\ directory
  45.      of the GoServe "working directory" (say, D:\GOSERVE\DATA)
  46.      will be created (and written to):
  47.         * COMMON.LOG -- the common-log audit file
  48.         * BROWSERS.LOG -- list of browsers
  49.         * REFERER.LOG -- list of referers
  50.         * COMBINED.LOG -- combination of common, referer, and browser logs.
  51.  
  52. iii) If post-filter processing has been suppressed (say, with the SEL-specific
  53.      NO_POSTFILTER permission), the request will not be recorded to these
  54.      audit files.
  55.  
  56.  iv) Advanced options: SRE-http will "lazy write" the audit files (about
  57.      once a minute).  SRE-http will also warn you (via the PMPRINTF
  58.      window) when a log file gets large (greater then 1M).  You can
  59.      change these limits by editing the POSTFCHK.RXX file.
  60.  
  61.   v) You can use the RENLOGS.CMD file as a sample of a "Scheduled Event" --
  62.      it will rename your common, browser, and referer logs on a
  63.      scheduled basis.
  64.  
  65.  vi) Scheduled options will be run even if POST-Filtering has been suppressed.
  66.  
  67.  
  68.  vii) You can instruct SRE-http to rename log files when they become
  69.       too large; thereby resetting the size of the log file to 0 bytes.
  70.       To do this, you should set the LOGFILE_MAXSIZE parameter in
  71.       SREFMON.CMD (see INITFILT.DOC for more details on LOGFILE_MAXSIZE).
  72.  
  73. -------------------------------------------------
  74. C) Configuration options
  75.  
  76. Configuration is accomplished by setting variables in SREFLOGS.INI.
  77. The following lists the variables, with details below:
  78.  
  79. COMMONLOG           == Default common-log file
  80. COMMONLOG.nnn       == Common-log file for port nnn server.
  81. COMMONLOG.hostn     == Common-log file for the "hostn" host.
  82. COMMONLOG.hostn.nnn == Common-log file for the "hostn" host on port nnn.
  83.  
  84. BROWSERLOG           == Default browser log file
  85. BROWSERLOG.nnn       == Browser log file for port nnn server.
  86. BROWSERLOG.hostn     == Browser log file for the "hostn" host.
  87. BROWSERLOG.hostn.nnn == Browser log file for the "hostn" host on port nnn.
  88.  
  89. REFERERLOG           == Default referer log file
  90. REFERERLOG.nnn       == Referer log file for port nnn server.
  91. REFERERLOG.hostn     == Referer log file for the "hostn" host.
  92. REFERERLOG.hostn.nnn == Referer log file for the "hostn" host on port nnn.
  93.  
  94. COMBINEDLOG           == Default combined (common/referer/browser) log file
  95. COMBINEDLOG.nnn       == Cominbedlog file for port nnn server.
  96. COMBINEDLOG.hostn     == Combined log file for the "hostn" host.
  97. COMBINEDLOG.hostn.nnn == Combined log file for the "hostn" host on port nnn.
  98.  
  99.  
  100.  
  101. APACHE_MODE          == Select format for Browser and Referer logs 
  102.  
  103.  
  104. FORCE_REFERER        == Use a " - " when no referer request header is available
  105.  
  106. NOOPTIONS            == Do not record the portion of the request selector
  107.                         following the ?
  108.  
  109. NOHTTP               == Do not record the HTTP/1.0 portion of the request
  110.                         string
  111.  
  112. NOCODES              == List of "return codes" and "http methods" to not record.
  113.  
  114. NOUSER               == List of IP addresses, and SRE-http "usernames", to
  115.                         not record
  116.  
  117. NOREFERER           == List of IP addresses to not record in REFERER.LOG
  118.                        (COMMON, COMBINED and BROWSER logs do NOT pay attention to
  119.                         this parameter).
  120.  
  121. NOURL              == Rquest selectors to not record
  122.  
  123. SCHED              == Scheduled programs to run
  124.  
  125.  
  126. C.1) Configuration Details: COMMONGLOG, COMBINEDLOG, BROWSERLOG and REFERERLOG ----
  127.  
  128. The COMMONLOG, COMBINEDLOG, BROWSERLOG, and REFERERLOG "stem" variables all have the same
  129. structure. The basic notion is that SRE-http will take the server port, and
  130. the server's host nickname, and attempt to find matching COMMONLOG (and
  131. COMBINEDLOG, BROWSERLOG and REFERERLOG) variables.  If a match is not found, 
  132. the "default" variables are used.
  133.  
  134. You should set these stem variable to equal filenames. If you use a
  135. relative file name (i.e.; FOO.BAR or DIR1/FOO.BAR), the file is
  136. assumed to be relative to the DATA\ subdirectory of the GoServe
  137. working directory.
  138.  
  139. Note that SREFLOGS.INI prior to SRE-http ver 1.3d, SREFLOGS.INI was in
  140. the DATA\ subdirectory; as of 1.3d, SREFLOGS.INI is in the CFGS\
  141. subdirectory.
  142.  
  143. Some examples should help.  These examples use COMMONLOG,
  144. but the logic is exactly the same for COMBINEDLOG, BROWSERLOG and REFERERLOG.
  145.  
  146. For these examples, assume the following entries in SREFLOGS.INI
  147. (also assume that the DATA\ subdirectory is D:\GOSERVE\DATA)
  148.  COMMONLOG='COMMON.LOG'
  149.  COMMONLOG.CIRCUS.8080='CIRCUS\COMMON.8080'
  150.  COMMONLOG.ZOO='D:\CIRCUS\WWW\COMMON.LOG'
  151.  
  152. Example 1: if the server is a single host (no host nicknames specified)
  153. on the standard port (80), then SRE-http would look for:
  154.    COMMONLOG.80         -- this is the first variable looked for
  155.    COMMONLOG            -- the default
  156. Since COMMONLOG.80 was not specified, COMMONLOG is used (which yields a
  157. value of D:\GOSERVE\DATA\COMMON.LOG).
  158. Note that this example also applies to non-standard ports on single
  159. host systems (with the .80 changed appropriately).
  160.  
  161. Example 2: port 80, host nickname of ZOO:
  162.    COMMONLOG.ZOO.80    -- this is the first variable looked for
  163.    COMMONLOG.ZOO       -- this is the second variable looked for
  164.    COMMONLOG           -- this is the default
  165. COMMONLOG.ZOO.80  was not specified, but COMMONLOG.ZOO was. Thus,
  166. the value will be D:\CIRCUS\WWW\COMMON.LOG.
  167.  
  168. Example 3: port 8080, "host nickname" of CIRCUS:
  169.    COMMONLOG.CIRCUS.8080   -- this is the first variable looked for
  170.    COMMONLOG.CIRCUS        -- this is the second variable looked for
  171.    COMMONLOG               -- this is the default
  172. Since COMMONLOG.CIRCUS.8080 exists; so the value will be
  173. D:\GOSERVE\DATA\CIRCUS\COMMON.8080  (D: must be an HPFS drive).
  174.  
  175. If the desired default is to not record, set COMMONLOG=0.  Note that
  176. you can override this default on a host-nickname/port specific basis.
  177.  
  178. As stated above, the COMBINEDLOG, BROWSERLOG and REFERERLOG variables are 
  179. treated the same way. Thus, to suppress the REFERERLOG, set REFERERLOG=0 
  180. (and have no other REFERERLOG. variables).
  181.  
  182. C.2a) The NOxxx,and other options  --------------------------------------
  183.  
  184. The followings options allow you to modify the output to the common-log file,
  185. and to suppress the recording of selected requests.
  186.  
  187.  
  188. APACHE_MODE:
  189.   If APACHE_MODE=1, then the referer and browser log's are written using
  190. an "Apache" mode (that is, something similar to what Apache server's write).
  191. If APACHE_MODE=0, then a "GoHTTP" mode is used.
  192.  
  193. For example:
  194. APACHE_MODE (browser and referer logs):
  195.   [14/Mar/1996:17:45:08] Mozilla/2.0 (X11; I; HP-UX A.09.05 9000/735)
  196.   [14/Mar/1996:17:48:10] http://guide-p.infoseek.com/Titles -> /~sret1/analog/
  197. GoHTTP:
  198.   [03/Jun/1997:19:35:16 -0500] DAL40-29.PPP.IADFW.NET Mozilla/2.02E (OS/2; I)
  199.   [2/Mar/1997:18:23:37 -0500] "/imgs/srefiltr.gif" http://ship.float.net/
  200.  
  201.  
  202. FORCE_REFERER:
  203. If FORCE_REFERER=1, then in cases where there is no referer,
  204. a " - " is used.
  205.  
  206.  
  207. NOOPTIONS:
  208.   If NOOPTIONS=1, then the portion of the request selector following a ?
  209.   will not be included.  Since this can be quite long (as when you are
  210.   using the GET method in an HTML FORM), inclusion of this information can
  211.   lead to very long (and hard to read) entries.
  212.   For example: given a request for: /LOOK1?arg1=sub1/&arg2=1&argx=1&xmac=0
  213.                if NOOPTIONS=1, the "request" portion of the common-log (and
  214.                referers log) will be /LOOK1
  215.  
  216. NOHTTP
  217.   Technically, a request string should end with the HTTP version.
  218.   Since this is almost always HTTP/1.0, and since it's not clear that
  219.   the common-log format requires this information, you can suppress this
  220.   portion of the request string by setting NOHTTP=1.
  221.  
  222. NOCODES
  223.    NOCODES should contain a space delimited list of  3 digit
  224.    "return status codes", and http-methods, that you do NOT want 
  225.    to record. For example,
  226.    you may not be interested in requests that generated a "authorization
  227.    response" (a 401 response). If so, set:
  228.        NOCODES='401 '
  229.    If you are also uninterested in "moved" responses, you can set:
  230.        NOCODES='401 301 302 '
  231.    If you are not interested in "authorization responses" and responses
  232.    to HEAD method requests:
  233.        NOCODES='401 HEAD'
  234.    And if you are sort of perverse, and are not interested in normal
  235.    responses, you can set:
  236.        NOCODES='200 '
  237.  
  238.    If the response code, or the request method, matches one of these NOCODES,
  239.    then none of the log files are written to.
  240.  
  241.  
  242. NOUSER
  243.    This should contain a space delimited list of IP names (or numeric
  244.    addresses for those clients with no IP name) that you do NOT wish to record.
  245.    It can also contain "usernames" (from SRE-http's USERS.IN
  246.    usename/password database).
  247.    That is, requests from these addresses (and from these "users") will NOT be
  248.    recorded.  One sensible use of this is to include OWNER's IP address
  249.    (since you probably don't care about requests you make to yourself), as
  250.    well as the "usernames" of the various SUPERUSERs.
  251.    Note that if you take this suggestion, you must put in the OWNER's IP
  252.    name (in contrast, the SRE-http OWNERS variable expects a numeric
  253.    IP address).
  254.  
  255.    Example: NOUSER=' joe.bars.net *.wah.com 151.121.55.6  ADMINX '
  256.  
  257.    Notes:
  258.      * you can use * as a wildcard for a field. Thus, ab.wah.com
  259.        and cd.wah.com would both match *.wah.com, but www.ef.wah.com would
  260.        NOT.
  261.     * If 151.121.55.6 has an IP name of jill.money.gov,
  262.       she would NOT match 151.121.55.6 -- 151.121.55.6 would only match
  263.       if there was NO ip name available.
  264.     * ADMINX is a possible "username" (possibly of a SUPERUSER).
  265.     * If a match to any of these NOCODES occurs, then none of the log files
  266.       are written to.
  267.  
  268. NOREFERER
  269.    This should contain a space delimited list of IP names (or numeric
  270.    addresses for those clients with no IP name) that you do NOT wish to record
  271.    in the REFERER.LOG file.
  272.    That is, requests that were refered from these addresses will NOT be
  273.    recorded in REFERER.LOG.  However, these requests WILL be recorded in the 
  274.    common.log, combined.log, and browser.log files.
  275.  
  276.  
  277.    Example: NOREFERER=' *.my.site.net  backup.site.org '
  278.  
  279.    Notes:
  280.      * you can use * as a wildcard for a field. Thus, ab.wah.com
  281.        and cd.wah.com would both match *.wah.com, but www.ef.wah.com would
  282.        NOT.
  283.     * If 151.121.55.6 has an IP name of jill.money.gov,
  284.       she would NOT match 151.121.55.6 -- 151.121.55.6 would only match
  285.       if there was NO ip name available.
  286.  
  287.  
  288. NOURL
  289.    The NOURL entries should contain URLs to NOT record. That is, if a request
  290.    selector matches one of these URLs, it will NOT be recorded.
  291.    For example:
  292.         NOURL = 'IMGS/*
  293.         NOURL = 'BORING/TEDIOUS.HTM '
  294.  
  295.    Notes:
  296.     *  You can include * as a wildcard. Thus, IMGS/HORSE.GIF
  297.        matches NOURL, and such requests would NOT be recorded
  298.        the common-log, etc. audit files.
  299.     *  These entries are NOT sensitive to host or port -- all
  300.        NOURL entries will apply to all hosts and ports (perhaps
  301.        we'll fix this up if there's enough demand).
  302.     *  If a request selector matches one of these NOURL variables, then none
  303.        of the log files are written to.
  304.     *  The several SRE-http hit suppresion options (such as
  305.        HIT_OWNER_SUPPRESS, have NO effect on these audit files).
  306.     *  \ are converted to /, and leading / are stripped.
  307.  
  308.     * You can also use the older (prior to sre-htt ver 1.3b.1298c) of:
  309.       NOURL.1 ='xxx'
  310.       NOURL.2='yyyy'
  311.       NOURL.3=0
  312.  
  313.  
  314. SCHED
  315.      SCHED='frequency prog_name argument' entries can be included
  316.      in SREFLOGS.INI. However, this has been deprecated -- the use
  317.      of SCHEDULE.CFG is recommened instead.
  318.  
  319. -------------------------------------------------
  320. D) Structure of .LOG files
  321.  
  322.  
  323. i) The common-log file format -------------------
  324.  
  325. (the following description is adapted from
  326.   http://www.apache.org/docs/mod/mod_log_common.html)
  327.  
  328. The common-log file contains a separate line for each request.
  329. A line is composed of several items (tokens) separated by spaces:
  330.      host ident authuser date request status bytes
  331. If a token does not have a value then it is represented by a hyphen (-).
  332.  
  333. The meanings and values of these tokens are as follows:
  334.  
  335. client
  336.   The fully-qualified domain name of the client, or its IP number if the
  337.   name is not available.
  338. ident
  339.    The identd identity information: NOT SUPPORTED BY SRE-http.
  340. authuser
  341.    The client's username, as provided in the AUTHORIZATION request header.
  342.    Note that the common-log standard suggests that "if the request was for a
  343.    password protected document, then this is the userid used in the request".
  344.    However, SRE-http will always include the authuser (if available), even
  345.    if the particular request did not require authorization.
  346. date
  347.    The date and time of the request, in the following format:
  348.       date = [day/month/year:hour:minute:second zone]
  349.    where:
  350.          day = 2 digit
  351.          month = 3 letter
  352.          year = 4 digit
  353.          hour = 2 digit
  354.          minute = 2 digit
  355.          second = 2 digit
  356.          zone = (`+' | `-') 4 digit
  357. request
  358.      The request line from the client, enclosed in double quotes
  359. status
  360.    The three digit status code returned to the client.
  361. bytes
  362.    The number of bytes in the object returned to the client, not including
  363.    any headers.
  364.  
  365. For example:
  366.  acl.wear.org - - [18/Mar/1996:16:24:08 -0500] "GET /SMP/HLO.HTM HTTP/1.0" 200 1251
  367.  
  368. In the above example, the HTTP/1.0 substring may not be standard (you can
  369. suppress it by setting the NOHTTP option in SREFLOGS.INI). Also note that
  370. -0500 corresponds to the EST offset from GMT.
  371.  
  372. ii) The BROWSERS log file ---------------------
  373.  
  374. The browsers log file has the following structure:
  375.    [date] client : user-agent
  376. For example:
  377.   [24/Feb/1997:18:14:30 -0500] 151.121.65.143 : IBM-WebExplorer-DLL/v1.1b
  378.  
  379. iii) The REFERERS log file ----------------------
  380.  
  381. The referers log file has the following structure:
  382.    [date]  "sel"  referer_url
  383. Where SEL is from the request string, and the referer_url is from the
  384. REFERER request header.
  385. For example:
  386.    [24/Feb/1997:18:18:19 -0500] "/SAMPLES/samp1.htm" http://dh.ag.gov/i.htm
  387. (http://dh.ag.gov/i.htm contained a link to /samples/samp1.htm)
  388.  
  389. Note: if a request does not have a REFERER request header (for example, WebEx
  390. does not provide a REFERER request header):
  391.   if FORCE_REFERER=0, an entry will NOT be added to the   REFERERS log.
  392.      FORCE_REFERER=1, a referer of " - " is used.
  393.  
  394. iv)The COMBINEDLOG log file
  395.  
  396. The  combined log file combines the common, referer, and browser logs.
  397. It has the following structure:
  398.   PARROT.HALL.NET - - [04/Jun/1997:22:38:16 -0400] "GET /imgs/justscal.gif"
  399.   200 516 "http://mysite.heights.edu/SAMPLES/guide.htm"
  400.   "Mozilla/2.02E (OS/2; I)"
  401. (but all on one long line).
  402.  
  403.  
  404. -- End of documentation.
  405.