Package CedarBackup2 :: Module cli
[hide private]
[frames] | no frames]

Module cli

source code

Provides command-line interface implementation for the cback script.

Summary

The functionality in this module encapsulates the command-line interface for the cback script. The cback 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.


Author: Kenneth J. Pronovici <pronovic@ieee.org>

Classes [hide private]
  Options
Class representing command-line options for the cback script.
  _ActionItem
Class representing a single action to be executed.
  _ManagedActionItem
Class representing a single action to be executed on a managed peer.
  _ActionSet
Class representing a set of local actions to be executed.
Functions [hide private]
 
cli()
Implements the command-line interface for the cback script.
source code
 
_usage(fd=sys.stdout)
Prints usage information for the cback script.
source code
 
_version(fd=sys.stdout)
Prints version information for the cback script.
source code
 
_diagnostics(fd=sys.stdout)
Prints runtime diagnostics information.
source code
 
setupLogging(options)
Set up logging based on command-line options.
source code
 
_setupLogfile(options)
Sets up and creates logfile as needed.
source code
 
_setupFlowLogging(logfile, options)
Sets up flow logging.
source code
 
_setupOutputLogging(logfile, options)
Sets up command output logging.
source code
 
_setupDiskFlowLogging(flowLogger, logfile, options)
Sets up on-disk flow logging.
source code
 
_setupScreenFlowLogging(flowLogger, options)
Sets up on-screen flow logging.
source code
 
_setupDiskOutputLogging(outputLogger, logfile, options)
Sets up on-disk command output logging.
source code
 
setupPathResolver(config)
Set up the path resolver singleton based on configuration.
source code
Variables [hide private]
  DEFAULT_CONFIG = '/etc/cback.conf'
The default configuration file.
  DEFAULT_LOGFILE = '/var/log/cback.log'
The default log file path.
  DEFAULT_OWNERSHIP = ['root', 'adm']
Default ownership for the logfile.
  DEFAULT_MODE = 416
Default file permissions mode on the logfile.
  VALID_ACTIONS = ['collect', 'stage', 'store', 'purge', 'rebuil...
List of valid actions.
  COMBINE_ACTIONS = ['collect', 'stage', 'store', 'purge']
List of actions which can be combined with other actions.
  NONCOMBINE_ACTIONS = ['rebuild', 'validate', 'initialize', 'all']
List of actions which cannot be combined with other actions.
  logger = logging.getLogger("CedarBackup2.log.cli")
  DISK_LOG_FORMAT = '%(asctime)s --> [%(levelname)-7s] %(message)s'
  DISK_OUTPUT_FORMAT = '%(message)s'
  SCREEN_LOG_FORMAT = '%(message)s'
  SCREEN_LOG_STREAM = sys.stdout
  DATE_FORMAT = '%Y-%m-%dT%H:%M:%S %Z'
  REBUILD_INDEX = 0
  VALIDATE_INDEX = 0
  INITIALIZE_INDEX = 0
  COLLECT_INDEX = 100
  STAGE_INDEX = 200
  STORE_INDEX = 300
  PURGE_INDEX = 400
  SHORT_SWITCHES = 'hVbqc:fMNl:o:m:OdsD'
  LONG_SWITCHES = ['help', 'version', 'verbose', 'quiet', 'confi...
  __package__ = 'CedarBackup2'
Function Details [hide private]

cli()

source code 

Implements the command-line interface for the cback script.

Essentially, this is the "main routine" for the cback 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 < 2.7
  • 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
Returns:
Error code as described above.
Notes:
  • 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.)
  • 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.

_usage(fd=sys.stdout)

source code 

Prints usage information for the cback script.

Parameters:
  • fd - File descriptor used to print information.

Note: The fd is used rather than print to facilitate unit testing.

_version(fd=sys.stdout)

source code 

Prints version information for the cback script.

Parameters:
  • fd - File descriptor used to print information.

Note: The fd is used rather than print to facilitate unit testing.

_diagnostics(fd=sys.stdout)

source code 

Prints runtime diagnostics information.

Parameters:
  • fd - File descriptor used to print information.

Note: The fd is used rather than print to facilitate unit testing.

setupLogging(options)

source code 

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 (CedarBackup2.log and CedarBackup2.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.

_setupLogfile(options)

source code 

Sets up and creates logfile as needed.

If the logfile already exists on disk, it will be left as-is, under the assumption that it was created with appropriate ownership and permissions. If the logfile does not exist on disk, it will be created as an empty file. Ownership and permissions will remain at their defaults unless user/group and/or mode are set in the options. We ignore errors setting the indicated user and group.

Parameters:
  • options - Command-line options.
Returns:
Path to logfile on disk.

Note: This function is vulnerable to a race condition. If the log file does not exist when the function is run, it will attempt to create the file as safely as possible (using O_CREAT). If two processes attempt to create the file at the same time, then one of them will fail. In practice, this shouldn't really be a problem, but it might happen occassionally if two instances of cback run concurrently or if cback collides with logrotate or something.

_setupFlowLogging(logfile, options)

source code 

Sets up flow logging.

Parameters:
  • logfile - Path to logfile on disk.
  • options - Command-line options.

_setupOutputLogging(logfile, options)

source code 

Sets up command output logging.

Parameters:
  • logfile - Path to logfile on disk.
  • options - Command-line options.

_setupDiskFlowLogging(flowLogger, logfile, options)

source code 

Sets up on-disk flow logging.

Parameters:
  • flowLogger - Python flow logger object.
  • logfile - Path to logfile on disk.
  • options - Command-line options.

_setupScreenFlowLogging(flowLogger, options)

source code 

Sets up on-screen flow logging.

Parameters:
  • flowLogger - Python flow logger object.
  • options - Command-line options.

_setupDiskOutputLogging(outputLogger, logfile, options)

source code 

Sets up on-disk command output logging.

Parameters:
  • outputLogger - Python command output logger object.
  • logfile - Path to logfile on disk.
  • options - Command-line options.

setupPathResolver(config)

source code 

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

Variables Details [hide private]

VALID_ACTIONS

List of valid actions.
Value:
['collect',
 'stage',
 'store',
 'purge',
 'rebuild',
 'validate',
 'initialize',
 'all']

LONG_SWITCHES

Value:
['help',
 'version',
 'verbose',
 'quiet',
 'config=',
 'full',
 'managed',
 'managed-only',
...