/usr/share/doc/cedar-backup2-doc/manual/ch06s02.html is in cedar-backup2-doc 2.26.5-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Amazon S3 Extension</title><link rel="stylesheet" type="text/css" href="styles.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="Cedar Backup 2 Software Manual"><link rel="up" href="ch06.html" title="Chapter 6. Official Extensions"><link rel="prev" href="ch06.html" title="Chapter 6. Official Extensions"><link rel="next" href="ch06s03.html" title="Subversion Extension"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Amazon S3 Extension</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch06.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Official Extensions</th><td width="20%" align="right"> <a accesskey="n" href="ch06s03.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cedar-extensions-amazons3"></a>Amazon S3 Extension</h2></div></div></div><p>
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.
</p><p>
The underlying functionality relies on the
<a class="ulink" href="http://aws.amazon.com/documentation/cli/" target="_top">AWS CLI</a> toolset.
Before you use this extension, you need to set up your Amazon S3
account and configure AWS CLI as detailed in Amazons's
<a class="ulink" href="http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-set-up.html" target="_top">setup guide</a>.
The extension assumes that the backup is being executed as root, and
switches over to the configured backup user to run the
<span class="command"><strong>aws</strong></span> program. So, make sure you configure the AWS
CLI tools as the backup user and not root. (This is different than
the amazons3 sync tool extension, which executes AWS CLI command as
the same user that is running the tool.)
</p><p>
When using physical media via the standard store action, there is an
implicit limit to the size of a backup, since a backup must fit on a
single disc. Since there is no physical media, no such limit exists
for Amazon S3 backups. This leaves open the possibility that Cedar
Backup might construct an unexpectedly-large backup that the
administrator is not aware of. Over time, this might become
expensive, either in terms of network bandwidth or in terms of Amazon
S3 storage and I/O charges. To mitigate this risk, set a reasonable
maximum size using the configuration elements shown below. If the
backup fails, you have a chance to review what made the backup larger
than you expected, and you can either correct the problem (i.e. remove
a large temporary directory that got inadvertently included in the
backup) or change configuration to take into account the new "normal"
maximum size.
</p><p>
You can optionally configure Cedar Backup to encrypt data before
sending it to S3. To do that, provide a complete command line using
the <code class="literal">${input}</code> and <code class="literal">${output}</code>
variables to represent the original input file and the encrypted
output file. This command will be executed as the backup user.
</p><p>
For instance, you can use something like this with GPG:
</p><pre class="programlisting">
/usr/bin/gpg -c --no-use-agent --batch --yes --passphrase-file /home/backup/.passphrase -o ${output} ${input}
</pre><p>
The GPG mechanism depends on a strong passphrase for security. One way to
generate a strong passphrase is using your system random number generator, i.e.:
</p><pre class="programlisting">
dd if=/dev/urandom count=20 bs=1 | xxd -ps
</pre><p>
(See <a class="ulink" href="http://security.stackexchange.com/questions/14867/gpg-encryption-security" target="_top">StackExchange</a>
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. And obviously, make sure to set permissions on the
passphrase file so it can only be read by the backup user.
</p><p>
To enable this extension, add the following section to the Cedar Backup
configuration file:
</p><pre class="programlisting">
<extensions>
<action>
<name>amazons3</name>
<module>CedarBackup2.extend.amazons3</module>
<function>executeAction</function>
<index>201</index> <!-- just after stage -->
</action>
</extensions>
</pre><p>
This extension relies on the options and staging configuration sections
in the standard Cedar Backup configuration file, and then also
requires its own <code class="literal">amazons3</code> configuration section.
This is an example configuration section with encryption disabled:
</p><pre class="programlisting">
<amazons3>
<s3_bucket>example.com-backup/staging</s3_bucket>
</amazons3>
</pre><p>
The following elements are part of the Amazon S3 configuration section:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">warn_midnite</code></span></dt><dd><p>Whether to generate warnings for crossing midnite.</p><p>
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 data was only
found in the day before or day after the current day.
</p><p>
Configuration for some users is such that the amazons3
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 <span class="quote">“<span class="quote">strange</span>”</span> might have happened.
</p><p>
This field is optional. If it doesn't exist, then
<code class="literal">N</code> will be assumed.
</p><p>
<span class="emphasis"><em>Restrictions:</em></span> Must be a boolean (<code class="literal">Y</code> or <code class="literal">N</code>).
</p></dd><dt><span class="term"><code class="literal">s3_bucket</code></span></dt><dd><p>The name of the Amazon S3 bucket that data will be written to.</p><p>
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 <code class="literal">example.com-backup</code>.
If you want, you can specify a subdirectory within the bucket,
such as <code class="literal">example.com-backup/staging</code>.
</p><p>
<span class="emphasis"><em>Restrictions:</em></span> Must be non-empty.
</p></dd><dt><span class="term"><code class="literal">encrypt</code></span></dt><dd><p>Command used to encrypt backup data before upload to S3</p><p>
If this field is provided, then data will be encrypted before
it is uploaded to Amazon S3. You must provide the entire
command used to encrypt a file, including the
<code class="literal">${input}</code> and <code class="literal">${output}</code>
variables. An example GPG command is shown above, but you
can use any mechanism you choose. The command will be run as
the configured backup user.
</p><p>
<span class="emphasis"><em>Restrictions:</em></span> If provided, must be non-empty.
</p></dd><dt><span class="term"><code class="literal">full_size_limit</code></span></dt><dd><p>Maximum size of a full backup</p><p>
If this field is provided, then a size limit will be applied
to full backups. If the total size of the selected staging
directory is greater than the limit, then the backup will
fail.
</p><p>
You can enter this value in two different forms. It can
either be a simple number, in which case the value is assumed
to be in bytes; or it can be a number followed by a unit
(KB, MB, GB).
</p><p>
Valid examples are <span class="quote">“<span class="quote">10240</span>”</span>, <span class="quote">“<span class="quote">250
MB</span>”</span> or <span class="quote">“<span class="quote">1.1 GB</span>”</span>.
</p><p>
<span class="emphasis"><em>Restrictions:</em></span> Must be a value as described above, greater than zero.
</p></dd><dt><span class="term"><code class="literal">incr_size_limit</code></span></dt><dd><p>Maximum size of an incremental backup</p><p>
If this field is provided, then a size limit will be applied
to incremental backups. If the total size of the selected
staging directory is greater than the limit, then the backup
will fail.
</p><p>
You can enter this value in two different forms. It can
either be a simple number, in which case the value is assumed
to be in bytes; or it can be a number followed by a unit
(KB, MB, GB).
</p><p>
Valid examples are <span class="quote">“<span class="quote">10240</span>”</span>, <span class="quote">“<span class="quote">250
MB</span>”</span> or <span class="quote">“<span class="quote">1.1 GB</span>”</span>.
</p><p>
<span class="emphasis"><em>Restrictions:</em></span> Must be a value as described above, greater than zero.
</p></dd></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch06.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch06.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch06s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 6. Official Extensions </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Subversion Extension</td></tr></table></div></body></html>
|