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)

Bases: object

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

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)

Bases: object

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

collectDir

workingDir

remoteUser

localUser

rcpCommand

rshCommand

cbackCommand

ignoreFailureMode

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