CedarBackup3.cli

Provides command-line interface implementation for the cback3 script.

Summary

The functionality in this module encapsulates the command-line interface for the cback3 script. The cback3 script itself is very short, basically just an invokation of one function implemented here. That, in turn, makes it simpler to validate the command line interface (for instance, it’s easier to run pychecker against a module, and unit tests are easier, too).

The objects and functions implemented in this module are probably not useful to any code external to Cedar Backup. Anyone else implementing their own command-line interface would have to reimplement (or at least enhance) all of this anyway.

Backwards Compatibility

The command line interface has changed between Cedar Backup 1.x and Cedar Backup 2.x. Some new switches have been added, and the actions have become simple arguments rather than switches (which is a much more standard command line format). Old 1.x command lines are generally no longer valid.

Module Attributes

CedarBackup3.cli.DEFAULT_CONFIG

The default configuration file

CedarBackup3.cli.DEFAULT_LOGFILE

The default log file path

CedarBackup3.cli.DEFAULT_OWNERSHIP

Default ownership for the logfile

CedarBackup3.cli.DEFAULT_MODE

Default file permissions mode on the logfile

CedarBackup3.cli.VALID_ACTIONS

List of valid actions

CedarBackup3.cli.COMBINE_ACTIONS

List of actions which can be combined with other actions

CedarBackup3.cli.NONCOMBINE_ACTIONS

List of actions which cannot be combined with other actions

author

Kenneth J. Pronovici <pronovic@ieee.org>

Module Contents

CedarBackup3.cli.logger

CedarBackup3.cli.DISK_LOG_FORMAT = %(asctime)s --> [%(levelname)-7s] %(message)s

CedarBackup3.cli.DISK_OUTPUT_FORMAT = %(message)s

CedarBackup3.cli.SCREEN_LOG_FORMAT = %(message)s

CedarBackup3.cli.SCREEN_LOG_STREAM

CedarBackup3.cli.DATE_FORMAT = %Y-%m-%dT%H:%M:%S %Z

CedarBackup3.cli.DEFAULT_CONFIG = /etc/cback3.conf

CedarBackup3.cli.DEFAULT_LOGFILE = /var/log/cback3.log

CedarBackup3.cli.DEFAULT_OWNERSHIP = ['root', 'adm']

CedarBackup3.cli.DEFAULT_MODE = 416

CedarBackup3.cli.REBUILD_INDEX = 0

CedarBackup3.cli.VALIDATE_INDEX = 0

CedarBackup3.cli.INITIALIZE_INDEX = 0

CedarBackup3.cli.COLLECT_INDEX = 100

CedarBackup3.cli.STAGE_INDEX = 200

CedarBackup3.cli.STORE_INDEX = 300

CedarBackup3.cli.PURGE_INDEX = 400

CedarBackup3.cli.VALID_ACTIONS = ['collect', 'stage', 'store', 'purge', 'rebuild', 'validate', 'initialize', 'all']

CedarBackup3.cli.COMBINE_ACTIONS = ['collect', 'stage', 'store', 'purge']

CedarBackup3.cli.NONCOMBINE_ACTIONS = ['rebuild', 'validate', 'initialize', 'all']

CedarBackup3.cli.SHORT_SWITCHES = hVbqc:fMNl:o:m:OdsD

CedarBackup3.cli.LONG_SWITCHES = ['help', 'version', 'verbose', 'quiet', 'config=', 'full', 'managed', 'managed-only',...

CedarBackup3.cli.cli()

Implements the command-line interface for the cback3 script.

Essentially, this is the “main routine” for the cback3 script. It does all of the argument processing for the script, and then sets about executing the indicated actions.

As a general rule, only the actions indicated on the command line will be executed. We will accept any of the built-in actions and any of the configured extended actions (which makes action list verification a two- step process).

The 'all' action has a special meaning: it means that the built-in set of actions (collect, stage, store, purge) will all be executed, in that order. Extended actions will be ignored as part of the 'all' action.

Raised exceptions always result in an immediate return. Otherwise, we generally return when all specified actions have been completed. Actions are ignored if the help, version or validate flags are set.

A different error code is returned for each type of failure:

• 1: The Python interpreter version is not supported

• 2: Error processing command-line arguments

• 3: Error configuring logging

• 4: Error parsing indicated configuration file

• 5: Backup was interrupted with a CTRL-C or similar

• 6: Error executing specified backup actions

Note: This function contains a good amount of logging at the INFO level, because this is the right place to document high-level flow of control (i.e. what the command-line options were, what config file was being used, etc.)

Note: We assume that anything that must be seen on the screen is logged at the ERROR level. Errors that occur before logging can be configured are written to sys.stderr.

Returns

Error code as described above

CedarBackup3.cli.setupLogging(options)

Set up logging based on command-line options.

There are two kinds of logging: flow logging and output logging. Output logging contains information about system commands executed by Cedar Backup, for instance the calls to mkisofs or mount, etc. Flow logging contains error and informational messages used to understand program flow. Flow log messages and output log messages are written to two different loggers target (CedarBackup3.log and CedarBackup3.output). Flow log messages are written at the ERROR, INFO and DEBUG log levels, while output log messages are generally only written at the INFO log level.

By default, output logging is disabled. When the options.output or options.debug flags are set, output logging will be written to the configured logfile. Output logging is never written to the screen.

By default, flow logging is enabled at the ERROR level to the screen and at the INFO level to the configured logfile. If the options.quiet flag is set, flow logging is enabled at the INFO level to the configured logfile only (i.e. no output will be sent to the screen). If the options.verbose flag is set, flow logging is enabled at the INFO level to both the screen and the configured logfile. If the options.debug flag is set, flow logging is enabled at the DEBUG level to both the screen and the configured logfile.

Parameters

options (Options object) – Command-line options

Returns

Path to logfile on disk

CedarBackup3.cli.setupPathResolver(config)

Set up the path resolver singleton based on configuration.

Cedar Backup’s path resolver is implemented in terms of a singleton, the PathResolverSingleton class. This function takes options configuration, converts it into the dictionary form needed by the singleton, and then initializes the singleton. After that, any function that needs to resolve the path of a command can use the singleton.

Parameters

config (Config object) – Configuration

class CedarBackup3.cli.Options(argumentList=None, argumentString=None, validate=True)

Bases: object

Class representing command-line options for the cback3 script.

The Options class is a Python object representation of the command-line options of the cback3 script.

The object representation is two-way: a command line string or a list of command line arguments can be used to create an Options object, and then changes to the object can be propogated back to a list of command-line arguments or to a command-line string. An Options object can even be created from scratch programmatically (if you have a need for that).

There are two main levels of validation in the Options class. The first is field-level validation. Field-level validation comes into play when a given field in an object is assigned to or updated. We use Python’s property functionality to enforce specific validations on field values, and in some places we even use customized list classes to enforce validations on list members. You should expect to catch a ValueError exception when making assignments to fields if you are programmatically filling an object.

The second level of validation is post-completion validation. Certain validations don’t make sense until an object representation of options is fully “complete”. We don’t want these validations to apply all of the time, because it would make building up a valid object from scratch a real pain. For instance, we might have to do things in the right order to keep from throwing exceptions, etc.

All of these post-completion validations are encapsulated in the Options.validate method. This method can be called at any time by a client, and will always be called immediately after creating a Options object from a command line and before exporting a Options object back to a command line. This way, we get acceptable ease-of-use but we also don’t accept or emit invalid command lines.

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

help

version

verbose

quiet

config

full

managed

managedOnly

logfile

owner

mode

output

debug

stacktrace

diagnostics

actions

__repr__()

Official string representation for class instance.

__str__()

Informal string representation for class instance.

__eq__(other)

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

__lt__(other)

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

__gt__(other)

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

__cmp__(other)

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

Returns

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

validate()

Validates command-line options represented by the object.

Unless --help or --version are supplied, at least one action must be specified. Other validations (as for allowed values for particular options) will be taken care of at assignment time by the properties functionality.

Note: The command line format is specified by the _usage function. Call _usage to see a usage statement for the cback3 script.

Raises

ValueError – If one of the validations fails

buildArgumentList(validate=True)

Extracts options into a list of command line arguments.

The original order of the various arguments (if, indeed, the object was initialized with a command-line) is not preserved in this generated argument list. Besides that, the argument list is normalized to use the long option names (i.e. –version rather than -V). The resulting list will be suitable for passing back to the constructor in the argumentList parameter. Unlike buildArgumentString, string arguments are not quoted here, because there is no need for it.

Unless the validate parameter is False, the Options.validate method will be called (with its default arguments) against the options before extracting the command line. If the options are not valid, then an argument list will not be extracted.

Note: It is strongly suggested that the validate option always be set to True (the default) unless there is a specific need to extract an invalid command line.

Parameters

validate (Boolean true/false) – Validate the options before extracting the command line

Returns

List representation of command-line arguments

Raises

ValueError – If options within the object are invalid

buildArgumentString(validate=True)

Extracts options into a string of command-line arguments.

The original order of the various arguments (if, indeed, the object was initialized with a command-line) is not preserved in this generated argument string. Besides that, the argument string is normalized to use the long option names (i.e. –version rather than -V) and to quote all string arguments with double quotes ("). The resulting string will be suitable for passing back to the constructor in the argumentString parameter.

Unless the validate parameter is False, the Options.validate method will be called (with its default arguments) against the options before extracting the command line. If the options are not valid, then an argument string will not be extracted.

Note: It is strongly suggested that the validate option always be set to True (the default) unless there is a specific need to extract an invalid command line.

Parameters

validate (Boolean true/false) – Validate the options before extracting the command line

Returns

String representation of command-line arguments

Raises

ValueError – If options within the object are invalid

CedarBackup3.cli.result