Setting up your BSD machine with bsdstats

Peter N. M. Hansteen

peter@bsdly.net

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS DOCUMENTATION IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Table of Contents
Introducing BSDstats
Setting up BSDstats on FreeBSD
Setting up BSDstats on OpenBSD
Setting up BSDstats on other BSD systems
Want to help improve this document?

Introducing BSDstats

The BSDStats project was started in August of 2006 by FreeBSD developer Marc Fournier and others with its stated mission to

"… compile semi-accurate numbers for advocacy and marketing of the *BSD operating systems.
More specifically, we are trying to demonstrate to hardware and software vendors out there that *BSD should be viewed as a serious operating system, not just as a hobbyist system, for support (ie. hardware drivers) purposes."

The statistics generation and collection is implemented as a shell script which is intended to be run periodically, reporting the specified statistics to the bsdstats.org servers once a month.

The initial development was done on FreeBSD and was soon made rather painless when the 300.statistics script was rolled into a port for that operating system. The present mini-guide is an attempt to make it easier for users of other BSD system to set up and maintain reporting on their systems.

Setting up BSDstats on FreeBSD

Getting started with BSDstats on FreeBSD is easy, thanks to the port /usr/ports/sysutils/bsdstats. The port drops the 300.statistics script into your /usr/local/etc/periodic/monthly directory, where the periodic(8) system will find it and execute it in due course. The port also adds the necessary variables to your /etc/periodic.conf.

To set up statistics reporting on your FreeBSD system:

Make sure your ports tree is up to date, using your favourite updating tool such as cvsup(1) or portsnap(8)
Install the port. The port installation script will prompt you for options such as whether you want it to edit your /etc/periodic.conf to enable the script and offer to run the reporting immediately after its infrastructure has been set up.

Once the script is properly included in the periodic(8) system infrastructure, it will be executed at the proper one-month interval. You may want to upgrade the script to newer versions occasionally, just like you would other installed ports.

Setting up BSDstats on OpenBSD

OpenBSD does not have the periodic system, but instead has the /etc/daily, /etc/weekly and /etc/monthly scripts, all of which are executed at the corresponding intervals from root's crontab[1].

The daily, weekly and monthly scripts will run the contents of corresponding .local files, so to run the bsdstats script once a month you either

create an /etc/monthly.local script which calls the 300.statistics script,
or, if the the 300.statistics script is the only local script you want to run each month, copy 300.statistics to /etc/monthly.local.

The bsdstats script depends on the setting of some environment variables which on FreeBSD are kept in /etc/periodic.conf. On OpenBSD, the place for locally defined system variables is /etc/rc.conf.local, where you put the lines

    monthly_statistics_enable="YES" # needed for bsdstats to work at all
    monthly_statistics_report_devices="YES" # optionally report devices too

As indicated by the comments, only the first of those is mandatory for the script to work; the second lets you submit hardware information too if you want to.

With a valid /etc/monthly.local script which runs the statistics script and the /etc/rc.conf.local lines in place, you can either sit back and wait for the monthly script to execute at some point in the future or run the script manually.

Setting up BSDstats on other BSD systems

Download the script to /usr/local/sbin, and add a cron entry, as root, to run the script once per month, similar to:

59 00 1 * * /usr/local/sbin/300.statistics

The following variables can be set in /etc/rc.conf.local to enable the statistics, as well as fine tune various parts of it:

    * monthly_statistics_enable="YES"
    * monthly_statistics_report_devices="YES"

After downloading, run it once initially.

Want to help improve this document?

This document is a first draft. If you find it needs improvement, please feel free to send your comments to <peter@bsdly.net>. The document itself is written as a DocBook SGML "book", much like the FreeBSD Handbook.