174 lines
5.7 KiB
Groff
174 lines
5.7 KiB
Groff
.\" $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 .
|