CedarBackup3.extend package — Cedar Backup v3 documentation

# CedarBackup3.extend package

Official Cedar Backup Extensions

This package provides official Cedar Backup extensions. These are Cedar Backup actions that are not part of the “standard” set of Cedar Backup actions, but are officially supported along with Cedar Backup.

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

## Submodules

## CedarBackup3.extend.amazons3 module

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>

class `CedarBackup3.extend.amazons3.` `AmazonS3Config`(warnMidnite=None, s3Bucket=None, encryptCommand=None, fullBackupSizeLimit=None, incrementalBackupSizeLimit=None)

  Bases: `object`

  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

  `__init__`(warnMidnite=None, s3Bucket=None, encryptCommand=None, fullBackupSizeLimit=None, incrementalBackupSizeLimit=None)

    Constructor for the `AmazonS3Config` class.

    Parameters: | warnMidnite – Whether to generate warnings for crossing midnite s3Bucket – Name of the Amazon S3 bucket in which to store the data encryptCommand – Command used to encrypt backup data before upload to S3 fullBackupSizeLimit – Maximum size of a full backup, a ByteQuantity incrementalBackupSizeLimit – Maximum size of an incremental backup, a ByteQuantity
    Raises: | `ValueError` – If one of the values is invalid

  `encryptCommand`

    Command used to encrypt data before upload to S3

  `fullBackupSizeLimit`

    Maximum size of a full backup, as a ByteQuantity

  `incrementalBackupSizeLimit`

    Maximum size of an incremental backup, as a ByteQuantity

  `s3Bucket`

    Amazon S3 Bucket in which to store data

  `warnMidnite`

    Whether to generate warnings for crossing midnite.

class `CedarBackup3.extend.amazons3.` `LocalConfig`(xmlData=None, xmlPath=None, validate=True)

  Bases: `object`

  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.

  `__init__`(xmlData=None, xmlPath=None, validate=True)

    Initializes a configuration object.

    If you initialize the object without passing either `xmlData` or `xmlPath` then configuration will be empty and will be invalid until it is filled in properly.

    No reference to the original XML data or original path is saved off by this class. Once the data has been parsed (successfully or not) this original information is discarded.

    Unless the `validate` argument is `False`, the `LocalConfig.validate` method will be called (with its default arguments) against configuration after successfully parsing any passed-in XML. Keep in mind that even if `validate` is `False`, it might not be possible to parse the passed-in XML document if lower-level validations fail.

    Note: It is strongly suggested that the `validate` option always be set to `True` (the default) unless there is a specific need to read in invalid configuration from disk.

    Parameters: | xmlData (String data) – XML data representing configuration xmlPath (Absolute path to a file on disk) – Path to an XML file on disk validate (Boolean true/false) – Validate the document after parsing it
    Raises: | `ValueError` – If both `xmlData` and `xmlPath` are passed-in `ValueError` – If the XML data in `xmlData` or `xmlPath` cannot be parsed `ValueError` – If the parsed configuration document is not valid

  `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

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

  `amazons3`

    AmazonS3 configuration in terms of a `AmazonS3Config` object.

  `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

`CedarBackup3.extend.amazons3.` `executeAction`(configPath, options, config)

  Executes the amazons3 backup action.

  Parameters: | configPath (String representing a path on disk) – Path to configuration file on disk options (Options object) – Program command-line options config (Config object) – Program configuration
  Raises: | `ValueError` – Under many generic error conditions `IOError` – If there are I/O problems reading or writing files

## CedarBackup3.extend.capacity module

Provides an extension to check remaining media capacity.

Some users have asked for advance warning that their media is beginning to fill up. This is an extension that checks the current capacity of the media in the writer, and prints a warning if the media is more than X% full, or has fewer than X bytes of capacity remaining.

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

class `CedarBackup3.extend.capacity.` `CapacityConfig`(maxPercentage=None, minBytes=None)

  Bases: `object`

  Class representing capacity configuration.

  The following restrictions exist on data in this class:

  > - The maximum percentage utilized must be a PercentageQuantity
  > - The minimum bytes remaining must be a ByteQuantity

  `__init__`(maxPercentage=None, minBytes=None)

    Constructor for the `CapacityConfig` class.

    Parameters: | maxPercentage – Maximum percentage of the media that may be utilized minBytes – Minimum number of free bytes that must be available

  `maxPercentage`

    Maximum percentage of the media that may be utilized.

  `minBytes`

    Minimum number of free bytes that must be available.

class `CedarBackup3.extend.capacity.` `LocalConfig`(xmlData=None, xmlPath=None, validate=True)

  Bases: `object`

  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 specific configuration values to this extension. 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.

  `__init__`(xmlData=None, xmlPath=None, validate=True)

    Initializes a configuration object.

    If you initialize the object without passing either `xmlData` or `xmlPath` then configuration will be empty and will be invalid until it is filled in properly.

    No reference to the original XML data or original path is saved off by this class. Once the data has been parsed (successfully or not) this original information is discarded.

    Unless the `validate` argument is `False`, the `LocalConfig.validate` method will be called (with its default arguments) against configuration after successfully parsing any passed-in XML. Keep in mind that even if `validate` is `False`, it might not be possible to parse the passed-in XML document if lower-level validations fail.

    Note: It is strongly suggested that the `validate` option always be set to `True` (the default) unless there is a specific need to read in invalid configuration from disk.

    Parameters: | xmlData (String data) – XML data representing configuration xmlPath (Absolute path to a file on disk) – Path to an XML file on disk validate (Boolean true/false) – Validate the document after parsing it
    Raises: | `ValueError` – If both `xmlData` and `xmlPath` are passed-in `ValueError` – If the XML data in `xmlData` or `xmlPath` cannot be parsed `ValueError` – If the parsed configuration document is not valid

  `addConfig`(xmlDom, parentNode)

    Adds a <capacity> 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:

        maxPercentage  //cb_config/capacity/max_percentage
        minBytes       //cb_config/capacity/min_bytes

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

  `capacity`

    Capacity configuration in terms of a `CapacityConfig` object.

  `validate`()

    Validates configuration represented by the object. THere must be either a percentage, or a byte capacity, but not both. :raises: `ValueError` – If one of the validations fails

class `CedarBackup3.extend.capacity.` `PercentageQuantity`(quantity=None)

  Bases: `object`

  Class representing a percentage quantity.

  The percentage is maintained internally as a string so that issues of precision can be avoided. It really isn’t possible to store a floating point number here while being able to losslessly translate back and forth between XML and object representations. (Perhaps the Python 2.4 Decimal class would have been an option, but I originally wanted to stay compatible with Python 2.3.)

  Even though the quantity is maintained as a string, the string must be in a valid floating point positive number. Technically, any floating point string format supported by Python is allowble. However, it does not make sense to have a negative percentage in this context.

  `__init__`(quantity=None)

    Constructor for the `PercentageQuantity` class. :param quantity: Percentage quantity, as a string (i.e. “99.9” or “12”)

    Raises: | `ValueError` – If the quantity value is invaid

  `percentage`

    Percentage value, as a floating point number.

  `quantity`

    Percentage value, as a string

`CedarBackup3.extend.capacity.` `executeAction`(configPath, options, config)

  Executes the capacity action.

  Parameters: | configPath (String representing a path on disk) – Path to configuration file on disk options (Options object) – Program command-line options config (Config object) – Program configuration
  Raises: | `ValueError` – Under many generic error conditions `IOError` – If there are I/O problems reading or writing files

## CedarBackup3.extend.encrypt module

Provides an extension to encrypt staging directories.

When this extension is executed, all backed-up files in the configured Cedar Backup staging directory will be encrypted using gpg. Any directory which has already been encrypted (as indicated by the `cback.encrypt` file) will be ignored.

This extension requires a new configuration section <encrypt> and is intended to be run immediately after the standard stage action or immediately before the standard store action. Aside from its own configuration, it requires the options and staging configuration sections in the standard Cedar Backup configuration file.

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

class `CedarBackup3.extend.encrypt.` `EncryptConfig`(encryptMode=None, encryptTarget=None)

  Bases: `object`

  Class representing encrypt configuration.

  Encrypt configuration is used for encrypting staging directories.

  The following restrictions exist on data in this class:

  > - The encrypt mode must be one of the values in `VALID_ENCRYPT_MODES`
  > - The encrypt target value must be a non-empty string

  `__init__`(encryptMode=None, encryptTarget=None)

    Constructor for the `EncryptConfig` class.

    Parameters: | encryptMode – Encryption mode encryptTarget – Encryption target (for instance, GPG recipient)
    Raises: | `ValueError` – If one of the values is invalid

  `encryptMode`

    Encrypt mode.

  `encryptTarget`

    Encrypt target (i.e. GPG recipient).

class `CedarBackup3.extend.encrypt.` `LocalConfig`(xmlData=None, xmlPath=None, validate=True)

  Bases: `object`

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

  `__init__`(xmlData=None, xmlPath=None, validate=True)

    Initializes a configuration object.

    If you initialize the object without passing either `xmlData` or `xmlPath` then configuration will be empty and will be invalid until it is filled in properly.

    No reference to the original XML data or original path is saved off by this class. Once the data has been parsed (successfully or not) this original information is discarded.

    Unless the `validate` argument is `False`, the `LocalConfig.validate` method will be called (with its default arguments) against configuration after successfully parsing any passed-in XML. Keep in mind that even if `validate` is `False`, it might not be possible to parse the passed-in XML document if lower-level validations fail.

    Note: It is strongly suggested that the `validate` option always be set to `True` (the default) unless there is a specific need to read in invalid configuration from disk.

    Parameters: | xmlData (String data) – XML data representing configuration xmlPath (Absolute path to a file on disk) – Path to an XML file on disk validate (Boolean true/false) – Validate the document after parsing it
    Raises: | `ValueError` – If both `xmlData` and `xmlPath` are passed-in `ValueError` – If the XML data in `xmlData` or `xmlPath` cannot be parsed `ValueError` – If the parsed configuration document is not valid

  `addConfig`(xmlDom, parentNode)

    Adds an <encrypt> 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:

        encryptMode    //cb_config/encrypt/encrypt_mode
        encryptTarget  //cb_config/encrypt/encrypt_target

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

  `encrypt`

    Encrypt configuration in terms of a `EncryptConfig` object.

  `validate`()

    Validates configuration represented by the object.

    Encrypt configuration must be filled in. Within that, both the encrypt mode and encrypt target must be filled in.

    Raises: | `ValueError` – If one of the validations fails

`CedarBackup3.extend.encrypt.` `executeAction`(configPath, options, config)

  Executes the encrypt backup action.

  Parameters: | configPath (String representing a path on disk) – Path to configuration file on disk options (Options object) – Program command-line options config (Config object) – Program configuration
  Raises: | `ValueError` – Under many generic error conditions `IOError` – If there are I/O problems reading or writing files

## CedarBackup3.extend.mbox module

Provides an extension to back up mbox email files.

### Backing up email

> Email folders (often stored as mbox flatfiles) are not well-suited being backed up with an incremental backup like the one offered by Cedar Backup. This is because mbox files often change on a daily basis, forcing the incremental backup process to back them up every day in order to avoid losing data. This can result in quite a bit of wasted space when backing up large folders. (Note that the alternative maildir format does not share this problem, since it typically uses one file per message.)

> One solution to this problem is to design a smarter incremental backup process, which backs up baseline content on the first day of the week, and then backs up only new messages added to that folder on every other day of the week. This way, the backup for any single day is only as large as the messages placed into the folder on that day. The backup isn’t as “perfect” as the incremental backup process, because it doesn’t preserve information about messages deleted from the backed-up folder. However, it should be much more space-efficient, and in a recovery situation, it seems better to restore too much data rather than too little.

### What is this extension?

> This is a Cedar Backup extension used to back up mbox email files via the Cedar Backup command line. Individual mbox files or directories containing mbox files can be backed up using the same collect modes allowed for filesystems in the standard Cedar Backup collect action: weekly, daily, incremental. It implements the “smart” incremental backup process discussed above, using functionality provided by the `grepmail` utility.

> This extension requires a new configuration section <mbox> and is intended to be run either immediately before or immediately after the standard collect action. Aside from its own configuration, it requires the options and collect configuration sections in the standard Cedar Backup configuration file.

> The mbox action is conceptually similar to the standard collect action, except that mbox directories are not collected recursively. This implies some configuration changes (i.e. there’s no need for global exclusions or an ignore file). If you back up a directory, all of the mbox files in that directory are backed up into a single tar file using the indicated compression method.

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

class `CedarBackup3.extend.mbox.` `LocalConfig`(xmlData=None, xmlPath=None, validate=True)

  Bases: `object`

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

  `__init__`(xmlData=None, xmlPath=None, validate=True)

    Initializes a configuration object.

    If you initialize the object without passing either `xmlData` or `xmlPath` then configuration will be empty and will be invalid until it is filled in properly.

    No reference to the original XML data or original path is saved off by this class. Once the data has been parsed (successfully or not) this original information is discarded.

    Unless the `validate` argument is `False`, the `LocalConfig.validate` method will be called (with its default arguments) against configuration after successfully parsing any passed-in XML. Keep in mind that even if `validate` is `False`, it might not be possible to parse the passed-in XML document if lower-level validations fail.

    Note: It is strongly suggested that the `validate` option always be set to `True` (the default) unless there is a specific need to read in invalid configuration from disk.

    Parameters: | xmlData (String data) – XML data representing configuration xmlPath (Absolute path to a file on disk) – Path to an XML file on disk validate (Boolean true/false) – Validate the document after parsing it
    Raises: | `ValueError` – If both `xmlData` and `xmlPath` are passed-in `ValueError` – If the XML data in `xmlData` or `xmlPath` cannot be parsed `ValueError` – If the parsed configuration document is not valid

  `addConfig`(xmlDom, parentNode)

    Adds an <mbox> 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:

        collectMode    //cb_config/mbox/collectMode
        compressMode   //cb_config/mbox/compressMode

    We also add groups of the following items, one list element per item:

        mboxFiles      //cb_config/mbox/file
        mboxDirs       //cb_config/mbox/dir

    The mbox files and mbox directories are added by `_addMboxFile` and `_addMboxDir`.

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

  `mbox`

    Mbox configuration in terms of a `MboxConfig` object.

  `validate`()

    Validates configuration represented by the object.

    Mbox configuration must be filled in. Within that, the collect mode and compress mode are both optional, but the list of repositories must contain at least one entry.

    Each configured file or directory must contain an absolute path, and then must be either able to take collect mode and compress mode configuration from the parent `MboxConfig` object, or must set each value on its own.

    Raises: | `ValueError` – If one of the validations fails

class `CedarBackup3.extend.mbox.` `MboxConfig`(collectMode=None, compressMode=None, mboxFiles=None, mboxDirs=None)

  Bases: `object`

  Class representing mbox configuration.

  Mbox configuration is used for backing up mbox email files.

  The following restrictions exist on data in this class:

  > - The collect mode must be one of the values in `VALID_COLLECT_MODES`.
  > - The compress mode must be one of the values in `VALID_COMPRESS_MODES`.
  > - The `mboxFiles` list must be a list of `MboxFile` objects
  > - The `mboxDirs` list must be a list of `MboxDir` objects

  For the `mboxFiles` and `mboxDirs` lists, validation is accomplished through the `util.ObjectTypeList` list implementation that overrides common list methods and transparently ensures that each element is of the proper type.

  Unlike collect configuration, no global exclusions are allowed on this level. We only allow relative exclusions at the mbox directory level. Also, there is no configured ignore file. This is because mbox directory backups are not recursive.

  Note: Lists within this class are “unordered” for equality comparisons.

  `__init__`(collectMode=None, compressMode=None, mboxFiles=None, mboxDirs=None)

    Constructor for the `MboxConfig` class.

    Parameters: | collectMode – Default collect mode compressMode – Default compress mode mboxFiles – List of mbox files to back up mboxDirs – List of mbox directories to back up
    Raises: | `ValueError` – If one of the values is invalid

  `collectMode`

    Default collect mode.

  `compressMode`

    Default compress mode.

  `mboxDirs`

    List of mbox directories to back up.

  `mboxFiles`

    List of mbox files to back up.

class `CedarBackup3.extend.mbox.` `MboxDir`(absolutePath=None, collectMode=None, compressMode=None, relativeExcludePaths=None, excludePatterns=None)

  Bases: `object`

  Class representing mbox directory configuration..

  The following restrictions exist on data in this class:

  > - The absolute path must be absolute.
  > - The collect mode must be one of the values in `VALID_COLLECT_MODES`.
  > - The compress mode must be one of the values in `VALID_COMPRESS_MODES`.

  Unlike collect directory configuration, this is the only place exclusions are allowed (no global exclusions at the <mbox> configuration level). Also, we only allow relative exclusions and there is no configured ignore file. This is because mbox directory backups are not recursive.

  `__init__`(absolutePath=None, collectMode=None, compressMode=None, relativeExcludePaths=None, excludePatterns=None)

    Constructor for the `MboxDir` class.

    You should never directly instantiate this class.

    Parameters: | absolutePath – Absolute path to a mbox file on disk collectMode – Overridden collect mode for this directory compressMode – Overridden compression mode for this directory relativeExcludePaths – List of relative paths to exclude excludePatterns – List of regular expression patterns to exclude

  `absolutePath`

    Absolute path to the mbox directory.

  `collectMode`

    Overridden collect mode for this mbox directory.

  `compressMode`

    Overridden compress mode for this mbox directory.

  `excludePatterns`

    List of regular expression patterns to exclude.

  `relativeExcludePaths`

    List of relative paths to exclude.

class `CedarBackup3.extend.mbox.` `MboxFile`(absolutePath=None, collectMode=None, compressMode=None)

  Bases: `object`

  Class representing mbox file configuration..

  The following restrictions exist on data in this class:

  > - The absolute path must be absolute.
  > - The collect mode must be one of the values in `VALID_COLLECT_MODES`.
  > - The compress mode must be one of the values in `VALID_COMPRESS_MODES`.

  `__init__`(absolutePath=None, collectMode=None, compressMode=None)

    Constructor for the `MboxFile` class.

    You should never directly instantiate this class.

    Parameters: | absolutePath – Absolute path to an mbox file on disk collectMode – Overridden collect mode for this directory compressMode – Overridden compression mode for this directory

  `absolutePath`

    Absolute path to the mbox file.

  `collectMode`

    Overridden collect mode for this mbox file.

  `compressMode`

    Overridden compress mode for this mbox file.

`CedarBackup3.extend.mbox.` `executeAction`(configPath, options, config)

  Executes the mbox backup action.

  Parameters: | configPath (String representing a path on disk) – Path to configuration file on disk options (Options object) – Program command-line options config (Config object) – Program configuration
  Raises: | `ValueError` – Under many generic error conditions `IOError` – If a backup could not be written for some reason

## CedarBackup3.extend.mysql module

Provides an extension to back up MySQL databases.

This is a Cedar Backup extension used to back up MySQL databases via the Cedar Backup command line. It requires a new configuration section <mysql> and is intended to be run either immediately before or immediately after the standard collect action. Aside from its own configuration, it requires the options and collect configuration sections in the standard Cedar Backup configuration file.

The backup is done via the `mysqldump` command included with the MySQL product. Output can be compressed using `gzip` or `bzip2`. Administrators can configure the extension either to back up all databases or to back up only specific databases. Note that this code always produces a full backup. There is currently no facility for making incremental backups. If/when someone has a need for this and can describe how to do it, I’ll update this extension or provide another.

The extension assumes that all configured databases can be backed up by a single user. Often, the “root” database user will be used. An alternative is to create a separate MySQL “backup” user and grant that user rights to read (but not write) various databases as needed. This second option is probably the best choice.

The extension accepts a username and password in configuration. However, you probably do not want to provide those values in Cedar Backup configuration. This is because Cedar Backup will provide these values to `mysqldump` via the command-line `--user` and `--password` switches, which will be visible to other users in the process listing.

Instead, you should configure the username and password in one of MySQL’s configuration files. Typically, that would be done by putting a stanza like this in `/root/.my.cnf`:

    [mysqldump]
    user     = root
    password = <secret>

Regardless of whether you are using `~/.my.cnf` or `/etc/cback3.conf` to store database login and password information, you should be careful about who is allowed to view that information. Typically, this means locking down permissions so that only the file owner can read the file contents (i.e. use mode `0600`).

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

class `CedarBackup3.extend.mysql.` `LocalConfig`(xmlData=None, xmlPath=None, validate=True)

  Bases: `object`

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

  `__init__`(xmlData=None, xmlPath=None, validate=True)

    Initializes a configuration object.

    If you initialize the object without passing either `xmlData` or `xmlPath` then configuration will be empty and will be invalid until it is filled in properly.

    No reference to the original XML data or original path is saved off by this class. Once the data has been parsed (successfully or not) this original information is discarded.

    Unless the `validate` argument is `False`, the `LocalConfig.validate` method will be called (with its default arguments) against configuration after successfully parsing any passed-in XML. Keep in mind that even if `validate` is `False`, it might not be possible to parse the passed-in XML document if lower-level validations fail.

    Note: It is strongly suggested that the `validate` option always be set to `True` (the default) unless there is a specific need to read in invalid configuration from disk.

    Parameters: | xmlData (String data) – XML data representing configuration xmlPath (Absolute path to a file on disk) – Path to an XML file on disk validate (Boolean true/false) – Validate the document after parsing it
    Raises: | `ValueError` – If both `xmlData` and `xmlPath` are passed-in `ValueError` – If the XML data in `xmlData` or `xmlPath` cannot be parsed `ValueError` – If the parsed configuration document is not valid

  `addConfig`(xmlDom, parentNode)

    Adds a <mysql> 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:

        user           //cb_config/mysql/user
        password       //cb_config/mysql/password
        compressMode   //cb_config/mysql/compress_mode
        all            //cb_config/mysql/all

    We also add groups of the following items, one list element per item:

        database       //cb_config/mysql/database

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

  `mysql`

    Mysql configuration in terms of a `MysqlConfig` object.

  `validate`()

    Validates configuration represented by the object.

    The compress mode must be filled in. Then, if the ‘all’ flag is set, no databases are allowed, and if the ‘all’ flag is not set, at least one database is required.

    Raises: | `ValueError` – If one of the validations fails

class `CedarBackup3.extend.mysql.` `MysqlConfig`(user=None, password=None, compressMode=None, all=None, databases=None)

  Bases: `object`

  Class representing MySQL configuration.

  The MySQL configuration information is used for backing up MySQL databases.

  The following restrictions exist on data in this class:

  > - The compress mode must be one of the values in `VALID_COMPRESS_MODES`.
  > - The ‘all’ flag must be ‘Y’ if no databases are defined.
  > - The ‘all’ flag must be ‘N’ if any databases are defined.
  > - Any values in the databases list must be strings.

  `__init__`(user=None, password=None, compressMode=None, all=None, databases=None)

    Constructor for the `MysqlConfig` class.

    Parameters: | user – User to execute backup as password – Password associated with user compressMode – Compress mode for backed-up files all – Indicates whether to back up all databases databases – List of databases to back up

  `all`

    Indicates whether to back up all databases.

  `compressMode`

    Compress mode to be used for backed-up files.

  `databases`

    List of databases to back up.

  `password`

    Password associated with user.

  `user`

    User to execute backup as.

`CedarBackup3.extend.mysql.` `backupDatabase`(user, password, backupFile, database=None)

  Backs up an individual MySQL database, or all databases.

  This function backs up either a named local MySQL database or all local MySQL databases, using the passed-in user and password (if provided) for connectivity. This function call always results a full backup. There is no facility for incremental backups.

  The backup data will be written into the passed-in backup file. Normally, this would be an object as returned from `open`, but it is possible to use something like a `GzipFile` to write compressed output. The caller is responsible for closing the passed-in backup file.

  Often, the “root” database user will be used when backing up all databases. An alternative is to create a separate MySQL “backup” user and grant that user rights to read (but not write) all of the databases that will be backed up.

  This function accepts a username and password. However, you probably do not want to pass those values in. This is because they will be provided to `mysqldump` via the command-line `--user` and `--password` switches, which will be visible to other users in the process listing.

  Instead, you should configure the username and password in one of MySQL’s configuration files. Typically, this would be done by putting a stanza like this in `/root/.my.cnf`, to provide `mysqldump` with the root database username and its password:

      [mysqldump]
      user     = root
      password = <secret>

  If you are executing this function as some system user other than root, then the `.my.cnf` file would be placed in the home directory of that user. In either case, make sure to set restrictive permissions (typically, mode `0600`) on `.my.cnf` to make sure that other users cannot read the file.

  Parameters: | user (String representing MySQL username, or `None`) – User to use for connecting to the database (if any) password (String representing MySQL password, or `None`) – Password associated with user (if any) backupFile (Python file object as from `open` or `file`) – File use for writing backup database (String representing database name, or `None` for all databases) – Name of the database to be backed up
  Raises: | `ValueError` – If some value is missing or invalid `IOError` – If there is a problem executing the MySQL dump

`CedarBackup3.extend.mysql.` `executeAction`(configPath, options, config)

  Executes the MySQL backup action.

  Parameters: | configPath (String representing a path on disk) – Path to configuration file on disk options (Options object) – Program command-line options config (Config object) – Program configuration
  Raises: | `ValueError` – Under many generic error conditions `IOError` – If a backup could not be written for some reason

## CedarBackup3.extend.postgresql module

Provides an extension to back up PostgreSQL databases.

This is a Cedar Backup extension used to back up PostgreSQL databases via the Cedar Backup command line. It requires a new configurations section <postgresql> and is intended to be run either immediately before or immediately after the standard collect action. Aside from its own configuration, it requires the options and collect configuration sections in the standard Cedar Backup configuration file.

The backup is done via the `pg_dump` or `pg_dumpall` commands included with the PostgreSQL product. Output can be compressed using `gzip` or `bzip2`. Administrators can configure the extension either to back up all databases or to back up only specific databases. The extension assumes that the current user has passwordless access to the database since there is no easy way to pass a password to the `pg_dump` client. This can be accomplished using appropriate voodoo in the `pg_hda.conf` file.

Note that this code always produces a full backup. There is currently no facility for making incremental backups.

You should always make `/etc/cback3.conf` unreadble to non-root users once you place postgresql configuration into it, since postgresql configuration will contain information about available PostgreSQL databases and usernames.

Use of this extension may expose usernames in the process listing (via `ps`) when the backup is running if the username is specified in the configuration.

author: | Kenneth J. Pronovici <pronovic@ieee.org>
author: | Antoine Beaupre <anarcat@koumbit.org>

class `CedarBackup3.extend.postgresql.` `LocalConfig`(xmlData=None, xmlPath=None, validate=True)

  Bases: `object`

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

  `__init__`(xmlData=None, xmlPath=None, validate=True)

    Initializes a configuration object.

    If you initialize the object without passing either `xmlData` or `xmlPath` then configuration will be empty and will be invalid until it is filled in properly.

    No reference to the original XML data or original path is saved off by this class. Once the data has been parsed (successfully or not) this original information is discarded.

    Unless the `validate` argument is `False`, the `LocalConfig.validate` method will be called (with its default arguments) against configuration after successfully parsing any passed-in XML. Keep in mind that even if `validate` is `False`, it might not be possible to parse the passed-in XML document if lower-level validations fail.

    Note: It is strongly suggested that the `validate` option always be set to `True` (the default) unless there is a specific need to read in invalid configuration from disk.

    Parameters: | xmlData (String data) – XML data representing configuration xmlPath (Absolute path to a file on disk) – Path to an XML file on disk validate (Boolean true/false) – Validate the document after parsing it
    Raises: | `ValueError` – If both `xmlData` and `xmlPath` are passed-in `ValueError` – If the XML data in `xmlData` or `xmlPath` cannot be parsed `ValueError` – If the parsed configuration document is not valid

  `addConfig`(xmlDom, parentNode)

    Adds a <postgresql> 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:

        user           //cb_config/postgresql/user
        compressMode   //cb_config/postgresql/compress_mode
        all            //cb_config/postgresql/all

    We also add groups of the following items, one list element per item:

        database       //cb_config/postgresql/database

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

  `postgresql`

    Postgresql configuration in terms of a `PostgresqlConfig` object.

  `validate`()

    Validates configuration represented by the object.

    The compress mode must be filled in. Then, if the ‘all’ flag is set, no databases are allowed, and if the ‘all’ flag is not set, at least one database is required.

    Raises: | `ValueError` – If one of the validations fails

class `CedarBackup3.extend.postgresql.` `PostgresqlConfig`(user=None, compressMode=None, all=None, databases=None)

  Bases: `object`

  Class representing PostgreSQL configuration.

  The PostgreSQL configuration information is used for backing up PostgreSQL databases.

  The following restrictions exist on data in this class:

  > - The compress mode must be one of the values in `VALID_COMPRESS_MODES`.
  > - The ‘all’ flag must be ‘Y’ if no databases are defined.
  > - The ‘all’ flag must be ‘N’ if any databases are defined.
  > - Any values in the databases list must be strings.

  `__init__`(user=None, compressMode=None, all=None, databases=None)

    Constructor for the `PostgresqlConfig` class.

    Parameters: | user – User to execute backup as compressMode – Compress mode for backed-up files all – Indicates whether to back up all databases databases – List of databases to back up

  `all`

    Indicates whether to back up all databases.

  `compressMode`

    Compress mode to be used for backed-up files.

  `databases`

    List of databases to back up.

  `user`

    User to execute backup as.

`CedarBackup3.extend.postgresql.` `backupDatabase`(user, backupFile, database=None)

  Backs up an individual PostgreSQL database, or all databases.

  This function backs up either a named local PostgreSQL database or all local PostgreSQL databases, using the passed in user for connectivity. This is always a full backup. There is no facility for incremental backups.

  The backup data will be written into the passed-in back file. Normally, this would be an object as returned from `open`, but it is possible to use something like a `GzipFile` to write compressed output. The caller is responsible for closing the passed-in backup file.

  Note: Typically, you would use the `root` user to back up all databases.

  Parameters: | user (String representing PostgreSQL username) – User to use for connecting to the database backupFile (Python file object as from `open` or `file`) – File use for writing backup database (String representing database name, or `None` for all databases) – Name of the database to be backed up
  Raises: | `ValueError` – If some value is missing or invalid `IOError` – If there is a problem executing the PostgreSQL dump

`CedarBackup3.extend.postgresql.` `executeAction`(configPath, options, config)

  Executes the PostgreSQL backup action.

  Parameters: | configPath (String representing a path on disk) – Path to configuration file on disk options (Options object) – Program command-line options config (Config object) – Program configuration
  Raises: | `ValueError` – Under many generic error conditions `IOError` – If a backup could not be written for some reason

## CedarBackup3.extend.split module

Provides an extension to split up large files in staging directories.

When this extension is executed, it will look through the configured Cedar Backup staging directory for files exceeding a specified size limit, and split them down into smaller files using the ‘split’ utility. Any directory which has already been split (as indicated by the `cback.split` file) will be ignored.

This extension requires a new configuration section <split> and is intended to be run immediately after the standard stage action or immediately before the standard store action. Aside from its own configuration, it requires the options and staging configuration sections in the standard Cedar Backup configuration file.

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

class `CedarBackup3.extend.split.` `LocalConfig`(xmlData=None, xmlPath=None, validate=True)

  Bases: `object`

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

  `__init__`(xmlData=None, xmlPath=None, validate=True)

    Initializes a configuration object.

    If you initialize the object without passing either `xmlData` or `xmlPath` then configuration will be empty and will be invalid until it is filled in properly.

    No reference to the original XML data or original path is saved off by this class. Once the data has been parsed (successfully or not) this original information is discarded.

    Unless the `validate` argument is `False`, the `LocalConfig.validate` method will be called (with its default arguments) against configuration after successfully parsing any passed-in XML. Keep in mind that even if `validate` is `False`, it might not be possible to parse the passed-in XML document if lower-level validations fail.

    Note: It is strongly suggested that the `validate` option always be set to `True` (the default) unless there is a specific need to read in invalid configuration from disk.

    Parameters: | xmlData (String data) – XML data representing configuration xmlPath (Absolute path to a file on disk) – Path to an XML file on disk validate (Boolean true/false) – Validate the document after parsing it
    Raises: | `ValueError` – If both `xmlData` and `xmlPath` are passed-in `ValueError` – If the XML data in `xmlData` or `xmlPath` cannot be parsed `ValueError` – If the parsed configuration document is not valid

  `addConfig`(xmlDom, parentNode)

    Adds a <split> 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:

        sizeLimit      //cb_config/split/size_limit
        splitSize      //cb_config/split/split_size

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

  `split`

    Split configuration in terms of a `SplitConfig` object.

  `validate`()

    Validates configuration represented by the object.

    Split configuration must be filled in. Within that, both the size limit and split size must be filled in.

    Raises: | `ValueError` – If one of the validations fails

class `CedarBackup3.extend.split.` `SplitConfig`(sizeLimit=None, splitSize=None)

  Bases: `object`

  Class representing split configuration.

  Split configuration is used for splitting staging directories.

  The following restrictions exist on data in this class:

  > - The size limit must be a ByteQuantity
  > - The split size must be a ByteQuantity

  `__init__`(sizeLimit=None, splitSize=None)

    Constructor for the `SplitCOnfig` class.

    Parameters: | sizeLimit – Size limit of the files, in bytes splitSize – Size that files exceeding the limit will be split into, in bytes
    Raises: | `ValueError` – If one of the values is invalid

  `sizeLimit`

    Size limit, as a ByteQuantity

  `splitSize`

    Split size, as a ByteQuantity

`CedarBackup3.extend.split.` `executeAction`(configPath, options, config)

  Executes the split backup action.

  Parameters: | configPath (String representing a path on disk) – Path to configuration file on disk options (Options object) – Program command-line options config (Config object) – Program configuration
  Raises: | `ValueError` – Under many generic error conditions `IOError` – If there are I/O problems reading or writing files

## CedarBackup3.extend.subversion module

Provides an extension to back up Subversion repositories.

This is a Cedar Backup extension used to back up Subversion repositories via the Cedar Backup command line. Each Subversion repository can be backed using the same collect modes allowed for filesystems in the standard Cedar Backup collect action: weekly, daily, incremental.

This extension requires a new configuration section <subversion> and is intended to be run either immediately before or immediately after the standard collect action. Aside from its own configuration, it requires the options and collect configuration sections in the standard Cedar Backup configuration file.

There are two different kinds of Subversion repositories at this writing: BDB (Berkeley Database) and FSFS (a “filesystem within a filesystem”). Although the repository type can be specified in configuration, that information is just kept around for reference. It doesn’t affect the backup. Both kinds of repositories are backed up in the same way, using `svnadmin dump` in an incremental mode.

It turns out that FSFS repositories can also be backed up just like any other filesystem directory. If you would rather do that, then use the normal collect action. This is probably simpler, although it carries its own advantages and disadvantages (plus you will have to be careful to exclude the working directories Subversion uses when building an update to commit). Check the Subversion documentation for more information.

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

class `CedarBackup3.extend.subversion.` `BDBRepository`(repositoryPath=None, collectMode=None, compressMode=None)

  Bases: `CedarBackup3.extend.subversion.Repository`

  Class representing Subversion BDB (Berkeley Database) repository configuration. This object is deprecated. Use a simple `Repository` instead.

  `__init__`(repositoryPath=None, collectMode=None, compressMode=None)

    Constructor for the `BDBRepository` class.

class `CedarBackup3.extend.subversion.` `FSFSRepository`(repositoryPath=None, collectMode=None, compressMode=None)

  Bases: `CedarBackup3.extend.subversion.Repository`

  Class representing Subversion FSFS repository configuration. This object is deprecated. Use a simple `Repository` instead.

  `__init__`(repositoryPath=None, collectMode=None, compressMode=None)

    Constructor for the `FSFSRepository` class.

class `CedarBackup3.extend.subversion.` `LocalConfig`(xmlData=None, xmlPath=None, validate=True)

  Bases: `object`

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

  `__init__`(xmlData=None, xmlPath=None, validate=True)

    Initializes a configuration object.

    If you initialize the object without passing either `xmlData` or `xmlPath` then configuration will be empty and will be invalid until it is filled in properly.

    No reference to the original XML data or original path is saved off by this class. Once the data has been parsed (successfully or not) this original information is discarded.

    Unless the `validate` argument is `False`, the `LocalConfig.validate` method will be called (with its default arguments) against configuration after successfully parsing any passed-in XML. Keep in mind that even if `validate` is `False`, it might not be possible to parse the passed-in XML document if lower-level validations fail.

    Note: It is strongly suggested that the `validate` option always be set to `True` (the default) unless there is a specific need to read in invalid configuration from disk.

    Parameters: | xmlData (String data) – XML data representing configuration xmlPath (Absolute path to a file on disk) – Path to an XML file on disk validate (Boolean true/false) – Validate the document after parsing it
    Raises: | `ValueError` – If both `xmlData` and `xmlPath` are passed-in `ValueError` – If the XML data in `xmlData` or `xmlPath` cannot be parsed `ValueError` – If the parsed configuration document is not valid

  `addConfig`(xmlDom, parentNode)

    Adds a <subversion> 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:

        collectMode    //cb_config/subversion/collectMode
        compressMode   //cb_config/subversion/compressMode

    We also add groups of the following items, one list element per item:

        repository     //cb_config/subversion/repository
        repository_dir //cb_config/subversion/repository_dir

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

  `subversion`

    Subversion configuration in terms of a `SubversionConfig` object.

  `validate`()

    Validates configuration represented by the object.

    Subversion configuration must be filled in. Within that, the collect mode and compress mode are both optional, but the list of repositories must contain at least one entry.

    Each repository must contain a repository path, and then must be either able to take collect mode and compress mode configuration from the parent `SubversionConfig` object, or must set each value on its own.

    Raises: | `ValueError` – If one of the validations fails

class `CedarBackup3.extend.subversion.` `Repository`(repositoryType=None, repositoryPath=None, collectMode=None, compressMode=None)

  Bases: `object`

  Class representing generic Subversion repository configuration..

  The following restrictions exist on data in this class:

  > - The respository path must be absolute.
  > - The collect mode must be one of the values in `VALID_COLLECT_MODES`.
  > - The compress mode must be one of the values in `VALID_COMPRESS_MODES`.

  The repository type value is kept around just for reference. It doesn’t affect the behavior of the backup.

  `__init__`(repositoryType=None, repositoryPath=None, collectMode=None, compressMode=None)

    Constructor for the `Repository` class.

    Parameters: | repositoryType – Type of repository, for reference repositoryPath – Absolute path to a Subversion repository on disk collectMode – Overridden collect mode for this directory compressMode – Overridden compression mode for this directory

  `collectMode`

    Overridden collect mode for this repository.

  `compressMode`

    Overridden compress mode for this repository.

  `repositoryPath`

    Path to the repository to collect.

  `repositoryType`

    Type of this repository, for reference.

class `CedarBackup3.extend.subversion.` `RepositoryDir`(repositoryType=None, directoryPath=None, collectMode=None, compressMode=None, relativeExcludePaths=None, excludePatterns=None)

  Bases: `object`

  Class representing Subversion repository directory.

  A repository directory is a directory that contains one or more Subversion repositories.

  The following restrictions exist on data in this class:

  > - The directory path must be absolute.
  > - The collect mode must be one of the values in `VALID_COLLECT_MODES`.
  > - The compress mode must be one of the values in `VALID_COMPRESS_MODES`.

  The repository type value is kept around just for reference. It doesn’t affect the behavior of the backup.

  Relative exclusions are allowed here. However, there is no configured ignore file, because repository dir backups are not recursive.

  `__init__`(repositoryType=None, directoryPath=None, collectMode=None, compressMode=None, relativeExcludePaths=None, excludePatterns=None)

    Constructor for the `RepositoryDir` class.

    Parameters: | repositoryType – Type of repository, for reference directoryPath – Absolute path of the Subversion parent directory collectMode – Overridden collect mode for this directory compressMode – Overridden compression mode for this directory relativeExcludePaths – List of relative paths to exclude excludePatterns – List of regular expression patterns to exclude

  `collectMode`

    Overridden collect mode for this repository.

  `compressMode`

    Overridden compress mode for this repository.

  `directoryPath`

    Absolute path of the Subversion parent directory.

  `excludePatterns`

    List of regular expression patterns to exclude.

  `relativeExcludePaths`

    List of relative paths to exclude.

  `repositoryType`

    Type of this repository, for reference.

class `CedarBackup3.extend.subversion.` `SubversionConfig`(collectMode=None, compressMode=None, repositories=None, repositoryDirs=None)

  Bases: `object`

  Class representing Subversion configuration.

  Subversion configuration is used for backing up Subversion repositories.

  The following restrictions exist on data in this class:

  > - The collect mode must be one of the values in `VALID_COLLECT_MODES`.
  > - The compress mode must be one of the values in `VALID_COMPRESS_MODES`.
  > - The repositories list must be a list of `Repository` objects.
  > - The repositoryDirs list must be a list of `RepositoryDir` objects.

  For the two lists, validation is accomplished through the `util.ObjectTypeList` list implementation that overrides common list methods and transparently ensures that each element has the correct type.

  Note: Lists within this class are “unordered” for equality comparisons.

  `__init__`(collectMode=None, compressMode=None, repositories=None, repositoryDirs=None)

    Constructor for the `SubversionConfig` class.

    Parameters: | collectMode – Default collect mode compressMode – Default compress mode repositories – List of Subversion repositories to back up repositoryDirs – List of Subversion parent directories to back up
    Raises: | `ValueError` – If one of the values is invalid

  `collectMode`

    Default collect mode.

  `compressMode`

    Default compress mode.

  `repositories`

    List of Subversion repositories to back up.

  `repositoryDirs`

    List of Subversion parent directories to back up.

`CedarBackup3.extend.subversion.` `backupBDBRepository`(repositoryPath, backupFile, startRevision=None, endRevision=None)

  Backs up an individual Subversion BDB repository. This function is deprecated. Use `backupRepository` instead.

`CedarBackup3.extend.subversion.` `backupFSFSRepository`(repositoryPath, backupFile, startRevision=None, endRevision=None)

  Backs up an individual Subversion FSFS repository. This function is deprecated. Use `backupRepository` instead.

`CedarBackup3.extend.subversion.` `backupRepository`(repositoryPath, backupFile, startRevision=None, endRevision=None)

  Backs up an individual Subversion repository.

  The starting and ending revision values control an incremental backup. If the starting revision is not passed in, then revision zero (the start of the repository) is assumed. If the ending revision is not passed in, then the youngest revision in the database will be used as the endpoint.

  The backup data will be written into the passed-in back file. Normally, this would be an object as returned from `open`, but it is possible to use something like a `GzipFile` to write compressed output. The caller is responsible for closing the passed-in backup file.

  Note: This function should either be run as root or as the owner of the Subversion repository.

  Note: It is apparently not a good idea to interrupt this function. Sometimes, this leaves the repository in a “wedged” state, which requires recovery using `svnadmin recover`.

  Parameters: | repositoryPath (String path representing Subversion repository on disk) – Path to Subversion repository to back up backupFile (Python file object as from `open` or `file`) – Python file object to use for writing backup startRevision (Integer value >= 0) – Starting repository revision to back up (for incremental backups) endRevision (Integer value >= 0) – Ending repository revision to back up (for incremental backups)
  Raises: | `ValueError` – If some value is missing or invalid `IOError` – If there is a problem executing the Subversion dump

`CedarBackup3.extend.subversion.` `executeAction`(configPath, options, config)

  Executes the Subversion backup action.

  Parameters: | configPath (String representing a path on disk) – Path to configuration file on disk options (Options object) – Program command-line options config (Config object) – Program configuration
  Raises: | `ValueError` – Under many generic error conditions `IOError` – If a backup could not be written for some reason

`CedarBackup3.extend.subversion.` `getYoungestRevision`(repositoryPath)

  Gets the youngest (newest) revision in a Subversion repository using `svnlook`.

  Note: This function should either be run as root or as the owner of the Subversion repository.

  Parameters: | repositoryPath (String path representing Subversion repository on disk) – Path to Subversion repository to look in
  Returns: | Youngest revision as an integer
  Raises: | `ValueError` – If there is a problem parsing the `svnlook` output `IOError` – If there is a problem executing the `svnlook` command

## CedarBackup3.extend.sysinfo module

Provides an extension to save off important system recovery information.

This is a simple Cedar Backup extension used to save off important system recovery information. It saves off three types of information:

> - Currently-installed Debian packages via `dpkg --get-selections`
> - Disk partition information via `fdisk -l`
> - System-wide mounted filesystem contents, via `ls -laR`

The saved-off information is placed into the collect directory and is compressed using `bzip2` to save space.

This extension relies on the options and collect configurations in the standard Cedar Backup configuration file, but requires no new configuration of its own. No public functions other than the action are exposed since all of this is pretty simple.

Note: If the `dpkg` or `fdisk` commands cannot be found in their normal locations or executed by the current user, those steps will be skipped and a note will be logged at the INFO level.

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

`CedarBackup3.extend.sysinfo.` `executeAction`(configPath, options, config)

  Executes the sysinfo backup action.

  Parameters: | configPath (String representing a path on disk) – Path to configuration file on disk options (Options object) – Program command-line options config (Config object) – Program configuration
  Raises: | `ValueError` – Under many generic error conditions `IOError` – If the backup process fails for some reason