awffull.conf(5)

📦
version 3.10.2 · 3 versions
, in debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 awffull.conf(5) 💖

okay bestie, welcome to awffull.conf(5) — the manual page for the config file of awffull(1). yes it's long. no we're not skipping anything. grab a snack 🍓

✨ NAME ✨

AWFFull — A Webalizer Fork, Full o' features 👑

🌸 DESCRIPTION 🌸

so awffull.conf is the configuration file for awffull(1). it's a totally standard ASCII(7) text file, which means you can create or edit it with literally any standard editor you vibe with. no fancy tooling required, bestie 💅

Blank lines? ignored. Lines that start with a pound sign (#)? also ignored. they're just little comments living their best life. 🎀

Any other line is a configuration line, and it's shaped like this:

Keyword Value

where the Keyword is one of the currently available configuration keywords, and the Value is the value you're assigning to that particular option. simple as. ✨

⚠️ heads up: any text found after the keyword up to the end of the line counts as that keyword's value. so do NOT put anything after the actual value on that line that isn't genuinely part of the value you're assigning. the parser is not psychic, she just reads to the end of the line. 💀

also, the file sample.conf that ships with the distribution is stuffed with useful documentation and examples — go read it, it's giving tutorial energy 🫶

Some keywords will accept a 2^nd value. when that happens, the first value may be wrapped in double quotes (") so you can sneak whitespace in there. cute, right? 🌈

Keywords are Case Insensitive. Values are Case Sensitive, with some gotchas: see Ignore* for the details. iykyk. 😭

🦋 WILDCARDS 🦋

ngl bestie, wildcards inside AWFFull are a little non standard and they may cause some confusion. let's break it down so you don't get caught out 💀

  • Wildcards are only valid within the Value of certain keywords. that's it. nowhere else.
  • A Value can have either a leading or trailing * to signify a wildcard character. if no wildcard is found, a match can occur anywhere in the string. so given a string www.yourmama.com, all three of these values will match: your, *mama.com, and www.your*. slay. 👑

So basically, using the wildcard is you saying "the other end of this Value is anchored at the Beginning or End of the field we're searching against." ✨

for example 🍓:

  • A Value of Bot* implies that the field (probably UserAgent in this case) MUST start with the letters Bot.
  • Or, in the case of a Hostname, *.gov.au implies a match ONLY against Australian Government hostnames. 🇦🇺

🔥 RUN OPTIONS 🔥

These are the generic ones, bestie. they tell AWFFull where stuff lives and how to generally operate. some of them can even modify the results that AWFFull produces, so pay attention 💅

  • OutputDir — this is where you want the output files to go. it should should be a full path name (yes, the original says "should should", we're keeping it, iconic typo 💀), however relative ones might work as well. if no output directory is specified, the current directory gets used. no cap.
  • LogFile — defines the web server log file to use. if it's not specified here or on the command line, input defaults to STDIN. and if the log filename ends in .gz (ie: a gzip compressed file), it will be decompressed on the fly as it's being read. so convenient fr fr ✨
  • LogType — defines the log type being processed. normally AWFFull expects a CLF or Combined web server log as input. using this option you can also process ftp logs (xferlog as produced by wu-ftpd and others), or Squid native logs. values can be 'auto', 'clf', 'combined', 'ftp', 'domino' or 'squid', with 'auto' as the default. 'auto' means AWFFull will try and work out what log format you're sending it. and if there's no joy? AWFFull will immediately exit. 😭
  • GeoIP — enables or disables the use of the GeoIP capability for more accurate detection of countries. default is 'no'.
⚠️ NOTE! Do not enable GeoIP if you analyse files that have had the IP Address translated to a Fully Qualified Host Name. use either raw IP Addresses and GeoIP, or Names and disable GeoIP. ie. Don't use GeoIP AND DNShistory. pick a lane bestie 🙈
  • GeoIPDatabase — the location of the GeoIP database file. default is /usr/share/GeoIP/GeoIP.dat, which is where a default GeoIP install will put it. note that the database is updated monthly. for the details see: ⟨http://www.maxmind.com/app/geoip_country⟩ 🌈
  • Incremental — incremental processing allows multiple partial log files to be used instead of one huge one. super useful for large sites that have to rotate their log files more than once a month. AWFFull will save its internal state before exiting, and restore it the next time it runs, so it can continue processing exactly where it left off. this mode also causes AWFFull to scan for and ignore duplicate records (records already processed by a previous run). see the README file for additional information. the value may be 'yes' or 'no', with a default of 'no'. the file awffull.current is used to store the current state data, and it lives in the output directory of the program (unless changed with the IncrementalName option below).
🫶 please read at least the section on Incremental processing in the README file before you enable this option. for real.
  • TimeMe — lets you force the display of timing information at the end of processing. a value of 'yes' will force the timing information to be displayed. a value of 'no' has no effect. that's it, that's the whole option ⏱️
  • IgnoreHist — should not be used in a standard configuration, but it's here because it's useful in certain analysis situations. if the history file is ignored, the main index.html file will only report on the current log files contents. Incremental data (if present) is still processed. useful when you want to reproduce the reports from scratch, for example.
⚠️ USE WITH CAUTION! valid values are 'yes' or 'no'. default is 'no'. 💀
  • IncrementalName — lets you specify the filename for saving the incremental data in. it's similar to the HistoryName option where the name is relative to the specified output directory, unless an absolute filename is specified. the default is a file named 'awffull.current' kept in the normal output directory. if you don't specify Incremental as 'yes' then this option has no meaning. 🎀
  • HistoryName — lets you specify the name of the history file produced by AWFFull. the history file keeps the data for up to 12 months worth of logs, used for generating the main HTML page (index.html). the default is a file named awffull.hist, stored in the specified output directory. if you specify just the filename (without a path), it'll be kept in the specified output directory. otherwise, the path is relative to the output directory, unless it's absolute (leading /). 👑

💖 ANALYSIS OPTIONS 💖

okay bestie, these are the basic analysis options — the ones you can, and honestly should, start tweaking so AWFFull is tuned just right for a given website. lowkey the most important section, ngl. 🎀

  • PageType — this is where you tell AWFFull what types of URLs you consider a 'page'. most people count html and cgi documents as pages, and do not count images and audio files. if you specify no types at all, the defaults kick in: 'htm', 'html', 'cgi' and HTMLExtension if it's different for web logs, plus 'txt' for ftp logs. put the more likely page types first in the list to speed up a run. 🏃‍♀️
Do Not Use Wildcards Here. It will not work. 💀
  • NotPageType — the direct and incompatible opposite of PageType. you can use one set or the other, but not both, periodt. PageType says what is a Page, NotPageType says what isn't — and therefore, by implication, everything else is a page. neither method is more or less correct than the other, it's just about which one is more accurate for your site. do not add the "." and don't use any wildcards. as a general rule. there are some assumed internal optimisations that may otherwise break. 👀 those who understand pcre's would do well to examine the source of parser.c if they want to extract greater flexibility from the below.
  • FoldSeqErr — makes AWFFull ✨ignore sequence errors✨. super useful for Netscape and other web servers that cache the writing of log records and don't guarantee they'll be in chronological order. using this option means out of sequence log records get treated as if they had the same time stamp as the last valid record. the default action is to just ignore out of sequence log records.
  • SearchEngine — these keywords let you specify search engines and their query strings on the URL. AWFFull uses them to locate and report what search strings were used to find your site. the first word is a substring to match in the referrer field that identifies the search engine, and the second is the URL variable that search engine uses to define its search terms. 🔍
  • VisitTimeout — sets the default timeout for a visit (sometimes called a 'session'). default is 30 minutes, which should be fine for most sites. visits are figured out by looking at the time of the current request and the time of the last request from the site. if the time difference is greater than the VisitTimeout value, it counts as a new visit and visit totals get incremented. the value is the number of seconds to timeout (default=1800=30min). ⏰
  • TrackPartialRequests — used to track 206 codes. this gives you two extra columns in the Top URLs tables: the first adds to "Hits" and counts the number of partial requests, the second adds to "Volume" and counts the volume in partial requests. this option is more of use to those with lots of PDF's. 📄
  • MangleAgents — lets you say how much, if any, AWFFull should mangle user agent names, so you get several levels of detail when reporting user agent statistics. there are six levels you can specify, defining different levels of detail suppression:
    • Level 5 shows only the browser name (MSIE or Mozilla) and the major version number.
    • Level 4 adds the minor version number (single decimal place).
    • Level 3 displays the minor version to two decimal places.
    • Level 2 adds any sub-level designation (such as Mozilla/3.01Gold or MSIE 3.0b).
    • Level 1 will attempt to also add the system type if it is specified.
    • the default Level 0 displays the full user agent field without modification and produces the greatest amount of detail.

user agent names that can't be mangled will be left unmodified. 🕵️‍♀️

  • AssignToCountry — a form of override that forces given domains to a specified country. use the standard 2 letter country codes. you can also use org, com, net and so on, if that's more appropriate. with judicious use of AllSites, GroupSite and 'whois', this can cover the majority of your users without too much effort. 🌍
  • IndexAlias — AWFFull normally strips the string 'index.' off the end of URLs to consolidate URL totals. for example, the URL /somedir/index.html gets turned into /somedir/, which is really the same URL. this option lets you specify additional strings to treat the same way. you don't need to specify 'index.' since it's always scanned for by AWFFull — this option is just for extra strings if you need them. if you don't need any, don't specify any, because each string gets scanned for in EVERY log record... a bunch of them will degrade performance. 😭 also, the string is scanned for anywhere in the URL, so a string of 'home' would turn the URL /somedir/homepages/brad/home.html into just /somedir/, which is probably not what was intended.
  • IgnoreIndexAlias — the opposite (in a way) of IndexAlias. this will STOP any URL variable stripping, and it also ignores the default "index." setting, or any that you set above. 🙅‍♀️

🚫 IGNORE* OPTIONS 🚫

the Ignore* keywords let you completely ignore, or filter away, log records based on hostname, URL, user agent, referrer or user name. use the same syntax as the Hide* keywords, where the value can have a leading or trailing wildcard '*'. ✨

  • IgnoreURL — filters out traffic accessing certain URLs. eg you may wish to avoid seeing traffic that accesses administration functions, thus "IgnoreURL /admin*". URLs are case sensitive. 🔒
  • IgnoreSite — ignore sites that visit this website. ignore by what is presented to awffull — name or IP Address. sites are lowercased prior to filtering, so if you're Ignore'ing by name, do use a lowercased Value.
  • IgnoreReferrer — ignore specified referrers. very useful for filtering away SPAM Referrers. 🗑️ referrers are partially case sensitive. \o/ the host portion is lowercased; the URI is case sensitive.
  • IgnoreUser — ignore specified users. user names are lowercased prior to filtering.
  • IgnoreAgent — Agents are case sensitive.

✅ INCLUDE* OPTIONS ✅

the Include* keywords let you force the inclusion of log records based on hostname, URL, user agent, referrer or user name. the Include* keywords take precedence over the Ignore* keywords. 👑

Note: Using Ignore/Include combinations to selectively process parts of a web site is extremely inefficient!!! Avoid doing so if possible ie: grep or gawk the records to a separate file if you really want that kind of report. 💀
  • IncludeURL
  • IncludeSite
  • IncludeReferrer
  • IncludeUser
  • IncludeAgent

🧚 SEGMENTING OPTIONS 🧚

Segmenting is a bit like the Ignore* and Include* keywords. where it differs is in "remembering". such that, as a 'session' (or 'visit') moves away from the original entry condition, that session is still tracked. so if you segment on a referral from Google, only sessions that were referred to the analysed website, from Google, will be tracked. even as that same session accesses other pages within the website. 🌈

eg. Google -> Site Page 1 -> Site Page 2 -> Site Page 3

Whereas Ignore/Include would only filter the first interaction. eg. Google -> Site Page 1

By "session" (or 'visit') it is meant that the time limitation of a session (typically 30 minutes timeout) will impact. so in the above example from Google, if the last step (from Page 2 to Page 3) occurred 31+ minutes after the Page 1 to Page 2 transition, then this final step would NOT be included. the trail would be:

Google -> Site Page 1 -> Site Page 2

Please do be aware that currently AWFFull uses IP Addresses to determine the continuation of a given session. this will be most flawed if you have a user population that sits behind corporate firewalls, or ISP Proxies. to mention two major problem areas. 😬

Why do Segmenting?

http://judah.webanalyticsdemystified.com/2007/11/a-few-tips-on-web-analytics-segmentation.html

'Segment analysis will tell you different things about your audience than you will realize from studying overall population metrics.'
'The goal of segmentation is to maximize future value of that segment by optimizing your marketing mix.'

With apologies to Judah for mixing his phrase order around. :-) 🫶

  • SegCountry — Segment by Country: only track sessions that come from the following countries. this will be determined by:
    1. Use of AssignToCountry overrides
    2. GeoIP lookups if so configured and enabled
    3. Hostname TLD. eg .au

the third option is generally going to be the worst for accuracy. eg. we have plenty of Australian IP addresses that otherwise resolve to .com or .net etc.

it is strongly advised to enable GeoIP if you wish to use this option. 🌏

  • SegReferer — Segment by Referer: only track sessions that originated from the following referers. NOTE!!!! SegReferer only works against the HOST name. Not the full URL. 🔗

✨ DISPLAY OPTIONS ✨

okay so these are the glow-up options bestie 💅 they change what AWFFull actually shows you — HTML headers, footers, cute little things added to every page. They don't touch the numbers AWFFull calculates, but they might change which ones show up, which gives the illusion of a numerical change. Sneaky? A little. Iconic? Also yes. 👑

  • ReportTitle — the text that shows up as the title, periodt. The hostname gets appended to the end of this string (separated by a space) to build the final full title string — unless it's blank, in which case nah. Default is (for English) ‘Usage Statistics for’.
  • HostName — sets the hostname for the report, bestie. It's used in the title, and it gets prepended to the URL table items. This is the way that clicking on URLs in the report goes to the proper location, in case you're running the report on a 'virtual' web server, or a server that's different from the one the report lives on. If you don't specify it here or on the command line, AWFFull tries to grab the hostname via a uname system call. If that fails, it defaults to ‘localhost’. 🏠
  • IndexMonths — controls how many years worth of data to display on the front summary page. In months, iykyk. eg: display the last 5 years: 5 x 12 = 60. math girlies rise 🧮
  • DailyStats — lets the daily statistics table be disabled (aka not displayed at all, ghosted 👻). Values can be ‘yes’ or ‘no’. Default is ‘yes’ — do display the Daily Statistics table.
  • HourlyStats — HourlyGraph and HourlyStats let the hourly statistics graph and statistics table be disabled (not displayed). Values can be "yes" or "no". Default is "yes".
  • CSSFilename — sets the name of the CSS file to use alongside the generated html. An existing file is not overwritten, so feel free to make your own changes to the default file, no cap 🎀 The default is awffull.css.
  • FlagsLocation — enables the display of country flag pictures in the country table 🏳️ The path is the one for a webserver, not the file system. Can be relative or complete. The trailing slash is not necessary. The default location is not set and hence will not be used.
  • YearlySubtotals — displays the subtotal for a given year in the main page. This is in addition to the Grand Total of all years. extra credit energy ✨
  • GroupShading — allows grouped rows to be shaded in the report. Super useful if you have lots of groups and individual records that intermingle in the report and you want to differentiate the group records a little more. Value can be ‘yes’ or ‘no’, with ‘yes’ being the default.
  • GroupHighlight — allows the group record to be displayed in BOLD 💪 Can be either ‘yes’ or ‘no’, with the default being ‘yes’.
  • HTMLExtension — lets you specify the filename extension to use for generated HTML pages. Normally this defaults to "html", but it can be changed for sites who need it (like for PHP embedded pages, iykyk).
  • UseHTTPS — use this if the analysis is being run on a secure server and links to urls should use ‘https://’ instead of the default ‘http://’ 🔒 If you need this, set it to ‘yes’. Default is ‘no’. This only changes the behaviour of the ‘Top URLs’ table. that's it, that's the whole vibe.
  • Top* — the various ‘Top’ options below define the number of entries for each table. Tables may be disabled by using zero (0) for the value. zero = ghosted, we love that for them 💀

🌈 The Top Tables 🌈

  • TopURLs — the most accessed URLs or Resources by number of requests (hits). Includes both Pages and Images, for example. Defaults to 30 URLs.
  • TopKURLs — the greatest volume generating URLs. Defaults to 10 URL's.
  • TopEntry — the most accessed initial URLs within a complete Visit. Will also display Single Access counts, Stickiness ration and Popularity ratio. Defaults to 10 URLs.
  • TopExit — the most accessed last URLs within a complete Visit. ie: the last page recorded of a Visit. Also displays the Popularity ratio. Defaults to 10 URLs.
  • Top404Errors — the most seen error requests and a corresponding referring URL. Defaults to 0, ie not shown.
  • TopSites — those Sites that have accessed the most Pages. Default is 30 Sites.
  • TopKSites — those Sites that have downloaded the greatest Volume. Default is 10 Sites.
  • TopReferrers — those local and remote URLs that refer the most requests. Default is 30 Referrers.
  • TopSearch — those words and phrases used at remote Search Engines to direct traffic here. Default is 20 Phrases.
  • TopUsers — those logged in users who most use the site. Default is 20 Users.
  • TopAgents — the Browser Agents that are busiest against this site. Default is 15 Agents.
  • TopCountries — a view of all traffic against this site via country. 🌍

💖 The All* Options 💖

  • All* — the All* keywords allow the display of all the below measures. If enabled, a separate HTML page will be created, and a link will be added to the bottom of the appropriate "Top" table. there are a couple of conditions for this to occur, bestie, so listen up 👂 First, there must be more items than will fit in the "Top" table (otherwise it would just be duplicating what is already displayed). Second, the listing will only show those items that are normally visible, which means it will not show any hidden items. Grouped entries will be listed first, followed by individual items. The value for these keywords can be either 'yes' or 'no', with the default being 'no'.
⚠️ heads up: please be aware that these pages can be quite large in size, particularly the sites page, and separate pages are generated for each month, which can consume quite a lot of disk space depending on the traffic to your site. disk girlies, beware 😭
  • AllURLs — All accessed URLs
  • AllEntryPages — All Pages that initialised a Visit
  • AllExitPages — All the last or exit pages in all Visits.
  • All404Errors — All ErrorRequests and the corresponding referral URLs.
  • AllSites — All remote sites that accessed this website.
  • AllReferrers — All local and remote referring URLs
  • AllSearchStr — All Remote Search Engine words and Phrases used to refer traffic here.
  • AllUsers — All users who logged into this website.
  • AllAgents — All Browser Agents used to access this site. Useful for identifying robots 🤖 lowkey my fave use case.

🦋 Time & HTML Vibe Options 🦋

  • GMTTime — allows reports to show GMT (UTC) time instead of local time. Default is to display the time the report was generated in the timezone of the local machine, such as EDT or PST. This keyword lets you have times displayed in UTC instead. Use only if you really have a good reason, since it will probably screw up the reporting periods by however many hours your local time zone is off of GMT 😬 no cap, be careful.
  • HTMLPre — defines HTML code to insert at the very beginning of the file. Default is the DOCTYPE line shown below. Max line length is 80 characters, so use multiple HTMLPre lines if you need more.
  • HTMLHead — defines HTML code to insert within the <HEAD></HEAD> block, immediately after the <TITLE> line. Maximum line length is 80 characters, so use multiple lines if needed.
  • HTMLBody — defines the HTML code to be inserted, starting with the <BODY> tag. If not specified, the default is shown below. If used, you MUST include your own <BODY> tag as the first line. Maximum line length is 80 char, use multiple lines if needed.
  • HTMLPost — defines the HTML code to insert immediately before the first <HR> on the document, which is just after the title and "summary period"-"Generated on:" lines. If anything, this should be used to clean up in case an image was inserted with HTMLBody. As with HTMLHead, you can define as many of these as you want and they will be inserted in the output stream in order of appearance. Max string size is 80 characters. Use multiple lines if you need to.
  • HTMLTail — defines the HTML code to insert at the bottom of each HTML document, usually to include a link back to your home page or insert a small graphic. It is inserted as a table data element (ie: <TD> your code here </TD>) and is right aligned with the page. The maximum string size is 80 characters.
  • HTMLEnd — defines the HTML code to add at the very end of the generated files. It defaults to what is shown below. If used, you MUST specify the </BODY> and </HTML> closing tags as the last lines. The maximum string length is 80 characters.
🫶 friendly reminder that "shown below" is doing a lot of heavy lifting in these descriptions — the defaults are displayed further down in the docs, so don't come for me, I'm just the messenger 💜

✨ GRAPHING OPTIONS ✨

okay so real talk — these are not the same as the general Display Options bestie. Display Options is the whole vibe, Graphing Options is specifically about ✨manipulating the graphs✨ that get produced. two different departments, both iconic 🎀

  • CountryGraph — lets you disable the usage-by-country graph entirely. values can be 'yes' or 'no', and the default is 'yes' 💖
  • DailyGraph — decides whether the daily statistics graph gets displayed or not. values may be "yes" or "no". default is "yes" — so yes, do display the daily graph, it's giving data ✨
  • HourlyGraph — decides whether the daily statistics graph gets displayed or not. values may be "yes" or "no". default is "yes" — do display the hourly graph 🕐
  • TopURLsbyHitsGraph — display a pie chart of the top URLs by HITS 🥧
  • TopURLsbyVolGraph — display a pie chart of the top URLs by HITS 🥧 (yes, that's what it says, we don't ask questions, we just report)
  • TopExitPagesGraph — display the Top Exit Pages Pie Chart. values may be ‘hits’ or ‘visits’ or "no". default is "no" 🚪
    • ‘hits’ means order the graph by hits
    • ‘visits’ means order the graph by visits
  • TopEntryPagesGraph — display the Top Entry Pages Pie Chart. values may be ‘hits’ or ‘visits’ or "no". default is "no" 🚪
    • ‘hits’ means order the graph by hits
    • ‘visits’ means order the graph by visits
  • TopSitesbyPagesGraph — display a pie chart of the Top Sites by Page Impressions 🥧
  • TopSitesbyVolGraph — display a pie chart of the Top Sites by Page Impressions 🥧
  • TopAgentsGraph — display a pie chart of the Top User Agents (by pages) 🤖
  • GraphLegend — turns the color coded legends on or off in the graphs. default is for them to be displayed. heads up tho — this only toggles the color coded legends, the other legends are not changed. and if you think they are hideous and ugly, just say 'no' here :) 💀
  • GraphLines — lets you have index lines drawn behind the graphs. anything other than "no" will enable the lines 📏
  • Graph*X and Graph*Y — these options modify the sizes of the created charts. the default settings are shown below, and the defaults are also the minimum settings. no going smaller than iconic, bestie 🫶
#define GRAPH_INDEX_X 512   /* px. Default X size (512) */
#define GRAPH_INDEX_Y 256   /* px. Default Y size (256) */
#define GRAPH_DAILY_X 512   /* px. Daily X size (512) */
#define GRAPH_DAILY_Y 400   /* px. Daily Y size (400) */
#define GRAPH_HOURLY_X 512  /* px. Daily X size (512) */
#define GRAPH_HOURLY_Y 400  /* px. Daily Y size (400) */
#define GRAPH_PIE_X 512     /* px. Pie X size (512) */
#define GRAPH_PIE_Y 300     /* px. Pie Y size (300) */
  • GraphIndexX — the main chart on the front page. Summary of all Months. default is 512 pixels 📊
  • GraphIndexY — default is 256 pixels 📊
  • GraphDailyX — the Day by Day Summary graph at the start of each Months Summary. default is 512 pixels 📊
  • GraphDailyY — default is 400 pixels 📊
  • GraphHourlyX — the Hourly Average graph within each Months Summary. default is 512 pixels 📊
  • GraphHourlyY — default is 400 pixels 📊
  • GraphPieX — all pie charts are the same size. default is 512 pixels 🥧
  • GraphPieY — default is 300 pixels 🥧

🎨 Graph and Table Colours 🎨

the custom bar graph and pie Colours can be overridden with these options. declare them the standard hexadecimal way — as per HTML but without the '#'. if none are given, you will get the default AWFFull colors. customizing your palette is such main character energy 💅

  • ColorHit — default value is ‘00805C’ (dark green) 💚
  • ColorFile — default value is ‘0000FF’ (blue) 💙
  • ColorSite — default value is ‘FF8000’ (orange) 🧡
  • ColorKbyte — default value is ‘FF0000’ (red) ❤️
  • ColorPage — default value is ‘00E0FF’ (cyan) 🩵
  • ColorVisit — default value is ‘FFFF00’ (yellow) 💛
  • PieColor1 — default value is ‘00805C’ (dark green) 💚
  • PieColor2 — default value is ‘0000FF’ (blue) 💙
  • PieColor3 — default value is ‘FF8000’ (orange) 🧡
  • PieColor4 — default value is ‘FF0000’ (red) ❤️

👯 GROUP* OPTIONS 👯

okay so the Group* keywords let you group similar objects as if they were one. grouped records show up in the ‘Top’ tables and can optionally be displayed in bold and/or shaded. groups cannot be hidden, and are not counted in the main totals. 🌈

and listen — the Group* options do not hide the individual items that are members of the Group. if you wish to hide the records that match — so just the grouping record is displayed — follow with an identical Hide* keyword with the same value. or, be lazy in the best way, and use the single GroupAndHide* keyword that matches, instead of the Group* and Hide* combination. efficiency queen 👑

Group* keywords may have an optional label which will be displayed instead of the keywords value. the label should be separated from the value by at least one white-space character, such as a space or tab. ✨

okay and here's the big picture recap, because it matters: the Hide*, Group*, Ignore* and Include* keywords allow you to change the way Sites, URL's, Referrers, User Agents and User names are manipulated. the Ignore* keywords will cause AWFFull to completely ignore records as if they didn't exist (and thus not counted in the main site totals). the Hide* keywords will prevent things from being displayed in the 'Top' tables, but will still be counted in the main totals. the Group* keywords allow grouping similar objects as if they were one. grouped records are displayed in the 'Top' tables and can optionally be displayed in BOLD and/or shaded. groups cannot be hidden, and are not counted in the main totals. the Group* options do not, by default, hide all the items that it matches. if you want to hide the records that match (so just the grouping record is displayed), follow with an identical Hide* keyword with the same value. (see example below 👀) in addition, Group* keywords may have an optional label which will be displayed instead of the keywords value. the label should be separated from the value by at least one 'white-space' character, such as a space or tab.

the value can have either a leading or trailing '*' wildcard character. if no wildcard is found, a match can occur anywhere in the string. given a string ‘www.yourmama.com’, the values ‘your’, ‘*mama.com’ and ‘www.your*’ will all match. wildcards stay undefeated fr fr 🔥

  • GroupURL
  • GroupSite
  • GroupReferrer
  • GroupUser
  • GroupAgent
  • GroupDomains — this one lets you group individual host names into their respective domains. the value specifies the level of grouping to perform, and can be thought of as 'the number of dots' that will be displayed. for example, if a visiting host is named cust1.tnt.mia.uu.net, a domain grouping of 1 will result in just "uu.net" being displayed, while a 2 will result in "mia.uu.net". the default value of zero disables this feature. domains will only be grouped if they do not match any existing "GroupSite" records, which allows overriding this feature with your own if desired. so polite, so respectful 💖

🙈 HIDE* OPTIONS 🙈

the Hide* keywords will prevent things from being displayed in the 'Top' tables. but — and this is important — the hidden items will still be counted in the main totals. they're not gone bestie, they're just not on the mood board 🎀

  • HideURL — hide URL matching name.
  • HideSite — hide site matching name.
  • HideReferrer — hide referrer matching name.
  • HideUser
  • HideAgent — hide user agents matching name.
  • HideAllSites — allows forcing individual sites to be hidden in the report. this is particularly useful when used in conjunction with the "GroupDomain" feature, but could be useful in other situations as well — such as when you only want to display grouped sites (with the GroupSite keywords...). the value for this keyword can be either 'yes' or 'no', with 'no' the default, allowing individual sites to be displayed. 🌸

🫶 GROUPANDHIDE* OPTIONS 🫶

all the Hide and Group "name" options can be combined in a single config line. eg GroupAndHideURL. if you start using the Group* options you will find that you tend to match every Group* option with a corresponding Hide* option. the GroupAndHide* options simply short circuit this unnecessary duplication. say it with me: we love a shortcut 💅

  • GroupAndHideURL
  • GroupAndHideSite
  • GroupAndHideReferrer
  • GroupAndHideUser
  • GroupAndHideAgent

📦 DATA DUMP OPTIONS 📦

the Dump* keywords allow the dumping of Sites, URL's, Referrers, User Agents, User names and Search strings to separate tab delimited text files, suitable for import into most database or spreadsheet programs. spreadsheet girlies rise up 🍓

  • DumpPath — specifies the path to dump the files. if not specified, it will default to the current output directory. do not use a trailing slash ('/') 🚫
  • DumpHeader — specifies if a header record should be written to the file. a header record is the first record of the file, and contains the labels for each field written. normally, files that are intended to be imported into a database system will not need a header record, while spreadsheets usually do. value can be either 'yes' or 'no', with 'no' being the default. ✨
  • DumpExtension — lets you specify the dump filename extension to use. the default is "tab", but some programs are picky about the filenames they use, so you may change it here (for example, some people may prefer to use "csv"). 🙄
  • DumpURLs
  • DumpEntryPages
  • DumpExitPages
  • DumpSites
  • DumpReferrers
  • DumpSearchStr
  • DumpUsers
  • DumpAgents
  • DumpCountries

💖 EXAMPLES 💖

okay bestie this is the part where it all clicks. two whole real-life configs, straight from the source, so you can see the vibes in action. ✨

🍓 Sample Extract of a configuration file

like, just a lil taste. a nibble. the amuse-bouche of awffull.conf:

# The 'auto' value means that AWFFull will try and work out what log format
# you are sending to it. If no joy, AWFFull will immediately exit.

LogType        auto

# OutputDir is where you want to put the output files.  This should
# should be a full path name, however relative ones might work as well.
# If no output directory is specified, the current directory will be used.

OutputDir      .

so LogType set to auto = AWFFull does the detective work on your log format itself, and if it can't figure it out, it's out, immediately, no notes. 🚪 And OutputDir is where your pretty reports land — full path is the move, relative ones might work, and if you say nothing at all, it just chills in the current directory. lowkey convenient.

🎀 Minimal configuration file

this is the bare minimum. the "I just want it to work" starter pack. the rest of the options are just there if the below only serves to whet your appetite. 🍽️

# Sample *MINIMAL* AWFFull configuration file
#
# The below settings are the only ones you *really* need to worry about
# when configuring AWFFull. See the sample.conf file for all options if
# the below only serves to whet your appetite.
#
# See awfful(1) or sample.conf for full explanations.

# We can do a little bit each day, or hour...
Incremental             yes

# Your server name to display
HostName                www.my_example.site

##---------------------------
# Use PageType OR NotPageType
# I personally prefer NotPageType - YMMV!
PageType                htm
PageType                html
PageType                php
#PageType               pl
#PageType               cfm
#PageType               pdf
#PageType               txt
#PageType               cgi
### OR! ---------------------
#NotPageType            gif
#NotPageType            css
#NotPageType            js
#NotPageType            jpg
#NotPageType            ico
#NotPageType            png
##---------------------------

# Should always fold in Sequence Errors. Logs can be messy...
FoldSeqErr              yes

# If you want to see the country flags, uncomment the following.
# This is the, possibly relative, URL where the flag flies are located.
#FlagsLocation          flags

.fi

the way this config is giving main character energy with zero effort 💅 — Incremental yes so you can do a lil bit each day or hour, HostName for your server's name on the report, then the great PageType / NotPageType showdown (you pick one camp, not both — the config itself says it prefers NotPageType, YMMV!). And FoldSeqErr yes is basically mandatory because logs are messy, fr fr. 🫠

🚨 note the ##--------------------------- block: it's PageType OR NotPageType. pick a lane, bestie. not both.

and if you want those lil country flags to show up, uncomment FlagsLocation — that's the possibly-relative URL where the flag files live. 🌍🏳️

👑 SEE ALSO 👑

  • awffull(1) — the big one. go read it. it's iconic. ✨

💀 BUGS 💀

None currently known. YMMV....

ngl a manpage that says "no known bugs" is either very brave or very lucky, and I respect it either way. 😭

Report bugs to ⟨https://bugs.launchpad.net/awffull⟩, or use the email discussion list: awffull@stedee.id.au

🧚 NOTES 🧚

In case it is not obvious: AWFFull is a play/pun on the word ‘awful’, and is pronounced the same way. Yes it was deliberate.

okay so the whole thing is a pun. it was on purpose. the author knew exactly what they were doing and honestly? obsessed. 🎀

📚 REFERENCES 📚

[1] Web Site Measurement Hacks. Eric T. Peterson (and others). O'Reilly. ISBN 0-596-00988-7.

and that's the whole page, bestie!! 🦋 you made it to the end of awffull.conf(5) — go forth and configure your little heart out. this one's from the 2008-Dec-13 era, awffull fam, so give it the respect it deserves. mwah. 💖✨

📦 where this page comes from