CedarBackup2.actions.store

Package CedarBackup2 :: Package actions :: Module store |
[hide private]
[frames] | no frames]

# Module store

source code

Implements the standard 'store' action.

Authors:
  Kenneth J. Pronovici <pronovic@ieee.org>, Dmitry Rutsky <rutsky@inbox.ru>

Functions | [hide private]
executeStore(configPath, options, config) Executes the store backup action. | source code
writeImage(config, newDisc, stagingDirs) Builds and writes an ISO image containing the indicated stage directories. | source code
writeStoreIndicator(config, stagingDirs) Writes a store indicator file into staging directories. | source code
consistencyCheck(config, stagingDirs) Runs a consistency check against media in the backup device. | source code
writeImageBlankSafe(config, rebuildMedia, todayIsStart, blankBehavior, stagingDirs) Builds and writes an ISO image containing the indicated stage directories. | source code
_getNewDisc(writer, rebuildMedia, todayIsStart, blankBehavior) Gets a value for the newDisc flag based on blanking factor rules. | source code
_findCorrectDailyDir(options, config) Finds the correct daily staging directory to be written to disk. | source code

Variables | [hide private]
| logger = `logging.getLogger("CedarBackup2.log.actions.store")`
| __package__ = ``'``CedarBackup2.actions``'``

Function Details | [hide private]

### executeStore(configPath, options, config) | source code
Executes the store 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 problems reading or writing files. Notes: The rebuild action and the store action are very similar. The main difference is that while store only stores a single day's staging directory, the rebuild action operates on multiple staging directories. When the store action is complete, we will write a store indicator to the daily staging directory we used, so it's obvious that the store action has completed.

### writeImage(config, newDisc, stagingDirs) | source code
Builds and writes an ISO image containing the indicated stage directories. The generated image will contain each of the staging directories listed in `stagingDirs`. The directories will be placed into the image at the root by date, so staging directory `/opt/stage/2005/02/10` will be placed into the disc at `/2005/02/10`. Parameters: `config` - Config object. `newDisc` - Indicates whether the disc should be re-initialized `stagingDirs` - Dictionary mapping directory path to date suffix. Raises: `ValueError` - Under many generic error conditions `IOError` - If there is a problem writing the image to disc. Note: This function is implemented in terms of writeImageBlankSafe. The `newDisc` flag is passed in for both `rebuildMedia` and `todayIsStart`.

### writeStoreIndicator(config, stagingDirs) | source code
Writes a store indicator file into staging directories. The store indicator is written into each of the staging directories when either a store or rebuild action has written the staging directory to disc. Parameters: `config` - Config object. `stagingDirs` - Dictionary mapping directory path to date suffix.

### consistencyCheck(config, stagingDirs) | source code
Runs a consistency check against media in the backup device. It seems that sometimes, it's possible to create a corrupted multisession disc (i.e. one that cannot be read) although no errors were encountered while writing the disc. This consistency check makes sure that the data read from disc matches the data that was used to create the disc. The function mounts the device at a temporary mount point in the working directory, and then compares the indicated staging directories in the staging directory and on the media. The comparison is done via functionality in `filesystem.py`. If no exceptions are thrown, there were no problems with the consistency check. A positive confirmation of "no problems" is also written to the log with `info` priority. Parameters: `config` - Config object. `stagingDirs` - Dictionary mapping directory path to date suffix. Raises: `ValueError` - If the two directories are not equivalent. `IOError` - If there is a problem working with the media. Warning: The implementation of this function is very UNIX-specific.

### writeImageBlankSafe(config, rebuildMedia, todayIsStart, blankBehavior, stagingDirs) | source code
Builds and writes an ISO image containing the indicated stage directories. The generated image will contain each of the staging directories listed in `stagingDirs`. The directories will be placed into the image at the root by date, so staging directory `/opt/stage/2005/02/10` will be placed into the disc at `/2005/02/10`. The media will always be written with a media label specific to Cedar Backup. This function is similar to writeImage, but tries to implement a smarter blanking strategy. First, the media is always blanked if the `rebuildMedia` flag is true. Then, if `rebuildMedia` is false, blanking behavior and `todayIsStart` come into effect:
      If no blanking behavior is specified, and it is the start of the week,
      the disc will be blanked

      If blanking behavior is specified, and either the blank mode is "daily"
      or the blank mode is "weekly" and it is the start of the week, then
      the disc will be blanked if it looks like the weekly backup will not
      fit onto the media.

      Otherwise, the disc will not be blanked
How do we decide whether the weekly backup will fit onto the media? That is what the blanking factor is used for. The following formula is used:
      will backup fit? = (bytes available / (1 + bytes required) <= blankFactor
The blanking factor will vary from setup to setup, and will probably require some experimentation to get it right. Parameters: `config` - Config object. `rebuildMedia` - Indicates whether media should be rebuilt `todayIsStart` - Indicates whether today is the starting day of the week `blankBehavior` - Blank behavior from configuration, or `None` to use default behavior `stagingDirs` - Dictionary mapping directory path to date suffix. Raises: `ValueError` - Under many generic error conditions `IOError` - If there is a problem writing the image to disc.

### _getNewDisc(writer, rebuildMedia, todayIsStart, blankBehavior) | source code
Gets a value for the newDisc flag based on blanking factor rules. The blanking factor rules are described above by writeImageBlankSafe. Parameters: `writer` - Previously configured image writer containing image entries `rebuildMedia` - Indicates whether media should be rebuilt `todayIsStart` - Indicates whether today is the starting day of the week `blankBehavior` - Blank behavior from configuration, or `None` to use default behavior Returns: newDisc flag to be set on writer.

### _findCorrectDailyDir(options, config) | source code
Finds the correct daily staging directory to be written to disk. In Cedar Backup v1.0, we assumed that the correct staging directory matched the current date. However, that has problems. In particular, it breaks down if collect is on one side of midnite and stage is on the other, or if certain processes span midnite. For v2.0, I'm trying to be smarter. I'll first check the current day. If that directory is found, it's good enough. If it's not found, I'll look for a valid directory from the day before or day after which has not yet been staged, according to the stage indicator file. The first one I find, I'll use. If I use a directory other than for the current day and `config.store.warnMidnite` is set, a warning will be put in the log. There is one exception to this rule. If the `options.full` flag is set, then the special "span midnite" logic will be disabled and any existing store indicator will be ignored. I did this because I think that most users who run `cback --full store` twice in a row expect the command to generate two identical discs. With the other rule in place, running that command twice in a row could result in an error ("no unstored directory exists") or could even cause a completely unexpected directory to be written to disc (if some previous day's contents had not yet been written). Parameters: `options` - Options object. `config` - Config object. Returns: Correct staging dir, as a dict mapping directory to date suffix. Raises: `IOError` - If the staging directory cannot be found. Note: This code is probably longer and more verbose than it needs to be, but at least it's straightforward.