mmstatd.8

mmstatd包含一个 C库和服务器

.\" $Id: mmstatd.8,v 1.3 2003/01/10 03:52:36 mmondor Exp $
.\"
.\" Copyright (C) 2002-2003, Matthew Mondor
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. 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.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"      This product includes software written by Matthew Mondor.
.\" 4. The name of Matthew Mondor may not be used to endorse or promote
.\"    products derived from this software without specific prior written
.\"    permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY MATTHEW MONDOR ``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 MATTHEW MONDOR 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.
.\"
.Dd 11 Dec, 2002
.Dt MMSTATD 8
.Os
.Sh NAME
.Nm mmstatd
.Nd
Statistics librarian and logger daemon with recovery and transaction support
.Sh SYNOPSIS
.Nm mmstatd Op Ar config_file
.Sh DESCRIPTION
.Nm mmstatd
consists of a statistics librarian daemon used by the familly of
mm utilities (mmmail, mmftpd, etc). It simply allows applications to record
statistical information using a key-based system. It also supports transactions
and crash recovery logging. Moreover, it features volatile and consistant
database entries, with creation and modification timestamps.
.Pp
The main reason why I wrote it was because syslog does not consist of an
ideal approach to count statistics, and that using an SQL server for this
is overkill, especially with required SQL commands parsing and atomic-safe
transaction locks. db4 could have been more efficient, but it is quite easy
to rival with it according to size. The size of mmstatd and mmstat library is
very small, and it's performance is decent. Moreover a database server would
consider all keys as persistant storage, when a requirement for both
persistant and volatile ones was met.
.Pp
.Nm The way it works
.Pp
Basically, it starts up two asynchroneous processes, the librarian and logger.
.Pp
The librarian is responsible for managing the database and affecting changes
while asynchroneously reading available logs. It also permits obtention of
statistics report connecting to a Unix domain stream socket. The librarian
synchronizes the memory database to disk every once in a while, recording
the current position in the logs, and deleting obsolete, already synchronized
logs when required. This synchronization to disk is only performed at large
time intervals, to minimize CPU and drive load, and maximise responsiveness.
The librarian also establishes a listening UNIX stream socket, to serve
reports and rotation requests.
.Pp
The logger, in turn, listens to a Unix datagram socket, and writes the logs,
syncing them to disk frequently enough, for both the librarian and logger.
This allows the logs to be used for recovery of persistant modifications that
were performed since the last full database sync. Moreover, it permits the
clients to always be able to send more packets without being subject to the
librarian processing, avoiding a bottleneck.
.Pp
Every time mmstatd is started, it first ensures to run with normal user
privileges, then looks for recovery logs and performs necessary modifications
to the database, before forcing a sync of the new database to disk, deleting
all recovery logs. It then launches the two asynchroneous processes which then
become ready to serve their tasks.
.Pp
Using this design allows applications to use a simple syslog-like API to
update statistics, in a very fast manner. For the various mm daemons, it
serves as a who database, using volatile storage, and as various statistical
tasks using persistant storage.
.Pp
The logging socket, used to send update requests, as well as the status socket,
are independant and can have specific permissions, so that only applications
who should access the service may. The user application interface library is
quite simple to use by programs wanting to keep their statistics using mmstatd.
See the
.Xr mmstat 3
man page for more information.
.Pp
.Sh INSTALLATION
.Nm mmstatd
is installed by the make.sh scripts of both
.Nm mmftpd
and
.Nm mmmail
by Matthew Mondor. It's administration is made through
.Nm /etc/mmstatd.conf
(See
.Xr mmstatd.conf 5
man page) and
.Nm mmstat
(See
.Xr mmstat 8
man page).
.Pp
Here is an overview of standard permissions various files should have:
.Pp
.Bd -literal -offset indent -compact
Permissions Owner    Group   File

-rwxr-x---  root     staff   /usr/local/sbin/mmstat
-rwx------  root     wheel   /usr/local/sbin/mmstatd

drwxr-x---  mmstatd  mmstat  /var/mmstatd

s-w--w----  mmstatd  mmstat  /var/mmstatd/mmstatd_log.sock
srw-rw----  mmstatd  staff   /var/mmstatd/mmstatd_stat.sock
.Ed
.Pp
Basically, the administrator will need access to
.Nm mmstat
binary as well as to both
.Nm /var/mmstatd/*.sock
files. Applications using the
.Xr mmstat 3
facility require access to the
.Nm /var/mmstatd/mmstatd_log.sock
file only. Only uid zero should have access to
.Nm /var/mmstatd
directory and
.Nm mmstatd
daemon.
.Pp
.Nm mmstatd
should normally be started before any other daemons using the
.Xr mmstat 3
interface. Although this is not obligatory, it is highly
recommended. As it will take the time to perform recovery before calling
.Xr fork 2
other daemons will have a clean and ready daemon to serve their requests,
so a startup script typically would use something like:
.Pp
.Bd -literal -offset indent -compact
/usr/local/sbin/mmstatd
/usr/local/sbin/mmftpd
/usr/local/sbin/mmsmtpd
/usr/local/sbin/mmpop3d
.Ed
.Sh FILES
.Bl -tag -width XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -compact
.It Pa /etc/mmstatd.conf
This file consists of the configuration file for
.Nm mmstatd
and controls all it's configurable parameters.
.Pp
.It Pa /var/mmstatd
The mmstat environment directory, where recovery logs and database file are
located. The default configuration also stores UNIX domain sockets there.
.Pp
.It Pa /var/mmstatd/mmstatd_stat.sock
The UNIX stream socket on which listens
.Nm mmstatd
librarian process, used by the administrator via
.Nm mmstat
binary to query statistical reports and request key rotations.
.Pp
.It Pa /var/mmstatd/mmstatd_log.sock
The UNIX datagram socket on which listens
.Nm mmstatd
logger process, used by all applications using the
.Xr mmstat 3
interface to update statistics.
.Pp
.It Pa /var/mmstatd/mmstatd.db
The database file used to permanently store persistant storage statistical
keys. When a disk synchronization occurs, a temporary file is used to save
the database on the same filesystem, and
.Xr rename 2
is used to move it over this file in an atomic manner.
.Pp
.It Pa /var/mmstatd/????????.log
Log files internally used and automatically maintained by
.Nm mmstatd
for crash recovery.
.Pp
.It Pa /usr/local/sbin/mmstatd
The actual daemon binary documented by
.Xr mmstatd 8
.Pp
.It Pa /usr/local/sbin/mmstat
The administration utility documented by
.Xr mmstat 8
.El
.Sh ENVIRONMENT
.Bl -tag -width XXXXXXXXXX
.It Pa Nm MMSTATCONF
If set, specifies the absolute location of the configuration file to load
instead of the default
.Nm /etc/mmstatd.conf .
If a configuration file name is specified on the command line, it will
override this environment variable even if it was set.
.El
.Sh AUTHOR
The suite of mmstat daemon, related utilities and documentation were written
by Matthew Mondor, and are
Copyright (c) 2002-2003, Matthew Mondor, All rights reserved.
They were developped
under NetBSD 1.5.3 for the mmftpd and mmmail suite of daemons from the same
author.
.Sh SEE ALSO
.Xr mmstat 3 ,
.Xr mmstatd.conf 5 ,
.Xr mmstat 8 ,
.Xr rename 2 ,
.Xr fork 2 ,
.Xr unix 4 .
.Sh BUGS
The internal format of the log files and database file are not
endian-independant and will therefore only remain useable on architectures
using the same endian format. Of course it would be possible to use
.Xr mmstat 8
utility to perform exportation and importation to a new system for the time
being.  This will eventually change and an endian-independant format will
be used.