Update of /cvsroot/monetdb/sql/src/backends/monet5/merovingian
In directory sfp-cvsdas-4.v30.ch3.sourceforge.com:/tmp/cvs-serv9268
Modified Files:
Makefile.ag
Added Files:
merovingian.1.in
Removed Files:
merovingian.1
Log Message:
expand stuff in merovingian's manpage too
--- merovingian.1 DELETED ---
--- NEW FILE: merovingian.1.in ---
.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.TH MEROVINGIAN 1 "SEPTEMBER 2009" Application "MonetDB Applications"
.SH NAME
merovingian \- the MonetDB Database Server daemon
.SH SYNOPSIS
.B merovingian
[database ...]
.SH DESCRIPTION
.B merovingian
is the MonetDB Database Server daemon. It is not meant to be used in
interactive environments, and hence has no help or version commands nor
flags. The typical use of
.B merovingian
is to be started from a startup script, such as from
.I /etc/init.d/
on Linux systems or
.BR smf (5)
on Solaris systems, as part of a system startup.
.P
A
.B merovingian
instance manages one local cluster based on the dbfarm specified in the
.I /etc/monetdb5.conf
config file. Within this local cluster
.B merovingian
takes care of starting up databases when necessary, and stopping them
either upon request via
.BR monetdb (1)
or when being shut down. Client connections initially are made against
.B merovingian
which redirects or proxies the client to the appropriate database
process, started on the fly when necessary.
.P
When started,
.B merovingian
runs in the background, sending log messages to
.IR /var/log/merovingian.log ,
until being sent a stop, terminate or interrupt signal. All arguments
given when starting
.B merovingian
are considered to be databases to be pre-started. Pre-started databases
are started as part of the startup of
.BR merovingian ,
which means their startup is not delayed until the first client
requests for them.
.P
.B merovingian
uses a neighbour discovery scheme to detect other
.B merovingian
processes running in the local network. Databases from those remote
instances are made available to a locally connecting client. Remote
databases never override local databases, and their availability is
controlled by the remote
.B merovingian
process.
.SH CONFIGURATION
.B merovingian
defaults to use the configuration file that was placed in the file
system during installation to control its behaviour. If the environment
variable
.I MONETDB5CONF
is set,
.B merovingian
uses the value of this variable as configuration file to load. In the
configuration file the following options can be specified. Most are
typically to be found under the
.I Merovingian
section in the default configuration file.
.IP gdk_dbfarm
The value of this setting determines which local cluster
.B merovingian
will monitor.
.IP mero_msglog
.IP mero_errlog
When both options are unset,
.B merovingian
logs messages and errors to the stdout and stderr channels on the
caller's console. By setting one or both of the
.B mero_msglog
and
.B mero_errlog
variables, one can specify messages and/or errors to be logged to a file
instead. It is legitimate to have both
.B mero_msglog
and
.B mero_errlog
pointing to the same file.
.IP mero_pidfile
Location pointing to the pidfile used by
.B merovingian
to write the process id of the daemon process that was started in the
background. This pid can be used to stop
.B merovingian
again by send a termination signal to the process id found in the file.
.IP mero_port
The port
.B merovingian
will open up and listen to connections for. When unset, the default
port
.I 50000
is used, which should be fine for most setups.
.IP mero_exittimeout
All database servers that were started by
.B merovingian
are shut down when
.B merovingian
is shut down. This behaviour is desirable if the
.B merovingian
process is ran from a start script that represents the MonetDB Database
Server. Setting the
.B mero_exittimeout
option to a positive
non-zero value, causes each started database server to be shut down by
.B merovingian
when it shuts down itself with a given time-out in seconds. If the
time-out expires, the database server is killed using the SIGKILL
signal. A time-out value of
.B 0
means that no attempt is made to shut down started database servers. As
a result, database servers will remain active after
.B merovingian
has stopped. The default value for
.B mero_exittimeout
is
.B 60
seconds. If your databases are rather large and find your databases
consistently being killed by
.B merovingian
upon shutdown, you may have to increase this timeout.
.IP mero_doproxy
.B merovingian
has two ways in which it can "attach" a connecting client to the target
database. The first method uses a redirect to the responsible mserver
process, the second method proxies the client to the mserver over
.BR merovingian .
While the first is more efficient, it requires the connecting client
to be able to connect to the mserver. In many settings this may be
undesirable or even impossible, since a wide range of open ports and
routing are necessary for this. In such case the proxy behaviour of
.B merovingian
is a good solution, which also allows a
.B merovingian
on the border of a network to serve requests to nodes in the local
(unreachable) network.
.IP mero_discoveryttl
Neighbour discovery allows
.B merovingian
to discover other running
.B merovingian
processes in the local network.
.B merovingian
publishes locally available databases to others periodically. The
interval used here depends on the time-to-live of the databases before
they need to get refreshed. The default is 10 minutes, which should
keep traffic in your network fairly low. If you add and/or remove
databases often, you may want to use a low ttl. The value of this
option is expressed in seconds.
.IP mero_discoveryport
The neighbour discovery service uses UDP broadcasting to announce
itself. For this
.B merovingian
listens to the given port, which defaults to the setting of
.BR mero_port .
If the port is set to 0, the neighbour discovery service is disabled and
hence no announcements will be made, nor received.
.IP mero_controlport
Each
.B merovingian
can possibly be controlled from a remote site, using
.BR monetdb (1).
The port to use can be set via this option. If unset,
.B merovingian
cannot be controlled remotely, but only via the local system by means of
a UNIX domain socket. Remote control requests are required to be
authenticated using a password. The password for this is stored in
the .merovingian_pass file in the dbfarm. If it doesn't exist,
.B merovingian
will create one to protect itself in case remote control is enabled.
One can set a password in this file. Note that
.B merovingian
needs to be restarted in order to pick up changes in
the .merovingian_pass file.
.P
Next to these global settings,
.B merovingian
respects per-database settings that are managed via
.BR monetdb (1).
The properties
.IR shared " and " forward
overrule the defaults from
.IR mero_discoveryport " and " mero_doproxy .
To obtain a list of properties, use `monetdb get all`.
.SH "REMOTE DATABASES"
The neighbour discovery capabilities of
.B merovingian
allow a user to contact a remote database transparently, as if it were a
local database. By default, all local databases are announced in the
network, such that neighbours can pick them up to make them available
for their local users. This feature can be disabled globally, or on
database level. For the latter, the
.BR monetdb (1)
utility can be used to change the share property of a database.
.P
While neighbour discovery in itself is sufficient to locate a database
in a cluster, it is limited in expressiveness. For instance, database
names are assumed to be unique throughout the entire system. This means
local databases overshadow remote ones, and duplicate remote entries
cannot be distinguished. To compensate for this,
.B merovingian
allows to adds a
.I tag
to each database that is being shared. This tag is sent in addition to
the database name, and only understood by other
.BR merovingian s.
.P
Tags are arbitrary ASCII-strings matching the pattern [A\-Za\-z0\-9./]+.
There are no assumed semantics in the tag, which allows for multiple
approaches when using the tag. The tag is always used in combination
with the database name. For this, the `/' character is used as
separator, which hence suggests the user to use that character as
separator for multilevel tags.
.B merovingian
allows common path globbing using `*' on tags, which allows for many
use-cases. Consider for instance the following three databases with their
tag:
.PP
.RS 0
dbX/master/tableQ
.RS 0
dbY/slave/tableQ
.RS 0
dbZ/slave/tableQ
.PP
A default match has implicit `/*' added to the search, making more generic
search strings match more specific ones. Hence, a connect with
database
.I dbX
is the same as
.I dbX/*
and hence matches
.IR dbX/master/tableQ .
Similar, a database connect for
.I */master
matches the same database as before. Note that the implicit `/*' is
not added if that would cause no matches, such as for
.I */master/tableQ
which would return all masters for
.IR tableQ ,
which in our hypothetical example is only
.IR dbX .
In contrast, a database connect for
.I */slave/tableQ
matches with either
.IR dbY " or " dbZ .
.B merovingian
returns the two options to the client in a round-robin fashion, such
that subsequent connects for the same pattern result in a load-balanced
connect to either of both databases.
.P
With tags in use, one can possibly make distinction between databases,
if setup like that. The previous example could hence also be setup like
this:
.PP
.RS 0
tableQ/master
.RS 0
tableQ/slave
.RS 0
tableQ/slave
.PP
Connecting to
.I tableQ/slave
would now return either of both databases even though they are not
unique (apart from the host they are located on, which is not shown in
the example). While being confusing for humans, for
.B merovingian
it is the same situation as in the previous example. However, because
globbing allows to make things easier to understand, tags for both
slaves could be changed to
.IR slaveX " or " slave/X
and use the necessary pattern to match them. It is up to the user to
decide how to use the tags.
.SH SIGNALS
.B merovingian
acts upon a number of signals as is common for a daemon.
.IP "SIGINT, SIGTERM, SIGQUIT"
Any of these signals make
.B merovingian
enter the shutdown sequence. This sequence involves cleanly shutting
down listener sockets, shutting down all started databases and finally
terminating itself.
.IP SIGHUP
When this signal is received by
.B merovingian
it will reopen the logfiles as pointed to by
.B mero_msglog
and
.BR mero_errlog .
When these two are unset or point to a file attached to a terminal,
.B merovingian
will not reopen the associated filedescriptor.
.SH "RETURN VALUE"
.B merovingian
returns exit code
.B 0
if it was able to successfully launch the background process. When an
error occurs during startup that prevents
.B merovingian
from functioning properly, an exit code
.B 1
is returned.
.SH FILES
.I @MONETDB5_CONFFILE@
.RS
The configuration file for MonetDB, located in the system configuration
directory.
.RE
.I /var/log/merovingian.log
.RS
The configuration file default location to write log output to.
.SH "SEE ALSO"
.BR monetdb (1)
.\".BR mserver5 (1)
Index: Makefile.ag
===================================================================
RCS file: /cvsroot/monetdb/sql/src/backends/monet5/merovingian/Makefile.ag,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -d -r1.16 -r1.17
--- Makefile.ag 13 Apr 2010 16:30:52 -0000 1.16
+++ Makefile.ag 13 Apr 2010 16:47:48 -0000 1.17
@@ -51,7 +51,8 @@
}
bin_merovingian = {
- SOURCES = merovingian.c
+ # hack: include merovingian.1.in here to get it expanded
+ SOURCES = merovingian.c merovingian.1.in
LIBS = \
libmeroutil \
$(MONETDB5_LIBS) -lmonetdb5 \
------------------------------------------------------------------------------
Download Intel® Parallel Studio Eval
Try the new software tools for yourself. Speed compiling, find bugs
proactively, and fine-tune applications for parallel performance.
See why Intel Parallel Studio got high marks during beta.
http://p.sf.net/sfu/intel-sw-dev
_______________________________________________
Monetdb-sql-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/monetdb-sql-checkins
