[cedar-backup-svn] SF.net SVN: cedar-backup:[1053] cedar-backup2/trunk
Brought to you by:
pronovic
Menu
▾
▴
[cedar-backup-svn] SF.net SVN: cedar-backup:[1053] cedar-backup2/trunk
|
From: <pro...@us...> - 2014-10-01 21:42:20
|
Revision: 1053
http://sourceforge.net/p/cedar-backup/code/1053
Author: pronovic
Date: 2014-10-01 21:42:12 +0000 (Wed, 01 Oct 2014)
Log Message:
-----------
Finish user documentation for amazons3 extension
Modified Paths:
--------------
cedar-backup2/trunk/CedarBackup2/extend/amazons3.py
cedar-backup2/trunk/manual/src/depends.xml
cedar-backup2/trunk/manual/src/extensions.xml
Modified: cedar-backup2/trunk/CedarBackup2/extend/amazons3.py
===================================================================
--- cedar-backup2/trunk/CedarBackup2/extend/amazons3.py 2014-10-01 20:30:20 UTC (rev 1052)
+++ cedar-backup2/trunk/CedarBackup2/extend/amazons3.py 2014-10-01 21:42:12 UTC (rev 1053)
@@ -46,10 +46,10 @@
Since it is intended to replace the store action, it does not rely on any store
configuration.
-The underlying functionality relies on the U{{Amazon S3Tools} <http://s3tools.org/>}
+The underlying functionality relies on the U{Amazon S3Tools <http://s3tools.org/>}
package. It is a very thin wrapper around the C{s3cmd put} command. Before
you use this extension, you need to set up your Amazon S3 account and configure
-C{s3cmd} as detailed in the U{{HOWTO} <http://s3tools.org/s3cmd-howto>}. The
+C{s3cmd} as detailed in the U{HOWTO <http://s3tools.org/s3cmd-howto>}. The
extension assumes that the backup is being executed as root, and switches over
to the configured backup user to run the C{s3cmd} program. So, make sure you
configure S3 Tools as the backup user and not root.
@@ -57,7 +57,7 @@
It's up to you how to configure the S3 Tools connection to Amazon, but I
recommend that you configure GPG encryption using a strong passphrase. One way
to generate a strong passphrase is using your system random number generator,
-i.e. C{dd if=/dev/urandom count=20 bs=1 | xxd -ps}. (See U{{StackExchange}
+i.e. C{dd if=/dev/urandom count=20 bs=1 | xxd -ps}. (See U{StackExchange
<http://security.stackexchange.com/questions/14867/gpg-encryption-security>}
for more details about that advice.) If you decide to use encryption, make sure
you save off the passphrase in a safe place, so you can get at your backup data
Modified: cedar-backup2/trunk/manual/src/depends.xml
===================================================================
--- cedar-backup2/trunk/manual/src/depends.xml 2014-10-01 20:30:20 UTC (rev 1052)
+++ cedar-backup2/trunk/manual/src/depends.xml 2014-10-01 21:42:12 UTC (rev 1053)
@@ -41,13 +41,13 @@
<variablelist>
<varlistentry>
- <term>Python 2.5</term>
+ <term>Python 2.5 (or later)</term>
<listitem>
<para>
Version 2.5 of the Python interpreter was released on 19 Sep
- 2006, so most current Linux and BSD distributions should
- include it.
+ 2006, so virtually any current Linux and BSD distributions should
+ include it or a later version.
</para>
<informaltable>
@@ -556,6 +556,47 @@
</varlistentry>
<varlistentry>
+ <term><command>s3cmd</command></term>
+ <listitem>
+
+ <para>
+ The <command>s3cmd</command> command is used by the Amazon S3
+ extension to communicate with Amazon AWS.
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"/>
+ <colspec colnum="2" colwidth="3.5*"/>
+ <thead>
+ <row>
+ <entry>Source</entry>
+ <entry>URL</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>upstream</entry>
+ <entry><ulink url="http://s3tools.org/s3cmd"/></entry>
+ </row>
+ <row>
+ <entry>Debian</entry>
+ <entry><ulink url="https://packages.debian.org/stable/s3cmd"/></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ If you can't find a package for your system, install from the package
+ source, using the <quote>upstream</quote> link.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
<term><command>split</command></term>
<listitem>
Modified: cedar-backup2/trunk/manual/src/extensions.xml
===================================================================
--- cedar-backup2/trunk/manual/src/extensions.xml 2014-10-01 20:30:20 UTC (rev 1052)
+++ cedar-backup2/trunk/manual/src/extensions.xml 2014-10-01 21:42:12 UTC (rev 1053)
@@ -93,6 +93,134 @@
<!-- ################################################################# -->
+ <sect1 id="cedar-extensions-amazons3">
+
+ <title>Amazon S3 Extension</title>
+
+ <para>
+ The Amazon S3 extension writes data to Amazon S3 cloud storage rather
+ than to physical media. It is intended to replace the store action,
+ but you can also use it alongside the store action if you'd prefer to
+ backup your data in more than one place. This extension must be run
+ after the stage action.
+ </para>
+
+ <para>
+ The underlying functionality relies on the
+ <ulink url="http://s3tools.org/">Amazon S3 Tools</ulink> package. It
+ is a very thin wrapper around the <literal>s3cmd put</literal>
+ command. Before you use this extension, you need to set up your
+ Amazon S3 account and configure <literal>s3cmd</literal> as detailed
+ in the <ulink url="http://s3tools.org/s3cmd-howto">HOWTO</ulink>.
+ The extension assumes that the backup is being executed as root, and
+ switches over to the configured backup user to run the
+ <literal>s3cmd</literal> program. So, make sure you configure the S3
+ tools as the backup user and not root.
+ </para>
+
+ <para>
+ When configuring the S3 tools connection to Amazon AWS, you probably want
+ to configure GPG encryption using a strong passphrase. One way
+ to generate a strong passphrase is using your system random number generator,
+ i.e. <literal>dd if=/dev/urandom count=20 bs=1 | xxd -ps</literal>. (See
+ <ulink url="http://security.stackexchange.com/questions/14867/gpg-encryption-security">StackExchange</ulink>
+ for more details about that advice.) If you decide to use encryption, make sure
+ you save off the passphrase in a safe place, so you can get at your backup data
+ later if you need to.
+ </para>
+
+ <para>
+ This extension was written for and tested on Linux. It will throw an exception
+ if run on Windows.
+ </para>
+
+ <para>
+ To enable this extension, add the following section to the Cedar Backup
+ configuration file:
+ </para>
+
+ <programlisting>
+<extensions> <action>
+ <action>
+ <name>amazons3</name>
+ <module>CedarBackup2.extend.amazons3</module>
+ <function>executeAction</function>
+ <index>201</index> <!-- just after stage -->
+ </action>
+</extensions>
+ </programlisting>
+
+ <para>
+ This extension relies on the options and staging configuration sections
+ in the standard Cedar Backup configuration file, and then also
+ requires its own <literal>amazons3</literal> configuration section.
+ This is an example configuration section:
+ </para>
+
+ <programlisting>
+<amazons3>
+ <s3_bucket>example.com-backup/staging</s3_bucket>
+</amazons3>
+ </programlisting>
+
+ <para>
+ The following elements are part of the Amazon S3 configuration section:
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><literal>warn_midnite</literal></term>
+ <listitem>
+ <para>Whether to generate warnings for crossing midnite.</para>
+ <para>
+ This field indicates whether warnings should be generated
+ if the Amazon S3 operation has to cross a midnite boundary in
+ order to find data to write to the cloud. For instance, a
+ warning would be generated if valid store data was only
+ found in the day before or day after the current day.
+ </para>
+ <para>
+ Configuration for some users is such that the store
+ operation will always cross a midnite boundary, so they
+ will not care about this warning. Other users will expect
+ to never cross a boundary, and want to be notified that
+ something <quote>strange</quote> might have happened.
+ </para>
+ <para>
+ This field is optional. If it doesn't exist, then
+ <literal>N</literal> will be assumed.
+ </para>
+ <para>
+ <emphasis>Restrictions:</emphasis> Must be a boolean (<literal>Y</literal> or <literal>N</literal>).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>s3_bucket</literal></term>
+ <listitem>
+ <para>The name of the Amazon S3 bucket that data will be written to.</para>
+ <para>
+ This field configures the S3 bucket that your data will be
+ written to. In S3, buckets are named globally. For
+ uniqueness, you would typically use the name of your domain
+ followed by some suffix, such as <literal>example.com-backup</literal>.
+ If you want, you can specify a subdirectory within the bucket,
+ such as <literal>example.com-backup/staging</literal>.
+ </para>
+ <para>
+ <emphasis>Restrictions:</emphasis> Must be non-empty.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </sect1>
+
+ <!-- ################################################################# -->
+
<sect1 id="cedar-extensions-subversion">
<title>Subversion Extension</title>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
