[hcoop/zz_old/debian/webalizer.git] / wcmgr.1

.TH wcmgr 1 "12-Jul-2008" "Version 1.00" "The Webalizer"
.SH NAME
wcmgr - Webalizer (DNS) Cache file Manager
.SH SYNOPSIS
.B wcmgr\fP [\fI option ... \fP] \fIcache-file\fP
.PP
.SH DESCRIPTION
\fIwcmgr\fP is a utility program which allows manipulation of the DNS cache
files used and produced by The \fIWebalizer\fP.  Each record in the cache
file contains an IP address (either IPv4 or IPv6), a timestamp of when the
entry was added to the cache, a flag to indicate if the record contains
a resolved name or not, and either the same IP address or a resolved host
name.  All records are accessed by their IP address.
.SH RUNNING WCMGR 
\fIwcmgr\fP was designed to be run from the Unix shell command line.  This
facilitates its use in shell scripts and other automated processes.  A
valid DNS cache file \fBmust\fP be specified.  Command line options are
optional, and if none are given, the default action is to list the
contents of the specified cache file.
.SH COMMAND LINE OPTIONS
Different functions are selected by using one or more of the following
command line options.  If no options are given, the default is to display
the contents of the cache file to the screen (stdout).
.PP
.TP 8
.B \-h
Display all available command line options and exit.
.TP 8
.B \-v
Be verbose.

.TP 8
.B \-V
Display the program version and exit.  Additional program specific
information will be displayed if \fIverbose\fP mode is also used
(e.g. '\fI-vV\fP'), which can be useful when submitting bug reports.
.TP 8
.B \-a \fIaddress\fP [\fI-n hostname\fP] [\fI-t0\fP]
Add a new record to the cache file.  The IP \fIaddress\fP will be added to
the cache file using the current time as the timestamp and with a resolved
name \fIhostname\fP.  If \fI-t0\fP is specified, the record will be
considered permanent, and will not be removed (during a purge) or expired.
If a \fIhostname\fP is not specified with the \fI-n\fP option, then the
\fIaddress\fP will be used instead, and the record will be flagged as
unresolved.
.TP 8
.B \-c
Create a new cache file.  If used alone, this option will create a new,
empty cache file.  If used with the \fIimport\fP option, a new cache
file will be created before importing the data.  An error will occur
if the file \fIcache-file\fP already exists.
.TP 8
.B \-d \fIaddress\fP
Delete a record from the cache file using the specified \fIaddress\fP.
.TP 8
.B \-f \fIaddress\fP
Find and display information for \fIaddress\fP from the cache file.
A single line similar to that produced by the \fI-l\fP option will
be displayed unless \fIverbose\fP mode is enabled, in which case a
more detailed listing will be produced.
.TP 8
.B \-i \fIname\fP [\fI-c\fP]
Import data into the cache file from the file \fIname\fP.  The import
file must be a valid tab delimited text file, such as that created by
the \fIexport\fP option.  If the imported data contains records already
present in the cache file, those records will be overwritten by the
imported data.  The cache file must exist unless the \fI-c\fP option
is specified, in which case, a new cache file will be created for the
imported data.
.TP 8
.B \-l
List the contents of the cache file.  This is the default action of the
program, so does not necessarily need to be specified.  If \fIverbose\fP
mode is enabled, a report title, column headers and summary totals will
also be displayed.
.TP 8
.B \-p \fInum\fP
Purge the cache file of entries older than \fInum\fP days.  If \fInum\fP
is not specified, then a default of \fB7 days\fP will be used.  if
\fIverbose\fP mode is enabled, each purged record will be printed and
the total number of purged records will be displayed.
.TP 8
.B \-s [\fI-t num\fP]
Display cache file information/statistics.  If a TTL value (in days) is
specified using the \fI-t\fP option, it will be used to calculate how
many records are older than \fInum\fP days, otherwise, the default value
of \fB7 days\fP will be used.
.TP 8
.B \-n \fIname\fP
Specify the \fIname\fP to use as the resolved hostname when adding records
to the cache.
.TP 8
.B \-t \fInum\fP
Time to live (TTL) value.  If used along with the \fI-p\fP (purge) option,
it specifies how many days a record will remain valid.  Any record that is
older than \fInum\fP days is considered expired and will be purged.  If
used with the \fI-a\fP (add) option, a zero value will cause the record
to be considered permanent.
.TP 8
.B \-x \fIname\fP
Export data from a cache file to a tab delimited text file named \fIname\fP.
If the text file \fIname\fP exists, it will be overwritten.
.SH BUGS
Please report bugs to the author.
.SH COPYRIGHT
Copyright (C) 1997-2011 by Bradford L. Barrett.  Distributed under
the GNU GPL.  See the files "\fICOPYING\fP" and "\fICopyright\fP",
supplied with all distributions for additional information.
.SH AUTHOR
Bradford L. Barrett <\fIbrad at mrunix dot net\fP>
Commit	Line	Data
e015f748 CE	1	.TH wcmgr 1 "12-Jul-2008" "Version 1.00" "The Webalizer"
	2	.SH NAME
	3	wcmgr - Webalizer (DNS) Cache file Manager
	4	.SH SYNOPSIS
	5	.B wcmgr\fP [\fI option ... \fP] \fIcache-file\fP
	6	.PP
	7	.SH DESCRIPTION
	8	\fIwcmgr\fP is a utility program which allows manipulation of the DNS cache
	9	files used and produced by The \fIWebalizer\fP. Each record in the cache
	10	file contains an IP address (either IPv4 or IPv6), a timestamp of when the
	11	entry was added to the cache, a flag to indicate if the record contains
	12	a resolved name or not, and either the same IP address or a resolved host
	13	name. All records are accessed by their IP address.
	14	.SH RUNNING WCMGR
	15	\fIwcmgr\fP was designed to be run from the Unix shell command line. This
	16	facilitates its use in shell scripts and other automated processes. A
	17	valid DNS cache file \fBmust\fP be specified. Command line options are
	18	optional, and if none are given, the default action is to list the
	19	contents of the specified cache file.
	20	.SH COMMAND LINE OPTIONS
	21	Different functions are selected by using one or more of the following
	22	command line options. If no options are given, the default is to display
	23	the contents of the cache file to the screen (stdout).
	24	.PP
	25	.TP 8
	26	.B \-h
	27	Display all available command line options and exit.
	28	.TP 8
	29	.B \-v
	30	Be verbose.
	31
	32	.TP 8
	33	.B \-V
	34	Display the program version and exit. Additional program specific
	35	information will be displayed if \fIverbose\fP mode is also used
	36	(e.g. '\fI-vV\fP'), which can be useful when submitting bug reports.
	37	.TP 8
	38	.B \-a \fIaddress\fP [\fI-n hostname\fP] [\fI-t0\fP]
	39	Add a new record to the cache file. The IP \fIaddress\fP will be added to
	40	the cache file using the current time as the timestamp and with a resolved
	41	name \fIhostname\fP. If \fI-t0\fP is specified, the record will be
	42	considered permanent, and will not be removed (during a purge) or expired.
	43	If a \fIhostname\fP is not specified with the \fI-n\fP option, then the
	44	\fIaddress\fP will be used instead, and the record will be flagged as
	45	unresolved.
	46	.TP 8
	47	.B \-c
	48	Create a new cache file. If used alone, this option will create a new,
	49	empty cache file. If used with the \fIimport\fP option, a new cache
	50	file will be created before importing the data. An error will occur
	51	if the file \fIcache-file\fP already exists.
	52	.TP 8
	53	.B \-d \fIaddress\fP
	54	Delete a record from the cache file using the specified \fIaddress\fP.
	55	.TP 8
	56	.B \-f \fIaddress\fP
	57	Find and display information for \fIaddress\fP from the cache file.
	58	A single line similar to that produced by the \fI-l\fP option will
	59	be displayed unless \fIverbose\fP mode is enabled, in which case a
	60	more detailed listing will be produced.
	61	.TP 8
	62	.B \-i \fIname\fP [\fI-c\fP]
	63	Import data into the cache file from the file \fIname\fP. The import
	64	file must be a valid tab delimited text file, such as that created by
65	the \fIexport\fP option. If the imported data contains records already
66	present in the cache file, those records will be overwritten by the
67	imported data. The cache file must exist unless the \fI-c\fP option
68	is specified, in which case, a new cache file will be created for the
69	imported data.
70	.TP 8
71	.B \-l
72	List the contents of the cache file. This is the default action of the
73	program, so does not necessarily need to be specified. If \fIverbose\fP
74	mode is enabled, a report title, column headers and summary totals will
75	also be displayed.
76	.TP 8
77	.B \-p \fInum\fP
78	Purge the cache file of entries older than \fInum\fP days. If \fInum\fP
79	is not specified, then a default of \fB7 days\fP will be used. if
80	\fIverbose\fP mode is enabled, each purged record will be printed and
81	the total number of purged records will be displayed.
82	.TP 8
83	.B \-s [\fI-t num\fP]
84	Display cache file information/statistics. If a TTL value (in days) is
85	specified using the \fI-t\fP option, it will be used to calculate how
86	many records are older than \fInum\fP days, otherwise, the default value
87	of \fB7 days\fP will be used.
88	.TP 8
89	.B \-n \fIname\fP
90	Specify the \fIname\fP to use as the resolved hostname when adding records
91	to the cache.
92	.TP 8
93	.B \-t \fInum\fP
94	Time to live (TTL) value. If used along with the \fI-p\fP (purge) option,
95	it specifies how many days a record will remain valid. Any record that is
96	older than \fInum\fP days is considered expired and will be purged. If
97	used with the \fI-a\fP (add) option, a zero value will cause the record
98	to be considered permanent.
99	.TP 8
100	.B \-x \fIname\fP
101	Export data from a cache file to a tab delimited text file named \fIname\fP.
102	If the text file \fIname\fP exists, it will be overwritten.
103	.SH BUGS
104	Please report bugs to the author.
105	.SH COPYRIGHT
106	Copyright (C) 1997-2011 by Bradford L. Barrett. Distributed under
107	the GNU GPL. See the files "\fICOPYING\fP" and "\fICopyright\fP",
108	supplied with all distributions for additional information.
109	.SH AUTHOR
110	Bradford L. Barrett <\fIbrad at mrunix dot net\fP>