summaryrefslogtreecommitdiff
path: root/documentation
diff options
context:
space:
mode:
authorPer Reedtz Thomsen <pthomsen@reedtz.com>2006-04-26 06:14:12 +0000
committerPer Reedtz Thomsen <pthomsen@reedtz.com>2006-04-26 06:14:12 +0000
commitfaab89ecaf8a2406a1112b9063d4ea648b636b04 (patch)
treea860e7f2cb6af5ac48dd06cc97e27b0a2c6b47d0 /documentation
parent145b286c7d8e3337b932dc271ff8a53661cabace (diff)
Added raidfile-config, bbstored-certs and bbstored-config.
Also, hacked makefile to do the right thing.
Diffstat (limited to 'documentation')
-rw-r--r--documentation/boxbackup/Makefile4
-rw-r--r--documentation/boxbackup/bbstored-certs.xml125
-rw-r--r--documentation/boxbackup/bbstored-config.xml140
-rw-r--r--documentation/boxbackup/raidfile-config.xml143
4 files changed, 410 insertions, 2 deletions
diff --git a/documentation/boxbackup/Makefile b/documentation/boxbackup/Makefile
index e1d65a7c..ea795710 100644
--- a/documentation/boxbackup/Makefile
+++ b/documentation/boxbackup/Makefile
@@ -36,9 +36,9 @@ $(HTMLPREFIX)/man-html/.there:
man-pages/.there:
if [ ! -d man-pages ]; then mkdir man-pages; touch man-pages/.there; fi
-man-nroff: bbackupquery.1 bbackupctl.1 bbstoreaccounts.1
+man-nroff: bbackupquery.1 bbackupctl.1 bbstoreaccounts.1 bbstored-config.1 raidfile-config.1 bbstored-certs.1
-man-html: bbackupquery.html bbackupctl.html bbstoreaccounts.html
+man-html: bbackupquery.html bbackupctl.html bbstoreaccounts.html bbstored-config.html raidfile-config.html bbstored-certs.html
%.html: %.xml
$(DBPROC) -o $@ $(NOCHUNKBOOKXSL) $<
diff --git a/documentation/boxbackup/bbstored-certs.xml b/documentation/boxbackup/bbstored-certs.xml
new file mode 100644
index 00000000..e7cb9316
--- /dev/null
+++ b/documentation/boxbackup/bbstored-certs.xml
@@ -0,0 +1,125 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry>
+ <refmeta>
+ <refentrytitle>bbstored-certs</refentrytitle>
+
+ <manvolnum>1</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>bbstored-certs</refname>
+
+ <refpurpose>Manage certificates for the Box Backup system</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>bbstored-certs &lt;certs-dir&gt; &lt;command&gt;
+ [&lt;arguments&gt;]</command>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para><literal>bbstored-certs</literal> creates and signs certificates for
+ use in Box Backup. It allows the user to create and sign the server keys,
+ as well as signing client keys.</para>
+
+ <para>All commands must be followed by the <literal>certs-dir</literal>,
+ which is the directory in which the certificates are stored.</para>
+
+ <refsection>
+ <title>Commands</title>
+
+ <para>There are 3 commands:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>init</literal>: Create the
+ <literal>certs-dir</literal>, and generate the server keys for
+ bbstored. <literal>certs-dir</literal> cannot exist before running
+ the command.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>sign-server &lt;servercsrfile&gt;</literal>: Sign the
+ server certificate. The <literal>servercsrfile</literal> is the file
+ generated by the <literal>init</literal> command.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>sign &lt;clientcsrfile&gt;</literal>: Sign a client
+ certificate. The <literal>clientcsrfile</literal> is generated
+ during client setup. See <literal>bbackupd-config(1)</literal>. Send
+ the signed certificate back to the client, and install according to
+ the instructions given by <literal>bbackupd-config</literal>.</para>
+ </listitem>
+ </itemizedlist>
+ </refsection>
+ </refsection>
+
+ <refsection>
+ <title>Author</title>
+
+ <para>Ben Summers and contributors. For help, please go to the <ulink
+ url="http://boxbackup.hostworks.ca/">Wiki</ulink>, or subscribe to the Box
+ Backup <ulink
+ url="http://lists.warhead.org.uk/mailman/listinfo/boxbackup">mailing
+ list.</ulink></para>
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+
+ <para><literal>bbstored-config(1)</literal></para>
+
+ <para><literal>bbstored.conf(5)</literal></para>
+
+ <para><literal>bbstoreaccounts(1)</literal></para>
+ </refsection>
+
+ <refsection>
+ <title>Files</title>
+
+ <para><literal>raidfile-config</literal> generates the raidfile.conf(5)
+ file.</para>
+ </refsection>
+
+ <refsection>
+ <title>Bugs</title>
+
+ <para>If you find a bug in Box Backup, and you want to let us know about
+ it, join the <ulink
+ url="http://lists.warhead.org.uk/mailman/listinfo/boxbackup">mailing
+ list</ulink>, and send a description of the problem there.</para>
+
+ <para>To report a bug, give us at least the following information:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The version of Box Backup you are running</para>
+ </listitem>
+
+ <listitem>
+ <para>The platform you are running on (Hardware and OS), for both
+ client and server.</para>
+ </listitem>
+
+ <listitem>
+ <para>If possible attach your config files (bbstored.conf,
+ bbackupd.conf) to the bug report.</para>
+ </listitem>
+
+ <listitem>
+ <para>Also attach any log file output that helps shed light on the
+ problem you are seeing.</para>
+ </listitem>
+
+ <listitem>
+ <para>And last but certainly not least, a description of what you are
+ seeing, in as much detail as possible.</para>
+ </listitem>
+ </itemizedlist>
+ </refsection>
+</refentry> \ No newline at end of file
diff --git a/documentation/boxbackup/bbstored-config.xml b/documentation/boxbackup/bbstored-config.xml
new file mode 100644
index 00000000..56a4fe23
--- /dev/null
+++ b/documentation/boxbackup/bbstored-config.xml
@@ -0,0 +1,140 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry>
+ <refmeta>
+ <refentrytitle>bbstored-config</refentrytitle>
+
+ <manvolnum>1</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>bbstored-config</refname>
+
+ <refpurpose>Create config files for bbstored</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>bbstored-config &lt;configdir&gt; &lt;servername&gt;
+ &lt;username&gt;</command>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>The <literal>bbstored-config</literal> script creates config files
+ and server certificates for a bbstored instance. It takes three
+ parameters:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>configdir</literal>: The directory where config files
+ will reside. A subdirectory bbstored will be created, where several
+ config files will reside. the <literal>bbstored.conf</literal> file
+ will be created in <literal>configdir</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>servername</literal>: The name of the server that is
+ being configured. Usually the fully qualified domain name of the
+ machine in question.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>username</literal>: The name of the user that should be
+ running the bbstored processes. Recommended name:
+ _<literal>bbstored.</literal></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>A valid raidfile.conf(5) must be found in configdir. Several steps
+ are taken during the run of bbstored-config:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Configuration files are created.</para>
+ </listitem>
+
+ <listitem>
+ <para>Server certificates are created. This requires interaction from
+ the operator.</para>
+ </listitem>
+
+ <listitem>
+ <para>The raid volumes are checked, to ensure that the configuration
+ is consistent, and will work.</para>
+ </listitem>
+
+ <listitem>
+ <para>Instructions for next steps to take are shown. These steps may
+ be different for different OS platforms, so pay close attention to
+ these instructions.</para>
+ </listitem>
+ </itemizedlist>
+ </refsection>
+
+ <refsection>
+ <title>Author</title>
+
+ <para>Ben Summers and contributors. For help, please go to the <ulink
+ url="http://boxbackup.hostworks.ca/">Wiki</ulink>, or subscribe to the Box
+ Backup <ulink
+ url="http://lists.warhead.org.uk/mailman/listinfo/boxbackup">mailing
+ list.</ulink></para>
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+
+ <para><literal>raidfile-config(1)</literal></para>
+
+ <para><literal>bbstored.conf(5)</literal></para>
+
+ <para><literal>raidfile.conf(5)</literal></para>
+ </refsection>
+
+ <refsection>
+ <title>Files</title>
+
+ <para><literal>bbstoreaccounts</literal> uses the Box Backup server
+ configuration file, usually located in
+ <filename>/etc/box/bbstored.conf</filename>.</para>
+ </refsection>
+
+ <refsection>
+ <title>Bugs</title>
+
+ <para>If you find a bug in Box Backup, and you want to let us know about
+ it, join the <ulink
+ url="http://lists.warhead.org.uk/mailman/listinfo/boxbackup">mailing
+ list</ulink>, and send a description of the problem there.</para>
+
+ <para>To report a bug, give us at least the following information:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The version of Box Backup you are running</para>
+ </listitem>
+
+ <listitem>
+ <para>The platform you are running on (Hardware and OS), for both
+ client and server.</para>
+ </listitem>
+
+ <listitem>
+ <para>If possible attach your config files (bbstored.conf,
+ bbackupd.conf) to the bug report.</para>
+ </listitem>
+
+ <listitem>
+ <para>Also attach any log file output that helps shed light on the
+ problem you are seeing.</para>
+ </listitem>
+
+ <listitem>
+ <para>And last but certainly not least, a description of what you are
+ seeing, in as much detail as possible.</para>
+ </listitem>
+ </itemizedlist>
+ </refsection>
+</refentry> \ No newline at end of file
diff --git a/documentation/boxbackup/raidfile-config.xml b/documentation/boxbackup/raidfile-config.xml
new file mode 100644
index 00000000..05163502
--- /dev/null
+++ b/documentation/boxbackup/raidfile-config.xml
@@ -0,0 +1,143 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry>
+ <refmeta>
+ <refentrytitle>raidfile-config</refentrytitle>
+
+ <manvolnum>1</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>raidfile-config</refname>
+
+ <refpurpose>Configure Box Backup's RAID files</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>raidfile-config &lt;configdir&gt; &lt;blocksize&gt;
+ &lt;dir1&gt; [&lt;dir2&gt; &lt;dir3&gt;]</command>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>raidfile-config creates a raidfile.conf file for Box Backup. This
+ file holds information about the directories used to store backups in. Box
+ Backup supports userland RAID, in a restricted RAID5 configuration, where
+ 3 and only 3 'drives' are supported. You can read more about RAID5 (and
+ other RAID-levels) <ulink
+ url="http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks#RAID_5">here</ulink>.
+ </para>
+
+ <refsection>
+ <title>Parameters</title>
+
+ <para>The parameters are as follows:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>configdir</literal>: The directory path where
+ configuration files are located. Usually this is
+ <literal>/etc/box</literal>. <literal>raidfile.conf</literal> will
+ be written in this directory.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>blocksize</literal>: The block size used for file
+ storage in the system, in bytes. Using a multple of the file system
+ block size is a good strategy. Depending on the size of the files
+ you will be backing up, this multiple varies. Of course it also
+ depends on the native block size of your file system.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>dir1</literal>: The first directory in the built-in
+ RAID array.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>dir2</literal>: The second directory in the built-in
+ RAID array. If you are not using the built-in RAID functionality,
+ this field should be ignored. You should not use the built-in RAID,
+ when you have a hardware RAID solution, or if you're using another
+ type of software RAID (like md on Linux).</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>dir3</literal>: The third directory in the built-in
+ RAID array. The same notes that apply to <literal>dir2</literal>
+ also apply to <literal>dir3</literal>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Note that there are currently no way to add multiple disk sets to
+ the raidfile.conf file using command line tools, etc. See
+ raidfile.conf(5) for details on adding more disks</para>
+ </refsection>
+ </refsection>
+
+ <refsection>
+ <title>Author</title>
+
+ <para>Ben Summers and contributors. For help, please go to the <ulink
+ url="http://boxbackup.hostworks.ca/">Wiki</ulink>, or subscribe to the Box
+ Backup <ulink
+ url="http://lists.warhead.org.uk/mailman/listinfo/boxbackup">mailing
+ list.</ulink></para>
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+
+ <para><literal>bbstored-config(1)</literal></para>
+
+ <para><literal>bbstored.conf(5)</literal></para>
+
+ <para><literal>raidfile.conf(5)</literal></para>
+ </refsection>
+
+ <refsection>
+ <title>Files</title>
+
+ <para><literal>raidfile-config</literal> generates the raidfile.conf(5)
+ file.</para>
+ </refsection>
+
+ <refsection>
+ <title>Bugs</title>
+
+ <para>If you find a bug in Box Backup, and you want to let us know about
+ it, join the <ulink
+ url="http://lists.warhead.org.uk/mailman/listinfo/boxbackup">mailing
+ list</ulink>, and send a description of the problem there.</para>
+
+ <para>To report a bug, give us at least the following information:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The version of Box Backup you are running</para>
+ </listitem>
+
+ <listitem>
+ <para>The platform you are running on (Hardware and OS), for both
+ client and server.</para>
+ </listitem>
+
+ <listitem>
+ <para>If possible attach your config files (bbstored.conf,
+ bbackupd.conf) to the bug report.</para>
+ </listitem>
+
+ <listitem>
+ <para>Also attach any log file output that helps shed light on the
+ problem you are seeing.</para>
+ </listitem>
+
+ <listitem>
+ <para>And last but certainly not least, a description of what you are
+ seeing, in as much detail as possible.</para>
+ </listitem>
+ </itemizedlist>
+ </refsection>
+</refentry> \ No newline at end of file