CedarBackup3.peer — cedar-backup3 3.10.0 documentation

# CedarBackup3.peer

Provides backup peer-related objects and utility functions.

## Module Attributes

CedarBackup3.peer.DEF_COLLECT_INDICATOR

  Name of the default collect indicator file

CedarBackup3.peer.DEF_STAGE_INDICATOR

  Name of the default stage indicator file

author:

  Kenneth J. Pronovici <pronovic@ieee.org>

## Module Contents

CedarBackup3.peer.logger

CedarBackup3.peer.DEF_RCP_COMMAND = ['/usr/bin/scp', '-B', '-q', '-C']

CedarBackup3.peer.DEF_RSH_COMMAND = ['/usr/bin/ssh']

CedarBackup3.peer.DEF_CBACK_COMMAND = '/usr/bin/cback3'

CedarBackup3.peer.DEF_COLLECT_INDICATOR = 'cback.collect'

CedarBackup3.peer.DEF_STAGE_INDICATOR = 'cback.stage'

CedarBackup3.peer.SU_COMMAND = ['su']

class CedarBackup3.peer.LocalPeer(name, collectDir, ignoreFailureMode=None)

  Backup peer representing a local peer in a backup pool.

  This is a class representing a local (non-network) peer in a backup pool. Local peers are backed up by simple filesystem copy operations. A local peer has associated with it a name (typically, but not necessarily, a hostname) and a collect directory.

  The public methods other than the constructor are part of a “backup peer” interface shared with the `RemotePeer` class.

  name
  collectDir
  ignoreFailureMode = None
  stagePeer(targetDir, ownership=None, permissions=None)

    Stages data from the peer into the indicated local target directory.

    The collect and target directories must both already exist before this method is called. If passed in, ownership and permissions will be applied to the files that are copied.

    Note: The caller is responsible for checking that the indicator exists, if they care. This function only stages the files within the directory.

    Note: If you have user/group as strings, call the `util.getUidGid` function to get the associated uid/gid as an ownership tuple.

    Parameters:

      - targetDir – Target directory to write data into

      - ownership – Owner and group that files should have, tuple of numeric `(uid, gid)`

      - permissions – Unix permissions mode that the staged files should have, in octal like `0640`

    Returns:

      Number of files copied from the source directory to the target directory

    Raises:

      - ValueError – If collect directory is not a directory or does not exist

      - ValueError – If target directory is not a directory, does not exist or is not absolute

      - ValueError – If a path cannot be encoded properly

      - IOError – If there were no files to stage (i.e. the directory was empty)

      - IOError – If there is an IO error copying a file

      - OSError – If there is an OS error copying or changing permissions on a file

  checkCollectIndicator(collectIndicator=None)

    Checks the collect indicator in the peer’s staging directory.

    When a peer has completed collecting its backup files, it will write an empty indicator file into its collect directory. This method checks to see whether that indicator has been written. We’re “stupid” here - if the collect directory doesn’t exist, you’ll naturally get back `False`.

    If you need to, you can override the name of the collect indicator file by passing in a different name.

    Parameters:

      collectIndicator – Name of the collect indicator file to check

    Returns:

      Boolean true/false depending on whether the indicator exists

    Raises:

      ValueError – If a path cannot be encoded properly

  writeStageIndicator(stageIndicator=None, ownership=None, permissions=None)

    Writes the stage indicator in the peer’s staging directory.

    When the master has completed collecting its backup files, it will write an empty indicator file into the peer’s collect directory. The presence of this file implies that the staging process is complete.

    If you need to, you can override the name of the stage indicator file by passing in a different name.

    Note: If you have user/group as strings, call the `util.getUidGid` function to get the associated uid/gid as an ownership tuple.

    Parameters:

      - stageIndicator – Name of the indicator file to write

      - ownership – Owner and group that files should have, tuple of numeric `(uid, gid)`

      - permissions – Unix permissions mode that the staged files should have, in octal like `0640`

    Raises:

      - ValueError – If collect directory is not a directory or does not exist

      - ValueError – If a path cannot be encoded properly

      - IOError – If there is an IO error creating the file

      - OSError – If there is an OS error creating or changing permissions on the file

class CedarBackup3.peer.RemotePeer(name=None, collectDir=None, workingDir=None, remoteUser=None, rcpCommand=None, localUser=None, rshCommand=None, cbackCommand=None, ignoreFailureMode=None)

  Backup peer representing a remote peer in a backup pool.

  This is a class representing a remote (networked) peer in a backup pool. Remote peers are backed up using an rcp-compatible copy command. A remote peer has associated with it a name (which must be a valid hostname), a collect directory, a working directory and a copy method (an rcp-compatible command).

  You can also set an optional local user value. This username will be used as the local user for any remote copies that are required. It can only be used if the root user is executing the backup. The root user will `su` to the local user and execute the remote copies as that user.

  The copy method is associated with the peer and not with the actual request to copy, because we can envision that each remote host might have a different connect method.

  The public methods other than the constructor are part of a “backup peer” interface shared with the `LocalPeer` class.

  name = None
  collectDir = None
  workingDir = None
  remoteUser = None
  localUser = None
  rcpCommand = None
  rshCommand = None
  cbackCommand = None
  ignoreFailureMode = None
  stagePeer(targetDir, ownership=None, permissions=None)

    Stages data from the peer into the indicated local target directory.

    The target directory must already exist before this method is called. If passed in, ownership and permissions will be applied to the files that are copied.

    Note: The returned count of copied files might be inaccurate if some of the copied files already existed in the staging directory prior to the copy taking place. We don’t clear the staging directory first, because some extension might also be using it.

    Note: If you have user/group as strings, call the `util.getUidGid` function to get the associated uid/gid as an ownership tuple.

    Note: Unlike the local peer version of this method, an I/O error might or might not be raised if the directory is empty. Since we’re using a remote copy method, we just don’t have the fine-grained control over our exceptions that’s available when we can look directly at the filesystem, and we can’t control whether the remote copy method thinks an empty directory is an error.

    Parameters:

      - targetDir – Target directory to write data into

      - ownership – Owner and group that files should have, tuple of numeric `(uid, gid)`

      - permissions – Unix permissions mode that the staged files should have, in octal like `0640`

    Returns:

      Number of files copied from the source directory to the target directory

    Raises:

      - ValueError – If target directory is not a directory, does not exist or is not absolute

      - ValueError – If a path cannot be encoded properly

      - IOError – If there were no files to stage (i.e. the directory was empty)

      - IOError – If there is an IO error copying a file

      - OSError – If there is an OS error copying or changing permissions on a file

  checkCollectIndicator(collectIndicator=None)

    Checks the collect indicator in the peer’s staging directory.

    When a peer has completed collecting its backup files, it will write an empty indicator file into its collect directory. This method checks to see whether that indicator has been written. If the remote copy command fails, we return `False` as if the file weren’t there.

    If you need to, you can override the name of the collect indicator file by passing in a different name.

    Note: Apparently, we can’t count on all rcp-compatible implementations to return sensible errors for some error conditions. As an example, the `scp` command in Debian ‘woody’ returns a zero (normal) status even when it can’t find a host or if the login or path is invalid. Because of this, the implementation of this method is rather convoluted.

    Parameters:

      collectIndicator – Name of the collect indicator file to check

    Returns:

      Boolean true/false depending on whether the indicator exists

    Raises:

      ValueError – If a path cannot be encoded properly

  writeStageIndicator(stageIndicator=None)

    Writes the stage indicator in the peer’s staging directory.

    When the master has completed collecting its backup files, it will write an empty indicator file into the peer’s collect directory. The presence of this file implies that the staging process is complete.

    If you need to, you can override the name of the stage indicator file by passing in a different name.

    Note: If you have user/group as strings, call the `util.getUidGid` function to get the associated uid/gid as an ownership tuple.

    Parameters:

      stageIndicator – Name of the indicator file to write

    Raises:

      - ValueError – If a path cannot be encoded properly

      - IOError – If there is an IO error creating the file

      - OSError – If there is an OS error creating or changing permissions on the file

  executeRemoteCommand(command)

    Executes a command on the peer via remote shell.

    Parameters:

      command – Command to execute

    Raises:

      IOError – If there is an error executing the command on the remote peer

  executeManagedAction(action, fullBackup)

    Executes a managed action on this peer.

    Parameters:

      - action – Name of the action to execute

      - fullBackup – Whether a full backup should be executed

    Raises:

      IOError – If there is an error executing the action on the remote peer