[Box Backup-dev] COMMIT r550 - box/trunk/documentation/boxbackup
boxbackup-dev@fluffy.co.uk
boxbackup-dev@fluffy.co.uk
Thu, 30 Mar 2006 21:04:22 +0000 (GMT)
Author: per
Date: 2006-03-30 21:04:14 +0000 (Thu, 30 Mar 2006)
New Revision: 550
Added:
box/trunk/documentation/boxbackup/generate_except_xml.pl
Modified:
box/trunk/documentation/boxbackup/Makefile
box/trunk/documentation/boxbackup/adminguide.xml
box/trunk/documentation/boxbackup/bb-book.xsl
Log:
Changed bb-book.xsl to point to the correct places in the directory structure.
Admin Guide now contains all exception codes. See below.
generate_except_xml.pl generates a DocBook Appendix with all exceptions from
ExceptionCodes.txt. That is then included in the Admin Guide.
Makefile updated to generate ExceptionCodes.xml, and the dockit.
Modified: box/trunk/documentation/boxbackup/Makefile
===================================================================
--- box/trunk/documentation/boxbackup/Makefile 2006-03-29 23:04:26 UTC (rev 549)
+++ box/trunk/documentation/boxbackup/Makefile 2006-03-30 21:04:14 UTC (rev 550)
@@ -8,21 +8,24 @@
VPATH= adminguide
.SUFFIXES: .html .xml
-all: adminguide instguide
+all: adminguide instguide
-adminguide: adminguide/index.html
+adminguide: adminguide/index.html
-adminguide/index.html: adminguide.xml
+adminguide/index.html: adminguide.xml ExceptionCodes.xml bb-book.xsl
# docname=`echo $@ | sed -e 's/\/index.html//'`
$(DBPROC) -o adminguide/ $(BOOKXSL) adminguide.xml
-instguide: instguide/index.html
+instguide: instguide/index.html bb-book.xsl
-instguide/index.html: instguide.xml
+instguide/index.html: instguide.xml bb-book.xsl
$(DBPROC) -o instguide/ $(BOOKXSL) instguide.xml
+ExceptionCodes.xml: ../../ExceptionCodes.txt
+ perl ./generate_except_xml.pl
+
dockit: instguide adminguide
- tar zcf documentation-kit-0.10.tar.gz images/ instguide/ adminguide/
+ tar zcf documentation-kit-0.10.tar.gz html/ instguide/ adminguide/
clean:
rm -rf ./instguide/
Modified: box/trunk/documentation/boxbackup/adminguide.xml
===================================================================
--- box/trunk/documentation/boxbackup/adminguide.xml 2006-03-29 23:04:26 UTC (rev 549)
+++ box/trunk/documentation/boxbackup/adminguide.xml 2006-03-30 21:04:14 UTC (rev 550)
@@ -1,16 +1,17 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+<!ENTITY __ExceptionCodes__elfjz3fu SYSTEM "ExceptionCodes.xml">
+]>
<book>
<title>Box Backup administrator's guide</title>
<preface>
<title>License</title>
- <para>Copyright (c) <YEAR>, <OWNER></para>
+ <para>Copyright © 2003 - 2006, Ben Summers and contributors. All rights
+ reserved.</para>
- <para>All rights reserved.</para>
-
<para>Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:</para>
@@ -29,9 +30,9 @@
</listitem>
<listitem>
- <para>Neither the name of the <ORGANIZATION> nor the names of
- its contributors may be used to endorse or promote products derived
- from this software without specific prior written permission</para>
+ <para>Neither the name of the authors nor the names of its
+ contributors may be used to endorse or promote products derived from
+ this software without specific prior written permission</para>
</listitem>
</itemizedlist>
@@ -123,8 +124,8 @@
authority directory is intended to be stored on another server. It
should not be kept on the backup server to limit the impact of a
server compromise. The instructions and the script assume that it will
- be kept elsewhere, so will ask you to copy files to and from the CA.
- </para>
+ be kept elsewhere, so will ask you to copy files to and from the
+ CA.</para>
<para><emphasis role="bold">Clock time warning</emphasis>: SSL
certificates contain validity dates, including a "valid from" time. If
@@ -134,7 +135,7 @@
on all machines. If you get strange errors when attempting to use new
certificates, check the clocks! You will probably just need to wait a
while until the certificates become valid, rather than having to
- regenerate them. </para>
+ regenerate them.</para>
<section>
<title>Set up a CA</title>
@@ -147,11 +148,11 @@
<programlisting>/usr/local/bin/bbstored-certs ca init</programlisting>
- <para>(See <link linkend="instguide.sgml">OpenSSL notes</link> if
- you get an OpenSSL error)</para>
+ <para>(See <link linkend="instguide.xml">OpenSSL notes</link> if you
+ get an OpenSSL error)</para>
<para>This creates the directory 'ca' in the current directory, and
- initialises it with basic keys. </para>
+ initialises it with basic keys.</para>
</section>
<section>
@@ -166,7 +167,7 @@
<para>This signs the certificate for the server. Follow the
instructions in the output on which files to install on the server.
The CSR file is now no longer needed. Make sure you run this command
- from the directory above the directory 'ca'. </para>
+ from the directory above the directory 'ca'.</para>
<para>TODO: Explain instructions in output.</para>
</section>
@@ -247,8 +248,8 @@
correct! Then send the two files back to the user, as instructed by
the script.</para>
- <para>Please read the Troubleshooting page if you have problems.
- </para>
+ <para>Please read the Troubleshooting page if you have
+ problems.</para>
<para>TODO: Link to troubleshooting...</para>
</section>
@@ -299,7 +300,7 @@
up a single user's files by running it as that user. (Tip: specify a
directory other than /etc/box, and then give the alternate config file
as the first argument to bbackupd). However, it will fall over if you
- don't give yourself read access to one of your files. </para>
+ don't give yourself read access to one of your files.</para>
<section>
<title id="BasicConfig">Basic configuration</title>
@@ -325,7 +326,7 @@
catch bad configuration of this nature!</para>
<para>You may also want to consider changing the mode from lazy to
- snapshot, depending on what your system is used for. </para>
+ snapshot, depending on what your system is used for.</para>
<itemizedlist>
<listitem>
@@ -333,7 +334,7 @@
scans the files, with only a rough schedule. It uploads files as
and when they are changed, if the latest version is more than a
set age. This is good for backing up user's documents stored on
- a server, and spreads the load out over the day. </para>
+ a server, and spreads the load out over the day.</para>
</listitem>
<listitem>
@@ -342,8 +343,8 @@
of the filesystem. The backup daemon does absolutely nothing
until it is instructed to make a backup using the bbackupctl
utility (probably as a cron job), at which point it uploads all
- files which have been changed since the last time it uploaded.
- </para>
+ files which have been changed since the last time it
+ uploaded.</para>
</listitem>
</itemizedlist>
@@ -450,7 +451,7 @@
directive.</para>
<para>If a directive ends in Regex, then it is a regular expression
- rather than a explicit full pathname. See </para>
+ rather than a explicit full pathname. See</para>
<programlisting> man 7 re_format</programlisting>
@@ -571,7 +572,7 @@
and -c allows an alternative configuration file to be
specified.</para>
- <para>Valid commands are: </para>
+ <para>Valid commands are:</para>
<itemizedlist>
<listitem>
@@ -617,14 +618,14 @@
traditional backup software.</para>
<para>Use bbackupd-config to write a configuration file in snapshot
- mode, and then run the following command as a cron job. </para>
+ mode, and then run the following command as a cron job.</para>
<programlisting>/usr/local/bin/bbackupctl -q sync</programlisting>
<para>This will cause the backup daemon to upload all changed files
immediately. <emphasis role="bold">bbackupctl</emphasis> will exit
almost immediately, and will not output anything unless there is an
- error. </para>
+ error.</para>
</section>
<section>
@@ -677,7 +678,7 @@
<para>On systems where GNU readline is available (by default) it uses
that for command line history and editing. Otherwise it falls back to
- very basic UNIX text entry. </para>
+ very basic UNIX text entry.</para>
<para>TODO: Did the readline dependency change to editline?</para>
@@ -687,7 +688,7 @@
<para>bbackupquery is the tool you use to verify, restore and
investigate your backup files with. When invoked, it simply logs
into the server using the certificates you have listed in
- bbackupd.conf. </para>
+ bbackupd.conf.</para>
<para>After you run bbackupquery, you will see a prompt, allowing
you to execute commands. The list (or ls) command lets you view
@@ -818,7 +819,7 @@
correctly.</para>
<para>You may wish to run either one as a cron job while testing
- this system. </para>
+ this system.</para>
</section>
<section>
@@ -843,7 +844,7 @@
backed up directory to make sure it doesn't start uploading the
restored files.)</para>
- <para>Type: </para>
+ <para>Type:</para>
<programlisting>/usr/local/bin/bbackupquery</programlisting>
@@ -876,7 +877,7 @@
versions will make this far more user-friendly.</para>
<para>Firstly, run bbackupquery in interactive mode. It behaves in a
- similar manner to a command line sftp client. </para>
+ similar manner to a command line sftp client.</para>
<programlisting>/usr/local/bin/bbackupquery</programlisting>
@@ -919,7 +920,7 @@
<para>(this is a listing from a server which is used as a Samba
server for a network of Windows clients.) You now need to fetch the
file using it's ID, rather than it's name. The ID is the hex number
- in the first column. Fetch it like this: </para>
+ in the first column. Fetch it like this:</para>
<programlisting>query > get -i 0000437e NTUSER.DAT
Object ID 0000437e fetched successfully.</programlisting>
@@ -960,7 +961,7 @@
<para>These instructions assume you're working on account 1234,
subsitute this for whatever account you're actually working on. These
- will need to be repeated for all affected accounts. </para>
+ will need to be repeated for all affected accounts.</para>
<section>
<title>Stop bbackupd</title>
@@ -983,7 +984,7 @@
retrieve any files you need. Then move the old store directories aside
(in case you need them) and start afresh with new accounts, and let
the clients upload all their data again. These utilities will be
- written shortly! </para>
+ written shortly!</para>
<para>TODO: Is this true anymore???</para>
</section>
@@ -1008,7 +1009,7 @@
<para><emphasis role="bold">NOTE</emphasis>: The utility may adjust
the soft and hard limits on the account to make sure that housekeeping
- will not remove anything -- check these afterwards. </para>
+ will not remove anything -- check these afterwards.</para>
</section>
<section>
@@ -1023,8 +1024,8 @@
directory of the store.</para>
<para>You can skip this step if you are sure that the client machine
- is fine -- in this case, bbackupd will bring the store up to date.
- </para>
+ is fine -- in this case, bbackupd will bring the store up to
+ date.</para>
</section>
<section>
@@ -1061,7 +1062,7 @@
<para>Some common causes of exceptions are listed below.</para>
<para>Please email me with any other codes you get, and I will let you
- know what they mean, and add notes here. </para>
+ know what they mean, and add notes here.</para>
<section>
<title>RaidFile (2/8)</title>
@@ -1101,7 +1102,7 @@
<para><emphasis role="bold">Resolution</emphasis>: Edit bbstored.conf
to point to the correct location of this additional configuration
- file. </para>
+ file.</para>
</section>
<section>
@@ -1116,7 +1117,7 @@
<para><emphasis role="bold">Resolution</emphasis>: Edit bbstored.conf
and correct the ListenAddresses line. You should replace the server
- address with the IP address of your machine. </para>
+ address with the IP address of your machine.</para>
</section>
<section>
@@ -1184,6 +1185,8 @@
</section>
</chapter>
+ &__ExceptionCodes__elfjz3fu;
+
<appendix>
<title id="WORoot">Running without root</title>
@@ -1200,7 +1203,7 @@
<para>To run it entirely as a non-root user, edit the bbstored.conf
file, and remove the User directive from the Server section. Then simply
- run the server as your desired user. </para>
+ run the server as your desired user.</para>
</section>
<section>
@@ -1223,8 +1226,7 @@
logs for reports of this failure.</para>
<para>Non-root operation of the backup client is recommended only for
- testing, and should not be relied on in a production environment.
- </para>
+ testing, and should not be relied on in a production environment.</para>
</section>
</appendix>
</book>
\ No newline at end of file
Modified: box/trunk/documentation/boxbackup/bb-book.xsl
===================================================================
--- box/trunk/documentation/boxbackup/bb-book.xsl 2006-03-29 23:04:26 UTC (rev 549)
+++ box/trunk/documentation/boxbackup/bb-book.xsl 2006-03-30 21:04:14 UTC (rev 550)
@@ -4,12 +4,12 @@
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"/>
-<xsl:param name="html.stylesheet" select="'bbdoc.css'"/>
+<xsl:param name="html.stylesheet" select="'../html/bbdoc.css'"/>
<xsl:param name="chunk.section.depth" select="'0'"/>
<xsl:template name="user.header.navigation">
<div id="header">
<div id="logo">
-<img src="images/bblogo.png" alt="logo" height="65" width="331" border="0" vspace="5" align="middle" /> <img src="images/stepahead.png" alt="a step ahead in data security" width="182" height="11" hspace="10" vspace="20" border="0" align="middle" /></div>
+<img src="../html/images/bblogo.png" alt="logo" height="65" width="331" border="0" vspace="5" align="middle" /> <img src="../html/images/stepahead.png" alt="a step ahead in data security" width="182" height="11" hspace="10" vspace="20" border="0" align="middle" /></div>
</div>
</xsl:template>
Added: box/trunk/documentation/boxbackup/generate_except_xml.pl
===================================================================
--- box/trunk/documentation/boxbackup/generate_except_xml.pl 2006-03-29 23:04:26 UTC (rev 549)
+++ box/trunk/documentation/boxbackup/generate_except_xml.pl 2006-03-30 21:04:14 UTC (rev 550)
@@ -0,0 +1,71 @@
+#!/usr/bin/perl -w
+use strict;
+
+open (EXCEPT, "<../../ExceptionCodes.txt") or die "Can't open ../../ExceptionCodes.txt: $!\n";
+open (DOCBOOK, ">ExceptionCodes.xml") or die "Can't open Exceptioncodes.xml for writing: $!\n";
+
+print DOCBOOK <<EOD;
+<?xml version="1.0" encoding="UTF-8"?>
+
+<appendix>
+ <title>Exception codes</title>
+
+EOD
+my $sectionName;
+my $sectionNum;
+my $sectionDesc;
+my $exceptionCode;
+my $exceptionShortDesc;
+my $exceptionLongDesc;
+while(<EXCEPT>)
+{
+ next if(m/^#/);
+ chomp;
+ if(m/^EXCEPTION TYPE (\w+) (\d+)/)
+ {
+ $sectionName = ucfirst(lc($1));
+ $sectionNum = $2;
+ if($sectionName ne "Common")
+ {
+ $sectionDesc = "the " . $sectionName;
+ }
+ else
+ {
+ $sectionDesc = "any";
+ }
+ print DOCBOOK <<EOD;
+ <section>
+ <title>$sectionName Exceptions ($sectionNum)</title>
+
+ <para>These are exceptions that can occur in $sectionDesc module
+ of the system.</para>
+
+ <itemizedlist>
+EOD
+ }
+
+ # The END TYPE line
+ if(m/^END TYPE$/)
+ {
+ print DOCBOOK " </itemizedlist>\n </section>\n";
+ }
+
+ # The actual exceptions
+ if(m/(\(\d+\/\d+\)) - (\w+ \w+)(?: - )?(.*)$/)
+ {
+ $exceptionCode = $1;
+ $exceptionShortDesc = $2;
+ $exceptionLongDesc = $3;
+
+ print DOCBOOK " <listitem>\n <para><emphasis role=\"bold\">";
+ print DOCBOOK $exceptionCode . ": " . $exceptionShortDesc . "</emphasis>";
+ if($exceptionLongDesc ne "")
+ {
+ print DOCBOOK " -- " . $exceptionLongDesc;
+ }
+ print DOCBOOK "</para>\n </listitem>\n";
+ }
+}
+
+print DOCBOOK "</appendix>\n";
+
\ No newline at end of file