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
- Protecting Your Data
- Optimizing Performance
- License Management
- Moving Your Database
- Understanding the Server's ActivityLog
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
|
|
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.
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
- The -i option says to initialize new database files. They are created in the directory specified by the -d option, or the current directory.
- The -l option lists the configuration.
- The optional -C option specifies the maximum number of megabytes the database cache can use. The default is 100MB. SnapshotCM will only allocate memory as it has need, so setting this larger than your database size does no harm.
- The optional -d option specifies the path of the database directory.
- The optional -a option specifies the path of the archive directory. The default is the ArchiveFiles subdirectory of the database directory.
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
- The -ip option says to initialize a new proxy cache. It is created in the directory specified by the -d option, or the current directory.
- The -M option specifies the maximum number of megabytes the cache can use. This should be large enough to hold all the working revisions of all the files of interest.
- The -h option specifies the repository server's hostname.
- The -d option specifies the path of the proxy cache directory.
- The -l option lists the configuration.
- The optional -C option specifies the maximum size of the memory cache to be used by the SnapshotCM Proxy Server. Specify only if the size needs to be limited.
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.
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
- The -C option specifies the maximum number of megabytes the database cache can use. More pages generally results in better performance. Best performance is achieved if the complete database fits into memory (assuming you have that much physical memory).
- The -i option says to initialize new database files. They are created in the folder specified by the -d option, else the current folder.
- The -d option specifies the location of the database folder.
- The -a option specifies the location of the archive folder. The archive folder can be the same as the database directory if desired. If omitted, it defaults to the ArchiveFiles folder inside the database folder.
- The -l option lists the configuration.
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.
|
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 |
Fill out the Create Project dialog, entering Current
for the initial snapshot name and then OK.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>.|
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. |
The second page of the wizard will ask for
a workspace name and location. Defaults are generated from the project and
snapshot names.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.
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
- The -ip option says to initialize a new proxy cache. The new cache is created in the -d specified folder, else the current folder.
- The -M option specifies the maximum number of megabytes the cache can use. This should be large enough to hold compressed copies of all the working revisions of all the files of interest.
- The -h option specifies the repository servers' hostname.
- The -d option specifies the folder of the proxy cache.
- The -l option lists the configuration.
- The optional -C option specifies the maximum size of the memory cache to be used by the SnapshotCM Proxy Server. Specify only if the size needs to be limited.
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:
- The SCCServerName value string specifies the SCC provider name.
- 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.
- The ProviderRegKey value string specifies the registry key (relative to HKEY_LOCAL_MACHINE) of the default SCC provider.
- 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.
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:
- 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.
- 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.
- 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:
- SnapshotCM.lck prevents multiple programs from accessing the database files simultaneously. Contains the process id of the server.
- activityLog.out is the default name of the server logging file. This name can be changed from the Admin->Server Properties... dialog and does not need to reside in the database directory. The server logging file records all selected actions that SnapshotCM takes and provides an audit trail for after-the-fact metrics or change tracking.
- msglog is the default name for the standard and error output of the SnapshotCM server. Consult this text file if the server fails abnormally. It can be truncated at any time. This filename can be changed using the cmconfig -f /new/msglog/path command.
- schema.dbd is the database description file. It must match both the database files and the SnapshotCM server version.
- transact.log is used by the SnapshotCM server for transaction logging. Do not delete it, as it is managed automatically, and is required to recover from a crash that occurs during a transaction.
- z* files are the actual binary database data files.
- Other files or subdirectories will be ignored. Therefore it is possible to make the archive directory a subdirectory of (or the same directory as) the database directory.
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.
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:
- 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.
- 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.
- Server properties can always be viewed.
- The everyone group is usually given Account View access, so that ACL entries can display symbolically rather than numerically.
- 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.
- File and Folder ACLs are initialized to give everyone Read, Write access, which effectively leaves access control to the snapshots.
- 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.
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:
- For best performance, put the database files on a non-busy, non-system disk drive.
- Type of file system on which the database files are located. NTFS is faster than FAT. Journaling file systems may be faster than vfs, etc. Of course, these files need to be part of a persistent (non-RAM) file system.
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.
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:
- Open the GUI and select Admin->Server Properties menu.
- Enter your account and host information, select the Install New button on the General tab.
- Paste the provided license string into the License Renewal dialog box and press OK.
- On success, a "License Successfully Installed" message is displayed.
Installing a SnapshotCM license using the client command-line:
- Run the command:
cmadmin -hServer -L "license"
where Server identifies your SnapshotCM server, and license is the provided SnapshotCM license string. - On success, a "License successfully installed." message is displayed.
Installing a SnapshotCM license directly into the SnapshotCM database:
- 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).
- 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 - Stop the SnapshotCM server:
trueserver stop - Install the new licenses. Example command:
cmconfig -L "SnapshotCM 1.11 25 permanent 00100 12345-67890 12345-67890-12345" - Restart the SnapshotCM server:
trueserver start
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. |
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:
- Make a backup of everything. After all, it is your data.
- Stop the trueserver process:
trueserver stop - Verify database consistency before the copy:
cd database_directory dbckNote: 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. - 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 - 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. - 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.
- 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. - Configure SnapshotCM to use the new locations:
cd new_database_directory cmconfig -d . -a new_archive_directory_path cmconfig -f new_logfile_path - Verify that the correct locations are configured:
cd new_database_directory cmconfig -l - Verify the database copy:
cd new_database_directory dbck - Start the SnapshotCM server on the new database:
trueserver start
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.
