CedarBackup3.extend.amazons3
============================

.. py:module:: CedarBackup3.extend.amazons3

.. autoapi-nested-parse::

   Store-type extension that writes data to Amazon S3.

   This extension requires a new configuration section <amazons3> and is intended
   to be run immediately after the standard stage action, replacing the standard
   store action.  Aside from its own configuration, it requires the options and
   staging configuration sections in the standard Cedar Backup configuration file.
   Since it is intended to replace the store action, it does not rely on any store
   configuration.

   The underlying functionality relies on the U{AWS CLI interface
   <http://aws.amazon.com/documentation/cli/>}.  Before you use this extension,
   you need to set up your Amazon S3 account and configure the AWS CLI connection
   per Amazon's documentation.  The extension assumes that the backup is being
   executed as root, and switches over to the configured backup user to
   communicate with AWS.  So, make sure you configure AWS CLI as the backup user
   and not root.

   You can optionally configure Cedar Backup to encrypt data before sending it
   to S3.  To do that, provide a complete command line using the ``${input``} and
   ``${output``} variables to represent the original input file and the encrypted
   output file.  This command will be executed as the backup user.

   For instance, you can use something like this with GPG::

      /usr/bin/gpg -c --no-use-agent --batch --yes --passphrase-file /home/backup/.passphrase -o ${output} ${input}

   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.::

      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
   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.

   This extension was written for and tested on Linux.  It will throw an exception
   if run on Windows.

   :author: Kenneth J. Pronovici <pronovic@ieee.org>









Module Contents
---------------

.. py:data:: logger

.. py:data:: SU_COMMAND
   :value: ['su']


.. py:data:: AWS_COMMAND
   :value: ['aws']


.. py:data:: STORE_INDICATOR
   :value: 'cback.amazons3'


.. py:class:: AmazonS3Config(warnMidnite=None, s3Bucket=None, encryptCommand=None, fullBackupSizeLimit=None, incrementalBackupSizeLimit=None)

   Class representing Amazon S3 configuration.

   Amazon S3 configuration is used for storing backup data in Amazon's S3 cloud
   storage using the ``s3cmd`` tool.

   The following restrictions exist on data in this class:

      - The s3Bucket value must be a non-empty string
      - The encryptCommand value, if set, must be a non-empty string
      - The full backup size limit, if set, must be a ByteQuantity >= 0
      - The incremental backup size limit, if set, must be a ByteQuantity >= 0



   .. py:attribute:: warnMidnite
      :value: None



   .. py:attribute:: s3Bucket
      :value: None



   .. py:attribute:: encryptCommand
      :value: None



   .. py:attribute:: fullBackupSizeLimit
      :value: None



   .. py:attribute:: incrementalBackupSizeLimit
      :value: None



   .. py:method:: __repr__()

      Official string representation for class instance.



   .. py:method:: __str__()

      Informal string representation for class instance.



   .. py:method:: __eq__(other)

      Equals operator, iplemented in terms of original Python 2 compare operator.



   .. py:method:: __lt__(other)

      Less-than operator, iplemented in terms of original Python 2 compare operator.



   .. py:method:: __gt__(other)

      Greater-than operator, iplemented in terms of original Python 2 compare operator.



   .. py:method:: __cmp__(other)

      Original Python 2 comparison operator.
      :param other: Other object to compare to

      :returns: -1/0/1 depending on whether self is ``<``, ``=`` or ``>`` other



.. py:class:: LocalConfig(xmlData=None, xmlPath=None, validate=True)

   Class representing this extension's configuration document.

   This is not a general-purpose configuration object like the main Cedar
   Backup configuration object.  Instead, it just knows how to parse and emit
   amazons3-specific configuration values.  Third parties who need to read and
   write configuration related to this extension should access it through the
   constructor, ``validate`` and ``addConfig`` methods.

   *Note:* Lists within this class are "unordered" for equality comparisons.



   .. py:attribute:: amazons3
      :value: None



   .. py:method:: __repr__()

      Official string representation for class instance.



   .. py:method:: __str__()

      Informal string representation for class instance.



   .. py:method:: __eq__(other)

      Equals operator, iplemented in terms of original Python 2 compare operator.



   .. py:method:: __lt__(other)

      Less-than operator, iplemented in terms of original Python 2 compare operator.



   .. py:method:: __gt__(other)

      Greater-than operator, iplemented in terms of original Python 2 compare operator.



   .. py:method:: __cmp__(other)

      Original Python 2 comparison operator.
      Lists within this class are "unordered" for equality comparisons.
      :param other: Other object to compare to

      :returns: -1/0/1 depending on whether self is ``<``, ``=`` or ``>`` other



   .. py:method:: validate()

      Validates configuration represented by the object.

      AmazonS3 configuration must be filled in.  Within that, the s3Bucket target must be filled in

      :raises ValueError: If one of the validations fails



   .. py:method:: addConfig(xmlDom, parentNode)

      Adds an <amazons3> configuration section as the next child of a parent.

      Third parties should use this function to write configuration related to
      this extension.

      We add the following fields to the document::

         warnMidnite                 //cb_config/amazons3/warn_midnite
         s3Bucket                    //cb_config/amazons3/s3_bucket
         encryptCommand              //cb_config/amazons3/encrypt
         fullBackupSizeLimit         //cb_config/amazons3/full_size_limit
         incrementalBackupSizeLimit  //cb_config/amazons3/incr_size_limit

      :param xmlDom: DOM tree as from ``impl.createDocument()``
      :param parentNode: Parent that the section should be appended to



.. py:function:: executeAction(configPath, options, config)

   Executes the amazons3 backup action.

   :param configPath: Path to configuration file on disk
   :type configPath: String representing a path on disk
   :param options: Program command-line options
   :type options: Options object
   :param config: Program configuration
   :type config: Config object

   :raises ValueError: Under many generic error conditions
   :raises IOError: If there are I/O problems reading or writing files


