Product InfoCustomer TestimonialsConcept and Reference DocumentsLicensing Terms and PricingCompany Location, Mission and VisionAnnouncements & NewslettersHome

SnapshotCM Administration Guide

The SnapshotCM product consists of server and client components. The server manages the configuration data while the client provides user access from local or remote systems. This document describes the administration tasks required to setup and maintain SnapshotCM in your environment.

Table of Contents:

Installing and Configuring SnapshotCM

Where to Install

The client-server architecture of SnapshotCM provides a lot of flexibility, but the simplest and recommended configuration involves a single SnapshotCM server with multiple SnapshotCM client installations. Since the SnapshotCM server manages all version and configuration data, choose a quick, reliable machine with lots of disk and memory. SnapshotCM does not require lots of resources for good performance, so this system need not be top-of-the-line. Good performance will result with a lightly loaded next-to-latest generation server system. Such a setup will give good performance to 200+ typical users.

Since a number of the SnapshotCM features are best accessed via the Windows GUI, the SnapshotCM administrator and at least one person from each project team or sub-team should have access to a Windows system for these operations.

SnapshotCM Install Road Map

WINDOWS
 
Install SnapshotCM Product
  1. Run the self-extracting install program.
    Choose install type: Client-only, Repository Server, or Proxy Server.
 
Configure a Repository Server
  1. Create a SnapshotCM database.
  2. Start the SnapshotCM server.
  3. Create SnapshotCM accounts.
  4. Create a SnapshotCM project.
  5. Create a SnapshotCM workspace.
  6. Continue using SnapshotCM.
 
Configuring a SnapshotCM Proxy Server
 
Reinstall SnapshotCM
  1. Run the self-extracting install program.
UNIX
 
Install SnapshotCM Product
  1. Unpack the install package.
  2. Configure user's PATH and MANPATH environment variables.
  3. Add truecm service entries.
 
Configure a Repository or Proxy Server
  1. Create a truecm user.
  2. Create a SnapshotCM Repository Database or
    Create a SnapshotCM Proxy Cache
  3. Start the SnapshotCM server.
  4. Create SnapshotCM accounts.
  5. Create a project.
  6. Create a workspace.
  7. Continue using SnapshotCM.
 
Reinstall SnapshotCM
  1. Stop the SnapshotCM Server (if server system) and stop all client programs.
  2. Unpack the install package.
  3. Restart the SnapshotCM Server (if server system).

Return to top of document.

Installing and Configuring on Unix

Unpack the Install Package

The Unix install package is a gzip'd tar file (.tar.gz extension) that should be unpacked from / as the root user. The following commands will unpack the client and server components of SnapshotCM into the /opt/SnapshotCM directory:

Run as root:

	# cd /
	# gunzip < /tmp/SnapshotCM.XXX.tar.gz | tar xvf - 2>&1 | more

Verify that there were no errors during the install.

Configure Environment

Add install directory to PATH.

Each user should add the install location to their PATH environment variable:

PATH="$PATH:/opt/SnapshotCM/bin"

Configure the man page directory.

On Linux, if PATH contains /opt/SnapshotCM/bin, then nothing further need be done. Otherwise, add the following line to the /etc/man.config file to configure the SnapshotCM manual pages into the system default path:

MANPATH /opt/SnapshotCM/man

On HP-UX, append the following string to the /etc/MANPATH file to configure the SnapshotCM manual pages into the system default path. (NOTE: append to existing line in file):

:/opt/SnapshotCM/man

On other systems, depending on the system and the user's configuration, it may or may not be useful to add the following to each user's login profile script.

MANPATH="$MANPATH:/opt/SnapshotCM/man"

Add truecm Service Entries. [Optional]

SnapshotCM clients and server communicate using TCP/IP on a well known port. SnapshotCM clients will check for the truecm services entry to determine which port to use, or silently default to port 8804 if truecm is not registered. The SnapshotCM server, at start-up, will do likewise, but will log a message about using the built-in default if the truecm service is not registered.

Optional Action: Add the following entries to your services file (/etc/services) and/or site services database:

	truecm            8804/tcp                # SnapshotCM
	truecm            8804/udp                # SnapshotCM

At this point, your SnapshotCM Unix client install is complete. For server configuration tasks, continue with the following steps.

Return to top of document.


SnapshotCM Repository and Proxy Server Configuration on Unix

Create a truecm User

The SnapshotCM servers perform all operations as the unix user truecm in order to provide a mechanism to control direct access to all managed files (which are all owned by this user). There are no special requirements for this user other than the user have a unique id. Optionally, a truecm group also can be created.

Sample /etc/passwd entry:

    truecm:*:7000:7000:SnapshotCM Server:/:/bin/true

Sample /etc/group entry:

    truecm:*:7000:truecm

After initialization, all SnapshotCM administration can be performed either as the root or truecm user. Therefore a truecm login account can be enabled to facilitate on-going truecm specific administration. Note that the above example disables login.

Create a SnapshotCM Repository Database (Creating a Proxy database is the next section)

The SnapshotCM Repository Server maintains all configuration management data in the SnapshotCM archive and database directories.

The SnapshotCM archive directory contains a hierarchy of versioned file contents for all files managed by the SnapshotCM server. The amount of space required will depend on the data being stored.

The SnapshotCM database directory stores all other data. The amount of space required will depend on the size of the projects being stored, but is typically much, much less than the archive directory.

To initialize the SnapshotCM database, create an empty directory to hold the database and archive files, and then run the following commands (see cmconfig for additional information):

Run as root on unix systems:

   # cd  database_directory
   # cmconfig  -i  -l

These items can be configured separately if desired or if merely updating the configuration information.

Example commands to run as root:

   mkdir  -p  /var/SnapshotCM
   cd  /var/SnapshotCM
   chown truecm .
   cmconfig  -i  -l
   chown truecm .  *  /etc/opt/SnapshotCM  /etc/opt/SnapshotCM/config
   chmod 700    .     /etc/opt/SnapshotCM

Verify database configuration.

To display the configuration, run the following:

   # cd  database_directory
   # cmconfig  -l

Use the cmconfig command to update any values necessary.

Create a SnapshotCM Proxy Database

The SnapshotCM Proxy Server transparently caches information from a specific SnapshotCM Repository in a proxy cache directory.

You configure the directory to use, the amount of space available to be used, and the server for which to proxy.

To initialize the SnapshotCM Proxy cache, create an empty directory to hold the cache files, and then run the following commands (see cmconfig for additional information):

Run as root on unix systems:

   # cd  cache_directory
   # cmconfig  -ip  -M100  -h <repository_host_name>  -d .  -l

These items can be configured separately if desired or if merely updating the configuration information.

Example commands to run as root:

   mkdir  -p  /var/SnapshotCM
   cd  /var/SnapshotCM
   chown truecm .
   cmconfig  -ip -M500 -C100 -h repo.domain.com  -d .  -l
   chown truecm .  *  /etc/opt/SnapshotCM  /etc/opt/SnapshotCM/config
   chmod 700    .     /etc/opt/SnapshotCM

Verify database configuration.

To display the configuration, run the following:

   # cd  database_directory
   # cmconfig  -l

Use the cmconfig command to update any values necessary.

Start the SnapshotCM Server

Add one of the following lines to the /etc/inittab file to start the SnapshotCM Repository or Proxy Server automatically at boot time (using your local timezone):

trcm:3:once:/opt/SnapshotCM/bin/trueserver TZ=MST7MDT
trcm:3:once:/opt/SnapshotCM/bin/trueproxy TZ=MST7MDT

Alternatively, trueserver or trueproxy can be configured to start from an rc script (not provided).

To manually start the SnapshotCM server, run one of the following:

/opt/SnapshotCM/bin/trueserver start
/opt/SnapshotCM/bin/trueproxy start

To manually stop the SnapshotCM server, run one of the following:

/opt/SnapshotCM/bin/trueserver stop
/opt/SnapshotCM/bin/trueproxy stop

When requested to stop, a running server stops accepting new client connections and waits a few seconds for connected client activity to finish before exiting.

Create SnapshotCM Accounts [command-line]

Initially, the repository database has only the administrator user defined. In this step, you create additional accounts using the administrator account, and then restrict general access to the administrator account. If configuring a proxy server to access a repository database, these things are already set up.

Use the cmaccount command to list, create and manipulate user and group SnapshotCM accounts from the command-line. Follow this link for directions on doing this and later steps from the Windows GUI.

Run the following to list the initial SnapshotCM accounts. Initially, there should be an administrator user account and both administration and everyone group accounts.

   $ SNAPSHOTCM_ACCOUNT=administrator  cmaccount -hhost -u
   $ SNAPSHOTCM_ACCOUNT=administrator  cmaccount -hhost -g

The following adds a new user account:

   $ SNAPSHOTCM_ACCOUNT=administrator  cmaccount -hhost -u -c -nNEWUSER -t'*@*'

If you use the above command to create a SnapshotCM account matching your local workstation login, you should now be able to run the following command:

   $ cmaccount -hhost -u

The following removes unrestricted access to the administrator account, and sets a password on the administrator account:

   $ SNAPSHOTCM_ACCOUNT=administrator  cmaccount -hhost -u -m -t@ -w administrator

Note: The -hhost option can be omitted from the cmaccount command if the server is running on your local system.

Assign Access

Once the database is created, the server started and users added, you need to give users appropriate access to the data. To view, set or modify user privileges, use the cmacl command.

Run this command to grant all access to user via the Administration ACL:

   SNAPSHOTCM_ACCOUNT=administrator  cmacl  -hhost  -A  -e u:user+VMPCDRW

Note: This example assigns server-wide permissions to the user. For demo or eval purposes, this is probably best. For production use, we recommend that users be added to appropriate groups, and that groups be given access only to projects and snapshots. See the Security section of this document for a description of the mechanism provided and the cmacl man page for the syntax.

Create a SnapshotCM Project [command-line]

Run the sscreate command with the server host name and a full project/initial release path:

   sscreate -hhost /Project/Current

The next steps are to map the "Current" snapshot to a workspace on your system, populate the Current release with some files, and make a copy of Current called "Old" or "Release 1" or whatever.

Create a SnapshotCM Workspace [command-line]

Run wmap add to be prompted for all necessary information to create a workspace.

Prompts:

New Workspace Name:
Enter any name which is unique to the user on the local system. The workspace name is used as a short-hand for many of the commands.
Hostname of SnapshotCM Repository or Proxy server:
the name of the host running the SnapshotCM server. If you have a Proxy Server configured locally, use the the Proxy Server's hostname. Otherwise, use the Repository Server's hostname.
Path of Project/Snapshot to map:
Enter the full path to the snapshot to associate with the new workspace.
Local Workspace Directory to map to:
Enter the root directory of the workspace hierarchy to associate with the snapshot.

Alternatively, you can enter all the options directly:

wmap add -Nname -hhost -D C:/workspace -S /Project/Current -r /

Run wmap -? or wmap --help to see the full set of wmap options.

If the mapping is done correctly, you should now be able to run wls from the local workspace root directory without error (and without output).

Start Using SnapshotCM

The following commands create and import your first file and directory into SnapshotCM:

   $ cd local_workspace_root_directory
   $ mkdir newDir            # Create sample directory
   $ date >newDir/newFile    # Create sample file
   $ wci -auto newDir        # Import directory and file
   $ wls -lR                 # List imported files
   $ cd newDir       
   $ whist newFile           # Show history of imported file
   $ wls -l

For more information on the SnapshotCM command line, see the unix-style man pages locally using the man command, or on-line. Each command also displays a usage summary when passed either the -? or --help option.

Return to top of document.


Installing & Configuring on Windows

Run the self-extracting install program, or if already unpacked, run setup.exe. Then follow the prompts. You will need to select whether to install the client only, the Repository Server and client, or the Proxy Server and client. Refer to the next section for background information on selecting a location for the database when doing a server install.

At this point, your SnapshotCM Windows client install is complete and configured. For server configuration tasks, continue with the following steps.

SnapshotCM Repository Server Configuration on Windows

Create a SnapshotCM Repository Database

The SnapshotCM installation program will create a database and start the SnapshotCM server automatically when a server install is selected. The database folder is queried by the install program, while the archive folder is defaulted as described below. To change the database location information after the install, use the cmconfig command as described below. Otherwise skip to Create SnapshotCM Accounts to continue SnapshotCM server configuration.

The SnapshotCM server maintains all configuration management data in the SnapshotCM archive and database folders.

The SnapshotCM archive folder contains a hierarchy of versioned file contents for all files managed by the SnapshotCM server. The amount of space required will depend on the data being stored.

The SnapshotCM database folder stores all other data. The amount of space required will depend on the size of the project attributes (other than file content) being stored, but is typically much less than the archive directory.

To initialize the SnapshotCM database, create empty folders to hold the database and archive files, and then run the following commands from a command window:

   # cd  database_directory
   # cmconfig  -i  -C100  -d .  -a archive_directory_path  -l

These items can be configured separately if desired or if merely updating the configuration information.

Example:

   # mkdir  -p  E:\SnapshotCM\db  E:\SnapshotCM\ArchiveFiles
   # cd  E:\SnapshotCM\db      # database_directory
   # cmconfig  -i  -d .  -a ArchiveFiles  -l
   # cmconfig -C100 -l

Verify database configuration.

To display the configuration, run the following:

   # cd  database_directory
   # cmconfig  -l

This command will display the current configuration information. Use the cmconfig command to update any values necessary.

Start the SnapshotCM Repository Server

To register the SnapshotCM server as a windows service and configure it to start automatically at system boot time, run:

trueserver install

To manually start the SnapshotCM server, run:

trueserver start

The installer will ask to do these steps for you during a server install or update.

The trueserver command options stop and delete, shutdown and unregister the SnapshotCM server process respectively.

When requested to stop, a running server stops accepting new client connections and waits a few seconds for connected client activity to finish before exiting.

Create SnapshotCM Accounts

In this step, you login to the SnapshotCM server using the predefined administrator account, create additional accounts, and then restrict general access to the administrator account.

Run the SnapshotCM GUI, either by running the truecm command, or by selecting Start -> Programs -> SnapshotCM.

Once the GUI starts, select Admin -> Accounts...

Select administrator in the SnapshotCM Account field of the Account Administrator dialog (initially it should have your local login) and then select your newly installed server in the SnapshotCM Server combo box. If your server is not in the list, enter your server host name in the edit field. Now select (or click) the Users tab.

If all goes well, you should be able to select New... and create an account for yourself (use your local login, the name originally in the top box). You can create other accounts as well as groups.

Before closing this dialog, select the administrator account, choose Edit..., enter a password for this account, and remove the wild-card Trusted Logins/Hosts pair by selecting the line and selecting Remove.

NOTE: In the event that the administrator password is ever forgotten, the administrator account and access can be reset by stopping the server and running (as user root or truecm) the

cmconfig -A

command in the database directory on the server.

Select "Close" when finished.

Assign Access

Once the database is created, the server started and users added, you need to give users appropriate access to the data. To set/modify user privileges, select Admin -> Server Properties and login as administrator as before. Select the Administration ACL tab and then select New..., select the Users button, select the account(s) to which to add privileges and choose Add.

Back in the Server Properties window, select your account in the list and then select all permissions bits below (by default, only "V" will be selected) and then choose OK.

Note: This example assigns server-wide permissions to the user. For demo or eval purposes, this is probably best. For production use, we recommend that users be added to appropriate groups, and that groups be given access only to projects and snapshots. See the Security section of this document for a description of the mechanism provided.

Create a SnapshotCM Project

From the GUI, select Project -> Open Project Manager..., select your server in the Projects list and press New.... This will open the Create Project dialog.

Create ProjectFill out the Create Project dialog, entering Current for the initial snapshot name and then OK.

Now press Open in the Project Manager to open the project and you'll see a graph with one node.

Note: You can open or switch projects by selecting Project -> Open Project Manager or Project -> Recent Projects and selecting the desired project.

A project can also be created from a unix or Windows command line by running the sscreate command with the server host name and a full project/initial release path:

sscreate -hhost /Project/Current

Create a SnapshotCM Workspace

To map a workspace from the GUI, double click on the snapshot to be mapped to a workspace. (In the example, double click on Current.) If already mapped, double-clicking will open the workspace browser on the associated workspace. Otherwise, it will ask if you want to create a new mapping. Select Yes.

You can also create a mapping by choosing Snapshot -> Map to Workspace..., and browse a workspace by selecting the mapped snapshot and then choosing Snapshot -> Browse.

You will now be in the workspace mapping wizard, which will prompt you to select the server and snapshot to map. The project and snapshot you double-clicked previously should be automatically selected so simply press Next>.

The second page of the wizard will ask for a workspace name and location. Defaults are generated from the project and snapshot names.

If you have an existing hierarchy of files to import, you can select that existing location for the Local Folder for the workspace.

Note: The defaults for the Workspace Name and Local Folder can be configured via the Project -> Options... dialog.

The Text File Format will be set to Windows. Unless managing a workspace to be accessed remotely, you will want this to be Windows.

Press Next> and then when you select Finish, the workspace browser will be started.

Start Using SnapshotCM

At this point, you have an open Workspace Browser. The Workspace Browser is where you check out your files from a project snapshot into your local workspace and where you check in and import files from your local workspace folders into a project snapshot.

If you selected an existing hierarchy in the workspace wizard, you can import those files and directories into the snapshot by selecting them in the Workspace View on the right, and then selecting the blue, left pointing arrow (alternatively, you can drag the files and directories from the Workspace View into the Snapshot View, or select the File -> Import... or File -> Check In... menu).

If the Workspace View is empty, use the File -> New menu to create initial files or folders, or use external tools to populate the workspace folders. You can also change the workspace's local folder (or any other workspace attribute) by selecting the Workspace -> Properties... menu.

The Workspace Browser has several areas to note. First, it is divided horizontally into 3 views. On the left is the Snapshot Folders View which shows the hierarchy of versioned folders in the project snapshot. In the middle is the Snapshot View, which shows the files and folders in the snapshot that correspond to the folder selected in the Snapshot Folders View. On the right, the Workspace View shows the files and folders in the local workspace that correspond to the folder selected in the Snapshot Folders View. A tool bar is positioned between the Snapshot and Workspace Views.

Below the three views is the Workspace Browser Output Window where status and error messages are displayed.

The Snapshot and Workspace views have predefined view filters that affect what is displayed. For additional information on the Workspace Browser, select the Workspace Browser and then press F1 to access the on-line help. Nearly every dialog also has on-line help describing the use and meaning of the dialog.

Return to top of document.


SnapshotCM Proxy Server Configuration on Windows

Create a SnapshotCM Proxy Cache

The SnapshotCM installation program will create a proxy cache and start the SnapshotCM proxy server automatically when a proxy server install is selected. The proxy cache folder is queried by the install program. To change the cache location information after the install, use the cmconfig command as described below.

The SnapshotCM Proxy Server maintains a cache of file revisions and related information. Whenever a request is made for one of the cached revisions, it is served locally without additional traffic to the SnapshotCM Repository Server.

The SnapshotCM Proxy cache contains s few database files and a hierarchy of file revisions managed by the SnapshotCM Proxy Server.

To initialize the SnapshotCM Proxy Cache, create an empty folder to hold the cache files, and then run the following commands from a command window:

   # cd  cache_directory
   # cmconfig  -ip  -M500  -h <repository_host_name>  -d . -l

These items can be configured separately if desired or if merely updating the configuration information.

Example:

   $ mkdir  -p  E:\SnapshotCM\proxy
   $ cd  E:\SnapshotCM\proxy                         # proxy cache directory
   $ cmconfig  -ip  -d . -M500 -h repo.domain.com -l # create new cache
   $ cmconfig -M1000 -l                              # change disk cache size

Verify database configuration.

To display the configuration, run the following:

   # cd  cache_directory
   # cmconfig  -l

This command will display the current configuration information. Use the cmconfig command to update any values necessary.

Start the SnapshotCM Proxy Server

To register the SnapshotCM Proxy Server as a windows service and configure it to start automatically at system boot time, run:

trueproxy install

To manually start the SnapshotCM Proxy Server, run:

trueproxy start

The installer will ask to do these steps for you during a server install or update.

The trueproxy command options stop and delete, shutdown and unregister the SnapshotCM server process respectively.

When requested to stop, a running server stops accepting new client connections and waits a few seconds for connected client activity to finish before exiting.


Configure as Source Code Control Provider [Client only] [Windows only]

On Windows, the SnapshotCM installer automatically performs this step. The following simply documents what the installer has already done for the curious.

SnapshotCM provides an integration to Developer Studio and other SCC using tools. Occasionally it is necessary to enable or disable this integration. Enabling is most easily accomplished by invoking the SnapshotCM.reg file included in the distribution. Otherwise, you need to edit the registry and get all the details just right.

There are three keys and four values necessary to properly configure SnapshotCM as the default SCC Provider:

Key: HKEY_LOCAL_MACHINE\SOFTWARE\True Blue Software\SnapshotCM\1.0
Value Name: SCCServerName
Value String: SnapshotCM
Value Name: SCCServerPath
Value String: C:\Program Files\True Blue Software\SnapshotCM\truescc.dll
Key: HKEY_LOCAL_MACHINE\SOFTWARE\SourceCodeControlProvider
Value Name: ProviderRegKey
Value String: SOFTWARE\True Blue Software\SnapshotCM\1.0
Key: HKEY_LOCAL_MACHINE\SOFTWARE\SourceCodeControlProvider\InstalledSCCProviders
Value Name: SnapshotCM
Value String: SOFTWARE\True Blue Software\SnapshotCM\1.0

The four values and their meanings are:

  1. The SCCServerName value string specifies the SCC provider name.
  2. The SCCServerPath value string specifies where the dll providing the integration resides. The above value assumes a default install location. The install modifies this path in SnapshotCM.reg according to the actual install directory.
  3. The ProviderRegKey value string specifies the registry key (relative to HKEY_LOCAL_MACHINE) of the default SCC provider.
  4. The last key contains a value for each SCC provider which is installed. The value name is the same as the SCCServerName value string and the value string is the same as the ProviderRegKey value string. This list allows an SCC using tool to present a list of SCC Providers from which the end-user can choose.

Return to top of document.


Protecting Your Data

Backup

The SnapshotCM server, trueserver, stores its files in the database and archive directories. In order to protect your data from inadvertent loss, both the database directory and the archive directory hierarchy should be backed up regularly. The SnapshotCM server wraps all database modifications within a transaction to protect against failures during an update which would otherwise leave the database in an inconsistent state. It is also important to perform the database and archive backups during a transaction to insure backing up a consistent state.

Performing a Backup

A backup of the SnapshotCM data involves three steps:

  1. Lock the database for backup. The database lock insures that the database and archive files are in a consistent state. Read operations will be allowed to continue, but operations that change or add information will block until the database lock is released. By allowing read access during backup, nightly build operations can continue without interference from the backup process.
  2. Backup the database and archive directory hierarchy. The database and archive files should be backed up together as they form the complete data for your projects. You can use whatever backup tool you have available, including a copy of all files to another disk drive.
  3. Release the backup lock.

The cmadmin command is used to lock and unlock the database for backup. cmadmin -l -h host will lock the SnapshotCM server running on host, and cmadmin -u -h host will unlock it. Locking and unlocking the database requires backup permissions in the Administration ACL (see the Admin->Server Properties... menu in the GUI).

Background information: Description of SnapshotCM database & archive files

The database directory contains several files as follows:

The archive directory contains a hierarchy of numbered directories containing numbered files. The numbers provide indexing and the files store revision content. Revision content files may be GNU RCS files with one or more revisions, or they may be simple (binary) files holding one revision. The SnapshotCM server chooses a storage method based on the size of the file being stored. Future releases may use more advanced storage methods.

What if the data becomes too large for my disk?

You can put the database and archive directories on separate disks.

On unix platforms, you can use symbolic links to put a portion of the archive hierarchy on another disk. Just be certain to backup all data together within the database lock / unlock window.

You can buy a bigger disk.

Return to top of document.

Security

SnapshotCM provides authentication and authorization flexibility to allow each site to balance trust, convenience and security.

Authentication

Authentication is the process of proving a user is who he or she claims to be. Two authentication methods are provided. Both start with the client requesting access as a given SnapshotCM user account. The SnapshotCM user default is the user's login name on the client, but can be overridden by the SNAPSHOTCM_ACCOUNT environment variable, and in some cases, by editing an appropriate field in a GUI dialog.

The most secure environment requires users to enter a password to obtain access to the SnapshotCM server. For GUI operation, the password need be entered only as often as the GUI is restarted, or the password is changed.

For command line operation, the first command will prompt for a password. On success, an authentication token is cached on the client system. Later command line accesses will pass the authentication token to the server, and if it is still valid (matches the token remembered by the server and not yet expired), access will continue without prompting for a password. If the authentication token is not valid, the user will be prompted for a password. Note: the authentication token time-out value can be set from the Admin->Server Properties... page. All authentication tokens are forgotten when the SnapshotCM server is restarted.

In some environments (nightly scripted access, for example) and for some access types (like locking for backup), it may be desirable to allow limited access without a password. To support this, SnapshotCM also supports a per account set of trusted login/host pairs. If accessing SnapshotCM from a trusted host (as determined by converting the client IP address to a hostname) and as a trusted user, then access will be granted without a password.

Overall, this scheme supports a balance between convenience (not prompting for a password on every server command), and security. A typical balance might require a password be entered daily, or allow operation without a password from local systems, but require a password for access from remote or dial-up systems. Backup locking typically would be enabled only for a special SnapshotCM user which only has backup privileges, and access to that SnapshotCM user account would be restricted to the system and account performing backups. If no password is set, no passworded access is allowed (i.e., null passwords are not provided).

Authorization

Authorization is the process of granting or restricting access to objects or operations for an authenticated SnapshotCM user account. SnapshotCM supports access control lists (ACLs) on three types of objects, each with up to eight different accesses. Each object's ACL contains a list of user and group ids together with the allowed accesses. Access granted to a user account for an object is the logical OR of all matching ACL entries. An ACL entry matches a given user account if the entry id is equal to the SnapshotCM account user id, or if the entry id is equal to one of the SnapshotCM group ids associated with the SnapshotCM user account. Every user is always a member of the everyone group.

The following table describes, for each object and access, what operations are allowed:

Access Object
Administration ACL
(See Admin->Server Properties...)7
Account ACL
(See Admin->Server Properties...)4
Project ACL
(See Project->Properties...)5
Snapshot ACL
(See Snapshot->Properties...)5
File ACL
(See File->Properties)5
Folder ACL (See File->Properties)5
View View any project, snapshot or account in this database.3 View any SnapshotCM user or group properties. View and traverse the project. Without view access, release snapshots cannot be seen. View and traverse the snapshot. Without view access, child snapshots cannot be seen. unused unused
Modify Modify any project, snapshot or account in this database (except for ACLs). Modify user and group properties. Modify the project properties (except the ACL). Modify the snapshot properties (except the ACL and frozen state). unused unused
Permission Edit any ACL (Administration, Account, Project or Snapshot) and any snapshot's frozen state. Edit the Account ACL. Edit the project ACL. Edit the snapshot ACL and toggle the snapshot frozen state. Edit the file ACL.2 Edit the folder ACL.1,2
Delete Delete or disable any project, snapshot or account. Disable user accounts, delete group accounts. Delete the project. Delete the snapshot. unused unused
Create Create new snapshots. unused Create release snapshots. Create a child snapshot. unused Copy ACL to new children.1
Read Read any file or directory in any snapshot. unused unused Read files and directories in the snapshot. Read file contents and attributes.2 Copied to new children or unused.1
Write Modify, create or delete any file or directory in any snapshot. Set, remove or break any lock. unused unused Modify, create or delete files and directories in the snapshot. Set, remove or break locks on files. Modify file contents and attributes.2 Copied to new children or unused.1
Backup Lock and unlock the server for backup. unused unused unused unused unused

Notes:

  1. The ACL on a folder can hold the default ACL for newly created files and folders within it. This is enabled when the everyone group's "Create" bit is set. If the everyone group's "Create" bit is not set, then a folder ACL has no effect on initial ACL values, or on access control.
  2. File Read, Write and/or folder or file Permission access is granted only if access is granted by the Administration ACL alone, or by both the Snapshot ACL and File ACL.
  3. Server properties can always be viewed.
  4. The everyone group is usually given Account View access, so that ACL entries can display symbolically rather than numerically.
  5. A project or snapshot's initial ACL will be copied from its parent and modified to give the creating user full access to the snapshot just created.
  6. File and Folder ACLs are initialized to give everyone Read, Write access, which effectively leaves access control to the snapshots.
  7. If Administration access is inadvertently deleted or password lost for all administrator users, the cmconfig command can be used to restore access. See the discussion in the Configuring SnapshotCM section of this document.

Return to top of document.


Optimizing SnapshotCM Performance

We strive to make the out-of-the-box performance of SnapshotCM pretty good. Usually, no special action is required to achieve good performance with SnapshotCM. Nevertheless, there are things out of our control which can impact real and perceived performance. This section provides places to look should performance be less than optimal in your environment, or for some users.

Server Performance

Optimal server performance will result if all database (z*) files fit into the server's cache. Recommendation: increase the maximum cache size to match the amount of system memory you can dedicate to SnapshotCM. SnapshotCM will only use the amount necessary. The following command configures a maximum cache size of 100 MB.

    cmconfig -C 100

Other things that can affect performance of the server:

Client Performance

Faster client systems (network, disk, CPU) improve update performance and general interaction with the SnapshotCM server. Additionally, configuring a working set and using the recursive display options with more restrictive filters will produce better performance than updating or displaying all files in a workspace.

Network Performance

SnapshotCM streams information between the client and the server to avoid slowdowns caused by long round-trip (ping) times (RTT). Nevertheless, some round-trips are inevitable, and the quicker your network (RTT, throughput, DNS lookups, etc.), the snappier will be your performance.

Additionally, if DNS is misconfigured or not operating properly, SnapshotCM performance will be impacted.


License Management

SnapshotCM is a licensed product. Upon database initialization, a one-time license will be installed allowing use by a large number of users for a limited time. Once that time has elapsed, one user is allowed to continue using SnapshotCM. Support for evaluation purposes is provided via the normal channels. Support for use of the single free license, other than for evaluation purposes, may be provided on a limited basis.

Once a license fee has been paid, a new license will be generated and sent to you for the database of your choosing. To generate a license, True Blue Software must know the database identifier for the database you intend to use as well as the license identifier. The SnapshotCM GUI displays this information in the Admin->Server Properties... dialog, under the General tab. This information also is displayed by running the cmconfig -l command from the database directory after stopping the trueserver process.

A SnapshotCM license is for a specific number of users for use with a specific database, and includes free updates for a specific period of time. An updated license will be generated annually as support contracts are renewed. A license should be purchased for each daily user of SnapshotCM. Less frequent users can share licenses, the number required depending on the frequency of use. Any access to the server, including locking for backup, will reserve a license.

Because a lot of time can be lost if a nightly build should fail, SnapshotCM does not strictly enforce the license limit. Users beyond the licensed number will will succeed, but will operate at significantly reduced performance. If your peak use regularly exceeds the licenses available, you should increase your licenses.

Return to top of document.

Installing a SnapshotCM License

A SnapshotCM license can be installed using the Windows GUI, using a client program, or directly into the database. All three procedures are described:

Installing a SnapshotCM license using the Windows GUI:

  1. Open the GUI and select Admin->Server Properties menu.
  2. Enter your account and host information, select the Install New button on the General tab.
  3. Paste the provided license string into the License Renewal dialog box and press OK.
  4. On success, a "License Successfully Installed" message is displayed.

Installing a SnapshotCM license using the client command-line:

  1. Run the command:
    cmadmin -hServer -L "license"
    

    where Server identifies your SnapshotCM server, and license is the provided SnapshotCM license string.
  2. On success, a "License successfully installed." message is displayed.

Installing a SnapshotCM license directly into the SnapshotCM database:

  1. Login on your SnapshotCM server machine as a user with permissions to modify the database files (root or truecm on unix, administrator privileges on Windows).
  2. From a command-line prompt, set working directory to the location of the SnapshotCM database. You can display the configured database location using the cmconfig command:
        cmconfig -l           # to display the configured database location
        cd DatabaseDirectory
    
  3. Stop the SnapshotCM server:
        trueserver stop
    
  4. Install the new licenses. Example command:
        cmconfig -L "SnapshotCM 1.11 25 permanent 00100 12345-67890 12345-67890-12345"
    
  5. Restart the SnapshotCM server:
        trueserver start

Return to top of document.

Understanding a SnapshotCM License

A SnapshotCM license consists of the following seven fields in order:

Field Example Description
Product name SnapshotCM SnapshotCM (very old licenses may still have TrueCM in this field).
Support expiration 1.11 The newest A.0Y.MM.xx release revision which will operate upon the database. Updating SnapshotCM to a product revision newer than the support expiration will result in a non-functioning product. Y = year - 2000, MM = month - 1 (range 0-11). The example is for December, 2001. Note that newer licenses use MM=month (range 1-12) rather than month - 1.
License count 25 Number of licenses granted.
License expiration permanent The last day for which the license is valid (YYYY/MM/DD). It is 'permanent' for non-expiring licenses.
License Id 00100 License identifier assigned by True Blue Software. It is 0 for evaluation licenses.
Database Id 12345-67890 Identifier of the database. If the license does not match the database, the license install will fail.
Checksum 12345-67890-12345 A checksum of the preceding fields. If any of the fields are incorrect, the checksum will not match and the license install will fail.

Return to top of document.


Moving Your Database

Moving your database to a bigger disk or disk partition or faster machine is a fairly simple operation, but must be done carefully. After all, it is your data we are talking about! Here are the steps:

  1. Make a backup of everything. After all, it is your data.
  2. Stop the trueserver process:
        trueserver stop
    
  3. Verify database consistency before the copy:
        cd database_directory
        dbck
    
    Note: If dbck reports any problems, please send the output of dbck to support@truebluesoftware.com for assistance in repairing reported problems. While copying the database files will not worsen any problem, we recommend that any reported problems be fixed immediately.
  4. If the byte order of integers in the old and new systems is different (one is big-endian and the other is little-endian), you will need to dump your database (z*) files to ascii (*.txt) files. Please contact support@truebluesoftware.com for the necessary conversion tools. The additional steps are:
        cd database_directory
        Replace the schema.dbd file with the version for your source platform from the conversion tools package
        Run "dbexp schema"
        Remove the dbexp file
    
  5. Copy the database directory files to the new location. If step 4 applies, you will need to copy the *.txt files. Otherwise, copy the z* files. Preserve the permissions and ownerships on the files, and make certain that the trueserver process will be able to access the new directory. The database files should be copied in binary mode if copying across a network.
    Important note: All transactions must be completed before copying the database files, because the transaction recovery log file, transact.log, contains hard-coded paths and cannot be moved. transact.log is appropriately removed by SnapshotCM upon a clean shutdown. You can also safely copy the database files (but not transact.log) if you've set a backup lock (with cmadmin -l). Do not copy the transact.log file.
  6. Copy the archive directory hierarchy to the new location. Preserve the permissions and ownerships on the files and directories, and make certain that the trueserver process will be able to access the new directory hierarchy. The archive files should be copied in binary mode if copying across a network.
  7. If step 4 (byte order) applies, do the following here:
        cd new_database_directory (where the *.txt files are)
        Copy the new schema.dbd and spec.imp files from the conversion tools package into this directory.
        Verify there are no transact.log or z* database files in this directory.
        Run "initdb -y schema" to create the initial, empty z* files
        Run "dbimp spec.imp" to load the *.txt data into the z* files
        Remove the spec.imp, initdb and dbimp files
        Confirm/set proper ownership of new z* files (truecm on unix, accessible only to SnapshotCM on Windows)
    
    Note: Expect a "Warning: Owner of directory_to_parent is NULL_DBA" message for each project or project folder in your database.
  8. Configure SnapshotCM to use the new locations:
        cd new_database_directory
        cmconfig  -d .  -a new_archive_directory_path
        cmconfig  -f new_logfile_path
    
  9. Verify that the correct locations are configured:
        cd new_database_directory
        cmconfig -l
    
  10. Verify the database copy:
        cd new_database_directory
        dbck
    
  11. Start the SnapshotCM server on the new database:
        trueserver start
    

Return to top of document.


Understanding the ActivityLog

The activity log file records operations performed by the server. Each action is a single line, formatted as described below. The set of actions which are logged can be modified via the Admin->Server Properties page, General tab, in the GUI. By default, all modify operations are logged and read-only operations are not logged.

[date.time] account ...

The account is the SnapshotCM account performing the action. For most entries, the account is followed by an ObjectType and an Action. The ObjectType is one of the following, with possible actions shown in ()

Object Type   Description   Possible Actions
A Account ACL Acl
DB Database Lock, Unlock
F File New, Ci, Commit, abort, Co
G Group List, New, NewMem, DelMem, Delete, Acl, Info
H History Comment, Ancestor, List
HistGetAncestor History Will be replaced with "H Ancestor"
HList History Will be replaced with "H List"
I Item (file or directory) List, Chmod, Copy, Merge, Mkdir, Delete, Rename, Acl, Io, Key, Rev, Unlink
L Lock List, Strict, Comment, Loc, Delete, Update
Login Login none
Srv Server global properties List, Acl, ArPath, AuthTime, LogMask, LogPath
SS Snapshot or project List, Con, Discon, New, Copy, Link, Delete, Rename, Acl, Desc, Flag, Diff
U User List, New, Info

Additional values after the action vary by what is logged, but typically include the name of the object or objects being operated upon, the object revision, the new value of the attribute, etc.

Return to top of document.