Hives
This topic describes how to use hives as a storage location.
Hives overview
A hive is a computer location where StarTeam Server stores archive files and a cache. These items are contained in the Archives and Cache folders. For example, if you created a server configuration named MyConfiguration and located it on the root of your C:\ drive, by default, StarTeam Server generates a folder under C:\MyConfiguration named DefaultHive containing Archives and Cache subfolders. The DefaultHive folder and its subfolders represent the hive.
StarTeam Server Native-II vaults can have any number of hives, each of which has its own archives and cache. If one hive fills up, you can add another without having to change any data locations or move any archive files. Companies with large files or large numbers of files can start off with more than one hive in the first place. They can even put the archives and cache on different drives or volumes (this is recommended).
Native-II vaults store each file revision in its entirety (even though the archive file may be compressed). This means that the Native-II vault eventually takes more space; however, you can spread the revisions over many drives or volumes by the use of hives for storage. This flexibility in using storage space becomes a greater benefit over time as hives become full.
When a server configuration has multiple hives, the Server adds files to each hive in turn before reusing the archive path of the first hive. If you are running a StarTeam client against a StarTeam Server and if a StarTeam Server configuration has more than one hive, then the Server does a round-robin as it stores files but it checks first to see that no hive already has this file before the client attempts to stream the file to the server.
When you create a server configuration, it automatically has at least one hive (either the default or a custom hive). To increase the amount of available space for this server configuration, you can add one or more new hives with the Hive Manager dialog. When remotely accessing a server configuration, you can create hives while the server configuration is running, because the configuration already has an initial path, if only to a DefaultHive in the repository path.
You can also use the Hive Manager dialog to change an individual archive path and/or cache path for a hive. Such changes should be done only when that hive must be moved. For example, you might move a hive as a result of a drive failure. You would also need to copy the contents of the archive path for that hive to the new location.
We recommend that the Archives and Cache volumes from one server configuration should not be mapped to Archives and Cache volumes from any other server configuration. Otherwise, the threshold settings on the Archives folders will not be calculated as accurately. This is because the server checks the available disk space when starting a server configuration, and it caches the value returned. As files are added or removed, for cache cleanup, the server adjusts the available space and determines if the threshold has been exceeded. Because of performance concerns, the threshold value is cached instead of checked every time a file is added or removed. The threshold value is a guideline used by the server to determine when to no longer place files in a particular hive. It is not meant to be an absolute cutoff.
Also, if the server believes that the threshold may have been crossed based on the cached available space, it will do one more check and query the file system as it does at startup to make sure current available disk space is correct before pulling the trigger on the hive. Accordingly, since the threshold value is tracked on a per-server-configuration-basis, in order for threshold calculation to be as accurate as possible (thus reducing the number of times the file system is checked for available space), we recommend that each server configuration point its hives to independent volumes.
Creating new hives
You can use the Hive Manager dialog for creating new hives to increase the amount of available space, or for viewing and updating the properties of an existing hive.
If accessing a remote server configuration or if a local server configuration has been added as a remote server, you can create new hives while that server configuration is running. If accessing a local server configuration locally, you must first shut down the server configuration before creating a new hive.
To create a new hive:
-
Open the
Server Administration tool and select the server configuration from the
Server Pane.
If you are not logged on, the Server Administration tool requires you to do so before continuing.
Note: If accessing a local server configuration locally, you must shut down the server configuration before proceeding to the next step.
-
Do one of the following:
- Click the Hive Manager shortcut button in the shortcut pane.
- Select from the main menu.
The Hive Manager dialog opens.
-
Click
New in the
Hive Manager dialog box.
This opens the New Hive dialog box.
Note: The location of the hive-index.html file, which contains the properties for each hive used by the server configuration, displays at the top of the dialog.
-
Type information about the new hive in the following fields:
- Name: Unique name for the hive. DefaultHive is the default.
- Archive path: Path to the Archives folder for the new hive. The default path is <repository path>\DefaultHive\Archives .
- Cache path: Path to the Cache folder for the new hive. The default path is <repository path>\DefaultHive\Cache .
- Maximum cache size: Maximum number of megabytes of hard disk space that the Cache can use. The default is 20% of the disk space available. In the Server Administration tool, you can calculate the correct default maximum size for the cache. However, if you are using the Server Administration tool and it is not running on the same computer as the Server, you cannot calculate the maximum size. In this situation, type 100MB, as a default size.
- Cache cleanup interval: Seconds between cache cleanup/refresh operations. The default value is 600. The range is 60 (1 minute) to 3153600 (1 year).
- Storage limit threshold: Percentage of total disk space allowed for hive. When this percentage has been reached, StarTeam does not add any more archives to the hive. The default is 95% of total disk space.
Tip: You can use UNC paths for the Archives and Cache paths.
-
Select or clear the option to
Allow new archives. The default is selected. If no other hives exist for the server configuration, this check box must be selected.
Note: If you are adding a hive because the original hive was low on space, you should also use the Hive Manager dialog to display the properties of that hive and clear the Allow new archives check box. This action allows the original hive to remain a check-out location, but keeps it from acquiring any new files. Files that are added go to the new hive.
-
Fill the
Root Cache Agent archive path
text box if you are using Cache Agent, and the Root Cache Agent is not on the same computer as the Server. Provide the path
to the cache from the point of view of the Cache Agent.
For example, suppose you create a new hive whose archive path is C:\ProdServer\Hives\NewHive\Archives, but the Root Cache Agent runs on a computer that has H:\ mapped to C:\ProdServer\Hives on the StarTeam Server computer. The Root Cache Agent would see the new hive archive path as H:\NewHive\Archives, so in this situation, you would type H:\NewHive\Archives in the Root Cache Agent archive path text box.
- Click OK to confirm your choices. This action returns you to the Hive Manager dialog.
-
Click
OK
to return to the main window of the
Server Administration tool.
Note: If accessing a local server configuration locally, you can now restart the server configuration.
Customizing the archives path
Changing the Archives path for a hive is generally done because of a serious problem, such as a drive failure. It must also be done with caution, or the results can be unexpected.
You must restart the server configuration for the new Archives path to take effect. The Server Administration tool saves the new path to the hive-index.xml file immediately; however, the changes take effect only after you restart the server configuration.
If accessing a remote server configuration or if a local server configuration has been added as a remote server, you can update the Archives path while that server configuration is running. If accessing a local server configuration locally, you must first shut down the server configuration before updating the Archives path.
To change the Archives path for a server configuration that is shut down:
- Open the Server Administration tool and shut down the server configuration for which you want to modify the Archives path.
- Copy the Archives folder to its new location.
- Open the
Hive Manager
dialog box in the
Server Administration tool by doing one of the following:
- Click the Hive Manager shortcut button in the shortcut pane,
- Select from the main menu.
- Update the Archive path field pointing to your new Archives path location.
- Click OK to confirm your choices. This action returns you to the Hive Manager dialog.
- Click OK to return to the main window of the Server Administration tool.
- Restart your server configuration.
Note: If you already have more than one hive for your server configuration, and you cannot quickly move the Archives folder to its new location, then you can disable any new archives from being added to the problematic Archives path by clearing the option to Allow new archives in the Hive Properties dialog. With this option cleared, StarTeam does not add any new archives to the designated Archives folder for the specified hive.
- Open the
Server Administration tool, and select the running server configuration containing the Archives path that you wish to update.
Note: This must be a remote server configuration or a local server configuration that has been added as a remote server. You cannot access hive properties for local server configurations running locally.
- Open the
Hive Manager
dialog box in the
Server Administration tool by doing one of the following:
- Click the Hive Manager shortcut button in the shortcut pane.
- Select from the main menu.
- Select the applicable hive in the
Hive Manager
dialog box, and click
Properties.
This opens the Hive Properties dialog box.
- Clear the
Allow new archives
check box in the
Hive Properties
dialog if at least one other hive exists for the server configuration.
The files that are added or checked in will be sent to the other hive.
- Restart the server configuration.
- At an appropriate time, do the following:
- Shut down the server configuration.
- Copy the archive files to their new location.
- Change the Archive path field in the Hive Properties dialog to the new location, and check the option to Allow new archives.
- Restart the server configuration.
Viewing and customizing hive properties
Sometimes you may want to view the properties for a specific hive or change its settings. For example, you may want to move its Archives or Cache folders to an alternate location. In that situation, you must use the Hive Manager dialog to display the properties for the hive, and then change them.
If accessing a remote server configuration or if a local server configuration has been added as a remote server, you can view and update hive properties while that server configuration is running. If accessing a local server configuration locally, you must first shut down the server configuration before viewing or updating hive properties.
To customize hive properties:
-
Open the
Server Administration tool and select the server configuration from the
Server Pane.
If you are not logged on, the Server Administration tool requires you to do so before continuing.
Note: If accessing a local server configuration locally, you must shut down the server configuration before proceeding to the next step.
-
Do one of the following:
- Click the Hive Manager shortcut button in the shortcut pane.
- Select from the main menu.
The Hive Manager dialog opens.
- Select the applicable hive in the Hive Manager dialog, and click Properties. The Hive Properties dialog opens.
-
Review and, if desired, change the information in this dialog.
Tip: With the exception of the Name field, you can edit all of the fields in the Hive Properties dialog. For the default and possible settings for these fields, refer to the link “Creating New Hives” at the bottom of this topic.
-
Click
OK
to confirm your choices when satisfied with your changes.
This action returns you to the Hive Manager dialog box.
-
Click
OK
to return to the main window of the
Server Administration tool.
Note: If accessing a local server configuration locally, you can now restart the server configuration.