← Back to branch summary

~josephjamesmills/zpanelcp/zpanelcp

« back to all changes in this revision

Viewing changes to var/www/zpanel/modules/webalizer_stats/bin/DNS.README

  • Committer: Joseph Mills
  • Date: 2012-05-09 02:52:32 UTC
  • Revision ID: josephjamesmills@gmail.com-20120509025232-ob5xni0ggrse28c0
setup framwork for www

Show diffs side-by-side

added added

removed removed

Lines of Context:
var/www/zpanel/modules/webalizer_stats/bin/DNS.README
 
1
The Webalizer - A log file analysis program  -- DNS information
 
2
 
 
3
The webalizer now has the ability to perform reverse DNS lookups.  This
 
4
document attempts to explain how it works and some things that you should
 
5
be aware of when using the DNS lookup features.
 
6
 
 
7
Note: The Reverse DNS feature may be enabled or disabled at compile
 
8
      time.  It is enabled by using the -DUSE_DNS compiler switch, or
 
9
      by specifing '--enable-dns' when "configure' is run.  DNS lookups
 
10
      are disabled by default.
 
11
      
 
12
Another Note: DNS lookups will not work under Windows yet, see the
 
13
      README.WIN file for more information.
 
14
 
 
15
 
 
16
How it works
 
17
------------
 
18
 
 
19
DNS lookups are made against a DNS cache file containing IP addresses
 
20
and resolved names.  If the IP address is not found in the cache file,
 
21
it will be left as an IP address.  In order for this to happen, a
 
22
cache file MUST be specified when the Webalizer is run, either using
 
23
the '-D' command line switch, or a "DNSCache" configuration file
 
24
keyword.  If no cache file is specified, no attempts to perform DNS
 
25
lookups will be done. The cache file can be made in two different ways.
 
26
 
 
27
1) You can have the Webalizer pre-process the specified log file at
 
28
   run-time, creating the cache file before processing the log file
 
29
   normally.  This is done by setting the number of DNS Children
 
30
   processes to run, either by using the '-N' command line switch or
 
31
   the "DNSChildren" configuration keyword.  This will cause the
 
32
   Webalizer to spawn the specified number of processes which will
 
33
   be used to do reverse DNS lookups.. generally, a larger number
 
34
   of processes will result in faster resolution of the log, however
 
35
   if set too high may cause overall system degredation.  A setting
 
36
   of between 5 and 20 should be acceptable, and there is a maximum
 
37
   limit of 100.   If used, a cache filename MUST be specified also,
 
38
   using either the '-D' command line switch, or the "DNSCache"
 
39
   configuration keyword.  Using this method, normal processing will
 
40
   continue only after all IP addresses have been processed, and the
 
41
   cache file is created/updated.
 
42
 
 
43
2) You can pre-process the log file as a standalone process, creating
 
44
   the cache file that will be used later by the Webalizer.  This is
 
45
   done by running the Webalizer with a name of 'webazolver' (ie: the
 
46
   name 'webazolver' is a symbolic link to 'webalizer') and specifing
 
47
   the cache filename (either with '-D' or DNSCache).   If the number
 
48
   of child processes is not given, the default of 5 will be used. In
 
49
   this mode, the log will be read and processed, creating a DNS cache
 
50
   file or updating an existing one, and the program will then exit
 
51
   without any further processing.
 
52
 
 
53
 
 
54
Run-time DNS cache file creation/update
 
55
---------------------------------------
 
56
 
 
57
The creation/update of a DNS cache file at run-time occurs as follows:
 
58
 
 
59
1) The log file is read, creating a list of all IP addresses that are
 
60
   not already cached and need to be resolved.
 
61
 
 
62
2) The specified number of children processes are forked, and are used
 
63
   to perform DNS lookups.
 
64
 
 
65
3) Each IP address is given, one at a time, to the next available child
 
66
   process until all IP addresses have been processed.  Each child will
 
67
   update the cache file when a name is found.
 
68
 
 
69
4) Once all IP addresses have been processed and the cache file updated,
 
70
   the Webalizer will process the log normally.  Each record it finds
 
71
   that has an unresolved IP address will be looked up in the cache file
 
72
   to see if a hostname is available (ie: was previously found).
 
73
 
 
74
Because there may be a significant amount of time between the inital
 
75
unresolved IP list and normal processing, the Webalizer should not be
 
76
run against live log files (ie: a log file that is activly being written
 
77
to by a server), otherwise there may be additional records present that
 
78
were not resolved.
 
79
 
 
80
 
 
81
Stand-Alone DNS cache file creation/update
 
82
------------------------------------------
 
83
 
 
84
The creation/update of the DNS cache file, when run in stand-alone mode,
 
85
occurs as follows:
 
86
 
 
87
1) The log file is read, creating a list of all IP addresses that are
 
88
   not already cached and need to be resolved.
 
89
 
 
90
2) The specified number of children processes are forked, and are used
 
91
   to perform DNS lookups.  If the number of processes was not specified,
 
92
   the default of 5 will be used.
 
93
 
 
94
3) Each IP address is given, one at a time, to the next available child
 
95
   process until all IP addresses have been processed.  Each child will
 
96
   update the cache file when a name is found.
 
97
 
 
98
4) Once all IP addresses have been processed and the cache file updated,
 
99
   the program will terminate without any further processing.
 
100
 
 
101
 
 
102
Larger sites may prefer to use a stand-alone process to create the DNS
 
103
cache file, and then run the Webalizer against the cache file.  This
 
104
allows a single cache file to be used for many virtual hosts, and reduces
 
105
the processing needed if many sites are being processed.  The Webalizer
 
106
can be used in stand alone mode by running it as 'webazolver'.  When
 
107
run in this fashion, it will only create the cache file and then exit
 
108
without any further processing.  A cache filename MUST be specified,
 
109
however unlike when running the Webalizer normally, the number of child
 
110
processes does not have to be given (will default to 5).  All normal
 
111
configuration and command line options are recognized, however, many
 
112
of them will simply be ignored.. this allows the use of a standard
 
113
configuration file for both normal use and stand alone use.
 
114
 
 
115
 
 
116
Examples:
 
117
---------
 
118
 
 
119
webalizer -c test.conf -N 10 -D dns_cache.db /var/log/my_www_log
 
120
 
 
121
   This will use the configuration file 'test.conf' to obtain normal
 
122
   configuration options such as hostname and output directory.. it
 
123
   will then either create or update the file 'dns_cache.db' in the
 
124
   default output directory (using 10 child processes) based on the
 
125
   IP addresses it finds in the log /var/lib/my_www_log, and then
 
126
   process that log file normally.
 
127
 
 
128
 
 
129
webalizer -o out -D dns_cache.db /var/log/my_www_log
 
130
 
 
131
  This will process the log file /var/log/my_www_log, resolving IP
 
132
  addresses from the cache file 'dns_cache.db' found in the default
 
133
  output directory "out".  The cache file must be present as it will
 
134
  not be created with this command.
 
135
 
 
136
 
 
137
for i in /var/log/*/access_log; do
 
138
  webazolver -N 20 -D /var/lib/dns_cache.db $i
 
139
done
 
140
 
 
141
  The above is an example of how to run through multiple log files
 
142
  creating a single DNS cache file.. this might be typically used on
 
143
  a larger site that has many virtual hosts, all keeping their log
 
144
  files in a seperate directory.  It will process each access_log it
 
145
  finds in /var/log/* and create a cache file (var/lib/dns_cache.db).
 
146
  This cache file can then be used to process the logs normally with
 
147
  with the Webalizer.
 
148
 
 
149
 
 
150
for i in /etc/webalizer/*.conf; do webalizer -c $i -D /etc/cache.db; done
 
151
 
 
152
  This will process each configuration file found in /etc/webalizer,
 
153
  using the DNS cache file /etc/cache.db.  This will also typically be
 
154
  used on a larger site with multiple hosts..  Each configration file
 
155
  will specify a site specific log file, hostname, output directory, etc.
 
156
  The cache file used will typically be created using a command similar
 
157
  to the one previous to this example.
 
158
 
 
159
 
 
160
Considerations
 
161
--------------
 
162
 
 
163
Processing of live log files is discouraged, as the chances of log records
 
164
being written between the time of DNS resolution and normal processing will
 
165
cause problems.
 
166
 
 
167
Cached DNS addresses have a TTL (time to live) of 3 days.  This may be
 
168
changed at compile time by editing the dns_resolv.h header file and
 
169
changing the value for DNS_CACHE_TTL.
 
170
 
 
171
There is an absolute maximum of 100 child processes that may be created,
 
172
however the actual number of children should be significantly less than
 
173
the maximum.. typical usage should be between 5 and 20.
 
174
 
 
175
If you are using STDIN for the input stream (log file) and have run-time
 
176
DNS cache file creation/update enabled.. the program will exit after the
 
177
cache file has been created/updated and no output will be produced.  If
 
178
you must use STDIN for the input log, you will need to process the stream
 
179
twice, once to create/update the cache file, and again to produce the
 
180
reports.
 
181
 
 
182
Special thanks to Henning P. Schmiedehausen <hps@tanstaafl.de> for the
 
183
original dns-resolver code he submitted,  which was the basis for this
 
184
implementation.
 
185