From: Frédéric Marchal Date: Sat, 27 Nov 2010 21:05:18 +0000 (+0000) Subject: Generate the manpage from a docbook document X-Git-Tag: v2.3.2~125 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=84a17075917b4358da0433a00fb91d7f268686f1;p=thirdparty%2Fsarg.git Generate the manpage from a docbook document sarg.1 is now produced by processing a xml document. The docbook document is easier to read and maintain. The documentation was revised in the process. --- diff --git a/Makefile.in b/Makefile.in index 3e2c64a..e4f636f 100644 --- a/Makefile.in +++ b/Makefile.in @@ -44,9 +44,9 @@ OBJS = $(patsubst %.c,%.o,$(SRCS)) DISTFILES = $(SRCS) ABOUT-NLS SUBDIRS = po -.PHONY: all install clean uninstall mostlyclean distclean update-po $(SUBDIRS) +.PHONY: all install clean uninstall mostlyclean distclean update-po doc $(SUBDIRS) -all: sarg +all: sarg sarg.1 .c.o: $(CC) -c -I. $(CPPFLAGS) $(DEFS) $(CFLAGS) $< @@ -59,6 +59,19 @@ sarg: $(OBJS) $(SUBDIRS): $(MAKE) -C $@ +doc: sarg.1 sarg_manpage.html + +sarg.1: sarg_manpage.xml + echo "Making manual page" + xmllint --nonet --valid --noout $< + xsltproc --stringparam man.output.encoding latin1 --nonet /usr/share/sgml/docbook/xsl-stylesheets/manpages/docbook.xsl $< +# docbook2man.pl $< + +sarg_manpage.html: sarg_manpage.xml + echo "Making html manual page" + xmllint --nonet --valid --noout $< + xsltproc --stringparam use.id.as.filename 1 --stringparam root.filename sarg_manpage --nonet /usr/share/sgml/docbook/xsl-stylesheets/html/onechunk.xsl $< + install: all install-po -@if test ! -d $(DESTDIR)$(BINDIR); then \ echo "creating $(DESTDIR)$(BINDIR)"; \ diff --git a/sarg.1 b/sarg.1 index 935c7cf..f2ad341 100644 --- a/sarg.1 +++ b/sarg.1 @@ -1,175 +1,377 @@ -.\" Hey, EMACS: -*- nroff -*- -.\" First parameter, NAME, should be all caps -.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection -.\" other parameters are allowed: see man(7), man(1) -.TH SARG 1 "May 9, 2010" -.\" Please adjust this date whenever revising the manpage. +'\" t +.\" Title: sarg +.\" Author: Luigi Gangitano +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 27 Nov 2010 +.\" Manual: SARG +.\" Source: sarg +.\" Language: English .\" -.\" Some roff macros, for reference: -.\" .nh disable hyphenation -.\" .hy enable hyphenation -.\" .ad l left justify -.\" .ad b justify to both left and right margins -.\" .nf disable filling -.\" .fi enable filling -.\" .br insert line break -.\" .sp insert n+1 empty lines -.\" for manpage-specific macros, see man(7) -.SH NAME +.TH "SARG" "1" "27 Nov 2010" "sarg" "SARG" +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" sarg \- Squid Analysis Report Generator -.SH SYNOPSIS -.B sarg -.RI [ options ] -.I logfile... -.SH DESCRIPTION -\fBsarg\fP is a logfile parser and analyzer for the \fBSquid Web Proxy Cache\fP, -which can be found at \fBhttp://www.squid-cache.org/\fP. -This manual page documents briefly the -.B sarg -command. More information is available at \fBhttp://sarg.sourceforge.net/\fP. -This manual page was originally written for the Debian distribution -because the author didn't include one in favor of documentation -in the GNU Info format; see below. -.PP -.\" TeX users may be more comfortable with the \fB\fP and -.\" \fI\fP escape sequences to invode bold face and italics, -.\" respectively. -\fBsarg\fP is a tool that allows you to view "where" your users are going to on -the Internet. \fBsarg\fP generates reports in HTML, with fields such as: users, -IP Addresses, bytes, sites, and times. These HTML files can appear in your -web server's directory for browsing by users or administrators. You may also -have \fBsarg\fP email the reports to the Squid Cache administrator. -.PP -\fBsarg\fP can read \fBsquid\fP or \fBMicrosoft ISA\fP access logs. Optionally, it can -complement the reports with the log of a Squid filter/redirector such as -\fBsquidGuard (http://www.squidguard.org/)\fP. -.SH OPTIONS -A summary of options is included below. -.TP -.B \-h -Show summary of options. -.TP -.B \-a [hostname|ip address] +.SH "SYNOPSIS" +.HP \w'\fBsarg\fR\ 'u +\fBsarg\fR [options] [logfile...] +.SH "DESCRIPTION" +.PP + +\fBsarg\fR +is a log file parser and analyzer for the +\m[blue]\fBSquid Web Proxy Cache\fR\m[]\&\s-2\u[1]\d\s+2\&. It allows you to view "where" your users are going to on the Internet\&. +.PP + +\fBsarg\fR +generates reports in HTML with fields such as: users, IP Addresses, bytes, sites, and times\&. These HTML files can appear in your web server\'s directory for browsing by users or administrators\&. You may also have +\fBsarg\fR +email the reports to the Squid Cache administrator\&. +.PP + +\fBsarg\fR +can read +squid +or +Microsoft ISA +access logs\&. Optionally, it can complement the reports with the log of a Squid filter/redirector such as +\m[blue]\fBsquidGuard\fR\m[]\&\s-2\u[2]\d\s+2\&. +.SH "OPTIONS" +.PP +A summary of options is included below\&. +.PP +\fB\-h\fR +.RS 4 +Show summary of options\&. +.RE +.PP +\fB\-a hostname|ip address\fR +.RS 4 Limits report to records containing the specified hostname/ip address -.TP -.B \-b filename +.RE +.PP +\fB\-b \fR\fB\fIfilename\fR\fR +.RS 4 Enables UserAgent log and writes it to -.IR "filename". -.TP -.B \-c filename -Uses -.IR "filename" -as the exclude files to select records that are not counted. -.TP -.B \-\-convert -Convert a squid log file date/time field to a human-readable format. All the log files are read and output as one text on the standard output. -.TP -.B \-\-css -Output, on the standard output, the internal css inlined in the reports by sarg. You can redirect the output to a file of your -choice and edit it. Then you can override the internal css with -.B external_css_file -in sarg.conf. -.TP -.B \-d date -Uses -.I date -as the time limit during log file processing. Format for -.I date +\fIfilename\fR\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBWarning\fR +.ps -1 +.br +This option is currently unused\&. +.sp .5v +.RE +.RE +.PP +\fB\-c \fR\fB\fIfilename\fR\fR +.RS 4 +Read +\fIfilename\fR +for a list of the web hosts to exclude from the report\&. See +the section called \(lqHOST EXCLUSION FILE\(rq\&. +.RE +.PP +\fB\-\-convert\fR +.RS 4 +Convert a +squid +log file date/time field to a human\-readable format\&. All the log files are read and output as one text on the standard output\&. +.RE +.PP +\fB\-\-css\fR +.RS 4 +Output, on the standard output, the internal css +\fBsarg\fR +inlines in the reports\&. You can redirect the output to a file of your choice and edit it\&. Then you can override the internal css with +\fIexternal_css_file\fR +in +sarg\&.conf\&. +.sp +Using an external css can reduce the size of the report file\&. If you are short on disk space, you may consider exporting the css as explained above\&. +.RE +.PP +\fB\-d \fR\fB\fIdate\fR\fR +.RS 4 +Use +\fIdate\fR +to restrict the report to some date range during log file processing\&. Format for +\fIdate\fR is -.B dd/mm/yyyy-dd/mm/yyyy +\fBdd/mm/yyyy\-dd/mm/yyyy\fR or a single date -.BR "dd/mm/yyyy" ". Date ranges can also be specified as " "day-\fIn\fP" ", " "week-\fIn\fP" ", or " "month-\fIn\fP" +\fBdd/mm/yyyy\fR\&. Date ranges can also be specified as +\fIday\-\fR\fI\fBn\fR\fR, +\fIweek\-\fR\fI\fBn\fR\fR, or +\fImonth\-\fR\fI\fBn\fR\fR where -.I n -is the number of days, weeks or months to jump backward. Note that there is no spaces around the hyphen. -.TP -.B \-e email +\fBn\fR +is the number of days, weeks or months to jump backward\&. Note that there is no spaces around the hyphen\&. +.RE +.PP +\fB\-e \fR\fB\fIemail\fR\fR +.RS 4 Sends report to -.IR "email" -(stdout for console). -.TP -.B \-f filename +\fIemail\fR +(stdout for console)\&. +.RE +.PP +\fB\-f \fR\fB\fIfilename\fR\fR +.RS 4 Reads configuration from -.IR "filename". -.TP -.B \-g e|u -Sets date format in generated reports. -.br -\fBe\fP = Europe -> dd/mm/yy +\fIfilename\fR\&. +.RE +.PP +\fB\-g e|u\fR +.RS 4 +Sets date format in generated reports\&. +.RS 4 +e = Europe \-> dd/mm/yy +.RE +.RS 4 +u = USA \-> mm/dd/yy +.RE +.RE +.PP +\fB\-i\fR +.RS 4 +Generates reports by user and ip address\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 .br -\fBu\fP = USA -> mm/dd/yy -.TP -.B \-i -Generates reports by user and ip address. +.ps +1 +\fBNote\fR +.ps -1 .br -\fBNOTE:\fP This requires the 'report_type' -option in config file to contain "users_sites". -.TP -.B \-l filename +This requires the +\fIreport_type\fR +option in config file to contain "users_sites"\&. +.sp .5v +.RE +.RE +.PP +\fB\-l \fR\fB\fIfilename\fR\fR +.RS 4 Uses -.IR "filename" -as the input log. This option can be repeated up to 255 times to read multiple files. If the files end with the extension -.IR ".gz" ", " ".bz2" " or " ".Z" -they are decompressed. -If the file name is just -.I - -, the log file is read from standard input. In that case, it cannot be compressed. - -This option is kept for compatibility with older versions of sarg but, starting with sarg 2.3, the log files may be named on the command -line without the -.B \-l -option. It allows the use of wildcards on the command line. Make sure you don't exceed the limit of 255 files. -.TP -.B \-L filename -Reads a proxy redirector log file such as one created by squidGuard or Rejik. If you use this option, you may want to configure -.B redirector_log_format -in sarg.conf to match the output format of your web content filtering program. This option can be repeated up to 64 times to read multiple files. -.TP -.B \-n -Enables ip address resolution. -.TP -.B \-o dir +\fIfilename\fR +as the input log\&. This option can be repeated up to 255 times to read multiple files\&. If the files end with the extension +\&.gz, +\&.bz2 +or +\&.Z +they are decompressed\&. If the file name is just +\fI\-\fR, the log file is read from standard input\&. In that case, it cannot be compressed\&. +.sp +This option is kept for compatibility with older versions of sarg but, starting with +sarg 2\&.3, the log files may be named on the command line without the +\fB\-l\fR +option\&. It allows the use of wildcards on the command line\&. Make sure you don\'t exceed the limit of 255 files\&. +.RE +.PP +\fB\-L \fR\fB\fIfilename\fR\fR +.RS 4 +Reads a proxy redirector log file such as one created by +squidGuard +or +Rejik\&. If you use this option, you may want to configure +\fIredirector_log_format\fR +in +sarg\&.conf +to match the output format of your web content filtering program\&. This option can be repeated up to 64 times to read multiple files\&. +.RE +.PP +\fB\-n\fR +.RS 4 +Enables ip address resolution\&. +.RE +.PP +\fB\-o \fR\fB\fIdir\fR\fR +.RS 4 Writes report in -.IR "dir". -.TP -.B \-p -Generates reports using ip address instead of userid. -.TP -.B \-s string +\fIdir\fR\&. +.RE +.PP +\fB\-p\fR +.RS 4 +Generates reports using ip address instead of userid\&. +.RE +.PP +\fB\-s \fR\fB\fIstring\fR\fR +.RS 4 Limits report to the site specified by -.IR "string -[eg. www.debian.org] -.TP -.B \-\-split -Split the squid log file and output it as text on the standard output omitting the dates outside of the range specified by the \fB-d\fP parameter. -If it is combined with -.B \-\-convert -the dates are also converted to a human-readable format. -.TP -.B \-t string -Limits records counted in statistics based on time-of-day. Format for -\fIstring\fP is \fBHH\fP or \fBHH:MM\fP or \fBHH:MM:SS\fP. -.TP -.B \-u user -Limits reports to \fIuser\fP activities. -.TP -.B \-w dir -Uses \fIdir\fP for temporary files. -.TP -.B \-x -Writes debug messages to \fBSTDOUT\fP -.TP -.B \-z -Writes messages on processes to \fBSTDOUT\fP -.SH FILES -.BR /usr/local/sarg/sarg.conf +\fIstring\fR +[eg\&. www\&.debian\&.org] +.RE +.PP +\fB\-\-split\fR +.RS 4 +Split the squid log file and output it as text on the standard output omitting the dates outside of the range specified by the +\fB\-d\fR +parameter\&. If it is combined with +\fB\-\-convert\fR +the dates are also converted to a human\-readable format\&. +.RE +.PP +\fB\-t \fR\fB\fIstring\fR\fR +.RS 4 +Limits the records included in the report based on time\-of\-day\&. Format for +\fIstring\fR +is +\fBHH:MM\fR +or +\fBHH:MM\-HH:MM\fR\&. The former reports only the requested time\&. The latter reports any entry falling within the requested range\&. This limit complement the limit imposed by option +\fB\-d\fR\&. +.RE +.PP +\fB\-u \fR\fB\fIuser\fR\fR +.RS 4 +Limits reports to +\fIuser\fR +activities\&. +.RE +.PP +\fB\-w \fR\fB\fIdir\fR\fR +.RS 4 +Store temporary files in +\fIdir\fR\&. In fact, +\fBsarg\fR +stores its temporary files in the +sarg +subdirectory of +\fIdir\fR\&. Be sure to set the HTML output directory to a place outside of the temporary directory or sarg may fail or delete the report when it completes its task\&. +.RE +.PP +\fB\-x\fR +.RS 4 +Writes debug messages to +stdout +.RE +.PP +\fB\-z\fR +.RS 4 +Writes process messages to +stdout\&. +.RE +.SH "HOST EXCLUSION FILE" +.PP +Sarg can be told to exclude visited hosts from the report by providing it with a file containing one host to exclude per line\&. The "host" may be one of the following: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +a full host name, +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +a host name starting with a wildcard (*) to match any prefix, +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +a single ip address, +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +a subnet noted a\&.b\&.c\&.d/e\&. +.RE +.PP +\fBExample\ \&1.\ \&Example of a hosts exclusion file\fR +.RS 4 +*\&.google\&.com +.RE +.RS 4 +10\&.0\&.0\&.0/8 +.RE +.PP +Sarg cannot exclude IPv6 addresses at the moment\&. +.SH "SEE ALSO" +.PP +squid(8) +.SH "AUTHORS" +.PP +This manual page was written by +Luigi Gangitano +gangitano@lugroma3\&.org, for the +Debian GNU/Linux +system (but may be used by others)\&. Revised by +Billy Newsom\&. +.PP +Currently maintained by +Frédéric Marchal +fmarchal@users\&.sourceforge\&.net\&. +.SH "AUTHORS" +.PP +\fBLuigi Gangitano\fR <\&gangitano@lugroma3\&.org\&> +.RS 4 +Author of the first manual page +.RE +.PP +\fBBilly Newsom\fR +.RS 4 +Revision of the manual page +.RE +.PP +\fBFrédéric Marchal\fR <\&fmarchal@users\&.sourceforge\&.net\&> +.RS 4 +Docbook version of the manual page +.RE +.SH "COPYRIGHT" .br -.B /var/log/squid/access.log +Copyright \(co 2010 Frédéric Marchal .br -.B /usr/local/squidGuard/logs/squidGuard.log -.SH SEE ALSO -squid(8) -.SH AUTHOR -This manual page was written by Luigi Gangitano , -for the Debian GNU/Linux system (but may be used by others). Revised -by Billy Newsom. +.SH "NOTES" +.IP " 1." 4 +Squid Web Proxy Cache +.RS 4 +\%http://www.squid-cache.org/ +.RE +.IP " 2." 4 +squidGuard +.RS 4 +\%http://www.squidguard.org/ +.RE diff --git a/sarg_manpage.xml b/sarg_manpage.xml new file mode 100644 index 0000000..590570a --- /dev/null +++ b/sarg_manpage.xml @@ -0,0 +1,359 @@ + + + +
+SARG + + + + + sarg + 27 Nov 2010 + + + Luigi + Gangitano + Author of the first manual page + gangitano@lugroma3.org + + + + Billy + Newsom + Revision of the manual page + + + + Frédéric + Marchal + Docbook version of the manual page + fmarchal@users.sourceforge.net + + + + 2010 + Frédéric Marchal + + + + + sarg + 1 + + + + sarg + Squid Analysis Report Generator + + + + + + sarg + options + logfile + + + +Description + +sarg is a log file parser and analyzer for the Squid Web Proxy Cache. +It allows you to view "where" your users are going to on +the Internet. + + +sarg generates reports in HTML with fields such as: users, +IP Addresses, bytes, sites, and times. These HTML files can appear in your +web server's directory for browsing by users or administrators. You may also +have sarg email the reports to the Squid Cache administrator. + + +sarg can read squid or Microsoft ISA access logs. +Optionally, it can complement the reports with the log of a Squid filter/redirector such as +squidGuard. + + + +Options + +A summary of options is included below. + + + + + + + +Show summary of options. + + + + + + + +Limits report to records containing the specified hostname/ip address + + + + + + + +Enables UserAgent log and writes it to filename. + +This option is currently unused. + + + + + + +Read filename for a list of the web hosts to exclude from the report. See . + + + + + + + +Convert a squid log file date/time field to a human-readable format. +All the log files are read and output as one text on the standard output. + + + + + + + +Output, on the standard output, the internal css sarg inlines in the reports. You can redirect +the output to a file of your choice and edit it. Then you can override the internal css with +external_css_file in sarg.conf. + + +Using an external css can reduce the size of the report file. If you are short on disk space, you may consider +exporting the css as explained above. + + + + + + + +Use date to restrict the report to some date range during log file processing. +Format for date is dd/mm/yyyy-dd/mm/yyyy +or a single date dd/mm/yyyy. Date ranges can also be specified as +day-n, week-n, +or month-n where n +is the number of days, weeks or months to jump backward. Note that there is no spaces around the hyphen. + + + + + + + +Sends report to email (stdout for console). + + + + + + + +Reads configuration from filename. + + + + + + + +Sets date format in generated reports. + +e = Europe -> dd/mm/yy +u = USA -> mm/dd/yy + + + + + + + + +Generates reports by user and ip address. + + + +This requires the report_type +option in config file to contain "users_sites". + + + + + + + + +Uses filename as the input log. This option can be repeated up to 255 times to read +multiple files. If the files end with the extension .gz, .bz2 or +.Z they are decompressed. If the file name is just +-, the log file is read from standard input. In that case, it cannot be compressed. + + +This option is kept for compatibility with older versions of sarg but, starting with sarg 2.3, +the log files may be named on the command line without the +option. It allows the use of wildcards on the command line. Make sure you don't exceed the limit of 255 files. + + + + + + + +Reads a proxy redirector log file such as one created by squidGuard or Rejik. +If you use this option, you may want to configure redirector_log_format +in sarg.conf to match the output format of your web content filtering program. +This option can be repeated up to 64 times to read multiple files. + + + + + + + +Enables ip address resolution. + + + + + + + +Writes report in dir. + + + + + + + +Generates reports using ip address instead of userid. + + + + + + + +Limits report to the site specified by string +[eg. www.debian.org] + + + + + + + +Split the squid log file and output it as text on the standard output omitting the dates outside of the +range specified by the parameter. +If it is combined with +the dates are also converted to a human-readable format. + + + + + + + +Limits the records included in the report based on time-of-day. Format for +string is HH:MM or HH:MM-HH:MM. +The former reports only the requested time. The latter reports any entry falling within the requested +range. This limit complement the limit imposed by option . + + + + + + + +Limits reports to user activities. + + + + + + + +Store temporary files in dir. In fact, sarg stores its temporary files in +the sarg subdirectory of dir. Be sure to set the HTML +output directory to a place outside of the temporary directory or sarg may fail or delete the report when it completes its task. + + + + + + + +Writes debug messages to stdout + + + + + + + +Writes process messages to stdout. + + + + + + + +Host exclusion file +Sarg can be told to exclude visited hosts from the report by providing it +with a file containing one host to exclude per line. The "host" may be one of the following: + + +a full host name, +a host name starting with a wildcard (*) to match any prefix, +a single ip address, +a subnet noted a.b.c.d/e. + +Example of a hosts exclusion file + +*.google.com +10.0.0.0/8 + + + + +Sarg cannot exclude IPv6 addresses at the moment. + + + + +See also + +squid(8) + + + +Authors + +This manual page was written by Luigi Gangitano +gangitano@lugroma3.org, +for the Debian GNU/Linux system (but may be used by others). Revised +by Billy Newsom. + + +Currently maintained by Frédéric Marchal +fmarchal@users.sourceforge.net. + + + + + +