Table of Contents

1      Introduction. 2

1.1       Plastic SCM. 2

1.2       Components 2

2      Minimum requirements. 4

2.1       Server 4

2.2       Client 4

3      Plastic SCM installation. 6

3.1       Prerequisites 6

3.2       Server and Client installation. 6

3.3       Installing several server instances 10

3.4       Server configuration. 11

3.5       User authentication configuration. 12

3.5.1      Authentication basics 13

3.5.2      Local users 13

3.5.3      Local users: name + ID. 13

3.5.4      Active Directory Integrated Security. 14

3.5.5      LDAP. 14

3.5.6      User/Password. 14

3.6       Server startup. 21

3.6.1      Windows Systems 21

3.6.2      Linux Systems 22

3.7       Client configuration. 23

3.7.1      Merge and Differences Tools configuration. 25

4      Using a proxy server 28

5      Creating and managing  repositories. 31

5.1       Creating a new repository. 31

5.2       Listing available repositories 32

5.3       Archiving repositories 33

5.4       Reconnecting archived repositories 34

5.5       Using several repository servers 34

6      Creating and managing workspaces. 36

6.1       Creating a new workspace. 37

6.2       Listing available workspaces 37

6.3       Removing a workspace. 38

6.4       Moving a workspace. 38

7      Repository data location. 39

8      Backup and restore. 40

8.1       Backup. 40

8.2       Restore. 41

9      Archiving revisions. 42

9.1       Why archiving revisions 42

9.2       How to archive my revisions 42

9.3       How are the archived revisions accessed. 43

9.4       How to restore archived revisions 44

Figures

Figure 1. Language selection. 6

Figure 2. Installer start up. 7

Figure 3. License agreement 7

Figure 4. Installation directory. 7

Figure 5. Component selection. 8

Figure 6. Eclipse location. 9

Figure 7. Ready to install 9

Figure 8. Copying files 10

Figure 9. Start system configuration. 10

Figure 10. Restart machine. 10

Figure 11. Server configuration welcome screen. 11

Figure 12. Server configuration language selection. 11

Figure 13. Server configuration authentication modes 12

Figure 14. LDAP Authentication configuration. 12

Figure 15. Port configuration. 12

Figure 16. User and password configuration screen. 15

Figure 17. Login dialog. 15

Figure 18. Involved configuration files in UP mode. 16

Figure 19 umtoolgui 17

Figure 20 umtoolgui usage. 18

Figure 21. users.conf file format 20

Figure 22. groups.conf file format 20

Figure 23. server.conf contains WorkingMode. 20

Figure 24. Managing Plastic SCM server service. 22

Figure 25. Client configuration welcome screen. 23

Figure 26. Client configuration language selection. 23

Figure 27. Workspace server selection. 24

Figure 28. Client authentication selection. 24

Figure 29. Client AD LDAP authentication window. 24

Figure 30. Example of proxy deployment 29

Figure 31. Example of network 29

Figure 32. Same network, improved by using two proxies 30

Figure 33. Creating a new repository. 32

Figure 34. Repositories view. 32

Figure 35. Creating a new repository. 37

Figure 36. Workspaces view. 37

Figure 37. Introduce the external data location path. 44

 

About this guide

This guide describes the procedures associated with Plastic SCM installation and maintenance.

Audience

This guide is targeted to developers and system administrators, assuming familiarity with Plastic SCM and operating system concepts.

Online documentation

Besides this document and the rest of the guides, Plastic SCM provides online reference throughout its different client frontends.

On the command line interface, both Windows and Linux, this reference can be obtained with the command:

For extended information on a specific command, type:

The graphical interface provides online reference through the Help menu.

Documentation errors

If you find any problem in this guide or any other part of the online reference, please report it using the following email address:

 

support@codicesoftware.com

1     Introduction

1.1    Plastic SCM

Plastic SCM is a Software Configuration Management system designed to handle software development teams of any size.

Plastic SCM provides high-end SCM capabilities without imposing any of the restrictions associated to these high-end systems like complex installation, operation and administration.

This guide assumes that the reader is familiar with the basic SCM concepts, with basic operating system usage through the command line and basic system administration.

The guide will show both system administrators and SCM managers how to install the SCM system, how to create repositories, workspaces and how to make backups.

1.2    Components

Plastic SCM uses a client / server architecture, divided into the following components:

• The server, responsible for storing all the project information, managing client access to that store.
• The Clients, run on the developers’ machines, and are responsible for communicating user operations to the server. The supported clients are:
• Command Line Interface (CLI): Provides access to Plastic SCM operations on the operating system shell. Very useful for task automation.
• Graphical User Interface (GUI): provides access to Plastic SCM operations using a graphic-oriented interface. It provides some graphical diagrams not available in the command line.
• Integrations with Integrated Development Environments such as:
• Visual Studio integration: provides access to commonly used operations like checkout / checkin from within Visual Studio, as well as full access to GUI views like Branch Explorer, labels and checkouts.
• Eclipse integration: provides access to the most used operations like checkout / checkin from within the Eclipse development environment.
• IntelliJ integration: provides access to the commonly used operations from the IDEA IDE.
• JDeveloper.
• Build Management tools integrations for the following products:
• Cruise Control
• Final Builder
• Integrations with task and issue management tools like:
• Atlassian Jira
• TechExcel DevTrack
• RallyDev
• Axosoft Ontime
• Version One
• Fog Creek’s FogBugz
• Trac
• Bugzilla
• Mantis

Visit our web page to get a full and up to date list of compatibilities at www.codicesoftware.com.

2     Minimum requirements

Below you will find the minimum hardware and software requirements needed to install and use Plastic SCM.

2.1    Server

The minimum system requirements to run the Plastic server are:

• Windows 2000 Server, Windows 2000 Professional, Windows 2003 Server or Windows XP SP2 Operating Systems. Server operating systems are strongly recommended.
• .NET Framework 2.0 or higher.
• 512 MB RAM.
• Enough free hard disk space. Hard disk space will vary depending on the size of project’s assets.

2.2    Client

Client machine requirements will vary depending on the Plastic SCM client in use. The GUI or IDE integrations will have higher requirements than the command line.

The supported operating systems are:

·         Windows 2000 Professional, Windows XP SP2, Windows Vista, Windows 7

·         Windows Server 2000 / 2003 / 2008

·         Fedora Core 8 or higher

·         Ubuntu 8.04 or higher

·         RedHat RHEL 5

·         OpenSuse 10.3 or higher, SLED 10 or higher

·         CentOS 5

·         Mac OS X 10.4 or higher

For windows, the .NET Framework 2.0 or higher is required. For Linux operating systems a mono package is distributed with the Plastic SCM installer.

The needed RAM will vary depending on:

• Command line client: is the smallest and needs few resources to work. Nevertheless, as a general rule, a 512 Mb RAM machine is strongly recommended.
• GUI client: 512 MB RAM
• Visual Studio Plug-in: same requirements as the IDE.
• Eclipse Plug-in: same requirements as the IDE.
• Other integrations: same requirements as the integrated package.

3     Plastic SCM installation

 

3.1    Prerequisites

The Plastic SCM server is installed as a Windows service or as a daemon in Linux / Mac. Administrative priviledges are required for this step to succeed during installation of the server component.

3.2    Server and Client installation

Plastic SCM is distributed as a single installation package. Once started, the installer will offer the option to choose which components to install, as well as specific setup options needed.

Table 1 describes the installation steps in details.

 

Table 1. Installation steps

3.3    Installing several server instances

You can have several installations of the Plastic SCM server on the machine at the same time, as long as every instance of the server is registered with a different name. To do this, execute the following from the command line:

Thus, you can install and run several instances of the server, each of them having a different name.

3.4    Server configuration

The server configuration wizard can be started at the last step of the installer, or from Plastic SCM start menu entry.

Table 2. Server configuration

3.5    User authentication configuration

Authentication methods tell Plastic SCM how to integrate users and groups of users with the objects of the repository. Plastic SCM can use five different connectors for retrieving its user information: 

• Local users of the machine (Only name)
• Local users of the machine (Name + ID)
• Integrated with Windows Active Directory
• LDAP
• Plastic SCM’s own User – Password database

Each of them allows different authentication possibilities and will be explained in the following sections.

3.5.1 Authentication basics

Client communicates certain security information to the server in order to be validated. The basic token sent from client to server is called SEID, the short name for SEcurity IDentifier.

The mechanisms to be described are basically based on different ways to build the SEID plus different ways to obtain users.

3.5.2 Local users

In Local users mode, the Plastic SCM server will read the local users names from the machine it is running on. So on startup it will create a list of known users, and recalculate it periodically.

For the system to work correctly the Plastic SCM clients must also be configured using the Local Users mechanism.

The client will take the name of its logged on user and send it to the server. This is the name that the server will use to first check whether it is a known user, and then make security calculations with.

This system heavily resides on correct network configuration. If a network is misconfigured it can have security flaws and it would be possible to cheat the server with identity hijacking.

It can be used on secured networks to easily configure a mixed Unix / Windows environment, relying, for instance on a NIS+ system.

It can also be used for easily configuring access from the Internet, provided that the server only allows trusted clients to connect.

3.5.3 Local users: name + ID

The mechanism is identical to local users but the SEID is built using both the user name plus the user ID.

It is a very simple way to prevent, or at least complicate a bit further, identity hijacking.

Under Windows systems the ID will be the SID of the user.

Under Unix based systems it will be the user id.

It works perfectly on non-cross-platform environments (Unix-Unix or Windows-Windows) but it will obviously break under Windows-Unix platforms unless a specific authentication mechanism is in place.

It can be used to work under NIS+ systems on Unix, or under any other configuration provided that both systems share the same user name and ID.

 

3.5.4 Active Directory Integrated Security

Using this configuration mechanism user list will be retrieved from the current Active Directory server. This system needs the server to be running inside an operating system that can be part of an Active Directory. It is designed to be run on Windows based operating systems.

3.5.5 LDAP

The LDAP security configuration mechanism allows interoperability with an LDAP environment.

It can be used to authenticate users against any kind of LDAP server. A Sun One or iPlanet LDAP Server can be used, for instance, to authenticate Plastic SCM users.

This is also a good method for Windows / Unix mixed environments, since Plastic SCM can connect to an Active Directory server using the LDAP mechanism, for instance when connecting from a unix box where the integrated Active Directory mode is not available.

3.5.6 User/Password

The user/password authentication system introduces an easier way to configure Plastic in a user – group based authentication in certain environments. When LDAP, Active Directory and local server authentication mode are not available options, the system administrator can select user/password authentication.

When using UP mode (meaning user/password authentication mode) the Plastic SCM security system works exactly as it would do with LDAP, Active Directory or any other mode, the difference being that the Plastic SCM server itself will store the user and group information.

When working in UP mode the administrator will define users, groups and their relationships using a specific Plastic configuration tool, then the client will just have to specify the previously configured user and password to log in the Plastic server.

UP authentication mode is appropriate for mixed Linux/Windows environments where LDAP or Active Directory integration is not an option, or to manage access to the Plastic SCM server on heterogeneous environments where there is no common user login among operating systems.

To configure the login and password the user needs to run the Plastic SCM configuration wizard as shown on the following Figure 16.

Figure 16. User and password configuration screen

 

When the Plastic SCM GUI client starts up, a login screen will pop up if the user or password doesn’t match.

Figure 17. Login dialog

The main difference between UP and the other authentication methods is that instead of relying on an external user and group provider, the UP authentication mode stores all its data into two files: users.conf and groups.conf.

• users.conf: stores information about all the users and their encrypted passwords.
• groups.conf: stores all the available groups and the users they contain.

Figure 18. Involved configuration files in UP mode

Configuring user/password authentication mode

In order to configure the UP mode you’ll use the following tools:

• The server’s configuration tools (configureserver or clconfigureserver) to set the authentication mode the server has to use.
• The client’s configuration tools (plastic --configure or the configuration wizard) to specify the authentication mode to communicate with the server.
• umtoolgui or umtool to configure the users, groups, and their relationships both graphically and from the command line.

 

Selecting the UP authentication mode

To select the UP authentication mode both the clients and the server must be configured accordingly, meaning running in the same mode.

Plastic users can run both the server configuration wizard (configureserver executable) and the client configuration (plastic --configure) to set the UP authentication mode as described on Figure 19.below:

Figure 19 umtoolgui

 

Umtoolgui is the GUI tool to configure the users, groups and their relationships and passwords. The tool is located on the server’s installation directory.

Figure 19 umtoolgui illustrates all the umtoolgui options. It is a simple and intuitive tool whose solely purpose is to help users configure the users.conf and groups.conf files.

The tool is able to create users and groups, assign users to a specific group, change a user’s password, and rename or delete users and groups.

Figure 20 umtoolgui usage

Umtool is the command line tool used to configure the users, groups and their relationships and passwords from the operating system’s console.

umtool implements several commands detailed on the followingTable 3 umtool commands.

Table 3 umtool commands

users.conf file format

The users.conf file contains the definition of the users known to the system in UP authentication mode. The format of the users.conf file is very simple: it contains a list of the available users followed by their passwords as shown on the figure below.

Figure 21. users.conf file format

 

groups.conf file format

The groups.conf file contains all the groups known to the Plastic system in UP mode. The file is a list of the groups, each one followed by the names of the users or groups it contains. Check the following figure for details.

Figure 22. groups.conf file format

 

Setting server’s UP working mode modifying server.conf

After the server’s working mode is set, it will be stored on the configuration file named server.conf.

The server.conf file can be manually modified to choose a different authentication mode. To set the UP working mode use the workingmode value specified in the figure below.

Figure 23. server.conf contains WorkingMode

User/Password mode common questions

 

This is the traditional authentication method; it allows Plastic SCM users to define their own users and groups on the Plastic server. This way Plastic works with an autonomous security mechanism, which could be the best option for many organizations which don't rely on systems like LDAP or Active Directory.

The server keeps a list of the users and each user defines his password. It also keeps groups as well as the relation between users and groups. Each client sets a user and a password in order to have access to the server, the user must exist on the server and the password must be the same one.

The list of users and groups is defined by two configuration files located in the server folder.

There are two tools used to manage users and groups, these tools can be found on the server’s installation directory:

umtool (command line tool)

umtoolgui (Graphic User Interface tool)

3.6    Server startup

Plastic SCM server starts automatically on server boot and after the installation process is finished, but it can be stopped, started, or restarted manually.

3.6.1 Windows Systems

In order to manage Plastic SCM start, stop or restart from Windows Systems, you can open the Windows Service Manager. Open Control Panelà Administrative Toolsà and Services. There you will find Plastic SCM service in the list. SeeFigure 24. Managing Plastic SCM server service.

Alternatively you can go to STARTàRUN and type: services.msc to open the windows services window.

Figure 24. Managing Plastic SCM server service

3.6.2 Linux Systems

To manage Plastic SCM start, stop or restart from Linux Systems, you can use plasticsd script. This script is located in the server installation directory (/opt/PlasticSCM/server by default). On RedHat based systems you can use the system call service plasticsd <options>. This script has the following options:

Once the Plastic SCM server is started, a default repository will be created, to ease the initial system usage.

To check whether the server is up and running, simplest way:

PID xxxx is the running process ID of the server.

Another way to check the server status is by looking at the repository list. Follow the next steps:

Open a command line window (cmd.exe) and type:

It will list all the repositories on server servername:port.

3.7    Client configuration

Each time a new client is installed on a developer machine, it must be configured to enable it to connect to a Plastic SCM server. This can be easily done using the client configuration wizard. The steps in the wizard are explained below.

Table 4. Client configuration steps

 

The client is now ready to be used and can be started from the startup menu or by typing plastic in a command line interface window.

 

3.7.1 Merge and Differences Tools configuration

This section describes how to configure the Plastic SCM client to use a specific merge or diff tool for specific types of files. Note that Plastic SCM includes its own 3-way merge and diff tool, so this step is not required in the default setup.

The configuration of the merge and differences tools are defined in the client.conf file. It allows specifying what tools have to be used for different types of files through a set of rules.

A rule contains information regarding the type of file (binary or text) and optionally the file extension to which this rule applies.

The default rules for the merge tool are listed here:

• FileType: Indicates the types of files the rule will applies to, they can be TextFile, for files identified as text by Plastic SCM or BinaryFile for files identified as binary by Plastic SCM.
• FileExtensions: Indicates file  extensions or types of files on which the rule is applied, if we have more than one extension for the same rule they would be separated by “;". If the rule is used for every extension "*" would be used.
• Tools: Different merge tools to be used on a specific file, if there is more than one tool, they are executed in order until one of them gives a result; only the first tool is used in the case of the differences. These tools must have every mandatory parameter using the variables given, which are replaced by the system value during execution. If we want the system to use a specific value for a rule instead of a variable, that value would be set. The given variables are the following ones:
• @basefile: path containing the merge common ancestor.
• @basesymbolic: name shown on the tool to refer to the base file, it is usually the spec revision or the disc file if loaded.
• @basehash: common ancestor content hash.
• @sourcefile: path containing the merge source file.
• @sourcesymbolic: name shown on the tool to refer to the merge source file, it is usually the spec revision or the disc file if loaded.
• @sourcehash: merge source content hash.
• @destinationfile: path containing the merge destination file, the location of the element in the workspace.
• @destinationhash: merge destination content hash.
• @output: file containing the merge result.
• @filetype: type of file used for the syntax highlight
• @comparationmethod: comparison method used.
• @fileencoding: file encoding. 
• @mergetype: type of merge used.

It must be highlighted that rules are executed in order, so the less restrictive ones must be the last ones to be executed on this type of files.

An example below shows using an additional rule for a single type of file considered as binary (.scs) if we want it to be considered as text and given fixed parameters: type of merge to be automatic only if one of the contributors has submitted changes and file codification as Unicode:

In the case of the differences tools, rules are built similarly but there are fewer variables. In order to add a rule to calculate differences on a binary file (.scs) as a text file with Unicode format, we would write the following:

4              Using a proxy server

Plastic supports the idea of having a Proxy server in order to load-balance the traffic between the two machines: the server machine and the proxy machine. This proxy can be installed with minimum operating resources. No database backend will be required in order to run, which makes it easy to set up. It is configurable as a daemon, Windows service or manually started from the command line.

Only read-only data will be cached. It means only checked-in revision data will be cached on the proxies, checked out data (shelved) will be ignored.

The Proxy server will start caching files from the repository server requested by clients. Once cached, revision data will stay on the proxy. Furthermore, it will handle concurrent requests of the same revision (identified by server, repository and id), performing a single network request to the remote server.

The proxy server will also cache the most used data in memory for additional performance. The maximum memory reservation for the cache is configurable.

With a proxy, you obtain the following benefits:

• The server will act as a data cache. No other data or metadata besides revision information will be stored.
• All cached data will be stored under a single disk location (directory tree) for maximum simplicity. Disk location is configurable.
• Data transmission between the proxy server, repository server and client will use the same data exchange protocol used by Plastic SCM, exchanging data chunks of 4Mb max size.

The following is an example of a configuration using a proxy server:

Figure 30. Example of proxy deployment

The basic usage scenario is depicted on the following set of figures. The typical scenario for proxy server is a centralized setup over a slow network which needs to be optimized.

Figure 31. Example of network

Each site can take advantage of a very simple proxy server which will increase the overall system performance by reducing network traffic over the distant networks.

Figure 32. Same network, improved by using two proxies

 

To configure a proxy server, you have to install the plasticcached.exe program provided in the PlasticSCM server folder as a service in Windows or as a daemon in Linux, and configure a plasticcached.conf file with the following information:

In CachePath, you must specify the directory where the data will be cached.

On the client, the users have to add the following line in their client.conf file:

5     Creating and managing
repositories

Repositories are the central data storage in the Plastic SCM system. They store the information for all the objects in the system.

5.1    Creating a new repository

An empty repository named default is created on the first server start up if no other repository exists yet. More repositories can be created using this command:

Where:

• PlasticServer is the hostname or IP address of the Plastic SCM server.
• 8084 is the TCP port where the server is listening.
• NewRepository is the name of the new repository to be created.

It is also possible to create a repository using the GUI tool. Figure 33 shows the repository creation dialog on the GUI.

Figure 33. Creating a new repository

Where:

• Name: The name for the new repository
• Server: The combination server:port of the Plastic SCM server.

5.2    Listing available repositories

Listing available repositories can be done in two different ways: from the command line and using the GUI client.

Let’s first have a look at how to list repositories from the command line:

Will show the following output (three repositories created):

Figure 34 shows the repositories view on the GUI tool, accessible from the View menu.

Figure 34. Repositories view

5.3    Archiving repositories

Repositories that are no longer used can be disconnected from the server and archived on offline storage like DVD or tapes, leaving free space for active repositories. These repositories can be later reconnected if they need to be used, following the procedures described here.

In order to archive a repository, the removerepository command is used, providing a repository specification. Before removing a repository, you should ensure that no workspace is using it. In any case, Plastic SCM will complain if this condition is detected, and will list the workspaces using the repository which is being removed.

First, list all repositories:

Get the number in the first column for your repository “the repository index”. In the sample above, we want to archive repository 3 (myproject). This number will be used later to identify the file to backup.

Next is removing the repository:

This command has two internal effects, important to note for later reconnection.

a)    It removes the repository from the list of registered repositories available to be used in workspaces.

b)    It removes the repository from the list of available repositories.

As noted before, while performing this operation, you may get an error indicating that some workspaces are using this repository:

To correct this, ensure that the workspaces are removed or point to a different repository.

The repository database files reside in the server installation folder and follow the following naming convention:

The file for myproject repository, in the sample, will be

This is the only file you need to archive on DVD or the media of your choice.

5.4    Reconnecting archived repositories

To reconnect an archived repository, first get a list of current repositories (this might be different from the list of reps found when it was archived)

In the sample above, several repositories have appeared/created since we archived myproject, which had number 3. Choose a free repository number not used in the list (next one is 8, but you can choose any other). Rename your rep_3.plastic.fdb to rep_8.plastic.fdb:

And now for reconnecting: first add the repository to the list of available repositories:

The first argument is the database name, without the .plastic.fdb extension.

The second argument is the name of the repository. This must be unique in the list of available repositories.

The last argument is the repository server IP:TCP PORT where the repository will be connected.

Next step is to register it in the list of repositories available to workspaces:

It is now ready to be used by the clients. You might need to close and reopen graphical clients so that they can use the reconnected repository.

5.5    Using several repository servers

It is possible to register several repository servers in a client; this way the users will be able to use them in their configurations.

In order to configure a workspace to use several repository servers, the users will need to register those repositories they want to use. To do this, a file named plastic.servers needs to be created in the plastic folder of the user local folder (that is, /home/<user>/.plastic directory in Linux or C:\Documents and Settings\<user>\Local Settings\Application Data\plastic in Windows XP or C:\Users\<user>\AppData\Local\plastic in Vista/Win7). The following is an example of the contents that this file may contain:

This way, the users will be able to use those repositories in their workspaces.

6     Creating and managing workspaces

Workspaces define the way users have to work on the items stored in the repositories. To be able to check out files and directories and work on them, a local workspace is needed.

A workspace actually maps a given repository status onto a certain location on the user’s local drive.

In Plastic, the workspaces are stored locally in the client machine, in a hidden folder named .plastic, placed in the root of the workspace. This folder contains the following files:

• plastic.selector, which stores the current selector content.
• plastic.workspace, which includes the name of the workspace and its GUID (Global Unique Idenifier).
• plastic.wktree, a binary file which states the revisions that must be loaded in the workspace.

Furthermore, in the local user folder (in Windows XP: Documents and Settings\<user>\Local Settings \Application Data\plastic) a plastic.workspaces file is stored, which contains information related with the workspaces handled by the Plastic client. Its content is something like this:

6.1    Creating a new workspace

To start working with Plastic SCM, a user needs a workspace. The workspace is both the place on the local disk to store the downloaded files and directories from the server, and an associated configuration and versioning information.

A workspace can be created from the command line typing:

myworkspace is the name of the newly created workspace, and c:\workspace its location.

It is also possible to create a repository using the GUI tool. Figure 35 shows the repository creation dialog on the GUI.

Figure 35. Creating a new repository

6.2    Listing available workspaces

The GUI tool can list all the available workspaces from the workspaces View.

From the view shown on Figure 36 new workspaces can also be created.

Figure 36. Workspaces view

Workspace listing can also be achieved from the command line tool typing:

Displaying the following output:

6.3    Removing a workspace

Workspaces are controlled by the server and contain information to know the exact revisions loaded on the client machines. This way no extra information is stored on local directories, just data. This is very helpful to avoid directory pollution.

Administrator or SCM manager can decide that certain workspaces shouldn’t be used anymore. In that sense he will remove them, meaning the server will not know about them anymore.

When a workspace is removed, its data is deleted from the server, but nothing is removed on the user’s local disk.

Workspace removal can be achieved from the workspaces View on the GUI tool, or it can be performed from the command line typing:

6.4    Moving a workspace

A workspace can also be moved, meaning its current configuration can be downloaded into any other location. This can be useful dealing with users moving from one workstation to another.

Workspace moving is a very specific operation that currently can only be  triggered from the command line.

7     Repository data location

By default, Plastic SCM databases are stored on the server installation folder. However, this might not be the best place for them so this setting can be changed following the procedure described here:

• Stop Plastic SCM service.
• In the server installation folder (usually c:\program files\plasticscm\server on Windows platform), create a file called db.conf, with this content:

• Specify the new storage folder inside the DatabasePath tag of this file and save.
• Move any file with .fdb extension in the server install folder to the folder you specified so that your existing data is used in the new location.
• Start the plastic server.

8     Backup and restore

The backup and restore procedures are closely related to the database backend used in Plastic SCM. Default installation of the server uses an embedded Firebird database engine and the following instructions are ment for that configuration. If you configured a different database backend, please check the guide for that backend for specific backup instructions.

8.1    Backup

Plastic SCM requires the administrator to stop the running server in order to perform the backup. Taking this into account, backup is very simple, and can be easily automated with a shell script if needed:

• Stop Plastic server
• Copy *.fdb files in your repository data location (by default, server installation folder, or the path in the DatabasePath tag of the db.conf file if it has been configured)
• Start Plastic server again.

Note that, while it is safe to perform an online backup if no operation is being performed by clients, (not requiring to stop the server) currently there is no way to check this condition, so the recommended procedure is stopping the server.

 

8.2    Restore

Restore procedure is very similar to backup:

• Stop Plastic server
• Copy *.fdb files from the backup to the repository data location. To keep consistency, it is important to copy all files.
• Start Plastic server again.

 

9     Archiving revisions

9.1    Why archiving revisions

In a production environment where there are third party compiled tools or programs, binaries, big documents and other kind of big files that rarely change and / or are rarely accessed, it can consume disk space and time when storing those revisions in the database and afterwards retrieving them from the database.

To help minimize the impact mentionwed above, you can use the archive command, which allows the administrator to set up a separate disk device, such as a tape, a USB pen drive, an external disk, a CD-ROM, DVD, or a specific disk space area, and store those big revisions there, so that they do not take space in the database. Thus, everytime that a user needs to access those revisions, Plastic SCM will search for them in the external storage area, and retrieve that information to the user.

9.2    How to archive my revisions

To archive revisions, use the archive command:

This command will archive the revision 0 of the branch main of the item mybigfile.tar, creating several chunks of the revision; each one contains a part of the revision content. The comment of the archive is “big file of libraries” and the archive files will start with the prefix “/home/plastic/bigfileTARrev0”. This means that the archive will be created in that path. The –f parameter is a prefix for the archive files that can be used as a destination path for the archives. If the –f switch is omitted the archive files will be created in the directory of execution of the command.

It is possible to archive several revisions specifying them one after the other in the same command. To get further information about this command, type on a command line:

Once the archive files have been created the administrator can move them to the external data location. The next time that a user tries to access that data, Plastic SCM will try to get it from the external storage area.

 

9.3    How are the archived revisions accessed

To access the data stored on an external location, a configuration file externaldata.conf file must be manually created. This file contains a path per line; those paths are the locations of the stored revisions. The following is a sample of an externaldata.conf file:

This file can be placed in two locations:

·         On the server side: placing the externaldata.conf file on the Plastic SCM server location will allow every user of that server to access those revisions automatically, as long as the external storage area is available. This is the most useful option for system administrators.

·         On the client side: placing the externaldata.conf file on the Plastic SCM client folder or on the user local directory (within Documents and Settings in Windows XP, Users in Vista/Seven, or home in UNIX based systems).

If a user tries to access to any stored revision from the GUI by executing an update, for example, and there is no externaldata.conf, a dialog will appear, asking for the location of the data as illustrated in the following picture:

Figure 37. Introduce the external data location path

Once the first chunk of the revision is introduced, Plastic SCM will be able to find the other chunks of the revision, it will create an externaldata.conf file in the local user directory and from that moment on it will try to access to the archived revisions from that location. If Plastic SCM cannot access the data at a certain point of time, it will show the same dialog again, and if a new location is introduced, this location will be added to the existing externaldata.conf file.

From the CLI (command line interface) an externaldata.conf must be always available. Otherwise, the command will ask the user for an externaldata.conf to look for the revisions.

9.4    How to restore archived revisions

It is possible to save archived revisions back into the database, so that the archives can be safely deleted. From that moment on the database will be used to get the data. Example:

This command will restore the revision 0 of the main branch of the file mybigfile.tar into the database, and the archives of that revision will not be used longer.

The external storage location must be available at the moment of the revision restoration, and an externaldata.conf must be available.

To get more information of this command, type on a command line: