mvmf: mvmcas man page
mvmf: mvmcas man page
MVMCAS(1) General Commands Manual MVMCAS(1)
NAME
mvmcas - mvmf's mail client assessment server
SYNOPSIS
mvmcas [-C configuration-file] [-h hostname] [-T host[:[port]]] [-U host[:[port]]] [-v] [-x]
DESCRIPTION
mvmcas is a server that is consulted by SMTP receivers (e.g., mvmtr).
The server may provide hints about how to treat a mail client, and the
SMTP receiver (and other sources) may provide feedback about the behav-
iour of a client. mvmcas will adjust its hints according to the feed-
back it gets.
Options which may be given are as follows:
-C configuration-file
The name of a configuration file to use instead of the default.
-h hostname
The name of the local host.
-T host[:[port]]
Start a TCP service on the specified local host and port.
-U host[:[port]]
Start a UDP service on the specified local host and port.
-v prints mvmcas's version number. The version number has three
decimal parts separated by periods: first a major version number,
next a minor version number, and finally a fix number. The fix
number is incremented whenever a new version contains only fixes
and enhancements to existing features. The minor number is in-
cremented whenever a new facility or technique is added, and the
major number is incremented when enough new things have been
added to consider it a major new edition of the program. A major
number of zero (0) indicates a prerelease version (one that
doesn't yet include all its initial release features or that may
not yet be considered fully tested).
-x Increments the debugging level.
OPERATION
The operation of mvmcas is documented in several pieces in different
places - one piece is this man page in this place, providing an
overview. Other documents give more details, for example the "PROTOCOL"
document describes the format of messages sent to and from mvmcas.
mvmcas engages in conversations about topics related to senders of mail
(or "email," I suppose.) A sender of email is known to mvmcas as an
email client. There are several kinds of email clients:
IPv4 address -
an IPv4 address, or loosely refered to as an IP address, identi-
fies an entity on the Internet that sends email. "IP" may be used
instead of "IPv4"
auth name -
the name of that an entity uses for authentication. This name is
the login name that is used in an SMTP AUTH dialog. If an auth
name is used, it becomes the responsible entity.
domain name -
the name of the Internet domain implicated as the sender of an
email message.
Note that a mail client can be known by more than one thing. An email
message can be associated with an IP address an and AUTH name and a do-
main name. Information gathered during a conversation with an email
client an impact the assessment of each of those, perhaps in different
ways or to different degrees. A mail client name, regularly called an
mcname, is referred to by the compbination of its type and its name
within that type. e.g. for an IP address, an mcname might be "IP
127.0.0.1/20" .
In typical mvmcas use, there is an entity, like an SMTP server, in com-
munication with an email client and also consulting with mvmas. We call
the entity (the receiving SMTP server) an agent of the email client, and
the email sender, as mentioned, an email client or a "mclient" as a
shorthand. Any given mclient may have connections, either to multiple
agents or to the same agent. Each of these connections is an "occurance"
of that client, or rather of a conversation with that client that is oc-
curing. One of mvmcas's functions is keeping track of how many occur-
ances there are with each mail client.
Remember that mvmcas is a "mail client assessment" server - it is con-
cerned with making a judgments about the incoming email, and the partic-
ipants in the sending of it. There can be different pieces involved in
the assessment. One piece is the server that has connected to the local
MTA. That server might have its own reputation. But that server may be
just one of many that is used by the sender - and while repution of each
sending server is significant, so is the the reputation of the sender
that uses it. We may wish to use other entities as proxies for the send-
ing system- e.g. perhaps looking at the set of sending servers (or a
subset thereof) can be used as a proxy for the specific system that is
connecting to us. And likewise if the responsible domain name for an
email message being sent can be ascertained, the assessment of that do-
main name can also be used.
Most, if not all, files used by mvmcas and referred to in this man page
are in a control directory whose location is specified in the mvmcas
source code. The default location as of this writing is
/usr/local/sys/mvmf/mvmcas
Within this directory are the configuration file and any database files.
mvmcas listens for messages using interfaces specified in its configura-
tion file (see CONFIGURATION FILE) and on the mvmcas command line. Each
message is a block of text that begins with an instruction word. That
word, thought of as a command, is followed by any arguments to the com-
mand.
Communication with mvmcas does not not strictly follow a client/server
relationship. The agent (i.e. the mvmcas client) sends messages to mvm-
cas, and mvmcas sends messages to agents. Often the messages sent by
mvmcas are triggered by the messages received by the agent, making the
communication look client/server-ish. mvmcas can send messages to an
agent in other cases, such as noting a change to an mclient that the
agent is known to be handling. For example, if a client's interaction
with one agent behaves in a way that it becomes blocked, an info message
to that effect, about that client, may be sent to all agents that are
communicating with it. Some commands from agents will cause mvmcas to
send a message back to the agent, a message that is essentially a reply.
Other commands do not.
Some commands are for agent support, i.e. agents are coded to send them.
Others are for administration, perhaps used manually.
Here's a summary of the commands that mvmcas handles. More detailed in-
formation is found in, for example, the PROTOCOL document. This is just
a synopsis to give an overview. Commands include:
control name [value] -
Set or get the value of a control in the mvmcas program. This is
an old idea that doesn't have much support. name is the name of
the control. Controls are either integers or strings. If there
is no value given, the current value is returned. If there is a
value, it is set, and a response is given indicating this. Cur-
rently the only control value is greylisting-suppressed, which
can have a value of 0 or 1. If set to 1, mvmcas will not apply
greylisting or send greylisting information. This provides a
quick way to turn off greylisting.
done - Says that the agent is done. All remembered relationships between
this agent and mail clients are removed. This is a synonym for
"quit"
hi [stuff] -
Say hello. mvmcas sends a "hi" back. This is essentially a ping,
showing that mvmcas is listening and responding on the interface
the message is sent to. Any "stuff" given is returned in the re-
ply in some way. "hi" is the default meaning of a message; if a
blank message is received it's treated as a "hi."
mclient-change mcname [updates] -
apply changes, as specified in the structured updates portion of
the message, to a mail client's information. Mainly an adminis-
trative function.
mclient-delete mcname -
delete an entry for a mail client. An administrative function.
mclient-info mcname -
return information about a mail client. An administrative func-
tion.
mclient-replace mcname [updates] -
replace mclient information - the information in the message com-
pletely replaces the mclient data, using the "updates" portion of
the message, rather than updating certain parts of it as with
mclient-change.
quit - Says that the agent is done. This is a synonym for "done"
start mcname -
Says that the agent sending the command has started communicating
with the named mail client. mvmcas will send notifications to
this agent whenever changes are made that affect the mail client.
stats -
returns some statistics about mvmcas.
stop mcname [updates] -
Indicates that the agent's conversation with the mail client has
ended. The agent may supply updates to the mail client, e.g. from
what has happened during an SMTP session, as a structured compo-
nent per description in the PROTOCOL document. mvmcas will remove
the occurance and will remove the association of the agent with
the mail client.
sync - to force an update to disk of the in-memory dynamic data. This is
mainly relevant if a database using in-memory storage has been
selected. mvmcas will periodically rewrite such dynamic data in
this situation, but the sync command can be used to make it hap-
pen sooner.
update mcname [updates] -
Applies updates to the named mail client per the structured "up-
dates" information in the message (see PROTOCOL). If the struc-
tured data includes a "STOP" term, this also acts as a STOP com-
mand. Likewise, if it includes "QUIT" it acts as QUIT.
Agents can communicate with mvmcas using either udp or tcp protocols.
udp is the most likely since it involves less setup and overhead. With
udp, in order to receive mvmcas messages the agent is expected to keep
listening on the socket it used. There's a bit of a complication here in
that when udp is used, mvmcas can not easily tell if the agent is still
listening, as opposed to tcp sessions where mvmcas will know when and if
the connection is dropped. For this reason, mvmcas will periodically
prune its knowledge of udp agents if it hasn't heard from them in a
while. agents are encouraged to specifically notify mvmcas if they stop
participlating, e.g. with a "quit" or "done" command or with quit or
done attributes to other messages such as "stop."
CONFIGURATION FILE
The configuration file, normally named mvmcas-rc and found in the mvmcas
control directory, is simply a line-by-line specification of parameters
and options. Blank lines and lines beginning with a "#" character are
ignored. Other than that, each line begins with a word specifying the
parameter name. This is followed by any arguments.
Parameters are:
cache type - Specifies which type of cache to use. The cache layer is a
selectable module, of which one can be chosen. It was implemented
as a selectable module mainly in order to let an alternative be
implemented and tested while the original could still be used,
even though this process was meant to replace the original, and
we still have a this configuation item even though only one
choice may be available. (Sort of inspired by the selectable
database module, where multiple choices are likely to remain.)
The choices are avl, which is the original implementation using
in-memory AVL trees, and std, the replacement which uses C++ std
library containers. The goal was to get rid of the avl module.
database type -
the database module to use. The database is where client data is
kept persistently. As with the cache selection, different selec-
table modules are present and can be used depending on need or
desire. The choices include avl, an in-memory database using AVL
trees; std, an in-memory database using C++ std library contain-
ers; and sqlite3, an SQL datbase using the sqlite3 engine. Some
discussion of these choices appears in a later section of this
man page.
serve protocol host - Listen (and serve) using protocol on host. pro-
tocol is either tcp or udp for, naturally, tcp or udp protocol.
host is the name of the host to listen on, which must be a name
that refers to an interface on the local system. ("localhost" for
example.) The hostname may include a trailing colon and port name
or number to use, otherwise a default port number (perhaps 2830,
but check the source code) is used.
There can be multiple serve lines using the same or different
protocols, as long as there are no conflicts of hostname or port
numbers.
DATABASE
Discussion of the operation of the selectable databases.
Text files
The avl and std database modules keep data in memory using different
techniques but operating similar ways. When mvmcas starts, it loads mail
client data into memory from text files and uses the data in memory for
its operations. If data is changed, as is expected during normal opera-
tion, the dynamic data is periodically rewritten and the data files ro-
tated.
There are two subdirectories in the mvmcas control directory that con-
tain text database files. These are
dbu for user-supplied data, meaning data that loaded by mvmcas but
never changed by it. All regular text files within this directory
are loaded when mvmcas starts; and
db which has dynamic files created by and maintained by mvmcas. (The
word "maintained" is used loosely-- they are periodically rewrit-
ten from dynamic data kept in memory, as stated below.") There
are two files containing mail client data in this subdirectory:
mctree_ip - mail clients that are named by IPv4 address, and
mctree_auth - mail clients that are named by the name used to au-
thenticate to the SMTP server.
During its operation, mvmcas will periodically rewrite these dy-
namic files (in db) after rotating them. "rotating" simply means
renaming them to a small set of numbered versions, resulting in
file names e.g. like "mctree_ip.0" and "mctree_ip.1" and so forth.
Mail client files in the db and dbu subdirectories each contain zero or
more mail client sections. The format of the mail client entries is de-
rived from and is roughly equivalent to sections in the PROTOCOLS docu-
ment. In the absence of better documentation (e.g. here or elsewhere),
that pointer will have to do.
sqlite3 database
Using an sqlite3 database, all data is stored on disk using the sqlite3
database code. Database file(s) are contained in a sqlite3 subdirectory
within the mvmcas control directory, and include:
mclientsdb -
an sqlite3 database file containing mail client data. This file
can be viewed and manipulated in various ways, including with the
sqlite3 command line program. mvmcas includes a tool, liteops,
that can import data from and export data to text files such as
used in the avl and std database modules.
You can modify the sqlite3 database (using the sqlite3 command line pro-
gram, for example), but be aware that sqlite3 does not support notifying
a program of changes to its data, and so mvmcas will not be informed of
and will therefore will not notice changes to data that it may have tem-
porarily cached. Changes will be better made using the adminstrative
sorts of messages that mvmcas interprets (e.g. mclient-changee and
mclient-delete). mvmcas can also be restarted without too much disrup-
tion to account for database changes
More can and should be said about the sqlite3 database.
SEE ALSO
liteops(1) - program to import and export mvmcas data in an sqlite3
database.
http://www.mvmf.org/ -- the mvmf web site.
PROTOCOL - the protocol document/memo.
schemas.sql - contains sqlite3 schemas for the mclients (mail clients)
table and any other things, such as hooks, needed by a sqlite3 database.
CREDITS TO
M. Mallett (mem@mvmf.org) 2006-2025
BUGS
You tell me..
MVMCAS(1)