Pegasus Enhancement Proposal (PEP)

PEP #: 271

Title: Repository Archive

Status: Approved

Version History:

Version Date Author Change Description
1.0 10 July 2006 Roger Kumpf Initial Submittal
1.1 20 July 2006 Roger Kumpf Updated based on architecture team review comments.
Approved version.

Abstract: This PEP proposes a mechanism to allow an archive copy of the CIM Server repository to be created without stopping the CIM Server.

Definition of the Problem

The CIM Server's repository contains important information which can be difficult to recreate. At present, it is necessary to shut down the CIM Server to create a repository backup in a predictably consistent state. A mechanism is needed to allow the creation of an archive copy of the repository while the CIM Server is running.

Proposed Solution

The proposed solution involves these components:

AutoFileLock class

A new AutoFileLock class is added to the System module. This class locks and unlocks an advisory file lock in its constructor and destructor, respectively. 

/**
    The AutoFileLock class uses an advisory file lock to allow access to a
    resource to be controlled.
*/
class AutoFileLock
{
public:

    AutoFileLock(const char* fileName);
    ~AutoFileLock();

private:

    AutoFileLock();
    AutoFileLock(const AutoFileLock&);
    AutoFileLock& operator=(const AutoFileLock&);

#ifdef PEGASUS_OS_TYPE_UNIX
    struct flock _fl;
    int _fd;
#endif
};

This class is implemented on Unix platforms using an flock structure and the fcntl() function to control the advisory file lock. Implementations are not proposed for Windows or OpenVMS (though they would be happily accepted).

CIMRepository

The CIMRepository is updated to use the AutoFileLock class whenever performing an operation that may result in a repository update, using the current configuration file is used as the lock file. Since the file locking is done in an advisory manner, this approach does not impact other access to this file.

cimreparchive command

A new command, cimreparchive, is added as an externally supported interface. This command uses the AutoFileLock class on the same file as the CIMRepository, so that repository updates are not performed while an archive operation is in progress. On Unix platforms, the cimreparchive command uses "tar" to create an archive file containing the contents of the repository directory. The behavior on other platforms is not yet defined.

NAME

cimreparchive - create an archive copy of the CIM Server repository.

SYNOPSIS

cimreparchive archive_file

cimreparchive --help

cimreparchive --version

DESCRIPTION

The cimreparchive command creates an archive copy of the CIM Server repository in the specified archive_file. The archive copy is assured to contain a consistent repository state even if it is created while the CIM Server is running.

OPTIONS

cimreparchive recognizes the following options:

--help Displays the command help message.
--version Displays the CIM Server version number.

EXIT STATUS

When an error occurs, an error message is written to the standard error stream and a non-zero exit status value is returned. The following exit status values are defined:

0 Success
1 General error
2 Failed to initiate archive operation
3 Archive operation failed

SEE ALSO

cimserver(8)

Rationale

Creating an archive copy of the repository while the CIM Server is running requires a mechanism to ensure that repository updates are not performed during the archive operation. One approach that was considered is to allow a user to explicitly "suspend" and "resume" repository updates. A solution of this type would allow an administrator the flexibility to use any tool to create the archive. However, allowing indefinite suspension of repository updates is expected to increase the support burden for a CIM Server installation. The cost of the increased complexity of this approach was determined to outweigh the benefits. Keeping the "lock" and "unlock" operations within the same command ensures that the repository will not be accidentally left in a locked state, and it makes the repository locking transparent to an administrator. On my HP-UX test system, cimreparchive takes about two seconds to archive a 44 megabyte copy of the test repository.

It is neither a goal nor is it feasible to perform a repository restore operation while the CIM Server is running. To restore from a repository archive, an administrator would need to shut down the CIM Server, use the appropriate command (e.g., tar) to restore the archive version, and restart the CIM Server.

Constraints and Limitations

Because the CIMRepository in the CIM Server and the cimreparchive command need to agree on the location of the repository, the cimreparchive command does not behave properly when the "repositoryDir" configuration property is not set to the default location. For this reason, the cimreparchive command is recommended for use only in installations where "repositoryDir" is not configurable.

An implementation is proposed only for Unix platforms, though the design is intended to allow straightforward extension to other platforms.

Windows platforms do not appear to have a universally available archiving tool. Extending cimreparchive to work on Windows may require a dependency on the installation/availability of a particular tool (such as WinZip). In addition, a Windows implementation may need to use mandatory file locking, since advisory file locks are not supported on that platform.

Test Plan

A unit test is added to stress the AutoFileLock class.

Test cases are added for the cimreparchive command to validate the creation of an archive file and to test the behavior of the command with invalid options.

Schedule

ActionPlannedActualComment
PEP Submitted7/10/067/10/06
PEP Reviewed7/21/067/18/06version 1.0
PEP Approved8/15/068/1/06version 1.1
Code CommittedPegasus 2.68/15/06Bug 5360

Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.; EMC Corporation; Symantec Corporation; The Open Group.
Permission is hereby granted, free of charge, to any person obtaining a copy  of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

 THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED  "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Template last modified: March 9th 2004 by Martin Kirk
Template version: 1.8