.\"	$NetBSD: monotone-server.7,v 1.2 2011/12/26 13:23:43 joerg Exp $
.\"
.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
.\" 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.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
.\"
.Dd March 12, 2010
.Dt MONOTONE-SERVER 7
.Os
.Sh NAME
.Nm monotone-server
.Nd guide to set up a monotone server
.Sh DESCRIPTION
The
.Nm
package provides a
.Xr rc.d 8
script, called
.Sq monotone ,
that aids in the configuration of a monotone server.
This script follows the normal conventions of other
.Xr rc.d 8
scripts, but adds a few extra commands to ease the configuration process
from scratch.
.Pp
.Ss Typical configuration procedure
In order to configure a monotone server using the
.Nm
package, follow these instructions:
.Bl -enum
.It
Check that the home directory of the
.Sq @MONOTONE_USER@
user points to the directory you want to use to keep your database in.
If it is not what you want, change it before initializing the server.
.It
Copy
.Pa @PREFIX@/share/examples/rc.d/monotone
to
.Pa @RCD_SCRIPTS_DIR@/monotone
if the latter does not exist.
.It
Set
.Sq monotone=YES
in
.Xr rc.conf 5 .
.It
Use the
.Sq init
subcommand to generate an empty monotone database for the server.
.It
Use the
.Sq genkey
subcommand to generate a new key pair for the monotone server.
.It
Edit the
.Pa @PKG_SYSCONFDIR@/read-permissions
and the
.Pa @PKG_SYSCONFDIR@/write-permissions
to adjust the users that are allowed to read from and to write to the server.
.It
Use the
.Sq read
subcommand to import the public keys needed to fulfill the permissions
configured in the previous step.
.It
Learn how to back up the server data as described in
.Sx Backing up your server .
Back the new files up now.
.It
Start the server as usual (with the
.Sq start
subcommand)!
.El
.Ss Backing up your server
In order to back up a monotone server configured by this package, you need to
copy the server database, the key pair for the server and the passphrase to
identify such key pair, in a safe place.
The exact location of these files is shown below in the
.Sx FILES
section.
.Ss Available subcommands
The list below describes all the non-standard subcommands provided by the
.Nm monotone
.Xr rc.d 8
script.
For the sake of completeness, some standard commands are also included:
.Bl -tag -width genkeyXXkeynameX
.It Ar genkey Op Ar keyname
Generates a new key pair to authenticate the server.
A random password is automatically generated for this key and the server is
configured to use it.
.Pp
If
.Ar keyname
is not provided, the key name defaults to
.Sq monotone@your-domain .
.It Ar init
Initializes the server by creating an empty monotone database.
This database is created in the home directory of the
.Sq @MONOTONE_USER@
user, and this directory is previously created if it does not exist.
.It Ar migrate
If the database schema has changed during an update of monotone, migrates
the database to the new version.
.It Ar read Op Ar file ...
Imports public keys into the server database.
Keys can be provided on the standard input or, if they reside in files,
as arguments.
.It Ar start
Starts the server.
.It Ar stop
Stops the server.
.El
.Sh FILES
.Bl -tag -width XXXXX -compact
.It Pa @RCD_SCRIPTS_DIR@/monotone
The
.Xr rc.d 8
startup script.
.It Pa @MONOTONE_HOME@/
Default location of the server database, unless the home directory of the
.Sq @MONOTONE_USER@
user has been changed.
.It Pa @PKG_SYSCONFDIR@/keys/
Location of server private keys.
.It Pa @PKG_SYSCONFDIR@/monotonerc
Configuration file (lua hooks) for the monotone server.
.It Pa @PKG_SYSCONFDIR@/passphrases
List of passphrases of the private keys.
.It Pa @PKG_SYSCONFDIR@/read-permissions
Configuration of the users allowed to read specific branches.
.It Pa @PKG_SYSCONFDIR@/write-permissions
Configuration of the users allowed to write to the database.
.It Pa @MONOTONE_LOGFILE@
Log file for the server.
.El
.Sh SEE ALSO
.Xr rc.conf 5 ,
.Xr rc.d 8
.Sh HISTORY
The monotone-server package first appeared in pkgsrc-2005Q1 and was composed of
a simple startup script and a separate interactive script for initial
configuration of the server.
.Pp
The monotone-server package was completely rewritten in pkgsrc-2010Q1 to provide
a single startup script that bundles the traditional behavior of an
.Xr rc.d 8
script alongside the configuration and management of the server.
These changes were inspired by the monotone-server package from Fedora.
.Sh AUTHORS
The monotone-server package and its accompanying scripts were written by
.An Julio Merino
.Aq jmmv@NetBSD.org .