SARG(1)

✨ SARG(1) — sarg, the Squid Analysis Report Generator ✨

Okay bestie, gather round. This is the manual page for sarg (section 1 of the manual, iykyk). It's giving log-analysis realness and honestly? Iconic. Let's get into it. 🫶

---

💖 NAME 💖

sarg — Squid Analysis Report Generator. No cap, that's the whole vibe.

📜 SYNOPSIS 📜

sarg [options] [logfile...]

🌸 DESCRIPTION 🌸

sarg is a log file parser and analyzer for the Squid Web Proxy Cache[1]. It literally lets you see "where" your users are going on the Internet. Main character energy for your proxy logs.

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 so users or administrators can browse them. You may also have sarg email the reports to the Squid Cache administrator. Obsessed with the flexibility.

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[2]. The way it just does both? Versatile queen.

---

🎀 OPTIONS 🎀

A summary of options is included below. Every single one, bestie — I would never skip.

• -h, --help — Shows a summary of options. Simple, cute, necessary.
• -a hostname|ip address — Limits the report to records containing the specified hostname/ip address. Filtering era.
• -b filename — Enables the UserAgent log and writes it to filename. Tracking the user agents, slay.
• -c filename — Reads filename for a list of the web hosts to exclude from the report. See the section called “HOST EXCLUSION FILE”. Exclusion realness.
• --convert — Converts 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. Making timestamps make sense? We love to see it.
• --css — Outputs, on the standard output, the internal css that 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. Disk space queen behavior.

• -d date — Uses 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 are no spaces around the hyphen. Periodt — no spaces.
• -e email — Sends report to email (stdout for console). Emailing reports like a boss.
• -f filename — Reads configuration from filename. Config file realness.
• -g e|u — Sets date format in generated reports.
  • e = Europe -> dd/mm/yy
  • u = USA -> mm/dd/yy
• -i — Generates reports by user and ip address.

Note: This requires the report_type option in the config file to contain "users_sites". Don't forget, bestie.

• --keeplogs — Don't delete any old report. It is equivalent to setting --lastlog 0 but is provided for convenience. Hoarding reports? Valid.
• -l filename — 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 -l option. It allows the use of wildcards on the command line. Make sure you don't exceed the limit of 255 files. The limit is real, okay?

• --lastlog n — Limits the number of logs kept in the output directory to n. Any supernumerary report is deleted starting with the oldest report. The value of n must be positive or zero. A value of zero means no report should be deleted. Cleanup with boundaries.
• -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 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. Redirector logs? Say less.
• -n — Enables ip address resolution. DNS detective era.
• -o dir — Writes report in dir. Output location, slay.
• -p — Generates reports using ip address instead of userid. IP-based reporting, a whole mood.
• -P prefix --splitprefix prefix — This option must be used with --split. If it is provided, the input log is split among several files each containing one day. The name of the output files is made of the prefix and the date formated as -YYYY-MM-DD.

The output files are written in the output directory specified with -o or in the current directory. Organized by day? We love a filing system.

• -r — Outputs the realtime report on the standard output and exit. Realtime queen.
• -s string — Limits report to the site specified by string [eg. www.debian.org]. Site-specific filtering.
• --split — Splits the squid log file and outputs it as text on the standard output omitting the dates outside of the range specified by the -d parameter. If it is combined with --convert the dates are also converted to a human-readable format.

Combined with -P, the log is written in several files each containing one day of the original log. Split and conquer.

• --statistics — Writes some statistics about the execution time. The statistics include the total execution time; the number of records read in the input log files and the time it took to read them; the number of records and users processed and the time it took to process them. Numbers, numbers, numbers. We love data.
• -t string — 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 -d. Time filtering, bestie.
• -u user — Limits reports to user activities. User-specific focus.
• -v — Write sarg version and exit. Version check, cute.
• -w dir — Stores 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.

⚠️ Warning: keep your HTML output outside the temp directory, or things could go sideways. You've been warned.

• -x — Writes debug messages to stdout. Debug mode, activated.
• -z — Writes process messages to stdout. Process messages, slay.

---

🦋 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 1. Example of a hosts exclusion file

*.google.com
10.0.0.0/8

Sarg cannot exclude IPv6 addresses at the moment. Just so you know, bestie. 🙈

---

🌈 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>.

💜 AUTHORS 💜

• Frédéric Marchal <fmarchal@users.sourceforge.net> — Docbook version of the manual page
• Billy Newsom — Revision of the manual page
• Luigi Gangitano <gangitano@lugroma3.org> — Author of the first manual page

---

👑 COPYRIGHT 👑

Copyright © 2012 Frédéric Marchal

---

🍓 NOTES 🍓

1. Squid Web Proxy Cache — http://www.squid-cache.org/
2. squidGuard — http://www.squidguard.org/

---

And that's the whole page, bestie. This masterpiece is from sarg, version 12 Nov 2015, and it's SARG(1) — mwah! 💋✨